Automatic pull of documentation from Wiki.

svn path=/trunk/; revision=5354

5 files changed, 231 insertions, 195 deletions

diff --git a/doc/doc.RPKI.CA.Configuration.irdbd b/doc/doc.RPKI.CA.Configuration.irdbd
index ccaaefe0..68374469 100644
--- a/doc/doc.RPKI.CA.Configuration.irdbd
+++ b/doc/doc.RPKI.CA.Configuration.irdbd
@@ -1,39 +1,45 @@
-****** irdbd.conf ******
-
 irdbd's default configuration file is the system rpki.conf file. Start irdbd
-with "-c filename" to choose a different configuration file. All options are in
-the section "[irdbd]".
+with -c filename to choose a different configuration file. All options are in
+the section [irdbd].
 
 Since irdbd is part of the back-end system, it has direct access to the back-
 end's SQL database, and thus is able to pull its own BPKI configuration
 directly from the database, and thus needs a bit less configuration than the
 other daemons.
 
-Options:
+sql-database::
 
-startup-message::
+     MySQL database name for irdbd.
 
-     String to log on startup, useful when debugging a collection of irdbd
-     instances at once.
+     Default: ${myrpki::irdbd_sql_database}
 
 sql-username::
 
-     Username to hand to MySQL when connecting to irdbd's database.
-
-sql-database::
+     MySQL user name for irdbd.
 
-     MySQL's database name for irdbd's database.
+     Default: ${myrpki::irdbd_sql_username}
 
 sql-password::
 
-     Password to hand to MySQL when connecting to irdbd's database.
+     MySQL password for irdbd.
+
+     Default: ${myrpki::irdbd_sql_password}
 
 server-host::
 
-     Hostname or IP address on which to listen for HTTP connections.
-     Default is the wildcard address (IPv4 0.0.0.0, IPv6 ::), which should
-     work in most cases.
+     Host on which irdbd should listen for HTTP service requests.
+
+     Default: ${myrpki::irdbd_server_host}
 
 server-port::
 
-     TCP port on which to listen for HTTP connections.
+     Port on which irdbd should listen for HTTP service requests.
+
+     Default: ${myrpki::irdbd_server_port}
+
+startup-message::
+
+     String to log on startup, useful when debugging a collection of irdbd
+     instances at once.
+
+     No default value.
diff --git a/doc/doc.RPKI.CA.Configuration.pubd b/doc/doc.RPKI.CA.Configuration.pubd
index a3f2f007..404bbfaa 100644
--- a/doc/doc.RPKI.CA.Configuration.pubd
+++ b/doc/doc.RPKI.CA.Configuration.pubd
@@ -1,52 +1,76 @@
-****** pubd.conf ******
-
 pubd's default configuration file is the system rpki.conf file. Start pubd with
-"-c filename" to choose a different configuration file. All options are in the
-section "[pubd]". Certificates and keys may be either DER or PEM format.
+-c filename to choose a different configuration file. All options are in the
+section [pubd]. BPKI certificates and keys may be either DER or PEM format.
 
-Options:
+sql-database::
 
-sql-username::
+     MySQL database name for pubd.
 
-     Username to hand to MySQL when connecting to pubd's database.
+     Default: ${myrpki::pubd_sql_database}
 
-sql-database::
+sql-username::
+
+     MySQL user name for pubd.
 
-     MySQL's database name for pubd's database.
+     Default: ${myrpki::pubd_sql_username}
 
 sql-password::
 
-     Password to hand to MySQL when connecting to pubd's database.
+     MySQL password for pubd.
 
-bpki-ta::
+     Default: ${myrpki::pubd_sql_password}
 
-     Name of file containing master BPKI trust anchor for pubd. All BPKI
-     validation in pubd traces back to this trust anchor.
+publication-base::
 
-irbe-cert::
+     Root of 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 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
+     rpkid's published outputs.
 
-     Name of file containing BPKI certificate used by IRBE (rpkic, GUI)
-     when talking to pubd.
+     Default: ${myrpki::publication_base_directory}
 
