Automatic pull of documentation from Wiki.

svn path=/trunk/; revision=5367

5 files changed, 416 insertions, 0 deletions

diff --git a/doc/doc.RPKI.CA.Configuration.DifferentServer b/doc/doc.RPKI.CA.Configuration.DifferentServer
new file mode 100644
index 00000000..3aaeeb25
--- /dev/null
+++ b/doc/doc.RPKI.CA.Configuration.DifferentServer
@@ -0,0 +1,64 @@
+****** Running rpkid or pubd on a different server ******
+
+The default configuration runs rpkid, pubd (if enabled) and the back end code
+all on the same server. For many purposes, this is fine, but in some cases you
+might want to split these functions up among different servers.
+
+As noted briefly above, there are two separate sets of rpki.conf options which
+control the necessary behavior: the run_* options and the start_* options. The
+latter are usually tied to the former, but you can set them separately, and
+they control slightly different things: the run_* options control whether the
+back end code attempts to manage the servers in question, while the start_*
+flags control whether the startup scripts should start the servers in question.
+
+Here's a guideline to how to set up the servers on different machines. For
+purposes of this description we'll assume that you're running both rpkid and
+pubd, and that you want rpkid and pubd each on their own server, separate from
+the back end code. We'll call these servers rpkid.example.org,
+pubd.example.org, and backend.example.org.
+
+Most of the configuration is the same as in the normal case, but there are a
+few extra steps. The following supplements but does not replace the normal
+instructions.
+
+WARNING: These setup directions have not (yet) been tested extensively.
+
+* Create rpki.conf as usual on backend.example.org, but pay particular
+  attention to the settings of rpkid_server_host, irbe_server_host, and
+  pubd_server_host: these should name rpkid.example.org, backend.example.org,
+  and pubd.example.org, respectively.
+
+* This example assumes that you're running pubd, so make sure that both
+  run_rpkid and run_pubd are enabled in rpki.conf.
+
+* Copy the rpki.conf to the other machines, and customize each copy to that
+  machine's role:
+
+  o start_rpkid should be enabled on rpkid.example.org and disabled on the
+    others.
+  o start_pubd should be enabled on pubd.example.org and disabled on the
+    others.
+  o start_irdbd should be enabled on backend.example.org and disabled on the
+    others.
+
+* Make sure that you set up SQL databases on all three servers; the rpki-sql-
+  setup script should do the right thing in each case based on the setting of
+  the start_* options.
+
+* Run "rpkic initialize" on the back end host. This will create the BPKI and
+  write out all of the necessary keys and certificates.
+
+* "rpkic initialize" should have created the BPKI files (.cer, .key, and .crl
+  files for the several servers). Copy the .cer and .crl files to the pubd and
+  rpkid hosts, along with the appropriate private key: rpkid.example.org should
+  get a copy of the rpkid.key file but not the pubd.key file, while
+  pubd.example.org should get a copy of the pubd.key file but not the rpkid.key
+  file.
+
+* Run rpki-start-servers on each of the three hosts when it's time to start the
+  servers.
+
+* Do the usual setup dance, but keep in mind that the the back end controlling
+  all of these servers lives on backend.example.org, so that's where you issue
+  the rpkic or GUI commands to manage them. rpkic and the GUI both know how to
+  talk to rpkid and pubd over the network, so managing them remotely is fine.
diff --git a/doc/doc.RPKI.CA.Configuration.autoconf b/doc/doc.RPKI.CA.Configuration.autoconf
new file mode 100644
index 00000000..30de5780
--- /dev/null
+++ b/doc/doc.RPKI.CA.Configuration.autoconf
@@ -0,0 +1,29 @@
+****** [autoconf] section ******
+
+rpki-confgen --autoconf records the current autoconf settings here, so that
+other options can refer to them. The section name "autoconf" is magic, don't
+change it.
+
+***** bindir *****
+
+Usually /usr/bin or /usr/local/bin.
+
+No default value.
+
+***** datarootdir *****
+
+Usually /usr/share or /usr/local/share.
+
+No default value.
+
+***** sbindir *****
+
+Usually /usr/sbin or /usr/local/sbin.
+
+No default value.
+
+***** sysconfdir *****
+
+Usually /etc or /usr/local/etc.
+
+No default value.
diff --git a/doc/doc.RPKI.CA.Configuration.myrpki b/doc/doc.RPKI.CA.Configuration.myrpki
new file mode 100644
index 00000000..92776cc8
--- /dev/null
+++ b/doc/doc.RPKI.CA.Configuration.myrpki
@@ -0,0 +1,295 @@
+****** [myrpki] section ******
+
+The "[myrpki]" section contains all the parameters that you really need to
+configure. The name "myrpki" is historical and may change in the future.
+
+***** handle *****
+
+Every resource-holding or server-operating entity needs a "handle", which is
+just an identifier by which the entity calls itself. Handles do not need to be
+globally unique, but should be chosen with an eye towards debugging operational
+problems: it's best if you use a handle that your parents and children will
+recognize as being you.
+
+The "handle" option in the "[myrpki]" section specifies the default handle for
+this installation. Previous versions of the CA tools required a separate
+configuration file, each with its own handle setting, for each hosted entity.
+The current code allows the current handle to be selected at runtime in both
+the GUI and command line user interface tools, so the handle setting here is
+just the default when you don't set one explictly. In the long run, this option
+may go away entirely, but for now you need to set this.
+
+Syntax is an identifier (ASCII letters, digits, hyphen, underscore -- no
+whitespace, non-ASCII characters, or other punctuation).
+
+No default value.
+
+***** bpki_servers_directory *****
+
+Directory for BPKI files generated by rpkic and used by rpkid and pubd. You
+will not normally need to change this.
+
+  bpki_servers_directory = ${autoconf::datarootdir}/rpki
+
+***** run_rpkid *****
+
+Whether you want to run your own copy of rpkid (and irdbd). Leave this alone
+unless you're doing something unusual like running a pubd-only installation.
+
+  run_rpkid = yes
+
+***** rpkid_server_host *****
+
+DNS hostname for rpkid. In most cases, this must resolve to a publicly-
+reachable address to be useful, as your RPKI children will need to contact your
+rpkid at this address.
+
+No default value.
+
+***** rpkid_server_port *****
+
+Server port number for rpkid. This can be any legal TCP port number that you're
+not using for something else.
+
+  rpkid_server_port = 4404
+
+***** irdbd_server_host *****
+
+DNS hostname for irdbd, or "localhost". This should be "localhost" unless you
+really know what you are doing.
+
+  irdbd_server_host = localhost
+
+***** irdbd_server_port *****
+
+Server port number for irdbd. This can be any legal TCP port number that you're
+not using for something else.
+
+  irdbd_server_port = 4403
+
+***** run_pubd *****
+
+Whether you want to run your own copy of pubd. In general, it's best to use
+your parent's pubd if your parent allows you to do so, because this will reduce
+the overall number of publication sites from which relying parties will need to
+retrieve data. However, not all parents offer publication service, or you may
+need to run pubd yourself for reliability reasons, or because you're certifying
+private address space or private Autonomous System Numbers.
+
+The out of band setup protocol will attempt to negotiate publication service
+for you with whatever publication service your parent is using, if it can and
+if you let it.
+
+  run_pubd = yes
+
+***** pubd_server_host *****
+
+DNS hostname for pubd, if you're running it. This must resolve to a publicly
+reachable address to be useful.
+
+No default value.
+
+***** pubd_server_port *****
+
+Server port number for pubd. This can be any legal TCP port number that you're
+not using for something else.
+
+  pubd_server_port = 4402
+
+***** pubd_contact_info *****
+
+Contact information to include in offers of repository service. This only
+matters when you're running pubd. This should be a human readable string,
+perhaps containing an email address or URL.
+
+No default value.
+
+***** run_rootd *****
+
+Whether you want to run your very own copy of rootd. Don't enable this unless
+you really know what you're doing.
+
+  run_rootd = no
+
+***** rootd_server_host *****
+
+DNS hostname for rootd, if you're running it. This should be localhost unless
+you really know what you are doing.
+
+  rootd_server_host = localhost
+
+***** rootd_server_port *****
+
+Server port number for rootd, if you're running it. This can be any legal TCP
+port number that you're not using for something else.
+
+  rootd_server_port = 4401
+
+***** publication_base_directory *****
+
+Root of local directory tree where pubd should write out published data. You
+need to configure this, and the configuration should match up with the
+directory where you point rsyncd. Neither pubd nor rsyncd much cares where you
+tell it to put this stuff, the important thing is that the rsync URIs in
+generated certificates match up with the published objects so that relying
+parties can find and verify rpkid's published outputs.
+
+  publication_base_directory = ${autoconf::datarootdir}/rpki/publication
+
+***** publication_root_cert_directory *****
+
+Root of local directory tree where rootd (sigh) should write out published
+data. This is just like publication_base_directory, but rootd is too dumb to
+use pubd and needs its own directory in which to write one certificate, one
+CRL, and one manifest. Neither rootd nor rsyncd much cares where you tell them
+to put this stuff, the important thing is that the rsync URIs in generated
+certificates match up with the published objects so that relying parties can
+find and verify rootd's published outputs.
+
+  publication_root_cert_directory = ${myrpki::publication_base_directory}.root
+
+***** publication_rsync_module *****
+
+rsyncd module name corresponding to publication_base_directory. This has to
+match the module you configured into rsyncd.conf. Leave this alone unless you
+have some need to change it.
+
+  publication_rsync_module = rpki
+
+***** publication_root_module *****
+
+rsyncd module name corresponding to publication_root_cert_directory. This has
+to match the module you configured into rsyncd.conf. Leave this alone unless
+you have some need to change it.
+
+  publication_root_module = root
+
+***** publication_rsync_server *****
+
+Hostname and optional port number for rsync URIs. In most cases this should
+just be the same value as pubd_server_host.
+
+  publication_rsync_server = ${myrpki::pubd_server_host}
+
+***** start_rpkid *****
+
+rpkid startup control. This should usually have the same value as run_rpkid:
+the only case where you would want to change this is when you are running the
+back-end code on a different machine from one or more of the daemons, in which
+case you need finer control over which daemons to start on which machines. In
+such cases, run_rpkid controls whether the back-end code is doing things to
+manage rpkid, while start_rpkid controls whether rpki-start-servers attempts to
+start rpkid on this machine.
+
+  start_rpkid = ${myrpki::run_rpkid}
+
+***** start_irdbd *****
+
+irdbd startup control. This should usually have the same value as run_rpkid:
+the only case where you would want to change this is when you are running the
+back-end code on a different machine from one or more of the daemons, in which
+case you need finer control over which daemons to start on which machines. In
+such cases, run_rpkid controls whether the back-end code is doing things to
+manage rpkid, while start_irdbd controls whether rpki-start-servers attempts to
+start irdbd on this machine.
+
+  start_irdbd = ${myrpki::run_rpkid}
+
+***** start_pubd *****
+
+pubd startup control. This should usually have the same value as run_pubd: the
+only case where you would want to change this is when you are running the back-
+end code on a different machine from one or more of the daemons, in which case
+you need finer control over which daemons to start on which machines. In such
+cases, run_pubd controls whether the back-end code is doing things to manage
+pubd, while start_pubd controls whether rpki-start-servers attempts to start
+pubd on this machine.
+
+  start_pubd = ${myrpki::run_pubd}
+
+***** start_rootd *****
+
+rootd startup control. This should usually have the same value as run_rootd:
+the only case where you would want to change this is when you are running the
+back-end code on a different machine from one or more of the daemons, in which
+case you need finer control over which daemons to start on which machines. In
+such cases, run_rootd controls whether the back-end code is doing things to
+manage rootd, while start_rootd controls whether rpki-start-servers attempts to
+start rootd on this machine.
+
+  start_rootd = ${myrpki::run_rootd}
+
+***** shared_sql_username *****
+
+If you're comfortable with having all of the databases use the same MySQL
+username, set that value here. The default setting of this variable should be
+fine.
+
+  shared_sql_username = rpki
+
+***** shared_sql_password *****
+
+If you're comfortable with having all of the databases use the same MySQL
+password, set that value here. You should use a locally generated password
+either here or in the individual settings below. The installation process
+generates a random value for this option, which satisfies this requirement, so
+ordinarily you should have no need to change this option.
+
+No default value.
+
+***** rpkid_sql_database *****
+
+SQL database name for rpkid's database. The default setting of this variable
+should be fine.
+
+  rpkid_sql_database = rpkid
+
+***** rpkid_sql_username *****
+
+If you want to use a separate SQL username for rpkid's database, set it here.
+
+  rpkid_sql_username = ${myrpki::shared_sql_username}
+
+***** rpkid_sql_password *****
+
+If you want to use a separate SQL password for rpkid's database, set it here.
+
+  rpkid_sql_password = ${myrpki::shared_sql_password}
+
+***** irdbd_sql_database *****
+
+SQL database for irdbd's database. The default setting of this variable should
+be fine.
+
+  irdbd_sql_database = irdbd
+
+***** irdbd_sql_username *****
+
+If you want to use a separate SQL username for irdbd's database, set it here.
+
+  irdbd_sql_username = ${myrpki::shared_sql_username}
+
+***** irdbd_sql_password *****
+
+If you want to use a separate SQL password for irdbd's database, set it here.
+
+  irdbd_sql_password = ${myrpki::shared_sql_password}
+
+***** pubd_sql_database *****
+
+SQL database name for pubd's database. The default setting of this variable
+should be fine.
+
+  pubd_sql_database = pubd
+
+***** pubd_sql_username *****
+
+If you want to use a separate SQL username for pubd's database, set it here.
+
+  pubd_sql_username = ${myrpki::shared_sql_username}
+
+***** pubd_sql_password *****
+
+If you want to use a separate SQL password for pubd's database, set it here.
+
+  pubd_sql_password = ${myrpki::shared_sql_password}
diff --git a/doc/doc.RPKI.CA.Configuration.web_portal b/doc/doc.RPKI.CA.Configuration.web_portal
new file mode 100644
index 00000000..f24b0a8b
--- /dev/null
+++ b/doc/doc.RPKI.CA.Configuration.web_portal
@@ -0,0 +1,28 @@
+****** [web_portal] section ******
+
+Glue to allow the Django application to pull user configuration from this file
+rather than directly editing settings.py.
+
+***** sql-database *****
+
+SQL database name the web portal should use.
+
+  sql-database = ${myrpki::irdbd_sql_database}
+
+***** sql-username *****
+
+SQL user name the web portal should use.
+
+  sql-username = ${myrpki::irdbd_sql_username}
+
+***** sql-password *****
+
+SQL password the web portal should use.
+
+  sql-password = ${myrpki::irdbd_sql_password}
+
+***** secret-key *****
+
+Site-specific secret key for Django.
+
+No default value.
diff --git a/doc/manual.pdf b/doc/manual.pdf
index 8fe8789d..e60f2e3b 100644
--- a/doc/manual.pdf
+++ b/doc/manual.pdf