Checkpoint

svn path=/myrpki/README; revision=2814

4 files changed, 35 insertions, 90 deletions

diff --git a/myrpki/README b/myrpki/README
index 24c0fdcf..2fce70fe 100644
--- a/myrpki/README
+++ b/myrpki/README
@@ -54,8 +54,8 @@ Note that, as certificates and CRLs have expiration and nextUpdate
 values, a low-level cycle of updates passing between resource holder
 and rpkid operator will be necessary as a part of steady state
 operation.  (The current version of these tools does not yet
-regenerate these expiring objects, but fixing this is a relatively
-minor matter.)
+regenerate these expiring objects, but fixing this will be a
+relatively minor matter.)
 
 Since we assume that anybody who bothers to run rpkid is also a
 resource holder, myirbe.py and myrpki.py can use the same
@@ -66,12 +66,12 @@ The third important file in this system is the configuration file for
 myrpk.py and myirbe.py.  This contains a number of sections, some of
 which are for these scripts, others of which are for the OpenSSL
 command line tool, which these scripts use do most of the certificate
-work.  The config file is (well, should and will be) commented to
-explain the various parameters.
+work.  The examples/ subdirectory contains a commented version of the
+config file that explains the various parameters.
 
 myrpki.py deliberately does not use any libraries other than the ones
 that ship with Python 2.5; in particular, it does not require any of
-the other Python RPKI code.  This is deliberate, to minimize
+the other Python RPKI code.  This is intentional, to minimize
 portability issues for hosted users.  It does require a reasonably
 current version of the OpenSSL command line tool, but the version that
 is built as a side effect of building the rcynic relying party tool is
@@ -79,95 +79,36 @@ adaquate if the system copy of this tool isn't.
 
 The .csv files read by myrpki.py can be anything that the Python "csv"
 library understands.  By default, they're in tab-delimited format
-(because the author finds that much easier to read than
-comma-delimited format), but this can be changed to fit local needs.
+(because the author finds this easier to read than the comma-delimited
+format), but this can be changed to fit local needs.
+
+Please note: tab delimited CSV is a format defined by a certain
+popular spreadsheet program, and is -not- the same as
+whitespace-separated text.  Tab characters are *punctuation*, and each
+tab character indicates the division between two columns.  Two tab
+characters in a row indicates a separator, a blank column, and another
+separator, not one separator.  The upshot of all this is that
+attempting to make your columns line up prettily will not work as you
+expect, you will end up with too many columns, some of them empty.
 
 A number of the fields in the config or CSV files involve
 certificates.  Some of these are built automatically, others must be
 imported so that the scripts can cross-certify them.  The certificates
-you need to import are all self-signed BPKI certs generated by other
-entities, you import them by specifying the name of a file where you
-stored the BPKI certificate in question (in OpenSSL "PEM" format).
+you need to import are all self-signed BPKI trust anchor certificates
+generated by other entities; you import them by specifying the name of
+a file where you stored the BPKI certificate in question (in OpenSSL
+"PEM" format).
 
 Keep reading, and don't panic.
 
 The default config file name is myrpki.conf.
 
+See examples/myrpki.conf for details on the variables that you can
+(and in some cases must) set.
 
