[389a55]: INSTRUCTIONS.in Maximize Restore History

Download this file

INSTRUCTIONS.in    810 lines (622 with data), 31.8 kB

@PACKAGE_LONGNAME@
Installation and Usage Manual
Version @PACKAGE_VERSION@

===============================================================================
Table of Contents

1. Organization of this document
2. Installation
    2.1 Prerequisites
      2.1.1 User Account
      2.1.2 OpenSSL
      2.1.3 MySQL and ODBC
      2.1.4 cryptlib
      2.1.5 rsync
      2.1.6 Python
      2.1.7 netcat
    2.2 RPKI Software
      2.2.1 Unpack the Source Code
      2.2.2 Configure
      2.2.3 Build the Executables
    2.3 RPKI User Account
      2.3.1 Environment Variables
    2.4 SSH Subsystem
    2.5 Self Test
    2.6 Post-Installation Procedures
      2.6.1 Cron Job Configuration
      2.6.2 Adjust Permissions
3. Running the RPKI Software
    3.1 Walkthrough
      3.1.1 Add rsync uris to configuration file.
      3.1.2 Clear database and local repository cache.
      3.1.3 Invoke DB Updater (rcli) in listening mode.
      3.1.4 Automatically download Trust Anchors using TAL files.
      3.1.5 Manually insert trust anchors (optional).
      3.1.6 Run URI Chaser.
      3.1.7 Run Garbage Collector.
    3.2 Results and Analysis
      3.2.1 Validation Report (results.py)
      3.2.2 Query Client
    3.3 Warning
Appendix A. Troubleshooting
    A.1 Database troubleshooting
    A.2 64-bit support
    A.3 Specific Operating Systems
      A.3.1 OpenBSD
      A.3.2 FreeBSD

===============================================================================

1. Organization of this document

This document describes how to install and use the Relying Party Security
Technology for Internet Routing (RPSTIR, pronounced rip-ster) software
by Raytheon BBN Technologies.  Please refer to the design document,
rpkidesign.doc, for a detailed description of the various software
components in this release. Note that various files may refer to this
software by its old name, RPKI.

Section 2 describes how to install that software, including its dependencies.

Section 3 provides a quick-start guide on how to get your system running.

Appendix A provides troubleshooting tips for some common problems.

===============================================================================

2. Installation

The RPKI software is distributed as source code that should be built
using the GNU build tools on Linux/Unix.  After reading this section,
you will know:
    . How to install and configure the prerequisites.
    . How to build the RPKI software.
    . How to set up a user with the correct environment.
    . How to validate the installation.
We assume that you can operate your system's package manager, as well
as build packages from source and do minor edits on Makefiles.

If you are running a 64-bit operating system or have python installed
somewhere other than /usr/bin/python, see Appendix A at the bottom of
this file before continuing.


2.1 Prerequisites

When installing prerequisites from your operating system's package
manager, you may need to look for a -dev or -devel version of each
package. These versions generally contain header files that are needed
to build rpstir.

2.1.1 User Account

You must establish a user account from which you can build and run the
RPKI software.  While the full environment setup is detailed in
section 2.3, the basic user should be created now so that you
can set and test environment variables.

2.1.2 OpenSSL

You must build OpenSSL from source in order to enable support for
RFC3779 X.509v3 extensions.  Download the latest source code (at least
version 1.0.0i) from http://www.openssl.org.  We recommend the default
installation target directory /usr/local/ssl.  As of version 1.0.0i,
the steps were:

	$ ./config enable-rfc3779
	$ make depend
	$ make
	$ make test
	$ make install

In addition, the some scripts invoke the OpenSSL executable from the
shell.  Modify your user's PATH such that `which openssl` points to
the custom-compiled binary that supports RFC 3779 extensions.

2.1.3 MySQL and ODBC

Install unixODBC from your operating system's package manager or
http://www.unixodbc.org/.  iODBC is also supported, but unixodbc is
recommended.  Install the MySQL database server, at least version 5.1,
from the package manager or http://mysql.org.  Install the MySQL
Connector/ODBC driver, at least version 3.51, from the package manager
or mysql.org.

