Routing Security Step-by-Step Guide

Command Reference

Table of Contents

Table of Contents

1 Introduction

2 Relying-Party Tools

3 rcynic Support Programs
   4 RPKI Utility Programs

5 Parsons Utility Programs

6 Certification-Authority Daemons
   7 Certification-Authority Utilities

8 Certification-Authority Test Tools

1 Introduction

In the RPKI system, a Relying Party retrieves RPKI objects from repositories, validates those objects, and uses the validation results as input to provide BGP security.

The rpki.net software provides tools for handling these functions, as well as for providing support and maintenance to those tools. This document discusses these tools and gives usage information for them. The Relying-Party tools provide this functionality. It is divided into the following sections:

This document is prepared under Contract Number HSHQDC-14-C-B0035 for DHS S&T CSD

2 Relying-Party Tools

rcynic and rpki-rtr are the primary Relying-Party tools. rcynic validates RPKI data. rpki-rtr transfers validated RPKI data to routers. rcynic-cron acts as a wrapper for these two tools. These tools are discussed in this section.

Relying-Party tools:

2.1 rcynic

rcynic is the primary RPKI tool for the rpki.net system. It performs the actual work of RPKI validation: checking syntax, signatures, expiration times, and conformance to profiles for RPKI objects. Data are pulled from remote sites (via rsync) and rcynic recursively walks the RPKI tree to validate certificates and CRLs. The other relying party programs take rcynic's output as their input.

rcynic maintains the RPKI objects in a set of directories, the layout of which is described below. It has the ability to work in a chroot() environment, but this is not the normal method of operation. This used to be the default configuration, but it proved impractical to properly integrate this with various packaging systems (FreeBSD ports, apt-get on Ubuntu and Debian, etc.) If necessary, this behavior can still be used by installing from source and giving the --enable-rcynic-jail option to ./configure.

The default rpki.net configuration (as given by make install and the various packaging systems) will run rcynic under cron using the rcynic-cron wrapper script.

Usage: 

    rcynic [options]

    Where options are:

        -a ARG  --authenticated ARG        root of authenticated data tree
        -c ARG  --config ARG               override default name of config file
        -h      --help                     print this help message
        -j ARG  --jitter ARG               set jitter value
        -l ARG  --log-level ARG            set log level
        -u ARG  --unauthenticated ARG      root of unauthenticated data tree
        -e      --use-stderr               log to syslog
        -s      --use-syslog               log to stderr
        -V      --version                  print program version
        -x ARG  --xml-file ARG             set XML output file location

rcynic.conf Configuration File

Most of rcynic's operational parameters are set in the rcynic.conf configuration file. The default name for the configuration is rcynic.conf; though this can be overridden with the -c option on the command line. In addition, a few parameters can be set from the command line.

rcynic.conf uses OpenSSL's configuration file syntax, which allows for multiple configuration sections. rcynic's own configuration parameters are in the "[rcynic]" section. The OpenSSL library configuration parameters (e.g., "engine" settings) required by rcynic can be set in this file as well.

Most configuration parameters are optional and reasonable defaults are used. If rcynic runs as a daemon (for example, started by the rcynic-cron script) additional parameters must be set to tell rcynic where to find its data and where to write its output. While many of the parameters are optional, the rcynic.conf is not. In order for rcynic to do anything useful, the configuration file must tell rcynic where to find one or more RPKI trust anchors or trust anchor locators (TALs).

The Step-By-Step Configuration File Reference has a complete description of the rcynic.conf file.

Data and Files

rcynic manages a diverse collection of certificates, CRLs, trust anchors, trust anchor locators, and CMS objects. Some of these are authenticated and some are unauthenticated. rcynic stores its database using filenames derived from the RPKI rsync URIs at which the data are published.

By default, rcynic stores its objects in two writable directory trees:

  • directory of unauthenticated data

    This directory contains raw data fetched by rsync. In order to take full advantage of rsync's optimized transfers, this directory should be preserved and reused across rcynic runs. This prevents rcynic from having to re-fetch data that have not changed.

    The actual directory is named by the unauthenticated field in the rcynic.conf file.

  • directory of authenticated data

    This directory contains data which rcynic has validated. This is the real output of the validation process.

    The name of the authenticated directory is really a symbolic link to a directory with a name of the form "authenticated.<timestamp>", where <timestamp> is an ISO-8601 timestamp like 2001-04-01T01:23:45Z. rcynic creates a new timestamped directory every time it runs, and changes the symbolic link as an atomic operation when the validation process completes. The intent is that the symbolic link of the authenticated directory always points to the most recent usable validation results, so that programs which use rcynic's output don't need to worry about whether an rcynic run is in progress.

    The actual directory is named by the authenticated field in the rcynic.conf file.

rcynic expects all certificates, CRLs, and CMS objects to be in DER format.

In order for rcynic to do anything useful, the rcynic.conf must contain one or more RPKI trust anchors or trust anchor locators (TALs).

rcynic installs trust anchors specified via the trust-anchor-locator directive in the unauthenticated directory tree just like any other fetched object. They are copied into the authenticated directory tree just like any other object once they pass rcynic's authentication checks. Each trust anchor has a unique name within the output tree.

rcynic copies trust anchors specified via the trust-anchor directive into the top-level directory of the authenticated tree with filenames of the form <xxxxxxxx>..cer, where <xxxxxxxx> and <n> are the OpenSSL object name hash and index, respectively, within the resulting virtual hash bucket. These are the same values that OpenSSL's c_hash script would produce. The reason for this naming scheme is that these trust anchors, by definition, are not fetched automatically, and thus do not really have publication URIs in the sense that every other object in these trees do.

Trust anchors cannot be confused with certificates. Trust anchors are always placed in the top level of the tree, while data fetched via rsync are always placed in subdirectories.

Trust anchors and trust anchor locators taken from the directory named by the trust-anchor-directory directive will follow the same naming scheme trust anchors and trust anchor locators specified via the trust-anchor and trust-anchor-locator directives.

rcynic Logging Levels

rcynic has its own system of logging levels, similar to those used by syslog(). However, the levels have been customized for the specific tasks performed by rcynic.

 
Log LevelDescription
log_sys_errError from operating system or library
log_usage_errBad usage (local configuration error)
log_data_errBad data (broken certificates or CRLs)
log_telemetryNormal chatter about rcynic's progress
log_verboseExtra verbose chatter
log_debugOnly useful when debugging

2.2 rpki-rtr

rpki-rtr transfers validated RPKI prefix origin data from a trusted cache to routers. This allows the routers to verifiably validate the origin AS's in BGP announcements. The trusted cache is built by the rcynic command.

rpki-rtr depends on rcynic to collect and validate the RPKI data. rpki-rtr serves that data in a light-weight format suitable for routers that want to do prefix origin authentication.

rpki-rtr is designed to do the translation from raw RPKI data into the rpki-rtr protocol only once. It does this by pre-computing the answers to all the queries it will answer for a given data set, and storing those answers on disk. rpki-rtr's cron job command handles this computation.

The software referred to as rpki-rtr consists of the rpki-rtr server, a test client, and a utility for examining the content of the database rpki-rtr generates from the data supplied by rcynic.

rcynic's output must be converted into the data files used by rpki-rtr. The rcynic-cron script handles this automatically, and is part of the default installation.

In addition, a listener for the rpki-rtr server must be set up. The listener will receive the generated data files. There are platform-specific packages for FreeBSD, Debian, and Ubuntu that automatically set up a plain TCP listener. Other platforms will require additional work to create a listener. If TCP is not being used as a transport protocol, then an alternate listener will also have to be created.

The transfer protocol implemented by rpki-rtr is defined in RFC-6810.

