Checkpoint

svn path=/docs/OPERATION; revision=1465

1 files changed, 131 insertions, 2 deletions

diff --git a/docs/OPERATION b/docs/OPERATION
index 272e251c..a7761749 100644
--- a/docs/OPERATION
+++ b/docs/OPERATION
@@ -434,7 +434,16 @@ sql-password:		Password to hand to MySQL when connecting to
 
 ----------------------------------------------------------------
 
-cronjob.py config file:
+cronjob.py:
+
+This is a trivial program to trigger a cron run within rpkid.  Once
+rpkid has been converted to the planned event-driven model, this
+function will be handled internally, but for now it has to be
+triggered by an external program.  For pseudo-production use one would
+run this program under the system cron daemon.  For scripted testing
+it happens to be useful to be able to control when cron cycles occur,
+so at the current stage of code development use of an external trigger
+is a useful feature.
 
 The default config file is cronjob.conf, start cronjob with "-c
 filename" to choose a different config file.  All options are in the
@@ -461,7 +470,127 @@ https-url:		Service URL for rpkid.  Must be a https:// URL.
 
 ----------------------------------------------------------------
 
-testbed.py
+testbed.py:
+
+testbed is a test harness to set up and run a collection of rpkid and
+irdbd instances under scripted control.  testbed is a very recent
+addition to the toolset and is still evolving rapidly.
+
+Unlike the programs described above, testbed 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.  testbed 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.
+
+All of the options in in the first (optional) configuration file are
+just overrides for wired-in default values.   In most cases the
+defaults will suffice, and the set of options is still in flux, so
+only a few of the options are described here.    The default name for
+this configuration file is testbed.conf, run testbed with "-c
+filename" to change it.
+
+testbed.conf options:
+
+testbed_dir:	Working directory into which testbed should write the
+		(many) files it generates.  Default is "testbed.dir".
+
+irdb_db_pass:	MySQL password for the "irdb" user.  Default is
+		"fnord".  You may want to override this.
+
+rpki_db_pass:	MySQL password for the "rpki" user.  Default is
+		"fnord".  You may want to override this.
+
+rootd_sia:	rsync URI naming a (perhaps fictious) directory to use
+		as the id-ad-caRepository SIA value in the generated
+		root resource certificate.  Default is
+		"rsync://wombat.invalid/".  You may want to override
+		this if you intend to run an rsync server and test
+		against the generated results using rcynic.   This
+		default will likely change if and when testbed learns
+		how to run rcynic itself as part of the test suite.
+
+The second configuration file is named testbed.yaml by default, run
+testbed with "-y filename" to change it.  The YAML file contains
+multiple YAML "documents".  The first document describes the initial
+test layout and resource allocations, subsequent documents describe
+modifications to the initial allocations and other parameters.
+Resources listed in the initial layout are aggregated automatically,
+so that a node in the resource hierarchy automatically receives the
+resources it needs to issue whatever its children are listed as
+holding.  Actions in the subsequent documents are modifications to the
+current resource set, modifications to validity dates or other
+non-resource parameters, or special commands like "sleep".  The
+details are still evolving, but here's an example of current usage:
+
+    name:           RIR
+    #valid_until:   2008-07-14T12:30:00Z
+    valid_for:      2d
+    sia_base:       "rsync://wombat.invalid/"
+    kids:
+      - name: LIR0
+	kids:
+	  - name: Alice
+	    ipv4: 192.0.2.1-192.0.2.33
+	    asn:  64533
+    ---
+    - name: Alice
+      valid_add:   10
+    ---
+    - name: Alice
+      add_as: 33
+      valid_add:   2d
+    # valid_until: 2009-07-14T12:30:00Z
+    ---
+    - name: Alice
+    # valid_until: 2009-04-01T00:00:00Z
+      valid_sub:   2d
+    ---
+    - name: Alice
+    # valid_until: 2009-04-01T00:00:00Z
+      valid_for:   10d
+
+This specifies an initial layout consisting of an RPKI engine named
+"RIR", with one child "LIR0", which in turn has one child "Alice".
+Alice has a set of assigned resources, and all resources in the system
+are initially set to be valid for two days from the time at which the
+test is started.  The first subsequent document adds ten seconds to
+the validity interval for Alice's resources and makes no other
+modifications.  The second subsequent document grants Alice additional
+resources and adds another two days to the validity interval for
+Alice's resources.  The next document subtracts two days from the
+validity interval for Alice's resources.  The final document sets the
+validity interval for Alice's resources to ten days.
+
+Operators in subsequent (update) documents:
+
+  add_as, add_v4, add_v6:	These add ASN, IPv4, or IPv6
+				resources, respectively.
+
+  sub_as, sub_v4, sub_v6:	These subtract resources.
+
+  valid_until:			Set an absolute expiration date.
+
+  valid_for:			Set a relative expiration date.
+
+  valid_add, valid_sub:		Add to or subtract from validity interval.
+
+  sleep [interval]:		Sleep for specified interval, or until
+				testbed receives a SIGALRM signal.
+
+Absolute timestamps should be in the form shown (UTC timestamp format
+as used in XML).
+
+Intervals (valid_add, valid_sub, valid_for, sleep) are either
+integers, in which case they're interpreted as seconds, or are a
+string of the form "wD xH yM zS" where w, x, y, and z are integers and
+D, H, M, and S indicate days, hours, minutes, and seconds.  In the
+latter case all of the fields are optional, but at least one must be
+specified.  For example, "3D4H" means "three days plus four hours".
 
 ----------------------------------------------------------------