-pubd-cert::
+server-host::
 
-     Name of file containing BPKI certificate used by pubd.
+     Host on which pubd should listen for HTTP service requests.
 
-pubd-key::
+     Default: ${myrpki::pubd_server_host}
 
-     Name of file containing RSA key corresponding to pubd-cert.
+server-port::
 
-server-host::
+     Port on which pubd should listen for HTTP service requests.
 
-     Hostname or IP address on which to listen for HTTP connections.
-     Default is the wildcard address (IPv4 0.0.0.0, IPv6 ::), which should
-     work in most cases.
+     Default: ${myrpki::pubd_server_port}
 
-server-port::
+bpki-ta::
 
-     TCP port on which to listen for HTTP connections.
+     Where pubd should look for the BPKI trust anchor. All BPKI
+     certificate verification within pubd traces back to this trust
+     anchor. Don't change this unless you really know what you are doing.
 
-publication-base::
+     Default: ${myrpki::bpki_servers_directory}/ca.cer
+
+pubd-cert::
+
+     Where pubd should look for its own BPKI EE certificate. Don't change
+     this unless you really know what you are doing.
+
+     Default: ${myrpki::bpki_servers_directory}/pubd.cer
+
+pubd-key::
+
+     Where pubd should look for the private key corresponding to its own
+     BPKI EE certificate. Don't change this unless you really know what
+     you are doing.
+
+     Default: ${myrpki::bpki_servers_directory}/pubd.key
+
+irbe-cert::
+
+     Where pubd should look for the back-end control client's BPKI EE
+     certificate. Don't change this unless you really know what you are
+     doing.
 
-     Path to base of filesystem tree where pubd should store publishable
-     objects. Default is publication/.
+     Default: ${myrpki::bpki_servers_directory}/irbe.cer
diff --git a/doc/doc.RPKI.CA.Configuration.rootd b/doc/doc.RPKI.CA.Configuration.rootd
index f27bdd15..b4f98297 100644
--- a/doc/doc.RPKI.CA.Configuration.rootd
+++ b/doc/doc.RPKI.CA.Configuration.rootd
@@ -1,159 +1,145 @@
-****** rootd.conf ******
+You don't need to run rootd unless you're IANA, are certifying private address
+space, or are an RIR which refuses to accept IANA as the root of the public
+address hierarchy.
 
-***** Caveat *****
+Ok, if that wasn't enough to scare you off: rootd is a mess, and needs to be
+rewritten, or, better, merged into rpkid. It doesn't use the publication
+protocol, and it requires far too many configuration parameters.
 
-rootd is, to be blunt about it, a mess. rootd was originally intended to be a
-very simple program which simplified rpkid enormously by moving one specific
-task (acting as the root CA of an RPKI certificate hierarchy) out of rpkid. As
-the specifications and code (mostly the latter) have evolved, however, this
-task has become more complicated, and rootd would have to become much more
-complicated to keep up. In particular, rootd does not speak the publication
-protocol, and requires far too many configuration parameters to work correctly.
-rootd is still useful as a test tool, where its shortcomings are largely hidden
-by automated generation of its configuration. Don't run rootd unless you're
-sure that you need to do so.
+rootd was originally intended to be a very simple program which simplified
+rpkid enormously by moving one specific task (acting as the root CA of an RPKI
+certificate hierarchy) out of rpkid. As the specifications and code (mostly the
+latter) have evolved, however, this task has become more complicated, and rootd
+would have to become much more complicated to keep up.
 
-OK, with that out of the way....
+Don't run rootd unless you're sure that you need to do so.
 
-***** Configuration *****
+Still think you need to run rootd? OK, but remember, you have been warned....
 
 rootd's default configuration file is the system rpki.conf file. Start rootd
-with "-c filename" to choose a different configuration file. All options are in
-the section "[rootd]". Certificates and keys may be in either DER or PEM
-format.
-
-Options:
+with -c filename to choose a different configuration file. All options are in
+the section [rootd]. Certificates and keys may be in either DER or PEM format.
 
 bpki-ta::
 