Usage: 

    rpki-rtr [-h] [--debug]
                  [--log-level {debug,info,warning,error,critical}]
                  [--log-to {syslog,stderr}]
    	      <command-specific options>
    	      <command>
    	      <command-specific arguments>

    optional arguments:
      -h, --help            show this help message and exit
      --debug               debugging mode
      --log-level {debug,info,warning,error,critical}
      --log-to {syslog,stderr}

    Commands:
      
        server              RPKI-RTR protocol server
        listener            TCP listener for RPKI-RTR protocol server
        client              Test client for RPKI-RTR protocol
        cronjob             Generate RPKI-RTR database from rcynic output
        show                Display content of RPKI-RTR database
The subcommands for rpki-rtr are described below.

2.2.1 rpki-rtr client

This subcommand invokes a test client, which is primarily used for debugging.

Usage: 

    rpki-rtr client [-h] [--sql-database SQL_DATABASE]
                           [--force-version {0,1}] [--reset-session]
                           {loopback,tcp,ssh,tls} [host] [port]

    positional arguments:
      {loopback,tcp,ssh,tls}
                            connection protocol
      host                  server host
      port                  server port

    optional arguments:
      -h, --help            show this help message and exit
      --sql-database SQL_DATABASE
                            filename for sqlite3 database of client state
      --force-version {0,1}
                            force specific protocol version
      --reset-session       reset any existing session found in sqlite3 database

2.2.2 rpki-rtr cronjob

This subcommand is run after executing rcynic has gathered router certificates and ROAs. It translates those data into the form used in the rpki-rtr protocol. This subcommand's output is an updated database containing both full dumps (AXFR) and incremental dumps against a specific prior version (IXFR). After updating the database, active servers are notified that they can inform their own clients that a new database version is available.

Usage: 

    rpki-rtr cronjob [-h] [--scan-roas SCAN_ROAS]
                            [--scan-routercerts SCAN_ROUTERCERTS]
                            [--force_zero_nonce]
                            rcynic_dir [rpki_rtr_dir]

    positional arguments:
      rcynic_dir            directory containing validated rcynic output tree
      rpki_rtr_dir          directory containing RPKI-RTR database
    
    optional arguments:
      -h, --help            show this help message and exit
      --scan-roas SCAN_ROAS
                            specify an external scan_roas program
      --scan-routercerts SCAN_ROUTERCERTS
                            specify an external scan_routercerts program
      --force_zero_nonce    force nonce value of zero

2.2.3 rpki-rtr listener

This subcommand provides an insecure TCP listener for the rpki-rtr protocol.

Usage: 

    rpki-rtr listener [-h] [--refresh REFRESH] [--retry RETRY]
                             [--expire EXPIRE]
                             port [rpki_rtr_dir]

    positional arguments:
      port               TCP port on which to listen
      rpki_rtr_dir       directory containing RPKI-RTR database

    optional arguments:
      -h, --help         show this help message and exit
      --refresh REFRESH  override default refresh timer
      --retry RETRY      override default retry timer
      --expire EXPIRE    override default expire timer

In theory, RPKI will migrate to using TCP-AO in the future. When this happens, this listener functionality will either go away or become a TCP-AO listener.

2.2.4 rpki-rtr server

This subcommand provides the server side of the rpki-rtr protocol. Most of the work has already been done by the database generator, so all this server has to do is pass results along to a client. Other than one PF_UNIX socket inode, this doesn't write anything to disk. For these two reasons, this subcommand can be run with minimal privileges.

Usage: 

    rpki-rtr server [-h] [--refresh REFRESH] [--retry RETRY]
                           [--expire EXPIRE]
                           [rpki_rtr_dir]

    positional arguments:
      rpki_rtr_dir       directory containing RPKI-RTR database

    optional arguments:
      -h, --help         show this help message and exit
      --refresh REFRESH  override default refresh timer
      --retry RETRY      override default retry timer
      --expire EXPIRE    override default expire timer

2.2.5 rpki-rtr show

This subcommand displays the current rpki-rtr server database in textual form.

Usage: 

    rpki-rtr show [-h] [rpki_rtr_dir]

    positional arguments:
      rpki_rtr_dir  directory containing RPKI-RTR database

    optional arguments:
      -h, --help    show this help message and exit

2.3 rcynic-cron

rcynic-cron is a wrapper for a set of Relying Party tools and is intended to be run as a cron job. It executes the RP commands consecutively, waiting for each one to finish before starting the next. The RP commands, in execution order, are:

  • rcynic
  • rpki-rtr cronjob
  • rpkigui-rcynic
  • rcynic-html
Usage: 
    $ rcynic-cron [--chroot]

    --chroot
        run chrooted; only usable by root

If the --chroot option is given to rcynic-cron, then it will run rcynic in a chroot()'d environment. This only applies to rcynic; the other commands are started regularly. This option may only be used by the root user.

The chroot() environment has two rcynic-cron-specific requirements. The rcynic command must be available in the environment's /bin/rcynic. Also, there must be an rcynic configuration file in the environment's /etc/rcynic.conf.

The rpki.autoconf module defines the locations in which rcynic-cron looks for various fields and paths to use in executing the child processes. The command lines below denote these module-based paths by being enclosed in brackets.

If rcynic-cron was run without the --chroot option, then rcynic will not be run in a restricted environment. The following command line (after field replacement) will be used: 

    {autoconf.bindir}/rcynic -c {autoconf.sysconfdir}/rcynic.conf

The rpki-rtr cronjob command will be run with the following command line (after field replacement): 

    {autoconf.bindir}/rpki-rtr cronjob   		\
        {autoconf.RCYNIC_DIR}/data/authenticated	\
        {autoconf.RCYNIC_DIR}/rpki-rtr

The rpkigui-rcynic command will be run with the following command line (after field replacement): 

    {autoconf.bindir}/rpkigui-rcynic

The rcynic-html command will be run with the following command line (after field replacement): 

    {autoconf.bindir}/rcynic-html			\
        {autoconf.RCYNIC_DIR}/data/rcynic.xml		\
        {autoconf.RCYNIC_HTML_DIR}

flock()-based file locking is used to ensure that only one instantiation of rcynic-cron executes at a time.

This command is intended to be executed by cron. The rpki.net installation process sets up a cron job to run rcynic-cron as user "rcynic" once per hour at a randomly-selected minute.

3 rcynic Support Programs

rcynic creates several XML files that describe the actions it has taken and the validation status of the objects it has found. Several commands are available to providing post-processing for the output generated by rcynic.

Utility Programs:

3.1 make-tal.sh

The make-tal.sh script is used to generate a Trust Anchor Locator (TAL) file for a Trust Anchor (TA). It uses the openssl req command to create the TAL. After generating a new root.cer file, the updated root.cer must be copied to the publication directory. Regenerating the certificate does not require regenerating the TAL unless the key or URL have changed.

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

The first argument must be an rsync URI. The second argument is the certificate file to be used.

Like any certificate, the root.cer generated by make-tal.sh will expire eventually. It must be regenerated before it expires. This may be done manually or a cron job can be used to create the certificate automatically.

3.2 rcynic-html

rcynic-html summarizes the XML output files created by rcynic. These files are reformatted into a collection of HTML pages and statistics are added to a set of RRD databases. The HTML files show the history of rsync transfer times and repository object counts in graphical form, as well as reporting problems encountered by rcynic.

Generally, you will not need to run rcynic-html yourself since rcynic-cron runs rcynic-html immediately after starting rcynic.

If for some reason you do need to run rcynic-html manually, the command usage is: 

    $ rcynic-html rcynic.xml /web/server/directory/
rcynic-html will write a collection of HTML and image files to the specified output directory. rcynic-html will create the output directory, if necessary. The RRD databases of statistics will also be stored in this directory.

rcynic-html requires rrdtool, a specialized database and graphing engine designed for maintaining round-robin databases. By giving the --no-show-graphs option, rcynic-html can run without rrdtool; however, the results won't be as useful.

autoconf, run at install time, will provide rcynic-html with a path to rrdtool. This initialization usually works; if for some reason it doesn't work in your environment, you will need to tell rcynic-html where to find rrdtool. This can be done in two ways. First, the path to rrdtool may be specified by passing the --rrdtool-binary option to rcynic-html: 

    $ rcynic-html --rrdtoolbinary /somewhere/rrdtool rcynic.xml /web/server/directory/

