Use html2text instead of lynx for dumping doc to flat text

svn path=/rpkid/Makefile; revision=3208

1 files changed, 160 insertions, 144 deletions

diff --git a/rpkid/doc/Operation b/rpkid/doc/Operation
index e8346c40..2118f43a 100644
--- a/rpkid/doc/Operation
+++ b/rpkid/doc/Operation
@@ -1,174 +1,190 @@
-Operation Guide
 
-   Production-side RPKI tools, for Internet Registries (RIRs, LIRs, etc).
 
-   See rcynic/README for relying party tools.
+****** Operation Guide ******
 
-   Warning:
-          rpkid is still in development, and the code changes more often
-          than the hand-maintained portions of this documentation. The
-          following text was reasonably accurate at the time it was
-          written but may be obsolete by the time you read it.
+Production-side RPKI tools, for Internet Registries (RIRs, LIRs, etc).
 
-   At present the package is intended to be run out of the rpkid/
-   directory.
+See rcynic/README for relying party tools.
 
-   In addition to the library routines in the rpkid/rpki/ directory, the
-   package includes the following programs:
 
-     * rpkid : The main RPKI engine daemon.
 
-     * pubd : The publication engine daemon.
+  Warning:
+      rpkid is still in development, and the code changes more often than the
+      hand-maintained portions of this documentation. The following text was
+      reasonably accurate at the time it was written but may be obsolete by the
+      time you read it.
 
-     * rootd : A separate daemon for handling the root of an RPKI
-       certificate tree. This is essentially a stripped down version of
-       rpkid with no SQL database, no left-right protocol implementation,
-       and only the parent side of the up-down protocol. It's separate
-       because the root is a special case in several ways and it was
-       simpler to keep the special cases out of the main daemon.
+At present the package is intended to be run out of the rpkid/ directory.
 
-     * irdbd : A sample implementation of an IR database daemon. rpkid
-       calls into this to perform lookups via the left-right protocol.
+In addition to the library routines in the rpkid/rpki/ directory, the package
+includes the following programs:
 
-     * smoketest : A test tool for running a collection of rpkid and irdb
-       instances under common control, driven by a unified test script.
 
-     * yamltest : Another test tool which takes the same input format as
-       smoketest.py, but with slightly different purpose. smoketest.py is
-       intended to support regression tests, while yamltest.py is intended
-       for automated testing of something closer to a real operational
-       environment. There's a fair amount of code duplication between the
-       two, and at some point they will probably be merged into a single
-       program that supports both modes of operation.
+* rpkid_: The main RPKI engine daemon.
 
-   Most of these programs take configuration files in a common format
-   similar to that used by the OpenSSL command line tool. The test
-   programs also take input in YAML format to drive the tests. Runs of the
-   yamltest test tool will generate a fairly complete set configuration
-   files which may be useful as examples.
 
-   Basic operation consists of creating the appropriate MySQL databases,
-   configuring relationships between parents and children and between
-   publication clients and repositories, starting rpkid, pubd, rootd, and
-   irdbd, and using the left-right and publication control protocols to
-   set up rpkid's and pubd's internal state. All other operations should
-   occur either as a result of cron events or as a result of incoming
-   left-right and up-down protocol requests.
+* pubd_: The publication engine daemon.
 
-   The core programs are all event-driven, and are (in theory) capable of
-   supporting an arbitrary number of hosted RPKI engines to run in a
-   single rpkid instance, up to the performance limits of the underlying
-   hardware.
-
-   At present the daemon programs all run in foreground, that is, if one
-   wants them to run in background one must do so manually, eg, using
-   Bourne shell syntax:
-
-   $ python whatever.py &
-   $ echo >whatever.pid  "$!"
-
-   All of the daemons use syslog by default. To make them log to stderr
-   instead, use the "-d" option.
 
-   Some of the options that the several daemons take are common to all
-   daemons. Which daemon they affect depends only on which sections of
-   which config files they are in. See Common Options for details.
+* rootd_: A separate daemon for handling the root of an RPKI certificate tree.
+  This is essentially a stripped down version of rpkid with no SQL database, no
+  left-right protocol implementation, and only the parent side of the up-down
+  protocol. It's separate because the root is a special case in several ways
+  and it was simpler to keep the special cases out of the main daemon.
 
-rpkid
 
-   rpkid is the main RPKI engine daemon. Configuration of rpkid is a two
-   step process: a config file to bootstrap rpkid to the point where it
-   can speak using the left-right protocol, followed by dynamic
-   configuration via the left-right protocol. The latter stage is handled
-   by the myrpki tool.
+* irdbd_: A sample implementation of an IR database daemon. rpkid calls into
+  this to perform lookups via the left-right protocol.
 
