Automatic pull of documentation from Wiki.

svn path=/trunk/; revision=5371

1 files changed, 82 insertions, 310 deletions

diff --git a/doc/doc.RPKI.CA.Configuration b/doc/doc.RPKI.CA.Configuration
index 6ccec59b..1e9d61fd 100644
--- a/doc/doc.RPKI.CA.Configuration
+++ b/doc/doc.RPKI.CA.Configuration
@@ -25,9 +25,10 @@ The location of rpki.conf varies depending on the operating system you're
 running and how you installed the software. Unless you did something unusual
 during installation, it's either /etc/rpki.conf or /usr/local/etc/rpki.conf.
 
-All of the configuration options you're most likely to need to change are in
-the ![myrpki] section of rpki.conf, which is discussed in much greater detail
-elsewhere.
+* All of the configuration options you're most likely to need to change are in
+  the [myrpki] section of rpki.conf.
+
+  [myrpki]
 
 * You need to check the setting of rpkid_server_host. The installation process
   sets this to the fully-qualified DNS hostname of the server on which you
@@ -39,11 +40,11 @@ elsewhere.
 * You need to set the value of run_pubd to reflect whether you intend to run
   your own RPKI publication server and rsync server.
 
-  run_pubd                        = false
+  run_pubd                        = yes
 
      or
 
-  run_pubd                        = true
+  run_pubd                        = no
 
 * If you are running your own RPKI publication server, you need to check the
   setting of pubd_server_host. The installation process sets this to the fully-
@@ -59,246 +60,77 @@ details if you need to know more, otherwise go to next steps.
 
 ***** Configuration file syntax *****
 
-Each of the programs that make up the RPKI tookit can potentially take its own
-configuration file, but for most uses this is unnecessarily complicated. The
-recommended approach is to use a single configuration file, and to put all of
-the parameters that a normal user might need to change into a single section of
-that configuration file, then reference these common settings from the program-
-specific sections of the configuration file via macro expansion.
+The general format of rpki.conf is the same as the configuration language used
+by many other programs, including the OpenSSL package. The file is divided into
+"sections", labeled with square brackets; individual options within a section
+look like variable assignments, with the option name on the left and the option
+value on the right.
+
+  [foo]
+
+  bar = fred
+  baz = 42
 
 The configuration file parser supports a limited version of the macro facility
 used in OpenSSL's configuration parser. An expression such as
 
   foo = ${bar::baz}
 
-sets foo to the value of the baz variable from section bar. The section name
-ENV is special: it refers to environment variables.
-
-***** rpki.conf *****
-
-The default name for the shared configuration file is rpki.conf. The location
-of the system-wide rpki.conf file is selected by ./configure during
-installation; the default location is /usr/local/etc, unless you use the --
-sysconfdir option to ./configure, in which case the default location is
-whatever directory you gave ./configure as the argument to this option.
-
-You can override the build-time default filename at runtime by setting the
-RPKI_CONF environment variable to the name of the configuration file you want
-to use. Most of the programs also take a command-line option specifying the
-name of the configuration file; if both the command line option and the
-environment variable are set, the command line option wins.
-
-Unless you really know what you're doing, you should start by copying the
-rpki.conf from the rpkid/examples directory and modifying it, as the sample
-configuration file already includes all the additional settings necessary to
-use the simplified configuration.
-
-We really should have a configuration wizard script which leads you through the
-process of creating a basic rpki.conf file, but we haven't written it yet.
-Someday Real Soon Now.
-
-  [myrpki]
-
-The [myrpki] section of rpki.conf contains all the parameters that you really
-need to configure. The name myrpki] is historical and may change in the future.
-
-  # Handle naming hosted resource-holding entity (<self/>) represented
-  # by this myrpki instance.  Syntax is an identifier (ASCII letters,
-  # digits, hyphen, underscore -- no whitespace, non-ASCII characters,
-  # or other punctuation).  You need to set this.
-
-  handle                          = Me
-
-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.
-
-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.
-
-  # Directory for BPKI files generated by rpkic and used by rpkid and pubd.
-  # Default is where we expect autoconf to decide that our data files
-  # belong, you might want or need to change this.   In the long term
-  # this should be handled by a setup wizard.
-
-  bpki_servers_directory          = /usr/local/share/rpki
-
-You shouldn't need to change this unless you used the --datarootdir option to
-tell ./configure; if you did, you'll need to adjust the setting of
-bpki_servers_directory to match whatever you told ./configure.
-
-  # Whether you want to run your own copy of rpkid (and irdbd).  You
-  # want this on unless somebody else is hosting rpkid service for you.
-
-  run_rpkid                      = true
-
-You probably don't need to change this.
+sets foo to the value of the baz variable from section bar.
 
