diff options
Diffstat (limited to 'doc/doc.RPKI.CA.Configuration')
| -rw-r--r-- | doc/doc.RPKI.CA.Configuration | 241 |
1 files changed, 241 insertions, 0 deletions
diff --git a/doc/doc.RPKI.CA.Configuration b/doc/doc.RPKI.CA.Configuration new file mode 100644 index 00000000..24c6d17b --- /dev/null +++ b/doc/doc.RPKI.CA.Configuration @@ -0,0 +1,241 @@ +****** 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. |