Secure Routing -- Protect Your Infrastructure

Configuration File Reference

1 Introduction
2 rpki.conf -- RPKI Engine Common Configuration Options
2.1 [autoconf] section
2.2 [irdbd] section
2.3 [myrpki] section
2.4 [pubd] section
2.5 [rootd] section
2.6 [rpkid] section
2.7 [web_portal] section
2.8 Debugging Options
2.9 CMS Message Options
3 rcynic.conf Configuration Options
4 rsyncd.conf Configuration Options
5 Full Table of Contents

1 Introduction

This document is a reference for the configuration files used by the rpki.net software. Program-specific files and general configuration files are described here.

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

2 rpki.conf -- RPKI Engine Common Configuration Options

The rpki.conf file is a centralized configuration file, containing the configuration options used by most of the rpki.net software.

This file is divided into several named sections and each section has a number of key/value entries.

The name of each configuration section is enclosed in square brackets. Each entry is comprised of the entry name, an equals sign, and the entry value.

For example, the [myrpki] section has entries that define the hostname and port that will be used by the irdbd server daemon. These entries look like this:

    [myrpki]
        irdbd_server_host = localhost
        irdbd_server_port = 4403

This section of the configuration-file reference is divided by the sections defined for the file itself. The sections are ordered alphabetically, not by importance of the section. Each section's entries are also ordered alphabetically by the entry's field name, again not based on the entry's importance.

In this document each configuration entry has a brief description and the default value, where there is a default. Some of the default values refer to an entry in another section. These are given in this manner:

    start_rpkid = ${myrpki::run_rpkid}

The following table lists the defined sections:

	[autoconf]	[rootd]
	[irdbd]	[rpkid]
	[myrpki]	[web_portal]
	[pubd]

In addition, there are options specific for debugging and CMS messages.

The [myrpki] section contains all the parameters that most installations are likely to need to configure. The name [myrpki] is historical and may change in the future.

2.1 [autoconf] section

The rpki-confgen --autoconf command records the current autoconf settings in this section so that other options can refer to them. The section name "autoconf" is special; do not change it.

2.1.1 bindir

Usually /usr/bin or /usr/local/bin.

No default value.

2.1.2 datarootdir

Usually /usr/share or /usr/local/share.

No default value.

2.1.3 sbindir

Usually /usr/sbin or /usr/local/sbin.

No default value.

2.1.4 sysconfdir

Usually /etc or /usr/local/etc.

No default value.

2.2 [irdbd] section

The irdbd command's default configuration file is the system's rpki.conf file. Since irdbd is part of the back-end system, it has direct access to the back-end's SQL database and is able to pull its own BPKI configuration directly from the database. This results in a little less configuration than is required for the other daemons.

All irdbd options are in the "[irdbd]" section.

2.2.1 server-host

Host on which irdbd should listen for HTTP service requests.

    server-host = ${myrpki::irdbd_server_host}

2.2.2 server-port

Port on which irdbd should listen for HTTP service requests.

    server-port = ${myrpki::irdbd_server_port}

2.2.3 sql-database

SQL database name for irdbd.

    sql-database = ${myrpki::irdbd_sql_database}

2.2.4 sql-password

SQL database password for irdbd's database. The default is to use the shared SQL database password, but this option allows a separate password to be used.

    sql-password = ${myrpki::irdbd_sql_password}

2.2.5 sql-username

SQL database username for irdbd's database. The default is to use the shared SQL database username, but this option allows a separate username to be used.

    sql-username = ${myrpki::irdbd_sql_username}

2.2.6 startup-message

String to log on startup, useful when debugging a collection of irdbd instances at once.

No default value.

2.3 [myrpki] section

The "[myrpki]" section contains parameters used by most of the rpki.net software.

The name "myrpki" is historical and may change in the future.

2.3.1 bpki_servers_directory

Directory for BPKI files generated by rpkic and used by rpkid and pubd. You will not normally need to change this.

    bpki_servers_directory = ${autoconf::datarootdir}/rpki

2.3.2 handle

Every resource-holding or server-operating entity needs a "handle", which is just an identifier by which the entity calls itself. Handles do not need to be globally unique, but they should be chosen with the thought of debugging operational problems. It is best to use a handle parents and children will recognize.

The handle option in the [myrpki] section specifies the default handle for this installation. Previous versions of the CA tools required each hosted entity to have a separate configuration file, each with its own handle setting. The current code allows the handle to be selected at runtime in both the GUI and command line user interface tools, so the handle setting here is just a default when a handle isn't set explicitly. In the long run, this option may go away entirely, but for now this must be set.

A handle is an identifier. Valid characters are ASCII letters, digits, hyphens, and underscores. No whitespace, non-ASCII characters, or other punctuation are allowed.

No default value.

2.3.3 irdbd_server_host

DNS hostname for irdbd, or "localhost". This should be "localhost" unless you really know what you are doing.

    irdbd_server_host = localhost

2.3.4 irdbd_server_port

Server port number for irdbd. This can be any legal TCP port number not being used for something else.

    irdbd_server_port = 4403

2.3.5 irdbd_sql_database

SQL database for irdbd's database.

    irdbd_sql_database = irdbd

2.3.6 irdbd_sql_password

