diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/doc.RPKI | 33 | ||||
| -rw-r--r-- | doc/doc.RPKI.Installation.FreeBSDPorts | 90 | ||||
| -rw-r--r-- | doc/doc.RPKI.Installation.FromSource | 277 | ||||
| -rw-r--r-- | doc/manual.pdf | bin | 730263 -> 757140 bytes |
4 files changed, 400 insertions, 0 deletions
diff --git a/doc/doc.RPKI b/doc/doc.RPKI index e69de29b..fd1a3bbe 100644 --- a/doc/doc.RPKI +++ b/doc/doc.RPKI @@ -0,0 +1,33 @@ +****** RPKI Tools Manual ****** + +This collection of tools implements both the production (CA) and relying party +(RP) sides of an RPKI environment. + +The Subversion repository for the entire project is available for (read-only) +anonymous access at http://subvert-rpki.hactrn.net/. + +If you just want to browse the code you might find the Trac source code browser +interface more convenient. + +***** Download and Install ***** + +Full source code is available, as are binary packages for a few platforms. + +See the installation instructions for how to download the code and install it +once you've downloaded it. + +***** Relying Party Tools ***** + +If you operate routers and want to use RPKI data to help secure them, you +should look at the relying party tools. + +***** CA Tools ***** + +If you control RPKI resources and need an engine let you request certificates, +issue ROAs, or issue certificates to other entities, you should look at the CA +tools. + +***** Thanks ***** + +This work was funded from 2006 through 2008 by ARIN, in collaboration with the +other Regional Internet Registries. Current work is funded by DHS. diff --git a/doc/doc.RPKI.Installation.FreeBSDPorts b/doc/doc.RPKI.Installation.FreeBSDPorts index e69de29b..34f924ec 100644 --- a/doc/doc.RPKI.Installation.FreeBSDPorts +++ b/doc/doc.RPKI.Installation.FreeBSDPorts @@ -0,0 +1,90 @@ +****** Installation Using FreeBSD Ports ****** + +Port skeletons are available for FreeBSD from download.rpki.net. To use these, +you need to download the port skeletons then run them using your favorite +FreeBSD port installation tool. + +***** Manual Download ***** + +To download the port skeletons manually and install from them, do something +like this: + + 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 + +After performing initial installation, you should customize the default +rpki.conf for your environment as necessary. In particular, you want to change +handle and rpkid_server_host. There are obsessively detailed instructions. + + emacs /usr/local/etc/rpki.conf + +Again, you want to change handle and rpkid_server_host at the minimum. + +To upgrade, you can perform almost the same steps, but the FreeBSD ports +system, which doesn't really know about upgrades, will require you to use the +deinstall and reinstall operations instead of plain install: + + 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 + +After an upgrade, you may want to 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. We generally try to keep options stable between +versions, and provide sane defaults where we can, but if you've done a lot of +customization to your rpki.conf you will want to keep track of this. + +***** Automated Download and Install with portmaster ***** + +There's a script you can use to automate the download steps above and perform +the updates using portmaster. First, download the script: + + fetch http://download.rpki.net/FreeBSD_Packages/rpki-portmaster.sh + +Then, to install or upgrade, just execute the script: + + sh rpki-portmaster.sh + +As with manual download (above) you should customize rpki.conf after initial +installation. + +***** Automated Download and Install with portupgrade ***** + +There's a script you can use to automate the download steps above and perform +the updates using portupgrade. First, download the script: + + fetch http://download.rpki.net/FreeBSD_Packages/rpki-portupgrade.sh + +Next, you will need to add information about the RPKI ports to two variables in +/usr/local/etc/pkgtools.conf before portupgrade will know how to deal with +these ports: + + EXTRA_CATEGORIES = [ + 'rpki', + ] + + ALT_INDEX = [ + ENV['PORTSDIR'] + '/INDEX.rpki', + ] + +Once you have completed these steps, you can just execute the script to install +or upgrade the RPKI code: + + sh rpki-portupgrade.sh + +As with manual download (above) you should customize rpki.conf after initial +installation. diff --git a/doc/doc.RPKI.Installation.FromSource b/doc/doc.RPKI.Installation.FromSource index e69de29b..b6acdc02 100644 --- a/doc/doc.RPKI.Installation.FromSource +++ b/doc/doc.RPKI.Installation.FromSource @@ -0,0 +1,277 @@ +****** 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 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, Debian, and MacOSX. + +***** Downloading the Source Code ***** + +The recommended way to obtain the source code is via subversion. To download, +do: + + $ svn checkout http://subvert-rpki.hactrn.net/trunk/ + +Code snapshots are also available from http://download.rpki.net/ as xz- +compressed tarballs. + +***** Prerequisites ***** + +Before attempting to build the tools from source, you will need to install any +missing prerequisites. + +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.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: + +* 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 Debian & 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 Debian & 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 Debian & 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 Debian & 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. + + o FreeBSD: /usr/ports/www/py-django (py27-django) + o Debian: python-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 Debian & Ubuntu: python-vobject + +* Several programs (more as time goes on) use the Python argparse module. This + module is part of the Python standard library as of Python 2.7, but you may + need to install it separately if you're stuck with Python 2.6. Don't do this + unless you must. In cases where this is necessary, you'll probably need to + use pip: + + $ python -c 'import argparse' 2>/dev/null || sudo pip install argparse + +* 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 Debian & 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 Debian & 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 Debian & 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 Debian & 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 Debian: python-django-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 + +***** 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 +ca/tests/smoketest.setup.sql. The MySQL command line client is usually the +easiest way to do this, eg: + + $ 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 + +If nothing explodes, your installation is probably ok. Any Python backtraces in +the output indicate a problem. + +***** Installing ***** + +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: binaries will be installed in / +usr/local/bin or /usr/local/sbin, Python modules will be installed using the +standard Python distutils and should end up wherever your system puts locally- +installed Python libraries, and so forth. + +The RPKI validator, rcynic, is a special case, because the install scripts may +attempt to build a chroot jail and install rcynic in that environment. This is +straightforward in FreeBSD, somewhat more complicated on other systems, +primarily due to hidden dependencies on dynamic libraries. + +To install the code, become root (su, sudo, whatever), then run "make install": + + $ cd $top + $ sudo make install + +***** Tools you should not need to install ***** + +There's a last set of tools that only developers should need, as they're only +used when modifying schemas or regenerating the documentation. These tools are +listed here for completeness. + +* http://www.doxygen.org/. Doxygen in turn pulls in several other tools, + notably Graphviz, pdfLaTeX, and Ghostscript. + + o FreeBSD: /usr/ports/devel/doxygen + o Debian & Ubuntu: doxygen + +* http://www.mbayer.de/html2text/. The documentation build process uses + xsltproc and html2text to dump flat text versions of a few critical + documentation pages. + + o FreeBSD: /usr/ports/textproc/html2text + +* 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. + + o FreeBSD: /usr/ports/textproc/trang + +* 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. + + o FreeBSD: /usr/ports/databases/p5-SQL-Translator + +* http://www.easysw.com/htmldoc/. The documentation build process uses htmldoc + to generate PDF from the project's Trac wiki. + + o FreeBSD: /usr/ports/textproc/htmldoc + +***** Next steps ***** + +Once you've finished installing the code, you will need to configure it. 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. diff --git a/doc/manual.pdf b/doc/manual.pdf Binary files differindex 4011447c..2985cc6a 100644 --- a/doc/manual.pdf +++ b/doc/manual.pdf |