diff options
Diffstat (limited to 'rpkid/doc/Configuration')
| -rw-r--r-- | rpkid/doc/Configuration | 273 |
1 files changed, 0 insertions, 273 deletions
diff --git a/rpkid/doc/Configuration b/rpkid/doc/Configuration deleted file mode 100644 index 3fd16f8e..00000000 --- a/rpkid/doc/Configuration +++ /dev/null @@ -1,273 +0,0 @@ -RPKI Engine  1.0 - -* MainÂ_Page -* RelatedÂ_Pages -* Packages -* Classes -* Files -* [Search ] - -* RPKI_Engine_Reference_Manual - -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. - - rpki.conf - -The default name for the shared configuration file is rpki.conf. 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. - - [myrpki] - -The [myrpki] section of rpki.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. - - # Directory where we look for various files. Default is the current - # directory, you might want to change this. - - configuration_directory = . - - # Names of various files and directories. Don't change these without - # a good reason. - - roa_csv = ${myrpki::configuration_directory}/roas.csv - prefix_csv = ${myrpki::configuration_directory}/ - prefixes.csv - asn_csv = ${myrpki::configuration_directory}/asns.csv - xml_filename = ${myrpki::configuration_directory}/ - myrpki.xml - bpki_resources_directory = ${myrpki::configuration_directory}/bpki/ - resources - bpki_servers_directory = ${myrpki::configuration_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 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. 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 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 - -* 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 -MySQL_setup_instructions. |