@PACKAGE_LONGNAME@ Installation and Usage Manual Version @PACKAGE_VERSION@
=============================================================================== Table of Contents
===============================================================================
This document describes how to install and use the Relying Party Security Technology for Internet Routing (RPSTIR, pronounced rip-ster) software by Raytheon BBN Technologies. Note that various files may refer to this software by its old name, RPKI.
Section 2 describes how to install that software, including its dependencies.
Section 3 provides a quick-start guide on how to get your system running.
Appendix A provides troubleshooting tips for some common problems.
===============================================================================
The RPKI software is distributed as source code that should be built using the GNU build tools on Linux/Unix. After reading this section, you will know: . How to install and configure the prerequisites. . How to build the @PACKAGE_NAME@ software. . How to set up a user with the correct environment. . How to validate the installation. We assume that you can operate your system's package manager, as well as build packages from source and do minor edits on Makefiles.
2.1 Prerequisites
When installing prerequisites from your operating system's package manager, you may need to look for a -dev or -devel version of each package. These versions generally contain header files that are needed to build @PACKAGE_NAME@.
2.1.0 Version Requirements OpenSSL (Section 2.1.2) at least @MIN_OPENSSL_VERSION@ MySQL (Section 2.1.3) at least @MIN_MYSQL_VERSION@ ODBC mySql Connector (Section 2.1.3) at least @MIN_MYSQL_ODBC_VERSION@ rsync (Section 2.1.5) at least @MIN_RSYNC_VERSION@ Python (Section 2.1.6) at least @MIN_PYTHON_VERSION@ patch (Section 2.5)
2.1.1 User Account
You must establish a user account from which you can build and run @PACKAGE_NAME@. While the full environment setup is detailed in section 2.3, the basic user should be created now so that you can set and test environment variables. It is not necessary, but recommended that the user is the only user in their primary group.
For the rest of this document, commands starting with $' should be run as this user and commands starting with#' should be run as root. If neither is
specified, the command should be run as @PACKAGE_NAME@'s user.
2.1.2 OpenSSL
You must build OpenSSL from source in order to enable support for RFC3779 X.509v3 extensions. Download the latest source code (at least version @MIN_OPENSSL_VERSION@) from http://www.openssl.org. We recommend the default installation target directory /usr/local/ssl. As of version 1.0.1e, the steps were:
$ ./config shared enable-rfc3779
$ make depend
$ make
$ make test
# make installIn addition, some scripts invoke the OpenSSL executable from the
shell. Modify your user's PATH such that which openssl points to
the custom-compiled binary that supports RFC 3779 extensions. This can
typically be done by adding a line like the below to the user's ~/.bashrc
file or another file that's automatically loaded by the shell.
export PATH="/usr/local/ssl/bin:$PATH"
2.1.3 MySQL and ODBC
Install unixODBC from your operating system's package manager or http://www.unixodbc.org/. iODBC is also supported, but unixodbc is recommended. Install the MySQL database server, client, and client libraries, at least version @MIN_MYSQL_VERSION@, from the package manager or http://mysql.org. Install the MySQL Connector/ODBC driver, at least version @MIN_MYSQL_ODBC_VERSION@, from the package manager or mysql.org.
Configure MySQL. First, secure the initial MySQL accounts, which includes setting a root password (see MySQL 5.1 manual, section 2.13.2). Then set up a database user and database(s) for @PACKAGE_NAME@. If you want to run the self-tests, it is recommended to create a separate database for testing than for production use. If you don't want to run the self-tests, only one database is needed. For example, the following creates a root password, then sets up a user with username "@PACKAGE_NAME@", password "bbn", and access to the databases named "@PACKAGE_NAME@" and "@PACKAGE_NAME@_test":
$ mysql -u root
mysql> SELECT Host, User FROM mysql.user; /* view all accounts */
mysql> SET PASSWORD FOR 'root'@'127.0.0.1' = PASSWORD('rootpass');
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('rootpass');
mysql> SET PASSWORD FOR 'root'@'<myhostname>' = PASSWORD('rootpass');
mysql> CREATE USER '@PACKAGE_NAME@'@'localhost' IDENTIFIED BY 'bbn';
mysql> CREATE DATABASE @PACKAGE_NAME@;
mysql> GRANT ALL PRIVILEGES ON @PACKAGE_NAME@.* TO '@PACKAGE_NAME@'@'localhost';
mysql> CREATE DATABASE @PACKAGE_NAME@_test;
mysql> GRANT ALL PRIVILEGES ON @PACKAGE_NAME@_test.* TO '@PACKAGE_NAME@'@'localhost';Configure the Connector/ODBC driver. First, locate your system ODBC drivers and data sources configuration files. For example:
$ odbcinst -j unixODBC 2.2.11 DRIVERS............: /usr/local/etc/odbcinst.ini SYSTEM DATA SOURCES: /usr/local/etc/odbc.ini USER DATA SOURCES..: /home/achi/.odbc.ini
Some systems provide example odbcinst.ini files. For example, Ubuntu's libmyodbc package provides /usr/share/libmyodbc/odbcinst.ini. If your system provides a suitable file, use it to fill in odbcinst.ini. Otherwise, you can use this as an example starting point for odbcinst.ini:
; Sample /usr/local/etc/odbcinst.ini
[myodbcConn] Description = MySQL odbc driver for Linux & Win32 Driver = /usr/local/lib/libmyodbc3.so ; could also be called libmyodbc.so Setup = /usr/local/lib/libmyodbc3S.so ; could also be called libmyodbcS.so or libodbcmyS.so UsageCount = 1
Then edit odbc.ini to set up a couple of system data sources. This is slightly confusing: the user, password, and database name are actually ignored because they will be overridden by @PACKAGE_NAME@. However, depending on whether your database user has a password, in future steps below you will need to remember to set your DatabaseDSN configuration option to choose the DSN that is expecting a password (e.g. "myodbc") or no password (e.g. "myodbc-np"). Here is an example of a working odbc.ini that corresponds to the odbcinst.ini above:
; ; odbc.ini configuration for Connector/ODBC and Connector/ODBC 3.51 drivers ; /usr/local/etc/odbc.ini ;
[ODBC Data Sources] myodbc = {MyODBC 3.51 Driver DSN} myodbc-np = {MyODBC 3.51 Driver DSN for users without password}
[myodbc] Driver = myodbcConn Description = Connector/ODBC 3.51 Driver DSN SERVER = localhost PORT = USER = arbitraryuser Password = arbitrarypassword Database = arbitrarydbname OPTION = 3 SOCKET =
You may also choose to set up user-specific $HOME/.odbc.ini file if you need special DSN settings per user. However, this is not required for successful operation of the RPKI software.
2.1.4 cryptlib
Install Peter Gutmann's cryptlib, currently available at http://www.cs.auckland.ac.nz/~pgut001/cryptlib. When compiling on *nix, it may be necessary to unzip in text mode to ensure that line endings are correct. Ensure that both the library itself and its include files are in accessible locations. For example, it may be necessary to manually copy libcl.so to /usr/local/lib and cryptlib.h to /usr/local/include. To install cryptlib 3.4.2 (for example):
$ wget --passive ftp://ftp.franken.de/pub/crypt/cryptlib/cl342.zip $ mkdir cryptlib $ cd cryptlib $ unzip -a ../cl342.zip # -a enables text-mode $ make shared # create libcl.so, not libcl.a $ su
On FreeBSD, cryptlib can be obtained one of two ways: (1) using the package system by issuing the command pkg_add -r cryptlib, or (2) using the ports system by issuing the command make search name="cryptlib" from the /usr/ports directory.
There seem to be some problems with compiling cryptlib on Linux machines. You may need to modify some files to get it to build cleanly. Also note that the self-test code (make testlib; ./testlib) fails on at least FreeBSD and Linux. We do not currently think that this is cause for concern.
2.1.5 rsync
Your rsync should be at least version @MIN_RSYNC_VERSION@, as earlier versions do not necessarily support the necessary flags. Check your version with rsync --version, and install from rsync.samba.org. We recommend the latest version due to security and bug fixes.
2.1.6 Python
Install python, at least version @MIN_PYTHON_VERSION@. Python is likely available in your operating system's package manager and is also available at http://python.org/download/.
2.1.7 netcat
Netcat comes preinstalled with many operating systems. If you do not already have the command nc, install netcat from your package manager or http://netcat.sourceforge.net/.
2.1.8 cURL
cURL also comes preinstalled with many operating systems. If the command curl is not already present, install it from your package manager or http://curl.haxx.se/.
2.1.9 Syslog
A syslog daemon is almost definitely already installed. However, on some systems syslog has poor performance by default. See http://stackoverflow.com/questions/208098/can-syslog-performance-be-improved for more information. If you're ok with the chance of losing some log messages if the system crashes, consider configuring your syslog daemon to not synchronize log files after each log message.
2.2 @PACKAGE_NAME_UC@ Software
@PACKAGE_NAME_UC@ is distributed as source code that should be built using the GNU build tools on Linux/Unix.
2.2.1 Unpack the Source Code
@PACKAGE_NAME_UC@ will have been delivered to you as a gzip-ed tarball named @PACKAGE_TARNAME@-@PACKAGE_VERSION@.tar.gz. Extract the file using:
$ tar xvzpf @PACKAGE_TARNAME@-@PACKAGE_VERSION@.tar.gzThis will create a directory named @PACKAGE_TARNAME@-@PACKAGE_VERSION@ which will contain various subdirectories.
Alternatively, you can get @PACKAGE_NAME@ from git if you want the latest version (which may or may not be particularly stable). In addition to the above prerequisites, you'll need to install git (http://git-scm.com/), automake (http://www.gnu.org/software/automake/), and autoconf (http://www.gnu.org/software/autoconf/). Then run the below commands:
$ git clone https://github.com/bgpsecurity/rpstir.git
$ cd rpstir
$ ./autogen.sh2.2.2 Configure
@PACKAGE_NAME_UC@ uses autoconf to generate its Makefiles. On many systems, it will suffice to run ./configure. However, the following options may be useful.
Optional Packages: --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) --with-ssl-include Path to openssl library install location: Defaults to /usr/local/ssl/include --with-ssl-lib Path to openssl library install location: Defaults to /usr/local/ssl/lib --with-cryptlib-include Path to cryptlib install location: Defaults to /usr/local/include --with-odbc-include Path to unixodbc include files: Defaults to /usr/local/include --with-cryptlib-lib Path to cryptlib install location: Defaults to /usr/local/lib --with-odbc-lib Path to unixODBC install location: Defaults to /usr/local/lib
In addition, GNU make has the ability to dramatically reduce its output. If you are using GNU make, then you have the option to use
$ ./configure --enable-silent-rules [other options]
which will give much shorter compilation/linking notifications.
The rpki-rtr code currently only compiles under gcc. If you have multiple compilers installed, add the option "CC=gcc" to ./configure.
2.2.3 Build the Executables
Once the configure script has generated all of the Makefiles, build the executables by issuing "make" in the top-level source directory.
2.3 @PACKAGE_NAME_UC@ User Account
Establish a user account from which to run @PACKAGE_NAME@. This provides a place to put the configuration file and prevent other users from reading sensitive information in it. It also provides a place, ~/.ssh/authorized_keys, to put all the RPKI-RTR clients' public keys to allow SSH login.
If you're installing to a non-standard location, add the bin directoy to the user's $PATH.
2.3.1 Self-Test Configuration File
@PACKAGE_NAME_UC@ uses two different configuration files, one for normal operations and one for the self tests. This step sets up the configuration file for the self-tests only. If you don't plan to run the self-tests, you can skip this section.
Copy etc/test.conf to ~/.@PACKAGE_NAME@.test.conf and make it readable only by the owner because it will contain a database password:
$ cp etc/test.conf ~/.@PACKAGE_NAME@.test.conf $ chmod 600 ~/.@PACKAGE_NAME@.test.conf
Open ~/.@PACKAGE_NAME@.test.conf in an editor, read the comments, and edit the file as directed by the comments.
NOTE: This file has database options that are homologous to options in the system-wide configuration file that you'll set up later. If you use the same database in both files, the self-tests will overwrite any data you keep in your production database. It is strongly recommended to use a different database for testing than for production use.
2.4 SSH Subsystem (optional)
If you plan to use the rpki-rtr server as an SSH subsystem, you will need to run @PACKAGE_NAME@-rpki-rtr-daemon and set up an ssh subsystem to connect to rtrd on localhost. The netcat program, nc(1), is recommended for the ssh subsystem. There are different versions of netcat, so read its manpage for caveats before setting it up as a subsystem. In particular, read the "-q" option's description, if your version of netcat has a "-q" option, to prevent runaway nc processes when clients disconnect. Edit the /etc/ssh/sshd_config file to contain the below line, modified for the options you want to pass to netcat:
Subsystem rpki-rtr nc
2.5 Self Test
If you didn't create the configuration files in step 2.3.1, go back and do that now. Some of the self tests won't work without the test configuration file.
It's necessary to create the VRS cache directory before run the self-test.
/usr/local/var/cache/@PACKAGE_NAME@-tmp /usr/local/var/cache/@PACKAGE_NAME@-tmp /usr/local/var/cache/@PACKAGE_NAME@-tmpTo perform a basic validation of your install, run the self-test target by issuing the command below. The self-tests do not support concurrent operation, so do not try to run make with more than one simultaneous job (i.e., do not pass the -jN option to make).
$ make check
If all tests pass, you will see a message indicating success.
If you have valgrind installed, you can run some tests under valgrind by running the command:
$ make check CHECKTOOL=valgrind
2.6 Installation
As root, run "make install" to install @PACKAGE_NAME@ on the system.
By default this will install various binaries to /usr/local/bin, which should be in the $PATH environment variable. Additional binaries, which should only be used internally or by experts, are in /usr/local/libexec/@PACKAGE_NAME@. Documentation, example configuration, and example trust anchor locators are installed in /usr/local/share/doc/@PACKAGE_NAME@. Some internal data is installed to /usr/local/share/@PACKAGE_NAME@. In the next step, you'll manually create cache and log directories.
2.7 Post-Installation Procedures
If this is the first time you've installed @PACKAGE_NAME@ (i.e. if this is not an upgrade), there are some initialization steps.
First, create the system-wide configuration directory and file. The system-wide configuration directory is /usr/local/etc/@PACKAGE_NAME@ by default. If you changed the value of ${sysconfdir}, use ${sysconfdir}/@PACKAGE_NAME@ instead. Files in the configuration directory should be readable only by the @PACKAGE_NAME@ user and root. After creating the directory, create a file @PACKAGE_NAME@.conf in it. There's a sample file that's in /usr/local/share/doc/@PACKAGE_NAME@/examples/@PACKAGE_NAME@.conf by default that you can use as a starting point. Assuming everything is in default locations and the user you created in step 2.1.1 is @PACKAGE_NAME@ with group @PACKAGE_NAME@:
Then open the configuration file you just created in an editor, read the comments, and edit the file as directed by the comments.
Later on, if you want to test configuration changes before changing the system-wide configuration, you can make a new configuration file and use it temporarily by setting $@CONFIG_ENV_VAR@, for example:
$ @CONFIG_ENV_VAR@=path/to/foo.conf path/to/executable
In the configuration file you just created, find the parameters RPKICacheDir and LogDir. Both of these directories, and ${localstatedir}/lib/@PACKAGE_NAME@, should be created and the user from step 2.1.1 should have full access to these directories. For example, if the directories are set to their defaults and the username is @PACKAGE_NAME@ in group @PACKAGE_NAME@:
/usr/local/var/cache/@PACKAGE_NAME@ \
/usr/local/var/lib/@PACKAGE_NAME@ \
/usr/local/var/log/@PACKAGE_NAME@ /usr/local/var/cache/@PACKAGE_NAME@ \
/usr/local/var/lib/@PACKAGE_NAME@ \
/usr/local/var/log/@PACKAGE_NAME@ /usr/local/var/cache/@PACKAGE_NAME@ \
/usr/local/var/lib/@PACKAGE_NAME@ \
/usr/local/var/log/@PACKAGE_NAME@Then run @PACKAGE_NAME@-initialize to set up the database:
$ @PACKAGE_NAME@-initialize -f # WARNING: This will delete any old data you
# Do not do this if you're upgrading
# and want to save your old data.2.8 Upgrading
Consider backing up your configuration and data before upgrading @PACKAGE_NAME@.
To upgrade @PACKAGE_NAME@, first upgrade the dependencies to the versions in section 2.1.0. Then compile (section 2.2) and install (section 2.6) @PACKAGE_NAME@. Run @PACKAGE_NAME@-upgrade with the version number of the previous release. For example, to upgrade from version 0.7, run:
$ @PACKAGE_NAME@-upgrade 0.7
2.9 Firewall
As part of @PACKAGE_NAME@'s normal operation, it fetches RPKI objects over rsync. Many of these objects contain links to additional RPKI objects, which @PACKAGE_NAME@ then attempts to fetch, recursively. If you plan to make the results of @PACKAGE_NAME@'s validation public and if your local network (or localhost) contains any confidential data available over rsync, you may want to set up a firewall to prevent @PACKAGE_NAME@ from downloading any data it shouldn't.
2.10 Run in Docker
The @PACKAGE_NAME@ can run in Docker, please refer to the handbook in doc/docker/Install_and_Run_Rpstir_in_Docker.txt
===============================================================================
3.1 Normal Operation
This section describes when and how to run each component of @PACKAGE_NAME@ as part of a relying party's normal operations. Cron jobs and init scripts are not included in this release, but this section should give the user enough information to create cron jobs or init scripts as appropriate.
3.1.1 Note About Cron Jobs
If you create cron jobs for @PACKAGE_NAME@, it is strongly recommended that you pick random numbers for the fixed parts of the cron job. For example, if you want to run @PACKAGE_NAME@ once per hour, pick a random number between 0 and 59 to use as the minute that @PACKAGE_NAME@ runs on every hour. Likewise, if you want to run once per day, pick a random minute between 0 and 59 and a random hour between 0 and 23. This should help spread out the load on the public RPKI servers.
3.1.2 @PACKAGE_NAME@-synchronize
@PACKAGE_NAME@-synchronize synchronizes the local cache with the global RPKI, or anything else pointed to by the configured trust anchor locators. It should be run regularly, for example by a cron job. The amount of time it takes to complete one run can vary, so experimentation is suggested before picking the frequency to run it.
3.1.3 @PACKAGE_NAME@-rpki-rtr-daemon
@PACKAGE_NAME@-rpki-rtr-daemon is @PACKAGE_NAME@'s rpki-rtr [rfc6810] server. If you plan to run an rpki-rtr server, this should be started on boot, e.g. from an init script or from rc.local. This program does not daemonize, but something like start-stop-daemon can be used.
3.1.4 @PACKAGE_NAME@-rpki-rtr-update
After @PACKAGE_NAME@-synchronize finishes, @PACKAGE_NAME@-rpki-rtr-update can update the rpki-rtr cache. If you plan to use the rpki-rtr server, you should call @PACKAGE_NAME@-rpki-rtr-update after each successful call to @PACKAGE_NAME@-synchronize. For example, the cron job command could be:
@PACKAGE_NAME@-synchronize && @PACKAGE_NAME@-rpki-rtr-update
3.2 Results and Analysis
This section describes some of your options for getting more information about @PACKAGE_NAME@'s operations (see previous section) or the state of the RPKI.
3.2.1 Validation Report (@PACKAGE_NAME@-results)
If you want an overview of @PACKAGE_NAME@'s cached view of the RPKI, you can use
@PACKAGE_NAME@-results
This should have some non-zero values for the validated objects if the @PACKAGE_NAME@-synchronize ran successfully.
At a basic level, every object is in one of three states: fully validated to a trust anchor, unknown, and definitely invalid. Valid objects are inserted in the database; unknown objects are potentially valid, so they are kept in the database; definitely invalid objects are not entered into the database.
The validation report generator (@PACKAGE_NAME@-results) searches the local cache and the database and summarizes the three categories as counts. In verbose mode, it also shows full paths to all invalid/unknown certifcates, thereby allowing the user to determine the offending rsync publication URI.
To see a list of options, run
$ @PACKAGE_NAME@-results --help
3.2.2 Query Client (@PACKAGE_NAME@-query)
This is the way to pull specific information out of the database and local repository. There are two basic modes.
The comprehensive query, indicated by the argument "-r", pulls all the
valid ROAs from the repository and outputs a set of BGP filters in
RPSL format specified by these ROAs. To send the output to a file
rather than the screen, include "-o
The informational query provides the user with a means to see what is
in the database without directly executing MySQL commands. The basic
informational query has the form
@PACKAGE_NAME@-query -t