The second way involved changing the rpki/autoconf.py file. This file should be located somewhere in the Python distribution. Edit the file and change the value of the RRDTOOL field to have the proper path to rrdtool.

3.3 rcynic-svn

rcynic-svn archives rcynic's results in a Subversion repository. For relying parties who want to analyze rcynic's output over a long period of time, rcynic-svn may provide a useful starting point. This is not something that every relying party is going to want, so rcynic-svn is not integrated into rcynic-cron.

To use rcynic-svn, you first must set up a Subversion repository and check out a working directory: 

    $ svnadmin create /somewhere/safe/rpki-archive
    $ svn co file:///somewhere/safe/rpki-archive /somewhere/else/rpki-archive
These commands create the repository /somewhere/safe/rpki-archive, then checks out an empty working directory in /somewhere/else/rpki-archive.

Once the repository and working directory are set up, you need to arrange for rcynic-svn to be executed after each rcynic run whose results must be archived. One way to do this would be to run rcynic-svn in the same cron job as rcynic-cron, immediately after rcynic-cron. The same same lock file used by rcynic-cron would have to be specified for rcynic-svn.

Usage: 


    $ rcynic-svn --lockfile /var/rcynic/data/lock       \
            /var/rcynic/data/authenticated              \
            /var/rcynic/data/unauthenticated            \
            /var/rcynic/data/rcynic.xml                 \
            /somewhere/else/rpki-archive
This execution assumes that rcynic's data is in the default location.

The last argument is the name of the Subversion working directory in which the results will be archived. The other arguments are the names of those portions of rcynic's output which are to be archived. Generally, the above set (authenticated, unauthenticated, and rcynic.xml) are the ones you want.

3.4 rcynic-text

rcynic-text provides a quick flat-text summary of validation results. This is useful primarily in test scripts (smoketest uses it.)

Usage: 

    $ rcynic-text rcynic.xml

3.5 rcynic.xsl

rcynic.xsl is an obsolete method of performing the function of rcynic-html. The required processing involved got more complex, and XSLT became insufficient for properly manipulating the rcynic output.

If for some reason XSLT works better in your environment than Python, you might find this stylesheet to be a useful starting point. Be warned that rcynic-xsl is significantly slower than it lacks many features of rcynic-html. It is no longer under development.

3.6 validation_status

validation_status provides a flat-text translation of the detailed validation results. This is useful primarily for checking the detailed status of some particular object or set of objects, perhaps using a program like grep or awk to filter validation_status's output.

Usage: 

    $ validation_status rcynic.xml
    $ validation_status rcynic.xml | fgrep rpki.misbehaving.org
    $ validation_status rcynic.xml | fgrep object_rejected

4 RPKI Utility Programs

The rpki.net distribution contains several utility programs. Most of these are nominally Relying-Party tools, but work at a low enough level that they may also be useful in diagnosing CA problems.

Unless otherwise specified, all of these tools expect RPKI objects (certificates, CRLs, CMS signed objects) to be in DER format.

Several of these tools accept an rcynic_directory argument. The directory to specify here depends on what is trying to be done, but if you're just trying to look at authenticated data in your RP cache, and assuming you've installed everything in the default locations, the directory will probably be /var/rcynic/data/authenticated.

Utility Programs:

4.1 find_roa

find_roa searches the authenticated-result tree from an rcynic run for ROAs matching specified prefixes.

Usage: 

    $ find_roa [-h | --help] [-a | --all]
               [-m | --match-maxlength ] [-f | --show-filenames]
               [-i | --show-inception]   [-e | --show-expiration]
               authtree [prefix...]

    Where options are:

        -h --help
            Show help

        -a --all
            Show all ROAs, do no prefix matching at all

        -e --show-expiration
            Show ROA chain expiration dates

        -f --show-filenames
            Show filenames instead of URIs

        -i --show-inception
            Show inception dates

        -m -match-maxlength
            Pay attention to maxlength values

        authtree
            rcynic-authenticated output tree

        prefix
            ROA prefix(es) on which to match

4.2 hashdir

hashdir copies an authenticated-result tree from an rcynic execution into the format expected by most OpenSSL-based programs. This format is a collection of "PEM" format files with names in the form expected by OpenSSL's -CApath lookup routines. This can be useful for validating RPKI objects which are not distributed as part of the repository system.

Usage: 

    $ hashdir [-h | --help] [-v | --verbose] rcynic_directory output_directory

    Where options are:

        -h --help
            Show help

        -v --verbose
            Whistle while you work

        rcynic_directory
            rcynic-authenticated output tree

        output_directory
            Output directory to create

4.3 print_roa

print_roa pretty-prints the contents of a ROA. It does NOT attempt to verify the signature.

Usage: 

    $ print_roa [-h | --help] [-b | --brief] [-c | --cms] [-s | --signing-time]
    ROA [ROA...]

    Where options are:

        -h --help
            Show help

        -b --brief
            Brief mode (only show ASN and prefix)

        -c --cms
            Print text representation of entire CMS blob

        -s --signing-time
            Show CMS signingTime

        ROA
            ROA object(s) to print

4.4 print_rpki_manifest

print_rpki_manifest pretty-prints the contents of a manifest. It does NOT attempt to verify the signature.

Usage: 

    $ print_rpki_manifest [-h | --help] [-c | --cms] manifest [manifest...]

    Where options are:

        -h --help
            Show help

        -c --cms
            Print text representation of entire CMS blob

        manifest
            Manifest(s) to print

4.5 scan_roas

scan_roas searches the authenticated-result tree from an rcynic run for ROAs, and prints the signing time, ASN, and prefixes for each ROA, one ROA per line.

Other programs, such as the rpki-rtr client, use scan_roas to extract the validated ROA payload after an rcynic validation run.

Usage: 

    $ scan_roas [-h | --help] rcynic_directory [rcynic_directory...]

    Where options are:

        -h --help
            Show help

        rcynic_directory
            rcynic-authenticated output tree

4.6 scan_routercerts

scan_routercerts searches the authenticated-result tree from an rcynic run for BGPSEC router certificates, and prints data of interest to the rpki-rtr code.

Other programs such as the rpki-rtr client use scan_routercerts to extract the validated ROA payload after an rcynic validation run.

Usage: 

    $ scan_routercerts [-h | --help] rcynic_directory [rcynic_directory...]

    Where options are:

        -h --help
            Show help

        rcynic_directory
            rcynic-authenticated output tree

4.7 uri

uri extracts URIs from the SIA, AIA, and CRLDP extensions of one or more X.509v3 certificates. The certificates must be either specified directly or as CMS objects containing X.509v3 certificates within the CMS wrapper.

Usage: 

    $ uri [-h | --help] [-s | --single-line] cert [cert...]

    Where options are:

        -h --help
            Show help

        -s --single-line
            Single output line per input file

        cert
            Object(s) to examine

5 Parsons Utility Programs

Parsons, Inc., provides a number of utility programs for use with the rpki.net software.

Utility Programs:

  • map_whois - enables one to discover network resources in ARIN's whois database that could belong to an organization.
  • rcynicchk - validates the contents of an rcynic.conf file
  • rpkichk - validates the contents of an rpki.conf file
  • rsyncdchk - validates the contents of an rsyncd.conf file

5.1 map_whois

The map_whois enables one to discover network resources in ARIN's whois database that could belong to an organization. A starting point in the form of a known POC handle, organization handle, net handle, or ASN number is assumed. The tool thereafter queries ARIN's RESTful API in order to detect other resources that the organization may hold.

See the MapResources User's Guide for more information and examples of use.