-  # DNS hostname and server port numbers for rpkid and irdbd.  rpkid's
-  # server host has to be a publicly reachable name to be useful;
-  # irdbd's server host should always be localhost unless you really
-  # know what you are doing.  Port numbers can be any legal TCP port
-  # number that you're not using for something else.
+The section name ENV is special: it refers to environment variables.
 
-  rpkid_server_host               = rpkid.example.org
-  rpkid_server_port               = 4404
-  irdbd_server_host               = localhost
-  irdbd_server_port               = 4403
-
-You'll need to set at least the rpkid_server_host parameter here. You may be
-able to use the default port numbers, or may need to pick different ones.
-Unless you plan to run irdbd on a different machine from rpkid, you should
-leave irdbd_server_host alone.
-
-  # Whether you want to run your own copy of pubd.  In general, it's
-  # best to use your parent's pubd if you can, to reduce the overall
-  # number of publication sites that relying parties need to check, so
-  # don't enable this unless you have a good reason.
-
-  run_pubd                        = false
+  home = ${ENV::HOME}
 
-  # DNS hostname and server port number for pubd, if you're running it.
-  # Hostname has to be a publicly reachable name to be useful, port can
-  # be any legal TCP port number that you're not using for something
-  # else.
+Each of the programs that make up the RPKI tookit can potentially take its own
+configuration file, but for most uses this is unnecessarily complicated. The
+recommended approach is to use a single configuration file, and to put all of
+the parameters that a normal user might need to change into a single section of
+that configuration file, then reference these common settings from the program-
+specific sections of the configuration file via macro expansion.
 
-  pubd_server_host                = pubd.example.org
-  pubd_server_port                = 4402
-
-  # Contact information to include in offers of repository service.
-  # This only matters when we're running pubd.  This should be a human
-  # readable string, perhaps containing an email address or URL.
-
-  pubd_contact_info               = repo-man@rpki.example.org
-
-The out of band setup protocol will attempt to negotiate publication service
-for you with whatever publication service your parent is using, if you let it,
-so in most cases you should not need to run pubd unless you need to issue
-certificates for private IP address space or private Autononmous System
-Numbers.
-
-If you do run pubd, you will need to set pubd_server_host. You may also need to
-set pubd_server_port, and you should provide something helpful as contact
-information in pubd_contact_info if you plan to offer publication service to
-your RPKI children, so that grandchildren (or descendents even further down the
-tree) who receive referrals to your service will know how to contact you.
-
-  # 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                       = false
-
-  # 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
-
-You shouldn't run rootd unless you're the root of an RPKI tree. Who gets to be
-the root of the public RPKI tree is a political issue outside the scope of this
-document. For everybody else, the only reason for running rootd (other than
-test purposes) would be to support certification of private IP addresses and
-ASNs. The core tools can do this without any problem, but the simplified
-configuration mechanism does not (yet) make this easy to do.
-
-  # Root of local directory tree where pubd (and rootd, sigh) 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.
-
-  publication_base_directory      = publication/
-
-  # 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
-
-  # 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}
-
-These parameters control the mapping between the rsync URIs presented by rsyncd
-and the local filesystem on the machine where pubd and rsyncd run. Any changes
-here must also be reflected as changes in rsyncd.conf. In most cases you should
-not change the value of publication_rsync_module from the default; since pubd
-can't (and should not) rewrite rsyncd.conf, it's best to use a static rsync
-module name here and let pubd do its work underneath that name. In most cases
-publication_rsync_server should be the same as publication_rsync_server, which
-is what the macro invocation in the default setting does.
-publication_base_directory, like other pathnames in rpki.conf, can be either a
-relative or absolute pathname; if relative, it's interpreted with respect to
-the directory in which the programs in question were started. It's probably
-better to use an absolute pathname, since this pathname must also appear in
-rsyncd.conf.
-
-  # Startup control.  These all default to the values of the
-  # corresponding run_* options, to keep things simple.  The only case
-  # where you would want to change these 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_*" controls whether
-  # the back-end code is doing things to manage the daemon in question,
-  # while "start_*" controls whether rpki-start-servers attempts to
-  # start the daemon in question.
-
-  start_rpkid                     = ${myrpki::run_rpkid}
-  start_irdbd                     = ${myrpki::run_rpkid}
-  start_pubd                      = ${myrpki::run_pubd}
-  start_rootd                     = ${myrpki::run_rootd}
-
-You don't need to change these unless for some reason you need to run rpkid,
-pubd, or both on different machines from your back end code. In such cases, you
-can use these options to control which daemons start on which hosts, and to
-tell the back end code (rpkic and the GUI) that they're responsible for talking
-to rpkid and pubd even though those daemons are running on other hosts.
-
-The main reason why you might want to do this would be cases where you might
-want to run rpkid and pubd in a DMZ while keeping all of the back end code
-behind a firewall.
-
-  # SQL configuration.  You can ignore this if you're not running any of
-  # the daemons yourself.
-
-  # If you're comfortable with having all of the databases use the same
-  # MySQL username and password, set those values here.  It's ok to
-  # leave the default username alone, but you should use a locally
-  # generated password either here or in the individual settings below.
-
-  shared_sql_username             = rpki
-  shared_sql_password             = fnord
-
-  # If you want different usernames and passwords for the separate SQL
-  # databases, enter those settings here; the shared_sql_* settings are
-  # only referenced here, so you can remove them entirely if you're
-  # setting everything in this block.
-
-  rpkid_sql_database              = rpkid
-  rpkid_sql_username              = ${myrpki::shared_sql_username}
-  rpkid_sql_password              = ${myrpki::shared_sql_password}
-
-  irdbd_sql_database              = irdbd
-  irdbd_sql_username              = ${myrpki::shared_sql_username}
-  irdbd_sql_password              = ${myrpki::shared_sql_password}
-
-  pubd_sql_database               = pubd
-  pubd_sql_username               = ${myrpki::shared_sql_username}
-  pubd_sql_password               = ${myrpki::shared_sql_password}
-
-These settings control how rpkid, irdbd, and pubd talk to the MySQL server. At
-minimum, each daemon needs its own database; in the simplest configuration, the
-username and password can be shared, which is what the macro references in the
-default configuration does. If for some reason you need to set different
-usernames and passwords for different daemons, you can do so by changing the
-daemon-specific variables.
+The default name for the shared configuration file is rpki.conf. The location
+of the system-wide rpki.conf file is selected by ./configure during
+installation. The default location is /usr/local/etc/rpki.conf when building
+from source or on platforms like FreeBSD or MacOSX where packaged software goes
+in the /usr/local tree; on GNU/Linux platforms, binary packages will use /etc/
+rpki.conf per GNU/Linux convention.
+
+Regardless of the default location, you can override the build-time default
+filename at runtime if necessary by setting the RPKI_CONF environment variable
+to the name of the configuration file you want to use. Most of the programs
+also take a command-line option (generally "-c") specifying the name of the
+configuration file; if both the command line option and the environment
+variable are set, the command line option wins.
+
+The installation process builds a sample configuration file rpki.conf.sample
+and installs it alongside of rpki.conf. If you have no rpki.conf installed, the
+installation process will copy rpki.conf.sample to rpki.conf, but it will not
+overwrite an existing rpki.conf file.
+
+***** Too much information about rpki.conf options *****
+
+The list of options that you can set in rpki.conf is ridiculously long. The
+default configuration includes what we hope are reasonable default settings for
+all of them, so in many cases you will never need to know about most of these
+options. A number of the options for individual programs are specified in terms
+of other options, using the macro facility described above.
+
+In general, if you don't understand what an option does, you probably should
+leave it alone.
+
+Detailed information about individual options is listed in separate sections,
+one per section of rpki.conf. These documentation sections are generated from
+the same source file as the sample configuration file.
+
+* Common Options
+* [myrpki] section
+* [rpkid] section
+* [irdbd] section
+* [pubd] section
+* [rootd] section
+* [web_portal] section
+* [autoconf] section
 
 ***** rsyncd.conf *****
 
