diff options
Diffstat (limited to 'rpkid/doc/Configuration')
| -rw-r--r-- | rpkid/doc/Configuration | 458 |
1 files changed, 236 insertions, 222 deletions
diff --git a/rpkid/doc/Configuration b/rpkid/doc/Configuration index 2b803f87..1fdccb60 100644 --- a/rpkid/doc/Configuration +++ b/rpkid/doc/Configuration @@ -1,263 +1,277 @@ -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 +****** Configuration Guide ****** -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. +This section describes the configuration file syntax and settings. -myrpki.conf +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 - The default name for the shared configuration file is myrpki.conf. -[myrpki] + foo = ${bar::baz} - The [myrpki] section of myrpki.conf contains all the parameters that - you really need to configure. +sets foo to the value of the baz variable from section bar. The section name +ENV is special: it refers to environment variables. -# 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 +***** myrpki.conf ***** - 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 default name for the shared configuration file is myrpki.conf. - 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. + [myrpki] -run_rpkid = true +The [myrpki] section of myrpki.conf contains all the parameters that you really +need to configure. -# 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. + # 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. -# SQL configuration. You can ignore this if you're not running any of -# the daemons yourself. + handle = Me -# 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. +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. -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. + # Names of various files and directories. Don't change these without + # a good reason. -rpkid_sql_database = rpkid -rpkid_sql_username = ${myrpki::shared_sql_username} -rpkid_sql_password = ${myrpki::shared_sql_password} + 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 -irdbd_sql_database = irdbd -irdbd_sql_username = ${myrpki::shared_sql_username} -irdbd_sql_password = ${myrpki::shared_sql_password} +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. -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. + # 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. -# 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. + run_rpkid = true -openssl = openssl + # 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. - The myrpki tool uses the openssl command line tool for most of its BPKI - operations, for two reasons: + rpkid_server_host = rpkid.example.org + rpkid_server_port = 4404 + irdbd_server_host = localhost + irdbd_server_port = 4403 - * To avoid duplicating CA-management functionality already provided - by the command line tool, and +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. - * To ease portability of the myrpki tool, so that a "hosted" resource - holder can use it without needing to install entire toolkit. +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. - 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. -Other configuration files and options + # 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. - In most cases the simplified configuration in the [myrpki] section of - myrpki.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 myrpki.conf. + run_pubd = false - * Common configuration options + # 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. - * rpkid configuration + pubd_server_host = pubd.example.org + pubd_server_port = 4402 - * irdbd configuration + # 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 configuration + pubd_contact_info = repo-man@rpki.example.org - * rootd configuration +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. + + +***** Other configuration files and options ***** + +In most cases the simplified configuration in the [myrpki] section of +myrpki.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 myrpki.conf. + + +* Common_configuration_options + + +* rpkid_configuration + + +* irdbd_configuration + + +* pubd_configuration + + +* rootd_configuration + + +* configuration_of_the_smoketest_test_harness + + +* test_description_language_for_the_smoketest_test_harness + +Once you've finished with configuration, the next thing you should read is the +Operation_Guide. - * configuration of the smoketest test harness - * test description language for the smoketest test harness - Once you've finished with configuration, the next thing you should read - is the Operation Guide. - __________________________________________________________________ - Generated on Fri Apr 16 17:28:16 2010 for RPKI Engine by doxygen - 1.6.3 |