Usage: 

    map_whois [-h] [-v] [-a ASN] [-p POC] [-o ORG] [-n NET] [-c CIDR]
        [-i IP] [-u URL] [-t THRESHOLD] [-l] [-s] [-f {png,svg}] [-R RVDB]
        [-L RESOURCELIST] [-j JSONFILE] [-g GRAPHFILE] [-r REPORTFILE]
        [-X | -H | -D DBSTORE]

    optional arguments:

        -h, --help
            show this help message and exit

        -v, --verbose
            increase output verbosity

        -a ASN, --asn ASN
            Start from the given ASN handle

        -p POC, --poc POC
            Start from the given POC handle

        -o ORG, --org ORG
            Start from the given Org handle

        -n NET, --net NET
            Start from the given Net handle

        -c CIDR, --cidr CIDR
            Start from the given CIDR block

        -i IP, --ip IP
            Start from the given IP address

        -u URL, --url URL
            Start from the given domain

        -t THRESHOLD, --threshold THRESHOLD
            Maximum number of dependencies to follow

        -l, --longform
            Dsplay detailed information

        -s, --showgraph
            Dsplay the graph

        -f {png,svg}, --format {png,svg}
            Graphviz file format to use

        -R RVDB, --rvdb RVDB
            Check against given Route Views Database file

        -L RESOURCELIST, --resourcelist RESOURCELIST
            Extract resource handles from the given file. Each line
            of the file should be formatted as :, where
            the different supported types are 'asn', 'poc', 'org',
            'net', 'cidr', 'ip' and 'url'.

        -j JSONFILE, --jsonfile JSONFILE
            Output resource information in json format

        -g GRAPHFILE, --graphfile GRAPHFILE
            Output graph image

        -r REPORTFILE, --reportfile REPORTFILE
            Output report

        -X, --nostore
            Do not use any data store

        -H, --hashstore
            Use an indexed hash store

        -D DBSTORE, --dbstore DBSTORE
            Use a DB store and issue queries if needed

5.2 rcynicchk

rcynicchk validates the contents of an rcynic.conf file. The configuration file is validated to ensure that reasonable values are specified for the various fields.

Some fields are not able to be fully validated. For example, the "rsync-program" field can be checked to ensure that it is a valid file, but it cannot be checked to ensure that the file is an rsync program.

The default configuration file is /etc/rcynic.conf. The -config option allows the user to specify an alternate file to be validated.

rcynicchk performs two types of checks -- basic checks and recommended-value checks. Both types of checks are performed by default. The -basic and -recval options allow only one type of check to be performed.

Basic checks are rudimentary checks of the configuration values in an rcynic.conf file. For example, it checks that the trust anchor directory is actually a directory, but not that it is only filled with trust anchors.

Recommended-value checks ensure that certain fields in an rcynic.conf file have the values recommended by the developers of the rpki.net software.

rcynicchk provides three types of output: a problem report, a table of results, and a summary. All three are given by default. However, any combination of the three may be selected by using the -problems, -table, and -summary options.

In addition to validating the contents of an rcynic.conf file, rcynicchk can display the contents. The -list option will display fields and values in the rcynic.conf file, but no validation will be performed.

Usage: 

    $ rcynicchk [options]

    Where [options] are:

        -config conffile         specify configuration file to validate
        -list                    only list configuration-section information

        -basic                   only run basic checks
        -recval                  only run recommended-value checks

	-problems		 only show problems found
        -summary                 give summary of checks only
	-table			 provide results in tabular form

        -verbose                 give verbose output
        -Version                 show version and exit
        -help                    show usage message and exit
        -manpage                 show the manual page and exit

See Validation Checks for rcynic.conf Files for more details on the various validation checks performed by rcynicchk.

5.3 rpkichk

rpkichk validates the contents of an rpki.conf file. The configuration file is validated to ensure that reasonable values are specified for the various fields. Some fields are not able to be fully validated. For example, the server-host field can be checked to ensure that it contains only characters valid for a hostname, but it cannot be checked to ensure that the specified hostname is truly the name of the required server host.

The default configuration file is /etc/rpki.conf. The -config option allows the user to specify an alternate file to be validated. The entire file is checked by default. However, there are options that restrict certain configuration sections from being checked. For example, the -nopubd option prevents validation of the fields in the pubd section.

rpkichk performs three types of checks -- basic checks, cross-checks, and recommended-value checks. All types of checks are performed by default. The -basic and -cross options allow only one type of check to be performed. (One additional type of checks -- cross-file checks -- is planned, but are not yet implemented.)

Basic checks are rudimentary checks of the configuration values in an rpki.conf file. For example, it checks that a database name isn't null, not that the database exists; or that a key file exists and is only readable by the file's owner, not that the key contents are a valid key.

Cross-checks ensure that an rpki.conf file is internally consistent. There are a number of fields in the configuration file that are related and are expected to have the same values. For example, the rootd section has the server-port and the myrpki section has the rootd_server_port field. The cross-checks ensure that these fields are the same.

Recommended-value checks ensure that certain fields in an rpki.conf file have the values recommended by the developers of the rpki.net software.

rpkichk provides three types of output: a problem report, a table of results, and a summary. All three are given by default. However, any combination of the three may be selected by using the -problems, -table, and -summary options.

In addition to validating the contents of an rpki.conf file, rpkichk can display the contents. The -list option will display fields and values in the rpki.conf file, but no validation will be performed. With no other options, all fields in all sections of the file will be listed. The -names option lists just the sections of the rpki.conf file. The -section option lists only the fields in the named section. Normally, field listings give the value as used by the RPKI software. However, the -untranslate option will give the value exactly as it is given in the rpki.conf file.

Usage: 

    $ rpkichk [options] 

    Where [options] are:

        -config conffile
	    specify configuration file to validate

        -list
	    list configuration-section information

        -names
	    list configuration-section names;
            must be used in conjunction with -list

        -untranslate
	    display untranslated values from the configuration file
            must be used in conjunction with -list

        -section section-name
	    specify section to examine;
            must be used in conjunction with -list

        -basic
	    only run basic checks

        -cross
	    only run cross-checks

        -recval
	    only run recommended-value checks

        -problems
	    only show problems found

        -summary
	    give summary of checks only

        -table
	    provide results in tabular form

        -noautoconf
	    don't check the autoconf section

        -noirdbd
	    don't check the irdbd section

        -nomyrpki
	    don't check the myrpki section

        -nopubd
	    don't check the pubd section

        -norootd
	    don't check the rootd section

        -norpkid
	    don't check the rpkid section

        -noweb_portal
	    don't check the web_portal section

        -verbose
	    give verbose output

        -Version
	    show version and exit

        -help
	    show usage message and exit

        -manpage
	    show the manual page and exit

See Validation Checks for rpki.conf Files for more details on the various validation checks performed by rpkichk.

5.4 rsyncdchk

rsyncdchk validates the contents of an rsyncd.conf file. The configuration file is validated to ensure that reasonable values are specified for the various fields.

The default configuration file is /etc/rsyncd.conf. The -config option allows the user to specify an alternate file to be validated.

rsyncdchk performs one type of checks. Basic checks are rudimentary checks of the configuration values in an rsyncd.conf file. For example, it checks that the path field is actually a directory, but not that it is used as is expected.

rsyncdchk provides three types of output: a problem report, a table of results, and a summary. All three are given by default. However, any combination of the three may be selected by using the -problems, -table, and -summary options.

In addition to validating the contents of an rsyncd.conf file, rsyncdchk can display the contents. The -list option will display fields and values in the rsyncd.conf file, but no validation will be performed.

Usage: 

    rsyncdchk [options]

    Where options may be:
        -config conffile         specify configuration file to validate
        -list                    list configuration-section information
        -names                   list configuration-section names;
                                 must be used in conjunction with -list
        -section section-name    specify section to examine;
                                 must be used in conjunction with -list

        -basic                   only run basic checks

	-problems		 only show problems found
        -summary                 give summary of checks only
	-table			 provide results in tabular form

        -norpki                  don't check the rpki section
        -noroot                  don't check the root section

        -verbose                 give verbose output
        -Version                 show version and exit
        -help                    show usage message and exit
        -manpage                 show the manual page and exit

See Validation Checks for rsyncd.conf Files for more details on the various validation checks performed by rsyncdchk.

6 Certification-Authority Daemons