@@ -327,87 +159,27 @@ You may need to do something more complicated if you are already running rsyncd
 for other purposes. See the rsync(1) and rsyncd.conf(5) manual pages for more
 details.
 
-***** Other configuration files and options *****
-
-In most cases the simplified configuration in the [myrpki] section of rpki.conf
-should suffice, but in case you need to tinker, here are details on the the
-rest of the configuration options. In most cases the default name of the
-configuration file for a program is the name of the program followed by .conf,
-and the section name is also named for the program, so that you can combine
-sections into a single configuration file as shown with rpki.conf.
-
-* Common configuration options
-* rpkid configuration
-* irdbd configuration
-* pubd configuration
-* rootd configuration
+***** Running your own RPKI root *****
 
-***** Next steps *****
-
-Once you've finished with configuration, the next thing you should read is the
-MySQL setup instructions.
+In general, we do not recommend running your own RPKI root environment, for
+various reasons. If, however, you need to do so, you should read the
+documentation for the [rootd] section, and the instructions for creating a RPKI
+root certificate.
 
 ***** 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.
+all on the same server. For most purposes, this is fine, but in some cases you
+might want to split these functions up among different servers. If you need to
+do this, see these instructions.
 
-* Copy the rpki.conf to the other machines, and customize each copy to that
-  machine's role:
+***** Configuring the test harness *****
 
-  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.
+We expect the test harness to be of interest primarily to developers, but if
+you need to understand how it works, you will probably want to read these
+instructions.
 
-* Run rpki-start-servers on each of the three hosts when it's time to start the
-  servers.
+***** Next steps *****
 
-* 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.
+Once you've finished with configuration, the next thing you should read is the
+MySQL setup instructions.