Configure MySQL.  First, secure the initial MySQL accounts, which
includes setting a root password (see MySQL 5.1 manual, section
2.13.2).  Then set up a database user for RPKI.  For example, the
following creates a root password, then sets up a user with username
"rpki", password "bbn", and access to the database named "rpkidb7":

    shell> mysql -u root
    mysql> SELECT Host, User FROM mysql.user;  /* view all accounts */
    mysql> SET PASSWORD FOR 'root'@'127.0.0.1' = PASSWORD('rootpass');
    mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('rootpass');
    mysql> SET PASSWORD FOR 'root'@'<myhostname>' = PASSWORD('rootpass');
    mysql> CREATE USER 'rpki'@'localhost' IDENTIFIED BY 'bbn';
    mysql> GRANT ALL PRIVILEGES ON rpkidb7.* TO 'rpki'@'localhost';

Configure the Connector/ODBC driver.  First, locate your system ODBC
drivers and data sources configuration files.  For example:

[achi@roa-pki:~/rpki]$ odbcinst -j
unixODBC 2.2.11
DRIVERS............: /usr/local/etc/odbcinst.ini
SYSTEM DATA SOURCES: /usr/local/etc/odbc.ini
USER DATA SOURCES..: /home/achi/.odbc.ini

Edit odbcinst.ini to use the appropriate driver depending on the
version of the MySQL Connector.  For example:

-----------------------------------------------------------------------------
;  Sample /usr/local/etc/odbcinst.ini

[myodbcConn]
Description             = MySQL odbc driver for Linux & Win32
Driver          = /usr/local/lib/libmyodbc3.so
Setup           = /usr/local/lib/libmyodbc3S.so
UsageCount              = 1

[ODBC]
TraceFile       = /tmp/sql-odbc.log
Trace           = Yes
ForceTrace      = Yes
-----------------------------------------------------------------------------

Then edit odbc.ini to set up a couple of system data sources.  This is
slightly confusing: the user, password, and database name are actually
ignored because they will be overridden by the RPKI software via
environment variables.  However, depending on whether your database
user has a password, in future steps below you will need to remember
to set your RPKI_DSN variable to choose the DSN that is expecting a
password (e.g. "myodbc3") or no password (e.g. "myodbc3-np").  Here is
an example of a working odbc.ini that corresponds to the odbcinst.ini
above:

-----------------------------------------------------------------------------
;
;  odbc.ini configuration for Connector/ODBC and Connector/ODBC 3.51 drivers
;  /usr/local/etc/odbc.ini
;

[ODBC Data Sources]
myodbc3     = {MyODBC 3.51 Driver DSN}
myodbc3-np  = {MyODBC 3.51 Driver DSN for users without password}

[myodbc3]
Driver       = myodbcConn
Description  = Connector/ODBC 3.51 Driver DSN
SERVER       = localhost
PORT         =
USER         = arbitraryuser
Password     = arbitrarypassword
Database     = arbitrarydbname
OPTION       = 3
SOCKET       =

[myodbc3-np]
Driver       = myodbcConn
Description  = Connector/ODBC 3.51 Driver DSN
SERVER       = localhost
PORT         =
USER         = arbitraryuser
; Password     = thisiscommentedout
Database     = arbitrarydbname
OPTION       = 3
SOCKET       =
-----------------------------------------------------------------------------

You may also choose to set up user-specific $HOME/.odbc.ini file if
you need special DSN settings per user.  However, this is not required
for successful operation of the RPKI software.

2.1.4 cryptlib

Install Peter Gutmann's cryptlib, currently available at
http://www.cs.auckland.ac.nz/~pgut001/cryptlib.  When compiling on *nix, it
may be necessary to unzip in text mode to ensure that line endings are
correct.  Ensure that both the library itself and its include files are in
accessible locations.  For example, it may be necessary to manually copy
libcl.so to /usr/local/lib and cryptlib.h to /usr/local/include.  To install
cryptlib 3.4.1 (for example):

$ wget --passive ftp://ftp.franken.de/pub/crypt/cryptlib/cl341.zip
$ mkdir cryptlib
$ cd cryptlib
$ unzip -a ../cl341.zip  # -a enables text-mode
$ make shared  # create libcl.so, not libcl.a
$ su
# install -o root -g root -m 755 libcl.so.3.4.1 /usr/local/lib
# ln -s libcl.so.3.4.1 /usr/local/lib/libcl.so
# install -o root -g root -m 644 cryptlib.h /usr/local/include