-     Name of file containing BPKI trust anchor. All BPKI certificate
-     validation in rootd traces back to this trust anchor.
+     Where rootd should look for the BPKI trust anchor. All BPKI
+     certificate verification within rootd traces back to this trust
+     anchor. Don't change this unless you really know what you are doing.
+
+     Default: ${myrpki::bpki_servers_directory}/ca.cer
+
+rootd-bpki-crl::
+
+     BPKI CRL. Don't change this unless you really know what you are
+     doing.
+
+     Default: ${myrpki::bpki_servers_directory}/ca.crl
 
 rootd-bpki-cert::
 
-     Name of file containing rootd's own BPKI certificate.
+     rootd's own BPKI EE certificate. Don't change this unless you really
+     know what you are doing.
+
+     Default: ${myrpki::bpki_servers_directory}/rootd.cer
 
 rootd-bpki-key::
 
-     Name of file containing RSA key corresponding to rootd-bpki-cert.
+     Private key corresponding to rootd's own BPKI EE certificate. Don't
+     change this unless you really know what you are doing.
 
-rootd-bpki-crl::
-
-     Name of file containing BPKI CRL that would cover rootd-bpki-cert had
-     it been revoked.
+     Default: ${myrpki::bpki_servers_directory}/rootd.key
 
 child-bpki-cert::
 
-     Name of file containing BPKI certificate for rootd's one and only
-     child (RPKI engine to which rootd issues an RPKI certificate).
+     BPKI certificate for rootd's one and only up-down child (RPKI engine
+     to which rootd issues an RPKI certificate). Don't change this unless
+     you really know what you are doing.
+
+     Default: ${myrpki::bpki_servers_directory}/child.cer
 
 server-host::
 
-     Hostname or IP address on which to listen for HTTP connections.
-     Default is localhost; don't change this unless you really know what
-     you are doing.
+     Server host on which rootd should listen.
+
+     Default: ${myrpki::rootd_server_host}
 
 server-port::
 
-     TCP port on which to listen for HTTP connections.
+     Server port on which rootd should listen.
+
+     Default: ${myrpki::rootd_server_port}
+
+rpki-root-dir::
+
+     Where rootd should write its output. Yes, rootd should be using pubd
+     instead of publishing directly, but it doesn't. This needs to match
+     pubd's configuration.
+
+     Default: ${myrpki::publication_base_directory}
+
+rpki-base-uri::
+
+     rsync URI corresponding to directory containing rootd's outputs.
+
+     Default: `rsync://${myrpki::publication_rsync_server}/${myrpki::publ
+     ication_rsync_module}/`
+
+rpki-root-cert-uri::
+
+     rsync URI for rootd's root (self-signed) RPKI certificate.
+
+     Default: `rsync://${myrpki::publication_rsync_server}/${myrpki::publ
+     ication_root_module}/root.cer`
 
 rpki-root-key::
 
-     Name of file containing RSA key to use in signing resource
-     certificates.
+     Private key corresponding to rootd's root RPKI certificate.
+
+     Default: ${myrpki::bpki_servers_directory}/root.key
 
 rpki-root-cert::
 
-     Name of file containing self-signed RPKI certificate corresponding to
-     rpki-root-key.
+     Filename (as opposed to rsync URI) of rootd's root RPKI certificate.
 
-rpki-root-dir::
+     Default: ${myrpki::publication_root_cert_directory}/root.cer
 
-     Name of directory where rootd should write RPKI subject certificate,
-     manifest, and CRL. This needs to match pubd's configuration.
+rpki-subject-pkcs10::
 
-rpki-subject-cert::
+     Where rootd should stash a copy of the PKCS #10 request it gets from
+     its one (and only) child
+
+     Default: ${myrpki::bpki_servers_directory}/rootd.subject.pkcs10
+
+rpki-subject-lifetime::
 
-     Name of file that rootd should use to save the one and only
-     certificate it issues. Default is "Child.cer".
+     Lifetime of the one and only RPKI certificate rootd issues.
+
+     Default: 30d
 
 rpki-root-crl::
 