The rpki.net Certification-Authority daemons implement the production-side tools for an RPKI environment. This includes generating the RPKI objects, such as certificates, CRLs, ROAs, and other RPKI objects. The four CA daemons are described below in their own sections.

Certification-Authority Daemons:

6.1 irdbd

irdbd is a sample implementation of the server side of the IRDB (Internet Registry DataBase.) irdbd is part of the IRBE (Internet Registry Back-End) system, and shares its SQL database with the rpkic utility and the rpki.net web interface.

In production, this service acts as a a function of the IRBE stub. irdbd may be suitable for production use in simple cases, but an Internet Registry with a complex IRDB may need to extend or rewrite irdbd.

irdbd's default configuration file is the system rpki.conf file. All of irdbd's options are in the "[irdbd]" section. A different configuration file may be used if irdbd is given with "-c filename" when the command is started.

By default, irdbd uses the syslog interface for logging. Options allow this to be changed to STDOUT, STDERR, or a named file.

The Step-By-Step Configuration File Reference has a complete description of the rpki.conf file.

Since irdbd is part of the back-end system, it has direct access to the back-end's SQL database. This allows it to to retrieve its own BPKI configuration directly from the database, which means that irdbd needs a little less configuration than the other Certification-Authority tools.

Usage: 

    irdbd [-h] [-c CONFIG] [-f] [--pidfile PIDFILE] [--profile PROFILE]
               [--log-level {debug,info,warning,error,critical}]
               [--log-syslog [{auth,authpriv,cron,daemon,ftp,kern,
		               local0,local1,local2,local3,local4,
			       local5,local6,local7,
			       lpr,mail,news,security,syslog,user,uucp}]   |
                --log-stderr | --log-stdout | --log-file LOG_FILE          |
                --log-rotating-file FILENAME KBYTES COUNT                  |
                --log-timed-rotating-file FILENAME HOURS COUNT]

    Where the options are:
        -h, --help            show this help message and exit
        -c CONFIG, --config CONFIG
                              override default location of configuration file
        -f, --foreground      do not daemonize
        --pidfile PIDFILE     override default location of pid file
        --profile PROFILE     enable profiling, saving data to PROFILE
        --log-level {debug,info,warning,error,critical}
                              how verbosely to log
        --log-syslog [{auth,authpriv,cron,daemon,ftp,kern,
		       local0,local1,local2,local3,local4,
		       local5,local6,local7,
		       lpr,mail,news,security,syslog,user,uucp}]
                              send logging to syslog
        --log-stderr          send logging to standard error
        --log-stdout          send logging to standard output
        --log-file LOG_FILE   send logging to a file, reopening if rotated away
        --log-rotating-file FILENAME KBYTES COUNT
                              send logging to rotating file
        --log-timed-rotating-file FILENAME HOURS COUNT
                              send logging to timed rotating file

The rpki.net package includes a second implementation of irdbd that is used only for testing. ca/tests/old_irdbd is a minimal implementation, used only by the smoketest testing tool. smoketest itself constitutes a fairly complete IRBE implementation. Ordinarily you won't need old_irdbd. However, for some reason you must write your own irdbd implementation, the work might be easier if started from this minimal version.

6.2 pubd

pubd implements the server side of the publication protocol. It publishes the certificates and other objects that rpkid generates. pubd stores dynamic data in an SQL database, which must have been created for it. pubd also stores the published objects themselves as disk files. The storage location is configurable by setting the appropriate field in the rsyncd.conf.

pubd's default configuration file is the system rpki.conf file. All of pubd's options are in the "[pubd]" section. A different configuration file may be used if pubd is given with "-c filename" when the command is started.

By default, pubd uses the syslog interface for logging. Options allow this to be changed to STDOUT, STDERR, or a named file.

The Step-By-Step Configuration File Reference has a complete description of the rpki.conf file.

Usage: 

    pubd [-h] [-c CONFIG] [-f] [--pidfile PIDFILE] [--profile PROFILE]
                [--log-level {debug,info,warning,error,critical}]
                [--log-syslog [{auth,authpriv,cron,daemon,ftp,kern,
                                local0,local1,local2,local3,local4,
                                local5,local6,local7,
                                lpr,mail,news,security,syslog,user,uucp}]   |
                 --log-stderr                                               |
                 --log-stdout                                               |
                 --log-file LOG_FILE                                        |
                 --log-rotating-file FILENAME KBYTES COUNT                  |
                 --log-timed-rotating-file FILENAME HOURS COUNT]

    optional arguments:
        -h, --help            show this help message and exit
        -c CONFIG, --config CONFIG
                              override default location of configuration file
        -f, --foreground      do not daemonize
        --pidfile PIDFILE     override default location of pid file
        --profile PROFILE     enable profiling, saving data to PROFILE
        --log-level {debug,info,warning,error,critical}
                              how verbosely to log
        --log-syslog [{auth,authpriv,cron,daemon,ftp,kern,
                       local0,local1,local2,local3,local4,local5,local6,local7,
                       lpr,mail,news,security,syslog,user,uucp}]
                              send logging to syslog
        --log-stderr          send logging to standard error
        --log-stdout          send logging to standard output
        --log-file LOG_FILE   send logging to a file, reopening if rotated away
        --log-rotating-file FILENAME KBYTES COUNT
                              send logging to rotating file
        --log-timed-rotating-file FILENAME HOURS COUNT
                              send logging to timed rotating file

The publication functionality could be combined with the main RPKI engine. This would result in pubd being part of the rpkid daemon. This was not done for two reasons:

  1. The hosting model allows installations 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 beneficial for Relying Parties, as it will speed up rcynic synchronization time.

  2. The publication server has to run on (or close to) the publication point itself. This means it must be on a publicly 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 publication server, so in some situations it might be preferable to wrap tighter firewall constraints around rpkid than would be practical for a combined rpkid/pubd daemon.

6.3 rootd

rootd is a stripped-down implementation of the server side of the up-down protocol. rootd is a simple implementation intended for test use, it's not suitable for use in a production system.

The root certificate of an RPKI certificate tree requires special handling and may also require a special handling policy.

rootd's default configuration file is the system rpki.conf file. All of rootd's options are in the "[rootd]" section. A different configuration file may be used if rootd is given with "-c filename" when the command is started.

By default, rootd uses the syslog interface for logging. Options allow this to be changed to STDOUT, STDERR, or a named file.

The Step-By-Step Configuration File Reference has a complete description of the rpki.conf file.

Usage: 

    rootd [-h] [-c CONFIG] [-f] [--pidfile PIDFILE]
               [--log-level {debug,info,warning,error,critical}]
               [--log-syslog [{auth,authpriv,cron,daemon,ftp,kern,
                               local0,local1,local2,local3,local4,
                               local5,local6,local7,
                               lpr,mail,news,security,syslog,user,uucp}]   |
                --log-stderr                                               |
                --log-stdout                                               |
                --log-file LOG_FILE                                        |
                --log-rotating-file FILENAME KBYTES COUNT                  |
                --log-timed-rotating-file FILENAME HOURS COUNT]

    optional arguments:
        -h, --help            show this help message and exit
        -c CONFIG, --config CONFIG
                              override default location of configuration file
        -f, --foreground      do not daemonize
        --pidfile PIDFILE     override default location of pid file
        --log-level {debug,info,warning,error,critical}
                              how verbosely to log
        --log-syslog [{auth,authpriv,cron,daemon,ftp,kern,
                       local0,local1,local2,local3,local4,local5,local6,local7,
                       lpr,mail,news,security,syslog,user,uucp}]
                              send logging to syslog
        --log-stderr          send logging to standard error
        --log-stdout          send logging to standard output
        --log-file LOG_FILE   send logging to a file, reopening if rotated away
        --log-rotating-file FILENAME KBYTES COUNT
                              send logging to rotating file
        --log-timed-rotating-file FILENAME HOURS COUNT
                              send logging to timed rotating file

6.4 rpkid