On FreeBSD, cryptlib can be obtained one of two ways: (1) using the package
system by issuing the command pkg_add -r cryptlib, or (2) using the ports
system by issuing the command make search name="cryptlib" from the
/usr/ports directory.

There seem to be some problems with compiling cryptlib on Linux machines.
You may need to modify some files to get it to build cleanly. Also note that
the self-test code (make testlib; ./testlib) fails on at least FreeBSD
and Linux. We do not currently think that this is cause for concern.

2.1.5 rsync

Your rsync should be at least version 2.6.9, as earlier versions do
not necessarily support the necessary flags.  Check your version with
rsync --version, and install from rsync.samba.org.  We recommend the
latest version due to security and bug fixes.

2.1.6 Python

Install python, at least version 2.6.  Python is likely available in
your operating system's package manager and is also available at
http://python.org/download/.

2.1.7 netcat

Netcat comes preinstalled with many operating systems. If you do not
already have the command nc, install netcat from your package manager
or http://netcat.sourceforge.net/.


2.2 RPKI Software

The RPKI software is distributed as source code that should be built
using the GNU build tools on Linux/Unix.

2.2.1 Unpack the Source Code

The RPKI software will have been delivered to you as a gzip-ed tarball
named @PACKAGE_TARNAME@-@PACKAGE_VERSION@.tar.gz.  Extract the file using:

    tar xvzpf @PACKAGE_TARNAME@-@PACKAGE_VERSION@.tar.gz
    
This will create a directory named @PACKAGE_TARNAME@-@PACKAGE_VERSION@ which will contain
various subdirectories.

2.2.2 Configure

The BBN RPKI validation software uses autoconf to generate its
Makefiles.  On many systems, it will suffice to run ./configure.
However, the following options may be useful for the BBN RPKI
software.

Optional Packages:
  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
  --with-ssl-include      Path to openssl library install location: Defaults
                          to /usr/local/ssl/include
  --with-ssl-lib          Path to openssl library install location: Defaults
                          to /usr/local/ssl/lib
  --with-cryptlib-include Path to cryptlib install location: Defaults to
                          /usr/local/include
  --with-odbc-include     Path to unixodbc include files: Defaults to
                          /usr/local/include
  --with-cryptlib-lib     Path to cryptlib install location: Defaults to
                          /usr/local/lib
  --with-odbc-lib         Path to unixODBC install location: Defaults to
                          /usr/local/lib

In addition, GNU make has the ability to dramatically reduce its
output.  If you are using GNU make, then you have the option to use

./configure --enable-silent-rules [other options]

which will give much shorter compilation/linking notifications.

The RTR code currently only compiles under gcc. If you have multiple
compilers installed, add the option "CC=gcc" to ./configure.

2.2.3 Build the Executables

Once the configure script has generated all of the Makefiles, build
the executables by issuing "make" in the top-level source directory.
On some systems, the default is not GNU Make, so you may want to
substitute the appropriate command (e.g. "gmake" on FreeBSD).


2.3 RPKI User Account

Establish a user account from which to run the RPKI software.  This
allows environment variables to be set consistently between logins,
especially if the default values need to be overridden.  It also
provides a place, ~/.ssh/authorized_keys, to put all the RPKI-RTR
clients' public keys to allow SSH login.

2.3.1 Environment Variables

There are several environment variables used throughout the scripts
and the code:

required: RPKI_ROOT - full path to the top-level directory of the RPKI tree
required: RPKI_PORT - port number on which the loader and feeder communicate
required: RPKI_DB - name of the MySQL database used to hold RPKI data
required: RPKI_DBUSER - username for logging into the MySQL database
required: RPKI_DBPASS - password for logging into the MySQL database, if any
required: RPKI_DSN - the DSN for db connection (e.g. "myodbc3-np")
optional: RPKI_ROOTPASSWORD - the MySQL root password
optional: RPKI_LISTPORT - port number for use by coordinator of parallel rsync

Set these environment variables to match your installation.  You may
choose any unused ports for RPKI_PORT and RPKI_LISTPORT.