SQL database password for irdbd's database. The default is to use the shared SQL database password, but this option allows a separate password to be used.

    irdbd_sql_password = ${myrpki::shared_sql_password}

2.3.7 irdbd_sql_username

SQL database username for irdbd's database. The default is to use the shared SQL database username, but this option allows a separate username to be used.

    irdbd_sql_username = ${myrpki::shared_sql_username}

2.3.8 pubd_contact_info

Contact information to include in offers of repository service. This only matters when running pubd. This should be a human-readable string, perhaps containing an email address or URL.

No default value.

2.3.9 pubd_server_host

DNS hostname for pubd, if it is being run. This must resolve to a publicly reachable address.

No default value.

2.3.10 pubd_server_port

Server port number for pubd. This can be any legal TCP port number that not being using for something else.

    pubd_server_port = 4402

2.3.11 pubd_sql_database

SQL database name for pubd's database.

    pubd_sql_database = pubd

2.3.12 pubd_sql_password

SQL database password for pubd's database. The default is to use the shared SQL database password, but this option allows a separate password to be used.

    pubd_sql_password = ${myrpki::shared_sql_password}

2.3.13 pubd_sql_username

SQL database username for pubd's database. The default is to use the shared SQL database username, but this option allows a separate username to be used.

    pubd_sql_username = ${myrpki::shared_sql_username}

2.3.14 publication_base_directory

Root of local directory tree where pubd should write published data. This must be configured, and the configuration should match the directory where you point rsyncd.

Neither pubd nor rsyncd cares where this directory is. The important thing is that the rsync URIs in generated certificates match the published objects so that relying parties can find and verify rpkid's published outputs.

    publication_base_directory = ${autoconf::datarootdir}/rpki/publication

2.3.15 publication_root_cert_directory

Root of local directory tree where rootd should write published data. This is just like publication_base_directory, but rootd needs its own directory in which to write one certificate, one CRL, and one manifest.

Neither rootd nor rsyncd cares where this directory is. The important thing is that the rsync URIs in generated certificates match the published objects so that relying parties can find and verify rootd's published outputs.

    publication_root_cert_directory = ${myrpki::publication_base_directory}.root

2.3.16 publication_root_module

rsyncd module name corresponding to publication_root_cert_directory. This has to match the module configured in rsyncd.conf. This should not be changed unless there is a specific need to change it.

    publication_root_module = root

2.3.17 publication_rsync_module

rsyncd module name corresponding to publication_base_directory. This has to match the module configured in rsyncd.conf. This should not be changed unless there is a specific need to change it.

    publication_rsync_module = rpki

2.3.18 publication_rsync_server

Hostname and optional port number for rsync URIs. In most cases this should just be the same value as pubd_server_host.

    publication_rsync_server = ${myrpki::pubd_server_host}

2.3.19 rootd_server_host

DNS hostname for rootd. This should be localhost unless you really know what you are doing.

    rootd_server_host = localhost

2.3.20 rootd_server_port

Server port number for rootd. This can be any legal TCP port number that not being using for something else.

    rootd_server_port = 4401

2.3.21 rpkid_server_host

DNS hostname for rpkid. In most cases, this must resolve to a publicly reachable address, as your RPKI children will need to contact your rpkid at this address.

No default value.

2.3.22 rpkid_server_port

Server port number for rpkid. This can be any legal TCP port number that not being using for something else.

    rpkid_server_port = 4404

2.3.23 rpkid_sql_database

SQL database name for rpkid's database.

    rpkid_sql_database = rpkid

2.3.24 rpkid_sql_password

SQL database password for rpkid's database. The default is to use the shared SQL database password, but this option allows a separate password to be used.

    rpkid_sql_password = ${myrpki::shared_sql_password}

2.3.25 rpkid_sql_username

SQL database username for rpkid's database. The default is to use the shared SQL database username, but this option allows a separate username to be used.

    rpkid_sql_username = ${myrpki::shared_sql_username}

2.3.26 run_pubd

Indicates whether a local instance of pubd should be run.

If your parent offer publication service, it is strongly recommended that you use their service. This recommendation may be overridden for reliability reasons or if you're certifying private address space or private Autonomous System Numbers.

The out-of-band setup protocol will attempt to negotiate publication service for you with whatever publication service your parent is using, if it can and if you let it.

    run_pubd = yes

2.3.27 run_rootd

Indicates whether a local instance of rootd should be run.

It is strongly recommended that you no enable this unless you really know what you're doing.

    run_rootd = no

2.3.28 run_rpkid

Indicates whether a local instance of rpkid (and irdbd) should be run.

It is strongly recommended that you no enable this unless you really know what you're doing. This recommendation may be overridden if you are doing something unusual like running a pubd-only installation.

    run_rpkid = yes

2.3.29 shared_sql_password

Shared SQL database password. This will be used for all the components that are not given a unique database password, such as in the irdbd_sql_password field.

The installation process generates a random value for this option, so ordinarily you should have no need to change this option.

No default value.

2.3.30 shared_sql_username

Shared SQL database username. This will be used for all the components that are not given a unique database username, such as in the irdbd_sql_username field.

    shared_sql_username = rpki

2.3.31 start_irdbd

irdbd startup control. This should usually have the same value as run_rpkid.