rpkid is the main RPKI engine, querying the IRDB for information. The queries request information about resources assigned to a particular child.

Configuration of rpkid is a two-step process. First, the rpki.conf configuration file is read to bootstrap the daemon to the point where it can speak using the left-right protocol. Second, it uses the left-right protocol to perform dynamic configuration. The second stage is handled by the rpkic command line tool or the web interface.

rpkid stores dynamic data in an SQL database, which must have been created for it, as explained in in the MySQL setup instructions.

rpkid's default configuration file is the system rpki.conf file. All of rpkid's options are in the "[rpkid]" section. A different configuration file may be used if rpkid is given with "-c filename" when the command is started.

By default, rpkid uses the syslog interface for logging. Options allow this to be changed to STDOUT, STDERR, or a named file.

The Step-By-Step Configuration File Reference has a complete description of the rpki.conf file.

Usage: 

    rpkid [-h] [-c CONFIG] [-f] [--pidfile PIDFILE] [--profile PROFILE]
               [--log-level {debug,info,warning,error,critical}]
               [--log-syslog [{auth,authpriv,cron,daemon,ftp,kern,
			       local0,local1,local2,local3,local4,
			       local5,local6,local7,
			       lpr,mail,news,security,syslog,user,uucp}]   |
                --log-stderr | --log-stdout | --log-file LOG_FILE          |
                --log-rotating-file FILENAME KBYTES COUNT                  |
                --log-timed-rotating-file FILENAME HOURS COUNT]

    optional arguments:
        -h, --help            show this help message and exit
        -c CONFIG, --config CONFIG
                              override default location of configuration file
        -f, --foreground      do not daemonize
        --pidfile PIDFILE     override default location of pid file
        --profile PROFILE     enable profiling, saving data to PROFILE
        --log-level {debug,info,warning,error,critical}
                              how verbosely to log
        --log-syslog [{auth,authpriv,cron,daemon,ftp,kern,
  		     local0,local1,local2,local3,local4, local5,local6,local7,
  		     lpr,mail,news,security,syslog,user,uucp}]
                              send logging to syslog
        --log-stderr          send logging to standard error
        --log-stdout          send logging to standard output
        --log-file LOG_FILE   send logging to a file, reopening if rotated away
        --log-rotating-file FILENAME KBYTES COUNT
                              send logging to rotating file
        --log-timed-rotating-file FILENAME HOURS COUNT
                              send logging to timed rotating file

7 Certification-Authority Utilities

The rpki.net Certification-Authority utilities provide supporting functionality and control for the CA RPKI environment. This includes such functions as configuring the required SQL databases, starting servers, and controlling the RPKI daemons.

Certification-Authority Utilities:

7.1 irbe_cli

irbe_cli is a IR back-end control program that provides command-line access to the rpkid and pubd CA daemons. There are commands specific to rpkid and pubd, and each of those commands takes its own set of options.

Usage: 

    irbe_cli [top-level options]  [command-options]

        # Top-level options:
        --config= --help --pem_out= --quiet --verbose
        
    rpkid commands:   
        parent --action= --tag= --self_handle= --parent_handle= --bsc_handle=
            --repository_handle= --peer_contact_uri= --sia_base=
            --sender_name= --recipient_name= --bpki_cms_cert= --bpki_cms_glue=
            --rekey --reissue --revoke --revoke_forgotten
            --clear_replay_protection
        repository --action= --tag= --self_handle= --repository_handle=
            --bsc_handle= --peer_contact_uri= --bpki_cert= --bpki_glue=
            --clear_replay_protection
        self --action= --tag= --self_handle= --crl_interval= --regen_margin=
            --bpki_cert= --bpki_glue= --rekey --reissue --revoke --run_now
            --publish_world_now --revoke_forgotten --clear_replay_protection
        list_received_resources --self_handle= --tag=
        child --action= --tag= --self_handle= --child_handle= --bsc_handle=
            --bpki_cert= --bpki_glue= --reissue --clear_replay_protection
        list_published_objects --self_handle= --tag= --child_handle=
        bsc --action= --tag= --self_handle= --bsc_handle= --key_type=
            --hash_alg= --key_length= --signing_cert= --signing_cert_crl=
            --generate_keypair
        
    pubd commands:
        ghostbuster --action= --tag= --client_handle= --uri=
        certificate --action= --tag= --client_handle= --uri=
        roa --action= --tag= --client_handle= --uri=
        manifest --action= --tag= --client_handle= --uri=
        client --action= --tag= --client_handle= --base_uri= --bpki_cert=
            --bpki_glue= --clear_replay_protection
        config --action= --tag= --bpki_crl=
        crl --action= --tag= --client_handle= --uri=

7.2 rpki-confgen

The rpki-confgen command creates a new rpki.conf configuration file.

The --read-xml argument is required, and it specifies an XML file from which the new configuration file will be populated. The XML file defines the sections and options to be used in the new file.

The Step-By-Step Configuration File Reference has a complete description of the rpki.conf file.

Usage: 

    rpki-confgen [-h] --read-xml FILE
                 [--write-xml FILE] [--write-wiki FILE] [--write-conf FILE]
                 [--set VARVAL] [--pwgen VAR] [--toc TRACNAV] [--autoconf]

    optional arguments:
        -h, --help         show this help message and exit
        --read-xml FILE    XML input file defining sections and options
        --write-xml FILE   XML file to write
        --write-wiki FILE  TracWiki file to write
        --write-conf FILE  rpki.conf configuration file to write
        --set VARVAL       variable setting in form "VAR=VAL"
        --pwgen VAR        set variable to generated password
        --toc TRACNAV      set TOC value to use with TracNav plugin
        --autoconf         configure [autoconf] section

7.3 rpki-manage

rpki-manage provides a command-line interface for initializing and controlling various aspects of the rpki.net system.

A large number of commands are available through rpki-manage. These commands are run individually by including one on the rpki-manage command line.

rpki-manage has an internal help system to provide information about its commands. It provides two levels of information:

  • Running "rpki-manage" "rpki-manage help provides a list of available commands. The command list is divided into five sections.
  • Running "rpki-manage help <command>" (e.g., "rpki-manage help diffsettings") will provide a description of the command and its arguments.

Usage: 

    rpki-manage command [options] [args]

    Options:
      -v VERBOSITY, --verbosity=VERBOSITY
                            Verbosity level; 0=minimal output, 1=normal output,
                            2=verbose output, 3=very verbose output
      --settings=SETTINGS   The Python path to a settings module, e.g.
                            "myproject.settings.main". If this isn't provided,
                            the DJANGO_SETTINGS_MODULE environment variable
                            will be used.
      --pythonpath=PYTHONPATH
                            A directory to add to the Python path, e.g.
                            "/home/djangoprojects/myproject".
      --traceback           Raise on exception
      --version             show program's version number and exit
      -h, --help            show this help message and exit

    commands:

        [auth]
            changepassword          change a user's password for django.contrib.auth
            createsuperuser         used to create a superuser

        [django]
            check                   checks configuration's compatibility with this version of Django
            cleanup                 clean out expired sessions (only with the database back-end at the moment)
            compilemessages         compiles .po files to .mo files for use with built-in gettext support
            createcachetable        creates the table needed to use the SQL cache backend
            dbshell                 runs the command-line client for a database
            diffsettings            displays differences between the current settings.py and Django's default settings
            dumpdata                output contents of the database as a fixture of the given format
            flush                   returns database to the state it was in immediately after syncdb was executed
            inspectdb               introspects database tables in the given database and outputs a Django model module
            loaddata                installs the named fixture(s) in the database
            makemessages            runs over a source tree of the current directory to find strings for translation
            runfcgi                 run project as a fastcgi application
            shell                   runs a Python interactive interpreter.
            sql                     prints the CREATE TABLE SQL statements for the given app name(s)
            sqlall                  prints the CREATE TABLE, custom SQL, and CREATE INDEX SQL statements for the given model module name(s)
            sqlclear                prints the DROP TABLE SQL statements for the given app name(s)
            sqlcustom               prints the custom table modifying SQL statements for the given app name(s)
            sqldropindexes          prints the DROP INDEX SQL statements for the given model module name(s)
            sqlflush                returns a list of the SQL statements required to return all tables in the database to the state they were in just after they were installed
            sqlindexes              prints the CREATE INDEX SQL statements for the given model module name(s)
            sqlinitialdata          renamed: see 'sqlcustom'
            sqlsequencereset        prints the SQL statements for resetting sequences for the given app name(s)
            startapp                creates a Django app directory structure for the given app name
            startproject            creates a Django project directory structure for the given project name
            validate                validates all installed models

        [sessions]
            clearsessions           clean out expired sessions (only with the database back-end at the moment)

        [south]
            convert_to_south        converts named application to use South
            datamigration           creates a new template data migration for the given app
            graphmigrations         outputs a GraphViz dot file of all migration dependencies
            migrate                 runs migrations for all apps
            migrationcheck          runs migrations for each app in turn, detecting missing depends_on values
            schemamigration         creates a new template schema migration for the given app
            startmigration          deprecated command
            syncdb                  create database tables for all apps in INSTALLED_APPS whose tables haven't already been created
            test                    discover and run tests in the specified modules or the current directory
            testserver              runs a development server with data from the given fixture(s)

        [staticfiles]
            collectstatic           collect static files in a single location
            findstatic              finds the absolute paths for the given static file(s)
            runserver               starts a light-weight Web server for development and also serves static files

