****** Installation ****** This section of the manual is primarily about installing the code from source. If you're installing from a pre-built package, you may be able to skip ahead to next steps. 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 we've tried to keep this to a minimum. 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. Note that initial development of this code has been on FreeBSD, so installation will probably be easiest on FreeBSD. We do, however, test on other platforms, such as Fedora, Ubuntu, and MacOSX. ***** Prerequisites ***** Before attempting to build the tools from source, you need to install any missing prerequisites. If you're using one of the pre-built packages (including the FreeBSD ports framework), this should be handled automatically via the package dependencies, but if you run into trouble you may want to review this list to confirm that the right packages have been installed. Some of the relying party tools and most of the CA tools are written in Python. Note that the Python code requires Python version 2.5, 2.6, or 2.7. 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. Packages you will need: * If you're building from source, you will need a C compiler. gcc is fine, others such as Clang should also work. * http://www.python.org/, the Python interpreter, libraries, and sources. 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 the POW code later in the build process and the error message says something about the file "Python.h" being missing, this is almost certainly your problem. o FreeBSD: # /usr/ports/lang/python27 (python) o Ubuntu: # python # python-dev # python-setuptools * http://codespeak.net/lxml/, a Pythonic interface to the Gnome LibXML2 libraries. lxml in turn requires the LibXML2 C libraries; on some platforms, some of the LibXML2 utilities are packaged separately and may not be pulled in as dependencies. o FreeBSD: /usr/ports/devel/py-lxml (py27-lxml) o Fedora: python-lxml.i386 o Ubuntu: # python-lxml # libxml2-utils * http://www.mysql.com/, MySQL client and server. How these are packaged varies by platform, on some platforms the client and server are separate packages, on others they might be a single monolithic package, or installing the server might automatically install the client as a dependency. On MacOSX you might be best off installing a binary package for MySQL. The RPKI CA tools have been tested with MySQL 5.0, 5.1, and 5.5; they will probably work with any other reasonably recent version. o FreeBSD: # /usr/ports/databases/mysql55-server (mysql55-server) # /usr/ports/databases/mysql55-client (mysql55-client) o Ubuntu: # mysql-client # mysql-server * http://sourceforge.net/projects/mysql-python/, the Python "db" interface to MySQL. o FreeBSD: /usr/ports/databases/py-MySQLdb (py27-MySQLdb) o Fedora: MySQL-python.i386 o Ubuntu: python-mysqldb * http://www.djangoproject.com/, the Django web user interface toolkit. The GUI interface to the CA tools requires this. Django 1.4 is required. Django 1.5 is currently not supported. o FreeBSD: /usr/ports/www/py-django (py27-django) o Ubuntu: Do not use the python-django package (Django 1.3.1) in 12.04 LTS, as it is known not to work. Instead, install a recent version using easy_install or pip: $ sudo pip install django==1.4.5 * http://vobject.skyhouseconsulting.com/, a Python library for parsing VCards. The GUI uses this to parse the payload of RPKI Ghostbuster objects. o FreeBSD: /usr/ports/deskutils/py-vobject (py27-vobject) o Ubuntu: python-vobject * http://pyyaml.org/. Several of the test programs use PyYAML to parse a YAML description of a simulated allocation hierarchy to test. o FreeBSD: /usr/ports/devel/py-yaml (py27-yaml) o Ubuntu: python-yaml * http://xmlsoft.org/XSLT/. Some of the test code uses xsltproc, from the Gnome LibXSLT package. o FreeBSD: /usr/ports/textproc/libxslt (libxslt) o Ubuntu: xsltproc * http://www.rrdtool.org/. The relying party tools use this to generate graphics which you may find useful in monitoring the behavior of your validator. The rest of the software will work fine without rrdtool, you just won't be able to generate those graphics. o FreeBSD: /usr/ports/databases/rrdtool (rrdtool) o Ubuntu: rrdtool * http://www.freshports.org/www/mod_wsgi3/ If you intend to run the GUI with wsgi, its default configuration, you will need to install mod_wsgi v3 o FreeBSD: /usr/ports/www/mod_wsgi3 (app22-mod_wsgi) o Ubuntu: libapache2-mod-wsgi * http://south.aeracode.org/ Django South 0.7.6 or later. This tool is used to ease the pain of changes to the web portal database schema. o FreeBSD: /usr/ports/databases/py-south (py27-south) o Ubuntu: Do not use the python-django-south 0.7.3 package in 12.04 LTS, as it is known not to work. Instead, install a recent version using easy_install or pip: pip install South>=0.7.6 * ftp://ftp.porcupine.org/pub/security/chrootuid1.3.tar.gz or later. This isn't needed on all platforms, but on systems without a usable system chroot program, you'll need this if you're going to set up rcynic to run in a chroot jail (recommended). At present, all GNU/Linux systems will require this, because the chroot program, while present, is broken in mysterious ways on some of them and we haven't figured out a reliable autoconf test for the usable versions. o FreeBSD: not needed (but it's in /usr/ports/security/chrootuid if you really want it for some reason) o Ubuntu: chrootuid ***** Configure and build ***** Once you have the prerequesite packages installed, you should be able to build the toolkit. cd to the top-level directory in the distribution, run the configure script, then run "make": $ cd $top $ ./configure $ make This should automatically build everything, in the right order, including building a private copy of the OpenSSL libraries with the right options if necessary and linking the POW module against either the system OpenSSL libraries or the private OpenSSL libraries, as appopriate. 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 ***** 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 rpkid/tests/smoketest.setup.sql. The MySQL command line client is usually the easiest way to do this, eg: $ cd $top/rpkid $ mysql -u root -p