Minimal documentation, perhaps better than nothing. In a couple of

cases the code should be fixed before further documentation updates,
since the documented behavior is gratuitously silly.

svn path=/rtr-origin/README; revision=3224

2 files changed, 83 insertions, 2 deletions

diff --git a/rtr-origin/README b/rtr-origin/README
new file mode 100644
index 00000000..ddde6d6b
--- /dev/null
+++ b/rtr-origin/README
@@ -0,0 +1,75 @@
+$Id$
+
+Sample implementation of draft-ymbk-rpki-rtr-protocol.
+
+This depends on rcynic (../rcynic/) to collect and validate the RPKI
+data.  This program's job is to serve up that data in a lightweight
+format suitable for routers that want to do prefix origin
+authentication.
+
+To use this, you need to do two things beyond setting up rcynic:
+
+1) Add an invocation of this program in --cronjob mode to the cron job
+   you're already running to run rcynic.  In cronjob mode this program
+   needs write access to a directory where it can store pre-digested
+   versions of the data it pulls from rcynic.
+
+   The program will create a collection of data files, as well as a
+   subdirectory in which each instance of the program running in
+   --server mode can write a PF_UNIX socket file.  At present, it
+   creates these files under the directory in which the program was
+   run.
+
+   So if this script lives in $srcdir, rcynic writes its data files
+   under $rcynicdir, and you want this program to write its datafiles
+   to $rtrorigindir, you would add something like the following to
+   your cronjob:
+
+     cd $rtrorigindir
+     /usr/local/bin/python $srcdir/rtr-origin.py --cronjob $rcynicdir
+
+   You should make sure this program runs at least once before
+   attempting to configure --server mode.  Nothing terrible will
+   happen if you don't, but --server invocations started before the
+   first --cronjob run may behave oddly.
+
+2) You need to to set up a server listener that invokes this program
+   in --server mode.  What kind of server listener you set up depends
+   on which network protocol you're using to transport this protocol.
+   The specification says that the rpki-rtr protocol will run under
+   ssh, but not all clients support that yet.  rtr-origin.py doesn't
+   really care, it just reads from stdin and writes to stdout.
+
+   As with --cronjob mode, --server mode currently uses the directory
+   in which it was started as its data directory (this may change in
+   the future), so you need to arrange for whatever program invokes it
+   to cd to whatever you used as your $rtrorigindir, above.  Eg:
+
+     cd $rtrorigindir
+     /usr/local/bin/python $srcdir/rtr-origin.py --server
+
+   There's a sample sshd.conf in the source directory.  You will have
+   to modify it to suit your environment.  The important part is the
+   Subsystem line, which runs the server.sh script as the rpki-rtr
+   service.  server.sh is also a sample and will also need
+   modification for your environment.
+
+   You can also run this code under inetd (or the netpipes "faucet"
+   program), with the understanding that this is totally insecure and
+   only suitable for early testing.
+
+   In theory one could also run this under TLS, eg, via the stunnel
+   program, which would provide roughly equivalent (albiet different)
+   security to ssh.  Other than a few lines of logging code, the
+   program really doesn't care.
+
+The program has two other modes, which might be useful for debugging:
+
+a) --client mode implements a dumb client program for this protocol,
+   over ssh, raw tcp, or by invoking --server mode directly in a
+   subprocess.  The output is not expected to be useful except for
+   debugging.
+
+b) --show mode will display a text dump of pre-digested data files in
+   the current directory.
+
diff --git a/rtr-origin/rtr-origin.py b/rtr-origin/rtr-origin.py
index 22a7ad4f..ad5b9d6c 100644
--- a/rtr-origin/rtr-origin.py
+++ b/rtr-origin/rtr-origin.py
@@ -1,6 +1,7 @@
 """
 Router origin-authentication rpki-router protocol implementation.
-This is a work in progress.
+This is a work in progress.  See draft-ymbk-rpki-rtr-protocol in fine
+Internet-Draft repositories near you.
 
 As presently written, this program can run in one of three different
 modes: cronjob, server, and client.
@@ -24,9 +25,14 @@ client mode is, at presnt, a toy client, intended only for debugging.
 It allows one to issue queries to a server and prints out the
 responses.
 
+NB: At present this supports an old version of the protocol, because
+the router implementation that currently tests against it also
+implements that old version.  One of these days we'll fix that.
+
+
 $Id$
 
-Copyright (C) 2009  Internet Systems Consortium ("ISC")
+Copyright (C) 2009-2010  Internet Systems Consortium ("ISC")
 
 Permission to use, copy, modify, and distribute this software for any
 purpose with or without fee is hereby granted, provided that the above