-===
-
-
-(Current) content of the [myrpki] section of the config file:
-
-- handle		Handle of this entity, used in left-right and
-			publication protocols, etc.  You need to set
-			this one.  Syntax is an identifier (letters,
-			digits, hyphen, underscore -- no whitespace or
-			funny characters).
-
-- repository_bpki_certificate
-			Where to find the repository's BPKI
-			certificate, so we can cross certify it.
-			You'll need to set this.
-
-
-- roa_csv		Names of various CSV files, ok as-is
-  children_csv
-  parents_csv
-  prefix_csv
-  asn_csv
-
-- xml_filename		Name of XML input/output file, ok as-is
-
-- bpki_directory	Where this entity's BPKI CA should live,
-			ok as-is
-
-===
-
-(Current) content of the [myirbe] section of the config file:
-
-- irdbd_conf		Where to find the config file for irdbd.  It's
-			ok for this to loop back to the same config
-			file (ie, for the value of this parameter to
-			be myrpki.conf); it's a separate parameter
-			because the [irdbd] config section contains an
-			SQL password, which you might want hidden.
-
-- rpkid_ca_directory	Directories for several CAs, ok as-is
-  pubd_ca_directory
-  rootd_ca_directory
-
-- rsync_base		rsync:// URI to use as base of publication
-			space.
-
-- pubd_base		https:// URL base for contacting pubd
-
-- rpkid_base		https:// URL base for contacting rpkid
-
-
-===
-
-
-CSV file formats:
-
-- roas:		<prefix>/<length>-<maxlength> <asn>
-
-- children:	<child_handle> <validitydate> <bpki_cert_filename>
-  
-- prefix:	<child_handle> <prefix>/<length>
-
-      or:	<child_handle> <range-min>-<range-max>
-
-- asn:		<child_handle> <asn>
-
-- parent:	<parent_handle> <service_uri> <cms_bpki_cert_filename> <https_bpki_cert_filename>
-
-
-===
-
-See the examples/ subdirectory for examples of these files.
-
-[Still need to doc [myirbe] parameters, and need better BPKI doc]
+See examples/*.csv for commented examples of the several CSV files.
+Note that the comments themselves are not legal CSV, they're just
+present to make it easier to understand the examples.
 
 
 
diff --git a/myrpki/examples/myrpki.conf b/myrpki/examples/myrpki.conf
index a61175a1..0eded59b 100644
--- a/myrpki/examples/myrpki.conf
+++ b/myrpki/examples/myrpki.conf
@@ -20,7 +20,9 @@
 [myrpki]
 
 # Handle naming hosted resource-holding entity (<self/>) represented
-# by this myrpki instance.  You need to set this.
+# 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
 
@@ -31,7 +33,9 @@ repository_bpki_certificate	= repository-ta.cer
 
 # Name by which repository will know this <self/>.  This may be a
 # structured handle, eg, "Grandma/Mom/Me" or might be a simple handle,
-# depending on how the repository is set up.  You need to set this.
+# depending on how the repository is set up.  Syntax is same as
+# "handle", with the addition of "/" characters as an allowed
+# delimiter.  You need to set this.
 
 repository_handle		= Me
 
diff --git a/myrpki/examples/parents.csv b/myrpki/examples/parents.csv
index a8f21a74..f1f8171c 100644
--- a/myrpki/examples/parents.csv
+++ b/myrpki/examples/parents.csv
@@ -3,4 +3,4 @@
 # NB: Comment lines are not allowed in these files, this one is only
 # present to explain the example
 #
-Mom	https://localhost:4414/up-down/Mom/Becca	Mom.ta.cer	Mom.rpkid.cer	Becca	rsync://localhost:4401/Me/
+Mom	https://localhost:4414/up-down/Mom/Becca	Mom.ta.cer	Mom.rpkid.cer	Becca	rsync://rpki.example.org/Me/
diff --git a/myrpki/examples/pubclients.csv b/myrpki/examples/pubclients.csv
index 522e8b8a..a521a77d 100644
--- a/myrpki/examples/pubclients.csv
+++ b/myrpki/examples/pubclients.csv
@@ -3,6 +3,6 @@
 # NB: Comment lines are not allowed in these files, this one is only
 # present to explain the example
 #
-Me	bpki.myrpki/ca.cer	rsync://localhost:4401/Me/
-Me/Alice	pubd-client-certs/Alice.cer	rsync://localhost:4401/Me/Alice/
-Me/Bob	pubd-client-certs/Bob.cer	rsync://localhost:4401/Me/Bob/
+Me	bpki.myrpki/ca.cer	rsync://rpki.example.org/Me/
+Me/Alice	pubd-client-certs/Alice.cer	rsync://rpki.example.org/Me/Alice/
+Me/Bob	pubd-client-certs/Bob.cer	rsync://rpki.example.org/Me/Bob/