diff options
| -rw-r--r-- | doc/doc.RPKI.RP.rcynic | 145 | ||||
| -rw-r--r-- | doc/doc.RPKI.RP.rcynicChroot | 169 | ||||
| -rw-r--r-- | doc/doc.RPKI.RP.rpki-rtr | 62 | ||||
| -rw-r--r-- | doc/manual.pdf | bin | 748580 -> 750676 bytes |
4 files changed, 201 insertions, 175 deletions
diff --git a/doc/doc.RPKI.RP.rcynic b/doc/doc.RPKI.RP.rcynic index 2830ea29..a7de376f 100644 --- a/doc/doc.RPKI.RP.rcynic +++ b/doc/doc.RPKI.RP.rcynic @@ -553,148 +553,3 @@ Usage: $ validation_status rcynic.xml $ validation_status rcynic.xml | fgrep rpki.misbehaving.org $ validation_status rcynic.xml | fgrep object_rejected - -***** Running rcynic chrooted ***** - -This is an attempt to describe the process of setting up rcynic in a chrooted -environment. The installation scripts that ship with rcynic attempt to do this -automatically for the platforms we support, but the process is somewhat -finicky, so some explanation seems in order. If you're running on one of the -supported platforms, the following steps may be handled for you by the -Makefiles, but you may still want to understand what all this is trying to do. - -rcynic itself does not include any direct support for running chrooted, but is -designed to be (relatively) easy to run in a chroot jail. Here's how. - -You'll either need staticly linked copies of rcynic and rsync, or you'll need -to figure out which shared libraries these programs need (try using the "ldd" -command). Here we assume staticly linked binaries, because that's simpler, but -be warned that statically linked binaries are not even possible on some -platforms, whether due to concious decisions on the part of operating system -vendors or due to hidden use of dynamic loading by other libraries at runtime. - -You'll need a chroot wrapper program. Your platform may already have one -(FreeBSD does -- /usr/sbin/chroot), but if you don't, you can download Wietse -Venema's "chrootuid" program from ftp://ftp.porcupine.org/pub/security/ -chrootuid1.3.tar.gz. - - Warning - The chroot program included in at least some GNU/Linux distributions is - not adaquate to this task. You need a wrapper that knows how to drop - privileges after performing the chroot() operation itself. If in doubt, - use chrootuid. - -Unfortunately, the precise details of setting up a proper chroot jail vary -wildly from one system to another, so the following instructions will likely -not be a precise match for the preferred way of doing this on any particular -platform. We have sample scripts that do the right thing for FreeBSD, feel free -to contribute such scripts for other platforms. - - 1. Build the static binaries. You might want to test them at this stage too, - although you can defer that until after you've got the jail built. - 2. Create a userid under which to run rcynic. Here we'll assume that you've - created a user "rcynic", whose default group is also named "rcynic". Do - not add any other userids to the rcynic group unless you really know what - you are doing. - 3. Build the jail. You'll need, at minimum, a directory in which to put the - binaries, a subdirectory tree that's writable by the userid which will be - running rcynic and rsync, your trust anchors, and whatever device inodes - the various libraries need on your system. Most likely the devices that - matter will be /dev/null, /dev/random,a nd /dev/urandom; if you're running - a FreeBSD system with devfs, you do this by mounting and configuring a - devfs instance in the jail, on other platforms you probably use the mknod - program or something. - - Important - Other than the directories that you want rcynic and rsync to be able to - modify, nothing in the initial jail setup should be writable by the - rcynic userid. In particular, rcynic and rsync should not be allowed to - modify: their own binary images, any of the configuration files, or your - trust anchors. It's simplest just to have root own all the files and - directories that rcynic and rsync are not allowed to modify, and make - sure that the permissions for all of those directories and files make - them writable only by root. - -Sample jail tree, assuming that we're putting all of this under /var/rcynic: - - $ mkdir /var/rcynic - $ mkdir /var/rcynic/bin - $ mkdir /var/rcynic/data - $ mkdir /var/rcynic/dev - $ mkdir /var/rcynic/etc - $ mkdir /var/rcynic/etc/trust-anchors - -Copy your trust anchors into /var/rcynic/etc/trust-anchors. - -Copy the staticly linked rcynic and rsync into /var/rcynic/bin. - -Copy /etc/resolv.conf and /etc/localtime (if it exists) into /var/rcynic/etc. - -Write an rcynic configuration file as /var/rcynic/etc/rcynic.conf (path names -in this file must match the jail setup, more below). - - $ chmod -R go-w /var/rcynic - $ chown -R root:wheel /var/rcynic - $ chown -R rcynic:rcynic /var/rcynic/data - -If you're using devfs, arrange for it to be mounted at /var/rcynic/dev; -otherwise, create whatever device inodes you need in /var/rcynic/dev and make -sure that they have sane permissions (copying whatever permissions are used in -your system /dev directory should suffice). - -rcynic.conf to match this configuration: - - [rcynic] - - trust-anchor-locator.1 = /etc/trust-anchors/ta-1.tal - trust-anchor-locator.2 = /etc/trust-anchors/ta-2.tal - trust-anchor-locator.3 = /etc/trust-anchors/ta-3.tal - - rsync-program = /bin/rsync - authenticated = /data/authenticated - unauthenticated = /data/unauthenticated - -Once you've got all this set up, you're ready to try running rcynic in the -jail. Try it from the command line first, then if that works, you should be -able to run it under cron. - -Note: chroot, chrootuid, and other programs of this type are usually intended -to be run by root, and should not be setuid programs unless you really know -what you are doing. - -Sample command line: - - $ /usr/local/bin/chrootuid /var/rcynic rcynic /bin/rcynic -s -c /etc/ - rcynic.conf - -Note that we use absolute pathnames everywhere. This is not an accident. -Programs running in jails under cron should not make assumptions about the -current working directory or environment variable settings, and programs -running in chroot jails would need different PATH settings anyway. Best just to -specify everything. - -**** Building static binaries **** - -On FreeBSD, building a staticly linked rsync is easy: just set the environment -variable LDFLAGS='-static' before building the rsync port and the right thing -will happen. Since this is really just GNU configure picking up the environment -variable, the same trick should work on other platforms...except that some -compilers don't support -static, and some platforms are missing some or all of -the non-shared libraries you'd need to link the resulting binary. - -For simplicity, we've taken the same approach with rcynic, so - - $ make LDFLAGS='-static' - -works. This isn't necessary on platforms where we know that static linking -works -- the default is static linking where supported. - -**** syslog from chrooted environment **** - -Depending on your syslogd configuration, syslog may not work properly with -rcynic in a chroot jail. On FreeBSD, the easiest way to fix this is to add the -following lines to /etc/rc.conf: - - altlog_proglist="named rcynic" - rcynic_chrootdir="/var/rcynic" - rcynic_enable="YES" diff --git a/doc/doc.RPKI.RP.rcynicChroot b/doc/doc.RPKI.RP.rcynicChroot new file mode 100644 index 00000000..a07dd357 --- /dev/null +++ b/doc/doc.RPKI.RP.rcynicChroot @@ -0,0 +1,169 @@ +****** Running rcynic chrooted ****** + +This is an attempt to describe the process of setting up rcynic in a chrooted +environment. The installation scripts that ship with rcynic attempt to do this +automatically when requested for the platforms we support, but the process is +somewhat finicky, so some explanation seems in order. If you're running on one +of the supported platforms, the following steps may be handled for you by the +Makefiles, but you may still want to understand what all this is trying to do. + +rcynic itself does not include any direct support for running chrooted, but is +designed to be (relatively) easy to run in a chroot jail. + +To enable chroot support during installation, you should install from source +and use the --enable-rcynic-jail option to ./configure. + +rcynic-cron includes support for running chrooted. To use it, specify the -- +chroot option on rcynic-cron's command line. This will cause rcynic-cron to run +rcynic in the chrooted environment. Note that, in order for this to work, +rcynic-cron itself must run as root, since only root can issue the chroot() +system call. When run as root, rcynic-cron takes care of changing the user ID +of each process it starts to the unprivileged "rcynic" user. + +***** Creating the chroot jail environment ***** + +By far the most tedious and finicky part of setting up rcynic to run in a +chroot jail is setting the jail itself. The underlying principal is simple and +obvious: a process running in the jail can't use files outside the jail. The +difficulty is that the list of files that needs to be in the jail is system- +dependent, can be rather long, and sometimes can only be discovered by trial +and error. + +You'll either need staticly linked copies of rcynic and rsync, or you'll need +to figure out which shared libraries these programs need (try using the "ldd" +command). Here we assume staticly linked binaries, because that's simpler, but +be warned that statically linked binaries are not even possible on some +platforms, whether due to concious decisions on the part of operating system +vendors or due to hidden use of dynamic loading by other libraries at runtime. +Once again, the Makefiles attempt to do the correct thing for your environment +if they know what it is, but they might get it wrong. + +You'll need a chroot wrapper program. As mentioned above, rcynic-cron can act +as that wrapper program; if this works for you, we recommend it, because it +works the same way on all platforms and doesn't require additional external +programs. Otherwise, you'll have to find a suitable wrapper program. Your +platform may already have one (FreeBSD does -- /usr/sbin/chroot), but if you +don't, you can download Wietse Venema's "chrootuid" program from ftp:// +ftp.porcupine.org/pub/security/chrootuid1.3.tar.gz. + + Warning + The chroot program included in at least some GNU/Linux distributions is + not adaquate to this task. You need a wrapper that knows how to drop + privileges after performing the chroot() operation itself. If in doubt, + use chrootuid. + +Unfortunately, the precise details of setting up a proper chroot jail vary +wildly from one system to another, so the following instructions may not be a +precise match for the preferred way of doing this on your platform. Please feel +free to contribute scripts for other platforms. + + 1. Build the static binaries. You might want to test them at this stage too, + although you can defer that until after you've got the jail built. + 2. Create a userid under which to run rcynic. Here we'll assume that's a user + named "rcynic", whose default group is also named "rcynic". Do not add any + other userids to the rcynic group unless you really know what you are + doing. + 3. Build the jail. You'll need, at minimum, a directory in which to put the + binaries, a subdirectory tree that's writable by the userid which will be + running rcynic and rsync, your trust anchors, and whatever device inodes + the various libraries need on your system. Most likely the devices that + matter will be /dev/null, /dev/random, and /dev/urandom; if you're running + a FreeBSD system with devfs, you do this by mounting and configuring a + devfs instance in the jail, on other platforms you probably use the mknod + program or something similar. + + Important + Other than the directories that you want rcynic and rsync to be able to + modify, nothing in the initial jail setup should be writable by the + rcynic userid. In particular, rcynic and rsync should not be allowed to + modify: their own binary images, any of the configuration files, or your + trust anchors. It's simplest just to have root own all the files and + directories that rcynic and rsync are not allowed to modify, and make + sure that the permissions for all of those directories and files make + them writable only by root. + +Sample jail tree, assuming that we're putting all of this under /var/rcynic: + + $ mkdir /var/rcynic + $ mkdir /var/rcynic/bin + $ mkdir /var/rcynic/data + $ mkdir /var/rcynic/dev + $ mkdir /var/rcynic/etc + $ mkdir /var/rcynic/etc/trust-anchors + +Copy your trust anchors into /var/rcynic/etc/trust-anchors. + +Copy the staticly linked rcynic and rsync into /var/rcynic/bin. + +Copy /etc/resolv.conf and /etc/localtime (if it exists) into /var/rcynic/etc. + +Write an rcynic configuration file as /var/rcynic/etc/rcynic.conf. Path names +in this file must match the jail setup, more on this below. + + $ chmod -R go-w /var/rcynic + $ chown -R root:wheel /var/rcynic + $ chown -R rcynic:rcynic /var/rcynic/data + +If you're using devfs, arrange for it to be mounted at /var/rcynic/dev; +otherwise, create whatever device inodes you need in /var/rcynic/dev and make +sure that they have sane permissions (copying whatever permissions are used in +your system /dev directory should suffice). + +rcynic.conf to match this configuration: + + [rcynic] + + rsync-program = /bin/rsync + authenticated = /data/authenticated + unauthenticated = /data/unauthenticated + xml-summary = /data/rcynic.xml + trust-anchor-directory = /etc/trust-anchors + +Once you've got all this set up, you're ready to try running rcynic in the +jail. Try it from the command line first, then if that works, you should be +able to run it under cron. + +Note: chroot, chrootuid, and other programs of this type are usually intended +to be run by root, and should not be setuid programs unless you really know +what you are doing. + +Sample command line: + + $ /usr/local/bin/chrootuid /var/rcynic rcynic /bin/rcynic -s -c /etc/ + rcynic.conf + +Note that we use absolute pathnames everywhere. This is not an accident. +Programs running in jails under cron should not make assumptions about the +current working directory or environment variable settings, and programs +running in chroot jails would need different PATH settings anyway. Best just to +specify everything. + +**** Building static binaries **** + +On FreeBSD, building a staticly linked rsync is easy: one just sets the +environment variable LDFLAGS='-static' before building rsync and the right +thing will happen. Since this is really just GNU configure picking up the +environment variable, the same trick should work on other platforms...except +that some compilers don't support -static, and some platforms are missing some +or all of the non-shared libraries you'd need to link the resulting binary. + +For simplicity, we've taken the same approach with rcynic, so + + $ make LDFLAGS='-static' + +works. This isn't necessary on platforms where we know that static linking +works -- the default is static linking where supported. + +**** syslog from chrooted environment **** + +Depending on how the syslog() library call and the syslog daemon (syslogd, +rsyslogd, ...) are implemented on your platform, syslog may not work properly +with rcynic in a chroot jail. On FreeBSD, the easiest way to fix this is to add +the following lines to /etc/rc.conf: + + altlog_proglist="named rcynic" + rcynic_chrootdir="/var/rcynic" + rcynic_enable="YES" + +This tells syslogd to listen on an additional PF_UNIX socket within rcynic's +chroot jail. diff --git a/doc/doc.RPKI.RP.rpki-rtr b/doc/doc.RPKI.RP.rpki-rtr index 810c3bdd..ee7bc55b 100644 --- a/doc/doc.RPKI.RP.rpki-rtr +++ b/doc/doc.RPKI.RP.rpki-rtr @@ -6,44 +6,47 @@ 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: +To use rtr-origin, you need to do two things beyond just running rcynic: - 1. You need to set up post-processing of rcynic's output into the data files - used by rtr-origin, and + 1. You need to post-process rcynic's output into the data files used by rtr- + origin. The rcynic-cron script handles this automatically, so the default + installation should already be taking care of this for you. 2. You need to set up a listener for the rtr-origin server, using the - generated data files. + generated data files. The platform-specific packages for FreeBSD and + Ubuntu automatically set up a plain TCP listener, but you will have to do + something on other platforms, or if you're using a transport protocol + other than plain TCP. ***** 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. +rtr-origin's --cronjob mode handles this computation. 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. +you're already running to run rcynic. As mentioned above, if you're running the +rcynic-cron script, this is already being done for you automatically, so you +don't need to do anything. If you've written your own cron script, you'll need +to add something like this to your script: + + cd /var/rcynic/rpki-rtr + /usr/local/bin/rtr-origin --cronjob /var/rcynic/data/authenticated + +In --cronjob mode, rtr-origin, needs write access to a directory where it can +store pre-digested versions of the data it pulls from rcynic. In the example +above, the directory /var/rcynic/rpki-rtr should be writable by the user ID +that is executing the cron script. 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. +which you run it, hence the cd command shown above. -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. +You should make sure that rtr-origin --cronjob 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 ***** @@ -54,8 +57,7 @@ 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. +reason). You may want to set up a separate UNIX userid for this purpose. --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 @@ -63,7 +65,7 @@ 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. +one for running under inetd on FreeBSD, the other for running under sshd. **** Running rtr-origin --server under inetd **** @@ -86,7 +88,7 @@ To run under inetd, you need to: 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 + server /var/rcynic/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 @@ -114,11 +116,11 @@ To run rtr-origin under sshd, you need 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 + rcynic/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/ + the example values given above, this would be /var/rcynic/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 @@ -131,7 +133,7 @@ To run rtr-origin under sshd, you need to: authorized_keys file regardless of what other user accounts might exist on the machine: - AuthorizedKeysFile /var/rpki-rtr/.ssh/authorized_keys + AuthorizedKeysFile /var/rcynic/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 diff --git a/doc/manual.pdf b/doc/manual.pdf Binary files differindex 41de6c56..9e8eb470 100644 --- a/doc/manual.pdf +++ b/doc/manual.pdf |