path: root/doc/doc.RPKI.CA.Configuration

****** Configuring the RPKI CA tools ******

This section describes the configuration file syntax and settings.

Each of the programs that make up the RPKI tookit can potentially take its own
configuration file, but for most uses this is unnecessarily complicated. The
recommended approach is to use a single configuration file, and to put all of
the parameters that a normal user might need to change into a single section of
that configuration file, then reference these common settings from the program-
specific sections of the configuration file via macro expansion. The
configuration file parser supports a limited version of the macro facility used
in OpenSSL's configuration parser. An expression such as

  foo = ${bar::baz}

sets foo to the value of the baz variable from section bar. The section name
ENV is special: it refers to environment variables.

***** rpki.conf *****

The default name for the shared configuration file is rpki.conf. The location
of the system-wide rpki.conf file is selected by ./configure during
installation; the default location is /usr/local/etc, unless you use the --
sysconfdir option to ./configure, in which case the default location is
whatever directory you gave ./configure as the argument to this option.

You can override the build-time default filename at runtime by setting the
RPKI_CONF environment variable to the name of the configuration file you want
to use. Most of the programs also take a command-line option specifying the
name of the configuration file; if both the command line option and the
environment variable are set, the command line option wins.

Unless you really know what you're doing, you should start by copying the
rpki.conf from the rpkid/examples directory and modifying it, as the sample
configuration file already includes all the additional settings necessary to
use the simplified configuration.

We really should have a configuration wizard script which leads you through the
process of creating a basic rpki.conf file, but we haven't written it yet.
Someday Real Soon Now.

  [myrpki]

The [myrpki] section of rpki.conf contains all the parameters that you really
need to configure. The name myrpki] is historical and really should become
[rpkic] or something like that.

  # Handle naming hosted resource-holding entity (<self/>) represented
  # by this myrpki instance.  Syntax is an identifier (ASCII letters,
  # digits, hyphen, underscore -- no whitespace, non-ASCII characters,
  # or other punctuation).  You need to set this.

  handle                          = Me

Every resource-holding or server-operating entity needs a "handle", which is
just an identifier by which the entity calls itself. Handles do not need to be
globally unique, but should be chosen with an eye towards debugging operational
problems: it's best if you use a handle that your parents and children will
recognize as being you.

Previous versions of the CA tools required a separate configuration file, each
with its own handle setting, for each hosted entity. The current code allows
the current handle to be selected at runtime in both the GUI and command line
user interface tools, so the handle setting here is just the default when you
don't set one explictly.

  # Directory for BPKI files generated by rpkic and used by rpkid and pubd.
  # Default is where we expect autoconf to decide that our data files
  # belong, you might want or need to change this.   In the long term
  # this should be handled by a setup wizard.

  bpki_servers_directory          = /usr/local/share/rpki

You shouldn't need to change this unless you used the --datarootdir option to
tell ./configure; if you did, you'll need to adjust the setting of
bpki_servers_directory to match whatever you told ./configure.

  # DNS hostname and server port numbers for rpkid and irdbd.  rpkid's
  # server host has to be a publicly reachable name to be useful;
  # irdbd's server host should always be localhost unless you really
  # know what you are doing.  Port numbers can be any legal TCP port
  # number that you're not using for something else.

  rpkid_server_host               = rpkid.example.org
  rpkid_server_port               = 4404
  irdbd_server_host               = localhost
  irdbd_server_port               = 4403

You'll need to set at least the rpkid_server_host parameter here. You may be
able to use the default port numbers, or may need to pick different ones.
Unless you plan to run irdbd on a different machine from rpkid, you should
leave irdbd_server_host alone.

  # Whether you want to run your own copy of pubd.  In general, it's
  # best to use your parent's pubd if you can, to reduce the overall
  # number of publication sites that relying parties need to check, so
  # don't enable this unless you have a good reason.

  run_pubd                        = false

  # DNS hostname and server port number for pubd, if you're running it.
  # Hostname has to be a publicly reachable name to be useful, port can
  # be any legal TCP port number that you're not using for something
  # else.

  pubd_server_host                = pubd.example.org
  pubd_server_port                = 4402

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

  pubd_contact_info               = repo-man@rpki.example.org

The out of band setup protocol will attempt to negotiate publication service
for you with whatever publication service your parent is using, if you let it,
so in most cases you should not need to run pubd unless you need to issue
certificates for private IP address space or private Autononmous System
Numbers.