Some variables are required for the operation of the RPKI software.
Each script will check for the required environment, and if any
variables are not set, the script will warn the user and automatically
set them to the following defaults:

RPKI_DB = rpkidb7
RPKI_PORT = 7344
RPKI_ROOT = ${HOME}/rpki
RPKI_DBUSER = rpki
RPKI_DBPASS = bbn
RPKI_DSN = myodbc3
RPKI_LISTPORT = 3450

If you ever need to directly run the binaries instead of running the
scripts, there will be no setting of defaults for environment
variables, so make sure to set these yourself.


2.4 SSH Subsystem

If you plan to use the RTR Server as an SSH subsystem, you will need
to run the rtr/rpstir-rtrd server as a daemon and set up an ssh subsystem
to connect to rtrd on localhost.  The netcat program, nc(1), is
recommended for the ssh subsystem.  There are different versions of
netcat, so read its manpage for caveats before setting it up as
a subsystem.  In particular, read the "-q" option's description, if your
version of netcat has a "-q" option, to prevent runaway nc processes
when clients disconnect. Edit the /etc/ssh/sshd_config file to contain
the below line, modified for the options you want to pass to netcat:

  Subsystem	rpki-rtr	nc <nc-options>... localhost <rtr-port>


2.5 Self Test

To perform a basic validation of your install, run the self-test
target by issuing the command:

   make check

Note:  this will clear any data in the RPKI database.

You may need to enter the MySQL root password several times as the
various self-test steps proceed.  If all tests pass, you will see a
message indicating success.

If the tests fail because of not enough output lines, it's possible
that it's because of a known bug (#174). The workaround is to insert
sleep commands into subsystemTests/runSubsystemTest.sh at the bottom
of the loop that contains the line "./step${TESTID}.${N}". The amount
of time needed to sleep depends on a number of factors and can be
increased (within limits) until make check succeeds.

If you have valgrind installed, you can run some tests under valgrind
by running the command:

   make check CHECKTOOL=valgrind


2.6 Post-Installation Procedures

Once the RPKI software installation passes the self-test, you may
configure it to automatically run at regular intervals via cron.  It
may also be desirable to allow arbitrary users to query the RPKI
database.

2.6.1 Cron Job Configuration

Except for the query client, all RPKI processes should run as the RPKI
user at regular intervals using cron jobs.  NOTE: While cron job
configuration will be used for final deployment, this release (@PACKAGE_VERSION@)
does not include suggested crontab entries.  It is assumed that for
trial purposes, manual execution gives the user/debugger maximum
control.

--------------------------------------------------------------------
Component (script or executable)     Frequency
--------------------------------------------------------------------
Parallelized rsync (rsync_cord.py)   Invoked by chaser
RCLI Database Client (loader.sh)     Continuously as daemon
Garbage Collector (garbage.sh)       Once per day
Chaser Client (chaser.sh)            Once per day
Trust anchor updater (updateTA.py)   Just before each chaser run
MySQL Database                       Continuously as daemon (mysqld)

RTR Server (rtr/rpstir-rtrd)         Continuously as daemon
RTR updater (rtr/rpstir-rtr-update)  After each call to chaser
RTR client (rtr/rtr-test-client)     On demand by user

Query Client (query.sh)              On demand by user
Results Statistics (results.py)      On demand by user
Initialization (initDB.sh)           Ideally only once ("reset all")
--------------------------------------------------------------------


2.6.2 Adjust Permissions

Depending on the setup, you may also want to allow arbitrary users to
run a query against the RPKI database, or to launch an rsync update
cycle.  This step is unnecessary if you are simply trying this
software out.

===============================================================================

3. Running the RPKI Software

3.1 Walkthrough

The following walkthrough shows how to run the BBN RPKI validator.
Note that steps 3.1.1-3.1.3 only need to be executed once at the
beginning if everything goes completely as planned.  The other steps
should be run periodically even under ideal circumstances.  In
production, it is recommended that the user create a script to run
3.1.4-3.1.6 and have a cron job that executes this script
periodically.

3.1.1 Add rsync uris to configuration file.

If you wish to download from publication points other than those
derived from the trust anchors, then add those publication points
to the file, additional_rsync_uris.config.