-   rpkid stores dynamic data in an SQL database, which must have been
-   created for it, as explained in the Installation Guide".
 
-   See Configuration Options for configuration options.
+* smoketest_: A test tool for running a collection of rpkid and irdb instances
+  under common control, driven by a unified test script.
 
-pubd
 
-   pubd is the publication daemon. It implements the server side of the
-   publication protocol, and is used by rpkid to publish the certificates
-   and other objects that rpkid generates.
+* yamltest : Another test tool which takes the same input format as
+  smoketest.py, but with slightly different purpose. smoketest.py is intended
+  to support regression tests, while yamltest.py is intended for automated
+  testing of something closer to a real operational environment. There's a fair
+  amount of code duplication between the two, and at some point they will
+  probably be merged into a single program that supports both modes of
+  operation.
 
-   pubd is separate from rpkid for two reasons:
+Most of these programs take configuration files in a common format similar to
+that used by the OpenSSL command line tool. The test programs also take input
+in YAML format to drive the tests. Runs of the yamltest test tool will generate
+a fairly complete set configuration files which may be useful as examples.
 
-     * The hosting model allows entities which choose to run their own
-       copies of rpkid to publish their output under a common publication
-       point. In general, encouraging shared publication services where
-       practical is a good thing for relying parties, as it will speed up
-       rcynic synchronization time.
-
-     * The publication server has to run on (or at least close to) the
-       publication point itself, which in turn must be on a publically
-       reachable server to be useful. rpkid, on the other hand, need only
-       be reachable by the IRBE and its children in the RPKI tree. rpkid
-       is a much more complex piece of software than pubd, so in some
-       situations it might make sense to wrap tighter firewall constraints
-       around rpkid than would be practical if rpkid and pubd were a
-       single program.
+Basic operation consists of creating the appropriate MySQL databases (see MySQL
+Setup), configuring relationships between parents and children and between
+publication clients and repositories (see The_myrpki_tool), starting rpkid,
+pubd, rootd, and irdbd, and using the left-right and publication control
+protocols (see The_myrpki_tool) to set up rpkid's and pubd's internal state.
+All other operations should occur either as a result of cron events or as a
+result of incoming left-right and up-down protocol requests.
 
