From c897c7cecf4134f20354e3dbba9438cbab706eaf Mon Sep 17 00:00:00 2001 From: Rob Austein Date: Thu, 4 Aug 2016 12:27:06 -0400 Subject: Wiki->HTML->Markdown on all dumped pages, zip attachments. --- doc/wiki-dump/APRICOT-2013-Hackathon.md | 117 ++++ doc/wiki-dump/JANOG.md | 264 +++++++++ doc/wiki-dump/PresentationArchive.md | 27 + doc/wiki-dump/PresentationArchive.zip | Bin 0 -> 3105591 bytes doc/wiki-dump/Puppet.md | 101 ++++ doc/wiki-dump/WebPortal%2FUpgradingFromSqlite.md | 121 ++++ doc/wiki-dump/WebPortal.md | 86 +++ doc/wiki-dump/WikiStart.md | 88 +++ doc/wiki-dump/convert-and-slurp-attachments.sh | 18 + doc/wiki-dump/doc%2FRPKI%2FCA%2FBPKIModel.md | 98 +++ .../doc%2FRPKI%2FCA%2FConfiguration%2FCommon.md | 72 +++ ...c%2FRPKI%2FCA%2FConfiguration%2FCreatingRoot.md | 142 +++++ ...FRPKI%2FCA%2FConfiguration%2FDifferentServer.md | 38 ++ .../doc%2FRPKI%2FCA%2FConfiguration%2FTests.md | 112 ++++ .../doc%2FRPKI%2FCA%2FConfiguration%2Fautoconf.md | 30 + .../doc%2FRPKI%2FCA%2FConfiguration%2Firdbd.md | 63 ++ .../doc%2FRPKI%2FCA%2FConfiguration%2Fmyrpki.md | 383 ++++++++++++ .../doc%2FRPKI%2FCA%2FConfiguration%2Fpubd.md | 107 ++++ .../doc%2FRPKI%2FCA%2FConfiguration%2Frootd.md | 203 +++++++ .../doc%2FRPKI%2FCA%2FConfiguration%2Frpkid.md | 114 ++++ ...doc%2FRPKI%2FCA%2FConfiguration%2Fweb_portal.md | 60 ++ doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration.md | 229 +++++++ doc/wiki-dump/doc%2FRPKI%2FCA%2FMySQLSetup.md | 77 +++ doc/wiki-dump/doc%2FRPKI%2FCA%2FOOBSetup.md | 5 + .../doc%2FRPKI%2FCA%2FProtocols%2FLeftRight.md | 490 +++++++++++++++ .../doc%2FRPKI%2FCA%2FProtocols%2FPublication.md | 200 +++++++ .../doc%2FRPKI%2FCA%2FSQLSchemas%2Fpubd.md | 11 + .../doc%2FRPKI%2FCA%2FSQLSchemas%2Frpkid.md | 11 + doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas.md | 9 + ...FRPKI%2FCA%2FUI%2FGUI%2FConfiguring%2FApache.md | 108 ++++ .../doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring.md | 108 ++++ .../doc%2FRPKI%2FCA%2FUI%2FGUI%2FInstalling.md | 51 ++ ...FCA%2FUI%2FGUI%2FUpgrading%2FBeforeMigration.md | 97 +++ .../doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading.md | 52 ++ .../doc%2FRPKI%2FCA%2FUI%2FGUI%2FUserModel.md | 156 +++++ doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI.md | 91 +++ doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2Frpkic.md | 89 +++ doc/wiki-dump/doc%2FRPKI%2FCA%2FUI.md | 117 ++++ doc/wiki-dump/doc%2FRPKI%2FCA.md | 254 ++++++++ .../doc%2FRPKI%2FInstallation%2FDebianPackages.md | 81 +++ .../doc%2FRPKI%2FInstallation%2FFreeBSDPorts.md | 123 ++++ .../doc%2FRPKI%2FInstallation%2FFromSource.md | 239 ++++++++ .../doc%2FRPKI%2FInstallation%2FUbuntuPackages.md | 4 + doc/wiki-dump/doc%2FRPKI%2FInstallation.md | 54 ++ doc/wiki-dump/doc%2FRPKI%2FListOfPrograms.md | 54 ++ doc/wiki-dump/doc%2FRPKI%2FProtocols%2FOOB.md | 18 + doc/wiki-dump/doc%2FRPKI%2FProtocols%2FOOB.zip | Bin 0 -> 4627 bytes doc/wiki-dump/doc%2FRPKI%2FProtocols%2FUp-Down.md | 12 + doc/wiki-dump/doc%2FRPKI%2FProtocols%2FUp-Down.zip | Bin 0 -> 4295 bytes doc/wiki-dump/doc%2FRPKI%2FProtocols.md | 11 + .../doc%2FRPKI%2FRP%2FHierarchicalRsync.md | 98 +++ .../doc%2FRPKI%2FRP%2FRunningUnderCron.md | 74 +++ doc/wiki-dump/doc%2FRPKI%2FRP%2Frcynic.md | 655 +++++++++++++++++++++ doc/wiki-dump/doc%2FRPKI%2FRP%2FrcynicChroot.md | 180 ++++++ doc/wiki-dump/doc%2FRPKI%2FRP%2Frpki-rtr.md | 174 ++++++ doc/wiki-dump/doc%2FRPKI%2FRP.md | 91 +++ doc/wiki-dump/doc%2FRPKI%2FRRDPtestbed.md | 455 ++++++++++++++ doc/wiki-dump/doc%2FRPKI%2FTOC.md | 160 +++++ doc/wiki-dump/doc%2FRPKI%2FUtils.md | 204 +++++++ ...FRPKI%2Fdoc%2FRPKI%2FInstallation%2FUbuntuRP.md | 108 ++++ ...KI%2Fdoc%2FRPKI%2FInstallation%2FUbuntuRootd.md | 395 +++++++++++++ doc/wiki-dump/doc%2FRPKI.md | 47 ++ doc/wiki-dump/extract-wiki-content.xsl | 177 ++++++ doc/wiki-dump/rcynic.md | 27 + 64 files changed, 7840 insertions(+) create mode 100644 doc/wiki-dump/APRICOT-2013-Hackathon.md create mode 100644 doc/wiki-dump/JANOG.md create mode 100644 doc/wiki-dump/PresentationArchive.md create mode 100644 doc/wiki-dump/PresentationArchive.zip create mode 100644 doc/wiki-dump/Puppet.md create mode 100644 doc/wiki-dump/WebPortal%2FUpgradingFromSqlite.md create mode 100644 doc/wiki-dump/WebPortal.md create mode 100644 doc/wiki-dump/WikiStart.md create mode 100755 doc/wiki-dump/convert-and-slurp-attachments.sh create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FBPKIModel.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FCommon.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FCreatingRoot.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FDifferentServer.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FTests.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fautoconf.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Firdbd.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fmyrpki.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fpubd.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frootd.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frpkid.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fweb_portal.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FMySQLSetup.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FOOBSetup.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FLeftRight.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FPublication.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Fpubd.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Frpkid.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring%2FApache.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FInstalling.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading%2FBeforeMigration.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUserModel.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2Frpkic.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FUI.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FInstallation%2FDebianPackages.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFreeBSDPorts.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFromSource.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FInstallation%2FUbuntuPackages.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FInstallation.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FListOfPrograms.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FProtocols%2FOOB.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FProtocols%2FOOB.zip create mode 100644 doc/wiki-dump/doc%2FRPKI%2FProtocols%2FUp-Down.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FProtocols%2FUp-Down.zip create mode 100644 doc/wiki-dump/doc%2FRPKI%2FProtocols.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FRP%2FHierarchicalRsync.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FRP%2FRunningUnderCron.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FRP%2Frcynic.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FRP%2FrcynicChroot.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FRP%2Frpki-rtr.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FRP.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FRRDPtestbed.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FTOC.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2FUtils.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2Fdoc%2FRPKI%2FInstallation%2FUbuntuRP.md create mode 100644 doc/wiki-dump/doc%2FRPKI%2Fdoc%2FRPKI%2FInstallation%2FUbuntuRootd.md create mode 100644 doc/wiki-dump/doc%2FRPKI.md create mode 100644 doc/wiki-dump/extract-wiki-content.xsl create mode 100644 doc/wiki-dump/rcynic.md diff --git a/doc/wiki-dump/APRICOT-2013-Hackathon.md b/doc/wiki-dump/APRICOT-2013-Hackathon.md new file mode 100644 index 00000000..c843d61d --- /dev/null +++ b/doc/wiki-dump/APRICOT-2013-Hackathon.md @@ -0,0 +1,117 @@ +# APRICOT 2013 RPKI CA Hackathon, Signapore + +## Options For Installation + + * FreeBSD binary packages (currently only FreeBSD 8-STABLE + * + * + * FreeBSD ports (any recent FreeBSD version) + * + * + * Ubuntu 12.04LTS binary packages + * + * + * [Build from source without package support][1] + * JPNIC has VirtualBox images + * JPNIC has virtual machines + +## FreeBSD binary packages on FreeBSD 8-STABLE + + + + 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 + + + + 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 + + + + 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 + + + + 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 [the documentation][2]). + * FreeBSD: `emacs /usr/local/etc/rpki.conf.sample` + * Ubuntu: `emacs /etc/rpki.conf.sample` + +## Initializing the CA software + + + + 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 + + + service inetd restart + service rpki-ca start + + +## Start the daemons: Ubuntu + + + + sudo initctl start rpki-ca + + +## Dance With Your Parent + +See: [Command line interface documentation][3] + + * 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: [Graphical web interface documentation][4] + + [1]: #_.wiki.doc.RPKI + + [2]: #_.wiki.doc.RPKI.CA.Configuration + + [3]: #_.wiki.doc.RPKI.CA.UI + + [4]: #_.wiki.doc.RPKI.CA.UI.GUI + diff --git a/doc/wiki-dump/JANOG.md b/doc/wiki-dump/JANOG.md new file mode 100644 index 00000000..615ee0a9 --- /dev/null +++ b/doc/wiki-dump/JANOG.md @@ -0,0 +1,264 @@ +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 [VirtualBox][1] [appliance image of Ubuntu 12.04 LTS with +RPKI relying party software][2] already installed, [with documentation][3]; 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 + * If you're running FreeBSD 8, you can try the pre-built FreeBSD package at + * 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 + * Otherwise, you'll have to compile from source as described at [Installation][4], 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 +[Relying Party tools][5], particularly the section on [running the Relying +Party tools under cron][6]. + +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 + * If you're running FreeBSD 8, you can try the pre-built FreeBSD package at + * 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 + * Otherwise, you'll have to compile from source as described at [Installation][4]; 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 +[create an rpki.conf][7] (by editing the provided rpki.conf.sample), then +[configure your MySQL databases][8] before you can start the daemons. + +You will also need to [configure the GUI][9] 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 + + + [1]: https://www.virtualbox.org/ + + [2]: http://psg.com/rpki/RPKI-CA-RP.ova + + [3]: http://psg.com/rpki/RPKI-VM.pdf + + [4]: #_.wiki.doc.RPKI.Installation + + [5]: #_.wiki.doc.RPKI.RP + + [6]: #_.wiki.doc.RPKI.RP#cronjob + + [7]: #_.wiki.doc.RPKI.CA.Configuration + + [8]: #_.wiki.doc.RPKI.CA.MySQLSetup + + [9]: #_.wiki.doc.RPKI.CA.UI.GUI + diff --git a/doc/wiki-dump/PresentationArchive.md b/doc/wiki-dump/PresentationArchive.md new file mode 100644 index 00000000..6eaadb82 --- /dev/null +++ b/doc/wiki-dump/PresentationArchive.md @@ -0,0 +1,27 @@ +## 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/PresentationArchive.zip b/doc/wiki-dump/PresentationArchive.zip new file mode 100644 index 00000000..43e0381a Binary files /dev/null and b/doc/wiki-dump/PresentationArchive.zip differ diff --git a/doc/wiki-dump/Puppet.md b/doc/wiki-dump/Puppet.md new file mode 100644 index 00000000..27ff8162 --- /dev/null +++ b/doc/wiki-dump/Puppet.md @@ -0,0 +1,101 @@ +# 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 , 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 + * 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 + + * + diff --git a/doc/wiki-dump/WebPortal%2FUpgradingFromSqlite.md b/doc/wiki-dump/WebPortal%2FUpgradingFromSqlite.md new file mode 100644 index 00000000..f741c901 --- /dev/null +++ b/doc/wiki-dump/WebPortal%2FUpgradingFromSqlite.md @@ -0,0 +1,121 @@ +# 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/WebPortal.md b/doc/wiki-dump/WebPortal.md new file mode 100644 index 00000000..c41186b6 --- /dev/null +++ b/doc/wiki-dump/WebPortal.md @@ -0,0 +1,86 @@ +# 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 +(). + +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 (). + * 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 + + + * [python-django PPAs][1] + +#### 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 + + + * + +### RHEL/CentOS/Scientific 6 + +Django is not included in base OS, but Django 1.2 is available via 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. + + [1]: https://launchpad.net/~chris-lea/+archive/python-django + diff --git a/doc/wiki-dump/WikiStart.md b/doc/wiki-dump/WikiStart.md new file mode 100644 index 00000000..52156c28 --- /dev/null +++ b/doc/wiki-dump/WikiStart.md @@ -0,0 +1,88 @@ +# 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 [over here][1]. + +## Downloads + +See [the documentation][2] for how to download and install the code. + +We now have [Debian packages][3], [Ubuntu packages][4], and [FreeBSD ports][5] +of the code. + +You can also [browse the source code][6]. + +## Documentation + +Primary [documentation for the code][2] is here, in the Trac wiki. PDF and +flat text forms derived from are available in [the source code repository][6]. + +## Bug Reports + +The [ticket queue][7] is open for public read. Please [register for an +account][8] if you need to create a ticket. + +## Monitoring + +[Current status of RPKI system as seen by one relying party][9]. + +## TLS Certificate + +If you're trying to connect to this site () 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 [download a PGP-signed version of the HACTRN CA certificate][10] 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 [install the HACTRN CA +certificate][11] without checking it. + +## APRICOT 2013 + +Hot link to information for [APRICOT 2013 Hackathon][12]. + +Thanks to JPNIC, [a VirtualBox appliance image][13] is available, [with +documentation][14]. + + [1]: http://wiki.rpki.net/ + + [2]: /wiki/doc/RPKI + + [3]: http://download.rpki.net/APT/debian/ + + [4]: http://download.rpki.net/APT/ubuntu/ + + [5]: http://download.rpki.net/FreeBSD_Packages/ + + [6]: /browser + + [7]: /query + + [8]: /register + + [9]: http://www.hactrn.net/opaque/rcynic/ + + [10]: http://www.hactrn.net/cacert.asc + + [11]: http://www.hactrn.net/cacert.cer + + [12]: #_.wiki.APRICOT-2013-Hackathon + + [13]: http://psg.com/rpki/RPKI-CA-RP.ova + + [14]: http://psg.com/rpki/RPKI-VM.pdf + diff --git a/doc/wiki-dump/convert-and-slurp-attachments.sh b/doc/wiki-dump/convert-and-slurp-attachments.sh new file mode 100755 index 00000000..ce7f34da --- /dev/null +++ b/doc/wiki-dump/convert-and-slurp-attachments.sh @@ -0,0 +1,18 @@ +#!/bin/sh - + +ls | fgrep -v . | +while read page +do + base="https://trac.rpki.net" + path="/wiki/$(echo $page | sed s=%2F=/=g)" + + # Fetch the Wiki page, extract the useful portion of the HTML, convert that into Markdown + curl "${base}${path}" | + xsltproc --html extract-wiki-content.xsl - | + html2markdown --no-skip-internal-links --reference-links >"$page.md" + + # Fetch a ZIP file containing any attachments, clean up if result is empty or broken + curl "${base}/zip-attachment${path}/" >"$page.zip" + zipinfo "$page.zip" >/dev/null 2>&1 || rm -f "$page.zip" + +done diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FBPKIModel.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FBPKIModel.md new file mode 100644 index 00000000..acfe557e --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FBPKIModel.md @@ -0,0 +1,98 @@ +# The BPKI model + +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 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": + +[![No image "rpkid-bpki.png" attached to doc/RPKI/CA/BPKIModel][1]][2] + +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": + +[![No image "pubd-bpki.png" attached to doc/RPKI/CA/BPKIModel][3]][4] + +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. + + [1]: /chrome/common/attachment.png (No image "rpkid-bpki.png" attached to +doc/RPKI/CA/BPKIModel) + + [2]: /attachment/wiki/doc/RPKI/CA/BPKIModel/rpkid-bpki.png + + [3]: /chrome/common/attachment.png (No image "pubd-bpki.png" attached to +doc/RPKI/CA/BPKIModel) + + [4]: /attachment/wiki/doc/RPKI/CA/BPKIModel/pubd-bpki.png + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FCommon.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FCommon.md new file mode 100644 index 00000000..b98a84f8 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FCommon.md @@ -0,0 +1,72 @@ +# RPKI Engine Common Configuration Options + +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 +{{ 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.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FCreatingRoot.md new file mode 100644 index 00000000..eb71cee4 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FCreatingRoot.md @@ -0,0 +1,142 @@ +# Creating an RPKI Root Certificate + +[rootd][1] 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: + + + + [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: + + + + #!/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`: + + + + $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: + + + + 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 + + + [1]: #_.wiki.doc.RPKI.CA.Configuration.rootd + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FDifferentServer.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FDifferentServer.md new file mode 100644 index 00000000..8f2039f0 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FDifferentServer.md @@ -0,0 +1,38 @@ +# 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.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FTests.md new file mode 100644 index 00000000..8eb2f463 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2FTests.md @@ -0,0 +1,112 @@ +# smoketest.yaml + +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.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fautoconf.md new file mode 100644 index 00000000..3ca61429 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fautoconf.md @@ -0,0 +1,30 @@ +# [autoconf] section + +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 + +Usually /usr/bin or /usr/local/bin. + +No default value. + +## datarootdir + +Usually /usr/share or /usr/local/share. + +No default value. + +## sbindir + +Usually /usr/sbin or /usr/local/sbin. + +No default value. + +## sysconfdir + +Usually /etc or /usr/local/etc. + +No default value. + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Firdbd.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Firdbd.md new file mode 100644 index 00000000..8734d643 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Firdbd.md @@ -0,0 +1,63 @@ +# [irdbd] section + +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 + +MySQL database name for irdbd. + + + + sql-database = ${myrpki::irdbd_sql_database} + + +## sql-username + +MySQL user name for irdbd. + + + + sql-username = ${myrpki::irdbd_sql_username} + + +## sql-password + +MySQL password for irdbd. + + + + sql-password = ${myrpki::irdbd_sql_password} + + +## server-host + +Host on which irdbd should listen for HTTP service requests. + + + + server-host = ${myrpki::irdbd_server_host} + + +## server-port + +Port on which irdbd should listen for HTTP service requests. + + + + server-port = ${myrpki::irdbd_server_port} + + +## 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.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fmyrpki.md new file mode 100644 index 00000000..65726bf5 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fmyrpki.md @@ -0,0 +1,383 @@ +# [myrpki] section + +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 + +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 + +Directory for BPKI files generated by rpkic and used by rpkid and pubd. You +will not normally need to change this. + + + + bpki_servers_directory = ${autoconf::datarootdir}/rpki + + +## 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. + + + + run_rpkid = yes + + +## 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 + +Server port number for rpkid. This can be any legal TCP port number that +you're not using for something else. + + + + rpkid_server_port = 4404 + + +## irdbd_server_host + +DNS hostname for irdbd, or "`localhost`". This should be "`localhost`" unless +you really know what you are doing. + + + + irdbd_server_host = localhost + + +## irdbd_server_port + +Server port number for irdbd. This can be any legal TCP port number that +you're not using for something else. + + + + irdbd_server_port = 4403 + + +## 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. + + + + run_pubd = yes + + +## 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 + +Server port number for pubd. This can be any legal TCP port number that you're +not using for something else. + + + + pubd_server_port = 4402 + + +## 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 + +Whether you want to run your very own copy of rootd. Don't enable this unless +you really know what you're doing. + + + + run_rootd = no + + +## rootd_server_host + +DNS hostname for rootd, if you're running it. This should be localhost unless +you really know what you are doing. + + + + rootd_server_host = localhost + + +## 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. + + + + rootd_server_port = 4401 + + +## 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. + + + + publication_base_directory = ${autoconf::datarootdir}/rpki/publication + + +## 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. + + + + publication_root_cert_directory = ${myrpki::publication_base_directory}.root + + +## 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. + + + + publication_rsync_module = rpki + + +## 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. + + + + publication_root_module = root + + +## 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. + + + + publication_rsync_server = ${myrpki::pubd_server_host} + + +## 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. + + + + start_rpkid = ${myrpki::run_rpkid} + + +## 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. + + + + start_irdbd = ${myrpki::run_rpkid} + + +## 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. + + + + start_pubd = ${myrpki::run_pubd} + + +## 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. + + + + start_rootd = ${myrpki::run_rootd} + + +## 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. + + + + shared_sql_username = rpki + + +## 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 + +SQL database name for rpkid's database. The default setting of this variable +should be fine. + + + + rpkid_sql_database = rpkid + + +## rpkid_sql_username + +If you want to use a separate SQL username for rpkid's database, set it here. + + + + rpkid_sql_username = ${myrpki::shared_sql_username} + + +## rpkid_sql_password + +If you want to use a separate SQL password for rpkid's database, set it here. + + + + rpkid_sql_password = ${myrpki::shared_sql_password} + + +## irdbd_sql_database + +SQL database for irdbd's database. The default setting of this variable should +be fine. + + + + irdbd_sql_database = irdbd + + +## irdbd_sql_username + +If you want to use a separate SQL username for irdbd's database, set it here. + + + + irdbd_sql_username = ${myrpki::shared_sql_username} + + +## irdbd_sql_password + +If you want to use a separate SQL password for irdbd's database, set it here. + + + + irdbd_sql_password = ${myrpki::shared_sql_password} + + +## pubd_sql_database + +SQL database name for pubd's database. The default setting of this variable +should be fine. + + + + pubd_sql_database = pubd + + +## pubd_sql_username + +If you want to use a separate SQL username for pubd's database, set it here. + + + + pubd_sql_username = ${myrpki::shared_sql_username} + + +## pubd_sql_password + +If you want to use a separate SQL password for pubd's database, set it here. + + + + pubd_sql_password = ${myrpki::shared_sql_password} + + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fpubd.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fpubd.md new file mode 100644 index 00000000..14561311 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fpubd.md @@ -0,0 +1,107 @@ +# [pubd] section + +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 + +MySQL database name for pubd. + + + + sql-database = ${myrpki::pubd_sql_database} + + +## sql-username + +MySQL user name for pubd. + + + + sql-username = ${myrpki::pubd_sql_username} + + +## sql-password + +MySQL password for pubd. + + + + sql-password = ${myrpki::pubd_sql_password} + + +## 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. + + + + publication-base = ${myrpki::publication_base_directory} + + +## server-host + +Host on which pubd should listen for HTTP service requests. + + + + server-host = ${myrpki::pubd_server_host} + + +## server-port + +Port on which pubd should listen for HTTP service requests. + + + + server-port = ${myrpki::pubd_server_port} + + +## 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. + + + + bpki-ta = ${myrpki::bpki_servers_directory}/ca.cer + + +## pubd-cert + +Where pubd should look for its own BPKI EE certificate. Don't change this +unless you really know what you are doing. + + + + pubd-cert = ${myrpki::bpki_servers_directory}/pubd.cer + + +## 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. + + + + pubd-key = ${myrpki::bpki_servers_directory}/pubd.key + + +## 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. + + + + irbe-cert = ${myrpki::bpki_servers_directory}/irbe.cer + + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frootd.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frootd.md new file mode 100644 index 00000000..ffd00010 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frootd.md @@ -0,0 +1,203 @@ +# [rootd] section + +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 + +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. + + + + bpki-ta = ${myrpki::bpki_servers_directory}/ca.cer + + +## rootd-bpki-crl + +BPKI CRL. Don't change this unless you really know what you are doing. + + + + rootd-bpki-crl = ${myrpki::bpki_servers_directory}/ca.crl + + +## rootd-bpki-cert + +rootd's own BPKI EE certificate. Don't change this unless you really know what +you are doing. + + + + rootd-bpki-cert = ${myrpki::bpki_servers_directory}/rootd.cer + + +## 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. + + + + rootd-bpki-key = ${myrpki::bpki_servers_directory}/rootd.key + + +## 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. + + + + child-bpki-cert = ${myrpki::bpki_servers_directory}/child.cer + + +## server-host + +Server host on which rootd should listen. + + + + server-host = ${myrpki::rootd_server_host} + + +## server-port + +Server port on which rootd should listen. + + + + server-port = ${myrpki::rootd_server_port} + + +## 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. + + + + rpki-root-dir = ${myrpki::publication_base_directory} + + +## rpki-base-uri + +rsync URI corresponding to directory containing rootd's outputs. + + + + rpki-base-uri = rsync://${myrpki::publication_rsync_server}/${myrpki::publication_rsync_module}/ + + +## rpki-root-cert-uri + +rsync URI for rootd's root (self-signed) RPKI certificate. + + + + rpki-root-cert-uri = rsync://${myrpki::publication_rsync_server}/${myrpki::publication_root_module}/root.cer + + +## rpki-root-key + +Private key corresponding to rootd's root RPKI certificate. + + + + rpki-root-key = ${myrpki::bpki_servers_directory}/root.key + + +## rpki-root-cert + +Filename (as opposed to rsync URI) of rootd's root RPKI certificate. + + + + rpki-root-cert = ${myrpki::publication_root_cert_directory}/root.cer + + +## rpki-subject-pkcs10 + +Where rootd should stash a copy of the PKCS [#10][1] request it gets from its +one (and only) child + + + + rpki-subject-pkcs10 = ${myrpki::bpki_servers_directory}/rootd.subject.pkcs10 + + +## rpki-subject-lifetime + +Lifetime of the one and only RPKI certificate rootd issues. + + + + rpki-subject-lifetime = 30d + + +## rpki-root-crl + +Filename (relative to rootd-base-uri and rpki-root-dir) of the CRL for rootd's +root RPKI certificate. + + + + rpki-root-crl = root.crl + + +## rpki-root-manifest + +Filename (relative to rootd-base-uri and rpki-root-dir) of the manifest for +rootd's root RPKI certificate. + + + + rpki-root-manifest = root.mft + + +## rpki-class-name + +Up-down protocol class name for RPKI certificate rootd issues to its one (and +only) child. + + + + rpki-class-name = ${myrpki::handle} + + +## rpki-subject-cert + +Filename (relative to rootd-base-uri and rpki-root-dir) of the one (and only) +RPKI certificate rootd issues. + + + + rpki-subject-cert = ${myrpki::handle}.cer + + + [1]: /ticket/10 (enhancement: Things Keyur wanted when he saw rcynic-ng's +HTML (closed: fixed)) + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frpkid.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frpkid.md new file mode 100644 index 00000000..774196c7 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Frpkid.md @@ -0,0 +1,114 @@ +# [rpkid] section + +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 + +MySQL database name for rpkid. + + + + sql-database = ${myrpki::rpkid_sql_database} + + +## sql-username + +MySQL user name for rpkid. + + + + sql-username = ${myrpki::rpkid_sql_username} + + +## sql-password + +MySQL password for rpkid. + + + + sql-password = ${myrpki::rpkid_sql_password} + + +## server-host + +Host on which rpkid should listen for HTTP service requests. + + + + server-host = ${myrpki::rpkid_server_host} + + +## server-port + +Port on which rpkid should listen for HTTP service requests. + + + + server-port = ${myrpki::rpkid_server_port} + + +## 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. + + + + irdb-url = http://${myrpki::irdbd_server_host}:${myrpki::irdbd_server_port}/ + + +## 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. + + + + bpki-ta = ${myrpki::bpki_servers_directory}/ca.cer + + +## rpkid-cert + +Where rpkid should look for its own BPKI EE certificate. Don't change this +unless you really know what you are doing. + + + + rpkid-cert = ${myrpki::bpki_servers_directory}/rpkid.cer + + +## 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. + + + + rpkid-key = ${myrpki::bpki_servers_directory}/rpkid.key + + +## irdb-cert + +Where rpkid should look for irdbd's BPKI EE certificate. Don't change this +unless you really know what you are doing. + + + + irdb-cert = ${myrpki::bpki_servers_directory}/irdbd.cer + + +## 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. + + + + irbe-cert = ${myrpki::bpki_servers_directory}/irbe.cer + + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fweb_portal.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fweb_portal.md new file mode 100644 index 00000000..5ff1f0d6 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration%2Fweb_portal.md @@ -0,0 +1,60 @@ +# [web_portal] section + +Glue to allow the Django application to pull user configuration from this file +rather than directly editing settings.py. + +## sql-database + +SQL database name the web portal should use. + + + + sql-database = ${myrpki::irdbd_sql_database} + + +## sql-username + +SQL user name the web portal should use. + + + + sql-username = ${myrpki::irdbd_sql_username} + + +## sql-password + +SQL password the web portal should use. + + + + sql-password = ${myrpki::irdbd_sql_password} + + +## secret-key + +Site-specific secret key for Django. + +No default value. + +## 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 + +A directory large enough to hold the RouteViews?.org routing table dump +fetched by the rpkigui-import-routes script. + + + + download-directory = /var/tmp + + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration.md new file mode 100644 index 00000000..eafa2755 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration.md @@ -0,0 +1,229 @@ +# 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`. + + * All of the configuration options you're most likely to need to change are in the `[myrpki]` section of `rpki.conf`. + + + [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. + + + 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. + + + run_pubd = yes + + +> or + + + + 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. + + + 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 [next steps][1]. + +## Configuration file 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. + + + + [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 + + + + 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. + + + + 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 [described above][2]. + +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. + + * [ Common Options ][3] + * [ [myrpki] section ][4] + * [ [rpkid] section ][5] + * [ [irdbd] section ][6] + * [ [pubd] section ][7] + * [ [rootd] section ][8] + * [ [web_portal] section ][9] + * [ [autoconf] section ][10] + +## 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: + + + + 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 [ the +documentation for the [rootd] section ][8], and [ the instructions for +creating a RPKI root certificate ][11]. + +## 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 [these instructions][12]. + +## 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 [these +instructions][13]. + +## Next steps + +Once you've finished with configuration, the next thing you should read is the +[MySQL setup instructions][14]. + + [1]: #_.wiki.doc.RPKI.CA.Configuration#nextsteps + + [2]: #_.wiki.doc.RPKI.CA.Configuration#syntax + + [3]: #_.wiki.doc.RPKI.CA.Configuration.Common + + [4]: #_.wiki.doc.RPKI.CA.Configuration.myrpki + + [5]: #_.wiki.doc.RPKI.CA.Configuration.rpkid + + [6]: #_.wiki.doc.RPKI.CA.Configuration.irdbd + + [7]: #_.wiki.doc.RPKI.CA.Configuration.pubd + + [8]: #_.wiki.doc.RPKI.CA.Configuration.rootd + + [9]: #_.wiki.doc.RPKI.CA.Configuration.web_portal + + [10]: #_.wiki.doc.RPKI.CA.Configuration.autoconf + + [11]: #_.wiki.doc.RPKI.CA.Configuration.CreatingRoot + + [12]: #_.wiki.doc.RPKI.CA.Configuration.DifferentServer + + [13]: #_.wiki.doc.RPKI.CA.Configuration.Tests + + [14]: #_.wiki.doc.RPKI.CA.MySQLSetup + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FMySQLSetup.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FMySQLSetup.md new file mode 100644 index 00000000..669cf3ab --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FMySQLSetup.md @@ -0,0 +1,77 @@ +# RPKI Engine MySQL Setup + +You need to install MySQL and set up the relevant databases before starting +rpkid, irdbd, or pubd. + +See the [Installation Guide][1] for details on where to download MySQL and +find documentation on installing it. + +See the [Configuration Guide][2] 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: + + + + $ 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: + + + + $ 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: + + + + $ 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 [user interface tools][3]. + + [1]: #_.wiki.doc.RPKI.Installation + + [2]: #_.wiki.doc.RPKI.CA.Configuration + + [3]: #_.wiki.doc.RPKI.CA.UI + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FOOBSetup.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FOOBSetup.md new file mode 100644 index 00000000..d3246292 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FOOBSetup.md @@ -0,0 +1,5 @@ +# RPKI CA Out-Of-Band Setup Protocol + +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.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FLeftRight.md new file mode 100644 index 00000000..68779905 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FLeftRight.md @@ -0,0 +1,490 @@ +# The Left-Right Protocol + +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 `` 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 `` object, representing the engine operator's +organization, but in environments where the engine operator hosts other +entities, there will be one `` 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 `` object. Data which +are shared by all hosted entities are referred to as "per-engine" data, data +which are specific to a particular `` object are "per-self" data. + +Since all other RPKI engine objects refer to a `` object via a +"self_handle" value, one must create a `` object before one can +usefully configure any other left-right protocol objects. + +Every `` 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 `` 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 +``, 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 ``. 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 ``, +``, and `` 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 ``, 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 `` +object associated with this `` 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 `` object associated with this `` 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 `` +object that would ordinarily be performed under cron. Not currently +implemented. + +publish_world_now:: + +> Force (re)publication of every publishable object for this `` object. +Not currently implemented. Intended to aid in recovery if RPKI engine and +publication engine somehow get out of sync. + +### <bsc/> object + +The `` ("business signing context") object represents all the BPKI data +needed to sign outgoing CMS messages. Various other objects include pointers +to a `` object. Whether a particular `` uses only one `` 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 `` object that +it can use to produce that signature. + +Every `` object has a bsc_handle, which must be specified for the +"create", "get", "set", and "destroy" actions. Every `` also has a +self_handle attribute which indicates the `` object with which this +`` object is associated. + +Payload data which can be configured in a `` 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 `` +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 +`` 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 `` object represents the RPKI engine's view of a particular +parent of the current `` object in the up-down protocol. Due to the way +that the resource hierarchy works, a given `` 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 `` object has a parent_handle, which must be specified for the +"create", "get", "set", and "destroy" actions. Every `` also has a +self_handle attribute which indicates the `` object with which this +`` object is associated, a bsc_handle attribute indicating the +`` object to be used when signing messages sent to this parent, and a +repository_handle indicating the `` object to be used when +publishing issued by the certificate issued by this parent. + +Payload data which can be configured in a `` 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 ``. 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 `` object. + +bpki_cms_glue:: (element) + +> Another BPKI CMS CA certificate for this ``, 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 `` 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 `` object, but limited to RPKI +CAs under this parent. + +reissue:: + +> This is like the reissue command in the `` object, but limited to +RPKI CAs under this parent. + +revoke:: + +> This is like the revoke command in the `` object, but limited to RPKI +CAs under this parent. + +### <child/> object + +The `` object represents the RPKI engine's view of particular child of +the current `` in the up-down protocol. + +Every `` object has a child_handle, which must be specified for the +"create", "get", "set", and "destroy" actions. Every `` also has a +self_handle attribute which indicates the `` object with which this +`` object is associated. + +Payload data which can be configured in a `` object: + +bpki_cert:: (element) + +> BPKI CA certificate for this ``. 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 `` object. + +bpki_glue:: (element) + +> Another BPKI CA certificate for this ``, 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 `` 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 `` object represents the RPKI engine's view of a particular +publication repository used by the current `` object. + +Every `` object has a repository_handle, which must be specified +for the "create", "get", "set", and "destroy" actions. Every `` +also has a self_handle attribute which indicates the `` object with +which this `` object is associated. + +Payload data which can be configured in a `` object: + +peer_contact_uri:: (attribute) + +> HTTP URI used to contact this repository. + +bpki_cms_cert:: (element) + +> BPKI CMS CA certificate for this ``. 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 +`` object. + +bpki_cms_glue:: (element) + +> Another BPKI CMS CA certificate for this ``, 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 `` object; if not needed, +the bpki_cms_glue certificate should be left unset. + +At present there are no control attributes for `` objects. + +### <route_origin/> object + +This section is out-of-date. The `` object has been replaced by +the `` IRDB query, but the documentation for that hasn't +been written yet. + +The `` 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 `` object represents a ROA to be generated on +behalf of ``, not on behalf of a ``. Thus, a hosted entity that +has no children but which does need to generate ROAs would be represented by a +hosted `` with no `` objects but one or more `` +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 `` 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 `` 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 `` 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: + + + + ::=
"/" [ "-" ] + ; Where defaults to the same + ; value as . + + ::= *( "," ) + + +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 `` 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 `` 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 `` 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 `` object, but the semantics differ: note in particular +that `` objects don't allow ranges, while `` +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 `` message which takes +the place of the expected protocol response message. `` +messages are CMS-signed XML messages like the rest of this protocol, and thus +can be archived to provide an audit trail. + +`` messages only appear in replies, never in queries. The +`` message can appear on either the "forward" (IRBE as client +of RPKI engine) or "back" (RPKI engine as client of IRDB) communication +channel. + +The `` 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 `` 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 `` 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.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FPublication.md new file mode 100644 index 00000000..1bf3bf55 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FPublication.md @@ -0,0 +1,200 @@ +# The Publication Protocol + +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 +[left-right protocol][1]: 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 `` +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. + + [1]: #_.wiki.doc.RPKI.CA.Protocols.LeftRight + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Fpubd.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Fpubd.md new file mode 100644 index 00000000..bbfb0e01 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Fpubd.md @@ -0,0 +1,11 @@ +# pubd SQL Schema + +pubd.sql + +[![No image "pubd.png" attached to doc/RPKI/CA/SQLSchemas/pubd][1]][2] + + [1]: /chrome/common/attachment.png (No image "pubd.png" attached to +doc/RPKI/CA/SQLSchemas/pubd) + + [2]: /attachment/wiki/doc/RPKI/CA/SQLSchemas/pubd/pubd.png + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Frpkid.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Frpkid.md new file mode 100644 index 00000000..70143184 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas%2Frpkid.md @@ -0,0 +1,11 @@ +# rpkid SQL schema + +rpkid.sql + +[![No image "rpkid.png" attached to doc/RPKI/CA/SQLSchemas/rpkid][1]][2] + + [1]: /chrome/common/attachment.png (No image "rpkid.png" attached to +doc/RPKI/CA/SQLSchemas/rpkid) + + [2]: /attachment/wiki/doc/RPKI/CA/SQLSchemas/rpkid/rpkid.png + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas.md new file mode 100644 index 00000000..6f4a34c3 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FSQLSchemas.md @@ -0,0 +1,9 @@ +# RPKI Engine SQL Database Schemas + + * [rpkid database schema][1] + * [pubd database schema][2] + + [1]: #_.wiki.doc.RPKI.CA.SQLSchemas.rpkid + + [2]: #_.wiki.doc.RPKI.CA.SQLSchemas.pubd + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring%2FApache.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring%2FApache.md new file mode 100644 index 00000000..ba433654 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring%2FApache.md @@ -0,0 +1,108 @@ +# 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**: + + + + 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 `` section: + + + + Include /usr/local/etc/rpki/apache.conf + + +Now restart `apache`: + + + + service apache2 restart + + +## FreeBSD + +Now configure apache, using `/usr/local/etc/rpki/apache.conf`, e.g. + + + + $ cp apache.conf /usr/local/etc/apache22/Includes/rpki.conf + + +Restart apache + + + + $ 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. + + + + $ ./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 for more information. + +## Verify the Web Portal is Working + +Navigate to and you should see the login page for the +web portal. + +Enter the superuser and password in login form (see +[doc/RPKI/CA/UI/GUI/UserModel][1] 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. + + [1]: #_.wiki.doc.RPKI.CA.UI.GUI.UserModel + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring.md new file mode 100644 index 00000000..c5c453d9 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FConfiguring.md @@ -0,0 +1,108 @@ +# Configuring the Web Portal + +Also see [doc/RPKI/CA/Configuration][1] for documentation on the +`/etc/rpki.conf` configuration file. + +## Creating Users + +See [doc/RPKI/CA/UI/GUI/UserModel][2] + +## Configuring Apache + +In order to use the web portal, Apache must be installed and configured to +serve the application. See [doc/RPKI/CA/UI/GUI/Configuring/Apache][3]. + +## 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 [RouteViews][4] [full snapshot][5] (**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 [instructions for setting up rcynic][6]. + +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 + +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: + + + + /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. + + [1]: #_.wiki.doc.RPKI.CA.Configuration + + [2]: #_.wiki.doc.RPKI.CA.UI.GUI.UserModel + + [3]: #_.wiki.doc.RPKI.CA.UI.GUI.Configuring.Apache + + [4]: http://www.routeviews.org + + [5]: http://archive.routeviews.org/oix-route-views/oix-full-snapshot- +latest.dat.bz2 + + [6]: #_.wiki.doc.RPKI.RP.rcynic + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FInstalling.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FInstalling.md new file mode 100644 index 00000000..c74f4f38 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FInstalling.md @@ -0,0 +1,51 @@ +# 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 [doc/RPKI/CA/UI/GUI/Upgrading][1] for +instructions. + +## Prerequisites + +This page assumes that you have already followed the steps to install the CA +software (see [doc/RPKI/Installation][2]) + +This page assumes that you have already created `/etc/rpki.conf` (see +[doc/RPKI/CA/Configuration][3]) + +## 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`): + + + + 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 [doc/RPKI/CA/UI/GUI/Configuring][4] + + [1]: #_.wiki.doc.RPKI.CA.UI.GUI.Upgrading + + [2]: #_.wiki.doc.RPKI.Installation + + [3]: #_.wiki.doc.RPKI.CA.Configuration + + [4]: #_.wiki.doc.RPKI.CA.UI.GUI.Configuring + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading%2FBeforeMigration.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading%2FBeforeMigration.md new file mode 100644 index 00000000..a1aa9bc4 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading%2FBeforeMigration.md @@ -0,0 +1,97 @@ +# 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 [doc/RPKI/CA/UI/GUI/Upgrading][1] 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: + + + + $ 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. + + + + $ 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: + + + + $ 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: + + + + $ rpki-manage migrate + + +From this point forward you will follow the steps in +[doc/RPKI/CA/UI/GUI/Upgrading][1] each time you upgrade. + +## Restart Apache + +In order to make Apache use the new version of the software, it must be +restarted: + + + + $ apachectl restart + + + [1]: #_.wiki.doc.RPKI.CA.UI.GUI.Upgrading + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading.md new file mode 100644 index 00000000..fb47c102 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUpgrading.md @@ -0,0 +1,52 @@ +# Upgrading from a Previous Version + + * See [wiki:doc/RPKI/CA/UI/GUI/Upgrading/BeforeMigration][1] 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 [doc/RPKI/CA/UI/GUI/Installing][2]. + +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. + + + + 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: + + + + apachectl restart + + +## Next Step + +See [doc/RPKI/CA/UI/GUI/Configuring][3] + + [1]: #_.wiki.doc.RPKI.CA.UI.GUI.Upgrading.BeforeMigration + + [2]: #_.wiki.doc.RPKI.CA.UI.GUI.Installing + + [3]: #_.wiki.doc.RPKI.CA.UI.GUI.Configuring + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUserModel.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUserModel.md new file mode 100644 index 00000000..008437b9 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI%2FUserModel.md @@ -0,0 +1,156 @@ +# 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 +holders][1] 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: + + + + $ rpki-manage changepassword + + +#### 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: + + + + $ rpki-manage createsuperuser + + +#### Creating user accounts + +When logged into the web portal with a [#superuser][2] 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 +holders][1] that this user is granted authorization to manage. + +Note that creating a user does **not** create a matching [#resource- +holder][1]. See [creating resource holders][3]. + +#### Destroying user accounts + +When logged into the web portal with a [#superuser][2] 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 holders][1] the +user is granted authorization to manage. + +### Resource Holders + +Resource holders are entities that have authority to manage a set of Internet +number resources. When a [user][4] 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][2] 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 + +Note that creating a new resource holder does **not** create a [user][4] +account. See [#create-user][5]. + +##### GUI + +When logged into the web portal with a [#superuser][2] 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][4] 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: + + + + $ rpkic -i 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][2] accounts. You may wish to [create a matching user account][5], +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 [user][4] +accounts. + +##### GUI + +When logged into the web portal with a [#superuser][2] 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: + + + + $ rpkic -i delete_self + $ rpkic synchronize + + +where _HANDLE_ is the name of the resource holder you wish to destroy. + +#### Modifying the User ACL + +Each [resource holder][6] may be managed by one or more [user][4] 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][2] 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. + + [1]: #_.wiki.doc.RPKI.CA.UI.GUI.UserModel#resource-holder + + [2]: #_.wiki.doc.RPKI.CA.UI.GUI.UserModel#superuser + + [3]: #_.wiki.doc.RPKI.CA.UI.GUI.UserModel#create-holder + + [4]: #_.wiki.doc.RPKI.CA.UI.GUI.UserModel#users + + [5]: #_.wiki.doc.RPKI.CA.UI.GUI.UserModel#create-user + + [6]: #_.wiki.doc.RPKI.CA.UI.GUI.UserModel#resourceholders + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI.md new file mode 100644 index 00000000..1b4d9ded --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2FGUI.md @@ -0,0 +1,91 @@ +# Installing and Configuring + + * [GUI/Installing][1] for new installs + * [GUI/Upgrading][2] for upgrading from a previous install + * [GUI/Configuring][3] + * [GUI/UserModel][4] for instructions on managing users + + + + +# Using the GUI + +# GUI Examples + + + +## Logging in to the GUI + +[![01-login.jpg][5]][6] + + +## The Dashboard - Let's Make a ROA + +[![02-dashboard.jpg][7]][8] + + +## ROA List Currently Empty, So Let's Create One + +[![03-roas.jpg][9]][10] + + +## Choose an AS and Prefix - Let MaxLen? Default + +[![04-create-roa.jpg][11]][12] + + +## What Will the Consequences Be? - Confirm OK + +[![05-are-you-sure.jpg][13]][14] + + +## Now We Can See ROAs - Let's Look at Routes + +> [![06-roa-list.jpg][15]][16] + + + + +## Real Effect on Routing Table + +[![07-route view.jpg][17]][18] + + +## Ghostbusters etc. are Similar + + [1]: #_.wiki.doc.RPKI.CA.UI.GUI.Installing + + [2]: #_.wiki.doc.RPKI.CA.UI.GUI.Upgrading + + [3]: #_.wiki.doc.RPKI.CA.UI.GUI.Configuring + + [4]: #_.wiki.doc.RPKI.CA.UI.GUI.UserModel + + [5]: /chrome/site/gui-pics/01-login.jpg (01-login.jpg) + + [6]: /chrome/site/gui-pics/01-login.jpg + + [7]: /chrome/site/gui-pics/02-dashboard.jpg (02-dashboard.jpg) + + [8]: /chrome/site/gui-pics/02-dashboard.jpg + + [9]: /chrome/site/gui-pics/03-roas.jpg (03-roas.jpg) + + [10]: /chrome/site/gui-pics/03-roas.jpg + + [11]: /chrome/site/gui-pics/04-create-roa.jpg (04-create-roa.jpg) + + [12]: /chrome/site/gui-pics/04-create-roa.jpg + + [13]: /chrome/site/gui-pics/05-are-you-sure.jpg (05-are-you-sure.jpg) + + [14]: /chrome/site/gui-pics/05-are-you-sure.jpg + + [15]: /chrome/site/gui-pics/06-roa-list.jpg (06-roa-list.jpg) + + [16]: /chrome/site/gui-pics/06-roa-list.jpg + + [17]: /chrome/site/gui-pics/07-route%20view.jpg (07-route view.jpg) + + [18]: /chrome/site/gui-pics/07-route%20view.jpg + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2Frpkic.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2Frpkic.md new file mode 100644 index 00000000..cda37bc3 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI%2Frpkic.md @@ -0,0 +1,89 @@ +# The rpkic tool + +rpkic is a command line interface to rpkid and pubd. It implements largely the +same functionality as the [web interface][1]. 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 [rpki.conf][2] 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][3] 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). + + [1]: #_.wiki.doc.RPKI.CA.UI.GUI + + [2]: #_.wiki.doc.RPKI.CA.Configuration + + [3]: #_.wiki.doc.RPKI.CA.UI + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI.md b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI.md new file mode 100644 index 00000000..ce2c6cad --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FUI.md @@ -0,0 +1,117 @@ +# The CA user interface tools + +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][1] is a command line interface to the the IRBE. The [web interface][2] +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 + +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, [install the software][3], create the [rpki.conf][4] for your installation, and [set up the MySQL database][5]. + 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: + + + + $ rsync rsync://rpki.example.org/where/ever/ + + +If you need to examine RPKI objects in detail, you have a few options: + + * The [RPKI utilities][6] 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 [dumpasn1][7] program may be useful if you are desperate enough that you need to examine raw ASN.1 objects. + + [1]: #_.wiki.doc.RPKI.CA.UI.rpkic + + [2]: #_.wiki.doc.RPKI.CA.UI.GUI + + [3]: #_.wiki.doc.RPKI.Installation + + [4]: #_.wiki.doc.RPKI.CA.Configuration + + [5]: #_.wiki.doc.RPKI.CA.MySQLSetup + + [6]: #_.wiki.doc.RPKI.Utils + + [7]: http://www.cs.auckland.ac.nz/~pgut001/dumpasn1.c + diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA.md b/doc/wiki-dump/doc%2FRPKI%2FCA.md new file mode 100644 index 00000000..85c3431a --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA.md @@ -0,0 +1,254 @@ +# RPKI CA Engine + +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 [relying party tools][1] 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 instructions][2]; if you're using pre-built packages you may be able to skip this step. + 2. Then read the [configuration instructions][3] + 3. Then the [MySQL setup instructions][4] + 4. And finally either the [command line tool][5] or [web interface][6] + +## 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 instructions][2] 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 guide][3] for +details. + +Basic operation consists of creating the appropriate MySQL databases (see +[MySQL setup][4]), starting the daemons, and using [rpkic][5] or [the web +interface][6] 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 guide][3] 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: + + + + 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 [Common Options][7] 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 [left-right protocol][8], followed by dynamic configuration via the +left-right protocol. The latter stage is handled by the [command line tool][5] +or the [web interface][6]. + +rpkid stores dynamic data in an SQL database, which must have been created for +it, as explained in in the [MySQL setup instructions][4]. + +### 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 [MySQL setup instructions][4]. 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 guide][3] 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 guide][3] 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 guide][3] 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 + 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 [test configuration language][9] for details on the content of these +YAML files. + +### 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. + + [1]: #_.wiki.doc.RPKI.RP + + [2]: #_.wiki.doc.RPKI.Installation + + [3]: #_.wiki.doc.RPKI.CA.Configuration + + [4]: #_.wiki.doc.RPKI.CA.MySQLSetup + + [5]: #_.wiki.doc.RPKI.CA.UI.rpkic + + [6]: #_.wiki.doc.RPKI.CA.UI.GUI + + [7]: #_.wiki.doc.RPKI.CA.Configuration.Common + + [8]: #_.wiki.doc.RPKI.CA.Protocols.LeftRight + + [9]: #_.wiki.doc.RPKI.CA.Configuration.Tests + diff --git a/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FDebianPackages.md b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FDebianPackages.md new file mode 100644 index 00000000..17f6be86 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FDebianPackages.md @@ -0,0 +1,81 @@ +# 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): + + 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): + + 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): + + 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): + + 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: + + sudo apt-get update + + + * Install the software: + + 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 [obsessively detailed instructions][1]. + + 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: + + 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: + + + + sudo apt-get update + sudo apt-get upgrade + + +Or, if you only want to update the RPKI tools: + + + + sudo apt-get update + sudo apt-get upgrade rpki-ca rpki-rp + + + [1]: #_.wiki.doc.RPKI.CA.Configuration + diff --git a/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFreeBSDPorts.md b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFreeBSDPorts.md new file mode 100644 index 00000000..457f545e --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFreeBSDPorts.md @@ -0,0 +1,123 @@ +# Installation Using FreeBSD Ports + +Port skeletons are available for FreeBSD from download.rpki.net. To use these, +you need to download the port skeletons then run them using your favorite +FreeBSD port installation tool. + +## Manual Download + +To download the port skeletons manually and install from them, do something +like this: + + + + for port in rpki-rp rpki-ca + do + fetch 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 [obsessively detailed +instructions][1]. + + + + emacs /usr/local/etc/rpki.conf + + +Again, you want to change `handle` and `rpkid_server_host` at the minimum. + +To upgrade, you can perform almost the same steps, but the FreeBSD ports +system, which doesn't really know about upgrades, will require you to use the +`deinstall` and `reinstall` operations instead of plain `install`: + + + + for port in rpki-rp rpki-ca + do + fetch 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 [script][2] you can use to automate the download steps above and +perform the updates using portmaster. First, download the script: + + + + fetch https://download.rpki.net/FreeBSD_Packages/rpki-portmaster.sh + + +Then, to install or upgrade, just execute the script: + + + + sh rpki-portmaster.sh + + +As with manual download (above) you should customize `rpki.conf` after initial +installation. + +## Automated Download and Install with portupgrade + +There's a [script][3] you can use to automate the download steps above and +perform the updates using portupgrade. First, download the script: + + + + 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: + + + + EXTRA_CATEGORIES = [ + 'rpki', + ] + + ALT_INDEX = [ + ENV['PORTSDIR'] + '/INDEX.rpki', + ] + + +Once you have completed these steps, you can just execute the script to +install or upgrade the RPKI code: + + + + sh rpki-portupgrade.sh + + +As with manual download (above) you should customize `rpki.conf` after initial +installation. + + [1]: #_.wiki.doc.RPKI.CA.Configuration + + [2]: https://download.rpki.net/FreeBSD_Packages/rpki-portmaster.sh + + [3]: https://download.rpki.net/FreeBSD_Packages/rpki-portupgrade.sh + diff --git a/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFromSource.md b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFromSource.md new file mode 100644 index 00000000..f64216be --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FInstallation%2FFromSource.md @@ -0,0 +1,239 @@ +# Installing From Source Code + +At present, the entire RPKI tools collection is a single source tree with a +shared autoconf configuration. This may change in the future, but for now, +this means that the build process is essentially the same regardless of which +tools one wants to use. Some of the tools have dependencies on external +packages, although we've tried to keep this to a minimum. + +Most of the tools require an [RFC-3779][1]-aware version of the [OpenSSL][2] +libraries. If necessary, the build process will generate its own private copy +of the OpenSSL libraries for this purpose. + +Other than OpenSSL, most of the relying party tools are fairly self-contained. +The CA tools have a few additional dependencies, described below. + +Note that initial development of this code has been on FreeBSD, so +installation will probably be easiest on FreeBSD. We do, however, test on +other platforms, such as Fedora, Ubuntu, Debian, and MacOSX. + +## Downloading the Source Code + +The recommended way to obtain the source code is via [subversion][3]. To +download, do: + + + + $ svn checkout https://subvert-rpki.hactrn.net/trunk/ + + +Code snapshots are also available from 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. + * , 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 + + * , 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 + * , 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 + * , the Python "db" interface to MySQL. + * FreeBSD: /usr/ports/databases/py-MySQLdb (py27-MySQLdb) + * Fedora: MySQL-python.i386 + * Debian & Ubuntu: python-mysqldb + * , 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: + + + $ sudo pip install django==1.4.5 + + + * , 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: + + $ python -c 'import argparse' 2>/dev/null || sudo pip install argparse + + + * . 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 + * . Some of the test code uses xsltproc, from the Gnome LibXSLT package. + * FreeBSD: /usr/ports/textproc/libxslt (libxslt) + * Debian & Ubuntu: xsltproc + * . 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 + * 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 + * 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: + + + pip install South>=0.7.6 + + +## Configure and build + +Once you have the prerequesite packages installed, you should be able to build +the toolkit. cd to the top-level directory in the distribution, run the +configure script, then run "make": + + + + $ cd $top + $ ./configure + $ make + + +This should automatically build everything, in the right order, including +building a private copy of the OpenSSL libraries with the right options if +necessary and linking the POW module against either the system OpenSSL +libraries or the private OpenSSL libraries, as appopriate. + +In theory, `./configure` will complain about any required packages which might +be missing. + +If you don't intend to run any of the CA tools, you can simplify the build and +installation process by telling `./configure` that you only want to build the +relying party tools: + + + + $ cd $top + $ ./configure --disable-ca-tools + $ make + + +## Testing the build + +Assuming the build stage completed without obvious errors, the next step is to +run some basic regression tests. + +Some of the tests for the CA tools require MySQL databases to store their +data. To set up all the databases that the tests will need, run the SQL +commands in `ca/tests/smoketest.setup.sql`. The MySQL command line client is +usually the easiest way to do this, eg: + + + + $ cd $top/ca + $ mysql -u root -p