3.1.2 Clear database and local repository cache.

First, clear any existing local cache and call the initDB script.
This deletes the database, if any, with the name RPKI_DB and sets up a
new database with all the right tables.  Be prepared to enter the root
MySQL password twice.

    cd $RPKI_ROOT
    rm -rf REPOSITORY LOGS chaser.log rcli.log rsync_aur.log
    mkdir -p REPOSITORY
    mkdir -p LOGS
    run_scripts/initDB.sh

3.1.3 Invoke DB Updater (rcli) in listening mode.

The following script starts the process that receives data from the
rsync log parser and loads it into the database.  Under ideal
circumstances, this will continue to run forever, waiting for input
from the log parser.  Note that this script actually invokes rcli--the
same executable that adds the trust anchors--but with flags which
enable a different mode where it perpetually listens on a TCP socket
for notifications of rsync updates.

     xterm -e run_scripts/loader.sh &

As the command indicates, it is useful run loader.sh in a new xterm
window.  Doing so separates the DB updater (rcli) log messages from
the chaser/rsync log messages.

3.1.4 Automatically download Trust Anchors using TAL files.

A trust anchor certificate in the RPKI is obtained through a long term
Trust Anchor Locator (TAL), which allows distribution via a mix of
out-of-band and online means [draft-ietf-sidr-ta].  In practice,
relying parties obtain TAL files through a trusted out-of-band channel
of their choice.  For testing purposes, these instructions use Rob
Austein's collection of sample trust anchors found at
http://subvert-rpki.hactrn.net/trunk/rcynic/sample-trust-anchors .

    cd $RPKI_ROOT
    # The following three commands retrieve three example long-term
    # trust anchors in the form of TALs.  Operationally, these TALs
    # must be obtained through a trusted channel, not HTTP!
    wget http://subvert-rpki.hactrn.net/trunk/rcynic/sample-trust-anchors/testbed-ripe.tal
    wget http://subvert-rpki.hactrn.net/trunk/rcynic/sample-trust-anchors/testbed-arin.tal
    wget http://subvert-rpki.hactrn.net/trunk/rcynic/sample-trust-anchors/testbed-apnic.tal
    # The following command parses the TAL files, downloads the trust
    # anchor certificates, verifies their public key and signature, and
    # inserts them into the local database.
    run_scripts/updateTA.py testbed-ripe.tal testbed-arin.tal testbed-apnic.tal

3.1.5 Manually insert trust anchors (optional).

Trust anchor material is not always distributed via TAL, e.g. in the
case of local trust anchors.  Instead, we assume the user has directly
obtained the trust anchor certificates through some reliable
out-of-band method.  Then, we use the out-of-band invocation of rcli
to manually add each of the trust anchors.

    cd REPOSITORY
    # The following three commands should be replaced by reliable methods.
    rsync rsync://apnic.rpki.net/rpki/apnic/root.cer apnic_root.cer
    rsync rsync://arin.rpki.net/rpki/arin/root.cer arin_root.cer
    rsync rsync://ripe.rpki.net/rpki/ripe/root.cer ripe_root.cer
    cd ..
    proto/rcli -y -F REPOSITORY/apnic_root.cer
    proto/rcli -y -F REPOSITORY/arin_root.cer
    proto/rcli -y -F REPOSITORY/ripe_root.cer

3.1.6 Run URI Chaser.

This chases down objects from repositories that may not have been
loaded but are required.  The chaser automatically invokes rsync to
download from all the repositories.  When each rsync transfer
completes, the chaser invokes the rsync log parser, which notifies the
DB Updater (activated in the previous step) of any changes.

    run_scripts/chaser.sh

The process of chasing URIs and then invoking rsync will automatically
continue until no new publication directories have been found, or
until a maximum depth is reached.

3.1.7 Run Garbage Collector.

(Note: the testbeds available as of 22 Nov 2010 have only small
amounts of change due to expiration.  Nevertheless, it may be
interesting to run the garbage collector just in case.)

