****** 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 may change in the future. # Handle naming hosted resource-holding entity () 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. # 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 You probably don't need to change this. # 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. # Startup control. These all default to the values of the # corresponding run_* options, to keep things simple. The only case # where you would want to change these 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_*" controls whether # the back-end code is doing things to manage the daemon in question, # while "start_*" controls whether rpki-start-servers attempts to # start the daemon in question. start_rpkid = ${myrpki::run_rpkid} start_irdbd = ${myrpki::run_rpkid} start_pubd = ${myrpki::run_pubd} start_rootd = ${myrpki::run_rootd} You don't need to change these unless for some reason you need to run rpkid, pubd, or both on different machines from your back end code. In such cases, you can use these options to control which daemons start on which hosts, and to tell the back end code (rpkic and the GUI) that they're responsible for talking to rpkid and pubd even though those daemons are running on other hosts. The main reason why you might want to do this would be cases where you might want to run rpkid and pubd in a DMZ while keeping all of the back end code behind a firewall. # 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. Here's a sample rsyncd.conf file: pid file = /var/run/rsyncd.pid uid = nobody gid = nobody [rpki] use chroot = no read only = yes transfer logging = yes path = /some/where/publication comment = RPKI publication You may need to adapt this to your system. In particular, you will need to set the path option to match the directory you named as publication_base_directory in rpki.conf. 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 ***** Next steps ***** Once you've finished with configuration, the next thing you should read is the MySQL setup instructions. ***** Running rpkid or pubd on a different server ***** The default configuration runs rpkid, pubd (if enabled) and the back end code all on the same server. For many purposes, this is fine, but in some cases you might want to split these functions up among different servers. As noted briefly above, there are two separate sets of rpki.conf options which control the necessary behavior: the run_* options and the start_* options. The latter are usually tied to the former, but you can set them separately, and they control slightly different things: the run_* options control whether the back end code attempts to manage the servers in question, while the start_* flags control whether the startup scripts should start the servers in question. Here's a guideline to how to set up the servers on different machines. For purposes of this description we'll assume that you're running both rpkid and pubd, and that you want rpkid and pubd each on their own server, separate from the back end code. We'll call these servers rpkid.example.org, pubd.example.org, and backend.example.org. Most of the configuration is the same as in the normal case, but there are a few extra steps. The following supplements but does not replace the normal instructions. WARNING: These setup directions have not (yet) been tested extensively. * Create rpki.conf as usual on backend.example.org, but pay particular attention to the settings of rpkid_server_host, irbe_server_host, and pubd_server_host: these should name rpkid.example.org, backend.example.org, and pubd.example.org, respectively. * This example assumes that you're running pubd, so make sure that both run_rpkid and run_pubd are enabled in rpki.conf. * Copy the rpki.conf to the other machines, and customize each copy to that machine's role: o start_rpkid should be enabled on rpkid.example.org and disabled on the others. o start_pubd should be enabled on pubd.example.org and disabled on the others. o start_irdbd should be enabled on backend.example.org and disabled on the others. * Make sure that you set up SQL databases on all three servers; the rpki-sql- setup script should do the right thing in each case based on the setting of the start_* options. * Run "rpkic initialize" on the back end host. This will create the BPKI and write out all of the necessary keys and certificates. * "rpkic initialize" should have created the BPKI files (.cer, .key, and .crl files for the several servers). Copy the .cer and .crl files to the pubd and rpkid hosts, along with the appropriate private key: rpkid.example.org should get a copy of the rpkid.key file but not the pubd.key file, while pubd.example.org should get a copy of the pubd.key file but not the rpkid.key file. * Run rpki-start-servers on each of the three hosts when it's time to start the servers. * Do the usual setup dance, but keep in mind that the the back end controlling all of these servers lives on backend.example.org, so that's where you issue the rpkic or GUI commands to manage them. rpkic and the GUI both know how to talk to rpkid and pubd over the network, so managing them remotely is fine.