The only case where you would want to change this is when you are running the back-end code on a different machine from one or more of the daemons, in which case you need finer control over which daemons to start on which machines. In such cases, run_rpkid controls whether the back-end code is managing rpkid, while start_irdbd controls whether rpki-start-servers attempts to start irdbd on this machine.

    start_irdbd = ${myrpki::run_rpkid}

2.3.32 start_pubd

pubd startup control. This should usually have the same value as run_pubd.

The only case where you would want to change this is when you are running the back-end code on a different machine from one or more of the daemons, in which case you need finer control over which daemons to start on which machines. In such cases, run_pubd controls whether the back-end code is doing things to manage pubd, while start_pubd controls whether rpki-start-servers attempts to start pubd on this machine.

    start_pubd = ${myrpki::run_pubd}

2.3.33 start_rootd

rootd startup control. This should usually have the same value as run_rootd.

The only case where you would want to change this is when you are running the back-end code on a different machine from one or more of the daemons, in which case you need finer control over which daemons to start on which machines. In such cases, run_rootd controls whether the back-end code is managing rootd, while start_rootd controls whether rpki-start-servers attempts to start rootd on this machine.

    start_rootd = ${myrpki::run_rootd}

2.3.34 start_rpkid

rpkid startup control. This should usually have the same value as run_rpkid.

The only case where you would want to change this is when you are running the back-end code on a different machine from one or more of the daemons, in which case you need finer control over which daemons to start on which machines. In such cases, run_rpkid controls whether the back-end code is managing rpkid, while start_rpkid controls whether rpki-start-servers attempts to start rpkid on this machine.

    start_rpkid = ${myrpki::run_rpkid}

2.4 [pubd] section

The pubd command's default configuration file is the system's rpki.conf file.

All pubd options are in the "[pubd]" section.

2.4.1 bpki-ta

The BPKI trust anchor. BPKI certificates and keys may be either DER or PEM format. All BPKI certificate verification within pubd traces back to this trust anchor. Don't change this unless you really know what you are doing.

    bpki-ta = ${myrpki::bpki_servers_directory}/ca.cer

2.4.2 irbe-cert

The back-end control client's BPKI EE certificate. BPKI certificates and keys may be either DER or PEM format. Don't change this unless you really know what you are doing.

    irbe-cert = ${myrpki::bpki_servers_directory}/irbe.cer

2.4.3 pubd-cert

pubd's own BPKI EE certificate. This BPKI certificate may be either DER or PEM format. Don't change this unless you really know what you are doing.

    pubd-cert = ${myrpki::bpki_servers_directory}/pubd.cer

2.4.4 pubd-key

The private key corresponding to pubd's own BPKI EE certificate. This BPKI certificate may be either DER or PEM format. Don't change this unless you really know what you are doing.

    pubd-key = ${myrpki::bpki_servers_directory}/pubd.key

2.4.5 publication-base

Root of the directory tree where pubd should write published data. This must be configured, and the configuration should match the directory where you point rsyncd.

    publication-base = ${myrpki::publication_base_directory}

2.4.6 server-host

Host on which pubd should listen for HTTP service requests.

    server-host = ${myrpki::pubd_server_host}

2.4.7 server-port

Port on which pubd should listen for HTTP service requests.

    server-port = ${myrpki::pubd_server_port}

2.4.8 sql-database

SQL database for pubd's database.

    sql-database = ${myrpki::pubd_sql_database}

2.4.9 sql-password

SQL database password for pubd's database. The default is to use the shared SQL database password, but this option allows a separate password to be used.

    sql-password = ${myrpki::pubd_sql_password}

2.4.10 sql-username

SQL database username for pubd's database. The default is to use the shared SQL database username, but this option allows a separate username to be used.

    sql-username = ${myrpki::pubd_sql_username}

2.5 [rootd] section

The rootd command's default configuration file is the system's rpki.conf file.

All rootd options are in the "[rootd]" section.

As has been detailed elsewhere, it is highly unlikely that you will need to run rootd. The situations in which you should run rootd are that you are IANA, you are certifying private address space, or you are an RIR which refuses to accept IANA as the root of the public address hierarchy. Do not enable it unless you are certain that you need to do so.

2.5.1 bpki-ta

The BPKI trust anchor for the rootd. All BPKI certificate verification within rootd traces back to this trust anchor. Don't change this unless you really know what you are doing.

    bpki-ta = ${myrpki::bpki_servers_directory}/ca.cer

2.5.2 child-bpki-cert

BPKI certificate for rootd's single up-down-protocol child. This certificate may be in either DER or PEM format. Don't change this unless you really know what you are doing.

    child-bpki-cert = ${myrpki::bpki_servers_directory}/child.cer

2.5.3 rootd-bpki-cert

BPKI EE certificate for rootd. This certificate may be in either DER or PEM format. Don't change this unless you really know what you are doing.

    rootd-bpki-cert = ${myrpki::bpki_servers_directory}/rootd.cer

2.5.4 rootd-bpki-crl

BPKI CRL for rootd. Don't change this unless you really know what you are doing.

    rootd-bpki-crl = ${myrpki::bpki_servers_directory}/ca.crl

2.5.5 rootd-bpki-key

Private key corresponding to rootd's own BPKI EE certificate. This key may be in either DER or PEM format. Don't change this unless you really know what you are doing.

    rootd-bpki-key = ${myrpki::bpki_servers_directory}/rootd.key

