Secure Routing -- Protect Your Infrastructure

Installation Guide

1 Introduction
2 Platform Possibilities
3 rpki.net Software Installation
4 Next Steps
5 Full Table of Contents

1 Introduction

The rpki.net package contains implementations of the Relying-Party and Certification-Authority software. It may be installed from pre-built packages on a variety of systems, such as FreeBSD, Ubuntu Linux, and Debian Linux. It may be built from source on other systems, but this may entail some modifications on the part of the installer.

The rpki.net package is available on rpki.net.

This document describes installing rpki.net from the pre-built packages, as well as installing from source. There are also instructions for upgrading previously installed versions of rpki.net.

This document only discusses rpki.net installation and upgrades. System configuration is discussed in the RSI-EARS Step-By-Step Configuration Guide.

This document is prepared under Contract Number HSHQDC-14-C-B0035 for DHS S&T CSD

2 Platform Possibilities

The rpki.net documentation (on http://rpki.net) says that rpki.net may be installed from pre-built packages and run on the following platforms:

Ubuntu 12.04 LTS ("Precise Pangolin")
Ubuntu 14.04 ("Trusty Tahir")
Debian 7 ("Wheezy")
FreeBSD

On other platforms, rpki.net may be built and installed from source code. It may be built from source on these platforms, as well.

We have had the best success installing rpki.net on Ubuntu 14.04.1 using binary packages.

3 rpki.net Software Installation

This section describes installing both the rpki.net software. In addition to the rpki.net software, there are additional software packages upon which rpki.net relies; installation instructions for these additional, required packages are also given.

Software installation requires superuser access on the target machine.
Shell commands provided below assume a sh/bash shell.

3.1 Installing on Debian and Ubuntu Using APT Packages

Precompiled binary packages for Debian and Ubuntu are available from http://download.rpki.net using the Advanced Package Tools (APT). To use APT, you need to configure APT on your machine to know about the rpki.net APT repository. Once you have done this, you should be able to install and update the rpki.net packages like any other precompiled package.

3.1.1 Initial APT Setup

You should only need to perform these steps once for any particular machine. The second step consists of only one command. However, the particular command depends on the platform.

Add the GPG public key for this repository. This step is optional.

    $ wget -q -O - http://download.rpki.net/APT/apt-gpg-key.asc | sudo apt-key add -

Configure APT to use this repository.

Debian Wheezy

    $ sudo wget -q -O /etc/apt/sources.list.d/rpki.list http://download.rpki.net/APT/rpki.wheezy.list

Ubuntu Precise

    $ sudo wget -q -O /etc/apt/sources.list.d/rpki.list http://download.rpki.net/APT/rpki.precise.list

Ubuntu Trusty

    $ sudo wget -q -O /etc/apt/sources.list.d/rpki.list http://download.rpki.net/APT/rpki.trusty.list

3.1.2 Installation Using APT Tools

These instructions assume that you're using apt-get. Other APT tools, such as aptitude, should also work.

Update available packages.
```
    $ sudo apt-get update
```

Install the software.

    $ sudo apt-get install rpki-rp rpki-ca

If the rpki.net Web Portal will be used on a CA installation, then Apache must also be installed.
```
    $ sudo apt-get install apache2 libapache2-mod-wsgi
```
Customize the default rpki.conf for your environment as necessary. The full path for this configuration file is /etc/rpki.conf.
In particular, you must change the handle and rpkid_server_host configuration fields.
There are detailed instructions for customizing the rpki.conf file in the Configuration File Reference.
Whenever anything in rpki.conf is changed, you must restart the RPKI CA service for the changes to take effect.
```
    $ sudo service rpki-ca restart
```

3.1.3 Prerequisites for Debian and Ubuntu

The packages in the following table must be installed in order for the rpki.net software to work. Each package's name is given so that the installation may performed by the apt-get command.

A C compiler may be needed if any of the prerequisite packages must be built, rather than installed from a binary package. gcc and Clang are known to work.

Software Package	APT Name
Python 2.7	python python-dev python-setuptools python-pip (for Ubuntu installations)
LibXML2	python-lxml libxml2-utils
MySQL client	mysql-client
MySQL server	mysql-server
Python "db" interface	python-mysqldb
Django 1.4	Debian: py27-django Ubuntu: Install manually using sudo pip install django==1.4.5
VObject	python-vobject
PyYAML	python-yaml
xsltproc	xsltproc
RRDTool	rrdtool
Apache	Apache 2.2 or later
ssl	libssl0.9.8 or libssl1.0.0
wsgi	libapache2-mod-wsgi 3 or later
Django South 0.7.6	Debian: python-django-south Ubuntu: Install manually using sudo pip install South>=0.7.6

On some platforms the Python sources (in particular, the header files and libraries needed when building Python extensions) are in a separate "development" package; on other platforms they are all part of a single package. If you get compilation errors trying to build a the package and the error message says something about the file Python.h being missing, this is almost certainly your problem.

After completing the installation steps in this section, you have finished installation and may proceed to the Next Steps section. However, developers should consider installing the development tools, as described in the Developers Tools section.

3.2 Upgrading rpki.net Software on Debian and Ubuntu

After rpki.net has been installed as described above, software upgrades may be performed using the normal APT upgrade process. The following commands will upgrade all your packages:

    $ sudo apt-get update
    $ sudo apt-get upgrade

Alternatively, the following commands will only upgrade the rpki.net tools:

    $ sudo apt-get update
    $ sudo apt-get upgrade rpki-ca rpki-rp

If the rpki.net Web Portal will be used on a CA installation, the Apache packages may be upgraded with this command:

    $ sudo apt-get upgrade apache2 libapache2-mod-wsgi

3.3 Installing on FreeBSD Using Ports

The FreeBSD Ports system may be used to install the rpki.net software. This section describes how to configure the Ports system and install rpki.net using it.

3.3.1 Manual Installation

FreeBSD port skeletons must be downloaded in order to install the rpki.net software using the ports system. These skeletons are available from download.rpki.net.

Download the port skeletons manually and install from them. The following shell commands will install the rpki.net ports:

    for port in rpki-rp rpki-ca
    do
        fetch http://download.rpki.net/FreeBSD_Packages/${port}-port.tgz
        tar xf ${port}-port.tgz
        cd ${port}
        make install
        cd ..
        rm -rf ${port}
    done

If the rpki.net Web Portal will be used on a CA installation, the port skeletons can be downloaded and installed manually. The following shell commands will install the rpki.net ports:

    for port in apache22 mod_wsgi3
    do
        fetch http://download.rpki.net/FreeBSD_Packages/${port}-port.tgz
        tar xf ${port}-port.tgz
        cd ${port}
        make install
        cd ..
        rm -rf ${port}
    done

Customize the default rpki.conf for your environment as necessary. The full path for this configuration file is /etc/rpki.conf.
In particular, you must change the handle and rpkid_server_host configuration fields.
There are detailed instructions for customizing the rpki.conf file in the Configuration File Reference.
Whenever anything in rpki.conf is changed, you must restart the RPKI CA service for the changes to take effect.
```
    $ sudo service rpki-ca restart
```

3.3.2 Automated Download and Install with rpki-portmaster.sh

The rpki-portmaster.sh script may be used to automate the download steps given in the "Manual Installation" section.

Download rpki-portmaster.sh.

    $ fetch http://download.rpki.net/FreeBSD_Packages/rpki-portmaster.sh

Install (or upgrade) the rpki.net software.
```
    $ sh rpki-portmaster.sh
```
Customize the default rpki.conf for your environment as necessary. The full path for this configuration file is /etc/rpki.conf.
In particular, you must change the handle and rpkid_server_host configuration fields.
There are detailed instructions for customizing the rpki.conf file in the Configuration File Reference.
Whenever anything in rpki.conf is changed, you must restart the RPKI CA service for the changes to take effect.
```
    $ sudo service rpki-ca restart
```

3.3.3 Prerequisite Software Packages for FreeBSD

The packages in the following table must be installed in order for the rpki.net software to work. Each package's path and name are given so that the installation may performed by either the make command or a ports-specific tool that understands path names.

A C compiler is needed in order to build the prerequisite packages. gcc and Clang are known to work.

Software Package	Ports Path	Ports Name
Python 2.7	/usr/ports/lang/python27	python
LibXML2	/usr/ports/devel/py-lxml	py27-lxml
MySQL client	/usr/ports/databases/mysql55-client	mysql55-client
MySQL server	/usr/ports/databases/mysql55-server	mysql55-server
Python "db" interface	/usr/ports/databases/py-MySqldb	py27-MySQLdb
Django 1.4	/usr/ports/www/py-django	py27-django
VObject	/usr/ports/deskutils/py-vobject	py27-vobject
PyYAML	/usr/ports/devel/py-yaml	py27-yaml
xsltproc	/usr/ports/lib/libxslt	libxslt
RRDTool	/usr/ports/databases/rrdtool	rrdtool
Apache	/usr/ports/www/apache22	apache22
wsgi	/usr/ports/www/mod_wsgi3	app22-mod_wsgi
Django South 0.7.6	/usr/ports/databases/py-south	py27-south

After completing the installation steps in this section, you have finished installation and may proceed to the Next Steps
section. However, developers should consider installing the development tools, as described in the Developers Tools section.

3.4 Upgrading on FreeBSD

The FreeBSD Ports system may be used to install the rpki.net software. This section describes how to upgrade software previously installed with the Ports system.

3.4.1 Manual Upgrade

The FreeBSD ports system doesn't really understand upgrades. Consequently, manual upgrade of the rpki.net software requires similar steps to manual installation, but it uses the deinstall and reinstall operations instead of plain install.

Re-install the rpki.net ports.

    for port in rpki-rp rpki-ca
    do
        fetch http://download.rpki.net/FreeBSD_Packages/${port}-port.tgz
        tar xf ${port}-port.tgz
        cd ${port}
        make deinstall
        make reinstall
        cd ..
        rm -rf ${port}
    done

If the rpki.net Web Portal is used on a CA installation, the Apache-related ports may be re-installed using these shell commands:

    for port in apache22 mod_wsgi3
    do
        fetch http://download.rpki.net/FreeBSD_Packages/${port}-port.tgz
        tar xf ${port}-port.tgz
        cd ${port}
        make deinstall
        make reinstall
        cd ..
        rm -rf ${port}
    done

After an upgrade, you should check the newly-installed /usr/local/etc/rpki.conf.sample against your existing /usr/local/etc/rpki.conf in case any important options have changed. The rpki.net configuration options are generally stable between versions, with sane defaults provided where possible. However, if you've done much customization to your rpki.conf you must keep track of this.

3.4.2 Automated Upgrade with rpki-portupgrade.sh

The rpki-portupgrade.sh script may be used to automate the download steps given in the "Manual Upgrade" section.

Download rpki-portupgrade.sh.

  fetch http://download.rpki.net/FreeBSD_Packages/rpki-portupgrade.sh

Add information about the RPKI ports must be added to two variables in /usr/local/etc/pkgtools.conf before rpki-portupgrade.sh will know how to deal with these ports:
```
    EXTRA_CATEGORIES = [
        'rpki',
    ]

    ALT_INDEX = [
        ENV['PORTSDIR'] + '/INDEX.rpki',
    ]
```
Once these steps have been completed, rpki-portupgrade.sh can be executed to install or upgrade the RPKI code.
```
    sh rpki-portupgrade.sh
```
Customize the default rpki.conf for your environment as necessary. The full path for this configuration file is /etc/rpki.conf.
In particular, you must change the handle and rpkid_server_host configuration fields.
There are detailed instructions for customizing the rpki.conf file in the Configuration File Reference.
Whenever anything in rpki.conf is changed, you must restart the RPKI CA service for the changes to take effect.
```
    $ sudo service rpki-ca restart
```

3.5 Installing From Source Code

At present, the entire RPKI tools collection is a single source tree with a shared autoconf configuration. This may change in the future, but for now, this means that the build process is essentially the same regardless of which tools one wants to use. Some of the tools have dependencies on external packages, although an effort has been make to keep these dependencies to a minimum.

Before attempting to build the rpki.net software from source, you will need to install any missing prerequisites.

Most of the tools require an RFC-3779-aware version of the OpenSSL libraries. If necessary, the build process will generate its own private copy of the OpenSSL libraries for this purpose.

Other than OpenSSL, most of the Relying-Party tools are fairly self-contained. The CA tools have a few additional dependencies, described below.

Initial development of this code has been on FreeBSD, so installation will probably be easiest on FreeBSD. The software is tested on other platforms, such as Fedora, Ubuntu, Debian, and MacOSX.

3.5.1 Downloading the Source Code

It is recommended that subversion be used to obtain the source code. To download:

    $ svn checkout http://subvert-rpki.hactrn.net/trunk/

Code snapshots are also available from http://download.rpki.net/ as xz-compressed tarballs.

3.5.2 Prerequisites Packages when Installing from Source Code

This section discusses installing the prerequisite software packages. If your platform is Debian, Ubuntu, or FreeBSD, then you should consult the appropriate sections that describe installing prerequisites on those systems. If you are using a different platform, you should continue reading this section.

The packages in the following table must be installed in order for the rpki.net software to work. They must be installed prior to building the source code. Each package's location is given so that it may be consulted to determine how the package may be installed on your platform. On some platforms (particularly MacOSX) the simplest way to install some of the Python packages may be the easy_install or pip tools that comes with Python.

A C compiler may be needed if any of the prerequisite packages must be built, rather than installed from a binary package. gcc and Clang are known to work.

Software Package	Package Location
Python 2.7	http://www.python.org
LibXML2	http://codespeak.net/lxml
MySQL client	http://www.mysql.com
MySQL server	http://www.mysql.com
Python "db" interface	http://sourceforge.net/projects/mysql-python
Django 1.4	http:/www.djangoproject.com
VObject	http://vobject.skyhouseconsulting.com
PyYAML	http://pyyaml.org
xsltproc	http://xmlsoft.org/XSLT
RRDTool	http://www.rrdtool.org
Apache	http://httpd.apache.org
wsgi	http://www.freshports.org/www/mod_wsgi3
Django South 0.7.6	http://south.aeracode.org

3.5.3 Building the Source Code

Once you have the prerequisite packages installed, you should be able to build the toolkit. Go to the top-level directory (signified below as $top) in the distribution, run the ./configure script and then run make:

    $ cd $top
    $ ./configure
    $ make

This should automatically build everything, in the right order. A private copy of the OpenSSL libraries will be built with the proper options, if necessary, and linking the POW module against either the system OpenSSL libraries or the private OpenSSL libraries, as appropriate.

In theory, ./configure will complain about any required packages which might be missing.

If you don't intend to run any of the CA tools, you can simplify the build and installation process by telling ./configure that you only want to build the Relying-Party tools:

    $ cd $top
    $ ./configure --disable-ca-tools
    $ make

3.5.4 Testing the Build

Assuming the build stage completed without obvious errors, the next step is to run some basic regression tests.

Some of the tests for the CA tools require MySQL databases to store their data. To set up all the databases that the tests will need, run the SQL commands in ca/tests/smoketest.setup.sql. The MySQL command line client is usually the easiest way to do this.

    $ cd $top/ca
    $ mysql -u root -p < tests/smoketest.setup.sql

To run the tests, run make test:

    $ cd $top
    $ make test

To run a more extensive set of tests on the CA tool, run make all-tests in the ca/ directory:

    $ cd $top/ca
    $ make all-tests

Errors and problems should be apparent. For example, any Python backtraces in the output indicate a problem. If no errors are obvious, then your installation is should be okay.

3.5.5 Installing the Build

Assuming the build and test phases went well, you should be ready to install the code. The ./configure script attempts to figure out the "obvious" places to install the various programs for your platform. For example, binaries will be installed in /usr/local/bin or /usr/local/sbin. Also, Python modules will be installed using the standard Python distutils and should end up wherever your system puts locally installed Python libraries.

The RPKI validator, rcynic, is a special case. The install scripts may attempt to build a chroot jail and install rcynic in that environment. This is straightforward in FreeBSD, but somewhat more complicated on other systems. This complexity is primarily due to hidden dependencies on dynamic libraries.

To install the code, become root (e.g., su or sudo), then run make install:

  $ cd $top
  $ sudo make install

3.5.6 Developers Tools

There's a set of tools that only developers should need. These tools are only used when modifying schemas or regenerating the documentation. These tools are listed here for completeness, but most installations are likely to not need them.

http://www.doxygen.org/. Doxygen in turn pulls in several other packages, notably Graphviz, pdfLaTeX, and Ghostscript.
- FreeBSD: /usr/ports/devel/doxygen
- Debian: doxygen
- Ubuntu: doxygen (apt)
http://www.mbayer.de/html2text/. The documentation build process uses xsltproc and html2text to dump flat text versions of a few critical documentation pages.
- FreeBSD: /usr/ports/textproc/html2text
- Ubuntu: html2text (apt)
http://www.thaiopensource.com/relaxng/trang.html. Trang is used to convert RelaxNG schemas from the human-readable "compact" form to the XML form that LibXML2 understands. Trang in turn requires Java.
- FreeBSD: /usr/ports/textproc/trang
- Ubuntu: trang (apt)
http://search.cpan.org/dist/SQL-Translator/. SQL-Translator, also known as "SQL Fairy", includes code to parse an SQL schema and dump a description of it as Graphviz input. SQL Fairy in turn requires Perl.
- FreeBSD: /usr/ports/databases/p5-SQL-Translator
- Ubuntu: sqlfairy (apt)
http://www.easysw.com/htmldoc/. The documentation build process uses htmldoc to generate PDF from the project's Trac wiki.
- FreeBSD: /usr/ports/textproc/htmldoc
- Ubuntu: htmldoc (apt)

4 Next Steps

Once you've finished installing the code, you will need to configure it. System configuration is discussed in the RSI-EARS Step-By-Step Configuration Guide.

Since CAs are generally also Relying Parties (if only so that they can check the results of their own actions), you will generally want to start by configuring the Relying-Party tools, then configure the CA tools if you're planning to use them.

Sections of this document are derived or taken verbatim from Dragon Research Lab's RPKI Tools Manual.

Routing Security Step-by-Step Guide

Table of Contents