Automatic pull of documentation from Wiki.

svn path=/trunk/; revision=5886

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
index 4011447c..2985cc6a 100644
--- a/doc/manual.pdf
+++ b/doc/manual.pdf