Checkpoint

svn path=/myrpki/README; revision=2817

1 files changed, 225 insertions, 11 deletions

diff --git a/myrpki/README b/myrpki/README
index 037dbc14..2d015a02 100644
--- a/myrpki/README
+++ b/myrpki/README
@@ -120,19 +120,50 @@ holders) and myirbe.py (for rpkid operators); myirbe.py runs myrpki.py
 automatically for a rpkid operator's own resources if myirbe.py finds
 a [myrpki] section in its config file.
 
-So the basic steps involved in getting started for a resource holder
-who is being hosted by somebody else are:
+Which process you need to follow to get started depends on whether you
+are running rpkid yourself or will be hosted by somebody else.  We
+call the first case "self-hosted", because the software treats running
+rpkid to handle resouces that you yourself hold as if you are an rpkid
+operator who is hosting an entity that happens to be yourself.
+
+"$top" in the following refers to wherever you put the
+subvert-rpki.hactrn.net code.  Once we have autoconf and "make
+install" targets, this will be some system directory or another; for
+now, it's wherever you checked out a copy of of the code from the
+subversion repository or unpacked a tarball of the code.
+
+GETTING STARTED -- HOSTED CASE
+
+The basic steps involved in getting started for a resource holder who
+is being hosted by somebody else are:
 
 1) Obtain contact information and BPKI trust anchors from RPKI parents
    and an RPKI publication service (see below for details).
 
