Automatic pull of documentation from Wiki.

svn path=/trunk/; revision=5354

1 files changed, 102 insertions, 116 deletions

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