-   pubd stores dynamic data in an SQL database, which must have been
-   created for it, as explained in the installation guide. pubd also
-   stores the published objects themselves as disk files in a configurable
-   location which should correspond to an appropriate module definition in
-   rsync.conf.
-
-   See Configuration Options for configuration options.
-
-rootd
-
-   rootd is a stripped down implmenetation of (only) the server side of
-   the up-down protocol. It's a separate program because the root
-   certificate of an RPKI certificate tree requires special handling and
-   may also require a special handling policy. rootd is a simple
-   implementation intended for test use, it's not suitable for use in a
-   production system. All configuration comes via the config file.
-
-   See Configuration Options for configuration options.
-
-irdbd
-
-   irdbd is a sample implemntation of the server side of the IRDB callback
-   subset of the left-right protocol. In production use this service is a
-   function of the IRBE stub; irdbd may be suitable for production use in
-   simple cases, but an IR with a complex IRDB may need to extend or
-   rewrite irdbd.
-
-   irdbd requires a pre-populated database to represent the IR's
-   customers. irdbd expects this database to use the SQL schema defined in
-   rpkid/irdbd.sql. Once this database has been populated, the IRBE stub
-   needs to create the appropriate objects in rpkid's database via the
-   control subset of the left-right protocol, and store the linkage IDs
-   (foreign keys into rpkid's database, basicly) in the IRDB.
-
-   See Configuration Options for configuration options.
+The core programs are all event-driven, and are (in theory) capable of
+supporting an arbitrary number of hosted RPKI engines to run in a single rpkid
+instance, up to the performance limits of the underlying hardware.
 
-smoketest:
-
-   smoketest is a test harness to set up and run a collection of rpkid and
-   irdbd instances under scripted control.
+At present the daemon programs all run in foreground, that is, the daemons
+themselves make no attempt to put themselves in background. The easiest way to
+run the servers is to run the start_servers script, which examines your
+myrpki.conf file and starts the appropriate servers in background using
+myrpki.conf as the configuration file for each server as well.
+
+If you prefer, you can run each server by hand instead of using the script, eg,
+using Bourne shell syntax to run rpkid in background:
+
+
+     $ python rpkid.py &
+     $ echo >rpkid.pid  "$!"
+
+All of the daemons use syslog by default. You can change this by running either
+the servers themselves or the start_servers script with the "-d" option. Used
+as an argument to a server directly, "-d" causes that server to log to stderr
+instead of to syslog. Used as an argument to start_servers, "-d" starts each of
+the servers with "-d" while redirecting stderr from each server to a separate
+log file. This is intended primarily for debugging.
+
+Some of the options that the several daemons take are common to all daemons.
+Which daemon they affect depends only on which sections of which config files
+they are in. See Common_Options for details.
+
+
+***** rpkid *****
+
+rpkid is the main RPKI engine daemon. Configuration of rpkid is a two step
+process: a config file to bootstrap rpkid to the point where it can speak using
+the left-right_protocol, followed by dynamic configuration via the left-right
+protocol. The latter stage is handled by the myrpki tool.
+
+rpkid stores dynamic data in an SQL database, which must have been created for
+it, as explained in the Installation_Guide.
+
+See Configuration_Options for configuration options.
+
+
+***** pubd *****
+
+pubd is the publication daemon. It implements the server side of the
+publication protocol, and is used by rpkid to publish the certificates and
+other objects that rpkid generates.
+
+pubd is separate from rpkid for two reasons:
+
+
+* The hosting model allows entities which choose to run their own copies of
+  rpkid to publish their output under a common publication point. In general,
+  encouraging shared publication services where practical is a good thing for
+  relying parties, as it will speed up rcynic synchronization time.
+
+
+* The publication server has to run on (or at least close to) the publication
+  point itself, which in turn must be on a publically reachable server to be
+  useful. rpkid, on the other hand, need only be reachable by the IRBE and its
+  children in the RPKI tree. rpkid is a much more complex piece of software
+  than pubd, so in some situations it might make sense to wrap tighter firewall
+  constraints around rpkid than would be practical if rpkid and pubd were a
+  single program.
+
+pubd stores dynamic data in an SQL database, which must have been created for
+it, as explained in the installation guide. pubd also stores the published
+objects themselves as disk files in a configurable location which should
+correspond to an appropriate module definition in rsync.conf.
+
+See Configuration_Options for configuration options.
+
+
+***** rootd *****
+
+rootd is a stripped down implmenetation of (only) the server side of the up-
+down protocol. It's a separate program because the root certificate of an RPKI
+certificate tree requires special handling and may also require a special
+handling policy. rootd is a simple implementation intended for test use, it's
+not suitable for use in a production system. All configuration comes via the
+config file.
+
+See Configuration_Options for configuration options.
+
+
+***** irdbd *****
+
+irdbd is a sample implemntation of the server side of the IRDB callback subset
+of the left-right protocol. In production use this service is a function of the
+IRBE stub; irdbd may be suitable for production use in simple cases, but an IR
+with a complex IRDB may need to extend or rewrite irdbd.
+
+irdbd requires a pre-populated database to represent the IR's customers. irdbd
+expects this database to use the SQL schema defined in rpkid/irdbd.sql. Once
+this database has been populated, the IRBE stub needs to create the appropriate
+objects in rpkid's database via the control subset of the left-right protocol,
+and store the linkage IDs (foreign keys into rpkid's database, basicly) in the
+IRDB.
+
+See Configuration_Options for configuration options.
+
+
+***** smoketest: *****
+
+smoketest is a test harness to set up and run a collection of rpkid and irdbd
+instances under scripted control.
+
+Unlike the programs described above, smoketest takes two configuration files in
+different languages. The first configuration file uses the same syntax as the
+above configuration files but is completely optional. The second configuration
+file is the test script, which is encoded using the YAML serialization language
+(see http://www.yaml.org/ for more information on YAML). The YAML script is not
+optional, as it describes the test layout. smoketest is designed to support
+running a fairly wide set of test configurations as canned scripts without
+writing any new control code. The intent is to make it possible to write
+meaningful regression tests.
+
+See smoketest.conf for what can go into the (optional) first configuration
+file.
+
+See smoketest.yaml for what goes into the (required) second configuration file.
 
-   Unlike the programs described above, smoketest takes two configuration
-   files in different languages. The first configuration file uses the
-   same syntax as the above configuration files but is completely
-   optional. The second configuration file is the test script, which is
-   encoded using the YAML serialization language (see http://www.yaml.org/
-   for more information on YAML). The YAML script is not optional, as it
-   describes the test layout. smoketest is designed to support running a
-   fairly wide set of test configurations as canned scripts without
-   writing any new control code. The intent is to make it possible to
-   write meaningful regression tests.
 
-   See smoketest.conf for what can go into the (optional) first
-   configuration file.
 
-   See smoketest.yaml for what goes into the (required) second
-   configuration file.
-     __________________________________________________________________
 
 
-    Generated on Fri Apr 16 17:28:16 2010 for RPKI Engine by  doxygen
-    1.6.3