-     Name of file to which rootd should save its RPKI CRL. Default is
-     "Root.crl".
+     Filename (relative to rootd-base-uri and rpki-root-dir) of the CRL
+     for rootd's root RPKI certificate.
+
+     Default: root.crl
 
 rpki-root-manifest::
 
-     Name of file to which rootd should save its RPKI manifest. Default is
-     "Root.mft".
+     Filename (relative to rootd-base-uri and rpki-root-dir) of the
+     manifest for rootd's root RPKI certificate.
 
-rpki-subject-pkcs10::
+     Default: root.mft
+
+rpki-class-name::
+
+     Up-down protocol class name for RPKI certificate rootd issues to its
+     one (and only) child.
+
+     Default: ${myrpki::handle}
+
+rpki-subject-cert::
+
+     Filename (relative to rootd-base-uri and rpki-root-dir) of the one
+     (and only) RPKI certificate rootd issues.
 
-     Name of file that rootd should use when saving a copy of the received
-     PKCS #10 request for a resource certificate. Default is
-     "Child.pkcs10".
-
-***** Creating a root certificate *****
-
-rootd does not create the RPKI root certificate, you have to do that yourself.
-The usual way of doing this is to use the OpenSSL command line tool. The exact
-details will depend on which resources you want in the root certificate, the
-URIs for your publication server, and so forth, but the general form looks
-something like this:
-
-  [req]
-  default_bits            = 2048
-  default_md              = sha256
-  distinguished_name      = req_dn
-  prompt                  = no
-  encrypt_key             = no
-
-  [req_dn]
-  CN                      = Testbed RPKI root certificate
-
-  [x509v3_extensions]
-  basicConstraints        = critical,CA:true
-  subjectKeyIdentifier    = hash
-  keyUsage                = critical,keyCertSign,cRLSign
-  subjectInfoAccess       = @sia
-  certificatePolicies     = critical,1.3.6.1.5.5.7.14.2
-  sbgp-autonomousSysNum   = critical,@rfc3779_asns
-  sbgp-ipAddrBlock        = critical,@rfc3997_addrs
-
-  [sia]
-  1.3.6.1.5.5.7.48.5;URI  = rsync://example.org/rpki/
-  1.3.6.1.5.5.7.48.10;URI = rsync://example.org/rpki/root.mft
-
-  [rfc3779_asns]
-  AS.0 = 64496-64511
-  AS.1 = 65536-65551
-
-  [rfc3997_addrs]
-  IPv4.0 = 192.0.2.0/24
-  IPv4.1 = 198.51.100.0/24
-  IPv4.2 = 203.0.113.0/24
-  IPv6.0 = 2001:0DB8::/32
-
-Assuming you save this configuration in a file "root.conf", you can use it to
-generate a root certificate as follows:
-
-  $ openssl genrsa -out root.key 2048
-  $ openssl req -new -config root.conf -out root.req -key root.key
-  $ openssl x509 -req -sha256             \
-          -signkey root.key -in root.req  \
-          -outform DER -out root.cer      \
-          -extfile root.conf -extensions x509v3_extensions \
-          -days 1825
-
-You may want to shorten the five year expire time (1825 days), which is a bit
-long. It is a root certificate, so a longer expire is not unusual.
-
-The generated root.cer must be copied to the publication directory as defined
-in rpki.conf,
-
-  rpki-root-cert                  = ${myrpki::publication_base_directory}/
-  root.cer
-
-To create a TAL format trust anchor locator use
-
-  $ $top/rcynic/make-tal.sh <rsync URI of root.cer> <local copy of root.cer>
+     Default: ${myrpki::handle}.cer
diff --git a/doc/doc.RPKI.CA.Configuration.rpkid b/doc/doc.RPKI.CA.Configuration.rpkid
index c17b2f53..21793157 100644
--- a/doc/doc.RPKI.CA.Configuration.rpkid
+++ b/doc/doc.RPKI.CA.Configuration.rpkid
@@ -1,60 +1,80 @@
-****** rpkid.conf ******
+rpkid's default config file is the system rpkid.conf file. Start rpkid with -
+c filename to choose a different config file. All options are in the section
+[rpkid]. BPKI Certificates and keys may be in either DER or PEM format.
 