7.4 rpki-sql-backup

rpki-sql-backup backs up the rpki.net SQL databases. It uses the rpki.conf configuration file to determine which databases must be backed up and the credentials to use for each.

rpki-sql-backup's default configuration file is the system rpki.conf file. A different configuration file may be used if rpki-sql-backup is given with "-c filename".

The Step-By-Step Configuration File Reference has a complete description of the rpki.conf file.

Usage: 

    rpki-sql-backup [-h] [-c CONFIG] [-o OUTPUT]
    
    optional arguments:
        -h, --help            show this help message and exit
        -c CONFIG, --config CONFIG
                              override default location of configuration file
        -o OUTPUT, --output OUTPUT
                              destination for SQL dump (default: stdout)

7.5 rpki-sql-setup

rpki-sql-setup automates the creation of the SQL databases used by the rpki.net CA tools. The databases are initialized according to the settings in the rpki.conf configuration file. The user will be prompted for the MySQL password as needed.

rpki-sql-setup's default configuration file is the system rpki.conf file. A different configuration file may be used if rpki-sql-setup is given with "-c filename".

The Step-By-Step Configuration File Reference has a complete description of the rpki.conf file.

Usage: 

    rpki-sql-setup [-h] [-c CONFIG] [-v] [--mysql-defaults MYSQL_DEFAULTS]
                          [--upgrade-scripts UPGRADE_SCRIPTS]
                          [--create | --drop   | --script-drop  |
                           --drop-and-create   | --fix-grants   |
                           --create-if-missing | --apply-upgrades]
    
    optional arguments:
        -h, --help            show this help message and exit
        -c CONFIG, --config CONFIG
                              specify alternate location for rpki.conf
        -v, --verbose         whistle while you work
        --mysql-defaults MYSQL_DEFAULTS
                              specify MySQL root access credentials via a
                              configuration file
        --upgrade-scripts UPGRADE_SCRIPTS
                              override default location of upgrade scripts
        --create              create databases and load schemas
        --drop                drop databases
        --script-drop         send SQL commands to drop databases to standard
                              output
        --drop-and-create     drop databases then recreate them and load
                              schemas
        --fix-grants          whack database access to match current
                              configuration file
        --create-if-missing   create databases and load schemas if they don't
                              exist already
        --apply-upgrades      apply upgrade scripts to existing databases

7.6 rpki-start-servers

This command starts the required CA daemons. It uses the rpki.conf file to determine which servers must be started.

rpki-start-servers's default configuration file is the system rpki.conf file. A different configuration file may be used if rpki-start-servers is given with "-c filename".

By default, rpki-start-servers uses the syslog interface for logging. Options allow this to be changed to STDOUT, STDERR, or a named file.

The Step-By-Step Configuration File Reference has a complete description of the rpki.conf file.

Usage: 

    usage: rpki-start-servers [-h] [-c CONFIG] [--log-directory LOG_DIRECTORY]
                      [--log-backup-count LOG_BACKUP_COUNT]
                      [--log-level {debug,info,warning,error,critical}]
                      [--log-file |
                       --log-rotating-file-kbytes LOG_ROTATING_FILE_KBYTES |
                       --log-rotating-file-hours LOG_ROTATING_FILE_HOURS |
                       --log-syslog [{auth,authpriv,cron,daemon,ftp,kern,
                                      local0,local1,local2,local3,local4,local5,local6,local7,
				      lpr,mail,news,security,syslog,user,uucp}]]
    
    optional arguments:
      -h, --help            show this help message and exit
      -c CONFIG, --config CONFIG
                            override default location of configuration file
      --log-directory LOG_DIRECTORY
                            where to write write log files when not using syslog
      --log-backup-count LOG_BACKUP_COUNT
                            keep this many old log files when rotating
      --log-level {debug,info,warning,error,critical}
                            how verbosely to log
      --log-file            log to files, reopening if rotated away
      --log-rotating-file-kbytes LOG_ROTATING_FILE_KBYTES
                            log to files, rotating after this many kbytes
      --log-rotating-file-hours LOG_ROTATING_FILE_HOURS
                            log to files, rotating after this many hours
      --log-syslog [{auth,authpriv,cron,daemon,ftp,kern,
		     local0,local1,local2,local3,local4,local5,local6,local7,
		     lpr,mail,news,security,syslog,user,uucp}]
                            log syslog

7.7 rpkic

rpkic is the command-line interface for the rpki.net CA daemons. It allows the CA daemons to be configured and controlled away from the web interface.

A large number of commands are available through rpkic. These commands may be run individually by including one on the rpkic command line. rpkic may be run as its own environment if it isn't given a command. In this case, the commands can be entered at the rpkic prompt.

rpkic has an internal help system to provide information about its commands. It provides three levels of information:

  • Running "rpkic --help" provides a list of commands and a very brief explanation of each command.
  • Running "help" within the rpkic environment gives a list of the available commands.
  • Adding a command name at the end (e.g., "help load_asns") will provide a description of the command and its arguments.

Usage: 

    rpkic [-h] [-c CONFIG] [-i IDENTITY] [--profile PROFILE]  [command [arguments]]
    
    optional arguments:
        -h, --help          show this help message and exit
        -c CONFIG, --config CONFIG
                            override default location of configuration file
        -i IDENTITY, --identity IDENTITY, --handle IDENTITY
                            set initial entity handle
        --profile PROFILE   enable profiling, saving data to PROFILE

    commands:

        select_identity     select an identity handle for use with later commands
        initialize          initialize an RPKI installation. DEPRECATED
        create_identity     create a new resource-holding entity
        initialize_server_bpki
                            initialize server BPKI portion of an RPKI
                            installation
        update_bpki         update BPKI certificates. Assumes an existing RPKI
                            installation
        configure_child     configure a new child of this RPKI entity
        delete_child        delete a child of this RPKI entity
        configure_parent    configure a new parent of this RPKI entity
        delete_parent       delete a parent of this RPKI entity
        configure_root      configure the current resource holding identity as a
                            root
        delete_root         delete local RPKI root as parent of the current
                            entity
        configure_publication_client
                            configure publication server to know about a new
                            client
        delete_publication_client
                            delete a publication client of this RPKI entity
        configure_repository
                            configure a publication repository for this RPKI
                            entity
        delete_repository   delete a repository of this RPKI entity
        delete_identity     delete the current RPKI identity (rpkid 
                            object)
        renew_child         update validity period for one child entity
        renew_all_children  update validity period for all child entities
        load_prefixes       load prefixes into IRDB from CSV file
        show_child_resources
                            show resources assigned to children
        show_roa_requests   show ROA requests
        show_ghostbuster_requests
                            show Ghostbuster requests
        show_received_resources
                            show resources received by this entity from its
                            parent(s)
        show_published_objects
                            show published objects
        show_bpki           show this entity's BPKI objects
        load_asns           load ASNs into IRDB from CSV file
        load_roa_requests   load ROA requests into IRDB from CSV file
        load_ghostbuster_requests
                            load Ghostbuster requests into IRDB from file
        add_router_certificate_request
                            load router certificate request(s) into IRDB from
                            XML file
        delete_router_certificate_request
                            delete a router certificate request from the IRDB
        show_router_certificate_requests
                            show this entity's router certificate requests
        synchronize         whack daemons to match IRDB
        force_publication   whack rpkid to force (re)publication of everything
        force_reissue       whack rpkid to force reissuance of everything
        up_down_rekey       initiate a "rekey" operation
        up_down_revoke      initiate a "revoke" operation
        revoke_forgotten    initiate a "revoke_forgotten" operation
        clear_all_sql_cms_replay_protection
                            tell rpkid and pubd to clear replay protection
        version             show current software version number
        list_self_handles   list all  handles in this rpkid instance