The Garbage Collector is responsible for any time-related state
changes in object validity.  This checks for certificates that may
have expired due to the passage of time, or crls that may have become
stale due to the passage of time, and takes the appropriate actions.
Any children certificates or roas of an expired certificate that are
not reparented are marked as invalid, with this propagating down
signing chains.  Certificates, and their descendant certificates and
roas, that might potentially be revoked by the updated version of a
stale crl are set to an intermediate state of validity (called
"unknown"), but are set back to valid if a current crl is available.

    run_scripts/garbage.sh

Successful garbage collection may not produce any screen output.


3.2 Results and Analysis

There are three ways to obtain results from RPSTIR.
. For an overview, generate a Validation Report (results.py).
. For detailed information about validation state, use the Query Client.
. For error analysis, search through rcli.log.
We recommend starting with the first option and moving down the list
as more detailed information is required.

3.2.1 Validation Report (results.py)

At a basic level, every object is in one of three states: fully
validated to a trust anchor, unknown, and definitely invalid.  Valid
objects are inserted in the database; unknown objects are potentially
valid, so they are kept in the database; definitely invalid objects
are not entered into the database.

The validation report generator (results.py) searches the local cache
and the database and summarizes the three categories as counts.  In
verbose mode, it also shows full paths to all invalid/unknown
certifcates, thereby allowing the user to determine the offending
rsync publication URI.

Usage: run_scripts/results.py [options]
Options:
  -h, --help     show this help message and exit
  -v, --verbose  print lists of valid/unknown/invalid objects to stdout

Example output:

[bbn@rpki-fc13 rpki]$ run_scripts/results.py 
Using RPKI root directory: /home/bbn/rpki
Using local repository path: /home/bbn/rpki/REPOSITORY

-------------------------------------------------------------------------------
Certficate Information:
-------------------------------------------------------------------------------
CA cert files: 23
EE cert files: 136
Total cert files: 159
Validated certs: 81
Status-unknown certs: 49
Invalid or duplicate certs: 29

-------------------------------------------------------------------------------
CRL Information:
-------------------------------------------------------------------------------
Total crl files: 21
Validated crls: 12
Status-unknown crls: 5
Invalid or duplicate crls: 4

-------------------------------------------------------------------------------
ROA Information:
-------------------------------------------------------------------------------
Total roa files: 105
Validated roas: 56
Status-unknown roas: 49
Invalid or duplicate roas: 0

-------------------------------------------------------------------------------
Manifest Information:
-------------------------------------------------------------------------------
Total manifest files: 31
Validated manifests: 7
Status-unknown manifests: 0
Invalid or duplicate manifests: 24

Hint: to see lists of unknown/invalid objects, run with -v.

3.2.2 Query Client

This is the way to pull specific information out of the database and
local repository.  There are two basic modes.

The comprehensive query, indicated by the argument "-r", pulls all the
valid ROAs from the repository and outputs a set of BGP filters in
RPSL format specified by these ROAs.  To send the output to a file
rather than the screen, include "-o <filename>" on the command line or
just redirect the output. ROAs (as well as certificates and CRLs) can
also be stale for a variety of reasons:
  - Validation Chain Stale: The ROA was validatated by a trust chain
    at some point, but now there is no longer a trust chain (e.g., due
    to a certificate expiring or being revoked by a CRL).
  - Stale CRL: Some certificate in the ROA's trust chain is in the
    domain of a CRL that was supposed to be updated by a certain time
    and has not.
  - Stale Manifest: Similar to stale CRL
  - No Manifest: Either the ROA or some certificate in its trust chain
    is not on a validated manifest.
For each type of staleness, it is possible to specify that the query
consider ROAs that are stale in this manner to be either all valid or
all invalid.  To control how different types of staleness are treated,
use the "-s <filename>" option, where filename is a file in the same
basic format as the sampleQuerySpecs file.  The sampleQuerySpecs file
also has further documentation on the different types of filtering
that can be specified.