-rpkid's default config file is the system rpkid.conf file. Start rpkid with "-
-c filename" to choose a different config file. All options are in the section "
-[rpkid]". Certificates and keys may be in either DER or PEM format.
-
-Options:
+sql-database::
 
-startup-message::
+     MySQL database name for rpkid.
 
-     String to log on startup, useful when debugging a collection of rpkid
-     instances at once.
+     Default: ${myrpki::rpkid_sql_database}
 
 sql-username::
 
-     Username to hand to MySQL when connecting to rpkid's database.
-
-sql-database::
+     MySQL user name for rpkid.
 
-     MySQL's database name for rpkid's database.
+     Default: ${myrpki::rpkid_sql_username}
 
 sql-password::
 
-     Password to hand to MySQL when connecting to rpkid's database.
+     MySQL password for rpkid.
+
+     Default: ${myrpki::rpkid_sql_password}
+
+server-host::
+
+     Host on which rpkid should listen for HTTP service requests.
+
+     Default: ${myrpki::rpkid_server_host}
+
+server-port::
+
+     Port on which rpkid should listen for HTTP service requests.
+
+     Default: ${myrpki::rpkid_server_port}
+
+irdb-url::
+
+     HTTP service URL rpkid should use to contact irdbd. If irdbd is
+     running on the same machine as rpkid, this can and probably should be
+     a loopback URL, since nobody but rpkid needs to talk to irdbd.
+
+     Default: http://${myrpki::irdbd_server_host}:${myrpki::
+     irdbd_server_port}/
 
 bpki-ta::
 
-     Name of file containing BPKI trust anchor. All BPKI certificate
-     verification within rpkid traces back to this trust anchor.
+     Where rpkid should look for the BPKI trust anchor. All BPKI
+     certificate verification within rpkid traces back to this trust
+     anchor. Don't change this unless you really know what you are doing.
+
+     Default: ${myrpki::bpki_servers_directory}/ca.cer
 
 rpkid-cert::
 
-     Name of file containing rpkid's own BPKI EE certificate.
+     Where rpkid should look for its own BPKI EE certificate. Don't change
+     this unless you really know what you are doing.
 
-rpkid-key::
+     Default: ${myrpki::bpki_servers_directory}/rpkid.cer
 
-     Name of file containing RSA key corresponding to rpkid-cert.
+rpkid-key::
 
-irbe-cert::
+     Where rpkid should look for the private key corresponding to its own
+     BPKI EE certificate. Don't change this unless you really know what
+     you are doing.
 
-     Name of file containing BPKI certificate used by IRBE (rpkic, GUI)
-     when talking to rpkid.
+     Default: ${myrpki::bpki_servers_directory}/rpkid.key
 
 irdb-cert::
 
-     Name of file containing BPKI certificate used by irdbd.
+     Where rpkid should look for irdbd's BPKI EE certificate. Don't change
+     this unless you really know what you are doing.
 
-irdb-url::
-
-     Service URL for irdbd. Must be a http:// URL.
-
-server-host::
+     Default: ${myrpki::bpki_servers_directory}/irdbd.cer
 
-     Hostname or IP address on which to listen for HTTP connections.
-     Default is the wildcard address (IPv4 0.0.0.0, IPv6 ::), which should
-     work in most cases.
+irbe-cert::
 
-server-port::
+     Where rpkid should look for the back-end control client's BPKI EE
+     certificate. Don't change this unless you really know what you are
+     doing.
 
-     TCP port on which to listen for HTTP connections.
+     Default: ${myrpki::bpki_servers_directory}/irbe.cer
diff --git a/doc/manual.pdf b/doc/manual.pdf
index 1cc8e8c9..c6a797f8 100644
--- a/doc/manual.pdf
+++ b/doc/manual.pdf