7.8 rpkigui-apache-conf-gen

rpkigui-apache-conf-gen creates and installs a configuration file for using Apache httpd to drive the RPKI web interface under WSGI. This command may also be used to uninstall the httpd configuration file.

Usage: 

    rpkigui-apache-conf-gen [-h] [-v] [--apache-version APACHE_VERSION]
                            [--freebsd | --debian | --ubuntu | --redhat | --macosx | --guess]
                            [-i | -r | -P]

    optional arguments:
        -h, --help            show this help message and exit
        -v, --verbose         whistle while you work
        --apache-version APACHE_VERSION
                              Apache version (default 22)
        --freebsd             configure for FreeBSD
        --debian              configure for Debian
        --ubuntu              configure for Ubuntu
        --redhat, --fedora, --centos
                              configure for Redhat/Fedora/CentOS
        --macosx, --darwin    configure for Mac OS X (Darwin)
        --guess               guess which platform configuration to use
        -i, --install         install configuration
        -r, --remove, --deinstall, --uninstall
                              remove configuration
        -P, --purge           remove configuration with extreme prejudice

7.9 rpkigui-check-expire

rpkigui-check-expired generates a report detailing all RPKI and BPKI certificates which are due for impending expiration. If no resource handles are specified, a report about all resource handles hosted by the local rpkid will be generated.

Usage: 

    rpkigui-check-expired [ -nV ] [ handle1 handle2... ]

    options:
        -h, --help            show this help message and exit
        -V, --version         display script version
        -f ADDRESS, --from=ADDRESS
                              specify the return email address for notifications
        -t DAYS, --expire-time=DAYS
                              specify the number of days in the future to check
        -l LOG_LEVEL, --level=LOG_LEVEL
                              set logging level
                              [default: WARNING]

7.10 rpkigui-import-routes

rpkigui-import-routes imports the IPv4/6 BGP table dumps from routeviews.org into the rpki.net Web Portal database. If the input file is a bzip2-compressed file, it will be decompressed automatically.

Usage: 

    rpkigui-import-routes [options] [PATH]

    options:
        -h, --help            show this help message and exit
        -t TYPE, --type=TYPE  specify the input file type (auto, text, mrt)
                              [default: auto]
        -l LOG_LEVEL, --level=LOG_LEVEL
                              set logging level
                              [default: ERROR]
        -u PROG, --bunzip2=PROG
                              specify bunzip2 program to use
        -b PROG, --bgpdump=PROG
                              specify path to bgpdump binary
        -j JITTER, --jitter=JITTER
                              specify upper bound of startup delay, in seconds
                              [default: 0]
        --lockfile=LOCKFILE   set name of lock file; empty string disables locking
                              [default: /tmp/rpkigui-import-routes.lock]
        --timeout=TIMEOUT     specify timeout for download and import, in seconds
                              [default: 5400]

7.11 rpkigui-query-routes

rpkigui-query-routes queries the rpki.net web portal database for routes covering a specified prefix. The prefix to check is passed as an argument to rpki.net. The validity and covering ROAs for each route are displayed.

Usage: 

    rpkigui-query-routes [options] PREFIX

    options:
        --version   show program's version number and exit
        -h, --help  show this help message and exit

7.12 rpkigui-rcynic

The rpkigui-rcynic command loads the contents of the rcynic.xml file into the rpki.gui.cacheview database. By default, rpkigui-rcynic will load the /var/rcynic/data/rcynic.xml file. This may be modified with the --file option.

The --root option specifies the chroot() directory used for the rcynic jail environment. If this option is not given, then rpkigui-rcynic will use the /var/rcynic/data directory.

Usage: 

    rpkigui-rcynic [options]
    
    options:
        -h, --help            show this help message and exit
        -l LOG_LEVEL, --level=LOG_LEVEL
                              specify the logging level [default: ERROR]
        -f LOGFILE, --file=LOGFILE
                              specify the rcynic XML file to parse
        -r DIR, --root=DIR    specify the chroot directory for the rcynic jail
                              [default: /var/rcynic/data]

8 Certification-Authority Test Tools

The rpki.net software includes two separate test programs for Certification-Authority tools. smoketest runs a test scenario and stops. yamltest provides a test environment (under scripted control) and runs indefinitely.

The test tools are only present in the source tree. Neither is installed during the rpki.net installation process.

Unlike the configuration files used by the other programs, these test programs read test descriptions written in the YAML serialization language. Each test script describes a hierarchy of RPKI entities, including hosting relationships and resource assignments, in a relatively compact form. The CA test programs use these descriptions to generate a set of configuration files, populate the back-end database, and drive the test.

See http://www.yaml.org/ for more information on YAML. See the test configuration language for details on the content of these YAML files.

Certification-Authority Test Tools:

8.1 smoketest

smoketest is a test harness to set up and run a collection of rpkid and irdbd instances under scripted control. smoketest runs a particular test scenario through a series of changes and shuts down.

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 and yamltest use the same YAML test description language.

smoketest is designed to support running a fairly wide set of test configurations as canned scripts. It is not expected to need new control code to be written. The intent is to make it possible to write meaningful regression tests.

Usage: 

    smoketest [-h] [-c CONFIG] [--profile] [-y] yaml_file

    positional arguments:
        yaml_file             YAML description of test network

    optional arguments:
        -h, --help            show this help message and exit
        -c CONFIG, --config CONFIG
                              configuration file for various
			      implementation-specific items
        --profile             enable profiling
        -y                    ignored; present only for backwards
                              compatability

8.2 yamltest

yamltest is a test harness to set up and run a collection of rpkid and irdbd instances under scripted control. yamltest 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. After reading the YAML configuration file, yamltest generates .csv and .conf files, runs daemons, and waits for one of them to exit.

smoketest and yamltest use the same YAML test description language.

At present, 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 of configuration files, which may be useful as examples.

Usage: 

    yamltest [-h] [-c CONFIG] [-f] [-k] [-p PIDFILE] [--skip_config]
                  [--stop_after_config] [--synchronize] [--profile]
                  [--store-router-private-keys]
                  yaml_file

    positional arguments:
        yaml_file             YAML description of test network

    optional arguments:
        -h, --help            show this help message and exit
        -c CONFIG, --config CONFIG
                              configuration file
        -f, --flat_publication
                              disable hierarchical publication
        -k, --keep_going      keep going until all subprocesses exit
        -p PIDFILE, --pidfile PIDFILE
                              save pid to this file
        --skip_config         skip over configuration phase
        --stop_after_config   stop after configuration phase
        --synchronize         synchronize IRDB with daemons
        --profile             enable profiling
        --store-router-private-keys
                              write generate router private keys to disk

Sections of this document are derived or taken verbatim from Dragon Research Lab's RPKI Tools Manual.

Copyright (c) 2015, Parsons, Inc
All rights reserved