The informational query provides the user with a means to see what is
in the database without directly executing MySQL commands.  The basic
informational query has the form
./query.sh -t <type> -d <field> [-d <field> ... -d <field>]
where type is either cert, crl, roa or manifest, and the fields are
all the fields of the objects to display.  There are different
possible fields for each object type. The full list of possibilities
is obtained with the command "query.sh -l <type>".  Most of these
fields also provide the capability for filtering the results based on
a simple comparison.  To do such filtering, add as many "-f
<field>.<op>.<value>" arguments to the command line as desired, where
op is one of (eq, ne, lt, gt, le, ge) and value is unquoted and
contains # characters to replaces spaces.  Additional arguments are
given if you type proto/query without any arguments.

    Examples:

    proto/query -t cert -d pathname      # display paths of valid certs
    proto/query -t cert -d pathname -d flags # display path+flags of valid certs
    proto/query -t cert -d pathname -i   # display paths of valid/unknown certs
    proto/query -t crl -d all            # display all fields of valid CRLs
    proto/query -t roa -d pathname -d flags # display path+flags of valid roas
    proto/query -t man -d all -i # display all fields of valid/unknown manifests


3.3 Warning

Aborting any of the scripts that change the database or repository in
the middle of operation can leave the database in an inconsistent
state.  It is recommended that after any such abort, you re-initialize
the database, clear the repository, and reload the data from scratch.
In the future, we plan to provide less drastic means of recovering
from an abort.

===============================================================================

Appendix A. Troubleshooting

A.1 Database troubleshooting

If you are having database errors, particularly when you first attempt
to use rcli, it is important to check and make sure that your MySQL
installation is correct.  Try the following command (drop the '-p' if
your MySQL user has no password):

    mysql --user=$RPKI_DBUSER -p

This should connect you to the database and give a "mysql> " prompt
back. If it does not, then your MySQL and/or ODBC installation is not
correct. Check the troubleshooting section of the MySQL
documentation. Verify that your ODBC information, in
/usr/local/etc/odbc.ini and /usr/local/etc/odbcinst.ini, is correct.
Verify that the MySQL daemon process mysqld is running using "ps -ef".
Verify that there is a mysql socket named mysql.sock, typically in
/tmp.

Once you can successfully connect to the database as user "mysql" try
connecting as root by issuing the command:

    mysql --user=root --password=PWD

where PWD is the root password specified in your odbc.ini file. If
this does not succeed, follow the steps given in the MySQL manual for
resetting the root password, then stop and restart the mysqld process.


A.2 64-bit support

The RPKI software does not currently support running in 64-bit mode.
It is however possible to run RPKI in 32-bit mode on a 64-bit OS that
supports 32-bit binaries and libraries.

The build environment, including gcc, need to support 32-bit programs.
You may need to install additional packages, see your operating system's
documentation. To compile in 32-bit mode on x86_64, gcc takes the flags
"-m32 -march=i686". The rest of these instructions assume those are the
appropriate flags for 32-bit compilation. Substitute whatever your system
uses in their place.

All libraries that RPKI depends on need to be compiled in 32-bit mode.
They may also need to be installed in an alternate library path for 32-bit
libraries, see your operating system's documentation.

Here are some notes from installing on CentOS 6.0 x86_64 that may or may
not be useful for you:

To configure openssl, subsitute

    ./config enable-rfc3779

with

    ./Configure linux-elf enable-rfc3779 -m32 -march=i686

To build cryptlib:

Near the top of makefile, find the line that sets the
CFLAGS variable and append "-m32 -march=i686" without quotes. Find the
line that sets LDFLAGS and append "-m32" without quotes. Note that -m32
is actually a gcc option, not an ld option. This is unusual behavior of
cryptlib, not a mistake in this document. Lower down in makefile, find
the line that starts like

    $(SLIBNAME):

Under that line, there should be a line that looks something like

    @./tools/buildsharedlib.sh ... $(LD) ...

Change only the "$(LD)" part so it looks like

    @./tools/buildsharedlib.sh ... "$(LD) $(LDFLAGS)" ...

Note the addition of quotes, they're important.

Next, edit tools/ccopts.sh and delete all instances of the word (string
separated by whitespace) "-march=opteron" that occur on a line that
looks like

    CCARGS=...

Continue building with the regular instructions.

To configure RPKI itself, run

    ./configure CFLAGS="-m32 -march=i686"


A.3 Specific Operating Systems

A.3.1 OpenBSD

If you have trouble compiling mysql-ODBC-connector, you may need to find
all lines in its source that call wprintf() or swprintf() and comment
them out.

A.3.2 FreeBSD

If you have trouble compiling cryptlib, you may have to comment out the
sections in tools/ccopts.sh that enable ODBC support.