Move old manual to doc/manual, to make it easier to find other documentation.

1 files changed, 297 insertions, 0 deletions

diff --git a/doc/manual/04.RPKI.Installation.FromSource.wiki b/doc/manual/04.RPKI.Installation.FromSource.wiki
new file mode 100644
index 00000000..f768e3ea
--- /dev/null
+++ b/doc/manual/04.RPKI.Installation.FromSource.wiki
@@ -0,0 +1,297 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= 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

+[[http://www.rfc-editor.org/rfc/rfc3779.txt|RFC-3779]]-aware version

+of the [[http://www.openssl.org/|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

+[[https://subversion.apache.org/|subversion]]. To download, do:

+

+{{{

+#!sh

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

+}}}

+

+Code snapshots are also available from https://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.

+  * FreeBSD:

+    * /usr/ports/lang/python27 (python)

+  * 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.

+  * FreeBSD: /usr/ports/devel/py-lxml (py27-lxml)

+  * Fedora:  python-lxml.i386

+  * 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.

+  * FreeBSD:

+    * /usr/ports/databases/mysql55-server (mysql55-server)

+    * /usr/ports/databases/mysql55-client (mysql55-client)

+  * Debian & Ubuntu:

+    * mysql-client

+    * mysql-server

+

+* http://sourceforge.net/projects/mysql-python/, the Python "db"

+  interface to MySQL.

+  * FreeBSD: /usr/ports/databases/py-MySQLdb (py27-MySQLdb)

+  * Fedora:  MySQL-python.i386

+  * 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.

+  * FreeBSD: /usr/ports/www/py-django (py27-django)

+  * Debian: python-django

+  * 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:

+    {{{

+    #!sh

+    $ 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.

+  * FreeBSD: /usr/ports/deskutils/py-vobject (py27-vobject)

+  * 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:

+  {{{

+  #!sh

+  $ 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.

+  * FreeBSD: /usr/ports/devel/py-yaml (py27-yaml)

+  * Debian & Ubuntu: python-yaml

+

+* http://xmlsoft.org/XSLT/.  Some of the test code uses xsltproc, from

+  the Gnome LibXSLT package.

+  * FreeBSD: /usr/ports/textproc/libxslt (libxslt)

+  * 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.

+  * FreeBSD: /usr/ports/databases/rrdtool (rrdtool)

+  * 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

+  * FreeBSD: /usr/ports/www/mod_wsgi3 (app22-mod_wsgi)

+  * 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. 

+  * FreeBSD: /usr/ports/databases/py-south (py27-south)

+  * Debian: python-django-south

+  * 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:

+    {{{

+    #!sh

+    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":

+

+{{{

+#!sh

+$ 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:

+

+{{{

+#!sh

+$ 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:

+

+{{{

+#!sh

+$ cd $top/ca

+$ mysql -u root -p <tests/smoketest.setup.sql

+}}}

+

+To run the tests, run "make test":

+

+{{{

+#!sh

+$ cd $top

+$ make test

+}}}

+

+To run a more extensive set of tests on the CA tool, run "make

+all-tests" in the `ca/` directory:

+

+{{{

+#!sh

+$ 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":

+

+{{{

+#!sh

+$ 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.

+  * FreeBSD: /usr/ports/devel/doxygen

+  * 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.

+  * 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.

+  * 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.

+  * 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.

+  * FreeBSD: /usr/ports/textproc/htmldoc

+

+== Next steps == #Nextsteps

+

+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 [[RP|relying party tools]], then

+configure the [[CA|CA tools]] if you're planning to use them.