1 files changed, 163 insertions, 0 deletions
diff --git a/doc/doc.RPKI.RP.rpki-rtr b/doc/doc.RPKI.RP.rpki-rtr
new file mode 100644
index 00000000..6af26a88
--- /dev/null
+++ b/doc/doc.RPKI.RP.rpki-rtr
@@ -0,0 +1,163 @@
+****** rpki-rtr ******
+
+rtr-origin is an implementation of the rpki-rtr protocol.
+
+rtr-origin depends on rcynic to collect and validate the RPKI data. rtr-
+origin's's job is to serve up that data in a lightweight format suitable for
+routers that want to do prefix origin authentication.
+
+To use rtr-origin, you need to do two things beyond setting up rcynic:
+
+  1. You need to set up post-processing of rcynic's output into the data files
+     used by rtr-origin, and
+  2. You need to set up a listener for the rtr-origin server, using the
+     generated data files.
+
+***** Post-processing rcynic's output *****
+
+rtr-origin is designed to do the translation from raw RPKI data into the rpki-
+rtr protocol only once. It does this by pre-computing the answers to all the
+queries it is willing to answer for a given data set, and storing them on disk.
+rtr-origin's --cronjob mode handles this.
+
+To set this up, add an invocation of rtr-origin --cronjob to the cron job
+you're already running to run rcynic. In --cronjob rtr-origin, needs write
+access to a directory where it can store pre-digested versions of the data it
+pulls from rcynic.
+
+rtr-origin creates 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, rtr-origin creates these files under the directory in
+which you run it.
+
+So, assuming that rtr-origin is installed in /usr/local/bin, that rcynic writes
+its data files under /var/rcynic/data/authenticated, and you want rtr-origin to
+write its datafiles to /var/rpki-rtr, you'd add something like the following to
+your cronjob:
+
+  cd /var/rpki-rtr
+  /usr/local/bin/rtr-origin --cronjob /var/rcynic/data/authenticated
+
+See the instructions for setting up a cron job for an example of how to run
+rcynic and rtr-origin together in a single cron job.
+
+You should make sure that rtr-origin runs at least once before attempting to
+configure --server mode. Nothing terrible will happen if you don't do this, but
+--server invocations started before the first --cronjob run may behave oddly.
+
+***** Setting up the rpki-rtr server *****
+
+You need to to set up a server listener that invokes rtr-origin in --server
+mode. What kind of server listener you set up depends on which network protocol
+you're using to transport this protocol. rtr-origin is happy to run under
+inetd, xinetd, sshd, or pretty much anything -- rtr-origin doesn't really care,
+it just reads from stdin and writes to stdout.
+
+--server mode should be run as a non-privileged user (it is read-only for a
+reason). You may want to set up a separate UNIX userid for this purpose so that
+you can give that user its own home directory and ssh configuration files.
+
+--server mode takes an optional argument specifying the path to its data
+directory; if you omit this argument, it uses the directory in in which you run
+it.
+
+The details of how you set up a listener for this vary depending on the network
+protocol and the operating system on which you run it. Here are two examples,
+one for running under inetd, the other for running under sshd.
+
+**** Running rtr-origin --server under inetd ****
+
+Running under inetd with plain TCP is insecure and should only be done for
+testing, but you can also run it with TCP-MD5 or TCP-AO, or over IPsec. The
+inetd configuration is generally the same, the details of how you set up TCP-
+MD5, TCP-AO, or IPsec are platform specific.
+
+To run under inetd, you need to:
+
+  1. Add an entry to /etc/services defining a symbolic name for the port, if
+     one doesn't exist already. At present there is no well-known port defined
+     for this protocol, for this example we'll use port 42420 and the symbolic
+     name rpki-rtr.
+
+     Add to /etc/services:
+
+  rpki-rtr          42420/tcp
+
+  1. Add the service line to /etc/inetd.conf:
+
+  rpki-rtr stream tcp nowait nobody /usr/local/bin/rtr-origin rtr-origin --
+  server /var/rpki-rtr
+
+     This assumes that you want the server to run as user "nobody", which
+     is generally a safe choice, or you could create a new non-priviledged
+     user for this purpose. DO NOT run the server as root; it shouldn't do
+     anything bad, but it's a network server that doesn't need root
+     access, therefore it shouldn't have root access.
+
+**** Running rtr-origin --server under sshd ****
+
+To run rtr-origin under sshd, you need to:
+
+  1. Decide whether to run a new instance of sshd on a separate port or use the
+     standard port. rtr-origin doesn't care, but some people seem to think that
+     it's somehow more secure to run this service on a different port. Setting
+     up sshd in general is beyond the scope of this documention, but most
+     likely you can copy the bulk of your configuration from the standard
+     config.
+  2. Configure sshd to know about the rpki-rtr subsystem. Add something like
+     this to your sshd.conf:
+
+  Subsystem rpki-rtr /usr/local/bin/rtr-origin
+
+  1. Configure the userid(s) you expect ssh clients to use to connect to the
+     server. For operational use you almost certainly do NOT want this user to
+     have a normal shell, instead you should configure its shell to be the
+     server (/usr/local/bin/rtr-origin or wherever you've installed it on your
+     system) and its home directory to be the rpki-rtr data directory (/var/
+     rpki-rtr or whatever you're using). If you're using passwords to
+     authenticate instead of ssh keys (not recommended) you will always need to
+     set the password(s) here when configuring the userid(s).
+  2. Configure the .ssh/authorized_keys file for your clients; if you're using
+     the example values given above, this would be /var/rpki-rtr/.ssh/
+     authorized_keys. You can have multiple ssh clients using different keys
+     all logging in as the same ssh user, you just have to list all of the ssh
+     keys here. You may want to consider using a command= parameter in the key
+     line (see the sshd(8) man page) to lock down the ssh keys listed here so
+     that they can only be used to run the rpki-rtr service.
+
+     If you're running a separate sshd for this purpose, you might also
+     want to add an AuthorizedKeysFile entry pointing at this
+     authorized_keys file so that the server will only use this
+     authorized_keys file regardless of what other user accounts might
+     exist on the machine:
+
+  AuthorizedKeysFile /var/rpki-rtr/.ssh/authorized_keys
+
+     There's a sample sshd.conf in the source directory. You will have to
+     modify it to suit your environment. The most important part is the
+     Subsystem line, which runs the server.sh script as the "rpki-rtr"
+     service, as required by the protocol specification.
+
+**** Other transports ****
+
+You can also run this code under xinetd, or the netpipes "faucet" program, or
+stunnel...other than a few lines that might need hacking to log the connection
+peer properly, the program really doesn't care.
+
+You should, however, care whether the channel you have chosen is secure; it
+doesn't make a lot of sense to go to all the trouble of checking RPKI data then
+let the bad guys feed bad data into your routers anyway because you were
+running the rpki-rtr link over an unsecured TCP connection.
+
+***** Other modes *****
+
+rtr-origin has two other modes which might be useful for debugging:
+
+  1. --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.
+  2. --show mode will display a text dump of pre-digested data files in the
+     current directory.
+
+rtr-origin has a few other modes intended to support specific research
+projects, but they're not intended for general use.