2.5.6 rpki-base-uri

rsync URI corresponding to the directory containing rootd's outputs.

    rpki-base-uri = rsync://${myrpki::publication_rsync_server}/${myrpki::publication_rsync_module}/

2.5.7 rpki-class-name

The up-down protocol class name for the RPKI certificate rootd issues to its single child.

    rpki-class-name = ${myrpki::handle}

2.5.8 rpki-root-cert

Filename (as opposed to rsync URI) of rootd's root RPKI certificate. This certificate may be in either DER or PEM format.

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

2.5.9 rpki-root-cert-uri

rsync URI for rootd's self-signed root RPKI certificate. This certificate may be in either DER or PEM format.

    rpki-root-cert-uri = rsync://${myrpki::publication_rsync_server}/${myrpki::publication_root_module}/root.cer

2.5.10 rpki-root-crl

Filename (relative to rootd-base-uri and rpki-root-dir) of the CRL for rootd's root RPKI certificate.

    rpki-root-crl = root.crl

2.5.11 rpki-root-dir

Output directory for rootd. This needs to match the pubd command's configuration.

    rpki-root-dir = ${myrpki::publication_base_directory}

2.5.12 rpki-root-key

Private key corresponding to rootd's root RPKI certificate. This key may be in either DER or PEM format.

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

2.5.13 rpki-root-manifest

Filename (relative to rootd-base-uri and rpki-root-dir) of the manifest for rootd's root RPKI certificate.

    rpki-root-manifest = root.mft

2.5.14 rpki-subject-cert

Filename (relative to rootd-base-uri and rpki-root-dir) of the single RPKI certificate issued by rootd. This certificate may be in either DER or PEM format.

    rpki-subject-cert = ${myrpki::handle}.cer

2.5.15 rpki-subject-lifetime

Lifetime of the single RPKI certificate issued by rootd.

    rpki-subject-lifetime = 30d

2.5.16 rpki-subject-pkcs10

Location of a copy of the PKCS #10 request that rootd get from its single child.

    rpki-subject-pkcs10 = ${myrpki::bpki_servers_directory}/rootd.subject.pkcs10

2.5.17 server-host

Server host on which rootd should listen.

    server-host = ${myrpki::rootd_server_host}

2.5.18 server-port

Server port on which rootd should listen.

    server-port = ${myrpki::rootd_server_port}

2.6 [rpkid] section

The rpkid command's default configuration file is the system's rpki.conf file.

All rpkid options are in the "[rpkid]" section.

2.6.1 bpki-ta

The BPKI trust anchor for the rpkid. All BPKI certificate verification within rpkid traces back to this trust anchor. Don't change this unless you really know what you are doing.

    bpki-ta = ${myrpki::bpki_servers_directory}/ca.cer

2.6.2 irbe-cert

The back-end control client's BPKI EE certificate. This certificate may be in either DER or PEM format. Don't change this unless you really know what you are doing.

    irbe-cert = ${myrpki::bpki_servers_directory}/irbe.cer

2.6.3 irdb-cert

The irdbd client's BPKI EE certificate. This certificate may be in either DER or PEM format. Don't change this unless you really know what you are doing.

    irdb-cert = ${myrpki::bpki_servers_directory}/irdbd.cer

2.6.4 irdb-url

HTTP service URL for contacting irdbd. If irdbd is running on the same machine as rpkid, this should be a loopback URL, since nobody but rpkid needs to talk to irdbd.

    irdb-url = http://${myrpki::irdbd_server_host}:${myrpki::irdbd_server_port}/

2.6.5 rpkid-cert

rpkid's own BPKI EE certificate. This BPKI certificate may be either DER or PEM format. Don't change this unless you really know what you are doing.

    rpkid-cert = ${myrpki::bpki_servers_directory}/rpkid.cer

2.6.6 rpkid-key

The private key corresponding to rpkid's own BPKI EE certificate. This BPKI certificate may be either DER or PEM format. Don't change this unless you really know what you are doing. This certificate may be in either DER or PEM format. This key may be in either DER or PEM format.

    rpkid-key = ${myrpki::bpki_servers_directory}/rpkid.key

2.6.7 server-host

Host on which rpkid should listen for HTTP service requests.

    server-host = ${myrpki::rpkid_server_host}

2.6.8 server-port

Port on which rpkid should listen for HTTP service requests.

    server-port = ${myrpki::rpkid_server_port}

2.6.9 sql-database

SQL database name for rpkid.

    sql-database = ${myrpki::rpkid_sql_database}

2.6.10 sql-password

SQL database password for rpkid's database. The default is to use the shared SQL database password, but this option allows a separate password to be used.

    sql-password = ${myrpki::rpkid_sql_password}

2.6.11 sql-username

SQL database username for rpkid's database. The default is to use the shared SQL database username, but this option allows a separate username to be used.

    sql-username = ${myrpki::rpkid_sql_username}

2.7 [web_portal] section

Django provides a GUI for the rpki.net software. Site-specific Django options are kept in this section of the system's rpki.conf so that there's no need to directly edit the settings.py file.

All Django-specific options are in the "[web_portal]" section.

2.7.1 allowed-hosts

Name of the virtual host that runs the Django GUI, if this is not the same as the system hostname. Django's security code wants to know the name of the virtual host on which Django is running. Django will fail when it thinks it's running on a disallowed host.

This option must be set if you get an error like "Invalid HTTP_HOST header (you may need to set ALLOWED_HOSTS)".

No default value.

2.7.2 secret-key

Site-specific secret key for Django.

No default value.

2.7.3 sql-database

SQL database name for the web portal.

    sql-database = ${myrpki::irdbd_sql_database}

2.7.4 sql-password

SQL database password for the web portal's database. The default is to use the shared SQL database password, but this option allows a separate password to be used.

    sql-password = ${myrpki::irdbd_sql_password}

2.7.5 sql-username

SQL database username for the web portal's database. The default is to use the shared SQL database username, but this option allows a separate username to be used.

    sql-username = ${myrpki::irdbd_sql_username}

2.8 Debugging Options

There is a set of flags that control debugging code. Most of these are boolean flags, which can be set to "true" or "false". If not specified, default values will be chosen (generally false). These are probably of interest only to the developers, but they are described below.

2.8.1 debug_cms_certs

Enable verbose logging about CMS certificates.

2.8.2 debug_http

Enable verbose HTTP debug logging.

2.8.3 enable_ipv6_clients

Enable IPv6 HTTP client code.

2.8.4 enable_ipv6_servers

Enable IPv6 HTTP server code. This option is set on by default, since listening for IPv6 connections is usually harmless.

2.8.5 enable_tracebacks

Enable Python tracebacks in logs.

2.8.6 gc_debug

Enable detailed garbage collector debugging.

2.8.7 sql_debug

Enable verbose logging about SQL operations.

2.8.8 timer_debug

Enable verbose logging of timer system.

2.8.9 use_adns

Use asynchronous DNS code. Enabling this will raise an exception if the dnspython toolkit is not installed.

Asynchronous DNS is an experimental feature intended to allow higher throughput on busy servers; if you don't know why you need it, you probably don't.

2.8.10 want_persistent_client

Enable HTTP 1.1 persistence on the client side.

2.8.11 want_persistent_server

Enable HTTP 1.1 persistence on the server side.

2.9 CMS Message Options

There are also a few options which allow you to save CMS messages for audit or debugging. The save format is a simple MIME encoding in a Maildir-format mailbox. The current options are very crude; at some point finer-grain controls may be provided.

2.9.1 dump_inbound_cms

Dump verbatim copies of received CMS messages to the specified mailbox.

2.9.2 dump_outbound_cms

Dump verbatim copies of sent CMS messages to the specified mailbox.

3 rcynic.conf Configuration Options

The rcynic.conf file controls the operation of the rcynic command. rcynic must have a configuration file in order to do anything useful, as the configuration file is the only way to list trust anchors.

All rcynic options are in the [rcynic] section in the rcynic.conf file. The section has a number of key/value entries. Each entry is comprised of the entry name, an equals sign, and the entry value.

For example, the [rcynic] section has entries that define the location of authenticated objects and the "jitter" time that will be used rcynic. These entries look like this:

    [rcynic]
        authenticated = /var/rcynic/data/auth-objs
        jitter = 900

This section of the configuration-file reference is describes the entries for the rcynic.conf file. The entries are ordered alphabetically by the entry's field name, not based on the entry's importance.

In this document each configuration entry has a brief description, the acceptable types of value for the field and the default value. Where a field has a default value, that will also be given.

rcynic uses the OpenSSL libcrypto configuration file mechanism. In addition to the configuration options listed in this section, all libcrypto configuration options are available. These are documented elsewhere.

3.1 allow-crl-digest-mismatch

Flag that allows processing to continue on a publication point whose manifest lists a different digest value for the CRL than the digest of the CRL currently held. Don't change this unless you really know what you are doing.

This value may be true or false. The default value is true.

3.2 allow-digest-mismatch

Flag that allows the use of otherwise valid objects which are listed in the manifest with a different digest value. Don't change this unless you really know what you are doing.

This value may be true or false. The default value is true.

3.3 allow-non-self-signed-trust-anchor

Flag that allows rcynic to attempt to work around OpenSSL's strong preference for self-signed trust anchors.

This option is experimental. Do not consider enabling this option unless you are intimately familiar with both X.509 and the internals of OpenSSL's X509_verify_cert() function and really know what you are doing.

This value may be true or false. The default value is false.

3.4 allow-object-not-in-manifest

Flag that allows the use of otherwise valid objects which are not listed in the manifest. This is not supposed to happen, but is probably harmless.

Enabling this option increases the chance that rcynic will attempt to validate data which a CA removed from the manifest but did not completely remove and revoke from the repository. One result of enabling the allow-object-not-in-manifest option will be that the logs are likely to be much noisier.

This value may be true or false. The default value is false.

3.5 allow-stale-crl

Flag that allows the use of CRLs which are past their nextUpdate timestamp. This is usually harmless, but since there are attack scenarios in which this is the first warning of trouble, this behavior is configurable.

This value may be true or false. The default value is true.

3.6 allow-stale-manifest

Flag that allows the use of manifests which are past their nextUpdate timestamp. This is probably harmless, but since it may be an early warning of problems, this behavior is configurable.

This value may be true or false. The default value is true.

3.7 authenticated

Path to the output directory where rcynic should place objects it has validated.

The default value is /var/rcynic/data/authenticated.

3.8 jitter

Startup jitter interval, specified in number of seconds. rcynic will pick a random number within the range from zero to this value, and will delay for that many seconds on startup. This spreads the load from large numbers of rcynic clients all running under cron with synchronized clocks, in particular to avoid overstressing the global RPKI rsync servers at midnight UTC.

This configuration option may be specified as the -j command-line option.

The default value is 600.

3.9 lockfile

Name of lock file. If this option is empty then no lock will be used. If rcynic is run under cron, this parameter should be used to set a lockfile so that successive instances of rcynic don't stomp on each other. If rcynic is run via rcynic-cron, this option need not be set as rcynic-cron maintains its own lock.

The default value is to use an empty value.

3.10 log-level

Level of log messages to use.

This configuration option may be specified with the -l command-line option. Command line setting overrides config file setting.

The logging levels are given using rcynic-specific names. These are mapped to syslog logging levels, though not one-to-one. The table below shows the rcynic-specific log levels mapped to syslog levels.

rcynic Log Level	syslog Log Level	Description
log_sys_err	LOG_ERR	error from OS or library
log_usage_err	LOG_ERR	bad usage (local error)
log_data_err	LOG_NOTICE	bad data
log_telemetry	LOG_INFO	normal progress messages
log_verbose	LOG_INFO	additional information
log_debug	LOG_DEBUG	only useful when debugging

The default log level is log_usage_err.

3.11 max-parallel-fetches

Upper limit on the number of instances of rsync that rcynic is allowed to run at once. Used properly, this can speed up synchronization considerably when fetching from repositories built with sub-optimal tree layouts or when dealing with unreachable repositories. Used improperly, this option can generate excessive load on repositories, cause synchronization to be interrupted by firewalls, and cause other timing issues. Adjust this value with caution.

As of this writing, values in the range 2-4 are reasonably safe. Values above 10 have been known to cause problems.

rcynic can't detect all of the possible problems created by excessive values of this parameter. If rcynic's report shows both successful retrievals and skipped retrievals from the same repository host, it's a good hint that something is wrong. An excessive value for this option is a good first guess as to the cause.

The default value is 1.

3.12 prune

Flag allowing clean-up of old files corresponding to URIs that rcynic did not see during this run. rcynic invokes rsync with the --delete option to clean up old objects from collections that rcynic revisits. However, if a URI changes so that rcynic never visits the old collection again, old files will remain in the local mirror indefinitely unless this option is enabled.

Pruning only occurs when run-rsync is true. When the run-rsync option is false, pruning is not performed regardless of the setting of the prune option option.

This value may be true or false. The default value is true.

3.13 require-crl-in-manifest

Flag for rejecting publication point if the manifest does not list the CRL that covers the manifest EE certificate.

This value may be true or false. The default value is false.

3.14 rsync-early

Flag for forcing rsync to run even when it has a valid manifest for a particular publication point and its nextUpdate time has not yet passed.

This is an experimental feature, and currently defaults to true, which is the old behavior. (running rsync regardless of whether we have a valid cached manifest). This default may change once we have more experience with rcynic's behavior when run with this option set to false.

Skipping the rsync fetch when we already have a valid cached manifest can significantly reduce the total number of rsync connections needed, and this will significantly reduce the load that each validator places on the authoritative publication servers. As with any caching scheme, however, there are some potential problems involved with not fetching the latest data, and we don't yet have enough experience with this option to know how this will work in practice. This is why this option is still considered experimental.

This value may be true or false. The default value is true.

3.15 rsync-program

Path to the rsync program. This is likely to be available through the PATH environment variable, but it would be best to set this option explicitly to ensure that it is set properly.

The default value is /usr/bin/rsync.

3.16 rsync-timeout

The length of time (in seconds) that rsync may run before it is assumed to be hung, and therefore should be terminated. rsync will not be timed out if this option is set to zero. This timeout should be fairly long in order to avoid terminating rsync connections prematurely. This option is present to help defend against denial of service attacks from too-long running connections.

The default value is 300 (five minutes.)

3.17 run-rsync

Flag indicating whether rsync should be executed.

Generally, this option should not be changed except when building complex topologies where rcynic running on one set of machines acts as an aggregator for another set of validators. A large ISP might want to build such a topology so that it can have a local validation cache in each POP while minimizing load on the global repository system and maintaining some degree of internal consistency between POPs. In such cases, one might want the rcynic instances in the POPs to validate data fetched from the aggregators via an external process, without the POP rcynic instances attempting to fetch anything themselves.

This value may be true or false. The default value is true.

3.18 syslog-facility

syslog facility to use.

The default value is local0.

3.19 syslog-priority-xyz

Provides a mapping between rcynic's priority classes and the associated syslog priority names.

The xyz portion of the option name will vary as needed for the rcynic priority classes.

Default priority mappings:

	rcynic Priority Class	syslog Priority Name
	syslog-priority-log_sys_err	err
	syslog-priority-log_usage_err	err
	syslog-priority-log_data_err	notice
	syslog-priority-log_telemetry	info
	syslog-priority-log_verbose	info
	syslog-priority-log_debug	debug

3.20 trust-anchor

Specify one RPKI trust anchor, represented as a local file containing an X.509 certificate in DER format. The value of this option is the pathname of the file.

This option has no default value.

3.21 trust-anchor-directory

Specify a directory containing a set of trust anchors and trust anchor locators. Trust anchors in this directory must have filenames ending in ".cer". Trust anchor locators in this directory must have names ending in ".tal". Any other files will be ignored.

This option is an alternative to using the trust-anchor and trust-anchor-locator options.

This option has no default value.

3.22 trust-anchor-locator

Specify one RPKI trust anchor locator, represented as a local file in the format specified in RFC-6490. The value of this option is the pathname of the file.

This is a simple text format containing an rsync URI and the RSA public key of the X.509 object specified by the URI. The first line of the file is the URI and the remainder is the public key in Base64-encoded DER format.

This option has no default value.

3.23 unauthenticated

Path to a directory where rcynic should store unauthenticated data retrieved via rsync.

rcynic should to preserve and reuse this directory across runs to minimize the network traffic necessary to bring the repository mirror up to date.

The default value is /var/rcynic/data/unauthenticated.

3.24 use-links

Flag indicating how rcynic should transfer objects from the unauthenticated directory to the authenticated directory. If the option value is true, then hard links will be used; otherwise, objects will be copied.

Using links is slightly more fragile, since anything that modifies on the unauthenticated file also modifies on the authenticated file. However, links are a bit faster and reduce the number of inodes consumed by a large data collection. Currently, copying is the default behavior, but this may change in the future.

This value may be true or false. The default value is false.

3.25 use-stderr

Flag indicating if log entries should be sent to stderr.

This option is the same as the -e command-line option. The command-line option overrides the configuration file setting.

This value may be true or false. The default value is false. However, if neither use-syslog nor use-stderr are set, then log output will be sent to stderr.

3.26 use-syslog

Flag indicating if log entries should be sent to syslog.

This option is the same as the -s command-line option. The command-line option overrides the configuration file setting.

This value may be true or false. The default value is false.

3.27 xml-summary

Enable output of a per-host summary at the end of an rcynic run. The output will be written to the specified file in XML format.

This value is the filename to which the XML summary should be written. If the given value is "-", then rcynic will send the XML summary to standard output. If no value is given, then the XML summary will not be written.

This value is a filename. The default value is empty, thus no XML summary will be written.

4 rsyncd.conf Configuration Options

If the pubd daemon is to be run then the rsyncd daemon must also be run. The rsyncd.conf file must be configured to allow for use with rpki.net. The rsyncd configuration must match the pubd configuration in rpki.conf so that relying parties can find the RPKI objects managed by pubd.

The rsyncd.conf file may contain two sections specific to rpki.net: [rpki] and [root]. The [root] section is only relevant if the rootd daemon is being run. The entries in these sections are the same entries defined for regular rsyncd.conf files. These entries are described in depth in the rsyncd.conf and rsync manual pages; the information is not duplicated here.

The expected entries for the [rpki] and [root] sections are:

        comment             = RPKI publication
        path                = /some/where/publication
        read only           = yes
        transfer logging    = yes
        use chroot          = no

If rsyncd is already being used for other purposes, then a somewhat more complex configuration may be required. These fields are not described in this section, other than some requirements for the path field that are given below.

4.1 path Requirements

This field must match the publication_base_directory field in the rpki.conf file.

5 Full Table of Contents


1 Introduction

2 rpki.conf -- RPKI Engine Common Configuration Options
2.1 [autoconf] section 2.1.1 bindir 2.1.2 datarootdir 2.1.3 sbindir 2.1.4 sysconfdir 2.2 [irdbd] section 2.2.1 server-host 2.2.2 server-port 2.2.3 sql-database 2.2.4 sql-password 2.2.5 sql-username 2.2.6 startup-message 2.3 [myrpki] section 2.3.1 bpki_servers_directory 2.3.2 handle 2.3.3 irdbd_server_host 2.3.4 irdbd_server_port 2.3.5 irdbd_sql_database 2.3.6 irdbd_sql_password 2.3.7 irdbd_sql_username 2.3.8 pubd_contact_info 2.3.9 pubd_server_host 2.3.10 pubd_server_port 2.3.11 pubd_sql_database 2.3.12 pubd_sql_password 2.3.13 pubd_sql_username 2.3.14 publication_base_directory 2.3.15 publication_root_cert_directory 2.3.16 publication_root_module 2.3.17 publication_rsync_module 2.3.18 publication_rsync_server 2.3.19 rootd_server_host 2.3.20 rootd_server_port 2.3.21 rpkid_server_host 2.3.22 rpkid_server_port 2.3.23 rpkid_sql_database 2.3.24 rpkid_sql_password 2.3.25 rpkid_sql_username 2.3.26 run_pubd 2.3.27 run_rootd 2.3.28 run_rpkid 2.3.29 shared_sql_password 2.3.30 shared_sql_username 2.3.31 start_irdbd 2.3.32 start_pubd 2.3.33 start_rootd 2.3.34 start_rpkid	2.4 [pubd] section 2.4.1 bpki-ta 2.4.2 irbe-cert 2.4.3 pubd-cert 2.4.4 pubd-key 2.4.5 publication-base 2.4.6 server-host 2.4.7 server-port 2.4.8 sql-database 2.4.9 sql-password 2.4.10 sql-username 2.5 [rootd] section 2.5.1 bpki-ta 2.5.2 child-bpki-cert 2.5.3 rootd-bpki-cert 2.5.4 rootd-bpki-crl 2.5.5 rootd-bpki-key 2.5.6 rpki-base-uri 2.5.7 rpki-class-name 2.5.8 rpki-root-cert 2.5.9 rpki-root-cert-uri 2.5.10 rpki-root-crl 2.5.11 rpki-root-dir 2.5.12 rpki-root-key 2.5.13 rpki-root-manifest 2.5.14 rpki-subject-cert 2.5.15 rpki-subject-lifetime 2.5.16 rpki-subject-pkcs10 2.5.17 server-host 2.5.18 server-port	2.6 [rpkid] section 2.6.1 bpki-ta 2.6.2 irbe-cert 2.6.3 irdb-cert 2.6.4 irdb-url 2.6.5 rpkid-cert 2.6.6 rpkid-key 2.6.7 server-host 2.6.8 server-port 2.6.9 sql-database 2.6.10 sql-password 2.6.11 sql-username 2.7 [web_portal] section 2.7.1 allowed-hosts 2.7.2 secret-key 2.7.3 sql-database 2.7.4 sql-password 2.7.5 sql-username 2.8 Debugging Options 2.8.1 debug_cms_certs 2.8.2 debug_http 2.8.3 enable_ipv6_clients 2.8.4 enable_ipv6_servers 2.8.5 enable_tracebacks 2.8.6 gc_debug 2.8.7 sql_debug 2.8.8 timer_debug 2.8.9 use_adns 2.8.10 want_persistent_client 2.8.11 want_persistent_server 2.9 CMS Message Options 2.9.1 dump_inbound_cms 2.9.2 dump_outbound_cms

3 rcynic.conf Configuration Options
3.1 allow-crl-digest-mismatch 3.2 allow-digest-mismatch 3.3 allow-non-self-signed-trust-anchor 3.4 allow-object-not-in-manifest 3.5 allow-stale-crl 3.6 allow-stale-manifest 3.7 authenticated 3.8 jitter 3.9 lockfile	3.10 log-level 3.11 max-parallel-fetches 3.12 prune 3.13 require-crl-in-manifest 3.14 rsync-early 3.15 rsync-program 3.16 rsync-timeout 3.17 run-rsync 3.18 syslog-facility	3.19 syslog-priority-xyz 3.20 trust-anchor 3.21 trust-anchor-directory 3.22 trust-anchor-locator 3.23 unauthenticated 3.24 use-links 3.25 use-stderr 3.26 use-syslog 3.27 xml-summary

4 rsyncd.conf Configuration Options
4.1 path Requirements

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

Routing Security Step-by-Step Guide

Table of Contents

1 Introduction

2 rpki.conf -- RPKI Engine Common Configuration Options

2.1 [autoconf] section

2.1.1 bindir

2.1.2 datarootdir

2.1.3 sbindir

2.1.4 sysconfdir

2.2 [irdbd] section

2.2.1 server-host

2.2.2 server-port

2.2.3 sql-database

2.2.4 sql-password

2.2.5 sql-username

2.2.6 startup-message

2.3 [myrpki] section

2.3.1 bpki_servers_directory

2.3.2 handle

2.3.3 irdbd_server_host

2.3.4 irdbd_server_port

2.3.5 irdbd_sql_database

2.3.6 irdbd_sql_password

2.3.7 irdbd_sql_username

2.3.8 pubd_contact_info

2.3.9 pubd_server_host

2.3.10 pubd_server_port

2.3.11 pubd_sql_database

2.3.12 pubd_sql_password

2.3.13 pubd_sql_username

2.3.14 publication_base_directory

2.3.15 publication_root_cert_directory

2.3.16 publication_root_module

2.3.17 publication_rsync_module

2.3.18 publication_rsync_server

2.3.19 rootd_server_host

2.3.20 rootd_server_port

2.3.21 rpkid_server_host

2.3.22 rpkid_server_port

2.3.23 rpkid_sql_database

2.3.24 rpkid_sql_password

2.3.25 rpkid_sql_username

2.3.26 run_pubd

2.3.27 run_rootd

2.3.28 run_rpkid

2.3.29 shared_sql_password

2.3.30 shared_sql_username

2.3.31 start_irdbd

2.3.32 start_pubd

2.3.33 start_rootd

2.3.34 start_rpkid

2.4 [pubd] section

2.4.1 bpki-ta

2.4.2 irbe-cert

2.4.3 pubd-cert

2.4.4 pubd-key

2.4.5 publication-base

2.4.6 server-host

2.4.7 server-port

2.4.8 sql-database

2.4.9 sql-password

2.4.10 sql-username

2.5 [rootd] section

2.5.1 bpki-ta

2.5.2 child-bpki-cert

2.5.3 rootd-bpki-cert

2.5.4 rootd-bpki-crl

2.5.5 rootd-bpki-key

2.5.6 rpki-base-uri

2.5.7 rpki-class-name

2.5.8 rpki-root-cert

2.5.9 rpki-root-cert-uri

2.5.10 rpki-root-crl

2.5.11 rpki-root-dir

2.5.12 rpki-root-key

2.5.13 rpki-root-manifest

2.5.14 rpki-subject-cert

2.5.15 rpki-subject-lifetime

2.5.16 rpki-subject-pkcs10

2.5.17 server-host