Dump of rpki.net Wiki, to capture content not linked into the manual.

60 files changed, 7433 insertions, 0 deletions

diff --git a/doc/wiki-dump/APRICOT-2013-Hackathon b/doc/wiki-dump/APRICOT-2013-Hackathon
new file mode 100644
index 00000000..e812a46f
--- /dev/null
+++ b/doc/wiki-dump/APRICOT-2013-Hackathon
@@ -0,0 +1,98 @@
+= APRICOT 2013 RPKI CA Hackathon, Signapore =

+

+== Options For Installation

+

+* FreeBSD binary packages (currently only FreeBSD 8-STABLE

+  * http://download.rpki.net/FreeBSD_Packages/rpki-rp-0.5080.tbz

+  * http://download.rpki.net/FreeBSD_Packages/rpki-ca-0.5080.tbz

+* FreeBSD ports (any recent FreeBSD version)

+  * http://download.rpki.net/FreeBSD_Packages/rpki-rp-port.tgz

+  * http://download.rpki.net/FreeBSD_Packages/rpki-ca-port.tgz

+* Ubuntu 12.04LTS binary packages

+  * http://download.rpki.net/Ubuntu_Packages/rpki-ca_0.5080_i386.deb

+  * http://download.rpki.net/Ubuntu_Packages/rpki-rp_0.5080_i386.deb

+* [[wiki:doc/RPKI|Build from source without package support]]

+* JPNIC has !VirtualBox images

+* JPNIC has virtual machines

+

+== FreeBSD binary packages on FreeBSD 8-STABLE ==

+{{{

+#!sh

+fetch http://download.rpki.net/FreeBSD_Packages/rpki-rp-0.5080.tbz

+fetch http://download.rpki.net/FreeBSD_Packages/rpki-ca-0.5080.tbz

+pkg_add rpki-*.tbz

+}}}

+

+== FreeBSD ports ==

+{{{

+#!sh

+fetch -o - http://download.rpki.net/FreeBSD_Packages/rpki-rp-port.tgz | tar xf -

+cd rpki-rp

+make install

+cd ..

+fetch -o - http://download.rpki.net/FreeBSD_Packages/rpki-ca-port.tgz | tar xf -

+cd rpki-ca

+make install

+cd ..

+}}}

+

+== FreeBSD ports with portmaster packages ==

+{{{

+#!sh

+mkdir /usr/ports/local

+cd /usr/ports/local

+fetch -o - http://download.rpki.net/FreeBSD_Packages/rpki-rp-port.tgz | tar xf -

+fetch -o - http://download.rpki.net/FreeBSD_Packages/rpki-ca-port.tgz | tar xf -

+portmaster -Pv local/rpki-rp local/rpki-ca

+}}}

+

+== Ubuntu 12.04LTS packages ==

+{{{

+#!sh

+wget http://download.rpki.net/Ubuntu_Packages/rpki-ca_0.5080_i386.deb

+wget http://download.rpki.net/Ubuntu_Packages/rpki-rp_0.5080_i386.deb

+dpkg -i rpki-*.deb

+}}}

+

+== Configuring the CA software ==

+* Copy rpki.conf.sample to rpki.conf

+* Edit as needed (see comments in file and see [[wiki:doc/RPKI/CA/Configuration|the documentation]]).

+* FreeBSD: {{{emacs /usr/local/etc/rpki.conf.sample}}}

+* Ubuntu: {{{emacs /etc/rpki.conf.sample}}}

+

+== Initializing the CA software ==

+{{{

+#!sh

+rpki-sql-setup

+rpkic initialize

+}}}

+

+== Start the daemons: FreeBSD ==

+* Add {{{rpkica_enable="YES"}}} to /etc/rc.conf

+* Add {{{inetd_enable="YES"}}} to /etc/rc.conf

+

+{{{

+#!sh

+service inetd restart

+service rpki-ca start

+}}}

+

+== Start the daemons: Ubuntu ==

+{{{

+#!sh

+sudo initctl start rpki-ca

+}}}

+

+== Dance With Your Parent ==

+See: [[wiki:doc/RPKI/CA/UI|Command line interface documentation]]

+* Child sends XML to parent

+* Parent runs rpkic configure_child

+* Parent sends result to child

+* Child runs rpkic configure_parent

+* Child sends repository request to repository (parent or self, depending on child's configuration)

+* Repository runs configure_publication_client

+* Repository sends result to child

+* Child runs configure_repository

+

+== Set Up The GUI ==

+See: [[wiki:doc/RPKI/CA/UI/GUI|Graphical web interface documentation]]

diff --git a/doc/wiki-dump/JANOG b/doc/wiki-dump/JANOG
new file mode 100644
index 00000000..643d0803
--- /dev/null
+++ b/doc/wiki-dump/JANOG
@@ -0,0 +1,211 @@
+Quick guide to installing RPKI relying party software for JANOG hackathon, February 2013.  This page will probably be renamed at some point in the future, the short name was chosen to be something we could write on a whiteboard.

+

+== Prepackaged RP software ==

+

+JPNIC has built a

+[https://www.virtualbox.org/ VirtualBox]

+[http://psg.com/rpki/RPKI-CA-RP.ova appliance image of Ubuntu 12.04 LTS with RPKI relying party software]

+already installed,

+[http://psg.com/rpki/RPKI-VM.pdf with documentation];

+if that works for you, just use it.

+

+If you want to install your own software:

+

+* If  you're running Ubuntu 12.04 LTS, you can try the pre-built Ubuntu package at http://download.rpki.net/Ubuntu_Packages/rpki-rp_0.5045_i386.deb

+

+* If you're running FreeBSD 8, you can try the pre-built FreeBSD package at http://download.rpki.net/FreeBSD_Packages/rpki-rp-0.5045.tbz

+

+* If you're running some other version of FreeBSD (or if you just don't like pre-built packages), you can try the FreeBSD port skeleton at http://download.rpki.net/FreeBSD_Packages/rpki-rp-port.tgz

+

+* Otherwise, you'll have to compile from source as described at [wiki:doc/RPKI/Installation Installation], but note that since for today we're only concerned with the relying party tools, you don't need to do everything on that page.

+

+If you're installing from packages or ports, you should get a working rcynic installation already set up under cron, running once an hour, with the default set of trust anchor locators (TALs) already installed.

+You might want to edit rcynic's configuration file (/usr/local/etc/rcynic.conf on FreeBSD, /etc/rcynic.conf on Ubuntu), but the default configuration should suffice for today's testing.

+

+The installed crontab will only run rcynic once per hour.  This is what you want for normal operation, but is a little slow for test purposes, so you might want to edit the crontab:

+

+{{{

+  $ sudo crontab -u rcynic -e

+}}}

+

+then change the first field of the crontab entry (a randomly-selected minute) to something like "*/10" to make it run every ten minutes.

+

+Even with the package or port, you will need to set up the listener

+for the rpki-rtr protocol manually.  For this, you will need to pick a

+port number, we don't have one assigned.  For this discussion we will

+call it 43779.  How you do this depends on whether you are running inetd or xinetd.

+

+For FreeBSD with inetd, you will need to add entries to /etc/services and /etc/inetd.conf

+

+/etc/services:

+{{{

+rpki-rtr		 43779/tcp	   #RPKI-RTR protocol

+}}}

+

+/etc/inetd.conf:

+{{{

+rpki-rtr	stream	tcp	nowait	nobody	/usr/local/bin/rtr-origin	rtr-origin --server /var/rpki-rtr

+}}}

+

+For Ubuntu, you probably need to use xinetd.  xinetd may not be installed by default, and is not (yet) listed as a package dependency for rpki-rp, so you may need to install it:

+

+{{{

+  $ sudo apt-get install xinetd

+}}}

+

+You will need to create a xinetd configuration file for the rpki-rtr service:

+

+/etc/xinetd.d/rpki-rtr:

+{{{

+service rpki-rtr

+{

+    socket_type    = stream

+    protocol       = tcp

+    port	   = 43779

+    wait           = no

+    user           = nobody

+    server         = /usr/bin/rtr-origin

+    server_args	   = --server /var/rpki-rtr

+}

+}}}

+

+And remember to

+

+{{{

+  $ sudo service xinetd restart

+}}}

+

+== Testing rpki-rtr service ==

+

+To test the rpki-rtr service you've installed, you can use the rtr-origin program (yes, the same program that acts as the rpki-rtr server) as a test client:

+

+{{{

+  $ rtr-origin --client tcp localhost 43779

+}}}

+

+This will attempt to connect to the rpki-rtr service on your machine

+using the given port.  If the service is running, you will either get

+a listing of the current database content, or a message warning that

+the server has no data yet.  In either of these cases, the client will

+stay connected to the server, waiting for updates.

+

+If the client does not connect to the server, or exits with an error

+message, something is wrong.  Sadly, there are many interesting ways

+for this to fail (for example: at the previous JANOG hackathon, we saw

+a case where it failed because inetd had TCP wrappers support enabled,

+so inetd was accepting the connection but not starting the server

+process).  If this happens to you, we will have to debug to see what

+is wrong.

+

+

+== Building from source ==

+

+If you need to build from source:

+

+Download the source code, either via subversion:

+

+{{{

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

+}}}

+

+or from a snapshot tarball:

+

+{{{

+  $ wget http://download.rpki.net/rpki-trunk.tar.xz

+  $ xzcat rpki-trunk.tar.xz | tar xf -

+}}}

+

+For the relying party tools, the packages you will need to install

+are:

+

+* Python

+* lxml

+* xsltproc

+* rrdtool

+* chrootuid

+

+See the installation page for details on platform packages and

+download URLs.

+

+If you forget any of these, ./configure will remind you.

+

+Once you have these installed, follow the installation instructions on

+the installation page.  You only need the relying party tools, so  you

+can configure it with:

+

+{{{

+  $ ./configure --disable-ca-tools

+  $ make

+  $ sudo make install

+}}}

+

+Once you have the tools installed, you should go to the documentation for the [wiki:doc/RPKI/RP Relying Party tools], particularly the section on [wiki:doc/RPKI/RP#cronjob running the Relying Party tools under cron].

+

+You will need to create the /var/rpki-rtr directory manually, and chown it to be owned by the rcynic user:

+

+{{{

+  $ sudo mkdir /var/rpki-rtr

+  $ sudo chown rcynic:rcynic /var/rpki-rtr

+}}}

+

+You will also need to set up a listener for the rpki-rtr service.  There are many ways to do this, but the most common one is to run rpki-rtr under inetd or xinetd.  Pick an available TCP port, and set up inetd or xinetd to run the command:

+

+{{{

+  rtr-origin --server /var/rpki-rtr

+}}}

+

+as the service for that port.

+

+If all goes well, at this point you should have a working RPKI cache, and can point routers that support the rpki-rtr protocol at the cache.

+

+== Prepackaged CA software ==

+

+The options for prepackaged version of the rpki.net CA tools are mostly the same as for the RP tools.

+

+JPNIC's appliance image may support the CA tools (ask them then update this page).

+

+If you want to install your own software:

+

+* If  you're running Ubuntu 12.04 LTS, you can try the pre-built Ubuntu package at http://download.rpki.net/Ubuntu_Packages/rpki-ca_0.5045_i386.deb

+

+* If you're running FreeBSD 8, you can try the pre-built FreeBSD package at http://download.rpki.net/FreeBSD_Packages/rpki-ca-0.5045.tbz

+

+* If you're running some other version of FreeBSD (or if you just don't like pre-built packages), you can try the FreeBSD port skeleton at http://download.rpki.net/FreeBSD_Packages/rpki-ca-port.tgz

+

+* Otherwise, you'll have to compile from source as described at [wiki:doc/RPKI/Installation Installation]; if you already did this //without// setting the --disable-ca-tools, you've already built everything;

+  if you did specify --disbale-ca-tools, you'll need to rebuild without that option.

+

+The prepackaged versions of the CA tools will need some configuration.  The package dependencies should pull in the MySQL server, but you will need to

+[wiki:doc/RPKI/CA/Configuration create an rpki.conf] (by editing the provided rpki.conf.sample), then

+[wiki:doc/RPKI/CA/MySQLSetup configure your MySQL databases] before you can start the daemons.

+

+You will also need to [wiki:doc/RPKI/CA/UI/GUI configure the GUI] before you can use the web interface to the CA tools.

+

+On FreeBSD, rpki.conf is in /usr/local/etc/rpki.conf; on Ubuntu, it's in /etc/rpki.conf.

+In both cases, you should find a rpki.conf.sample file in the same directory.

+

+Once you have configured the CA code and created its databases, you need to run:

+

+{{{

+  $ rpkic initialize

+}}}

+

+to create the BPKI (sic) certificates and keys needed by the daemons.

+

+If you get through all this, you should be ready to start the servers.  On FreeBSD, you do this by adding

+

+{{{

+rpkica_enable="YES"

+}}}

+

+to /etc/rc.conf, then running

+

+{{{

+  $ /usr/local/et/rc.d/rpki-ca start

+}}}

+

+On Ubuntu, the CA tools are under upstart control, so you should be able to start the daemons by running

+

+{{{

+  $ sudo initctl start rpki-ca

+}}}

diff --git a/doc/wiki-dump/PresentationArchive b/doc/wiki-dump/PresentationArchive
new file mode 100644
index 00000000..bec7a71a
--- /dev/null
+++ b/doc/wiki-dump/PresentationArchive
@@ -0,0 +1,23 @@
+

+== Presentation Archive ==

+

+This is an archive of various presentations and supporting materials we've accumulated over the years.

+

+OK, I lied.  This is really an archive of stuff that had accumulated in the /presentations directory of the subversion repository, which we decided really belonged here in the Wiki instead.   At some point we may get around to organizing this in a more useful fashion.

+

+==== Old notes on what some of this is ====

+

+

+070523.lacnic-pki.pdf           A presentation from LACNIC, May 2007

+

+bpki.pdf                        Old discussion of a design choice between two slightly different business PKI (BPKI) architectures

+

+entity-decompose.pdf            An overview presentation

+

+images                          Some old pictures

+

+repository-engine-objects.dot   Objects in the RPKI engine (PDF)

+

+repository-engine-objects.pdf   Graphviz source for "

+

+repository-structure.txt        Old notes on repository structure

diff --git a/doc/wiki-dump/Puppet b/doc/wiki-dump/Puppet
new file mode 100644
index 00000000..cd9b859b
--- /dev/null
+++ b/doc/wiki-dump/Puppet
@@ -0,0 +1,94 @@
+= Setting up a RPKI testbed with Puppet

+

+This document outlines how Google stood up a few virtual machines to

+serve as a testbed for evaluating and running RPKI.net packages.

+The rpki-mgmt project, at https://github.com/google/rpki-mgmt, contains

+puppet modules and a setup script to generate a pupet manifest for the

+testbed.

+

+The testbed consists of:

+

+* A puppet server

+* A RPKI Certificate Authority, with Relying Party tools

+* One or more log servers

+* One or more publication servers

+

+All of the machines, except for the publication servers, are intended to

+run on an internal/private network. The publication servers collect RPKI

+data from the CA (Certificate Authority) and republish to the world.

+

+Currently the puppet modules are fairly tightly coulpled to the exact

+configuration and host OS (Debian Jessie) used by Google. Hopefully

+future versions of the module will be more flexible.

+

+

+=  Information gathering

+

+To begin with, you will need to collect/set-up the following:

+

+* DNS name for all machines. The host names should match the DNS names,

+ as the puppet modules make use of puppet's node certificates for

+ secure connections to the log servers, and puppet's node certificates

+ are based on the node's hostname. For example:

+ {{{

+    pup.rpki.example.com       IN      A       10.1.1.10

+    ca.rpki.example.com        IN      A       10.1.1.11

+    log.rpki.example.com       IN      A       10.1.1.12

+    pub.rpki.example.com       IN      A       10.1.1.13

+}}}

+

+* (Optionally) Banner text for publication servers

+* (Optionally) Network range to restrict ssh acceess. Default is unrestricted (0.0.0.0/0)

+* (Optionally) Any additional puppet configuration for all nodes (e.g.user(s) to create, their associated ssh key(s)).

+

+= Install VMs

+

+Create all the VMs and perform basic setup (IP address, resolver config, etc.)

+

+== Set up pup.rpki.example.com

+  - apt-get install puppetmaster

+  - Edit the '[main]' section /etc/puppet/puppet.conf

+    - server=puppet.rpki.example.com

+    - pluginsync=true

+

+== Run script to generate puppet config

+The rpki-mgmt generate script will prompt you for all the information on node names that

+was gathered earlier.

+

+  - wget https://github.com/google/rpki-mgmt/raw/dev/generate-rpki-mgmt-config.sh

+  - bash ./generate-rpki-mgmt-config.sh

+

+== Use newly generated puppet config to configure puppet master

+  - cp /root/rpki-mgmt.pp /etc/puppet/manifests/site.pp

+  - puppet agent --enable

+  - puppet agent -t

+

+== Enroll all machines with the puppet master

+  - apt-get install puppet

+  - edit /etc/puppet/puppet.conf [main] section

+    - add 'server=pup.rpki.example.com'

+    - add 'pluginsync=true'

+  - puppet agent --enable

+  - puppet agent -t

+    - this will print a message:

+      Exiting; no certificate found and waitforcert is disabled

+    - Ignore the error and continue with the next machine

+

+== Sign puppet certificates

+- On pup.rpki.example.com

+  - puppet cert list

+  - puppet cert sign --all

+

+== Run puppet on log servers

+  - puppet agent -t

+

+== Run puppet on all other servers

+  - puppet agent -t

+

+== Install rpki software on rpki master node(s)

+  - apt-get install rpki-ca rpki-rp

+  - you'll need to set mysql admin password

+

+== Configure RPKI.net software

+At this point your testbed environment should be set up, and you are ready to continue and configure the RPKI.net software. More information on that process can be found at

+  - https://rpki.net/wiki/doc/RPKI/CA

diff --git a/doc/wiki-dump/README.md b/doc/wiki-dump/README.md
new file mode 100644
index 00000000..52c4e116
--- /dev/null
+++ b/doc/wiki-dump/README.md
@@ -0,0 +1,3 @@
+Full verbatim page dump of https://rpki.net/ Wiki, generated using
+trac-admin's "wiki dump" command then manuallly pruning pages that are
+part of Trac's internal documentation.
diff --git a/doc/wiki-dump/WebPortal b/doc/wiki-dump/WebPortal
new file mode 100644
index 00000000..3e059425
--- /dev/null
+++ b/doc/wiki-dump/WebPortal
@@ -0,0 +1,66 @@
+[[PageOutline]]

+

+= Web Portal =

+

+The RPKI Web Portal currently requires Django 1.2 or later.

+

+Django upstream currently provides support for the previous two minor releases, which is 1.2 and 1.3 as of the writing of this page (https://docs.djangoproject.com/en/1.3/internals/release-process/#supported-versions).

+

+Targeting RHEL/CentOS/Scientific 6.x and Ubuntu 10.04 LTS.  Should work with any newer Fedora or Ubuntu release as well, but those are not typically deployed as production servers.

+

+

+== Platforms ==

+

+=== Ubuntu 10.04 ===

+

+Ships with Django 1.1.1 which is out of upstream's support window.  My recommendation is to install or rebuild a newer supported release.

+

+* Ubuntu Maverick (10.10) and Natty (11.04) do have 1.2.x releases, but seem to be missing the security patches from the 1.2.7 release (https://www.djangoproject.com/weblog/2011/sep/09/security-releases-issued/).  

+* The 1.3 release in Oneiric (11.10) also seems to be missing the security updates from that same advisory.

+

+==== Installing Django 1.3.1 PPA ====

+

+This section describes how to install a pre-built PPA package for python-django 1.3.1.

+

+Put the following in your `/etc/apt/sources.list`:

+{{{

+deb http://ppa.launchpad.net/chris-lea/python-django/ubuntu lucid main 

+deb-src http://ppa.launchpad.net/chris-lea/python-django/ubuntu lucid main 

+}}}

+

+Then run the following commands:

+{{{

+# apt-get update

+# apt-get install python-django

+}}}

+

+* [https://launchpad.net/~chris-lea/+archive/python-django python-django PPAs]

+

+==== Rebuilding python-django from source deb ====

+

+The 1.3.1 package from Precise Pangolin (12.04 LTS) doesn't build due to build dependencies for newer python-sphinx than ships with 10.04 LTS.  However, once built you can install the new python-django package on other systems without needing to upgrade other packages.  You can also chose to build the 1.2.5 release from Natty (11.04).

+

+To rebuild the python-django package:

+{{{

+# apt-get install dpkg-dev

+# apt-get build-dep python-django

+# tar zxvf python-django_1.2.5.orig.tar.gz

+# cd Django-1.2.5

+# tar zxvf ../python-django_1.2.5-1ubuntu1.debian.tar.gz

+# dpkg-buildpackage

+}}}

+

+* https://launchpad.net/ubuntu/+source/python-django

+

+=== RHEL/CentOS/Scientific 6 ===

+

+Django is not included in base OS, but Django 1.2 is available via EPEL (http://fedoraproject.org/wiki/EPEL).

+

+Once you have enabled the EPEL repository, you can run:

+{{{

+# yum install Django

+}}}

+

+==== SELinux ====

+

+Extra steps are required to run the Web Portal with SELinux enabled.

diff --git a/doc/wiki-dump/WebPortal%2FUpgradingFromSqlite b/doc/wiki-dump/WebPortal%2FUpgradingFromSqlite
new file mode 100644
index 00000000..27500aa6
--- /dev/null
+++ b/doc/wiki-dump/WebPortal%2FUpgradingFromSqlite
@@ -0,0 +1,85 @@
+[[PageOutline]]

+

+= Upgrading From Sqlite to MySQL Backend

+

+If you originally deployed the Web Portal using the sqlite backend, you can migrate to the MySQL backend using the steps detailed on this page.

+

+== Bring source tree up to date ==

+If you have not already done so, bring your copy of the subversion repository up to date:

+{{{

+# cd $top

+# svn up

+}}}

+Where ''${top}'' is the top level directory of the SVN repository.

+

+== Backup Current Sqlite Database

+

+Create a backup of the database. The dump will only contain the data from the `rpki.gui.app` and `django.contrib.auth`, which are the only Django applications that contain site-specific data.

+

+{{{

+# ${top}/rpkid/portal-gui/scripts/dumpdata.py > gui-backup.json

+}}}

+

+Where ''${top}'' is the top level directory of the SVN repository.

+

+'''Note''': On some systems such as FreeBSD, the command is `django-admin.py` (with the `.py` suffix).

+

+== Backup Current IRDB

+

+After this upgrade, the Web Portal will store its SQL tables in the same MySQL database used by `irdbd`.  Therefore, it is a good idea to create a backup of your current IRDB prior to performing the upgrade.  By default, the database is named ''irdbd''.  Consult your `rpki.conf` and look in the ''myrpki'' section (default is the first section of the file) for the line that looks like this:

+{{{

+irdbd_sql_database              = irdbd

+}}}

+Once you have determined the correct database, you can create the backup:

+{{{

+# mysqldump -u root -p irdbd > irdb-backup.sql

+}}}

+Replace ''irdbd'' with the name of your database from your `rpki.conf` if you customized it.

+

+== Install Software

+

+At this point you should install the software if you have not already done so:

+{{{

+# cd ${top}

+# make clean

+# ./configure

+# make

+# make install

+}}}

+

+== Editing rpki.conf

+

+Edit your `rpki.conf` and add the following section at the end of the file:

+{{{

+[web_portal]

+sql-database = ${myrpki::irdbd_sql_database}

+sql-user     = ${myrpki::irdbd_sql_username}

+sql-password = ${myrpki::irdbd_sql_password}

+}}}

+

+== Creating /usr/local/etc/rpki.conf

+

+The web portal now expects that the `rpki.conf` for the self-hosted resource handle (i.e. the `rpki.conf` with '''run_rpkid = True''') is accessible via the system configuration directory.  This is typically `/usr/local/etc/rpki.conf`.  If you have been running the rpki tools with the rpki.conf in `/usr/local/var/rpki/conf/${HANDLE}/rpki.conf` you have one of two choices:

+ 1. Move the `rpki.conf` to `/usr/local/etc/`

+ 2. Create a symbolic link from your `rpki.conf` to `/usr/local/etc/rpki.conf`

+

+== Create Database Tables

+

+This steps creates the database tables used by the Web Portal.

+{{{

+# django-admin syncdb --settings=settings --pythonpath=/usr/local/etc/rpki --noinput

+}}}

+

+The '''--noinput''' argument is specified to suppress the prompt to create a superuser account.  It is assumed that you had orignally created a superuser account in the sqlite backend which will be recreated when you restore the database dump as the final step in the migration process.

+

+== Restore Data from Backup

+

+The final step is to restore the data from the backup created in the first step.

+

+{{{

+# django-admin loaddata --settings=settings --pythonpath=/usr/local/etc/rpki gui-backup.json

+}}}

+

+== Restart the Web Server

+

+The final step is to restart the web server so that the web portal is served up using the new mysql backend.

diff --git a/doc/wiki-dump/WikiStart b/doc/wiki-dump/WikiStart
new file mode 100644
index 00000000..96e8f06a
--- /dev/null
+++ b/doc/wiki-dump/WikiStart
@@ -0,0 +1,51 @@
+= rpki.net project site =

+

+This is the Trac site for the rpki.net project.  The project provides a free, BSD License, open source, complete system for the Internet Registry or ISP.  It includes separate components which may be combined to suit your needs:

+* Certification Engine

+* Relying Party Cache (sometimes called a 'validator')

+* rpki-rtr protocol, to feed the data to routers doing RPKI-based origin validation

+* GUI for use by users of the 'hosted' model (i.e. customers who do not run their own CA)

+* Web Reporting Pages so you can see what your cache has found

+* Creation of pseudo-IRR data for those who wish to feed RPSL toolchains

+

+If you're looking for the general RPKI Wiki (not specific to our software), it's [[http://wiki.rpki.net/|over here]].

+

+== Downloads ==

+

+See [[/wiki/doc/RPKI|the documentation]] for how to download and install the code.

+

+We now have [[http://download.rpki.net/APT/debian/|Debian packages]], [[http://download.rpki.net/APT/ubuntu/|Ubuntu packages]], and [[http://download.rpki.net/FreeBSD_Packages/|FreeBSD ports]] of the code.

+

+You can also [[/browser|browse the source code]].

+

+== Documentation ==

+

+Primary [[/wiki/doc/RPKI|documentation for the code]] is here, in the Trac wiki.  PDF and flat text forms derived from are available in [[/browser|the source code repository]].

+

+== Bug Reports ==

+

+The [[/query|ticket queue]] is open for public read.  Please [[/register|register for an account]] if you need to create a ticket.

+

+== Monitoring ==

+

+[[http://www.hactrn.net/opaque/rcynic/|Current status of RPKI system as seen by one relying party]].

+

+== TLS Certificate ==

+

+If you're trying to connect to this site (https://rpki.net/) using

+HTTPS, you may see warnings about an untrusted certificate.  There's

+nothing wrong, this just means that your web browser doesn't know

+about the Certification Authority that we use.

+

+You can [[http://www.hactrn.net/cacert.asc|download a PGP-signed version of the HACTRN CA certificate]] to fix this.

+

+If you don't care about checking the CA certificate and just want the

+warning to go away, you can set a browser exception or just

+[[http://www.hactrn.net/cacert.cer|install the HACTRN CA certificate]]

+without checking it.

+

+== APRICOT 2013 ==

+

+Hot link to information for [[wiki:APRICOT-2013-Hackathon|APRICOT 2013 Hackathon]].

+

+Thanks to JPNIC, [[http://psg.com/rpki/RPKI-CA-RP.ova |a VirtualBox appliance image]] is available, [[http://psg.com/rpki/RPKI-VM.pdf |with documentation]].

diff --git a/doc/wiki-dump/doc%2FRPKI b/doc/wiki-dump/doc%2FRPKI
new file mode 100644
index 00000000..aaf59d4e
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI
@@ -0,0 +1,39 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= 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 https://subvert-rpki.hactrn.net/.

+

+If you just want to browse the code you might find the

+[[http://trac.rpki.net/browser/|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 [[wiki:doc/RPKI/Installation|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 [[./RP|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|CA tools]].

+

+== Thanks ==

+

+This work was funded from 2006 through 2008 by

+[[http://www.arin.net/|ARIN]], in collaboration with the other

+Regional Internet Registries.  Current work is funded by

+[[http://www.dhs.gov/|DHS]].

diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA b/doc/wiki-dump/doc%2FRPKI%2FCA
new file mode 100644
index 00000000..9fd1f7f0
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA
@@ -0,0 +1,264 @@
+= RPKI CA Engine =

+

+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+The RPKI CA engine is an implementation of the production-side tools

+for generating certificates, CRLs, ROAs, and other RPKI objects.  The

+CA tools are implemented primarily in Python, with an extension module

+linked against an RFC-3779-enabled version of the OpenSSL libraries

+to handle some of the low-level details.

+

+See the [[RP|relying party tools]] for tools for retrieving,

+verifying, and using RPKI data.

+

+== Getting started ==

+

+If you just want to get started with the CA tools and hate reading

+documentation, here's a roadmap on what you do need to read:

+

+1. Start with the [[Installation|installation instructions]]; if you're using pre-built packages you may be able to skip this step.

+

+2. Then read the [[./Configuration|configuration instructions]]

+

+3. Then the [[./MySQLSetup|MySQL setup instructions]]

+

+4. And finally either the [[./UI/rpkic|command line tool]] or [[./UI/GUI|web interface]] 

+

+== Overview of the CA engine ==

+

+=== Terminology ===

+

+A few special terms appear often enough in code and documentation that

+they need explaining.

+

+IRBE::

+      "Internet Registry Back End."

+

+IRDB::

+      "Internet Registry Data Base."

+

+BPKI::

+      "Business PKI."

+

+RPKI::

+      "Resource PKI."

+

+=== Programs ===

+

+See the [[Installation|installation instructions]] for how to build and install the code.

+

+The RPKI CA engine includes the following programs:

+

+rpkid::

+	The main RPKI engine daemon.

+

+pubd::

+	The publication engine daemon.

+

+rootd::

+

+	A separate daemon for handling the root of an RPKI certificate

+	tree.  This is essentially a stripped down version of rpkid

+	with no SQL database, no left-right protocol implementation,

+	and only the parent side of the up-down protocol.  It's

+	separate because the root is a special case in several ways

+	and it was simpler to keep the special cases out of the main

+	daemon.

+

+irdbd::

+	A sample implementation of an IR database daemon.  rpkid calls

+	into this to perform lookups via the left-right protocol.

+

+rpkic::

+	A command line interface to control rpkid and pubd.

+

+GUI::

+	A web-based graphical interface to control rpkid and pubd.

+

+irdbd, rpkic, and the GUI collectively make up the "Internet registry

+back end" (IRBE) component of the system.

+

+These programs take configuration files in a common format similar to

+that used by the OpenSSL command line tool, see the

+[[./Configuration|configuration guide]] for details.

+

+Basic operation consists of creating the appropriate MySQL databases

+(see [[./MySQLSetup|MySQL setup]]), starting the daemons, and using

+[[./UI/rpkic|rpkic]] or [[./UI/GUI|the web interface]] to configure

+relationships between parents and children, relationships between

+publication clients and repositories, allocate resources to children,

+and create ROAs.  Once setup is complete, rpkid should maintain the

+requested data automatically, including re-querying its parent(s)

+periodically to check for changes, reissuing certificates and other

+objects as needed, and so forth.

+

+The daemons are all event-driven, and are (in theory) capable of

+supporting an arbitrary number of hosted RPKI engines to run in a

+single rpkid instance, up to the performance limits of the underlying

+hardware.

+

+== Starting the servers ==

+

+You need to follow the instructions in the

+[[./Configuration|configuration guide]] before attempting to start the

+servers.

+

+Once you've written the servers' configuration file, the easiest way

+to run the servers is to run the `rpki-start-servers` script,

+which examines your `rpki.conf` file and starts the appropriate

+servers in background.

+

+If you prefer, you can run each server by hand instead of using the

+script, eg, using Bourne shell syntax to run rpkid in background:

+

+{{{

+#!sh

+rpkid &

+echo >rpkid.pid  "$!"

+}}}

+

+You can also use separate configuration files for each server if

+necessary, run multiple copies of the same server with different

+configuration files, and so forth.

+

+All of the daemons use syslog by default.  You can change this by

+running either the servers themselves or the `rpki-start-servers`

+script with the "-d" option.  Used as an argument to a server

+directly, "-d" causes that server to log to stderr instead of to

+syslog.  Used as an argument to `rpki-start-servers`, "-d" starts

+each of the servers with "-d" while redirecting stderr from each

+server to a separate log file.  This is intended primarily for

+debugging.

+

+Some of the configuration options are common to all daemons: which

+daemon they affect depends only on which sections of the configuration

+file they are in.  See [[./Configuration/Common|Common Options]] for

+details.

+

+=== rpkid ===

+

+rpkid is the main RPKI engine daemon.  Configuration of rpkid is a two

+step process: a config file to bootstrap rpkid to the point where it

+can speak using the [[./Protocols/LeftRight|left-right protocol]],

+followed by dynamic configuration via the left-right protocol.  The

+latter stage is handled by the [[./UI/rpkic|command line tool]] or the

+[[./UI/GUI|web interface]].

+

+rpkid stores dynamic data in an SQL database, which must have been

+created for it, as explained in in the

+[[./MySQLSetup|MySQL setup instructions]].

+

+=== pubd ===

+

+pubd is the publication daemon.  It implements the server side of

+the publication protocol, and is used by rpkid to publish the

+certificates and other objects that rpkid generates.

+

+pubd is separate from rpkid for two reasons:

+

+* The hosting model allows entities which choose to run their own

+  copies of rpkid to publish their output under a common publication

+  point.  In general, encouraging shared publication services where

+  practical is a good thing for relying parties, as it will speed up

+  rcynic synchronization time.

+

+* The publication server has to run on (or at least close to) the

+  publication point itself, which in turn must be on a publically

+  reachable server to be useful.  rpkid, on the other hand, need only

+  be reachable by the IRBE and its children in the RPKI tree.  rpkid

+  is a much more complex piece of software than pubd, so in some

+  situations it might make sense to wrap tighter firewall constraints

+  around rpkid than would be practical if rpkid and pubd were a single

+  program.

+

+pubd stores dynamic data in an SQL database, which must have been

+created for it, as explained in the

+[[./MySQLSetup|MySQL setup instructions]].

+pubd also stores the published objects themselves as disk files in a

+configurable location which should correspond to an appropriate module

+definition in rsync.conf; see the

+[[./Configuration|configuration guide]] for details.

+

+=== rootd ===

+

+rootd is a stripped down implmenetation of (only) the server side of

+the up-down protocol.  It's a separate program because the root

+certificate of an RPKI certificate tree requires special handling and

+may also require a special handling policy.  rootd is a simple

+implementation intended for test use, it's not suitable for use in a

+production system.  All configuration comes via the config file; see

+the [[./Configuration|configuration guide]] for details.

+

+=== irdbd ===

+

+irdbd is a sample implemntation of the server side of the IRDB

+callback subset of the left-right protocol.  In production use this

+service is a function of the IRBE stub; irdbd may be suitable for

+production use in simple cases, but an IR with a complex IRDB may need

+to extend or rewrite irdbd.

+

+irdbd is part of the IR back-end system, and shares its SQL database

+with rpkic and the web interface.

+

+The package actually includes a second implementation of irdbd, used

+only for testing: `ca/tests/old_irdbd` is a mininmal

+implementation, used only by smoketest, which itself constitues

+a fairly complete (if rather strange) IRBE implementatation.

+Ordinarly you won't care about this, but if for some reason you need

+to write your own irdbd implementation, you might find it easier to

+start from the minimal version.

+

+See the [[./Configuration|configuration guide]] for details on

+configuring irdbd.

+

+== Test programs ==

+

+The package includes two separate test programs, which take similar

+test description files but use them in different ways.  The test tools

+are only present in the source tree ("make install" does not install

+them).

+

+Unlike the configuration files used by the other programs, these test

+programs read test descriptions written in the YAML serialization

+language (see http://www.yaml.org/ for more information on YAML).

+Each test script describes a hierarchy of RPKI entities, including

+hosting relationships and resource assignments, in a relatively

+compact form.  The test programs use these descriptions to generate a

+set of configuration files, populate the back end database, and drive

+the test.

+

+See the [[./Configuration/Tests|test configuration language]] for

+details on the content of these YAML files.

+

+=== smoketest === #smoketest

+

+smoketest is a test harness to set up and run a collection of rpkid

+and irdbd instances under scripted control.  The YAML test description

+defines the test configuration for smoketest to run, including initial

+resource assignments.  Subsequent YAML "documents" in the same

+description file define an ordered series of changes to be made to the

+configuration.  smoketest runs the rcynic RPKI validator between each

+update cycle, to check the output of the CA programs.

+

+smoketest is designed to support running a fairly wide set of test

+configurations as canned scripts, without writing any new control

+code.  The intent is to make it possible to write meaningful

+regression tests.

+

+=== yamltest ===

+

+yamltest is another test harness to set up and run a collection of

+rpkid and irdbd instances under scripted control.  It is similar in

+many ways to, and uses the same YAML test description language, but

+its purpose is different: smoketest runs a particular test scenario

+through a series of changes, then shuts it down; yamltest, on the

+other hand, sets up a test network using the same tools that a real

+user would use (principally the rpkic tool), and leaves the test

+running indefinitely.

+

+At present, this means that yamltest ignores all but the first

+"document" in a test description file.  This may change in the future.

+

+Running yamltest will generate a fairly complete set configuration

+files, which may be useful as examples.

diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FBPKIModel b/doc/wiki-dump/doc%2FRPKI%2FCA%2FBPKIModel
new file mode 100644
index 00000000..e3c98cf5
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FBPKIModel
@@ -0,0 +1,106 @@
+= The BPKI model =
+
+[[TracNav(doc/RPKI/TOC)]]
+
+The "business PKI" (BPKI) is the PKI used to authenticate
+communication on the up-down, left-right, and publication protocols.
+BPKI certificates are //not// resource PKI (RPKI) certificates.  The
+BPKI is a separate PKI that represents relationships between the
+various entities involved in the production side of the RPKI system.
+In most cases the BPKI tree will follow existing business
+relationships, hence the "B" (Business) in "BPKI".
+
+Setup of the BPKI is handled by the back end; for the most part,
+rpkid and pubd just use the result.  The one place where the engines
+are directly involved in creation of new BPKI certificates is in the
+production of end-entity certificates for use by the engines.
+
+For the most part an ordinary user of this package need not worry
+about the details explained here, as the [[rpkic|rpkic tool]]
+takes care of all of this.  However, users who want to understand
+what's going on behind the scenes or who have needs too complex for
+the myrpki tool to handle might want to understand the underlying
+model.
+
+There are a few design principals that underly the chosen BPKI model:
+
+* Each engine should rely on a single BPKI trust anchor which is
+  controlled by the back end entity that runs the engine; all other
+  trust material should be cross-certified into the engine's BPKI
+  tree.
+
+* Private keys must never transit the network.
+
+* Except for end entity certificates, the engine should only have
+  access to the BPKI certificates; in particular, the private key for
+  the BPKI trust anchor should not be accessible to the engine.
+
+* The number of BPKI keys and certificates that the engine has to
+  manage should be no larger than is necessary.
+
+rpkid's hosting model adds an additional constraint: rpkid's BPKI
+trust anchor belongs to the entity operating rpkid, but the entities
+hosted by rpkid should have control of their own BPKI private keys.
+This implies the need for an additional layer of BPKI certificate
+hierarchy within rpkid.
+
+Here is a simplified picture of what the BPKI might look like for an
+rpkid operator that hosts two entities, "Alice" and "Ellen":
+
+[[Image(rpkid-bpki.png)]]
+
+Black objects belong to the hosting entity, blue objects belong to
+the hosted entities, red objects are cross-certified objects from
+the hosted entities' peers.  The arrows indicate certificate
+issuance: solid arrows are the ones that rpkid will care about
+during certificate validation, dotted arrows show the origin of the
+EE certificates that rpkid uses to sign CMS and TLS messages.
+
+The certificate tree looks complicated, but the set of certificates
+needed to build any particular validation chain is obvious.
+
+Detailed instructions on how to build a BPKI are beyond the scope of
+this document, but one can handle simple cases using the OpenSSL
+command line tool and cross_certify; the latter is a tool
+designed specifically for the purpose of generating the
+cross-certification certificates needed to splice foreign trust
+material into a BPKI tree.
+
+The BPKI tree for a pubd instance is similar to to the BPKI tree for
+an rpkid instance, but is a bit simpler, as pubd does not provide
+hosting in the same sense that rpkid does: pubd is a relatively
+simple server that publishes objects as instructed by its clients.
+
+Here's a simplified picture of what the BPKI might look like for a
+pubd operator that serves two clients, "Alice" and "Bob":
+
+[[Image(pubd-bpki.png)]]
+
+While it is likely that RIRs (at least) will operate both rpkid and
+pubd instances, the two functions are conceptually separate.  As far
+as pubd is concerned, it doesn't matter who operates the rpkid
+instance: pubd just has clients, each of which has trust material
+that has been cross-certified into pubd's BPKI.  Similarly, rpkid
+doesn't really care who operates a pubd instance that it's been
+configured to use, it just treats that pubd as a foreign BPKI whose
+trust material has to be cross-certified into its own BPKI.  Cross
+certification itself is done by the back end operator, using
+cross_certify or some equivalent tool; the resulting BPKI
+certificates are configured into rpkid and pubd via the left-right
+protocol and the control subprotocol of the publication protocol,
+respectively.
+
+Because the BPKI tree is almost entirely controlled by the operating
+entity, CRLs are not necessary for most of the BPKI.  The one
+exception to this is the EE certificates issued under the
+cross-certification points.  These EE certificates are generated by
+the peer, not the local operator, and thus require CRLs.  Because of
+this, both rpkid and pubd require regular updates of certain BPKI
+CRLs, again via the left-right and publication control protocols.
+
+Because the left-right protocol and the publication control
+subprotocol are used to configure BPKI certificates and CRLs, they
+cannot themselves use certificates and CRLs configured in this way.
+This is why the configuration files for rpkid and pubd require
+static configuration of the left-right and publication control
+certificates.
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration
new file mode 100644
index 00000000..410215d8
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration
@@ -0,0 +1,263 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= Configuring the RPKI CA tools: `rpki.conf` =

+

+This section describes `rpki.conf`, the the configuration file for the

+RPKI CA tools.

+

+The first subsection is a quick summary of the options you're most

+likely to need to configure (or at least check) for a basic setup.

+

+The rest of this section contains a more complete reference to the

+configuration file and some of the things you might need to do with it

+if your needs are more complex.

+

+There are a lot of configuration options, but in most cases you will

+never have to touch more than a few of them.  Keep reading, and don't

+panic.

+

+== Quick guide to the most common configuration options ==

+

+This subsection describes only a handful of `rpki.conf` configuration

+options.  These are the ones you'll need to set, or at least check, as

+part of initial installation.  In general, the installation process

+will have already set sane values for these, but you may need to a few

+of them depending on exactly what you're doing.

+

+The location of `rpki.conf` varies depending on the operating system

+you're running and how you installed the software.  Unless you did

+something unusual during installation, it's either `/etc/rpki.conf` or

+`/usr/local/etc/rpki.conf`.

+

+{{{

+#!comment

+

+Should we even discuss `handle` here?  We no longer create any

+ResourceHolderCA automatically, so it's almost irrelevant at this

+point, and we'd like to get rid of it eventually.  Leave it out for

+now and see if anybody complains, I guess.

+

+}}}

+

+* All of the configuration options you're most likely to need to change

+  are in the `[myrpki]` section of `rpki.conf`.

+

+  {{{

+  #!ini

+  [myrpki]

+  }}}

+

+* You need to check the setting of `rpkid_server_host`.  The

+  installation process sets this to the fully-qualified DNS hostname

+  of the server on which you installed the code, but if you use a

+  service-specific DNS name for RPKI service you will need to change

+  this option to match that service name.

+

+  {{{

+  #!ini

+  rpkid_server_host               = rpkid.example.org

+  }}}

+

+* You need to set the value of `run_pubd` to reflect whether you

+  intend to run your own RPKI publication server and rsync server.

+

+  {{{

+  #!ini

+  run_pubd                        = yes

+  }}}

+

+  or

+

+  {{{

+  #!ini

+  run_pubd                        = no

+  }}}

+

+* If you are running your own RPKI publication server, you need to

+  check the setting of `pubd_server_host`.  The installation process

+  sets this to the fully-qualified DNS hostname of the server on which

+  you installed the code, but if you use a service-specific DNS name

+  for RPKI publication service you will need to change this option to

+  match that service name.

+

+  {{{

+  #!ini

+  pubd_server_host                = pubd.example.org

+  }}}

+

+

+There are //many// other configuration options, but setting the above

+correctly should suffice to get you started with the default

+configuration.  Read on for details if you need to know more,

+otherwise go to [[#nextsteps|next steps]].

+

+

+== Configuration file syntax == #syntax

+

+The general format of `rpki.conf` is the same as the configuration

+language used by many other programs, including the OpenSSL package.

+The file is divided into "sections", labeled with square brackets;

+individual options within a section look like variable assignments,

+with the option name on the left and the option value on the right.

+

+{{{

+#!ini

+[foo]

+

+bar = fred

+baz = 42

+}}}

+

+The configuration file parser supports a limited version of the macro

+facility used in OpenSSL's configuration parser.  An expression such

+as

+

+{{{

+#!ini

+foo = ${bar::baz}

+}}}

+

+sets foo to the value of the baz variable from section

+bar.

+

+The section name `ENV` is special: it refers to environment variables.

+

+{{{

+#!ini

+home = ${ENV::HOME}

+}}}

+

+Each of the programs that make up the RPKI tookit can potentially take

+its own configuration file, but for most uses this is unnecessarily

+complicated.  The recommended approach is to use a single

+configuration file, and to put all of the parameters that a normal

+user might need to change into a single section of that configuration

+file, then reference these common settings from the program-specific

+sections of the configuration file via macro expansion.

+

+The default name for the shared configuration file is `rpki.conf`.

+The location of the system-wide `rpki.conf` file is selected by

+`./configure` during installation.  The default location is

+`/usr/local/etc/rpki.conf` when building from source or on platforms

+like FreeBSD or MacOSX where packaged software goes in the

+`/usr/local` tree; on GNU/Linux platforms, binary packages will use

+`/etc/rpki.conf` per GNU/Linux convention.

+

+Regardless of the default location, you can override the build-time

+default filename at runtime if necessary by setting the `RPKI_CONF`

+environment variable to the name of the configuration file you want to

+use.  Most of the programs also take a command-line option (generally

+"`-c`") specifying the name of the configuration file; if both the

+command line option and the environment variable are set, the command

+line option wins.

+

+The installation process builds a sample configuration file

+`rpki.conf.sample` and installs it alongside of `rpki.conf`.  If you

+have no `rpki.conf` installed, the installation process will copy

+`rpki.conf.sample` to `rpki.conf`, but it will not overwrite an

+existing `rpki.conf` file.

+

+== Too much information about `rpki.conf` options ==

+

+The list of options that you can set in `rpki.conf` is ridiculously

+long.  The default configuration includes what we hope are reasonable

+default settings for all of them, so in many cases you will never need

+to know about most of these options.  A number of the options for

+individual programs are specified in terms of other options, using the

+macro facility [[#syntax|described above]].

+

+In general, if you don't understand what an option does, you probably

+should leave it alone.

+

+Detailed information about individual options is listed in separate

+sections, one per section of `rpki.conf`.  These documentation

+sections are generated from the same source file as the sample

+configuration file.

+

+{{{

+#!comment

+

+See notes in doc/RPKI/TOC about the format of link labels containing

+square brackets like rpki.conf section names, and be careful here,

+because the syntax is somewhat finicky.

+

+}}}

+

+* [[wiki:doc/RPKI/CA/Configuration/Common|	Common Options		]]

+* [[wiki:doc/RPKI/CA/Configuration/myrpki|	[myrpki] section        ]]

+* [[wiki:doc/RPKI/CA/Configuration/rpkid|	[rpkid] section         ]]

+* [[wiki:doc/RPKI/CA/Configuration/irdbd|	[irdbd] section         ]]

+* [[wiki:doc/RPKI/CA/Configuration/pubd|	[pubd] section          ]]

+* [[wiki:doc/RPKI/CA/Configuration/rootd|	[rootd] section         ]]

+* [[wiki:doc/RPKI/CA/Configuration/web_portal|	[web_portal] section    ]]

+* [[wiki:doc/RPKI/CA/Configuration/autoconf|	[autoconf] section      ]]

+

+{{{

+#!comment

+

+Still have to write subsections linking to:

+

+       * [wiki:doc/RPKI/CA/Configuration/CreatingRoot   Creating a RPKI Root Certificate]

+       * [wiki:doc/RPKI/CA/Configuration/Tests          Test configuration]

+       * [wiki:doc/RPKI/CA/Configuration/DifferentServer Using Different Servers]

+

+}}}

+

+== rsyncd.conf ==

+

+If you're running pubd, you'll also need to run rsyncd.  Your rsyncd

+configuration will need to match your pubd configuration in order for

+relying parties to find the RPKI objects managed by pubd.

+

+Here's a sample rsyncd.conf file:

+

+{{{

+#!ini

+pid file        = /var/run/rsyncd.pid

+uid             = nobody

+gid             = nobody

+

+[rpki]

+    use chroot          = no

+    read only           = yes

+    transfer logging    = yes

+    path                = /some/where/publication

+    comment             = RPKI publication

+}}}

+

+You may need to adapt this to your system.  In particular, you will

+need to set the `path` option to match the directory you named as

+`publication_base_directory` in `rpki.conf`.

+

+You may need to do something more complicated if you are already

+running rsyncd for other purposes.  See the `rsync(1)` and

+`rsyncd.conf(5)` manual pages for more details.

+

+== Running your own RPKI root ==

+

+In general, we do not recommend running your own RPKI root

+environment, for various reasons.  If, however, you need to do so, you

+should read

+[[wiki:doc/RPKI/CA/Configuration/rootd| the documentation for the [rootd] section ]],

+and

+[[wiki:doc/RPKI/CA/Configuration/CreatingRoot| the instructions for creating a RPKI root certificate ]].

+

+== Running rpkid or pubd on a different server ==

+

+The default configuration runs rpkid, pubd (if enabled) and the back

+end code all on the same server.  For most purposes, this is fine, but

+in some cases you might want to split these functions up among

+different servers.  If you need to do this, see

+[wiki:doc/RPKI/CA/Configuration/DifferentServer these instructions].

+

+== Configuring the test harness ==

+

+We expect the test harness to be of interest primarily to developers,

+but if you need to understand how it works, you will probably want to read

+[wiki:doc/RPKI/CA/Configuration/Tests these instructions].

+

+== Next steps == #nextsteps

+

+Once you've finished with configuration, the next thing you should

+read is the [[MySQLSetup|MySQL setup instructions]].

diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FCommon b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FCommon
new file mode 100644
index 00000000..2b1d3163
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FCommon
@@ -0,0 +1,63 @@
+= RPKI Engine Common Configuration Options =
+
+[[TracNav(doc/RPKI/TOC)]]
+
+Some of the configuration options are common to all of the daemons.
+Which daemon they affect depends only on which sections of which
+configuration file they are in.
+
+The first group of options are boolean flags, which can be set to
+"true" or "false".  If not specified, default values will be chosen
+(generally false).  Many of these flags controll debugging code that
+is probably of interest only to the developers.
+
+debug_http::
+	Enable verbose http debug logging.
+
+want_persistent_client::
+	Enable http 1.1 persistence, client side.
+
+want_persistent_server::
+	Enable http 1.1 persistence, server side.
+
+use_adns::
+	Use asynchronous DNS code.  Enabling this will raise an
+	exception if the dnspython toolkit is not installed.
+	Asynchronous DNS is an experimental feature intended to allow
+	higher throughput on busy servers; if you don't know why you
+	need it, you probably don't.
+
+enable_ipv6_clients::
+	Enable IPv6 HTTP client code.
+
+enable_ipv6_servers::
+	Enable IPv6 HTTP server code.  On by default, since listening
+	for IPv6 connections is usually harmless.
+
+debug_cms_certs::
+	Enable verbose logging about CMS certificates.
+
+sql_debug::
+	Enable verbose logging about sql operations.
+
+gc_debug::
+	Enable scary garbage collector debugging.
+
+timer_debug::
+	Enable verbose logging of timer system.
+
+enable_tracebacks::
+	Enable Python tracebacks in logs.
+
+
+There are also a few options which allow you to save CMS messages for
+audit or debugging.  The save format is a simple MIME encoding in a
+{{http://en.wikipedia.org/wiki/Maildir|Maildir}-format mailbox.  The
+current options are very crude, at some point we may provide finer
+grain controls.
+
+dump_outbound_cms::
+	Dump verbatim copies of CMS messages we send to this mailbox.
+
+dump_inbound_cms::
+	Dump verbatim copies of CMS messages we receive to this mailbox.
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FCreatingRoot b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FCreatingRoot
new file mode 100644
index 00000000..2661a111
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FCreatingRoot
@@ -0,0 +1,143 @@
+[[TracNav(doc/RPKI/TOC)]]

+

+= Creating an RPKI Root Certificate =

+

+[wiki:doc/RPKI/CA/Configuration/rootd rootd] does not create RPKI root

+certificates automatically.  If you're running your own root, you have

+to do this yourself.  The usual method of doing this is to use the

+OpenSSL command line tool.  The exact details will depend on which

+resources you need to put in the root certificate, the URIs for your

+publication server, and so forth, but the general form looks something

+like this:

+

+{{{

+#!ini

+[req]

+default_bits            = 2048

+default_md              = sha256

+distinguished_name      = req_dn

+prompt                  = no

+encrypt_key             = no

+

+[req_dn]

+CN                      = Testbed RPKI root certificate

+

+[x509v3_extensions]

+basicConstraints        = critical,CA:true

+subjectKeyIdentifier    = hash

+keyUsage                = critical,keyCertSign,cRLSign

+subjectInfoAccess       = @sia

+certificatePolicies     = critical,1.3.6.1.5.5.7.14.2

+sbgp-autonomousSysNum   = critical,@rfc3779_asns

+sbgp-ipAddrBlock        = critical,@rfc3997_addrs

+

+[sia]

+1.3.6.1.5.5.7.48.5;URI  = rsync://example.org/rpki/root/

+1.3.6.1.5.5.7.48.10;URI = rsync://example.org/rpki/root/root.mft

+

+[rfc3779_asns]

+AS.0 = 64496-64511

+AS.1 = 65536-65551

+

+[rfc3997_addrs]

+IPv4.0 = 192.0.2.0/24

+IPv4.1 = 198.51.100.0/24

+IPv4.2 = 203.0.113.0/24 

+IPv6.0 = 2001:0DB8::/32

+}}}

+

+Assuming you save this configuration in a file `root.conf`, you can

+use it to generate a root certificate as follows:

+

+{{{

+#!sh

+#!/bin/sh -

+

+# Generate the root key if it doesn't already exist.

+test -f root.key ||

+openssl genrsa -out root.key 2048

+

+# Generate the root certificate.

+openssl req                     \

+        -new                    \

+	-x509			\

+        -config root.conf       \

+        -key    root.key	\

+        -out    root.cer        \

+        -outform    DER         \

+        -days       1825        \

+	-set_serial 1		\

+        -extensions x509v3_extensions

+}}}

+

+You may want to shorten the five year expiration time (1825 days),

+which is a bit long.  It is a root certificate, so a long expiration

+is not unusual.

+

+When regenerating a certificate using the same key, just skip the

+`openssl genrsa` step above.

+

+You must copy the generated root.cer to the publication directory as

+defined in rpki.conf:

+

+{{{

+rpki-root-cert          = ${myrpki::publication_base_directory}/root.cer

+}}}

+

+You must place the generated root.key in a safe location where it is

+readable by rootd but not accessible to the outside world, then you

+need to tell rootd where to find it by setting the appropriate

+variable in rpki.conf.  The directory where the daemons keep their

+BPKI keys and certificates should be suitable for this:

+

+{{{

+rpki-root-key           = ${myrpki::bpki_servers_directory}/root.key

+}}}

+

+To create a TAL format trust anchor locator use the `make-tal.sh`

+script from `$top/rp/rcynic`:

+

+{{{

+#!sh

+$top/rp/rcynic/make-tal.sh  rsync://example.org/rpki/root/root.cer  root.cer

+}}}

+

+Note that, like any certificate, the root.cer you just generated will

+expire eventually.  Either you need to remember to regenerate it

+before that happens, or you need to set up a cron job to do that for

+you automatically.  Running the above shell script (really, just the

+`openssl req` command) should suffice to regenerate `root.cer`;

+remember to copy the updated `root.cer` to the publication directory.

+

+Regenerating the certificate does not require regenerating the TAL

+unless you change the key or URL.

+

+

+== Converting an existing RSA key from PKCS !#8 format ==

+

+If you previously generated a certificate using `openssl req` with the

+`-newkey` option and are having difficulty getting `rootd` to accept

+the resulting private key, the problem may be that OpenSSL saved the

+private key file in PKCS !#8 format.  OpenSSL's behavior changed here,

+the `-newkey` option saved the key in PKCS !#1 format, but newer

+versions use PKCS !#8.  While PKCS !#8 is indeed likely an

+improvement, the change confuses some programs, including versions

+of `rootd` from before we discovered this problem.

+

+If you think this might be your problem, you can convert the existing

+private key to PKCS !#1 format with a script like this:

+

+{{{

+#!sh

+if ! openssl rsa -in root.key -out root.key.new

+then

+    echo Conversion failed

+    rm root.key.new

+elif cmp -s root.key root.key.new

+    echo No change

+    rm root.key.new

+else

+    echo Converted

+    mv root.key.new root.key

+fi

+}}}

diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FDifferentServer b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FDifferentServer
new file mode 100644
index 00000000..3e31bc2b
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FDifferentServer
@@ -0,0 +1,69 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= Running rpkid or pubd on a different server =

+

+The default configuration runs rpkid, pubd (if enabled) and the back

+end code all on the same server.  For many purposes, this is fine, but

+in some cases you might want to split these functions up among

+different servers.

+

+As noted briefly above, there are two separate sets of rpki.conf

+options which control the necessary behavior: the `run_*` options

+and the `start_*` options.  The latter are usually tied to the

+former, but you can set them separately, and they control slightly

+different things: the `run_*` options control whether the back end

+code attempts to manage the servers in question, while the

+`start_*` flags control whether the startup scripts should start

+the servers in question.

+

+Here's a guideline to how to set up the servers on different machines.

+For purposes of this description we'll assume that you're running both

+rpkid and pubd, and that you want rpkid and pubd each on their own

+server, separate from the back end code.  We'll call these servers

+rpkid.example.org, pubd.example.org, and backend.example.org.

+

+Most of the configuration is the same as in the normal case, but there

+are a few extra steps.  The following supplements but does not replace

+the normal instructions.

+

+**WARNING**: These setup directions have not (yet) been tested

+extensively.

+

+* Create rpki.conf as usual on backend.example.org, but pay particular

+  attention to the settings of `rpkid_server_host`,

+  `irbe_server_host`, and `pubd_server_host`: these should

+  name rpkid.example.org, backend.example.org, and pubd.example.org,

+  respectively.

+

+* This example assumes that you're running pubd, so make sure that

+  both `run_rpkid` and `run_pubd` are enabled in rpki.conf.

+

+* Copy the rpki.conf to the other machines, and customize each copy to

+  that machine's role:

+  * `start_rpkid` should be enabled on rpkid.example.org and disabled on the others.

+  * `start_pubd` should be enabled on pubd.example.org and disabled on the others.

+  * `start_irdbd` should be enabled on backend.example.org and disabled on the others.

+

+* Make sure that you set up SQL databases on all three servers; the

+  `rpki-sql-setup` script should do the right thing in each case

+  based on the setting of the `start_*` options.

+

+* Run "rpkic initialize" on the back end host.  This will create the

+  BPKI and write out all of the necessary keys and certificates.

+

+* "rpkic initialize" should have created the BPKI files (.cer, .key,

+  and .crl files for the several servers).  Copy the .cer and .crl

+  files to the pubd and rpkid hosts, along with the appropriate

+  private key: rpkid.example.org should get a copy of the rpkid.key

+  file but not the pubd.key file, while pubd.example.org should get a

+  copy of the pubd.key file but not the rpkid.key file.

+

+* Run `rpki-start-servers` on each of the three hosts when it's

+  time to start the servers.

+

+* Do the usual setup dance, but keep in mind that the the back end

+  controlling all of these servers lives on backend.example.org, so

+  that's where you issue the rpkic or GUI commands to manage them.

+  rpkic and the GUI both know how to talk to rpkid and pubd over the

+  network, so managing them remotely is fine.

diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FTests b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FTests
new file mode 100644
index 00000000..8e349185
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FTests
@@ -0,0 +1,102 @@
+= smoketest.yaml =
+
+[[TracNav(doc/RPKI/TOC)]]
+
+smoketest test description file is named smoketest.yaml by default.
+Run smoketest with "-y filename" to change it.  The YAML file contains
+multiple YAML "documents".  The first document describes the initial
+test layout and resource allocations, subsequent documents describe
+modifications to the initial allocations and other parameters.
+Resources listed in the initial layout are aggregated automatically,
+so that a node in the resource hierarchy automatically receives the
+resources it needs to issue whatever its children are listed as
+holding.  Actions in the subsequent documents are modifications to the
+current resource set, modifications to validity dates or other
+non-resource parameters, or special commands like "sleep".
+
+Here's an example of current usage:
+
+{{{
+    name:           Alice
+    valid_for:      2d
+    sia_base:       "rsync://alice.example/rpki/"
+    kids:
+      - name: Bob
+     kids:
+       - name: Carol
+         ipv4: 192.0.2.1-192.0.2.33
+         asn:  64533
+    ---
+    - name: Carol
+      valid_add:   10
+    ---
+    - name: Carol
+      add_as: 33
+      valid_add:   2d
+    ---
+    - name: Carol
+      valid_sub:   2d
+    ---
+    - name: Carol
+      valid_for:   10d
+}}}
+
+This specifies an initial layout consisting of an RPKI engine named
+"Alice", with one child "Bob", which in turn has one child "Carol".
+Carol has a set of assigned resources, and all resources in the system
+are initially set to be valid for two days from the time at which the
+test is started.  The first subsequent document adds ten seconds to
+the validity interval for Carol's resources and makes no other
+modifications.  The second subsequent document grants Carol additional
+resources and adds another two days to the validity interval for
+Carol's resources.  The next document subtracts two days from the
+validity interval for Carol's resources.  The final document sets the
+validity interval for Carol's resources to ten days.
+
+Operators in subsequent (update) documents:
+
+add_as::
+             Add ASN resources.
+
+add_v4::
+             Add IPv4 resources.
+
+add_v6::
+             Add IPv6 resources.
+
+sub_as::
+             Subtract ASN resources.
+
+sub_v4::
+             Subtract IPv4 resources.
+
+sub_v6::
+             Subtract IPv6 resources.
+
+valid_until::
+             Set an absolute expiration date.
+
+valid_for::
+             Set a relative expiration date.
+
+valid_add::
+             Add to validity interval.
+
+valid_sub::
+             Subtract from validity interval.
+
+sleep [interval]::
+             Sleep for specified interval, or until smoketest receives a SIGALRM signal.
+
+shell cmd...::
+             Pass rest of line verbatim to /bin/sh and block until the shell returns.
+
+Absolute timestamps should be in the form shown (UTC timestamp format
+as used in XML).
+
+Intervals ({{{valid_add}}}, {{{valid_sub}}}, {{{valid_for}}}, {{{sleep)}}} are either
+integers, in which case they're interpreted as seconds, or are a
+string of the form "wD xH yM zS" where w, x, y, and z are integers and
+D, H, M, and S indicate days, hours, minutes, and seconds.  In the
+latter case all of the fields are optional, but at least one must be
+specified.  For example, "3D4H" means "three days plus four hours".
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fautoconf b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fautoconf
new file mode 100644
index 00000000..6a07de8c
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fautoconf
@@ -0,0 +1,43 @@
+{{{
+#!comment
+
+******************************************************************************
+THIS PAGE WAS GENERATED AUTOMATICALLY, DO NOT EDIT.
+
+Generated from $Id: rpki-confgen.xml 6070 2015-03-23 18:04:06Z melkins $
+            by $Id: rpki-confgen 5856 2014-05-31 18:32:19Z sra $
+******************************************************************************
+
+}}}
+[[TracNav(doc/RPKI/TOC)]]
+[[PageOutline]]
+
+= [autoconf] section = #autoconf
+
+rpki-confgen --autoconf records the current autoconf settings here, so
+that other options can refer to them. The section name "autoconf" is
+magic, don't change it.
+
+== bindir == #bindir
+
+Usually /usr/bin or /usr/local/bin.
+
+No default value.
+
+== datarootdir == #datarootdir
+
+Usually /usr/share or /usr/local/share.
+
+No default value.
+
+== sbindir == #sbindir
+
+Usually /usr/sbin or /usr/local/sbin.
+
+No default value.
+
+== sysconfdir == #sysconfdir
+
+Usually /etc or /usr/local/etc.
+
+No default value.
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Firdbd b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Firdbd
new file mode 100644
index 00000000..6992e48e
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Firdbd
@@ -0,0 +1,76 @@
+{{{
+#!comment
+
+******************************************************************************
+THIS PAGE WAS GENERATED AUTOMATICALLY, DO NOT EDIT.
+
+Generated from $Id: rpki-confgen.xml 6070 2015-03-23 18:04:06Z melkins $
+            by $Id: rpki-confgen 5856 2014-05-31 18:32:19Z sra $
+******************************************************************************
+
+}}}
+[[TracNav(doc/RPKI/TOC)]]
+[[PageOutline]]
+
+= [irdbd] section = #irdbd
+
+irdbd's default configuration file is the system `rpki.conf` file.
+Start irdbd with "`-c filename`" to choose a different configuration
+file. All options are in the "`[irdbd]`" section.
+
+Since irdbd is part of the back-end system, it has direct access to
+the back-end's SQL database, and thus is able to pull its own BPKI
+configuration directly from the database, and thus needs a bit less
+configuration than the other daemons.
+
+== sql-database == #sql-database
+
+MySQL database name for irdbd.
+
+{{{
+#!ini
+sql-database = ${myrpki::irdbd_sql_database}
+}}}
+
+== sql-username == #sql-username
+
+MySQL user name for irdbd.
+
+{{{
+#!ini
+sql-username = ${myrpki::irdbd_sql_username}
+}}}
+
+== sql-password == #sql-password
+
+MySQL password for irdbd.
+
+{{{
+#!ini
+sql-password = ${myrpki::irdbd_sql_password}
+}}}
+
+== server-host == #server-host
+
+Host on which irdbd should listen for HTTP service requests.
+
+{{{
+#!ini
+server-host = ${myrpki::irdbd_server_host}
+}}}
+
+== server-port == #server-port
+
+Port on which irdbd should listen for HTTP service requests.
+
+{{{
+#!ini
+server-port = ${myrpki::irdbd_server_port}
+}}}
+
+== startup-message == #startup-message
+
+String to log on startup, useful when debugging a collection of irdbd
+instances at once.
+
+No default value.
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fmyrpki b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fmyrpki
new file mode 100644
index 00000000..d5611841
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fmyrpki
@@ -0,0 +1,413 @@
+{{{
+#!comment
+
+******************************************************************************
+THIS PAGE WAS GENERATED AUTOMATICALLY, DO NOT EDIT.
+
+Generated from $Id: rpki-confgen.xml 6070 2015-03-23 18:04:06Z melkins $
+            by $Id: rpki-confgen 5856 2014-05-31 18:32:19Z sra $
+******************************************************************************
+
+}}}
+[[TracNav(doc/RPKI/TOC)]]
+[[PageOutline]]
+
+= [myrpki] section = #myrpki
+
+The "`[myrpki]`" section contains all the parameters that you really
+need to configure. The name "`myrpki`" is historical and may change in
+the future.
+
+== handle == #handle
+
+Every resource-holding or server-operating entity needs a "handle",
+which is just an identifier by which the entity calls itself. Handles
+do not need to be globally unique, but should be chosen with an eye
+towards debugging operational problems: it's best if you use a handle
+that your parents and children will recognize as being you.
+
+The "`handle`" option in the "`[myrpki]`" section specifies the
+default handle for this installation. Previous versions of the CA
+tools required a separate configuration file, each with its own handle
+setting, for each hosted entity. The current code allows the current
+handle to be selected at runtime in both the GUI and command line user
+interface tools, so the handle setting here is just the default when
+you don't set one explictly. In the long run, this option may go away
+entirely, but for now you need to set this.
+
+Syntax is an identifier (ASCII letters, digits, hyphen, underscore --
+no whitespace, non-ASCII characters, or other punctuation).
+
+No default value.
+
+== bpki_servers_directory == #bpki_servers_directory
+
+Directory for BPKI files generated by rpkic and used by rpkid and
+pubd. You will not normally need to change this.
+
+{{{
+#!ini
+bpki_servers_directory = ${autoconf::datarootdir}/rpki
+}}}
+
+== run_rpkid == #run_rpkid
+
+Whether you want to run your own copy of rpkid (and irdbd). Leave this
+alone unless you're doing something unusual like running a pubd-only
+installation.
+
+{{{
+#!ini
+run_rpkid = yes
+}}}
+
+== rpkid_server_host == #rpkid_server_host
+
+DNS hostname for rpkid. In most cases, this must resolve to a
+publicly-reachable address to be useful, as your RPKI children will
+need to contact your rpkid at this address.
+
+No default value.
+
+== rpkid_server_port == #rpkid_server_port
+
+Server port number for rpkid. This can be any legal TCP port number
+that you're not using for something else.
+
+{{{
+#!ini
+rpkid_server_port = 4404
+}}}
+
+== irdbd_server_host == #irdbd_server_host
+
+DNS hostname for irdbd, or "`localhost`". This should be "`localhost`"
+unless you really know what you are doing.
+
+{{{
+#!ini
+irdbd_server_host = localhost
+}}}
+
+== irdbd_server_port == #irdbd_server_port
+
+Server port number for irdbd. This can be any legal TCP port number
+that you're not using for something else.
+
+{{{
+#!ini
+irdbd_server_port = 4403
+}}}
+
+== run_pubd == #run_pubd
+
+Whether you want to run your own copy of pubd. In general, it's best
+to use your parent's pubd if your parent allows you to do so, because
+this will reduce the overall number of publication sites from which
+relying parties will need to retrieve data. However, not all parents
+offer publication service, or you may need to run pubd yourself for
+reliability reasons, or because you're certifying private address
+space or private Autonomous System Numbers.
+
+The out of band setup protocol will attempt to negotiate publication
+service for you with whatever publication service your parent is
+using, if it can and if you let it.
+
+{{{
+#!ini
+run_pubd = yes
+}}}
+
+== pubd_server_host == #pubd_server_host
+
+DNS hostname for pubd, if you're running it. This must resolve to a
+publicly reachable address to be useful.
+
+No default value.
+
+== pubd_server_port == #pubd_server_port
+
+Server port number for pubd. This can be any legal TCP port number
+that you're not using for something else.
+
+{{{
+#!ini
+pubd_server_port = 4402
+}}}
+
+== pubd_contact_info == #pubd_contact_info
+
+Contact information to include in offers of repository service. This
+only matters when you're running pubd. This should be a human readable
+string, perhaps containing an email address or URL.
+
+No default value.
+
+== run_rootd == #run_rootd
+
+Whether you want to run your very own copy of rootd. Don't enable this
+unless you really know what you're doing.
+
+{{{
+#!ini
+run_rootd = no
+}}}
+
+== rootd_server_host == #rootd_server_host
+
+DNS hostname for rootd, if you're running it. This should be localhost
+unless you really know what you are doing.
+
+{{{
+#!ini
+rootd_server_host = localhost
+}}}
+
+== rootd_server_port == #rootd_server_port
+
+Server port number for rootd, if you're running it. This can be any
+legal TCP port number that you're not using for something else.
+
+{{{
+#!ini
+rootd_server_port = 4401
+}}}
+
+== publication_base_directory == #publication_base_directory
+
+Root of local directory tree where pubd should write out published
+data. You need to configure this, and the configuration should match
+up with the directory where you point rsyncd. Neither pubd nor rsyncd
+much cares //where// you tell it to put this stuff, the important
+thing is that the rsync URIs in generated certificates match up with
+the published objects so that relying parties can find and verify
+rpkid's published outputs.
+
+{{{
+#!ini
+publication_base_directory = ${autoconf::datarootdir}/rpki/publication
+}}}
+
+== publication_root_cert_directory == #publication_root_cert_directory
+
+Root of local directory tree where rootd (sigh) should write out
+published data. This is just like publication_base_directory, but
+rootd is too dumb to use pubd and needs its own directory in which to
+write one certificate, one CRL, and one manifest. Neither rootd nor
+rsyncd much cares //where// you tell them to put this stuff, the
+important thing is that the rsync URIs in generated certificates match
+up with the published objects so that relying parties can find and
+verify rootd's published outputs.
+
+{{{
+#!ini
+publication_root_cert_directory = ${myrpki::publication_base_directory}.root
+}}}
+
+== publication_rsync_module == #publication_rsync_module
+
+rsyncd module name corresponding to publication_base_directory. This
+has to match the module you configured into `rsyncd.conf`. Leave this
+alone unless you have some need to change it.
+
+{{{
+#!ini
+publication_rsync_module = rpki
+}}}
+
+== publication_root_module == #publication_root_module
+
+rsyncd module name corresponding to publication_root_cert_directory.
+This has to match the module you configured into `rsyncd.conf`. Leave
+this alone unless you have some need to change it.
+
+{{{
+#!ini
+publication_root_module = root
+}}}
+
+== publication_rsync_server == #publication_rsync_server
+
+Hostname and optional port number for rsync URIs. In most cases this
+should just be the same value as pubd_server_host.
+
+{{{
+#!ini
+publication_rsync_server = ${myrpki::pubd_server_host}
+}}}
+
+== start_rpkid == #start_rpkid
+
+rpkid startup control. This should usually have the same value as
+run_rpkid: the only case where you would want to change this is when
+you are running the back-end code on a different machine from one or
+more of the daemons, in which case you need finer control over which
+daemons to start on which machines. In such cases, run_rpkid controls
+whether the back-end code is doing things to manage rpkid, while
+start_rpkid controls whether rpki-start-servers attempts to start
+rpkid on this machine.
+
+{{{
+#!ini
+start_rpkid = ${myrpki::run_rpkid}
+}}}
+
+== start_irdbd == #start_irdbd
+
+irdbd startup control. This should usually have the same value as
+run_rpkid: the only case where you would want to change this is when
+you are running the back-end code on a different machine from one or
+more of the daemons, in which case you need finer control over which
+daemons to start on which machines. In such cases, run_rpkid controls
+whether the back-end code is doing things to manage rpkid, while
+start_irdbd controls whether rpki-start-servers attempts to start
+irdbd on this machine.
+
+{{{
+#!ini
+start_irdbd = ${myrpki::run_rpkid}
+}}}
+
+== start_pubd == #start_pubd
+
+pubd startup control. This should usually have the same value as
+run_pubd: the only case where you would want to change this is when
+you are running the back-end code on a different machine from one or
+more of the daemons, in which case you need finer control over which
+daemons to start on which machines. In such cases, run_pubd controls
+whether the back-end code is doing things to manage pubd, while
+start_pubd controls whether rpki-start-servers attempts to start pubd
+on this machine.
+
+{{{
+#!ini
+start_pubd = ${myrpki::run_pubd}
+}}}
+
+== start_rootd == #start_rootd
+
+rootd startup control. This should usually have the same value as
+run_rootd: the only case where you would want to change this is when
+you are running the back-end code on a different machine from one or
+more of the daemons, in which case you need finer control over which
+daemons to start on which machines. In such cases, run_rootd controls
+whether the back-end code is doing things to manage rootd, while
+start_rootd controls whether rpki-start-servers attempts to start
+rootd on this machine.
+
+{{{
+#!ini
+start_rootd = ${myrpki::run_rootd}
+}}}
+
+== shared_sql_username == #shared_sql_username
+
+If you're comfortable with having all of the databases use the same
+MySQL username, set that value here. The default setting of this
+variable should be fine.
+
+{{{
+#!ini
+shared_sql_username = rpki
+}}}
+
+== shared_sql_password == #shared_sql_password
+
+If you're comfortable with having all of the databases use the same
+MySQL password, set that value here. You should use a locally
+generated password either here or in the individual settings below.
+The installation process generates a random value for this option,
+which satisfies this requirement, so ordinarily you should have no
+need to change this option.
+
+No default value.
+
+== rpkid_sql_database == #rpkid_sql_database
+
+SQL database name for rpkid's database. The default setting of this
+variable should be fine.
+
+{{{
+#!ini
+rpkid_sql_database = rpkid
+}}}
+
+== rpkid_sql_username == #rpkid_sql_username
+
+If you want to use a separate SQL username for rpkid's database, set
+it here.
+
+{{{
+#!ini
+rpkid_sql_username = ${myrpki::shared_sql_username}
+}}}
+
+== rpkid_sql_password == #rpkid_sql_password
+
+If you want to use a separate SQL password for rpkid's database, set
+it here.
+
+{{{
+#!ini
+rpkid_sql_password = ${myrpki::shared_sql_password}
+}}}
+
+== irdbd_sql_database == #irdbd_sql_database
+
+SQL database for irdbd's database. The default setting of this
+variable should be fine.
+
+{{{
+#!ini
+irdbd_sql_database = irdbd
+}}}
+
+== irdbd_sql_username == #irdbd_sql_username
+
+If you want to use a separate SQL username for irdbd's database, set
+it here.
+
+{{{
+#!ini
+irdbd_sql_username = ${myrpki::shared_sql_username}
+}}}
+
+== irdbd_sql_password == #irdbd_sql_password
+
+If you want to use a separate SQL password for irdbd's database, set
+it here.
+
+{{{
+#!ini
+irdbd_sql_password = ${myrpki::shared_sql_password}
+}}}
+
+== pubd_sql_database == #pubd_sql_database
+
+SQL database name for pubd's database. The default setting of this
+variable should be fine.
+
+{{{
+#!ini
+pubd_sql_database = pubd
+}}}
+
+== pubd_sql_username == #pubd_sql_username
+
+If you want to use a separate SQL username for pubd's database, set it
+here.
+
+{{{
+#!ini
+pubd_sql_username = ${myrpki::shared_sql_username}
+}}}
+
+== pubd_sql_password == #pubd_sql_password
+
+If you want to use a separate SQL password for pubd's database, set it
+here.
+
+{{{
+#!ini
+pubd_sql_password = ${myrpki::shared_sql_password}
+}}}
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fpubd b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fpubd
new file mode 100644
index 00000000..87dbb538
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fpubd
@@ -0,0 +1,123 @@
+{{{
+#!comment
+
+******************************************************************************
+THIS PAGE WAS GENERATED AUTOMATICALLY, DO NOT EDIT.
+
+Generated from $Id: rpki-confgen.xml 6070 2015-03-23 18:04:06Z melkins $
+            by $Id: rpki-confgen 5856 2014-05-31 18:32:19Z sra $
+******************************************************************************
+
+}}}
+[[TracNav(doc/RPKI/TOC)]]
+[[PageOutline]]
+
+= [pubd] section = #pubd
+
+pubd's default configuration file is the system `rpki.conf` file.
+Start pubd with "`-c filename`" to choose a different configuration
+file. All options are in the "`[pubd]`" section. BPKI certificates and
+keys may be either DER or PEM format.
+
+== sql-database == #sql-database
+
+MySQL database name for pubd.
+
+{{{
+#!ini
+sql-database = ${myrpki::pubd_sql_database}
+}}}
+
+== sql-username == #sql-username
+
+MySQL user name for pubd.
+
+{{{
+#!ini
+sql-username = ${myrpki::pubd_sql_username}
+}}}
+
+== sql-password == #sql-password
+
+MySQL password for pubd.
+
+{{{
+#!ini
+sql-password = ${myrpki::pubd_sql_password}
+}}}
+
+== publication-base == #publication-base
+
+Root of directory tree where pubd should write out published data. You
+need to configure this, and the configuration should match up with the
+directory where you point rsyncd. Neither pubd nor rsyncd much cares
+-where- you tell them to put this stuff, the important thing is that
+the rsync URIs in generated certificates match up with the published
+objects so that relying parties can find and verify rpkid's published
+outputs.
+
+{{{
+#!ini
+publication-base = ${myrpki::publication_base_directory}
+}}}
+
+== server-host == #server-host
+
+Host on which pubd should listen for HTTP service requests.
+
+{{{
+#!ini
+server-host = ${myrpki::pubd_server_host}
+}}}
+
+== server-port == #server-port
+
+Port on which pubd should listen for HTTP service requests.
+
+{{{
+#!ini
+server-port = ${myrpki::pubd_server_port}
+}}}
+
+== bpki-ta == #bpki-ta
+
+Where pubd should look for the BPKI trust anchor. All BPKI certificate
+verification within pubd traces back to this trust anchor. Don't
+change this unless you really know what you are doing.
+
+{{{
+#!ini
+bpki-ta = ${myrpki::bpki_servers_directory}/ca.cer
+}}}
+
+== pubd-cert == #pubd-cert
+
+Where pubd should look for its own BPKI EE certificate. Don't change
+this unless you really know what you are doing.
+
+{{{
+#!ini
+pubd-cert = ${myrpki::bpki_servers_directory}/pubd.cer
+}}}
+
+== pubd-key == #pubd-key
+
+Where pubd should look for the private key corresponding to its own
+BPKI EE certificate. Don't change this unless you really know what you
+are doing.
+
+{{{
+#!ini
+pubd-key = ${myrpki::bpki_servers_directory}/pubd.key
+}}}
+
+== irbe-cert == #irbe-cert
+
+Where pubd should look for the back-end control client's BPKI EE
+certificate. Don't change this unless you really know what you are
+doing.
+
+{{{
+#!ini
+irbe-cert = ${myrpki::bpki_servers_directory}/irbe.cer
+}}}
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frootd b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frootd
new file mode 100644
index 00000000..172460cf
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frootd
@@ -0,0 +1,216 @@
+{{{
+#!comment
+
+******************************************************************************
+THIS PAGE WAS GENERATED AUTOMATICALLY, DO NOT EDIT.
+
+Generated from $Id: rpki-confgen.xml 6070 2015-03-23 18:04:06Z melkins $
+            by $Id: rpki-confgen 5856 2014-05-31 18:32:19Z sra $
+******************************************************************************
+
+}}}
+[[TracNav(doc/RPKI/TOC)]]
+[[PageOutline]]
+
+= [rootd] section = #rootd
+
+You don't need to run rootd unless you're IANA, are certifying private
+address space, or are an RIR which refuses to accept IANA as the root
+of the public address hierarchy.
+
+Ok, if that wasn't enough to scare you off: rootd is a mess, and needs
+to be rewritten, or, better, merged into rpkid. It doesn't use the
+publication protocol, and it requires far too many configuration
+parameters.
+
+rootd was originally intended to be a very simple program which
+simplified rpkid enormously by moving one specific task (acting as the
+root CA of an RPKI certificate hierarchy) out of rpkid. As the
+specifications and code (mostly the latter) have evolved, however,
+this task has become more complicated, and rootd would have to become
+much more complicated to keep up.
+
+Don't run rootd unless you're sure that you need to do so.
+
+Still think you need to run rootd? OK, but remember, you have been
+warned....
+
+rootd's default configuration file is the system `rpki.conf` file.
+Start rootd with "`-c filename`" to choose a different configuration
+file. All options are in the "`[rootd]`" section. Certificates and
+keys may be in either DER or PEM format.
+
+== bpki-ta == #bpki-ta
+
+Where rootd should look for the BPKI trust anchor. All BPKI
+certificate verification within rootd traces back to this trust
+anchor. Don't change this unless you really know what you are doing.
+
+{{{
+#!ini
+bpki-ta = ${myrpki::bpki_servers_directory}/ca.cer
+}}}
+
+== rootd-bpki-crl == #rootd-bpki-crl
+
+BPKI CRL. Don't change this unless you really know what you are doing.
+
+{{{
+#!ini
+rootd-bpki-crl = ${myrpki::bpki_servers_directory}/ca.crl
+}}}
+
+== rootd-bpki-cert == #rootd-bpki-cert
+
+rootd's own BPKI EE certificate. Don't change this unless you really
+know what you are doing.
+
+{{{
+#!ini
+rootd-bpki-cert = ${myrpki::bpki_servers_directory}/rootd.cer
+}}}
+
+== rootd-bpki-key == #rootd-bpki-key
+
+Private key corresponding to rootd's own BPKI EE certificate. Don't
+change this unless you really know what you are doing.
+
+{{{
+#!ini
+rootd-bpki-key = ${myrpki::bpki_servers_directory}/rootd.key
+}}}
+
+== child-bpki-cert == #child-bpki-cert
+
+BPKI certificate for rootd's one and only up-down child (RPKI engine
+to which rootd issues an RPKI certificate). Don't change this unless
+you really know what you are doing.
+
+{{{
+#!ini
+child-bpki-cert = ${myrpki::bpki_servers_directory}/child.cer
+}}}
+
+== server-host == #server-host
+
+Server host on which rootd should listen.
+
+{{{
+#!ini
+server-host = ${myrpki::rootd_server_host}
+}}}
+
+== server-port == #server-port
+
+Server port on which rootd should listen.
+
+{{{
+#!ini
+server-port = ${myrpki::rootd_server_port}
+}}}
+
+== rpki-root-dir == #rpki-root-dir
+
+Where rootd should write its output. Yes, rootd should be using pubd
+instead of publishing directly, but it doesn't. This needs to match
+pubd's configuration.
+
+{{{
+#!ini
+rpki-root-dir = ${myrpki::publication_base_directory}
+}}}
+
+== rpki-base-uri == #rpki-base-uri
+
+rsync URI corresponding to directory containing rootd's outputs.
+
+{{{
+#!ini
+rpki-base-uri = rsync://${myrpki::publication_rsync_server}/${myrpki::publication_rsync_module}/
+}}}
+
+== rpki-root-cert-uri == #rpki-root-cert-uri
+
+rsync URI for rootd's root (self-signed) RPKI certificate.
+
+{{{
+#!ini
+rpki-root-cert-uri = rsync://${myrpki::publication_rsync_server}/${myrpki::publication_root_module}/root.cer
+}}}
+
+== rpki-root-key == #rpki-root-key
+
+Private key corresponding to rootd's root RPKI certificate.
+
+{{{
+#!ini
+rpki-root-key = ${myrpki::bpki_servers_directory}/root.key
+}}}
+
+== rpki-root-cert == #rpki-root-cert
+
+Filename (as opposed to rsync URI) of rootd's root RPKI certificate.
+
+{{{
+#!ini
+rpki-root-cert = ${myrpki::publication_root_cert_directory}/root.cer
+}}}
+
+== rpki-subject-pkcs10 == #rpki-subject-pkcs10
+
+Where rootd should stash a copy of the PKCS #10 request it gets from
+its one (and only) child
+
+{{{
+#!ini
+rpki-subject-pkcs10 = ${myrpki::bpki_servers_directory}/rootd.subject.pkcs10
+}}}
+
+== rpki-subject-lifetime == #rpki-subject-lifetime
+
+Lifetime of the one and only RPKI certificate rootd issues.
+
+{{{
+#!ini
+rpki-subject-lifetime = 30d
+}}}
+
+== rpki-root-crl == #rpki-root-crl
+
+Filename (relative to rootd-base-uri and rpki-root-dir) of the CRL for
+rootd's root RPKI certificate.
+
+{{{
+#!ini
+rpki-root-crl = root.crl
+}}}
+
+== rpki-root-manifest == #rpki-root-manifest
+
+Filename (relative to rootd-base-uri and rpki-root-dir) of the
+manifest for rootd's root RPKI certificate.
+
+{{{
+#!ini
+rpki-root-manifest = root.mft
+}}}
+
+== rpki-class-name == #rpki-class-name
+
+Up-down protocol class name for RPKI certificate rootd issues to its
+one (and only) child.
+
+{{{
+#!ini
+rpki-class-name = ${myrpki::handle}
+}}}
+
+== rpki-subject-cert == #rpki-subject-cert
+
+Filename (relative to rootd-base-uri and rpki-root-dir) of the one
+(and only) RPKI certificate rootd issues.
+
+{{{
+#!ini
+rpki-subject-cert = ${myrpki::handle}.cer
+}}}
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frpkid b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frpkid
new file mode 100644
index 00000000..211dc772
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frpkid
@@ -0,0 +1,129 @@
+{{{
+#!comment
+
+******************************************************************************
+THIS PAGE WAS GENERATED AUTOMATICALLY, DO NOT EDIT.
+
+Generated from $Id: rpki-confgen.xml 6070 2015-03-23 18:04:06Z melkins $
+            by $Id: rpki-confgen 5856 2014-05-31 18:32:19Z sra $
+******************************************************************************
+
+}}}
+[[TracNav(doc/RPKI/TOC)]]
+[[PageOutline]]
+
+= [rpkid] section = #rpkid
+
+rpkid's default config file is the system `rpki.conf` file. Start
+rpkid with "`-c filename`" to choose a different config file. All
+options are in the "`[rpkid]`" section. BPKI Certificates and keys may
+be in either DER or PEM format.
+
+== sql-database == #sql-database
+
+MySQL database name for rpkid.
+
+{{{
+#!ini
+sql-database = ${myrpki::rpkid_sql_database}
+}}}
+
+== sql-username == #sql-username
+
+MySQL user name for rpkid.
+
+{{{
+#!ini
+sql-username = ${myrpki::rpkid_sql_username}
+}}}
+
+== sql-password == #sql-password
+
+MySQL password for rpkid.
+
+{{{
+#!ini
+sql-password = ${myrpki::rpkid_sql_password}
+}}}
+
+== server-host == #server-host
+
+Host on which rpkid should listen for HTTP service requests.
+
+{{{
+#!ini
+server-host = ${myrpki::rpkid_server_host}
+}}}
+
+== server-port == #server-port
+
+Port on which rpkid should listen for HTTP service requests.
+
+{{{
+#!ini
+server-port = ${myrpki::rpkid_server_port}
+}}}
+
+== irdb-url == #irdb-url
+
+HTTP service URL rpkid should use to contact irdbd. If irdbd is
+running on the same machine as rpkid, this can and probably should be
+a loopback URL, since nobody but rpkid needs to talk to irdbd.
+
+{{{
+#!ini
+irdb-url = http://${myrpki::irdbd_server_host}:${myrpki::irdbd_server_port}/
+}}}
+
+== bpki-ta == #bpki-ta
+
+Where rpkid should look for the BPKI trust anchor. All BPKI
+certificate verification within rpkid traces back to this trust
+anchor. Don't change this unless you really know what you are doing.
+
+{{{
+#!ini
+bpki-ta = ${myrpki::bpki_servers_directory}/ca.cer
+}}}
+
+== rpkid-cert == #rpkid-cert
+
+Where rpkid should look for its own BPKI EE certificate. Don't change
+this unless you really know what you are doing.
+
+{{{
+#!ini
+rpkid-cert = ${myrpki::bpki_servers_directory}/rpkid.cer
+}}}
+
+== rpkid-key == #rpkid-key
+
+Where rpkid should look for the private key corresponding to its own
+BPKI EE certificate. Don't change this unless you really know what you
+are doing.
+
+{{{
+#!ini
+rpkid-key = ${myrpki::bpki_servers_directory}/rpkid.key
+}}}
+
+== irdb-cert == #irdb-cert
+
+Where rpkid should look for irdbd's BPKI EE certificate. Don't change
+this unless you really know what you are doing.
+
+{{{
+#!ini
+irdb-cert = ${myrpki::bpki_servers_directory}/irdbd.cer
+}}}
+
+== irbe-cert == #irbe-cert
+
+Where rpkid should look for the back-end control client's BPKI EE
+certificate. Don't change this unless you really know what you are
+doing.
+
+{{{
+#!ini
+irbe-cert = ${myrpki::bpki_servers_directory}/irbe.cer
+}}}
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fweb_portal b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fweb_portal
new file mode 100644
index 00000000..9df6487f
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fweb_portal
@@ -0,0 +1,73 @@
+{{{
+#!comment
+
+******************************************************************************
+THIS PAGE WAS GENERATED AUTOMATICALLY, DO NOT EDIT.
+
+Generated from $Id: rpki-confgen.xml 6070 2015-03-23 18:04:06Z melkins $
+            by $Id: rpki-confgen 5856 2014-05-31 18:32:19Z sra $
+******************************************************************************
+
+}}}
+[[TracNav(doc/RPKI/TOC)]]
+[[PageOutline]]
+
+= [web_portal] section = #web_portal
+
+Glue to allow the Django application to pull user configuration from
+this file rather than directly editing settings.py.
+
+== sql-database == #sql-database
+
+SQL database name the web portal should use.
+
+{{{
+#!ini
+sql-database = ${myrpki::irdbd_sql_database}
+}}}
+
+== sql-username == #sql-username
+
+SQL user name the web portal should use.
+
+{{{
+#!ini
+sql-username = ${myrpki::irdbd_sql_username}
+}}}
+
+== sql-password == #sql-password
+
+SQL password the web portal should use.
+
+{{{
+#!ini
+sql-password = ${myrpki::irdbd_sql_password}
+}}}
+
+== secret-key == #secret-key
+
+Site-specific secret key for Django.
+
+No default value.
+
+== allowed-hosts == #allowed-hosts
+
+Name of virtual host that runs the Django GUI, if this is not the same
+as the system hostname. Django's security code wants to know the name
+of the virtual host on which Django is running, and will fail when it
+thinks it's running on a disallowed host.
+
+If you get an error like "Invalid HTTP_HOST header (you may need to
+set ALLOWED_HOSTS)", you will need to set this option.
+
+No default value.
+
+== download-directory == #download-directory
+
+A directory large enough to hold the RouteViews.org routing table dump
+fetched by the rpkigui-import-routes script.
+
+{{{
+#!ini
+download-directory = /var/tmp
+}}}
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FMySQLSetup b/doc/wiki-dump/doc%2FRPKI%2FCA%2FMySQLSetup
new file mode 100644
index 00000000..13d88be1
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FMySQLSetup
@@ -0,0 +1,73 @@
+= RPKI Engine MySQL Setup =

+

+[[TracNav(doc/RPKI/TOC)]]

+

+You need to install MySQL and set up the relevant databases before

+starting rpkid, irdbd, or pubd.

+

+See the [[Installation|Installation Guide]] for details on

+where to download MySQL and find documentation on installing it.

+

+See the [[Configuration|Configuration Guide]] for details on

+the configuration file settings the daemons will use to find and

+authenticate themselves to their respective databases.

+

+Before you can (usefully) start any of the daemons, you will need to

+set up the MySQL databases they use.  You can do this by hand, or

+you can use the {{{rpki-sql-setup}}} script, which prompts you for your

+MySQL root password then attempts to do everything else

+automatically using values from rpki.conf.

+

+Using the script is simple:

+

+{{{

+#!sh

+$ rpki-sql-setup

+Please enter your MySQL root password:

+}}}

+

+The script should tell you what databases it creates.  You can use

+the -v option if you want to see more details about what it's doing.

+

+If you'd prefer to do the SQL setup manually, perhaps because you

+have valuable data in other MySQL databases and you don't want to

+trust some random setup script with your MySQL root password, you'll

+need to use the MySQL command line tool, as follows:

+

+{{{

+#!sh

+$ mysql -u root -p

+

+mysql> CREATE DATABASE irdb_database;

+mysql> GRANT all ON irdb_database.* TO irdb_user@localhost IDENTIFIED BY 'irdb_password';

+mysql> CREATE DATABASE rpki_database;

+mysql> GRANT all ON rpki_database.* TO rpki_user@localhost IDENTIFIED BY 'rpki_password';

+mysql> USE rpki_database;

+mysql> SOURCE $top/schemas/sql/rpkid.sql;

+mysql> COMMIT;

+mysql> quit

+}}}

+

+where {{{irdb_database}}}, {{{irdb_user}}}, {{{irdb_password}}},

+{{{rpki_database}}}, {{{rpki_user}}}, and {{{rpki_password}}} match

+the values you used in your configuration file.

+

+If you are running pubd and are doing manual SQL setup, you'll also

+have to do:

+

+{{{

+#!sh

+$ mysql -u root -p

+mysql> CREATE DATABASE pubd_database;

+mysql> GRANT all ON pubd_database.* TO pubd_user@localhost IDENTIFIED BY 'pubd_password';

+mysql> USE pubd_database;

+mysql> SOURCE $top/schemas/sql/pubd.sql;

+mysql> COMMIT;

+mysql> quit

+}}}

+

+where {{{pubd_database}}}, {{{pubd_user}}} {{{pubd_password}}} match the

+values you used in your configuration file.

+

+Once you've finished configuring MySQL, the next thing you should

+read is the instructions for the [[UI|user interface tools]].

diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FOOBSetup b/doc/wiki-dump/doc%2FRPKI%2FCA%2FOOBSetup
new file mode 100644
index 00000000..dde87608
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FOOBSetup
@@ -0,0 +1,6 @@
+= RPKI CA Out-Of-Band Setup Protocol =

+

+[[TracNav(doc/RPKI/TOC)]]

+

+Not documented yet.  Eventually this will be a readable explanation of

+the out-of-band setup protocol.

diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FLeftRight b/doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FLeftRight
new file mode 100644
index 00000000..0859c463
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FLeftRight
@@ -0,0 +1,473 @@
+= The Left-Right Protocol =
+
+[[TracNav(doc/RPKI/TOC)]]
+[[PageOutline]]
+
+The left-right protocol is really two separate client/server
+protocols over separate channels between the RPKI engine and the IR
+back end (IRBE).  The IRBE is the client for one of the
+subprotocols, the RPKI engine is the client for the other.
+
+== Operations initiated by the IRBE ==
+
+This part of the protcol uses a kind of message-passing.  Each object
+that the RPKI engine knows about takes five messages: "create", "set",
+"get", "list", and "destroy".  Actions which are not just data
+operations on objects are handled via an SNMP-like mechanism, as if
+they were fields to be set.  For example, to generate a keypair one
+"sets" the "generate-keypair" field of a BSC object, even though there
+is no such field in the object itself as stored in SQL.  This is a bit
+of a kludge, but the reason for doing it as if these were variables
+being set is to allow composite operations such as creating a BSC,
+populating all of its data fields, and generating a keypair, all as a
+single operation.  With this model, that's trivial, otherwise it's at
+least two round trips.
+
+Fields can be set in either "create" or "set" operations, the
+difference just being whether the object already exists.  A "get"
+operation returns all visible fields of the object.  A "list"
+operation returns a list containing what "get" would have returned on
+each of those objects.
+
+Left-right protocol objects are encoded as signed CMS messages
+containing XML as eContent and using an eContentType OID of {{{id-ct-xml}}}
+(1.2.840.113549.1.9.16.1.28).  These CMS messages are in turn passed
+as the data for HTTP POST operations, with an HTTP content type of
+"application/x-rpki" for both the POST data and the response data.
+
+All operations allow an optional "tag" attribute which can be any
+alphanumeric token.  The main purpose of the tag attribute is to allow
+batching of multiple requests into a single PDU.
+
+=== self_obj <self/> object ===
+
+A {{{<self/>}}} object represents one virtual RPKI engine.  In simple cases
+where the RPKI engine operator operates the engine only on their own
+behalf, there will only be one {{{<self/>}}} object, representing the engine
+operator's organization, but in environments where the engine operator
+hosts other entities, there will be one {{{<self/>}}} object per hosted
+entity (probably including the engine operator's own organization,
+considered as a hosted customer of itself).
+
+Some of the RPKI engine's configured parameters and data are shared by
+all hosted entities, but most are tied to a specific {{{<self/>}}} object.
+Data which are shared by all hosted entities are referred to as
+"per-engine" data, data which are specific to a particular {{{<self/>}}}
+object are "per-self" data.
+
+Since all other RPKI engine objects refer to a {{{<self/>}}} object via a
+"self_handle" value, one must create a {{{<self/>}}} object before one can
+usefully configure any other left-right protocol objects.
+
+Every {{{<self/>}}} object has a self_handle attribute, which must be specified
+for the "create", "set", "get", and "destroy" actions.
+
+Payload data which can be configured in a {{{<self/>}}} object:
+
+use_hsm:: (attribute)
+    Whether to use a Hardware Signing Module.  At present this option
+    has no effect, as the implementation does not yet support HSMs.
+
+crl_interval:: (attribute)
+    Positive integer representing the planned lifetime of an RPKI CRL
+    for this {{{<self/>}}}, measured in seconds.
+
+regen_margin:: (attribute)
+    Positive integer representing how long before expiration of an
+    RPKI certificiate a new one should be generated, measured in
+    seconds.  At present this only affects the one-off EE
+    certificates associated with ROAs.  This parameter also controls
+    how long before the nextUpdate time of CRL or manifest the CRL
+    or manifest should be updated.
+
+bpki_cert:: (element)
+    BPKI CA certificate for this {{{<self/>}}}.  This is used as part of the
+    certificate chain when validating incoming TLS and CMS messages,
+    and should be the issuer of cross-certification BPKI certificates
+    used in {{{<repository/>}}}, {{{<parent/>}}}, and {{{<child/>}}} objects.  If the
+    bpki_glue certificate is in use (below), the bpki_cert certificate
+    should be issued by the bpki_glue certificate; otherwise, the
+    bpki_cert certificate should be issued by the per-engine bpki_ta
+    certificate.
+
+bpki_glue:: (element)
+    Another BPKI CA certificate for this {{{<self/>}}}, usually not needed.
+    Certain pathological cross-certification cases require a
+    two-certificate chain due to issuer name conflicts.  If used, the
+    bpki_glue certificate should be the issuer of the bpki_cert
+    certificate and should be issued by the per-engine bpki_ta
+    certificate; if not needed, the bpki_glue certificate should be
+    left unset.
+
+Control attributes that can be set to "yes" to force actions:
+
+rekey::
+    Start a key rollover for every RPKI CA associated with every
+    {{{<parent/>}}} object associated with this {{{<self/>}}} object.  This is the
+    first phase of a key rollover operation.
+
+revoke::
+    Revoke any remaining certificates for any expired key associated
+    with any RPKI CA for any {{{<parent/>}}} object associated with this
+    {{{<self/>}}} object.   This is the second (cleanup) phase for a key
+    rollover operation; it's separate from the first phase to leave
+    time for new RPKI certificates to propegate and be installed.
+
+reissue::
+    Not implemented, may be removed from protocol.  Original theory
+    was that this operation would force reissuance of any object with
+    a changed key, but as that happens automatically as part of the
+    key rollover mechanism this operation seems unnecessary.
+
+run_now::
+    Force immediate processing for all tasks associated with this
+    {{{<self/>}}} object that would ordinarily be performed under cron.  Not
+    currently implemented.
+
+publish_world_now::
+    Force (re)publication of every publishable object for this {{{<self/>}}}
+    object.  Not currently implemented.   Intended to aid in recovery
+    if RPKI engine and publication engine somehow get out of sync.
+
+
+=== <bsc/> object ===
+
+The {{{<bsc/>}}} ("business signing context") object represents all the BPKI
+data needed to sign outgoing CMS messages.  Various other
+objects include pointers to a {{{<bsc/>}}} object.  Whether a particular
+{{{<self/>}}} uses only one {{{<bsc/>}}} or multiple is a configuration decision
+based on external requirements: the RPKI engine code doesn't care, it
+just cares that, for any object representing a relationship for which
+it must sign messages, there be a {{{<bsc/>}}} object that it can use to
+produce that signature.
+
+Every {{{<bsc/>}}} object has a bsc_handle, which must be specified for the
+"create", "get", "set", and "destroy" actions.  Every {{{<bsc/>}}} also has a self_handle
+attribute which indicates the {{{<self/>}}} object with which this {{{<bsc/>}}}
+object is associated.
+
+Payload data which can be configured in a {{{<isc/>}}} object:
+
+signing_cert:: (element)
+    BPKI certificate to use when generating a signature.
+
+signing_cert_crl:: (element)
+    CRL which would list signing_cert if it had been revoked.
+
+Control attributes that can be set to "yes" to force actions:
+
+generate_keypair::
+    Generate a new BPKI keypair and return a {{{PKCS #10}}} certificate
+    request.  The resulting certificate, once issued, should be
+    configured as this {{{<bsc/>}}} object's signing_cert.
+
+Additional attributes which may be specified when specifying
+"generate_keypair":
+
+key_type::
+    Type of BPKI keypair to generate.  "rsa" is both the default and,
+    at the moment, the only allowed value.
+
+hash_alg::
+    Cryptographic hash algorithm to use with this keypair.  "sha256"
+    is both the default and, at the moment, the only allowed value.
+
+key_length::
+    Length in bits of the keypair to be generated.  "2048" is both the
+    default and, at the moment, the only allowed value.
+
+Replies to "create" and "set" actions that specify "generate-keypair"
+include a <bsc_pkcs10/> element, as do replies to "get" and "list"
+actions for a {{{<bsc/>}}} object for which a "generate-keypair" command has
+been issued.  The RPKI engine stores the {{{PKCS #10}}} request, which
+allows the IRBE to reuse the request if and when it needs to reissue
+the corresponding BPKI signing certificate.
+
+=== <parent/> object ===
+
+The {{{<parent/>}}} object represents the RPKI engine's view of a particular
+parent of the current {{{<self/>}}} object in the up-down protocol.  Due to
+the way that the resource hierarchy works, a given {{{<self/>}}} may obtain
+resources from multiple parents, but it will always have at least one;
+in the case of IANA or an RIR, the parent RPKI engine may be a trivial
+stub.
+
+Every {{{<parent/>}}} object has a parent_handle, which must be specified for
+the "create", "get", "set", and "destroy" actions.  Every {{{<parent/>}}} also has a
+self_handle attribute which indicates the {{{<self/>}}} object with which this
+{{{<parent/>}}} object is associated, a bsc_handle attribute indicating the {{{<bsc/>}}}
+object to be used when signing messages sent to this parent, and a
+repository_handle indicating the {{{<repository/>}}} object to be used when
+publishing issued by the certificate issued by this parent.
+
+Payload data which can be configured in a {{{<parent/>}}} object:
+
+peer_contact_uri:: (attribute)
+    HTTP URI used to contact this parent.
+
+sia_base:: (attribute)
+    The leading portion of an rsync URI that the RPKI engine should
+    use when composing the publication URI for objects issued by the
+    RPKI certificate issued by this parent.
+
+sender_name:: (attribute)
+    Sender name to use in the up-down protocol when talking to this
+    parent.  The RPKI engine doesn't really care what this value is,
+    but other implementations of the up-down protocol do care.
+
+recipient_name:: (attribute)
+    Recipient name to use in the up-down protocol when talking to this
+    parent.   The RPKI engine doesn't really care what this value is,
+    but other implementations of the up-down protocol do care.
+
+bpki_cms_cert:: (element)
+    BPKI CMS CA certificate for this {{{<parent/>}}}.  This is used as part
+    of the certificate chain when validating incoming CMS messages If
+    the bpki_cms_glue certificate is in use (below), the bpki_cms_cert
+    certificate should be issued by the bpki_cms_glue certificate;
+    otherwise, the bpki_cms_cert certificate should be issued by the
+    bpki_cert certificate in the {{{<self/>}}} object.
+
+bpki_cms_glue:: (element)
+    Another BPKI CMS CA certificate for this {{{<parent/>}}}, usually not
+    needed.  Certain pathological cross-certification cases require a
+    two-certificate chain due to issuer name conflicts.  If used, the
+    bpki_cms_glue certificate should be the issuer of the
+    bpki_cms_cert certificate and should be issued by the bpki_cert
+    certificate in the {{{<self/>}}} object; if not needed, the
+    bpki_cms_glue certificate should be left unset.
+
+Control attributes that can be set to "yes" to force actions:
+
+rekey::
+    This is like the rekey command in the {{{<self/>}}} object, but limited
+    to RPKI CAs under this parent.
+
+reissue::
+    This is like the reissue command in the {{{<self/>}}} object, but limited
+    to RPKI CAs under this parent.
+
+revoke::
+    This is like the revoke command in the {{{<self/>}}} object, but limited
+    to RPKI CAs under this parent.
+
+=== <child/> object ===
+
+The {{{<child/>}}} object represents the RPKI engine's view of particular
+child of the current {{{<self/>}}} in the up-down protocol.
+
+Every {{{<child/>}}} object has a child_handle, which must be specified for the
+"create", "get", "set", and "destroy" actions.  Every {{{<child/>}}} also has a
+self_handle attribute which indicates the {{{<self/>}}} object with which this
+{{{<child/>}}} object is associated.
+
+Payload data which can be configured in a {{{<child/>}}} object:
+
+bpki_cert:: (element)
+    BPKI CA certificate for this {{{<child/>}}}.  This is used as part of
+    the certificate chain when validating incoming TLS and CMS
+    messages.  If the bpki_glue certificate is in use (below), the
+    bpki_cert certificate should be issued by the bpki_glue
+    certificate; otherwise, the bpki_cert certificate should be issued
+    by the bpki_cert certificate in the {{{<self/>}}} object.
+
+bpki_glue:: (element)
+    Another BPKI CA certificate for this {{{<child/>}}}, usually not needed.
+    Certain pathological cross-certification cases require a
+    two-certificate chain due to issuer name conflicts.  If used, the
+    bpki_glue certificate should be the issuer of the bpki_cert
+    certificate and should be issued by the bpki_cert certificate in
+    the {{{<self/>}}} object; if not needed, the bpki_glue certificate
+    should be left unset.
+
+Control attributes that can be set to "yes" to force actions:
+
+reissue::
+    Not implemented, may be removed from protocol.
+
+=== <repository/> object ===
+
+The {{{<repository/>}}} object represents the RPKI engine's view of a
+particular publication repository used by the current {{{<self/>}}} object.
+
+Every {{{<repository/>}}} object has a repository_handle, which must be
+specified for the "create", "get", "set", and "destroy" actions.  Every
+{{{<repository/>}}} also has a self_handle attribute which indicates the {{{<self/>}}}
+object with which this {{{<repository/>}}} object is associated.
+
+Payload data which can be configured in a {{{<repository/>}}} object:
+
+peer_contact_uri:: (attribute)
+    HTTP URI used to contact this repository.
+
+bpki_cms_cert:: (element)
+    BPKI CMS CA certificate for this {{{<repository/>}}}.  This is used as part
+    of the certificate chain when validating incoming CMS messages If
+    the bpki_cms_glue certificate is in use (below), the bpki_cms_cert
+    certificate should be issued by the bpki_cms_glue certificate;
+    otherwise, the bpki_cms_cert certificate should be issued by the
+    bpki_cert certificate in the {{{<self/>}}} object.
+
+bpki_cms_glue:: (element)
+    Another BPKI CMS CA certificate for this {{{<repository/>}}}, usually not
+    needed.  Certain pathological cross-certification cases require a
+    two-certificate chain due to issuer name conflicts.  If used, the
+    bpki_cms_glue certificate should be the issuer of the
+    bpki_cms_cert certificate and should be issued by the bpki_cert
+    certificate in the {{{<self/>}}} object; if not needed, the
+    bpki_cms_glue certificate should be left unset.
+
+At present there are no control attributes for {{{<repository/>}}} objects.
+
+=== <route_origin/> object ===
+
+This section is out-of-date. The {{{<route_origin/>}}} object
+has been replaced by the {{{<list_roa_requests/>}}} IRDB query,
+but the documentation for that hasn't been written yet.
+
+The {{{<route_origin/>}}} object is a kind of prototype for a ROA.  It
+contains all the information needed to generate a ROA once the RPKI
+engine obtains the appropriate RPKI certificates from its parent(s).
+
+Note that a {{{<route_origin/>}}} object represents a ROA to be generated on
+behalf of {{{<self/>}}}, not on behalf of a {{{<child/>}}}.  Thus, a hosted entity
+that has no children but which does need to generate ROAs would be
+represented by a hosted {{{<self/>}}} with no {{{<child/>}}} objects but one or
+more {{{<route_origin/>}}} objects.   While lumping ROA generation in with
+the other RPKI engine activities may seem a little odd at first, it's
+a natural consequence of the design requirement that the RPKI daemon
+never transmit private keys across the network in any form; given this
+requirement, the RPKI engine that holds the private keys for an RPKI
+certificate must also be the engine which generates any ROAs that
+derive from that RPKI certificate.
+
+The precise content of the {{{<route_origin/>}}} has changed over time as
+the underlying ROA specification has changed.  The current
+implementation as of this writing matches what we expect to see in
+draft-ietf-sidr-roa-format-03, once it is issued.  In particular, note
+that the exactMatch boolean from the -02 draft has been replaced by
+the prefix and maxLength encoding used in the -03 draft.
+
+Payload data which can be configured in a {{{<route_origin/>}}} object:
+
+asn:: (attribute)
+    Autonomous System Number (ASN) to place in the generated ROA.  A
+    single ROA can only grant authorization to a single ASN; multiple
+    ASNs require multiple ROAs, thus multiple {{{<route_origin/>}}} objects.
+
+ipv4:: (attribute)
+    List of IPv4 prefix and maxLength values, see below for format.
+
+ipv6:: (attribute)
+    List of IPv6 prefix and maxLength values, see below for format.
+
+Control attributes that can be set to "yes" to force actions:
+
+suppress_publication::
+    Not implemented, may be removed from protocol.
+
+The lists of IPv4 and IPv6 prefix and maxLength values are represented
+as comma-separated text strings, with no whitespace permitted.  Each
+entry in such a string represents a single prefix/maxLength pair.
+
+ABNF for these address lists:
+
+{{{
+  <ROAIPAddress> ::= <address> "/" <prefixlen> [ "-" <max_prefixlen> ]
+                        ; Where <max_prefixlen> defaults to the same
+                        ; value as <prefixlen>.
+
+  <ROAIPAddressList> ::= <ROAIPAddress> *( "," <ROAIPAddress> )
+}}}
+
+For example, {{{10.0.1.0/24-32,10.0.2.0/24}}}, which is a shorthand
+form of {{{10.0.1.0/24-32,10.0.2.0/24-24}}}.
+
+== Operations initiated by the RPKI engine ==
+
+The left-right protocol also includes queries from the RPKI engine
+back to the IRDB.  These queries do not follow the message-passing
+pattern used in the IRBE-initiated part of the protocol.  Instead,
+there's a single query back to the IRDB, with a corresponding
+response.  The CMS encoding are the same as in the rest of
+the protocol, but the BPKI certificates will be different as the
+back-queries and responses form a separate communication channel.
+
+=== <list_resources/> messages ===
+
+The {{{<list_resources/>}}} query and response allow the RPKI engine to ask
+the IRDB for information about resources assigned to a particular
+child.  The query must include both a {{{self_handle}}} attribute naming
+the {{{<self/>}}} that is making the request and also a {{{child_handle}}}
+attribute naming the child that is the subject of the query.  The
+query and response also allow an optional //tag// attribute of the
+same form used elsewhere in this protocol, to allow batching.
+
+A {{{<list_resources/>}}} response includes the following attributes, along
+with the tag (if specified), {{{self_handle}}}, and {{{child_handle}}} copied
+from the request:
+
+valid_until::
+    A timestamp indicating the date and time at which certificates
+    generated by the RPKI engine for these data should expire.  The
+    timestamp is expressed as an XML {{{xsd:dateTime}}}, must be
+    expressed in UTC, and must carry the "Z" suffix indicating UTC.
+
+asn::
+    A list of autonomous sequence numbers, expressed as a
+    comma-separated sequence of decimal integers with no whitespace.
+
+ipv4::
+    A list of IPv4 address prefixes and ranges, expressed as a
+    comma-separated list of prefixes and ranges with no whitespace.
+    See below for format details.
+
+ipv6::
+    A list of IPv6 address prefixes and ranges, expressed as a
+    comma-separated list of prefixes and ranges with no whitespace.
+    See below for format details.
+
+Entries in a list of address prefixes and ranges can be either
+prefixes, which are written in the usual address/prefixlen notation,
+or ranges, which are expressed as a pair of addresses denoting the
+beginning and end of the range, written in ascending order separated
+by a single "-" character.  This format is superficially similar to
+the format used for prefix and maxLength values in the {{{<route_origin/>}}}
+object, but the semantics differ: note in particular that
+{{{<route_origin/>}}} objects don't allow ranges, while {{{<list_resources/>}}}
+messages don't allow a maxLength specification.
+
+== Error handling ==
+
+Error in this protocol are handled at two levels.
+
+Since all messages in this protocol are conveyed over HTTP
+connections, basic errors are indicated via the HTTP response code.
+4xx and 5xx responses indicate that something bad happened.  Errors
+that make it impossible to decode a query or encode a response are
+handled in this way.
+
+Where possible, errors will result in a {{{<report_error/>}}} message which
+takes the place of the expected protocol response message.
+{{{<report_error/>}}} messages are CMS-signed XML messages like the rest of
+this protocol, and thus can be archived to provide an audit trail.
+
+{{{<report_error/>}}} messages only appear in replies, never in queries.
+The {{{<report_error/>}}} message can appear on either the "forward" (IRBE
+as client of RPKI engine) or "back" (RPKI engine as client of IRDB)
+communication channel.
+
+The {{{<report_error/>}}} message includes an optional //tag// attribute to
+assist in matching the error with a particular query when using
+batching, and also includes a {{{self_handle}}} attribute indicating the
+{{{<self/>}}} that issued the error.
+
+The error itself is conveyed in the {{{error_code}}} (attribute).  The
+value of this attribute is a token indicating the specific error that
+occurred.  At present this will be the name of a Python exception; the
+production version of this protocol will nail down the allowed error
+tokens here, probably in the RelaxNG schema.
+
+The body of the {{{<report_error/>}}} element itself is an optional text
+string; if present, this is debugging information.  At present this
+capabilty is not used, debugging information goes to syslog.
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FPublication b/doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FPublication
new file mode 100644
index 00000000..fedc0889
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FPublication
@@ -0,0 +1,216 @@
+= The Publication Protocol =
+
+[[TracNav(doc/RPKI/TOC)]]
+[[PageOutline]]
+
+The publication protocol is really two separate client/server
+protocols, between different parties.  The first is a configuration
+protocol for an IRBE to use to configure a publication engine,
+the second is the interface by which authorized clients request
+publication of specific objects.
+
+Much of the architecture of the publication protocol is borrowed from
+the [[LeftRight|left-right protocol]]: like the left-right
+protocol, the publication protocol uses CMS-wrapped XML over HTTP with
+the same eContentType OID and the same HTTP content-type, and the
+overall style of the XML messages is very similar to the left-right
+protocol.  All operations allow an optional "tag" attribute to allow
+batching.
+
+The publication engine operates a single HTTP server which serves
+both of these subprotocols.  The two subprotocols share a single
+server port, but use distinct URLs to allow demultiplexing.
+
+== Publication control subprotocol ==
+
+The control subprotocol reuses the message-passing design of the
+left-right protocol.  Configured objects support the "create", "set",
+"get", "list", and "destroy" actions, or a subset thereof when the
+full set of actions doesn't make sense.
+
+=== <config/> object ===
+
+The <config/> object allows configuration of data that apply to the
+entire publication server rather than a particular client.
+
+There is exactly one <config/> object in the publication server, and
+it only supports the "set" and "get" actions -- it cannot be created
+or destroyed.
+
+Payload data which can be configured in a <config/> object:
+
+bpki_crl:: (element)
+    This is the BPKI CRL used by the publication server when
+    signing the CMS wrapper on responses in the publication
+    subprotocol.  As the CRL must be updated at regular intervals,
+    it's not practical to restart the publication server when the
+    BPKI CRL needs to be updated.  The BPKI model doesn't require
+    use of a BPKI CRL between the IRBE and the publication server,
+    so we can use the publication control subprotocol to update the
+    BPKI CRL.
+
+=== <client/> object ===
+
+The <client/> object represents one client authorized to use the
+publication server.
+
+The <client/> object supports the full set of "create", "set", "get",
+"list", and "destroy" actions.  Each client has a "client_handle"
+attribute, which is used in responses and must be specified in "create", "set",
+"get", or "destroy" actions.
+
+Payload data which can be configured in a <client/> object:
+
+base_uri:: (attribute)
+    This is the base URI below which this client is allowed to publish
+    data.  The publication server may impose additional constraints in
+    the case of a child publishing beneath its parent.
+
+bpki_cert:: (element)
+    BPKI CA certificate for this <client/>.  This is used as part of
+    the certificate chain when validating incoming TLS and CMS
+    messages.  If the bpki_glue certificate is in use (below), the
+    bpki_cert certificate should be issued by the bpki_glue
+    certificate; otherwise, the bpki_cert certificate should be issued
+    by the publication engine's bpki_ta certificate.
+
+bpki_glue:: (element)
+    Another BPKI CA certificate for this <client/>, usually not
+    needed.  Certain pathological cross-certification cases require a
+    two-certificate chain due to issuer name conflicts.  If used, the
+    bpki_glue certificate should be the issuer of the bpki_cert
+    certificate and should be issued by the publication engine's
+    bpki_ta certificate; if not needed, the bpki_glue certificate
+    should be left unset.
+
+== Publication subprotocol ==
+
+The publication subprotocol is structured somewhat differently from
+the publication control protocol.  Objects in the publication
+subprotocol represent objects to be published or objects to be
+withdrawn from publication.  Each kind of object supports two actions:
+"publish" and "withdraw".  In each case the XML element representing
+hte object to be published or withdrawn has a "uri" attribute which
+contains the publication URI.  For "publish" actions, the XML element
+body contains the DER object to be published, encoded in Base64; for
+"withdraw" actions, the XML element body is empty.
+
+In theory, the detailed access control for each kind of object might
+be different.  In practice, as of this writing, access control for all
+objects is a simple check that the client's {{{base_uri}}} is a leading
+substring of the publication URI.  Details of why access control might
+need to become more complicated are discussed in a later section.
+
+=== <certificate/> object ===
+
+The <certificate/> object represents an RPKI certificate to be
+published or withdrawn.
+
+=== <crl/> object ===
+
+The <crl/> object represents an RPKI CRL to be published or withdrawn.
+
+=== <manifest/> object ===
+
+The <manifest/> object represents an RPKI publication manifest to be
+published or withdrawn.
+
+Note that part of the reason for the batching support in the
+publication protocol is because //every// publication or withdrawal
+action requires a new manifest, thus every publication or withdrawal
+action will involve at least two objects.
+
+=== <roa/> object ===
+
+The <roa/> object represents a ROA to be published or withdrawn.
+
+== Error handling ==
+
+Error in this protocol are handled at two levels.
+
+Since all messages in this protocol are conveyed over HTTP
+connections, basic errors are indicated via the HTTP response code.
+4xx and 5xx responses indicate that something bad happened.  Errors
+that make it impossible to decode a query or encode a response are
+handled in this way.
+
+Where possible, errors will result in a <report_error/> message which
+takes the place of the expected protocol response message.
+<report_error/> messages are CMS-signed XML messages like the rest of
+this protocol, and thus can be archived to provide an audit trail.
+
+<report_error/> messages only appear in replies, never in
+queries.  The <report_error/> message can appear in both the
+control and publication subprotocols.
+
+The <report_error/> message includes an optional //tag// attribute to
+assist in matching the error with a particular query when using
+batching.
+
+The error itself is conveyed in the {{{error_code}}} (attribute).  The
+value of this attribute is a token indicating the specific error that
+occurred.  At present this will be the name of a Python exception; the
+production version of this protocol will nail down the allowed error
+tokens here, probably in the RelaxNG schema.
+
+The body of the <report_error/> element itself is an optional text
+string; if present, this is debugging information.  At present this
+capabilty is not used, debugging information goes to syslog.
+
+== Additional access control considerations ==
+
+As detailed above, the publication protocol is trivially simple.  This
+glosses over two bits of potential complexity:
+
+* In the case where parent and child are sharing a repository, we'd
+  like to nest child under parent, because testing has demonstrated
+  that even on relatively slow hardware the delays involved in setting
+  up separate rsync connections tend to dominate synchronization time
+  for relying parties.
+
+* The repository operator might also want to do some checks to assure
+  itself that what it's about to allow the RPKI engine to publish is
+  not dangerous toxic waste.
+
+The up-down protocol includes a mechanism by which a parent can
+suggest a publication URI to each of its children.  The children are
+not required to accept this hint, and the children must make separate
+arrangements with the repository operator (who might or might not be
+the same as the entity that hosts the children's RPKI engine
+operations) to use the suggested publication point, but if everything
+works out, this allows children to nest cleanly under their parents
+publication points, which helps reduce synchronization time for
+relying parties.
+
+In this case, one could argue that the publication server is
+responsible for preventing one of its clients (the child in the above
+description) from stomping on data published by another of its clients
+(the parent in the above description).  This goes beyond the basic
+access check and requires the publication server to determine whether
+the parent has given its consent for the child to publish under the
+parent.  Since the RPKI certificate profile requires the child's
+publication point to be indicated in an SIA extension in a certificate
+issued by the parent to the child, the publication engine can infer
+this permission from the parent's issuance of a certificate to the
+child.  Since, by definition, the parent also uses this publication
+server, this is an easy check, as the publication server should
+already have the parent's certificate available by the time it needs
+to check the child's certificate.
+
+The previous paragraph only covers a "publish" action for a
+{{{<certificate/>}}} object.  For "publish" actions on other
+objects, the publication server would need to trace permission back
+to the certificate issued by the parent; for "withdraw" actions,
+the publication server would have to perform the same checks it
+would perform for a "publish" action, using the current published
+data before withdrawing it.  The latter in turn implies an ordering
+constraint on "withdraw" actions in order to preserve the data
+necessary for these access control decisions; as this may prove
+impractical, the publication server may probably need to make
+periodic sweeps over its published data looking for orphaned
+objects, but that's probably a good idea anyway.
+
+Note that, in this publication model, any agreement that the
+repository makes to publish the RPKI engine's output is conditional
+upon the object to be published passing whatever access control checks
+the publication server imposes.
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas b/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas
new file mode 100644
index 00000000..ba38fd83
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas
@@ -0,0 +1,6 @@
+= RPKI Engine SQL Database Schemas =
+
+[[TracNav(doc/RPKI/TOC)]]
+
+* [[./rpkid|rpkid database schema]]
+* [[./pubd|pubd database schema]]
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Fpubd b/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Fpubd
new file mode 100644
index 00000000..966c6a4d
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Fpubd
@@ -0,0 +1,8 @@
+= pubd SQL Schema =
+
+[[TracNav(doc/RPKI/TOC)]]
+[[PageOutline]]
+
+[[source:/trunk/rpkid/pubd.sql|pubd.sql]]
+
+[[Image(pubd.png, title = "Diagram of pubd.sql")]]
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Frpkid b/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Frpkid
new file mode 100644
index 00000000..5e9112f1
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Frpkid
@@ -0,0 +1,8 @@
+= rpkid SQL schema =
+
+[[TracNav(doc/RPKI/TOC)]]
+[[PageOutline]]
+
+[[source:/trunk/rpkid/rpkid.sql|rpkid.sql]]
+
+[[Image(rpkid.png, title = "Diagram of rpkid.sql")]]
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI
new file mode 100644
index 00000000..6679c5ef
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI
@@ -0,0 +1,177 @@
+= The CA user interface tools =

+

+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+The design of rpkid and pubd assumes that certain tasks can be thrown

+over the wall to the registry's back end operation.  This was a

+deliberate design decision to allow rpkid and pubd to remain

+independent of existing database schema, business PKIs, and so forth

+that a registry might already have.  All very nice, but it leaves

+someone who just wants to test the tools or who has no existing back

+end with a fairly large programming project.  The user interface tools

+attempt to fill that gap.  Together with irdbd, these tools consitute

+the "IR back-end" (IRBE) programs.

+

+[[./rpkic|rpkic]] is a command line interface to the the IRBE.  The

+[[./GUI|web interface]] is a Django-based graphical user interface to

+the IRBE.  The two user interfaces are built on top of the same

+libraries, and can be used fairly interchangeably.  Most users will

+probably prefer the GUI, but the command line interface may be useful

+for scripted control, for testing, or for environments where running a

+web server is not practical.

+

+A large registry which already has its own back-end system might want

+to roll their own replacement for the entire IRBE package.  The tools

+are designed to allow this.

+

+The user interface tools support two broad classes of operations:

+

+1. Relationship management: setting up relationships between RPKI

+   parent and child entities and between publication repositories and

+   their clients.  This is primarily about exchange of BPKI keys with

+   other entities and learning the service URLs at which rpkid should

+   contact other servers.  We refer to this as the "setup phase".

+

+2. Operation of rpkid once relationships have been set up: issuing

+   ROAs, assigning resources to children, and so forth.  We refer to

+   this as the "data maintenance" phase.

+

+During setup phase, the tools generate and processes small XML

+messages, which they expects the user to ship to and from its parents,

+children, etc via some out-of-band means (email, perhaps with PGP

+signatures, USB stick, we really don't care).  During data maintenance

+phase, the tools control the operation of rpkid and pubd.

+

+While the normal way to enter data during maintenance phase is by

+filling out web forms, there's also a file-based format which can be

+used to upload and download data from the GUI; the command line tool

+uses the same file format.  These files are simple

+whitespace-delimited text files (".csv files" -- the name is

+historical, at one point these were parsed and generated using the

+Python "csv" library, and the name stuck).  The intent is that these

+be very simple files that are easy to parse or to generate as a dump

+from relational database, spreadsheet, awk script, whatever works in

+your environment.

+

+As with rpkid and pubd, the user interface tools use a configuration

+file, which defaults to the same system-wide rpki.conf file as the

+other programs.

+

+== Overview of setup phase == #overview

+

+While the specific commands one uses differ depending on whether you

+are using the command line tool or the GUI, the basic operations

+during setup phase are the same:

+

+1. If you haven't already done so,

+   [[Installation|install the software]], create the

+   [[Configuration|rpki.conf]] for your installation, and

+   [[MySQLSetup|set up the MySQL database]].

+

+2. If you haven't already done so, create the initial BPKI database

+   for your installation by running the "rpkic initialize" command.

+   This will also create a BPKI identity for the handle specified in

+   your rpki.conf file.  BPKI initialization is tied to creation of

+   the initial BPKI identity for historical reasons.  These operations

+   probably ought to be handled by separate commands, and may be in

+   the future.

+

+3. If you haven't already done so, start the servers, using the

+   {{{rpki-start-servers}}} script.

+

+4. Send a copy of the XML identity file written out by "rpkic

+   initialize" to each of your parents, somehow (email, USB stick,

+   carrier pigeon, we don't care).  The XML identity file will have a

+   filename like ./${handle}.identity.xml where "." is the directory

+   in which you ran rpkic and ${handle} is the handle set in your

+   rpki.conf file or selected with rpkic's {{{select_identity}}}

+   command.  This XML identity file tells each of your parents what

+   you call yourself, and supplies each parent with a trust anchor for

+   your resource-holding BPKI.

+

+5. Each of your parents configures you as a child, using the XML

+   identity file you supplied as input.  This registers your data with

+   the parent, including BPKI cross-registration, and generates a

+   return message containing your parent's BPKI trust anchors, a

+   service URL for contacting your parent via the "up-down" protocol,

+   and (usually) either an offer of publication service (if your

+   parent operates a repository) or a referral from your parent to

+   whatever publication service your parent does use.  Referrals

+   include a CMS-signed authorization token that the repository

+   operator can use to determine that your parent has given you

+   permission to home underneath your parent in the publication tree.

+

+6. Each of your parents sends (...) back the response XML file

+   generated by the "configure_child" command.

+

+7. You feed the response message you just got into the IRBE using

+   rpkic's "configure_parent" command.  This registers the

+   parent's information in your database, handles BPKI

+   cross-certification of your parent., and processes the repository

+   offer or referral to generate a publication request message.

+

+8. You send (...) the publication request message to the repository.

+   The {{{contact_info}}} element in the request message should (in

+   theory) provide some clue as to where you should send this.

+

+9. The repository operator processes your request using rpkic's "configure_publication_client" command.  This registers

+   your information, including BPKI cross-certification, and generates

+   a response message containing the repository's BPKI trust anchor

+   and service URL.

+

+10. Repository operator sends (...) the publication confirmation

+   message back to you.

+

+11. You process the publication confirmation message using rpkic's "configure_repository" command.

+

+At this point you should, in theory, have established relationships,

+exchanged trust anchors, and obtained service URLs from all of your

+parents and repositories.

+

+== Troubleshooting ==

+

+If you run into trouble setting up this package, the first thing to do

+is categorize the kind of trouble you are having.  If you've gotten

+far enough to be running the daemons, check their log files.  If

+you're seeing Python exceptions, read the error messages.  If you're

+getting CMS errors, check to make sure that you're using all the right

+BPKI certificates and service contact URLs.

+

+If you've completed the steps above, everything appears to have gone

+OK, but nothing seems to be happening, the first thing to do is check

+the logs to confirm that nothing is actively broken.  rpkid's log

+should include messages telling you when it starts and finishes its

+internal "cron" cycle.  It can take several cron cycles for resources

+to work their way down from your parent into a full set of

+certificates and ROAs, so have a little patience.  rpkid's log should

+also include messages showing every time it contacts its parent(s) or

+attempts to publish anything.

+

+rcynic in fully verbose mode provides a fairly detailed

+explanation of what it's doing and why objects that fail have

+failed.

+

+You can use rsync (sic) to examine the contents of a publication

+repository one directory at a time, without attempting validation,

+by running rsync with just the URI of the directory on its command

+line:

+

+{{{

+#!sh

+$ rsync rsync://rpki.example.org/where/ever/

+}}}

+

+If you need to examine RPKI objects in detail, you have a few options:

+

+* The [[../../Utils|RPKI utilities]] include several programs for dumping

+  RPKI-specific objects in text form.

+

+* The OpenSSL command line program can also be useful for examining

+  and manipulating certificates and CMS messages, although the syntax

+  of some of the commands can be a bit obscure.

+

+* Peter Gutmann's excellent

+  [[http://www.cs.auckland.ac.nz/~pgut001/dumpasn1.c|dumpasn1]]

+  program may be useful if you are desperate enough that you need to

+  examine raw ASN.1 objects.

diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI
new file mode 100644
index 00000000..57f9c688
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI
@@ -0,0 +1,47 @@
+[[TracNav(doc/RPKI/TOC)]]

+

+[[PageOutline]]

+

+= Installing and Configuring =

+

+* [[wiki:GUI/Installing]] for new installs

+* [[wiki:GUI/Upgrading]] for upgrading from a previous install

+* [[wiki:GUI/Configuring]]

+* [[wiki:GUI/UserModel]] for instructions on managing users

+

+\\

+\\

+= Using the GUI =

+

+= GUI Examples =

+\\

+== Logging in to the GUI ==

+[[Image(htdocs:gui-pics/01-login.jpg)]]

+\\

+\\

+== The Dashboard - Let's Make a ROA ==

+[[Image(htdocs:gui-pics/02-dashboard.jpg)]]

+\\

+\\

+== ROA List Currently Empty, So Let's Create One ==

+[[Image(htdocs:gui-pics/03-roas.jpg)]]

+\\

+\\

+== Choose an AS and Prefix - Let MaxLen Default ==

+[[Image(htdocs:gui-pics/04-create-roa.jpg)]]

+\\

+\\

+== What Will the Consequences Be? - Confirm OK ==

+[[Image(htdocs:gui-pics/05-are-you-sure.jpg)]]

+\\

+\\

+== Now We Can See ROAs - Let's Look at Routes ==

+ [[Image(htdocs:gui-pics/06-roa-list.jpg)]]

+\\

+\\

+== Real Effect on Routing Table ==

+[[Image(htdocs:gui-pics/07-route view.jpg)]]

+\\

+\\

+== Ghostbusters etc. are Similar ==

+				    

diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring
new file mode 100644
index 00000000..c2176d97
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring
@@ -0,0 +1,65 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= Configuring the Web Portal =

+

+Also see [[wiki:doc/RPKI/CA/Configuration]] for documentation on the `/etc/rpki.conf` configuration file.

+

+== Creating Users ==

+

+See [[wiki:doc/RPKI/CA/UI/GUI/UserModel]]

+

+== Configuring Apache ==

+

+In order to use the web portal, Apache must be installed and configured to serve the application.

+See [[wiki:doc/RPKI/CA/UI/GUI/Configuring/Apache]].

+

+== Error Notifications via Email ==

+

+If an exception is generated while the web portal is processing a request, by default will be logged to the apache log file, and an email will be set to `root@localhost`.  If you wish to change where email is sent, you can edit `/etc/rpki/local_settings.py` and add the following lines:

+{{{

+ADMINS = (('YOUR NAME', 'YOUR EMAIL ADDRESS'),)

+}}}

+For example,

+{{{

+ADMINS = (('Joe User', 'joe@example.com'),)

+}}}

+

+== Cron Jobs ==

+

+The web portal makes use of some external data sources to display the validation status of routing entries.  Therefore, it is necessary to run some background jobs periodically to refresh this data.  The web portal software makes use of the `cron` facility present in POSIX operating systems to perform these tasks.

+

+=== Importing Routing Table Snapshot ===

+

+In order for the web portal to display the validation status of routes covered by a resource holder's RPKI certificates, it needs a source of the currently announced global routing table.  The web portal includes a script which can parse the output of the [http://www.routeviews.org RouteViews] [http://archive.routeviews.org/oix-route-views/oix-full-snapshot-latest.dat.bz2 full snapshot] ('''warning''': links to very large file!).

+

+When the software is installed, there will be a `/usr/local/sbin/rpkigui-import-routes` script that should be invoked periodically.  Routeviews.org updates the snapshot every two hours, so it does not make sense to run it more frequently than two hours.  How often to run it depends on how often the routes you are interested in are changing.

+

+Create an entry in root's crontab such as

+

+{{{

+30  */2 *   *   *      /usr/local/sbin/rpkigui-import-routes

+}}}

+

+=== Importing ROAs ===

+

+If you want the GUI's "routes" page to see ROAs when you click those

+buttons, you will need to run rcynic.  see the

+[[doc/RPKI/RP/rcynic|instructions for setting up rcynic]].

+

+This data is imported by the `rcynic-cron` script.  If you have not already set up that cron job, you should do so now.  Note that by default, rcynic-cron is run once an hour.  What this means is that the ''routes'' view in the GUI will '''not''' immediately update as you create/destroy ROAs.  You may wish to run `rcynic-cron` more frequently, or configure `rcynic.conf` to only include the TAL that is the root of your resources, and run the script more frequently (perhaps every 2-5 minutes).

+

+If you are running rootd, you may want to run with only your local trust

+anchor.  In this case, to have the GUI be fairly responsive to changes,

+you may want to run the rcynic often.  In this case, you may want to

+look at the value of '''jitter''' in rcynic.conf.

+

+=== Expiration Checking === #expire-check

+

+The web portal can notify users when it detects that RPKI certificates will expire in the near future.  Run the following script as a cron job, perhaps once a night:

+{{{

+#!sh

+/usr/local/sbin/rpkigui-check-expired

+}}}

+

+By default it will warn of expiration 14 days in advance, but this may be changed by using the `-t` command line option and specifying how many days in advance to check.
\ No newline at end of file
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring%2FApache b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring%2FApache
new file mode 100644
index 00000000..1e97dc57
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring%2FApache
@@ -0,0 +1,79 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= Apache Configuration =

+

+This page documents how to configure Apache to server the web portal application.

+

+During the software install process, `/usr/local/etc/rpki/apache.conf` is created, which needs to be included from the apache configuration inside of a `VirtualHost` section.

+

+Note that the web portal application '''requires TLS''' to be enabled for the `VirtualHost` it is configured in, otherwise it will fail to operate.

+

+== Requirements ==

+

+* Apache 2.2 or later

+* mod_ssl

+* mod_wsgi 3 or later

+

+== Debian & Ubuntu ==

+

+First, you need to install `apache` and enable SSL.  Run the following commands in a shell as '''root''':

+

+{{{#!sh

+apt-get install apache2 libapache2-mod-wsgi

+a2enmod ssl

+a2ensite default-ssl

+}}}

+

+Edit `/etc/apache2/sites-enabled/default-ssl` and place the following line inside the `<VirtualHost>` section:

+{{{

+Include /usr/local/etc/rpki/apache.conf

+}}}

+

+Now restart `apache`:

+{{{#!sh

+service apache2 restart

+}}}

+

+== FreeBSD ==

+

+Now configure apache, using `/usr/local/etc/rpki/apache.conf`, e.g.

+

+{{{

+#!sh

+$ cp apache.conf /usr/local/etc/apache22/Includes/rpki.conf

+}}}

+

+Restart apache

+{{{

+#!sh

+$ apachectl restart

+}}}

+

+== Running the web portal as a different user (optional) ==

+

+By default, the web portal is run in embedded mode in mod_wsgi, which means it runs inside the apache process.  However, you can make the web portal run in daemon mode as a different user using mod_wsgi.

+

+{{{

+#!sh

+$ ./configure --enable-wsgi-daemon-mode[=user[:group]]

+}}}

+

+Where `user` is the optional user to run the web portal as, and `group` is the optional group to run the web portal as.  If `user` is not specified, it will run in a separate process but the same user as apache is configured to run.

+

+Note that when run in daemon mode, a unix domain socket will be created in the same directory as the apache log files.  If the user you have specified to run the web portal as does not have permission to read a file in that directory, the web interface will return a **500 Internal Server Error** and you will see a **permission denied** error in your apache logs.  The solution to this is to use the `WSGISocketPrefix` apache configuration directive to specify an alternative location, such as:

+{{{

+WSGISocketPrefix /var/run/wsgi

+}}}

+

+Note that this directive **must not** be placed inside of the `VirtualHost` section.  It **must** be located at the global scope.

+

+see http://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGISocketPrefix for more information.

+

+== Verify the Web Portal is Working ==

+

+Navigate to https://YOURHOST/rpki/ and you should see the login page for the web portal.

+

+Enter the superuser and password in login form (see [[wiki:doc/RPKI/CA/UI/GUI/UserModel]] if you haven't yet created a superuser).  If you've only done the above bootstrap, there will only be a single

+handle to manage, so the GUI will automatically bring you to the

+dashboard for that handle.
\ No newline at end of file
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FInstalling b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FInstalling
new file mode 100644
index 00000000..9a273d8f
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FInstalling
@@ -0,0 +1,34 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= Installing the Web Portal for the First Time =

+

+This page documents how to install the web portal software.  '''If you have previously installed the software''', see [[wiki:doc/RPKI/CA/UI/GUI/Upgrading]] for instructions.

+

+== Prerequisites ==

+

+This page assumes that you have already followed the steps to install the CA software (see [[wiki:doc/RPKI/Installation]])

+

+This page assumes that you have already created `/etc/rpki.conf` (see [[wiki:doc/RPKI/CA/Configuration]])

+

+== Create Database Tables ==

+

+This step creates the tables used by the web portal in the database.  Run the following commands in the shell (you do not need to be ''root'', just have permission to read `/etc/rpki.conf`):

+

+{{{#!sh

+rpki-manage syncdb --noinput

+rpki-manage migrate

+}}}

+

+Note that at the end of the `syncdb` output you will see the following message:

+{{{

+Not synced (use migrations):

+ - rpki.gui.app

+(use ./manage.py migrate to migrate these)

+}}}

+

+You should '''ignore the message about running ./manage.py''' since that script does not exist in our setup (we use `rpki-manage` instead`).

+

+== Next Step ==

+

+See [[wiki:doc/RPKI/CA/UI/GUI/Configuring]]

diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading
new file mode 100644
index 00000000..644cbb16
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading
@@ -0,0 +1,36 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= Upgrading from a Previous Version =

+

+* See wiki:doc/RPKI/CA/UI/GUI/Upgrading/BeforeMigration for the special situation where you are upgrading from a release '''prior to database migration support being added'''.

+

+This page describes the steps you must take if you upgrading from a previous version of the software that is already installed on the system.  If you are installing for the first time see [[wiki:doc/RPKI/CA/UI/GUI/Installing]].

+

+Run the following commands at a shell prompt.  Note that you do not need run these as the ''root'' user, any user with permission to read `/etc/rpki.conf` is sufficient.

+

+{{{#!sh

+rpki-manage syncdb

+rpki-manage migrate

+}}}

+

+Note that at the end of the `syncdb` output you will see the following message:

+{{{

+Not synced (use migrations):

+ - rpki.gui.app

+(use ./manage.py migrate to migrate these)

+}}}

+

+You should '''ignore the message about running ./manage.py''' since that script does not exist in our setup (we use `rpki-manage` instead`).

+

+== Restart Apache ==

+

+In order to cause Apache to reload the web portal software using the newly installed software, it must be restarted.  Execute the following command as ''root'' in a shell:

+

+{{{#!sh

+apachectl restart

+}}}

+

+== Next Step ==

+

+See [[wiki:doc/RPKI/CA/UI/GUI/Configuring]]

diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading%2FBeforeMigration b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading%2FBeforeMigration
new file mode 100644
index 00000000..d0098c05
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading%2FBeforeMigration
@@ -0,0 +1,71 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= Upgrading from a Previous Release without Migration Support =

+

+This page documents the steps required to upgrade the web portal when you have a previous version of the software install '''prior to migration support via Django South'''.  Note that this is a special case and will not apply to most situations (see [[wiki:doc/RPKI/CA/UI/GUI/Upgrading]] for the normal upgrade path).  If you have already performed the steps on this page previously, then it does not apply to your situation.  

+

+If you are unsure whether or not you have previously run this command, you can verify with the following command:

+{{{#!sh

+$ rpki-manage migrate --list

+

+ app

+  (*) 0001_initial

+  (*) 0002_auto__add_field_resourcecert_conf

+  (*) 0003_set_conf_from_parent

+  (*) 0004_auto__chg_field_resourcecert_conf

+  (*) 0005_auto__chg_field_resourcecert_parent

+  ( ) 0006_add_conf_acl

+  ( ) 0007_default_acls

+}}}

+The migrations are an ordered list.  The presence of the asterisk `(*)` indicates that the migration has

+already been performed.  `( )` indicates that the specific migration

+has not yet been applied.  In the example above, migrations 0001 through 0005 have been applied, but 0006 and 0007 have not.

+

+== Sync databases ==

+

+Execute the following command in a shell.  Note that you do not need to be the ''root'' user, any user with permission to read `/etc/rpki.conf` is sufficient.

+{{{

+#!sh

+$ rpki-manage syncdb

+}}}

+

+Note that at the end of the `syncdb` output you will see the following message:

+{{{

+Not synced (use migrations):

+ - rpki.gui.app

+(use ./manage.py migrate to migrate these)

+}}}

+

+You should '''ignore the message about running ./manage.py''' since that script does not exist in our setup.

+

+== Initial Database Migration ==

+

+For a completely new install, there will not be any existing tables in the database, and the `rpki-manage migrate` command will create them.  However, in the special situation where you are upgrading from a previous release prior to the migration support being added, you will already have the tables created, which will case the initial migration to fail.  In order to work around this problem, we have to tell the migration that the initial step has already been performed.  This is accomplished via the use the `--fake` command line argument:

+

+{{{

+#!sh

+$ rpki-manage migrate app 0001 --fake

+}}}

+

+Note that this step doesn't actually modify the database, other than to record that the migration has already taken place.

+

+== Database Migration ==

+

+Now bring your database up to date with the current release:

+

+{{{

+#!sh

+$ rpki-manage migrate

+}}}

+

+From this point forward you will follow the steps in [[wiki:doc/RPKI/CA/UI/GUI/Upgrading]] each time you upgrade.

+

+== Restart Apache ==

+

+In order to make Apache use the new version of the software, it must be restarted:

+

+{{{

+#!sh

+$ apachectl restart

+}}}

diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUserModel b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUserModel
new file mode 100644
index 00000000..bc7201f2
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUserModel
@@ -0,0 +1,93 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= RPKI Web Portal User Model =

+

+== Roles ==

+

+The web portal uses a model where users are distinct from resource holders.

+

+=== Users ===

+

+A user is an entity that is granted permission to utilize the web portal.  Each user account has an associated password that is used to log in to the web portal.

+

+The web portal maintains an access control list that specifies which [#resource-holder resource holders] the user is allowed to manage.  If a user is authorized to manage more than a single resource holder, the user will be presented with a list of the resource holders upon login.

+

+Database tables: `irdbd.auth_user` and `irdbd.app_confacl`

+

+==== Changing User Passwords ====

+

+The password for a user may be changed via the web portal, or on the command line:

+{{{#!sh

+$ rpki-manage changepassword <USER>

+}}}

+

+==== Superuser ====

+

+A user account with the superuser bit set has the special capability that it may assume the role of any resource holder managed by the local RPKI service.  Superusers are created via the command line interface:

+

+{{{#!sh

+$ rpki-manage createsuperuser

+}}}

+

+==== Creating user accounts ==== #create-user

+

+When logged into the web portal with a [#superuser] account, select the '''web users''' link in the sidebar, and then click on the '''create''' button at the bottom of the page.  You may optionally select one or more [#resource-holder resource holders] that this user is granted authorization to manage.

+

+Note that creating a user does '''not''' create a matching [#resource-holder].  See [#create-holder creating resource holders].

+

+==== Destroying user accounts ====

+

+When logged into the web portal with a [#superuser] account, select the '''web users''' link in the sidebar, and then click on the '''Delete''' icon next to the user you wish to delete.

+

+Note that this action does '''not''' remove any of the [#resource-holder resource holders] the user is granted authorization to manage.

+

+

+=== Resource Holders === #resource-holder

+

+Resource holders are entities that have authority to manage a set of Internet number resources.  When a [#users user] logs into the web portal, they select which resource holder role to assume.  The user may choose to assume the role of a different resource holder by clicking on the '''select identity''' link in the sidebar.

+

+The list of resource holders managed by the local RPKI service can be viewed with a [#superuser] account by clicking on the **resource holders** link in the sidebar of the web portal.  From this page the super can manage the resource holders.

+

+Database table: `irdbd.irdb_resourceholderca` (via `irdbd.app_conf` proxy model)

+

+==== Creating resource holders ==== #create-holder

+

+Note that creating a new resource holder does '''not''' create a [#users user] account.  See [#create-user].

+

+===== GUI =====

+When logged into the web portal with a [#superuser] account, select the '''resource holders''' link in the sidebar, and then click on the '''create''' button at the bottom of the page.

+

+If the new resource holder is going to be a child of another resource holder hosted by the local RPKI service, you may optionally select the parent resource holder from the dropdown box, and the parent-child relationship will automatically be established when the new resource holder is created.

+

+Additionally, one or more [#users] authorized to manage the new resource holder may be selected from the '''Users''' list on the creation form.

+

+===== Command Line =====

+

+You can also create resource holders on the command line:

+{{{#!sh

+$ rpkic -i <HANDLE> initialize

+$ rpkic synchronize

+}}}

+where '''HANDLE''' is the name of new resource holder.  Note that this new resource holder will initially only be allowed to be managed by [#superuser] accounts.  You may wish to [#create-user create a matching user account], but the name of the user need not be the same as the handle of the resource holder.  Additionally, you can manage the list of users allowed to manage this resource holder via the web portal; click on the '''Edit''' icon next to the resource holder, and select the users you wish to grant permission to manage.

+

+==== Destroying resource holders ====

+

+Note that deleting a resource holder does '''not''' remove any [#users user] accounts.

+

+===== GUI =====

+

+When logged into the web portal with a [#superuser] account, select the '''resource holders''' link in the sidebar, and then click on the '''delete''' button next to the resource holder you wish to delete.

+

+===== Command Line =====

+

+Or you may use the command line interface:

+{{{#!sh

+$ rpkic -i <HANDLE> delete_self

+$ rpkic synchronize

+}}}

+where ''HANDLE'' is the name of the resource holder you wish to destroy.

+

+==== Modifying the User ACL ==== #acls

+

+Each [#resourceholders resource holder] may be managed by one or more [#users user] accounts.  The list of users authorized to assume the role of a particular resource holder may be changed in the web portal.  When logged into the web portal with a [#superuser] account, select the '''resource holders''' link in the sidebar, and then click on the '''Edit''' icon next to the resource holder, and select the users you wish to grant permission to manage.
\ No newline at end of file
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2Frpkic b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2Frpkic
new file mode 100644
index 00000000..044372d3
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2Frpkic
@@ -0,0 +1,105 @@
+= The rpkic tool =

+

+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+rpkic is a command line interface to rpkid and pubd.  It implements

+largely the same functionality as the [[GUI|web interface]].  In most

+cases you will want to use the web interface for normal operation, but

+rpkic is available if you need it.

+

+rpkic can be run either in an interactive mode or by passing a single

+command on the command line when starting the program; the former mode

+is intended to be somewhat human-friendly, the latter mode is useful

+in scripting, cron jobs, and automated testing.

+

+Some rpkic commands write out data files, usually in the current

+directory.

+

+rpkic uses the same system-wide [[Configuration|rpki.conf]] file as

+the other CA tools as its default configuration file.

+

+rpkic includes a "help" command which provides inline help for its

+several commands.

+

+== Selecting an identity ==

+

+The //handle// variable in rpki.conf specifies the handle of the

+default identity for an rpkic command, but this is just the default.

+rpkid can host an arbitrary number of identities, and rpkic has to be

+able to control all of them.

+

+When running rpkic interactively, use rpkic's "select_identity"

+command to set the current identity handle.

+

+When running rpkic with a single command on the command line, use the

+"-i" (or "--identity") option to set the current identity handle.

+

+== rpkic in setup phase ==

+

+See the [[..|introduction to the user interfaces]] for an overview of

+how setup phase works.  The general structure of the setup phase in

+rpkic is as described there, but here we provide the specific commands

+involved.  The following assumes that you have already installed the

+software and started the servers.

+

+* The rpkic "initialize" command writes out an "identity.xml" file in

+  addition to all of its other tasks.

+

+* A parent who is using rpkic runs the "configure_child" command to

+  configure the child, giving this command the identity.xml file the

+  child supplied as input.  configure_child will write out a response

+  XML file, which the parent sends back to the child.

+

+* A child who is running rpkic runs the "configure_parent" command to

+  process the parent's response, giving it the XML file sent back by

+  the parent as input to this command.  configure_parent will write

+  out a publication request XML file, which the child sents to the

+  repository operator.

+

+* A repository operator who is using rpkic runs the

+  "configure_publication_client" command to process a client's

+  publication request.  configure_publication_client generates a

+  confirmation XML message which the repository operator sends back to

+  the client.

+

+* A publication client who is using rpkic runs the

+  "configure_repository" command to process the repository's response.

+

+== rpkic in data maintenance phase ==

+

+rpkic uses whitespace-delimited text files (called ".csv files", for

+historical reasons) to control issuance of addresses and autonomous

+sequence numbers to children, and to control issuance of ROAs.  See

+the "load_asns", "load_prefixes", and "load_roa_requests" commands.

+

+== Maintaining child validity data ==

+

+All resources issued to child entities are tagged with a validity

+date.  If not updated, these resources will eventually expire.  rpkic

+includes two commands for updating these validity dates:

+

+* "renew_child" updates the validity date for a specific child.

+

+* "renew_all_children" updates the validity date for all children.

+

+== BPKI maintenance ==

+

+Certificates and CRLs in the BPKI have expiration dates and netUpdate

+dates, so they need to be maintained.  Failure to maintain these will

+eventually cause the CA software to grind to a halt, as expired

+certificates will cause CMS validation failures.

+

+rpkic's "update_bpki" command takes care of this.  Usually one will

+want to run this periodically (perhaps once per month), under cron.

+

+== Forcing synchronization ==

+

+Most rpkic commands synchronize the back end database with the daemons

+automatically, so in general it should not be necessary to synchronize

+manually.  However, since these are separate databases, it is

+theoretically possible for them to get out of synch, perhaps because

+something crashed at exactly the wrong time.

+

+rpkic's "synchronize" command runs a synchronization cycle with rpkid

+(if {{{run_rpkic}}} is set) and pubd (if {{{run_pubd}}} is set).

diff --git a/doc/wiki-dump/doc%2FRPKI%2FInstallation b/doc/wiki-dump/doc%2FRPKI%2FInstallation
new file mode 100644
index 00000000..89b9225b
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FInstallation
@@ -0,0 +1,38 @@
+[[PageOutline]]

+

+[[TracNav(doc/RPKI/TOC)]]

+

+= Download and Installation =

+

+There are a few different ways to install the RPKI code, depending on

+what the platform on which you're trying to install.

+

+* On Ubuntu 12.04 LTS ("Precise Pangolin"), Ubuntu 14.04 ("Trusty Tahir"), or Debian 7 ("Wheezy"), you can use [wiki:doc/RPKI/Installation/DebianPackages Debian binary packages].

+

+== Simple RPKI Cacha Install ==

+

+if you want to install a simple RPKI cache to feed routers from a Ubuntu 14.04 system, [wiki:doc/RPKI/Installation/UbuntuRP here is a one page ten minute recipe].

+

+== install a CA and a cache on a Ubuntu 14.04 with a rootd CA ==

+

+If you want to install a CA and a cache on a Ubuntu 14.04 with a rootd CA, [wiki:doc/RPKI/Installation/UbuntuRootd here is a one page hack].  It will take less than an hour.

+

+== Try the rrdp testbed CA and RP on Ubuntu Xenial ==

+

+If you are feeling adventurous and want to try the rrdp testbed CA and RP on Ubuntu Xenial 16.04 [wiki:RRDPtestbed here is a one page hack.]  It supports a much simpler root CA.

+

+== FreeBSD ==

+

+On FreeBSD, you can use [wiki:doc/RPKI/Installation/FreeBSDPorts FreeBSD ports].

+

+== Other Platforms ==

+

+On all other platforms, or on the above platforms if the

+pre-packaged versions don't suit your needs, you will have to

+[wiki:doc/RPKI/Installation/FromSource install from source code].

+

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

diff --git a/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FDebianPackages b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FDebianPackages
new file mode 100644
index 00000000..fdf5b1d3
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FDebianPackages
@@ -0,0 +1,90 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= Installation Using Debian Packages on Debian and Ubuntu Systems =

+

+Precompiled binary packages for Ubuntu 12.04 LTS ("Precise Pangolin") and

+Debian 7 ("Wheezy") are available from download.rpki.net using the Debian

+Advanced Package Tools (APT).  To use these, you need to configure APT on your

+machine to know about our APT repository, but once you've done this you should

+be able to install and update these packages like any other precompiled package.

+

+== Initial APT Setup ==

+

+You should only need to perform these steps once for any particular

+machine.

+

+* Add the GPG public key for this repository (optional, but APT will whine unless you do this):

+{{{

+#!sh

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

+}}}

+

+* Configure APT to use this repository (for Ubuntu Trusty systems):

+{{{

+#!sh

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

+}}}

+

+* Configure APT to use this repository (for Ubuntu Precise systems):

+{{{

+#!sh

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

+}}}

+

+* Configure APT to use this repository (for Debian Wheezy systems):

+{{{

+#!sh

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

+}}}

+

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

+{{{

+#!sh

+sudo apt-get update

+}}}

+

+* Install the software:

+{{{

+#!sh

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

+}}}

+

+* Customize the default `rpki.conf` for your environment as necessary.  In

+  particular, you want to change `handle` and `rpkid_server_host`.

+  There are [[CA/Configuration|obsessively detailed instructions]].

+{{{#!sh

+sudo emacs /etc/rpki.conf

+}}}

+

+  Again, you want to change `handle` and `rpkid_server_host` at the minimum.

+

+* If you changed anything in `rpki.conf`, you should restart the RPKI CA service:

+{{{

+#!sh

+sudo service rpki-ca restart

+}}}

+

+== Upgrading ==

+

+Once you've performed the steps above you should be able to upgrade

+to newer version of the code using the normal APT upgrade process, eg:

+

+{{{

+#!sh

+sudo apt-get update

+sudo apt-get upgrade

+}}}

+

+Or, if you only want to update the RPKI tools:

+

+{{{

+#!sh

+sudo apt-get update

+sudo apt-get upgrade rpki-ca rpki-rp

+}}}

diff --git a/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFreeBSDPorts b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFreeBSDPorts
new file mode 100644
index 00000000..bff99b78
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFreeBSDPorts
@@ -0,0 +1,124 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

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

+

+{{{

+#!sh

+for port in rpki-rp rpki-ca

+do

+  fetch https://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

+[[CA/Configuration|obsessively detailed instructions]].

+

+{{{

+#!sh

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

+

+{{{

+#!sh

+for port in rpki-rp rpki-ca

+do

+  fetch https://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

+[[https://download.rpki.net/FreeBSD_Packages/rpki-portmaster.sh|script]]

+you can use to automate the download steps above and perform the

+updates using portmaster.  First, download the script:

+

+{{{

+#!sh

+fetch https://download.rpki.net/FreeBSD_Packages/rpki-portmaster.sh

+}}}

+

+Then, to install or upgrade, just execute the script:

+

+{{{

+#!sh

+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

+[[https://download.rpki.net/FreeBSD_Packages/rpki-portupgrade.sh|script]]

+you can use to automate the download steps above and perform the

+updates using portupgrade.  First, download the script:

+

+{{{

+#!sh

+fetch https://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:

+

+{{{

+#!ruby

+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

+sh rpki-portupgrade.sh

+}}}

+

+As with manual download (above) you should customize `rpki.conf` after

+initial installation.

diff --git a/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFromSource b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFromSource
new file mode 100644
index 00000000..f768e3ea
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFromSource
@@ -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.

diff --git a/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FUbuntuPackages b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FUbuntuPackages
new file mode 100644
index 00000000..298de61f
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FUbuntuPackages
@@ -0,0 +1 @@
+See [wiki:"doc/RPKI/Installation/DebianPackages"].
\ No newline at end of file
diff --git a/doc/wiki-dump/doc%2FRPKI%2FListOfPrograms b/doc/wiki-dump/doc%2FRPKI%2FListOfPrograms
new file mode 100644
index 00000000..dc672e51
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FListOfPrograms
@@ -0,0 +1,52 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= List of RPKI programs =

+

+This is the beginning of a list of all the programs included in the

+RPKI toolkit.  It's not complete yet.  At the moment, its primary

+purpose is just to move fragments of such a list out of other

+documentation pages where they just clutter things up and make the

+text unreadable.

+

+== RP tools ==

+

+Relying party ("RP") tools.

+

+=== rcynic ===

+

+rcynic is the primary validation tool.

+

+See the [[wiki:doc/RPKI/RP/rcynic|rcynic documentation]] for details.

+

+=== rcynic-html ===

+

+rcynic-html is a post-processor which converts rcyic's XML status

+output into a set of HTML pages displaying status and history.

+

+=== rcynic-cron ===

+

+rcynic-cron is a small script to run the most common set of relying

+party tools under cron.

+

+=== rtr-origin ===

+

+rtr-origin is an implementation of the rpki-rtr protocol, using

+[[#rcynic|rcynic's]] output as its data source.

+

+See the [[wiki:doc/RPKI/RP/rpki-rtr|rtr-origin documentation]] for details.

+

+=== roa-to-irr ===

+

+roa-to-irr is an experimental program for converting RPKI ROA data

+into IRR data.  Some operators have established procedures that depend

+heavily on IRR, so being able to distribute validated RPKI data via

+IRR is somewhat useful to these operators.

+

+roa-to-irr expects its output to be piped to the `irr_rpsl_submit`

+program.

+

+Opinions vary regarding exactly what the RPSL corresponding to a

+particular set of ROAs should look like, so roa-to-irr is currently

+experimental code at best.  Operators who really care about this may

+well end up writing their own ROA to IRR conversion tools.

diff --git a/doc/wiki-dump/doc%2FRPKI%2FProtocols b/doc/wiki-dump/doc%2FRPKI%2FProtocols
new file mode 100644
index 00000000..5b852d41
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FProtocols
@@ -0,0 +1,8 @@
+= Overview Of RPKI Protocols =

+

+[[TracNav(doc/RPKI/TOC)]]

+

+Brief overview of certain RPKI protocols.  This is a work in progress.

+

+* [[wiki:doc/RPKI/Protocols/OOB|The out-of-band setup protocol]]

+* [[wiki:doc/RPKI/Protocols/Up-Down|The "Up-Down" provisioning protocol]]

diff --git a/doc/wiki-dump/doc%2FRPKI%2FProtocols%2FOOB b/doc/wiki-dump/doc%2FRPKI%2FProtocols%2FOOB
new file mode 100644
index 00000000..7e6e77ea
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FProtocols%2FOOB
@@ -0,0 +1,15 @@
+= The RPKI Out-Of-Band Setup Protocol =

+

+[[TracNav(doc/RPKI/TOC)]]

+

+This protocol configures the initial URLs and BPKI certificates needed

+to operate the up-down and publication protocols.  This is not an IETF

+standard of any kind.  The rpki.net code is, as far as we know, the

+only complete implementation of this protocol, but other RPKI CA

+packages implement portions of it for interoperability.

+

+In the long run we intend to clean this up and submit the cleaned-up

+version as a candidate for IETF standardization, since it seems to be

+in everyone's best interests, but we're not there yet.

+

+[[Image(oob-setup.svg)]]

diff --git a/doc/wiki-dump/doc%2FRPKI%2FProtocols%2FUp-Down b/doc/wiki-dump/doc%2FRPKI%2FProtocols%2FUp-Down
new file mode 100644
index 00000000..ed5fb0a1
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FProtocols%2FUp-Down
@@ -0,0 +1,8 @@
+= RPKI "Up-Down" Provisioning Protocol =

+

+[[TracNav(doc/RPKI/TOC)]]

+

+This is the provisioning protocol described in

+[[http://www.rfc-editor.org/rfc/rfc6492.txt|RFC-6492]].

+

+[[Image(up-down.svg)]]

diff --git a/doc/wiki-dump/doc%2FRPKI%2FRP b/doc/wiki-dump/doc%2FRPKI%2FRP
new file mode 100644
index 00000000..a05cb2ab
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FRP
@@ -0,0 +1,81 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= RPKI Relying Party Tools =

+

+These tools implements the "relying party" role of the RPKI system,

+that is, the entity which retrieves RPKI objects from repositories,

+validates them, and uses the result of that validation process as

+input to other processes, such as BGP security.

+

+See the [[CA|CA tools]] for programs to help you generate RPKI

+objects, if you need to do that.

+

+The RP main tools are [[#rcynic|rcynic]] and

+[[#rpki-rtr|rpki-rtr]], each of which is discussed below.

+

+The installation process sets up everything you need for a basic RPKI

+validation installation.  You will, however, need to think at least

+briefly about which [[#trust-anchors|RPKI trust anchors]] you are

+using, and may need to change these from the defaults.

+

+The installation process sets up a cron job running running

+[[#rcynic-cron|rcynic-cron]] as user "`rcynic`" once per hour at a

+randomly-selected minute.

+

+== rcynic ==

+

+rcynic is the primary validation tool.  It does the actual work of

+RPKI validation: checking syntax, signatures, expiration times, and

+conformance to the profiles for RPKI objects.  The other relying party

+programs take rcynic's output as their input.

+

+The installation process sets up a basic rcynic configuration.  See

+the [[wiki:doc/RPKI/RP/rcynic|rcynic documentation]] if you need to

+know more.

+

+See the [[#trust-anchors|discussion of trust anchors]].

+

+== rpki-rtr ==

+

+rpki-rtr is an implementation of the rpki-rtr protocol, using

+rcynic's output as its data source.  rpki-rtr includes the rpki-rtr

+server, a test client, and a utiltity for examining the content of the

+database rpki-rtr generates from the data supplied by rcynic.

+

+See the [[wiki:doc/RPKI/RP/rpki-rtr|rpki-rtr documentation]] for

+further details.

+

+== rcynic-cron ==

+

+rcynic-cron is a small script to run the most common set of relying

+party tools under cron.  See the

+[[wiki:doc/RPKI/RP/RunningUnderCron|discussion of running relying party tools under cron]]

+for further details.

+

+== Selecting trust anchors == #trust-anchors

+

+As in any PKI system, validation in the RPKI system requires a set of

+"trust anchors" to use as a starting point when checking certificate

+chains.  By definition, trust anchors can only be selected by you, the

+relying party.

+

+As with most other PKI software, we supply a default set of trust

+anchors which you are welcome to use if they suit your needs.  These

+are installed as part of the normal installation process, so if you

+don't do anything, you'll get these.  You can, however, override this

+if you need something different; see

+[[wiki:doc/RPKI/RP/rcynic|the rcynic documentation]] for details.

+

+Remember: It's only a trust anchor if **you** trust it.  We can't make

+that decision for you.

+

+Also note that, at least for now, ARIN's trust anchor locator is

+absent from the default set of trust anchors.  This is not an

+accident: it's the direct result of a deliberate policy decision by

+ARIN to require anyone using their trust anchor to

+[[https://www.arin.net/resources/rpki/faq.html#tal|jump through legal hoops]].

+If you have a problem with this,

+[[http://lists.arin.net/mailman/listinfo/arin-ppml|complain to ARIN]].

+If and when ARIN changes this policy, we will be happy to include

+their trust anchor locator along with those of the other RIRs.

diff --git a/doc/wiki-dump/doc%2FRPKI%2FRP%2FHierarchicalRsync b/doc/wiki-dump/doc%2FRPKI%2FRP%2FHierarchicalRsync
new file mode 100644
index 00000000..6727b073
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FRP%2FHierarchicalRsync
@@ -0,0 +1,103 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= Running a hierarchical rsync configuration =

+

+Having every relying party on the Internet contact every publication

+service is not terribly efficient.  In many cases, it may make more

+sense to use a hierarchical configuration in which a few "gatherer"

+relying parties contact the publication servers directly, while a

+collection of other relying parties get their raw data from the

+gatherers.

+

+ Note:: The relying parties in this configuration still perform their

+   own validation, they just let the gatherers do the work of

+   collecting the unvalidated data for them.

+

+A gatherer in a configuration like this would look just like a

+stand-alone relying party as discussed [[#cronjob|above]].  The only

+real difference is that a gatherer must also make its unauthenticated

+data collection available to other relying parties.  Assuming the

+standard configuration, this will be the directory

+`/var/rcynic/data/unauthenticated` and its subdirectories.

+

+There are two slightly different ways to do this with rsync:

+

+1. Via unauthenticated rsync, by configuring an `rsyncd.conf`

+   "module", or

+

+2. Via rsync over a secure transport protocol such as ssh.

+

+Since the downstream relying party performs its own validation in any

+case, either of these will work, but using a secure transport such as

+ssh makes it easier to track problems back to their source if a

+downstream relying party concludes that it's been receiving bad

+data.

+

+Script for a downstream relying party using ssh might look like this:

+

+{{{

+#!sh

+#!/bin/sh -

+

+PATH=/usr/bin:/bin:/usr/local/bin

+umask 022

+eval `/usr/bin/ssh-agent -s` >/dev/null

+/usr/bin/ssh-add /root/rpki_ssh_id_rsa 2>&1 | /bin/fgrep -v 'Identity added:'

+hosts='larry.example.org moe.example.org curly.example.org'

+for host in $hosts

+do

+  /usr/bin/rsync --archive --update --safe-links rpkisync@${host}:/var/rcynic/data/unauthenticated/ /var/rcynic/data/unauthenticated.${host}/

+done

+eval `/usr/bin/ssh-agent -s -k` >/dev/null

+for host in $hosts

+do

+  /usr/sbin/chroot -u rcynic -g rcynic /var/rcynic /bin/rcynic -c /etc/rcynic.conf -u /data/unauthenticated.${host}

+  /var/rcynic/bin/rcynic-html /var/rcynic/data/rcynic.xml /usr/local/www/data/rcynic.${host}

+done

+cd /var/rcynic/rpki-rtr

+/usr/bin/su -m rcynic -c '/usr/local/bin/rpki-rtr cronjob /var/rcynic/data/authenticated'

+}}}

+

+where /root/rpki_ssh_id_rsa is an SSH private key authorized to log in

+as user "rpkisync" on the gatherer machines.  If you want to lock this

+down a little tighter, you could use ssh's `command="..."`

+mechanism as described in the sshd documentation to restrict the

+rpkisync user so that it can only run this one rsync command.

+

+If you prefer to use insecure rsync, perhaps to avoid allowing the

+downstream relying parties any sort of login access at all on the

+gatherer machines, the configuration would look more like this:

+

+{{{

+#!sh

+#!/bin/sh -

+

+PATH=/usr/bin:/bin:/usr/local/bin

+umask 022

+hosts='larry.example.org moe.example.org curly.example.org'

+for host in $hosts

+do

+  /usr/bin/rsync --archive --update --safe-links rsync://${host}/unauthenticated/ /var/rcynic/data/unauthenticated.${host}/

+done

+for host in $hosts

+do

+  /usr/sbin/chroot -u rcynic -g rcynic /var/rcynic /bin/rcynic -c /etc/rcynic.conf -u /data/unauthenticated.${host}

+  /var/rcynic/bin/rcynic-html /var/rcynic/data/rcynic.xml /usr/local/www/data/rcynic.${host}

+done

+cd /var/rcynic/rpki-rtr

+/usr/bin/su -m rcynic -c '/usr/local/bin/rpki-rtr cronjob /var/rcynic/data/authenticated'

+}}}

+

+where "unauthenticated" here is an rsync module pointing at

+`/var/rcynic/data/unauthenticated` on each of the gatherer

+machines.  Configuration for such a module would look like:

+

+{{{

+#!ini

+[unauthenticated]

+    read only           = yes

+    transfer logging    = yes

+    path                = /var/rcynic/data/unauthenticated

+    comment             = Unauthenticated RPKI data

+}}}

diff --git a/doc/wiki-dump/doc%2FRPKI%2FRP%2FRunningUnderCron b/doc/wiki-dump/doc%2FRPKI%2FRP%2FRunningUnderCron
new file mode 100644
index 00000000..dd323c1a
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FRP%2FRunningUnderCron
@@ -0,0 +1,72 @@
+[[TracNav(doc/RPKI/TOC)]]

+

+= Running relying party tools under cron =

+

+rcynic is the primary relying party tool, and it's designed to run

+under the cron daemon.  Consequently, most of the other tools are also

+designed to run under the cron daemon, so that they can make use of

+rcynic's output immediately after rcynic finishes a validation run.

+

+[[wiki:doc/RPKI/RP#rcynic-cron|rcynic-cron]] runs the basic set of

+relying party tools (`rcynic`, `rcynic-html`, and `rpki-rtr cronjob`);

+if this suffices for your purposes, you don't need to do anything

+else.  This section is a discussion of alternative approaches.

+

+Which tools you want to run depends on how you intend to use the

+relying party tools.  Here we assume a typical case in which you want

+to gather and validate RPKI data and feed the results to routers using

+the rpki-rtr protocol.  We also assume that everything has been

+installed in the default locations.

+

+The exact sequence for invoking rcynic itself varies depending both on

+whether you're using a chroot jail or not and on the platform on which

+you're running rcynic, as the chroot utilities on different platforms

+behave slightly differently.  Using a chroot jail used to be the

+default for rcynic, but it turned out that many users found the setup

+involved to be too complex.

+

+If you're not using rcynic-cron, it's probably simplest to generate a

+short shell script which calls the tools you want in the correct

+order, so that's what we show here.

+

+Once you've written this script, install it in your crontab, running

+at some appropriate interval: perhaps hourly, or perhaps every six

+hours, depending on your needs.  You should run it at least once per

+day, and probably should not run it more frequently than once per hour

+unless you really know what you are doing.  Please do //NOT// just

+arrange for the script to run on the hour, instead pick some random

+minute value within the hour as the start time for your script, to

+help spread the load on the repository servers.

+

+On FreeBSD or MacOSX, this script might look like this:

+

+{{{

+#!sh

+#!/bin/sh -

+/usr/sbin/chroot -u rcynic -g rcynic /var/rcynic /bin/rcynic -c /etc/rcynic.conf || exit

+/var/rcynic/bin/rcynic-html /var/rcynic/data/rcynic.xml /usr/local/www/data/rcynic

+/usr/bin/su -m rcynic -c '/usr/local/bin/rpki-rtr cronjob /var/rcynic/data/authenticated /var/rcynic/rpki-rtr'

+}}}

+

+This assumes that you have done

+{{{

+mkdir /var/rcynic/rpki-rtr

+chown rcynic /var/rcynic/rpki-rtr

+}}}

+

+On GNU/Linux systems, the script might look like this if you use the chrootuid program:

+

+{{{

+#!sh

+#!/bin/sh -

+/usr/bin/chrootuid /var/rcynic rcynic /bin/rcynic -c /etc/rcynic.conf || exit

+/var/rcynic/bin/rcynic-html /var/rcynic/data/rcynic.xml /var/www/rcynic

+/usr/bin/su -m rcynic -c '/usr/local/bin/rpki-rtr cronjob /var/rcynic/data/authenticated /var/rcynic/rpki-rtr'

+}}}

+

+If you use the chroot program instead of chrootuid, change the line that invokes rcynic to:

+

+{{{

+#!sh

+/usr/sbin/chroot --userspec rcynic:rcynic /var/rcynic /bin/rcynic -c /etc/rcynic.conf || exit

+}}}

diff --git a/doc/wiki-dump/doc%2FRPKI%2FRP%2Frcynic b/doc/wiki-dump/doc%2FRPKI%2FRP%2Frcynic
new file mode 100644
index 00000000..6dc30ebe
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FRP%2Frcynic
@@ -0,0 +1,690 @@
+= rcynic RPKI validator =

+

+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+`rcynic` is the core RPKI relying party tool, and is the code which

+performs the actual RPKI validation.  Most of the other relying party

+tools just use `rcynic`'s output.

+

+The name is short for "cynical rsync", because `rcynic`'s task involves

+an interleaved process of `rsync` retrieval and RPKI validation.

+

+This code was developed on FreeBSD, and has been tested most heavily

+on FreeBSD versions 6-STABLE through 8-STABLE.  It is also known to

+work on Ubuntu (12.04 LTS), Debian (Wheezy) and Mac OS X (Snow

+Leopard).  In theory it should run on any reasonably POSIX-like

+system.  As far as we know, `rcynic` does not use any seriously

+non-portable features, but neither have we done a POSIX reference

+manual lookup for every function call.  Please report any portability

+problems.

+

+== Don't panic ==

+

+`rcynic` has a lot of options, but it attempts to choose reasonable

+defaults where possible.  The installation process will create a basic

+working `rcynic` configuration for you and arrange for this to run

+hourly under cron.  If all goes well, this should "just work".

+

+`rcynic` has the ability to do all of its work in a chroot jail.  This

+used to be the default configuration, but integrating this properly

+with platform-specific packaging systems (FreeBSD ports, `apt-get` on

+Ubuntu and Debian, etc) proved impractical.  You can still get this

+behavior if you need it, by

+[[wiki:doc/RPKI/Installation/FromSource|installing from source]]

+and using the `--enable-rcynic-jail` option to `./configure`.

+

+The default configuration set up by `make install` and the various

+packaging systems will run `rcynic` under `cron` using the `rcynic-cron`

+wrapper script.  See the

+[[wiki:doc/RPKI/RP/RunningUnderCron|instructions for setting up your own cron jobs]]

+if you need something more complicated; also see the

+[[wiki:doc/RPKI/RP/RunningUnderCron|instructions for setting up hierarchical rsync]]

+if you need to build a complex topology of rcynic validators.

+

+== Overview ==

+

+`rcynic` depends heavily on the OpenSSL `libcrypto` library, and

+requires a reasonably current version of OpenSSL with both RFC 3779

+and CMS support.

+

+`rcynic` expects all certificates, CRLs, and CMS objects to be in DER

+format.  `rcynic` stores its database using filenames derived from the

+RPKI rsync URIs at which the data are published.

+

+All configuration is via an OpenSSL-style configuration file, except

+for selection of the name of the configuration file itself.  A few

+other parameters can also be set from the command line.  The default

+name for the configuration is "`rcynic.conf`"; you can override this

+with the `-c` option on the command line.  The configuration file uses

+OpenSSL's configuration file syntax, and you can set OpenSSL library

+configuration paramaters (eg, "engine" settings) in the config file as

+well.  `rcynic`'s own configuration parameters are in a section called

+"`[rcynic]`".

+

+Most configuration parameters are optional and have defaults which

+should do something reasonable if you are running `rcynic` in a test

+directory.  If you're running rcynic as a system program, perhaps

+under `cron` via the `rcynic-cron` script, you'll want to set

+additional parameters to tell `rcynic` where to find its data and

+where to write its output (the installation process sets these

+parameters for you).  The configuration file itself, however, is not

+optional.  In order for `rcynic` to do anything useful, your

+configuration file **MUST** at minimum tell `rcynic` where to find one

+or more RPKI trust anchors or trust anchor locators (TALs).

+

+=== Trust anchors ===

+

+* To specify a trust anchor, use the `trust-anchor` directive to

+  name the local file containing the trust anchor.

+

+* To specify a trust anchor locator (TAL), use the

+  `trust-anchor-locator` directive to name a local file containing

+  the trust anchor locator.

+

+* To specify a directory containing trust anchors or trust anchor

+  locators, use the `trust-anchor-directory` directive to name the

+  directory.  Files in the specified directory with names ending in

+  `".cer"` will be processed as trust anchors, while files with names

+  ending in `".tal"` will be processed as trust anchor locators.

+

+You may use a combination of these methods if necessary.

+

+Trust anchors are represented as DER-formatted X.509 self-signed

+certificate objects, but in practice trust anchor locators are more

+common, as they reduce the amount of locally configured data to the

+bare minimum and allow the trust anchor itself to be updated without

+requiring reconfiguration of validators like rcynic.  A trust anchor

+locator is a file in the format specified in

+[[http://www.rfc-editor.org/rfc/rfc6490.txt|RFC-6490]], consisting of

+the rsync URI of the trust anchor followed by the Base64 encoding of

+the trust anchor's public key.

+

+Strictly speaking, trust anchors do not need to be self-signed, but

+many programs (including OpenSSL) assume that trust anchors will be

+self-signed.  See the `allow-non-self-signed-trust-anchor`

+configuration option if you need to use a non-self-signed trust

+anchor, but be warned that the results, while technically correct, may

+not be useful.

+

+See the `make-tal.sh` script in this directory if you need to generate

+your own TAL file for a trust anchor.

+

+As of this writing, there still is no single global trust anchor for

+the RPKI system, so you have to provide separate trust anchors for

+each Regional Internet Registry (RIR) which is publishing RPKI data.

+The installation process installs the ones it knows about.

+

+Example of a minimal config file specifying nothing but trust anchor

+locators:

+

+{{{

+#!ini

+[rcynic]

+

+trust-anchor-locator.0 = trust-anchors/apnic.tal

+trust-anchor-locator.1 = trust-anchors/ripe.tal

+trust-anchor-locator.2 = trust-anchors/afrinic.tal

+trust-anchor-locator.3 = trust-anchors/lacnic.tal

+}}}

+    

+Eventually, this should all be collapsed into a single trust anchor,

+so that relying parties don't need to sort this out on their own, at

+which point the above configuration could become something like:

+

+{{{

+#!ini

+[rcynic]

+

+trust-anchor-locator = trust-anchors/iana.tal

+}}}

+

+=== Output directories ===

+

+By default, `rcynic` uses two writable directory trees:

+

+`unauthenticated`::

+

+	Raw data fetched via `rsync`.  In order to take full advantage

+	of `rsync`'s optimized transfers, you should preserve and reuse

+	this directory across `rcynic` runs, so that `rcynic` need not

+	re-fetch data that have not changed.

+

+`authenticated`::

+

+	Data which `rcynic` has checked.  This is the real output of

+	the validation process.

+

+`authenticated` is really a symbolic link to a directory with a name of

+the form "`authenticated`.//<timestamp>//", where //<timestamp>// is an

+ISO 8601 timestamp like `2001-04-01T01:23:45Z`.  `rcynic` creates a new

+timestamped directory every time it runs, and moves the symbolic link

+as an atomic operation when the validation process completes.  The

+intent is that `authenticated` always points to the most recent usable

+validation results, so that programs which use `rcynic`'s output don't

+need to worry about whether an `rcynic` run is in progress.

+

+`rcynic` installs trust anchors specified via the `trust-anchor-locator`

+directive in the `unauthenticated` tree just like any other fetched

+object, and copies them into the `authenticated` trees just like any

+other object once they pass `rcynic`'s checks.

+

+`rcynic` copies trust anchors specified via the `trust-anchor` directive

+into the top level directory of the `authenticated` tree with filenames

+of the form //<xxxxxxxx>//`.`//<n>//`.cer`, where //<xxxxxxxx>// and

+//<n>// are the OpenSSL object name hash and index within the

+resulting virtual hash bucket, respectively.  These are the same

+values that OpenSSL's `c_hash` Perl script would produce.  The reason

+for this naming scheme is that these trust anchors, by definition, are

+not fetched automatically, and thus do not really have publication

+URIs in the sense that every other object in these trees do.  So

+`rcynic` uses a naming scheme which insures:

+

+* that each trust anchor has a unique name within the output tree and

+

+* that trust anchors cannot be confused with certificates: trust

+  anchors always go in the top level of the tree, data fetched via

+  rsync always go in subdirectories.

+

+Trust anchors and trust anchor locators taken from the directory named

+by the `trust-anchor-directory` directive will follow the same naming

+scheme trust anchors and trust anchor locators specified via the

+`trust-anchor` and `trust-anchor-locator` directives, respectively.

+

+== Usage and configuration ==

+

+=== Logging levels ===

+

+`rcynic` has its own system of logging levels, similar to what

+`syslog()` uses, but customized to the specific task `rcynic` performs.

+

+||`log_sys_err`   ||Error from operating system or library        ||

+||`log_usage_err` ||Bad usage (local configuration error)         ||

+||`log_data_err`  ||Bad data (broken certificates or CRLs)        ||

+||`log_telemetry` ||Normal chatter about rcynic's progress        ||

+||`log_verbose`   ||Extra verbose chatter                         ||

+||`log_debug`     ||Only useful when debugging                    ||

+

+=== Command line options ===

+

+||`-c` //configfile// ||Path to configuration file (default: `rcynic.conf`)  ||

+||`-l` //loglevel//   ||Logging level (default: `log_data_err`)              ||

+||`-s`                ||Log via syslog                                       ||

+||`-e`                ||Log via stderr when also using syslog                ||

+||`-j`                ||Start-up jitter interval (see below; default: `600`) ||

+||`-V`                ||Print rcynic's version to standard output and exit   ||

+||`-x`                ||Path to XML "summary" file (see below; no default)   ||

+

+== Configuration file reference ==

+

+`rcynic` uses the OpenSSL `libcrypto` configuration file mechanism.

+All `libcrypto` configuration options (eg, for engine support) are

+available.  All `rcynic`-specific options are in the "`[rcynic]`" section.

+You **MUST** have a configuration file in order for `rcynic` to do

+anything useful, as the configuration file is the only way to list

+your trust anchors.

+

+=== authenticated ===

+

+Path to output directory (where `rcynic` should place objects it

+has been able to validate).

+

+Default: `rcynic-data/authenticated`

+

+=== unauthenticated ===

+

+Path to directory where `rcynic` should store unauthenticatd

+data retrieved via `rsync`.  Unless something goes horribly

+wrong, you want `rcynic` to preserve and reuse this directory

+across runs to minimize the network traffic necessary to bring

+your repository mirror up to date.

+

+Default: `rcynic-data/unauthenticated`

+

+=== rsync-timeout ===

+

+How long (in seconds) to let `rsync` run before terminating the

+`rsync` process, or zero for no timeout.  You want this timeout

+to be fairly long, to avoid terminating `rsync` connections

+prematurely.  It's present to let you defend against evil

+`rsync` server operators who try to tarpit your connection as a

+form of denial of service attack on `rcynic`.

+

+Default: `300`

+

+=== max-parallel-fetches ===

+

+Upper limit on the number of copies of `rsync` that `rcynic` is

+allowed to run at once.  Used properly, this can speed up

+synchronization considerably when fetching from repositories

+built with sub-optimal tree layouts or when dealing with

+unreachable repositories.  Used improperly, this option can

+generate excessive load on repositories, cause synchronization

+to be interrupted by firewalls, and generally creates create a

+public nuisance.  Use with caution.

+

+As of this writing, values in the range 2-4 are reasonably

+safe.  Values above 10 have been known to cause problems.

+

+`rcynic` can't really detect all of the possible problems

+created by excessive values of this parameter, but if rcynic's

+report shows that both successful retrivial and skipped

+retrieval from the same repository host, that's a pretty good

+hint that something is wrong, and an excessive value here is a

+good first guess as to the cause.

+

+Default: `1`

+

+=== rsync-program ===

+

+Path to the rsync program.

+

+Default: `rsync`, but you should probably set this variable rather

+than just trusting the `PATH` environment variable to be set

+correctly.

+

+=== log-level ===

+

+Same as `-l` option on command line.  Command line setting overrides

+config file setting.

+

+Default: `log_log_err`

+

+=== use-syslog ===

+

+Same as `-s` option on command line.  Command line setting overrides

+config file setting.

+

+Values: `true` or `false`.

+

+Default: `false`

+

+=== use-stderr ===

+

+Same as -e option on command line.  Command line setting overrides

+config file setting.

+

+Values: `true` or `false`.

+

+Default: `false`, but if neither `use-syslog` nor `use-stderr` is set,

+log output goes to `stderr`.

+

+=== syslog-facility ===

+

+Syslog facility to use.

+

+Default: local0

+

+=== syslog-priority-xyz ===

+

+(where xyz is an rcynic logging level, above)

+

+Override the syslog priority value to use when

+logging messages at this rcynic level.

+

+Defaults:

+

+||`syslog-priority-log_sys_err`   ||`err`           ||

+||`syslog-priority-log_usage_err` ||`err`           ||

+||`syslog-priority-log_data_err`  ||`notice`        ||

+||`syslog-priority-log_telemetry` ||`info`          ||

+||`syslog-priority-log_verbose`   ||`info`          ||

+||`syslog-priority-log_debug`     ||`debug`         ||

+

+=== jitter ===

+

+Startup jitter interval, same as `-j` option on command line.  Jitter

+interval, specified in number of seconds.  `rcynic` will pick a random

+number within the interval from zero to this value, and will delay for

+that many seconds on startup.  The purpose of this is to spread the

+load from large numbers of `rcynic` clients all running under cron

+with synchronized clocks, in particular to avoid hammering the global

+RPKI `rsync` servers into the ground at midnight UTC.

+

+Default: `600`

+

+=== lockfile ===

+

+Name of lockfile, or empty for no lock.  If you run `rcynic` directly

+under cron, you should use this parameter to set a lockfile so that

+successive instances of rcynic don't stomp on each other.  If you run

+`rcynic` under `rcynic-cron`, you don't need to touch this, as

+`rcynic-cron` maintains its own lock.

+

+Default: no lock

+

+=== xml-summary ===

+

+Enable output of a per-host summary at the end of an `rcynic`

+run in XML format.

+

+Value: filename to which XML summary should be written; "-" will send

+XML summary to standard output.

+

+Default: no XML summary.

+

+=== allow-stale-crl ===

+

+Allow use of CRLs which are past their `nextUpdate` timestamp.

+This is usually harmless, but since there are attack scenarios

+in which this is the first warning of trouble, it's

+configurable.

+

+Values: `true` or `false`.

+

+Default: `true`

+

+=== prune ===

+

+Clean up old files corresponding to URIs that `rcynic` did not

+see at all during this run.  `rcynic` invokes `rsync` with the

+`--delete` option to clean up old objects from collections

+that `rcynic` revisits, but if a URI changes so that `rcynic`

+never visits the old collection again, old files will remain

+in the local mirror indefinitely unless you enable this

+option.

+

+Note: Pruning only happens when `run-rsync` is true.  When the

+`run-rsync` option is false, pruning is not done regardless of

+the setting of the prune option option.

+

+Values: `true` or `false`.

+

+Default: `true`

+

+=== allow-stale-manifest ===

+

+Allow use of manifests which are past their `nextUpdate`

+timestamp.  This is probably harmless, but since it may be an

+early warning of problems, it's configurable.

+

+Values: `true` or `false`.

+

+Default: `true`

+

+=== require-crl-in-manifest ===

+

+Reject publication point if manifest doesn't list the CRL that

+covers the manifest EE certificate.

+

+Values: `true` or `false`.

+

+Default: `false`

+

+=== allow-object-not-in-manifest ===

+

+Allow use of otherwise valid objects which are not listed in the

+manifest.  This is not supposed to happen, but is probably harmless.

+

+Enabling this does, however, often result in noisier logs, as it

+increases the chance that `rcynic` will attempt to validate data which a

+CA removed from the manifest but did not completely remove and revoke

+from the repository.

+

+Values: `true` or `false`

+

+Default: `false`

+

+=== allow-digest-mismatch ===

+

+Allow use of otherwise valid objects which are listed in the

+manifest with a different digest value.

+

+You probably don't want to touch this.

+

+Values: `true` or `false`

+

+Default: `true`

+

+=== allow-crl-digest-mismatch ===

+

+Allow processing to continue on a publication point whose

+manifest lists a different digest value for the CRL than the

+digest of the CRL we have in hand.

+

+You probably don't want to touch this.

+

+Values: `true` or `false`

+

+Default: `true`

+

+=== allow-non-self-signed-trust-anchor ===

+

+Experimental.  Attempts to work around OpenSSL's strong

+preference for self-signed trust anchors.

+

+We're not going to explain this one in any further detail.  If you

+really want to know what it does, Use The Source, Luke.

+

+**Do not even consider enabling this option unless you are intimately

+familiar with both X.509 and the internals of OpenSSL's

+`X509_verify_cert()` function and really know what you are doing.**

+

+Values: `true` or `false`.

+

+Default: `false`

+

+=== run-rsync ===

+

+Whether to run `rsync` to fetch data.  You don't generally want to

+change this except when building complex topologies where `rcynic`

+running on one set of machines acts as aggregators for another set of

+validators.  A large ISP might want to build such a topology so that

+they could have a local validation cache in each POP while minimizing

+load on the global repository system and maintaining some degree of

+internal consistency between POPs.  In such cases, one might want the

+`rcynic` instances in the POPs to validate data fetched from the

+aggregators via an external process, without the POP `rcynic`

+instances attempting to fetch anything themselves.

+

+Values: `true` or `false`.

+

+Default: `true`

+

+=== use-links ===

+

+Whether to use hard links rather than copying valid objects

+from the unauthenticated to authenticated tree.  Using links

+is slightly more fragile (anything that stomps on the

+unauthenticated file also stomps on the authenticated file)

+but is a bit faster and reduces the number of inodes consumed

+by a large data collection.  At the moment, copying is the

+default behavior, but this may change in the future.

+

+Values: `true` or `false`.

+

+Default: `false`

+

+=== rsync-early ===

+

+Whether to force `rsync` to run even when we have a valid manifest for

+a particular publication point and its `nextUpdate` time has not yet

+passed.

+

+This is an experimental feature, and currently defaults to **true**,

+which is the old behavior (running `rsync` regardless of whether we

+have a valid cached manifest).  This default may change once we have

+more experience with `rcynic`'s behavior when run with this option set

+to `false`.

+

+Skipping the `rsync` fetch when we already have a valid cached

+manifest can significantly reduce the total number of `rsync`

+connections we need to make, and significantly reduce the load that

+each validator places on the authoritative publication servers.  As

+with any caching scheme, however, there are some potential problems

+involved with not fetching the latest data, and we don't yet have

+enough experience with this option to know how this will play out in

+practice, which is why this is still considered experimental.

+

+Values: `true` or `false`

+

+Default: `true` (but may change in the future)

+

+=== trust-anchor ===

+

+Specify one RPKI trust anchor, represented as a local file

+containing an X.509 certificate in DER format.  Value of this

+option is the pathname of the file.

+

+**No default**.

+

+=== trust-anchor-locator ===

+

+Specify one RPKI trust anchor locator, represented as a local file in

+the format specified in

+[[http://www.rfc-editor.org/rfc/rfc6490.txt|RFC-6490]].  This a simple

+text format containing an rsync URI and the RSA public key of the

+X.509 object specified by the URI; the first line of the file is the

+URI, the remainder is the public key in Base64 encoded DER format.

+

+Value of this option is the pathname of the file.

+

+**No default**.

+

+=== trust-anchor-directory ===

+

+Specify a directory containing trust anchors, trust anchor locators,

+or both.  Trust anchors in such a directory must have filenames ending

+in "`.cer`"; trust anchor locators in such a directory must have names

+ending in "`.tal`"; any other files will be skipped.

+

+This directive is an alternative to using the `trust-anchor` and

+trust-anchor-locator` directives.  This is probably easier to use than

+the other trust anchor directives when dealing with a collection of

+trust anchors.  This may change on that promised day when we have only

+a single global trust anchor to deal with, but we're not there yet.

+

+**No default**.

+

+== Post-processing rcynic's XML output ==

+

+The distribution includes several post-processors for the XML output

+`rcynic` writes describing the actions it has taken and the validation

+status of the objects it has found.

+

+=== rcynic-html === #rcynichtml

+

+`rcynic-html` converts `rcynic`'s XML output into a collection of HTML

+pages summarizing the results, noting problems encountered, and

+showing some history of `rsync` transfer times and repository object

+counts in graphical form.

+

+`rcynic-cron` runs `rcynic-html` automatically, immediately after running

+`rcynic`.  If for some reason you need to run `rcynic-html` by hand, the

+command syntax is:

+

+{{{

+#!sh

+$ rcynic-html rcynic.xml /web/server/directory/

+}}}

+

+`rcynic-html` will write a collection of HTML and image files to the

+specified output directory, along with a set of RRD databases.

+`rcynic-html` will create the output directory if necessary.

+

+`rcynic-html` requires [[http://www.rrdtool.org/|`rrdtool`]], a

+specialized database and graphing engine designed for this sort of

+work.  You can run `rcynic-html` without `rrdtool` by giving it the

+`--no-show-graphs` option, but the result won't be as useful.

+

+`rcynic-html` gets its idea of where to find the `rrdtool` program from

+autoconf, which usually works.  If for some reason it doesn't work in

+your environment, you will need to tell `rcynic-html` where to find

+`rrdtool`, using the `--rrdtool-binary` option:

+

+{{{

+#!sh

+$ rcynic-html --rrdtoolbinary /some/where/rrdtool rcynic.xml /web/server/directory/

+}}}

+

+=== rcynic.xsl ===

+

+`rcynic.xsl` was an earlier attempt at the same kind of HTML output as

+[[#rcynichtml|rcynic-html]] generates.  XSLT was a convenient language

+for our initial attempts at this, but as the processing involved got

+more complex, it became obvious that we needed a general purpose

+programming language.

+

+If for some reason XSLT works better in your environment than Python,

+you might find this stylesheet to be a useful starting point, but be

+warned that it's significantly slower than `rcynic-html`, lacks many

+features, and is no longer under development.

+

+=== rcynic-text ===

+

+`rcynic-text` provides a quick flat text summary of validation results.

+This is useful primarily in test scripts

+([[wiki:doc/RPKI/CA#smoketest|smoketest]] uses it).

+

+Usage:

+

+{{{

+#!sh

+$ rcynic-text rcynic.xml

+}}}

+

+=== validation_status ===

+

+`validation_status` provides a flat text translation of the detailed

+validation results.  This is useful primarily for checking the

+detailed status of some particular object or set of objects, perhaps

+using a program like `grep` or `awk` to filter `validation_status`'s

+output.

+

+Usage:

+

+{{{

+#!sh

+$ validation_status rcynic.xml

+$ validation_status rcynic.xml | fgrep rpki.misbehaving.org

+$ validation_status rcynic.xml | fgrep object_rejected

+}}}

+

+=== rcynic-svn ===

+

+`rcynic-svn` is a tool for archiving `rcynic`'s results in a

+[[http://subversion.apache.org/|Subversion]] repository.  `rcynic-svn`

+is not integrated into `rcynic-cron`, because this is not something

+that every relying party is going to want to do.  However, for relying

+parties who want to analyze `rcynic`'s output over a long period of

+time, `rcynic-svn` may provide a useful starting point starting point.

+

+To use `rcynic-svn`, you first must set up a Subversion repository and

+check out a working directory:

+

+{{{

+#!sh

+$ svnadmin create /some/where/safe/rpki-archive

+$ svn co file:///some/where/safe/rpki-archive /some/where/else/rpki-archive

+}}}

+

+The name can be anything you like, in this example we call it

+"`rpki-archive`".  The above sequence creates the repository, then

+checks out an empty working directory `/some/where/else/rpki-archive`.

+

+The repository does not need to be on the same machine as the working

+directory, but it probably should be for simplicity unless you have

+some strong need to put it elsewhere.

+

+Once you have the repository and working directory set up, you need to

+arrange for `rcynic-svn` to be run after each `rcynic` run whose results

+you want to archive.  One way to do this would be to run `rcynic-svn` in

+the same cron job as `rcynic-cron`, immediately after `rcynic-cron` and

+specifying the same lock file that `rcynic-cron` uses.

+

+Sample usage, assuming that `rcynic`'s data is in the usual place:

+

+{{{

+#!sh

+$ rcynic-svn --lockfile /var/rcynic/data/lock   \

+        /var/rcynic/data/authenticated          \

+        /var/rcynic/data/unauthenticated        \

+        /var/rcynic/data/rcynic.xml             \

+        /some/where/else/rpki-archive

+}}}

+

+where the last argument is the name of the Subversion working

+directory and the other arguments are the names of those portions of

+`rcynic`'s output which you wish to archive.  Generally, the above set

+(`authenticated`, `unauthenticated`, and `rcynic.xml`) are the ones

+you want, but feel free to experiment.

diff --git a/doc/wiki-dump/doc%2FRPKI%2FRP%2FrcynicChroot b/doc/wiki-dump/doc%2FRPKI%2FRP%2FrcynicChroot
new file mode 100644
index 00000000..d46be8a4
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FRP%2FrcynicChroot
@@ -0,0 +1,214 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= Running rcynic chrooted =

+

+This is an attempt to describe the process of setting up rcynic in a

+chrooted environment.  The installation scripts that ship with rcynic

+attempt to do this automatically when requested for the platforms we

+support, but the process is somewhat finicky, so some explanation

+seems in order.  If you're running on one of the supported platforms,

+the following steps may be handled for you by the Makefiles, but you

+may still want to understand what all this is trying to do.

+

+rcynic itself does not include any direct support for running

+chrooted, but is designed to be (relatively) easy to run in a chroot

+jail.  

+

+To enable chroot support during installation, you should

+[[wiki:doc/RPKI/Installation/FromSource|install from source]] and use

+the `--enable-rcynic-jail` option to `./configure`.

+

+rcynic-cron includes support for running chrooted.  To use it, specify

+the `--chroot` option on rcynic-cron's command line.  This will cause

+rcynic-cron to run rcynic in the chrooted environment.  Note that, in

+order for this to work, rcynic-cron itself must run as root, since

+only root can issue the `chroot()` system call.  When run as root,

+rcynic-cron takes care of changing the user ID of each process it

+starts to the unprivileged "`rcynic`" user.

+

+== Creating the chroot jail environment ==

+

+By far the most tedious and finicky part of setting up rcynic to run

+in a chroot jail is setting the jail itself.  The underlying principal

+is simple and obvious: a process running in the jail can't use files

+outside the jail.  The difficulty is that the list of files that needs

+to be in the jail is system-dependent, can be rather long, and

+sometimes can only be discovered by trial and error.

+

+You'll either need staticly linked copies of rcynic and rsync, or

+you'll need to figure out which shared libraries these programs need

+(try using the "ldd" command).  Here we assume staticly linked

+binaries, because that's simpler, but be warned that statically linked

+binaries are not even possible on some platforms, whether due to

+concious decisions on the part of operating system vendors or due to

+hidden use of dynamic loading by other libraries at runtime.  Once

+again, the Makefiles attempt to do the correct thing for your

+environment if they know what it is, but they might get it wrong.

+

+You may also find that the dynamic loader looks in a different place

+than you (and the Makefiles) would expect when running within the

+chroot jail.  For example, you might think that library

+`/usr/local/lib/libfoo.so` being installed into a jail named

+`/var/rcynic` should go into `/var/rcynic/usr/local/lib/libfoo.so`,

+but we've seen cases where the dynamic loader ended up expecting to

+find it in `/var/rcynic/lib/libfoo.so`.  Getting this right may

+require a bit of trial and error.

+

+You'll need a chroot wrapper program.  As mentioned above, rcynic-cron

+can act as that wrapper program; if this works for you, we recommend

+it, because it works the same way on all platforms and doesn't require

+additional external programs.  Otherwise, you'll have to find a

+suitable wrapper program.  Your platform may already have one (FreeBSD

+does -- `/usr/sbin/chroot`), but if you don't, you can download Wietse

+Venema's "chrootuid" program from

+ftp://ftp.porcupine.org/pub/security/chrootuid1.3.tar.gz.

+

+ Warning::

+	The chroot program included in at least some GNU/Linux

+	distributions is not adaquate to this task.  You need a wrapper

+	that knows how to drop privileges after performing the

+	chroot() operation itself.  If in doubt, use chrootuid.

+

+Unfortunately, the precise details of setting up a proper chroot jail

+vary wildly from one system to another, so the following instructions

+may not be a precise match for the preferred way of doing this on your

+platform.  Please feel free to contribute scripts for other platforms.

+

+1. Build the static binaries.  You might want to test them at this

+   stage too, although you can defer that until after you've got the

+   jail built.

+

+2. Create a userid under which to run rcynic.  Here we'll assume

+   that's a user named "rcynic", whose default group is also named

+   "rcynic".  Do not add any other userids to the rcynic group unless

+   you really know what you are doing.

+

+3. Build the jail.  You'll need, at minimum, a directory in which to

+   put the binaries, a subdirectory tree that's writable by the userid

+   which will be running rcynic and rsync, your trust anchors, and

+   whatever device inodes the various libraries need on your system.

+   Most likely the devices that matter will be `/dev/null`,

+   `/dev/random`, and `/dev/urandom`; if you're running a FreeBSD system

+   with devfs, you do this by mounting and configuring a devfs

+   instance in the jail, on other platforms you probably use the `mknod`

+   program or something similar.

+

+ Important::

+	Other than the directories that you want rcynic and rsync to

+	be able to modify, //nothing// in the initial jail setup should

+	be writable by the rcynic userid.  In particular, rcynic and

+	rsync should //not// be allowed to modify: their own binary

+	images, any of the configuration files, or your trust anchors.

+	It's simplest just to have root own all the files and

+	directories that rcynic and rsync are not allowed to modify,

+	and make sure that the permissions for all of those

+	directories and files make them writable only by root.

+

+Sample jail tree, assuming that we're putting all of this under

+`/var/rcynic`:

+

+{{{

+#!sh

+$ mkdir /var/rcynic

+$ mkdir /var/rcynic/bin

+$ mkdir /var/rcynic/data

+$ mkdir /var/rcynic/dev

+$ mkdir /var/rcynic/etc

+$ mkdir /var/rcynic/etc/trust-anchors

+}}}

+

+Copy your trust anchors into `/var/rcynic/etc/trust-anchors`.

+

+Copy the staticly linked rcynic and rsync into `/var/rcynic/bin`.

+

+Copy `/etc/resolv.conf` and `/etc/localtime` (if it exists) into

+`/var/rcynic/etc`.

+

+Write an rcynic configuration file as `/var/rcynic/etc/rcynic.conf`.  

+Path names in this file must match the jail setup, more on this below.

+

+{{{

+#!sh

+$ chmod -R go-w /var/rcynic

+$ chown -R root:wheel /var/rcynic

+$ chown -R rcynic:rcynic /var/rcynic/data

+}}}

+

+If you're using devfs, arrange for it to be mounted at

+`/var/rcynic/dev`; otherwise, create whatever device inodes you need in

+`/var/rcynic/dev` and make sure that they have sane permissions (copying

+whatever permissions are used in your system `/dev` directory should

+suffice).

+

+`rcynic.conf` to match this configuration:

+

+{{{

+#!ini

+

+[rcynic]

+

+rsync-program		= /bin/rsync

+authenticated		= /data/authenticated

+unauthenticated		= /data/unauthenticated

+xml-summary		= /data/rcynic.xml

+trust-anchor-directory	= /etc/trust-anchors

+}}}

+

+Once you've got all this set up, you're ready to try running rcynic in

+the jail.  Try it from the command line first, then if that works, you

+should be able to run it under cron.

+

+Note: chroot, chrootuid, and other programs of this type are usually

+intended to be run by root, and should //not// be setuid programs

+unless you //really// know what you are doing.

+

+Sample command line:

+

+{{{

+#!sh

+$ /usr/local/bin/chrootuid /var/rcynic rcynic /bin/rcynic -s -c /etc/rcynic.conf

+}}}

+

+Note that we use absolute pathnames everywhere.  This is not an

+accident.  Programs running in jails under cron should not make

+assumptions about the current working directory or environment

+variable settings, and programs running in chroot jails would need

+different `PATH` settings anyway.  Best just to specify everything.

+

+=== Building static binaries ===

+

+On FreeBSD, building a staticly linked rsync is easy: one just sets

+the environment variable `LDFLAGS='-static'` before building rsync and

+the right thing will happen.  Since this is really just GNU configure

+picking up the environment variable, the same trick should work on

+other platforms...except that some compilers don't support `-static`,

+and some platforms are missing some or all of the non-shared libraries

+you'd need to link the resulting binary.

+

+For simplicity, we've taken the same approach with rcynic, so 

+

+{{{

+#!sh

+$ make LDFLAGS='-static'

+}}}

+

+works.  This isn't necessary on platforms where we know that static

+linking works -- the default is static linking where supported.

+

+=== syslog from chrooted environment ===

+

+Depending on how the `syslog()` library call and the syslog daemon

+(`syslogd`, `rsyslogd`, ...) are implemented on your platform, syslog

+may not work properly with rcynic in a chroot jail.  On FreeBSD, the

+easiest way to fix this is to add the following lines to /etc/rc.conf:

+

+{{{

+#!sh

+altlog_proglist="named rcynic"

+rcynic_chrootdir="/var/rcynic"

+rcynic_enable="YES"

+}}}

+

+This tells syslogd to listen on an additional `PF_UNIX` socket within

+rcynic's chroot jail.

diff --git a/doc/wiki-dump/doc%2FRPKI%2FRP%2Frpki-rtr b/doc/wiki-dump/doc%2FRPKI%2FRP%2Frpki-rtr
new file mode 100644
index 00000000..17bb5def
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FRP%2Frpki-rtr
@@ -0,0 +1,213 @@
+[[TracNav(doc/RPKI/TOC)]]

+[[PageOutline]]

+

+= rpki-rtr =

+

+`rpki-rtr` is an implementation of the

+[[http://www.rfc-editor.org/rfc/rfc6810.txt|"RPKI-router" protocol (RFC-6810)]].

+

+`rpki-rtr` depends on [[rcynic|`rcynic`]] to collect and validate the

+RPKI data.  `rpki-rtr`'s's job is to serve up that data in a

+lightweight format suitable for routers that want to do prefix origin

+authentication.

+

+To use `rpki-rtr`, you need to do two things beyond just running `rcynic`:

+

+1. You need to [[#cronjob-mode|post-process `rcynic`'s output]] into the

+   data files used by rpki-rtr.  The `rcynic-cron` script handles this

+   automatically, so the default installation should already be taking

+   care of this for you.

+

+2. You need to [[#server-mode|set up a listener]] for the `rpki-rtr`

+   server, using the generated data files.  The platform-specific

+   packages for FreeBSD, Debian, and Ubuntu automatically set up a

+   plain TCP listener, but you will have to do something on other

+   platforms, or if you're using a transport protocol other than plain

+   TCP.

+

+== Post-processing rcynic's output == #cronjob-mode

+

+`rpki-rtr` is designed to do the translation from raw RPKI data into

+the rpki-rtr protocol only once.  It does this by pre-computing the

+answers to all the queries it is willing to answer for a given data

+set, and storing them on disk.  `rpki-rtr`'s `cronjob` command handles

+this computation.

+

+To set this up, add an invocation of `rpki-rtr cronjob` to the

+cron job you're already running to run `rcynic`.  As mentioned above,

+if you're running the `rcynic-cron` script, this is already being done

+for you automatically, so you don't need to do anything.  If you've

+written your own cron script, you'll need to add something like this

+to your script:

+

+{{{

+#!sh

+/usr/local/bin/rpki-rtr cronjob /var/rcynic/data/authenticated /var/rcynic/rpki-rtr

+}}}

+

+`rpki-rtr cronjob` needs write access to a directory where it can

+store pre-digested versions of the data it pulls from `rcynic`.  In

+the example above, the directory `/var/rcynic/rpki-rtr` should be

+writable by the user ID that is executing the cron script.

+

+`rpki-rtr` creates a collection of data files, as well as a

+subdirectory in which each instance of `rpki-rtr server` can place a

+`PF_UNIX` socket file.  By default, `rpki-rtr` creates these files

+under the directory in which you run it, but you can change that by

+specifying the target directory as a second command line argument, as

+shown above.

+

+You should make sure that `rpki-rtr cronjob` runs at least once before

+attempting to configure `rpki-rtr server`.  Nothing terrible will

+happen if you don't do this, but `rpki-rtr server` invocations started

+before the first `rpki-rtr cronjob` run may behave oddly.

+

+== Setting up the rpki-rtr server == #server-mode

+

+You need to to set up a server listener that invokes `rpki-rtr

+server`.  What kind of server listener you set up depends on which

+network protocol you're using to transport this protocol.  `rpki-rtr`

+is happy to run under inetd, xinetd, sshd, or pretty much anything --

+`rpki-rtr` doesn't really care, it just reads from `stdin` and writes

+to `stdout`.

+

+`rpki-rtr server` should be run as a non-privileged user (it is

+read-only for a reason).  You may want to set up a separate UNIX

+userid for this purpose.

+

+`rpki-rtr server` takes an optional argument specifying the path to

+its data directory; if you omit this argument, it uses the directory

+in in which you run it.

+

+The details of how you set up a listener for this vary depending on

+the network protocol and the operating system on which you run it.

+Here are three examples, for running under `inetd` on FreeBSD, under

+`sshd`, or as a free-standing server using `rpki-rtr listener`.

+

+=== Running rpki-rtr server under inetd === #under-inetd

+

+Running under `inetd` with plain TCP is insecure and should only be done

+for testing, but you can also run it with TCP-MD5 or TCP-AO, or over

+IPsec.  The inetd configuration is generally the same, the details of

+how you set up TCP-MD5, TCP-AO, or IPsec are platform specific.

+

+To run under `inetd`, you need to:

+

+a. Add an entry to `/etc/services` defining a symbolic name for the

+   port, if one doesn't exist already.  At present there is no

+   well-known port defined for this protocol, for this example we'll

+   use port 42420 and the symbolic name `rpki-rtr`.

+

+   Add to `/etc/services`:

+

+   {{{

+   rpki-rtr          42420/tcp

+   }}}

+

+b. Add the service line to `/etc/inetd.conf`:

+

+   {{{

+   rpki-rtr stream tcp nowait nobody /usr/local/bin/rpki-rtr rpki-rtr server /var/rcynic/rpki-rtr

+   }}}

+

+   This assumes that you want the server to run as user "nobody",

+   which is generally a safe choice, or you could create a new

+   non-priviledged user for this purpose.  **DO NOT** run the server

+   as root; it shouldn't do anything bad, but it's a network server

+   that doesn't need root access, therefore it shouldn't have root

+   access.

+

+=== Running rpki-rtr server under sshd ===

+

+To run `rpki-rtr server` under `sshd`, you need to:

+

+a. Decide whether to run a new instance of sshd on a separate port or

+   use the standard port.  `rpki-rtr` doesn't care, but some people

+   seem to think that it's somehow more secure to run this service on

+   a different port.  Setting up `sshd` in general is beyond the scope

+   of this documention, but most likely you can copy the bulk of your

+   configuration from the standard config.

+

+b. Configure `sshd` to know about the `rpki-rtr` subsystem.  Add something

+   like this to your `sshd.conf`:

+

+   {{{

+   Subsystem rpki-rtr /usr/local/bin/rpki-rtr

+   }}}

+

+c. Configure the userid(s) you expect SSH clients to use to connect to

+   the server.  For operational use you almost certainly do //NOT//

+   want this user to have a normal shell, instead you should configure

+   its shell to be the server (`/usr/local/bin/rpki-rtr` or wherever

+   you've installed it on your system) and its home directory to be

+   the `rpki-rtr` data directory (`/var/rcynic/rpki-rtr` or whatever

+   you're using).  If you're using passwords to authenticate instead

+   of ssh keys (not recommended) you will always need to set the

+   password(s) here when configuring the userid(s).

+

+d. Configure the `.ssh/authorized_keys` file for your clients; if you're

+   using the example values given above, this would be

+   `/var/rcynic/rpki-rtr/.ssh/authorized_keys`.  You can have multiple

+   SSH clients using different keys all logging in as the same SSH

+   user, you just have to list all of the SSH keys here.  You may want

+   to consider using a `command=` parameter in the key line (see the

+   `sshd(8)` man page) to lock down the SSH keys listed here so that

+   they can only be used to run the `rpki-rtr` service.

+

+   If you're running a separate `sshd` for this purpose, you might also

+   want to add an `!AuthorizedKeysFile` entry pointing at this

+   `authorized_keys` file so that the server will only use this

+   `authorized_keys` file regardless of what other user accounts might

+   exist on the machine:

+

+   {{{

+   AuthorizedKeysFile /var/rcynic/rpki-rtr/.ssh/authorized_keys

+   }}}

+

+   There's a sample `sshd.conf` in the source directory.  You will have

+   to modify it to suit your environment.  The most important part is

+   the `Subsystem` line, which runs the `server.sh` script as the

+   "`rpki-rtr`" service, as required by the protocol specification.

+

+=== Running rpki-rtr listener ===

+

+`rpki-rtr listener` is a free-standing plain TCP server which just

+listens on a TCP socket then forks a child process running `rpki-rtr server`.

+

+All of the [[#under-inetd|caveats regarding plain TCP]] apply to `rpki-rtr listener`.

+

+`rpki-rtr listener` takes one required argument, the TCP port number

+on which to listen; it also accepts a second argument which specifies

+the rcynic output directory, like `rpki-rtr server`.

+

+{{{

+/usr/local/bin/rpki-rtr listener 42420 /var/rcynic/rpki-rtr

+}}}

+

+=== Other transports ===

+

+You can also run this code under `xinetd`, or the netpipes "`faucet`"

+program, or `stunnel`...other than a few lines that might need hacking

+to log the connection peer properly, the program really doesn't care.

+

+You //should//, however, care whether the channel you have chosen is

+secure; it doesn't make a lot of sense to go to all the trouble of

+checking RPKI data then let the bad guys feed bad data into your

+routers anyway because you were running the rpki-rtr link over an

+unsecured TCP connection.

+

+== Other commands ==

+

+`rpki-rtr` has two other commands which might be useful for debugging:

+

+a. `rpki-rtr client` implements a dumb client program for this

+   protocol, over SSH, raw TCP, or by invoking `rpki-rtr server` 

+   directly in a subprocess.  The output is not expected to be useful

+   except for debugging.  Either run it locally where you run the

+   cron job, or run it anywhere on the net, as in

+   {{{

+   $ rpki-rtr client tcp <hostname> <port>

+   }}}

+

+b. `rpki-rtr show` will display a text dump of pre-digested data

+   files in the current directory.

diff --git a/doc/wiki-dump/doc%2FRPKI%2FRRDPtestbed b/doc/wiki-dump/doc%2FRPKI%2FRRDPtestbed
new file mode 100644
index 00000000..01508bf2
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FRRDPtestbed
@@ -0,0 +1,436 @@
+[[PageOutline]]

+

+[[TracNav(doc/RPKI/TOC)]]

+

+= Building a DRLng Certificate Authority on Ubuntu Xenial =

+

+I wanted to build a DRLng (rrdp, integrated root CA, seriously reworked

+and meaner and leaner) Certificate Authority.

+

+* I prefer Ubuntu these days.

+* I wanted to build it on Ubuntu Xenial because Xenial has the upgraded

+  TLS for rrdp.

+

+== System Requirements ==

+

+I built the following:

+

+* 32GB of hard disk, enough to leave headroom unless you plan a LOT of

+  certificates, as in thousands;

+* 2GB or RAM, as it still is a bit of a RAM hog; and

+* One CPU should be enough to start.

+* The server must not have an AAAA DNS RR unless it has working IPv6

+  connectivity.

+

+== Xenial Install ==

+

+* 

+  [http://releases.ubuntu.com/16.04/ubuntu-16.04-server-amd64.iso 16.04 Ubuntu Xenial LTS 64-bit server]

+* I do a fairly basic install, OpenSSH, basic utilities, and grub

+* apt update and apt dist-upgrade of course

+* I install automatic updates, emacs-nox, ntp, ... with ansible.  Note that ansible requires python2 and xenial installs python3.  So I had to install python2.7

+

+I am lazy and log in as root as pretty much everything I do is going to

+require being root.  If you like sudo, then just prefix a lot with it.

+

+== Install the Basic RPKI CA and RP Software ==

+

+You should only need to perform these steps once for any particular

+machine.

+

+Add the GPG public key for this repository (optional, but APT will whine

+unless you do this):

+{{{

+# wget -q -O - http://download.rpki.net/APTng/apt-gpg-key.asc | sudo apt-key add -

+}}}

+

+Configure APT to use this repository (for Ubuntu Trusty systems):

+{{{

+# wget -q -O /etc/apt/sources.list.d/rpki.list http://download.rpki.net/APTng/rpki.trusty.list

+}}}

+

+Update available packages:

+{{{

+# apt update

+}}}

+

+Install the software:

+{{{

+# apt install rpki-rp rpki-ca

+}}}

+

+500kg of packages will be installed.  The daemons should also be started.

+{{{

+# /bin/ps axu | grep rpki | grep -v grep

+rpki      5250  0.0  0.4 308040  8404 ?        Sl   07:37   0:00 (wsgi:rpkigui)    -k start

+rpki      5436  0.0  0.4  45184  9380 ?        Ss   07:37   0:00 /usr/bin/python /usr/lib/rpki/rpki-nanny --log-level warning --log-directory /var/log/rpki --log-rotating-file-hours 3 --log-backup-count 56

+rpki      5437  1.1  2.2 220204 45584 ?        S    07:37   0:00 /usr/bin/python /usr/lib/rpki/irdbd --foreground --log-level warning --log-timed-rotating-file /var/log/rpki/irdbd.log 3 56

+rpki      5439  1.1  2.0 206428 42220 ?        S    07:37   0:00 /usr/bin/python /usr/lib/rpki/pubd --foreground --log-level warning --log-timed-rotating-file /var/log/rpki/pubd.log 3 56

+postgres  5499  0.0  0.7 302016 15272 ?        Ss   07:37   0:00 postgres: rpki rpki [local] idle

+}}}

+

+== Minimal Configuration ==

+

+This example install uses the server hostname `ca.rg.net`.  Any

+use of that hostname below will have to be replaced with your host's

+name, of course.

+

+=== Relying Party - rcynic ===

+

+The RP (Relying Party) software should have installed and should be

+running.  You can test it by browsing to https://ca.rg.net/rcynic/.  It

+uses a self-signed TLS certificate; you can be lazy and decided to

+accept it as opposed to installing a real one.  If you want to use a

+Lets Encrypt certificate, you might try

+[https://wiki.rg.net/AcmeTinyUbuntu this homegrown recipe using acme_tiny.py],

+which will require a bit of hacking as the rpki package

+puts apache credentials in an odd place.

+

+!!!!!!!!!  THE RCYNIC PAGE IS EMPTY  !!!!!!

+

+The rcynic web page has not populated yet because the cron job to

+populate is generated for a socially polite cache which fetches once an

+hour.

+{{{

+# crontab -l -u rpki

+MAILTO=root

+41 * * * *      exec /usr/bin/rcynic-cron

+}}}

+Do not change this now as it would place an asocial load on the global

+RPKI.

+

+If you plan to use the rpki-rtr protocol to feed a router from the RP

+cache you just installed, check `/etc/xinetd.d/rpki-rtr` to be sure the

+port number is 323, the IANA assigned port, as opposed to some old hacks

+that were used pre [http://www.rfc-editor.org/rfc/rfc6810.txt RFC 6810].

+{{{

+# cat > /etc/xinetd.d/rpki-rtr << EOF

+service rpki-rtr

+{

+    type           = UNLISTED

+    flags          = IPv4

+    socket_type    = stream

+    protocol       = tcp

+    port           = 323

+    wait           = no

+    user           = rpkirtr

+    server         = /usr/bin/rpki-rtr

+    server_args    = server /var/rcynic/rpki-rtr

+    }

+EOF

+}}}

+

+If you have to change it, remember to

+{{{

+# systemctl restart xinetd

+}}}

+

+The configuration for rcynic is in `/etc/rpki.conf`.  Note that it

+says to use the trust anchors in the directory

+`/etc/rpki/trust-anchors`.  You may want to change the set of trust

+anchors if you have unusual requirements.

+

+=== CA Configuration - rpki.conf ===

+

+`/etc/rpki.conf` is the core configuration file for the CA.  You need to

+make very minimal changes.  If you want an explanation for all the

+options, go to https://trac.rpki.net/wiki/doc/RPKI/CA/Configuration.

+Get coffee first.

+

+`handle` is generated as `ca_rg_net` or whatever.  You may want to

+change it to something more intuitive such as `testCA` or whatever you

+like.  You do not really need to do this, but let's assume you do.  I

+changed it to `RGnet`, as I was creating a CA for RGnet's resources.

+

+The `handle` in rpkic.conf is a historical relic (dating back to the

+`myrpki.xml` interface, circa 2008).  It's become just the default for

+`-i` / `--identity` / `select_identity` and may eventually go away

+completely.

+

+If you may offer publication services to other CAs, you will want to put

+the contact email in `pubd_contact_info`.

+

+Observe that the `publication_base_directory` expands/decodes to

+`/usr/share/rpki/publication`.  Similarly, `bpki_servers_directory`

+decodes to `/usr/share/rpki`.

+

+That is it for configuration of `/etc/rpki.conf`!

+

+=== rsyncd Configuration ===

+

+Next, you want to get the rsync daemon working.  First you need to tell

+the rsync daemon what it should serve.  So configure `/etc/rsyncd.conf`

+as follows:

+

+{{{

+# cat > /etc/rsyncd.conf << EOF

+uid             = nobody

+gid             = rpki

+

+[rpki]

+    use chroot          = no

+    read only           = yes

+    transfer logging    = yes

+    path                = /usr/share/rpki/publication

+    comment             = RPKI publication

+

+# the following is only of you plan to run a root CA

+[tal]

+    use chroot          = no

+    read only           = yes

+    transfer logging    = yes

+    path                = /usr/share/rpki/rrdp-publication

+    comment             = altCA TAL

+EOF

+}}}

+

+Then tell xinetd to run the rsync deamon when asked and then to restart

+xinetd

+{{{

+# cat > /etc/xinetd.d/rsync << EOF

+service rsync

+{

+    disable         = no

+    socket_type     = stream

+    port            = 873

+    protocol        = tcp

+    wait            = no

+    user            = root

+    server          = /usr/bin/rsync

+    server_args     = --daemon

+    log_on_failure  += USERID

+}

+EOF

+}}}

+

+Remember to

+{{{

+# systemctl restart xinetd

+}}}

+

+== CA Data Initialization ==

+

+The remaining configuration is done using the RPKI software itself.

+

+=== Starting Services ===

+

+Before configuring the CA daemon and database, you should first restart the

+daemons.

+{{{

+# systemctl restart rpki-ca

+}}}

+You should see the daemons running

+{{{

+# /bin/ps axu | grep rpki | grep -v grep

+rpki      5250  0.1  2.7 546316 57316 ?        Sl   07:37   0:00 (wsgi:rpkigui)    -k start

+rpki      5597  0.0  0.3  25348  7132 ?        Ss   07:42   0:00 /usr/bin/python /usr/bin/rcynic-cron

+rpki      5598 25.6  5.7 287132 116880 ?       R    07:42   1:44 /usr/bin/python /usr/bin/rcynic

+postgres  5601  9.9  4.4 305024 91336 ?        Rs   07:42   0:40 postgres: rpki rpki [local] idle

+rpki      7183  0.0  0.4  45184  9440 ?        Ss   07:48   0:00 /usr/bin/python /usr/lib/rpki/rpki-nanny --log-level warning --log-directory /var/log/rpki --log-rotating-file-hours 3 --log-backup-count 56

+rpki      7184  4.0  2.2 220140 45848 ?        S    07:48   0:00 /usr/bin/python /usr/lib/rpki/irdbd --foreground --log-level warning --log-timed-rotating-file /var/log/rpki/irdbd.log 3 56

+rpki      7186  3.7  2.0 206424 42308 ?        S    07:48   0:00 /usr/bin/python /usr/lib/rpki/pubd --foreground --log-level warning --log-timed-rotating-file /var/log/rpki/pubd.log 3 56

+postgres  7193  0.0  0.6 302016 13104 ?        Ss   07:48   0:00 postgres: rpki rpki [local] idle

+}}}

+

+=== Initializing the CA ===

+

+The command utility, `rpkic` is a CLI for dealing with the CA.  This

+example uses it instead of the GUI, especially for initial setup, as it

+is easier to copy and paste into a wiki.  The CLI has tab completion,

+and the other features offered by readline().

+

+It makes life easier if you do all this in a sub-directory to keep it

+all together.  Also, files are written and read from the current

+directory, often with code running under the uid of rpki.  So make the

+director writiable by that uid.

+{{{

+# mkdir CA-data

+# chown rpki CA-data

+# cd CA-data

+}}}

+

+rpkic has the concept of the current identity.  Initially, it starts

+with the identity from the handle in `/etc/rpki.conf`, RGnetCA in this

+example

+{{{

+# rpkic

+rpkic>

+}}}

+

+Before you do anything else, you need to initialize the CA.  Note that

+we now use `create_identity` as opposed to `initialize`.  As mentioned

+previously, for the moment the identity should be the same as the

+`handle` in /etc/rpki.conf.

+{{{

+# rpkic

+# rpkic create_identity RGnet

+Wrote /root/CA-data/RGnet.identity.xml

+This is the "identity" file you will need to send to your parent

+}}}

+

+For testing, copy the identity to the publication point.

+{{{

+# rsync RGnet.identity.xml /usr/share/rpki/publication

+}}}

+

+As the publication point now has data, it is recommended that you test

+it from a remote system

+{{{

+% rsync rsync://ca.rg.net/rpki/RGnet.identity.xml

+-rw-r--r--        1175 2016/04/24 16:53:53 RGnet.identity.xml

+}}}

+

+== Identity and Publication ==

+

+You need to establish the BPKI relationship with your parent CA.  In

+this case, that was RIPE

+

+

+You may want to look below at the 

+[https://trac.rpki.net/wiki/doc/RPKI/RRDPtestbed#UsingtherpkicCLIinsetupphase Using the rpkic CLI in setup phase]

+for a general description of the provisioning steps.

+

+=== The !Identity/Repository Handshake ===

+

+I browsed to

+[https://my.ripe.net/#/provisioning/non-hosted RIPE's provisioning page]

+and uploaded /root/CA-data/RGnet.identity.xml and received back

+issuer-identity-20160513.xml

+

+I used that file to configure my server's view of its parent

+{{{

+# rpkic configure_parent issuer-identity-20160513.xml 

+Parent calls itself '3336711f-25e1-4b5c-9748-e6c58bef82a5', we call it '3336711f-25e1-4b5c-9748-e6c58bef82a5'

+Parent calls us 'f1400649-ab90-4332-b7e3-3da6b7e44cdb'

+Wrote /root/CA-data/RGnet.3336711f-25e1-4b5c-9748-e6c58bef82a5.repository-request.xml

+This is the file to send to the repository operator

+}}}

+

+The CA will need a repository, and we are assuming that we

+will also host it.  So it should accept its own offer made above

+{{{

+# rpkic configure_publication_client RGnet.3336711f-25e1-4b5c-9748-e6c58bef82a5.repository-request.xml 

+This might be an offer, checking

+We don't host this client's parent, so we didn't make an offer

+Don't know where else to nest this client, so defaulting to top-level

+Client calls itself 'RGnet', we call it 'RGnet'

+Wrote /root/CA-data/RGnet.repository-response.xml

+Send this file back to the publication client you just configured

+}}}

+

+And then I configured the repository using the response from above

+{{{

+# rpkic configure_repository RGnet.repository-response.xml

+Repository calls us 'RGnet'

+No explicit parent_handle given, guessing parent 3336711f-25e1-4b5c-9748-e6c58bef82a5

+}}}

+

+You can see if it is publishing, maybe using a bit of coercion 

+{{{

+# rpkic force_publication

+# ls -l /usr/share/rpki/publication

+total 8

+drwxr-xr-x 2 rpki rpki 4096 May 14 07:39 RGnet/

+-rw-r--r-- 1 root root 1175 May 14 07:10 RGnet.identity.xml

+}}}

+

+If the publication sub-directory is not there, go work on something else

+for a while and come back.

+

+=== The GUI Should Now Work ===

+

+One simple test is to try the GUI.  But first you need to set up the GUI

+superuser password.  [ insert lecture on strong passwords ] 

+{{{

+# rpki-manage createsuperuser

+Username (leave blank to use 'rpki'): RGnet

+Email address: randy@psg.com

+Password: 

+Password (again): 

+Superuser created successfully.

+}}}

+and write it down somewhere safe.

+

+Then you can point your browser at `https://ca.rg.net`, and you should

+see the login page.  Enter the user 'RGnet' (per above) and the password

+from createsuperuser above.  This should take you to RGnet's dashboard.

+

+== Using the rpkic CLI in setup phase ==

+

+See the [[..|introduction to the user interfaces]] for an overview of

+how setup phase works.  The general structure of the setup phase in

+rpkic is as described there, but here we provide the specific commands

+involved.  The following assumes that you have already installed the

+software and started the servers.

+

+* The rpkic "initialize" command writes out an "identity.xml" file in

+  addition to all of its other tasks.

+

+* A parent who is using rpkic runs the "configure_child" command to

+  configure the child, giving this command the identity.xml file the

+  child supplied as input.  configure_child will write out a response

+  XML file, which the parent sends back to the child.

+

+* A child who is running rpkic runs the "configure_parent" command to

+  process the parent's response, giving it the XML file sent back by

+  the parent as input to this command.  configure_parent will write

+  out a publication request XML file, which the child sents to the

+  repository operator.

+

+* A repository operator who is using rpkic runs the

+  "configure_publication_client" command to process a client's

+  publication request.  configure_publication_client generates a

+  confirmation XML message which the repository operator sends back to

+  the client.

+

+* A publication client who is using rpkic runs the

+  "configure_repository" command to process the repository's response.

+

+

+

+== Creating a New Root Authority ==

+

+If you also need to be a CA for private address space, legacy space ARIN

+will not certify, etc. you will want to create a root CA.

+

+{{{

+# rpkic configure_root

+Generating root for resources ASN: 0-4294967295, V4: 0.0.0.0/0, V6: ::/0

+Wrote /root/CA-stuff/altCA.altCA.repository-request.xml

+This is the file to send to the repository operator

+}}}

+creates a weird kind of parent object, gives you back the XML for

+repository setup (same as it did before, difference is just the

+implementation).

+

+configure_root can take an optional --resources argument which

+configures the set of resources for the root to hold.  As you can see,

+by default it's everything (0-4294967295,0.0.0.0/8,::/0).

+

+=== Extract Root Certificate and TAL ===

+

+There are two new commands to extract root cert and TAL:

+{{{

+# rpkic extract_root_certificate

+# rpkic extract_root_tal

+}}}

+

+The latter is a bit iffy in the sense that it has no way of knowing

+how you really set up all the things beyond its direct control: the

+TAL it generates should be correct if you used the default setup, but

+if you did something weird (eg, in your Apache or rsyncd

+configuration) it might have the wrong URIs, and it has no real way of

+knowing what you did.

+

+Both certificate and TAL will be written to names derived from the

+g(SKI) of the certificate, in the current directory (.).

+

+You can rename the TAL to anything you like, but you should preserve

+the g(SKI) filename of the certificate, because that's what the TAL

+will be expecting to find.

+

+Note that RRDP does *not* help with publication of the root

+certificate (the root certificate is how the RP finds RRDP, not the

+other way around), so you'll need to put a copy of the root

+certificate in the location named by the HTTPS URI in the TAL

+(/usr/share/rpki/rrdp-publication/ in the default Ubuntu setup).

diff --git a/doc/wiki-dump/doc%2FRPKI%2FTOC b/doc/wiki-dump/doc%2FRPKI%2FTOC
new file mode 100644
index 00000000..8c666d09
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FTOC
@@ -0,0 +1,87 @@
+= RPKI Manual Table Of Contents =

+

+[[TracNav(doc/RPKI/TOC)]]

+

+**DANGER, WILL ROBINSON!!!**

+

+**This is not a normal Wiki page, it's input to a Trac macro.**

+

+**Read carefully before touching anything here.**

+

+This page is the table of contents for the RPKI manual.  This uses the

+!TracNav macro, to avoid replicating the list of pages everywhere;

+instead, each page uses !TracNav to refer to this page, which contains

+the one and only copy.  This list is also used to generate the PDF and

+flat text documentation, via some ad hoc scripting and a preprosterous

+set of text processing tools.

+

+Be very careful when modifying this page.  In particular, be careful

+about modifying the following list, as messing it up will break the

+navigation for the entire manual.

+

+Also note that syntax for links containing square brackets in the

+label is very tricky and somewhat fragile.  We use this for TOC

+entries corresponding to rpki.conf sections.  We can do this using

+WikiCreole link syntax so long as we have whitespace before the double

+close square bracket that ends the link.  Yes, this is a kludge.  See

+http://trac.edgewall.org/ticket/616 for details.

+

+ * [wiki:doc/RPKI				RPKI Tools]

+   * [wiki:doc/RPKI/Installation		Installation]

+     * [wiki:doc/RPKI/Installation/DebianPackages Debian and Ubuntu Binary Packages]

+     * [wiki:doc/RPKI/Installation/FreeBSDPorts   FreeBSD Ports]

+     * [wiki:doc/RPKI/Installation/FromSource   Installing From Source Code]

+   * [wiki:doc/RPKI/RP				Relying Party Tools]

+     * [wiki:doc/RPKI/RP/rcynic			rcynic]

+     * [wiki:doc/RPKI/RP/rpki-rtr		rpki-rtr]

+     * [wiki:doc/RPKI/RP/RunningUnderCron	Alternative cron jobs]

+     * [wiki:doc/RPKI/RP/HierarchicalRsync	Hierarchical rsync]

+     * [wiki:doc/RPKI/RP/rcynicChroot		Running rcynic chrooted]

+   * [wiki:doc/RPKI/CA				CA Tools]

+     * [wiki:doc/RPKI/CA/Configuration			Configuration]

+       * [wiki:doc/RPKI/CA/Configuration/Common		Common Options]

+       * [[wiki:doc/RPKI/CA/Configuration/myrpki|	[myrpki] section	]]

+       * [[wiki:doc/RPKI/CA/Configuration/rpkid|	[rpkid] section		]]

+       * [[wiki:doc/RPKI/CA/Configuration/irdbd|	[irdbd] section		]]

+       * [[wiki:doc/RPKI/CA/Configuration/pubd|		[pubd] section		]]

+       * [[wiki:doc/RPKI/CA/Configuration/rootd|	[rootd] section		]]

+       * [wiki:doc/RPKI/CA/Configuration/CreatingRoot	Creating a RPKI Root Certificate]

+       * [[wiki:doc/RPKI/CA/Configuration/web_portal|	[web_portal] section	]]

+       * [[wiki:doc/RPKI/CA/Configuration/autoconf|	[autoconf] section	]]

+       * [wiki:doc/RPKI/CA/Configuration/Tests		Test configuration]

+       * [wiki:doc/RPKI/CA/Configuration/DifferentServer Using Different Servers]

+     * [wiki:doc/RPKI/CA/MySQLSetup		MySQL Setup]

+     * [wiki:doc/RPKI/CA/OOBSetup		The out-of-band setup protocol]

+     * [wiki:doc/RPKI/CA/UI			The user interface]

+       * [wiki:doc/RPKI/CA/UI/rpkic		Command line interface]

+       * [wiki:doc/RPKI/CA/UI/GUI		Web interface]

+         * [wiki:doc/RPKI/CA/UI/GUI/Installing			Installing the GUI]

+         * [wiki:doc/RPKI/CA/UI/GUI/Upgrading			Upgrading the GUI]

+         * [wiki:doc/RPKI/CA/UI/GUI/Upgrading/BeforeMigration	Before migrating the GUI]

+         * [wiki:doc/RPKI/CA/UI/GUI/Configuring			Configuring the GUI]

+         * [wiki:doc/RPKI/CA/UI/GUI/Configuring/Apache		Configuring Apache for the GUI]

+         * [wiki:doc/RPKI/CA/UI/GUI/UserModel			GUI user model]

+       * [wiki:doc/RPKI/CA/Protocols/LeftRight	The left-right protocol]

+   * [wiki:doc/RPKI/Utils			Utility programs]

+   * [wiki:doc/RPKI/Protocols			Protocol diagrams]

+     * [wiki:doc/RPKI/Protocols/OOB		Out-of-band setup protocol]

+     * [wiki:doc/RPKI/Protocols/Up-Down		"Up-Down" provisioning protocol]

+

+I (sra) just added the GUI subpages as they were missing entirely.

+Titles might need work, and we don't yet know whether the HTML-to-text

+hack will work on these as we haven't tried it yet.

+

+The following is a non-list of nodes in the old (Doxygen) manual which

+don't currently have any place in the new manual.  I haven't yet

+figured out which of these we should keep, or where to put them.  So

+long as they aren't formatted as part of the Wiki list, !TracNav will

+ignore them.

+

+Not sure where these should go yet.  Perhaps a RPKI/CA/Reference

+section, except that sounds too much like a command reference.

+

+RPKI/CA/Protocols/Publication

+RPKI/CA/SQLSchemas

+RPKI/CA/SQLSchemas/pubd

+RPKI/CA/SQLSchemas/rpkid

+RPKI/CA/BPKIModel

diff --git a/doc/wiki-dump/doc%2FRPKI%2FUtils b/doc/wiki-dump/doc%2FRPKI%2FUtils
new file mode 100644
index 00000000..59ae491d
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2FUtils
@@ -0,0 +1,179 @@
+= RPKI utility programs =

+

+[[TracNav(doc/RPKI/TOC)]]

+

+The distribution contains a few small utility programs.  Most of these

+are nominally relying party tools, but work at a low enough level that

+they may also be useful in diagnosing CA problems.

+

+Unless otherwise specified, all of these tools expect RPKI objects

+(certificates, CRLs, CMS signed objects) to be in DER format.

+

+Several of these tools accept an `rcynic_directory` argument.  Which

+directory to specify here depends on what you're trying to do, but if

+you're just trying to look at authenticated data in your RP cache, and

+assuming you've installed everything in the default locations, the

+directory you want is probably `/var/rcynic/data/authenticated`.

+

+== uri ==

+

+`uri` is a utility program to extract URIs from the SIA, AIA, and

+CRLDP extensions of one or more X.509v3 certificates, either specified

+directly or as CMS objects containing X.509v3 certificates within the

+CMS wrapper.

+

+Usage:

+

+{{{

+#!sh

+$ uri [-h | --help] [-s | --single-line] cert [cert...]

+}}}

+

+ `-h --help`::

+   Show help

+ `-s --single-line`::

+    Single output line per input file

+ `cert`::

+    Object(s) to examine

+

+== hashdir ==

+

+`hashdir` copies an authenticated result tree from an rcynic run into

+the format expected by most OpenSSL-based programs: a collection of

+"PEM" format files with names in the form that OpenSSL's `-CApath`

+lookup routines expect.  This can be useful for validating RPKI

+objects which are not distributed as part of the repository system.

+

+Usage:

+

+{{{

+#!sh

+$ hashdir [-h | --help] [-v | --verbose] rcynic_directory output_directory

+}}}

+

+ `-h --help`::

+   Show help

+ `-v --verbose`::

+   Whistle while you work

+ `rcynic_directory`::

+   rcynic authenticated output tree

+ `output_directory`::

+   Output directory to create

+

+== print_rpki_manifest ==

+

+`print_rpki_manifest` pretty-prints the content of a manifest.  It

+does //NOT// attempt to verify the signature.

+

+Usage:

+

+{{{

+#!sh

+$ print_rpki_manifest [-h | --help] [-c | --cms] manifest [manifest...]

+}}}

+

+ `-h --help`::

+    Show help

+ `-c --cms`::

+   Print text representation of entire CMS blob

+ `manifest`::

+   Manifest(s) to print

+

+== print_roa ==

+

+`print_roa` pretty-prints the content of a ROA.  It does //NOT//

+attempt to verify the signature.

+

+Usage:

+

+{{{

+#!sh

+$ print_roa [-h | --help] [-b | --brief] [-c | --cms] [-s | --signing-time] ROA [ROA...]

+}}}

+

+ `-h --help`::

+   Show help

+ `-b --brief`::

+   Brief mode (only show ASN and prefix)

+ `-c --cms`::

+   Print text representation of entire CMS blob

+ `-s --signing-time`::

+   Show CMS signingTime

+ `ROA`::

+   ROA object(s) to print

+

+== find_roa ==

+

+`find_roa` searches the authenticated result tree from an rcynic run

+for ROAs matching specified prefixes.

+

+Usage:

+

+{{{

+#!sh

+$ find_roa [-h | --help] [-a | --all]

+           [-m | --match-maxlength ] [-f | --show-filenames]

+           [-i | --show-inception]   [-e | --show-expiration]

+           authtree [prefix...]

+}}}

+

+ `-h --help`::

+   Show help

+ `-a --all`::

+   Show all ROAs, do no prefix matching at all

+ `-e --show-expiration`::

+   Show ROA chain expiration dates

+ `-f --show-filenames`::

+   Show filenames instead of URIs

+ `-i --show-inception`::

+   Show inception dates

+ `-m -match-maxlength`::

+   Pay attention to maxLength values

+ `authtree`::

+   rcynic authenticated output tree

+ `prefix`::

+   ROA prefix(es) to on which to match

+

+== scan_roas ==

+

+`scan_roas` searchs the authenticated result tree from an rcynic

+run for ROAs, and prints out the signing time, ASN, and prefixes for

+each ROA, one ROA per line.

+

+Other programs such as the [[RP/rpki-rtr|rpki-rtr client]] use

+`scan_roas` to extract the validated ROA payload after an rcynic

+validation run.

+

+Usage:

+

+{{{

+#!sh

+$ scan_roas [-h | --help] rcynic_directory [rcynic_directory...]

+}}}

+

+ `-h --help`::

+   Show help

+ `rcynic_directory`::

+   rcynic authenticated output tree

+

+== scan_routercerts ==

+

+`scan_routercerts` searchs the authenticated result tree from an

+rcynic run for BGPSEC router certificates, and prints out data of

+interest to the rpki-rtr code.

+

+Other programs such as the [[RP/rpki-rtr|rpki-rtr client]] use

+`scan_routercerts` to extract the validated ROA payload after an

+rcynic validation run.

+

+Usage:

+

+{{{

+#!sh

+$ scan_routercerts [-h | --help] rcynic_directory [rcynic_directory...]

+}}}

+

+ `-h --help`::

+   Show help

+ `rcynic_directory`::

+   rcynic authenticated output tree

diff --git a/doc/wiki-dump/doc%2FRPKI%2Fdoc%2FRPKI%2FInstallation%2FUbuntuRP b/doc/wiki-dump/doc%2FRPKI%2Fdoc%2FRPKI%2FInstallation%2FUbuntuRP
new file mode 100644
index 00000000..c421ac2d
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2Fdoc%2FRPKI%2FInstallation%2FUbuntuRP
@@ -0,0 +1,100 @@
+[[PageOutline]]

+

+[[TracNav(doc/RPKI/TOC)]]

+

+= Ubuntu trusty 14.04 RPKI Relying Party Cache Install =

+

+Given a running Ubuntu 14.04 server, this should take ten minutes.

+

+== Ingredients ==

+

+You can start with the following:

+* A small VM, 4GB disk, 512MB RAM, one processor

+* Ubuntu 14.04 i386 server version

+* opensshd, and

+* Emacs, of course

+

+I am lazy and log in as root as pretty much everything I do is going to

+require being root.  If you like sudo, then just prefix a lot with it.

+

+This example uses apt-get.  If you prefer other tools, see the more

+detailed page,

+https://trac.rpki.net/wiki/doc/RPKI/Installation/DebianPackages.

+

+== Install the Basic RPKI RP Software ==

+

+You should only need to perform these steps once for any particular

+machine.

+

+Add the GPG public key for this repository (optional, but APT will whine

+unless you do this): 

+{{{

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

+}}}

+

+Configure APT to use this repository (for Ubuntu Trusty systems):

+{{{

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

+}}}

+

+Update available packages:

+{{{

+apt-get update

+}}}

+

+Install the software:

+{{{

+apt-get install rpki-rp

+}}}

+

+== Minimal Configuration ==

+

+This example install uses the server hostname `test.dfw.rg.net`.  Any

+use of that hostname below will have to be replaced with your host's

+name, of course.

+

+=== Relying Party - rcynic ===

+

+The RP (Relying Party) software should have installed and should be

+running.  You can test it by browsing to

+https://test.dfw.rg.net/rcynic/.  It uses a self-signed TLS certificate;

+you can be lazy and decided to accept it as opposed to installing a real

+one generated from from your own TLS CA; your call.

+

+The rcynic web page had not populated yet because the cron job to

+populate is generated for a socially polite cache which fetches once an

+hour.

+{{{

+test.dfw.rg.net:/root# crontab -u rcynic -l

+MAILTO=root

+49 * * * *      exec /usr/bin/rcynic-cron

+}}}

+Do not change this now as it would place an asocial load on the global

+RPKI.

+

+If you plan to use the rpki-rtr protocol to feed a router from the RP

+cache you just installed, check `/etc/xinetd.d/rpki-rtr` to be sure the

+port number is 323, the IANA assigned port, as opposed to some old hacks

+that were used pre [http://www.rfc-editor.org/rfc/rfc6810.txt RFC 6810].

+{{{

+cat /etc/xinetd.d/rpki-rtr

+service rpki-rtr

+{

+    type           = UNLISTED

+    flags          = IPv4

+    socket_type    = stream

+    protocol       = tcp

+    port           = 323

+    wait           = no

+    user           = rpkirtr

+    server         = /usr/bin/rpki-rtr

+    server_args    = server /var/rcynic/rpki-rtr

+}

+}}}

+

+The configuration for rcynic is in `/etc/rcynic.conf`.  Note that it

+says to use the trust anchors in the directory

+`/etc/rpki/trust-anchors`.  As you intend to install the created root

+instance's trust anchor there, try to remembered how to find it.

+

+That's it!
\ No newline at end of file
diff --git a/doc/wiki-dump/doc%2FRPKI%2Fdoc%2FRPKI%2FInstallation%2FUbuntuRootd b/doc/wiki-dump/doc%2FRPKI%2Fdoc%2FRPKI%2FInstallation%2FUbuntuRootd
new file mode 100644
index 00000000..d877621c
--- /dev/null
+++ b/doc/wiki-dump/doc%2FRPKI%2Fdoc%2FRPKI%2FInstallation%2FUbuntuRootd
@@ -0,0 +1,354 @@
+[[PageOutline]]

+

+[[TracNav(doc/RPKI/TOC)]]

+

+= Ubuntu trusty 14.04 RPKI Install with rootd =

+

+Given a running Ubuntu 14.04 server, this should take an hour or

+less.

+

+== Rationale ==

+

+Due to the ravages of time and the business of hackers, documentation of

+the arcane process of installing the RPKI CA software has not kept as

+current as it might.  Additionally, back in the day, we thought that

+installing a root instance would be exceedingly rare, so tools and

+documentation of that process are poor.  This page attempts to patch

+that pothole.

+

+Many users will be happy installing a rootless CA instance.  This page

+may still help them as it puts everything in one place; just skip the

+root parts.

+

+But a root instance turns out to be very helpful for:

+* Experimenting, where one does not want to mess up the global RPKI

+* Certifying use of RFC1918 and other private spaces

+* Running private environments

+

+== Prerequisites ==

+

+You can start with the following:

+* A small VM, 4GB disk, 512MB RAM, one processor

+* Ubuntu 14.04 i386 server version

+* opensshd, and

+* Emacs, of course

+

+I am lazy and log in as root as pretty much everything I do is going to

+require being root.  If you like sudo, then just prefix a lot with it.

+

+This example uses apt-get.  If you prefer other tools, see the more

+detailed page,

+https://trac.rpki.net/wiki/doc/RPKI/Installation/DebianPackages.

+

+== Install the Basic RPKI CA and RP Software ==

+

+You should only need to perform these steps once for any particular

+machine.

+

+Add the GPG public key for this repository (optional, but APT will whine

+unless you do this): 

+{{{

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

+}}}

+

+Configure APT to use this repository (for Ubuntu Trusty systems):

+{{{

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

+}}}

+

+Update available packages:

+{{{

+apt-get update

+}}}

+

+Install the software:

+{{{

+apt-get install rpki-rp rpki-ca

+}}}

+

+You will be prompted to enter

+{{{

+New password for the MySQL "root" user:

+}}}

+This will be the password for root@localhost on the MySQL server.  Make

+one up, save it somewhere safe, and enter it twice.  [ insert lecture on

+strong passwords. ]

+

+== Minimal Configuration ==

+

+This example install uses the server hostname `test.dfw.rg.net`.  Any

+use of that hostname below will have to be replaced with your host's

+name, of course.

+

+=== Relying Party - rcynic ===

+

+The RP (Relying Party) software should have installed and should be

+running.  You can test it by browsing to

+https://test.dfw.rg.net/rcynic/.  It uses a self-signed TLS certificate;

+you can be lazy and decided to accept it as opposed to installing a real

+one generated from from your own TLS CA; your call.

+

+The rcynic web page had not populated yet because the cron job to

+populate is generated for a socially polite cache which fetches once an

+hour.

+{{{

+test.dfw.rg.net:/root# crontab -u rcynic -l

+MAILTO=root

+49 * * * *      exec /usr/bin/rcynic-cron

+}}}

+Do not change this now as it would place an asocial load on the global

+RPKI.

+

+If you plan to use the rpki-rtr protocol to feed a router from the RP

+cache you just installed, check `/etc/xinetd.d/rpki-rtr` to be sure the

+port number is 323, the IANA assigned port, as opposed to some old hacks

+that were used pre [http://www.rfc-editor.org/rfc/rfc6810.txt RFC 6810].

+{{{

+cat /etc/xinetd.d/rpki-rtr

+service rpki-rtr

+{

+    type           = UNLISTED

+    flags          = IPv4

+    socket_type    = stream

+    protocol       = tcp

+    port           = 323

+    wait           = no

+    user           = rpkirtr

+    server         = /usr/bin/rpki-rtr

+    server_args    = server /var/rcynic/rpki-rtr

+}

+}}}

+

+The configuration for rcynic is in `/etc/rcynic.conf`.  Note that it

+says to use the trust anchors in the directory

+`/etc/rpki/trust-anchors`.  As you intend to install the created root

+instance's trust anchor there, try to remembered how to find it.

+

+=== CA Configuration - rpki.conf ===

+

+`/etc/rpki.conf` is the core configuration file for the CA.  You need to

+make very minimal changes.  If you want an explanation for all the

+options, go to https://trac.rpki.net/wiki/doc/RPKI/CA/Configuration.

+Get coffee first.

+

+`handle` is generated as `test_dfw_rg_net`.  You may want to change it

+to something more intuitive such as `testCA`.  You do not really need to

+do this, but let's assume you do.

+

+`run_rootd` was generated as `no` because most folk do not want to run

+rootd.  But if you intend to have the rootd part of this exercise,

+change it to `yes`.

+

+Observe that the `publication_base_directory` expands/decodes to

+`/usr/share/rpki/publication`.  Similarly, `bpki_servers_directory`

+decodes to `/usr/share/rpki`.

+

+That is it for configuration or `/etc/rpki.conf`!

+

+=== Creating a Root Certificate ===

+

+At this point, you may want to

+{{{

+cd /usr/share/rpki

+}}}

+so that everything is in one place; otherwise it is easy to get

+confused.

+

+If you intend to run a root CA, i.e. run rootd, you need to create a

+root certificate with all possible resources, i.e.\\

+ASs 0-4294967295,\\

+0.0.0.0/0, and\\

+0::/0

+

+sra made a great hack to do this, so you so not have to go through all

+the arcane (and not working for me) instructions on

+https://trac.rpki.net/wiki/doc/RPKI/CA/Configuration/CreatingRoot

+

+{{{

+wget https://subvert-rpki.hactrn.net/trunk/potpourri/generate-root-certificate --no-check-certificate

+}}}

+And then

+{{{

+python generate-root-certificate 

+}}}

+

+This should give you

+{{{

+/usr/share/rpki# ls -l root.*

+-rw-r--r-- 1 root root 1056 Aug  7 06:55 root.cer

+-rw-r--r-- 1 root root 1194 Aug  7 06:55 root.key

+-rw-r--r-- 1 root root  439 Aug  7 06:55 root.tal

+}}}

+

+For security considerations, the root certificate really should not be

+in the publication point.  And the script does not make a stash for it.

+so you should make and use one.

+{{{

+mkdir /usr/share/rpki/publication.root

+rsync root.cer /usr/share/rpki/publication.root

+}}}

+

+Remember that RP software runs from the trust anchors in

+`/etc/rpki/trust-anchors`.  In this example, you want the root to be the

+only trust anchor, so

+{{{

+rm /etc/rpki/trust-anchors/*

+rsync root.tal /etc/rpki/trust-anchors/TestRoot.tal

+}}}

+

+And now it it safe to hack rcynic's crontab to be frequent

+{{{

+crontab -u rcynic -l

+MAILTO=root

+*/10 * * * *    exec /usr/bin/rcynic-cron

+}}}

+

+=== rsyncd Configuration ===

+

+Next, you want to get the rsync daemon working.  First you need to tell

+the rsync daemon what it should serve.  Remember that we decided to

+serve root and data separately.  So configure `/etc/rsyncd.conf` as

+follows: 

+{{{

+cat > /etc/rsyncd.conf << EOF

+uid             = nobody

+gid             = rcynic

+

+[root]

+    use chroot          = no

+    read only           = yes

+    transfer logging    = yes

+    path                = /usr/share/rpki/publication.root

+    comment             = ROOT publication

+

+[rpki]

+    use chroot          = no

+    read only           = yes

+    transfer logging    = yes

+    path                = /usr/share/rpki/publication

+    comment             = RPKI publication

+EOF

+}}}

+

+Then tell xinetd to run the rsync deamon when asked and then to restart

+xinetd

+{{{

+cat > /etc/xinetd.d/rsync << EOF

+service rsync

+{

+    disable         = no

+    socket_type     = stream

+    port            = 873

+    protocol        = tcp

+    wait            = no

+    user            = root

+    server          = /usr/bin/rsync

+    server_args     = --daemon

+    log_on_failure  += USERID

+}

+EOF

+service xinetd restart

+}}}

+

+It is recommended that you test it from a remote system

+{{{

+rsync rsync://test.dfw.rg.net/root/root.cer

+-rw-r--r--        1056 2015/08/07 16:28:10 root.cer

+}}}

+

+== CA Data Initialization ==

+

+The remaining configuration was done using the RPKI software itself.

+

+=== Starting Services ===

+

+Before configuring the CA daemon and database, you should first restart the

+daemons.

+{{{

+service rpki-ca restart

+}}}

+You should see all four daemons running

+{{{

+/bin/ps axu | grep rpki.conf | grep -v grep

+root      1541  0.1  4.0  42244 20580 ?        Ss   Aug07   2:15 /usr/bin/python /usr/lib/rpki/irdbd --config /etc/rpki.conf --log-level warning --log-syslog daemon

+root      1543  0.1  2.8  35144 14232 ?        Ss   Aug07   3:37 /usr/bin/python /usr/lib/rpki/rpkid --config /etc/rpki.conf --log-level warning --log-syslog daemon

+root      1546  0.0  1.9  33584  9780 ?        Ss   Aug07   0:00 /usr/bin/python /usr/lib/rpki/pubd --config /etc/rpki.conf --log-level warning --log-syslog daemon

+root      1559  0.0  1.8  24496  9608 ?        Ss   Aug07   0:22 /usr/bin/python /usr/lib/rpki/rootd --config /etc/rpki.conf --log-level warning --log-syslog daemon

+}}}

+

+=== Initializing the CA ===

+

+The command utility, `rpkic` is a CLI for dealing with the CA.  This

+example uses it instead of the GUI, especially for initial setup, as it

+is easier to copy and paste into a wiki.  The CLI has tab completion,

+and the other features offered by readline().

+

+rpkic has the concept of the current identity.  Initially, it starts

+with the identity from the handle in `/etc/rpki.conf`, testCA in this

+example

+{{{

+rpkic

+rpkic> 

+}}}

+

+Before you do anything else, you need to initialize the CA.

+{{{

+rpkic> initialize

+Wrote /usr/share/rpki/testCA.testCA.repository-request.xml

+This is the "repository offer" file for you to use if you want to publish in your own repository

+Writing /usr/share/rpki/ca.crl

+Writing /usr/share/rpki/rootd.key

+Writing /usr/share/rpki/rootd.cer

+Writing /usr/share/rpki/child.cer

+}}}

+

+The root instance will need a repository, so it should accept its own

+offer made above

+{{{

+rpkic> configure_publication_client /usr/share/rpki/testCA.testCA.repository-request.xml

+This looks like an offer, checking

+This client's parent is rootd

+Don't know where to nest this client, defaulting to top-level

+Client calls itself 'testCA', we call it 'testCA'

+Client says its parent handle is 'testCA'

+Wrote /usr/share/rpki/testCA.repository-response.xml

+Send this file back to the publication client you just configured

+}}}

+

+And then configure the repository using the response

+{{{

+rpkic> configure_repository /usr/share/rpki/testCA.repository-response.xml

+Repository calls us 'testCA'

+Repository response associated with parent_handle 'testCA'

+rpkic> 

+}}}

+

+You can  see if it is publishing

+{{{

+ls -l /usr/share/rpki/publication

+total 16

+-rw-r--r-- 1 root root  433 Aug  7 07:38 root.crl

+-rw-r--r-- 1 root root 1747 Aug  7 07:38 root.mft

+drwxr-xr-x 2 root root 4096 Aug  7 07:38 testCA/

+-rw-r--r-- 1 root root 1219 Aug  7 07:38 testCA.cer

+}}}

+

+=== The GUI Should Now Work ===

+

+One simple test is to try the GUI.  But first you need to set up the GUI

+superuser password.  [ insert lecture on strong passwords ]

+{{{

+rpki-manage createsuperuser

+Username (leave blank to use 'root'): 

+Email address: randy@psg.com

+Password: 

+Password (again): 

+Superuser created successfully.

+}}}

+and write it down somewhere safe.

+

+Then you can point your browser at `https://test.dfw.rg.net`, and you

+should see the login page.  Enter the user 'root' and the password from

+createsuperuser above.  This should take you to testCA's dashboard.  For

+some reason, it often comes up with no resources; so push the Refresh

+button, and it should show that you own the whole Internet!

diff --git a/doc/wiki-dump/rcynic b/doc/wiki-dump/rcynic
new file mode 100644
index 00000000..9511115f
--- /dev/null
+++ b/doc/wiki-dump/rcynic
@@ -0,0 +1,21 @@
+= rcynic RPKI Validator =

+

+`rcynic` is the name of the primary RPKI validation in the rpki.net

+tool kit.

+

+See the [[wiki:doc/RPKI/RP|overview of the rpki.net relying party tools]]

+for an introduction to the tools that a router operator would use to

+retrieve and validate data from the global RPKI system.

+

+See [[wiki:doc/RPKI/Installation|the installation instructions]] for

+details on how to download the code and run it yourself.

+

+You can [[browser:trunk/rcynic|browse the rcynic source code]] if you like.

+

+You can also [[wiki:doc/RPKI|read the full documentation for the toolkit]].

+

+This page is a placeholder to provide a stable reference point for

+external links to rcynic.  It's probably a bad idea for this page to

+replicate too much of the information that's available elsewhere,

+instead this page should provide links to current information.  If you

+disagree and have edit rights in the Wiki, well, OK, fix this.