If you do run pubd, you will need to set pubd_server_host. You may also need to
set pubd_server_port, and you should provide something helpful as contact
information in pubd_contact_info if you plan to offer publication service to
your RPKI children, so that grandchildren (or descendents even further down the
tree) who receive referrals to your service will know how to contact you.

  # Whether you want to run your very own copy of rootd.  Don't enable
  # this unless you really know what you're doing.

  run_rootd                       = false

  # Server port number for rootd, if you're running it.  This can be any
  # legal TCP port number that you're not using for something else.

  rootd_server_port               = 4401

You shouldn't run rootd unless you're the root of an RPKI tree. Who gets to be
the root of the public RPKI tree is a political issue outside the scope of this
document. For everybody else, the only reason for running rootd (other than
test purposes) would be to support certification of private IP addresses and
ASNs. The core tools can do this without any problem, but the simplified
configuration mechanism does not (yet) make this easy to do.

  # Root of local directory tree where pubd (and rootd, sigh) should
  # write out published data.  You need to configure this, and the
  # configuration should match up with the directory where you point
  # rsyncd.  Neither pubd nor rsyncd much cares -where- you tell them to
  # put this stuff, the important thing is that the rsync:// URIs in
  # generated certificates match up with the published objects so that
  # relying parties can find and verify rpkid's published outputs.

  publication_base_directory      = publication/

  # rsyncd module name corresponding to publication_base_directory.
  # This has to match the module you configured into rsyncd.conf.
  # Leave this alone unless you have some need to change it.

  publication_rsync_module        = rpki

  # 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}

These parameters control the mapping between the rsync URIs presented by rsyncd
and the local filesystem on the machine where pubd and rsyncd run. Any changes
here must also be reflected as changes in rsyncd.conf. In most cases you should
not change the value of publication_rsync_module from the default; since pubd
can't (and should not) rewrite rsyncd.conf, it's best to use a static rsync
module name here and let pubd do its work underneath that name. In most cases
publication_rsync_server should be the same as publication_rsync_server, which
is what the macro invocation in the default setting does.
publication_base_directory, like other pathnames in rpki.conf, can be either a
relative or absolute pathname; if relative, it's interpreted with respect to
the directory in which the programs in question were started. It's probably
better to use an absolute pathname, since this pathname must also appear in
rsyncd.conf.

  # SQL configuration.  You can ignore this if you're not running any of
  # the daemons yourself.

  # If you're comfortable with having all of the databases use the same
  # MySQL username and password, set those values here.  It's ok to
  # leave the default username alone, but you should use a locally
  # generated password either here or in the individual settings below.

  shared_sql_username             = rpki
  shared_sql_password             = fnord

  # If you want different usernames and passwords for the separate SQL
  # databases, enter those settings here; the shared_sql_* settings are
  # only referenced here, so you can remove them entirely if you're
  # setting everything in this block.

  rpkid_sql_database              = rpkid
  rpkid_sql_username              = ${myrpki::shared_sql_username}
  rpkid_sql_password              = ${myrpki::shared_sql_password}

  irdbd_sql_database              = irdbd
  irdbd_sql_username              = ${myrpki::shared_sql_username}
  irdbd_sql_password              = ${myrpki::shared_sql_password}

  pubd_sql_database               = pubd
  pubd_sql_username               = ${myrpki::shared_sql_username}
  pubd_sql_password               = ${myrpki::shared_sql_password}

These settings control how rpkid, irdbd, and pubd talk to the MySQL server. At
minimum, each daemon needs its own database; in the simplest configuration, the
username and password can be shared, which is what the macro references in the
default configuration does. If for some reason you need to set different
usernames and passwords for different daemons, you can do so by changing the
daemon-specific variables.

***** rsyncd.conf *****

If you're running pubd, you'll also need to run rsyncd. Your rsyncd
configuration will need to match your pubd configuration in order for relying
parties to find the RPKI objects managed by pubd.

There's a sample rsync configuration file in rpkid/examples/rsyncd.conf, but
you may need to do something more complicated if you are already running rsyncd
for other purposes. See the rsync(1) and rsyncd.conf(5) manual pages for more
details.

***** Other configuration files and options *****

In most cases the simplified configuration in the [myrpki] section of rpki.conf
should suffice, but in case you need to tinker, here are details on the the
rest of the configuration options. In most cases the default name of the
configuration file for a program is the name of the program followed by .conf,
and the section name is also named for the program, so that you can combine
sections into a single configuration file as shown with rpki.conf.

* Common configuration options
* rpkid configuration
* irdbd configuration
* pubd configuration
* rootd configuration

Once you've finished with configuration, the next thing you should read is the
MySQL setup instructions.