-2) Write a config file (copy examples/myrpki.conf and edit as needed).
-
-3) Create a set of CSV files representing RPKI parents, RPKI children,
-   resources to be assigned to RPKI children, and ROAs to be generated
-   once the necessary RPKI certificates are available.  Most of these
-   CSV files can be empty while first getting started, the only one
-   that absolutely must be populated is the file describing parents.
+2) Write a config file (copy $top/myrpki/examples/myrpki.conf and edit
+   as needed).  You can skip the sections associated with the various
+   daemons and their runtime control tools ([myirbe], [rpkid],
+   [irdbd], [pubd], [rootd], [irbe_cli]).  You *do* need to configure
+   the [myrpki] section.
+
+3) Using $top/myrpki/examples/*.csv as a guide, create a set of CSV
+   files representing RPKI parents, RPKI children, resources to be
+   assigned to RPKI children, and ROAs to be generated once the
+   necessary RPKI certificates are available.  Most of these CSV files
+   can be empty while first getting started, the only file that
+   absolutely must be populated is the file describing parents.
+
+   You may choose to place your config file (which we will refer to
+   here as myrpki.conf) and your CSV files in their own directory.
+   The software doesn't really care.  If you use absolute names for
+   all the filename entries in the config file and CSV files, you can
+   put the files whereever you like; if you use relative names, they
+   will be interpreted relative to the directory in which you run the
+   program that reads the file.
+
+   [At some future date we may provide a default directory for
+   relative filenames such as /usr/local/etc/rpki, but the above
+   description holds for now.]
 
 4) Run myrpki.py to generate a BPKI trust anchor and collect all the
    data from the config file, CSV files, and newly created BPKI into a
@@ -159,13 +190,196 @@ date.]  Any time you run myrpki.py, you should send the updated XML
 file to your rpkid operator, who will [generally?] send you a further
 updated XML file in response.
 
-[CONTINUE HERE]
+GETTING STARTED -- SELF-HOSTED CASE
+
+The first few steps involved in getting started for a self-hosted
+resource holder (that is, a resource holder that runs its own copy of
+rpkid) are the same as in the hosted case above; after that the
+process diverges.
+
+[As of the time at which these instructions were written, it had
+become clear that there really should be an additional setup script
+which automates much of the following.  That script hasn't been
+written yet, so for the moment this documents the setup process as it
+stands now.  Once that setup script has been written, these
+instructions will be updated to match.  In the meantime, please accept
+the author's apologies for the tedious nature of the current setup
+process.]
+
+The [current] steps are:
+
+1) Obtain contact information and BPKI trust anchors from RPKI parents
+   and an RPKI publication service (see below for details).
+
+2) Write a config file (copy examples/myrpki.conf and edit as needed).
+   You need to configure the [myrpki] and [myirbe] sections as well as
+   the sections associated with the daemons you will be running
+   ([rpkid], [irdbd], [irbe_cli]).  You only need to configure the
+   [pubd] section if you intend to run your own publication service:
+   in general this is not recommended, because each additional
+   publication service in the RPKI universe places a small additional
+   burden on every relying party, since every relying party has to
+   download data from every publication service.  In general it's
+   better to use an existing publication service operated by somebody
+   else (eg, your RPKI parent) if you can.  In general most cases you
+   can leave the [rootd] section alone, as in most cases you should
+   not be running rootd.
+
+3) Using $top/myrpki/examples/*.csv as a guide, create a set of CSV
+   files representing RPKI parents, RPKI children, resources to be
+   assigned to RPKI children, and ROAs to be generated once the
+   necessary RPKI certificates are available.  Most of these CSV files
+   can be empty while first getting started, the only file that
+   absolutely must be populated is the file describing parents.
+
+   You may choose to place your config file (which we will refer to
+   here as myrpki.conf) and your CSV files in their own directory.
+   The software doesn't really care.  If you use absolute names for
+   all the filename entries in the config file and CSV files, you can
+   put the files whereever you like; if you use relative names, they
+   will be interpreted relative to the directory in which you run the
+   program that reads the file.
+
+   [At some future date we may provide a default directory for
+   relative filenames such as /usr/local/etc/rpki, but the above
+   description holds for now.]
+
+4) See rpkid/doc/Installation, and follow the basic installation
+   instructions there to build the RFC-3779-aware OpenSSL code and
+   associated Python extension module.
+
+5) Run myirbe.py -b to set up the initial BPKI structure needed to run
+   your daemons:
+
+   $ python $top/myrpki/myirbe.py -b
+
+   The -b option tells myrpki.py that you want it to stop after the
+   initial BPKI setup, regardless of whether it thinks this is
+   necessary.  If you have not done this before it should tell you
+   that it has updated the BPKI and that you need to (re)start daemons
+   now.
+
+[missing step -- sql setup]
+
+[missing step -- rsyncd setup -- include sample config in myrpki/examples?]
+
+6) Start the daemons.  You can use $top/myrpki/start-servers.sh to do
+   this, or write your own script.
+
+   If you intend to run pubd, you should make sure that the directory
+   you specified as publication-base in the [pubd] section exists and
+   is writable by the userid that will be running pubd.
+
+   [start-servers.sh should be replaced by a python script that
+   understands myprki.conf so that it can figure out whether to run
+   pubd and rootd from the config file.]
+
+7) Run myirbe.py again, twice, this time with no arguments.
+
+   $ python $top/myrpki/myirbe.py
+   $ python $top/myrpki/myirbe.py
+
+   The reason for running myirbe.py twice at this point is explained
+   in the Introduction section, above; in brief, the first run sets up
+   almost everything, but a second pass is required to generate the
+   BSC certificate.
+
+At this point, if everything went well, rpkid should be up,
+configured, and starting to obtain resource certificates from its
+parents, generate CRLs and manifests, and so forth.  At this point you
+should go figure out how to use the relying party tool, rcynic: see
+$top/rcynic/README if you haven't already done so.
+
+If and when you change your CSV files, you should run myirbe.py again
+to feed the changes into the daemons.
+
+GETTING STARTED -- HOSTING CASE
+
+If you are running rpkid not just for your own resources but also to
+host other resource holders (see "HOSTED CASE" above), your setup will
+be almost the same as in the self-hosted case (see "SELF-HOSTED CASE",
+above), with one procedural change: you will need to tell myirbe.py to
+process the XML files produced by the resource holders you are
+hosting.  You do this by specifying the names of all those XML files
+on myirbe's command line.  So, if you are hosting two friends, Alice
+and Bob, then, everywhere the instructions for the self-hosted case
+say to run myirbe.py with no arguments, you will instead run it with
+the names of Alice's and Bob's XML files:
+
+  $ python $top/myrpki/myirbe.py alice.xml bob.xml
+
+Note that myirbe.py sometimes modifies these XML files, in which case
+it will write them back to the same filenames.  While it is possible
+to figure out the set of circumstances in which myirbe.py will modify
+XML files (at present, this only happens when myirbe.py has to ask
+rpkid to create a new BSC keypair and PKCS #10 certificate request),
+it may be easiest just to ship back an updated copy of the XML file
+after every you run myirbe.py.
+
+GETTING STARTED -- "PURE" HOSTING CASE
+
+In general we assume that anybody who bothers to run rpkid is also a
+resource holder, but the software does not insist on this.  If you are
+running rpkid solely for others and have no resources of your own, the
+process is almost identical to the "HOSTING CASE", above.  The one
+change is that you should *not* have a [myrpki] section in your
+configuration file.
+
+A (perhaps) slightly-more-plausible use for this capability would be
+if you are an rpkid-running resource holder who wants for some reason
+to keep the resource-holding side of your operation completely
+separate from the rpkid-running side of your operation.  This is
+essentially the pure-hosting model, just with an internal hosted
+entity within a different part of your own organization.
+
+DATA YOU NEED FROM YOUR RPKI PARENT AND PUBLICATION SERVICE
+
+[Not yet written]
+
+TROUBLESHOOTING
+
+If you run into trouble setting up this package, the first thing to do
+is categorize the kind of trouble you are having.  If you've gotten
+far enough to be running the daemons, check their log files.  If
+you're seeing Python exceptions, read the error messages.  If you're
+getting TLS errors, check to make sure that you're using all the right
+BPKI certificates and service contact URLs.
+
+TLS configuration errors are, unfortunately, notoriously difficult to
+debug, because connections due to misconfiguration usually fail early,
+deep in the guts of the OpenSSL TLS code, where there isn't enough
+application context available to provide useful error messages.
+
+If you've completed the steps above, everything appears to have gone
+ok, but nothing seems to be happening, the first thing to do is check
+the logs to confirm that nothing is actively broken.  rpkid's log
+should include messages telling you when it starts and finishes its
+internal "cron" cycle.  It can take several cron cycles for resources
+to work their way down from your parent into a full set of
+certificates and ROAs, so have a little patience.  rpkid's log should
+also include messages showing every time it contacts its parent(s) or
+attempts to publish anything.
+
+rcynic in fully verbose mode provides a fairly detailed explanation of
+what it's doing and why objects that fail have failed.
+
+You can use rsync (sic) to examine the contents of a publication
+repository one directory at a time, without attempting validation, by
+running rsync with just the URI of the directory on its command line:
+
+  $ rsync rsync://rpki.example.org/where/ever/
+
+[Maybe there should be something here explaining how to use
+irbe_cli.py for debugging, but the syntax is fairly obscure as it's
+just a command line interface to the left-right and publication
+protocols -- almost certainly want a friendlier tool for
+troubleshooting.]
 
 
 
 Sketch towards a simple description of the BPKI (sic).
 
-This started out as notes to myself during a redesign, and needs
+This started out as notes to myself during a redesign, and badly needs
 rewriting.
 
 Hosted (myrpki) entity needs: