path: root/rpkid/doc/Configuration

Configuration Guide

   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.

   The default name for the shared configuration file is myrpki.conf.

[myrpki]

   The [myrpki] section of myrpki.conf contains all the parameters that
   you really need to configure.

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

# Names of various files and directories.  Don't change these without
# a good reason.

roa_csv                         = roas.csv
prefix_csv                      = prefixes.csv
asn_csv                         = asns.csv
xml_filename                    = myrpki.xml
bpki_resources_directory        = bpki/resources
bpki_servers_directory          = bpki/servers

   The myrpki tool requires filenames for several input data files, the
   "business PKI" databases used to secure CMS and TLS communications, and
   the XML intermediate format that it uses. Rather than hardwiring the
   names into the code, they're configured here. You can change the names
   if you must, but the defaults should be fine in most cases.

# Whether you want to run your own copy of rpkid (and irdbd).  You
# want this on unless somebody else is hosting rpkid service for you.

run_rpkid                       = true

# DNS hostname and server port numbers for rpkid and irdbd, if you're
# running them.  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

   If you're hosting RPKI service for others, or are self-hosting, you
   want this on. If somebody else is running rpkid on your behalf and
   you're just shipping them your myrpki.xml file, you can turn this off.

   If you're running rpkid at all, 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 myrpki tool 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 myrpki.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. In this specific case, 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.

# Name of OpenSSL binary.  You might need to change this if you have
# no system copy installed, or if the system copy doesn't support CMS.
# The copy of openssl built by this package should suffice.

openssl                         = openssl

   The myrpki tool uses the openssl command line tool for most of its BPKI
   operations, for two reasons:

     * To avoid duplicating CA-management functionality already provided
       by the command line tool, and

     * To ease portability of the myrpki tool, so that a "hosted" resource
       holder can use it without needing to install entire toolkit.

   The myrpki tool's use of OpenSSL does not require exotic features like
   RFC 3779 support, but it does require a version of the tool recent
   enough to support CMS and the -ss_cert argument to the ca command.
   Depending on the platform on which you are running this code, you may
   or may not have a system copy of the openssl tool installed that meets
   these criteria; if not, the openssl binary built when you compile the
   toolkit will suffice. This parameter allows you to tell myrpki where to
   find the binary, if necessary; the default just uses the system search
   path.

   Warning:
          At this point we should have subpages showing configuration
          details for the various daemons, for people who really want or
          need to know. We should also have a configuration example for
          rsyncd.conf.

   Once you've finished with configuration, the next thing you should read
   is the Operation Guide.
     __________________________________________________________________


    Generated on Thu Apr 15 15:51:08 2010 for RPKI Engine by  doxygen
    1.6.3