From 14a9628f0552d3818cd58fb085e7544cdbb3b5eb Mon Sep 17 00:00:00 2001 From: Rob Austein Date: Wed, 3 Aug 2016 18:27:49 +0000 Subject: Dump of rpki.net Wiki, to capture content not linked into the manual. --- doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration | 263 ++++++++++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration (limited to 'doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration') diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration new file mode 100644 index 00000000..410215d8 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FConfiguration @@ -0,0 +1,263 @@ +[[TracNav(doc/RPKI/TOC)]] +[[PageOutline]] + += Configuring the RPKI CA tools: `rpki.conf` = + +This section describes `rpki.conf`, the the configuration file for the +RPKI CA tools. + +The first subsection is a quick summary of the options you're most +likely to need to configure (or at least check) for a basic setup. + +The rest of this section contains a more complete reference to the +configuration file and some of the things you might need to do with it +if your needs are more complex. + +There are a lot of configuration options, but in most cases you will +never have to touch more than a few of them. Keep reading, and don't +panic. + +== Quick guide to the most common configuration options == + +This subsection describes only a handful of `rpki.conf` configuration +options. These are the ones you'll need to set, or at least check, as +part of initial installation. In general, the installation process +will have already set sane values for these, but you may need to a few +of them depending on exactly what you're doing. + +The location of `rpki.conf` varies depending on the operating system +you're running and how you installed the software. Unless you did +something unusual during installation, it's either `/etc/rpki.conf` or +`/usr/local/etc/rpki.conf`. + +{{{ +#!comment + +Should we even discuss `handle` here? We no longer create any +ResourceHolderCA automatically, so it's almost irrelevant at this +point, and we'd like to get rid of it eventually. Leave it out for +now and see if anybody complains, I guess. + +}}} + +* All of the configuration options you're most likely to need to change + are in the `[myrpki]` section of `rpki.conf`. + + {{{ + #!ini + [myrpki] + }}} + +* You need to check the setting of `rpkid_server_host`. The + installation process sets this to the fully-qualified DNS hostname + of the server on which you installed the code, but if you use a + service-specific DNS name for RPKI service you will need to change + this option to match that service name. + + {{{ + #!ini + rpkid_server_host = rpkid.example.org + }}} + +* You need to set the value of `run_pubd` to reflect whether you + intend to run your own RPKI publication server and rsync server. + + {{{ + #!ini + run_pubd = yes + }}} + + or + + {{{ + #!ini + run_pubd = no + }}} + +* If you are running your own RPKI publication server, you need to + check the setting of `pubd_server_host`. The installation process + sets this to the fully-qualified DNS hostname of the server on which + you installed the code, but if you use a service-specific DNS name + for RPKI publication service you will need to change this option to + match that service name. + + {{{ + #!ini + pubd_server_host = pubd.example.org + }}} + + +There are //many// other configuration options, but setting the above +correctly should suffice to get you started with the default +configuration. Read on for details if you need to know more, +otherwise go to [[#nextsteps|next steps]]. + + +== Configuration file syntax == #syntax + +The general format of `rpki.conf` is the same as the configuration +language used by many other programs, including the OpenSSL package. +The file is divided into "sections", labeled with square brackets; +individual options within a section look like variable assignments, +with the option name on the left and the option value on the right. + +{{{ +#!ini +[foo] + +bar = fred +baz = 42 +}}} + +The configuration file parser supports a limited version of the macro +facility used in OpenSSL's configuration parser. An expression such +as + +{{{ +#!ini +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. + +{{{ +#!ini +home = ${ENV::HOME} +}}} + +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 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/rpki.conf` when building from source or on platforms +like FreeBSD or MacOSX where packaged software goes in the +`/usr/local` tree; on GNU/Linux platforms, binary packages will use +`/etc/rpki.conf` per GNU/Linux convention. + +Regardless of the default location, you can override the build-time +default filename at runtime if necessary 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 (generally +"`-c`") specifying the name of the configuration file; if both the +command line option and the environment variable are set, the command +line option wins. + +The installation process builds a sample configuration file +`rpki.conf.sample` and installs it alongside of `rpki.conf`. If you +have no `rpki.conf` installed, the installation process will copy +`rpki.conf.sample` to `rpki.conf`, but it will not overwrite an +existing `rpki.conf` file. + +== Too much information about `rpki.conf` options == + +The list of options that you can set in `rpki.conf` is ridiculously +long. The default configuration includes what we hope are reasonable +default settings for all of them, so in many cases you will never need +to know about most of these options. A number of the options for +individual programs are specified in terms of other options, using the +macro facility [[#syntax|described above]]. + +In general, if you don't understand what an option does, you probably +should leave it alone. + +Detailed information about individual options is listed in separate +sections, one per section of `rpki.conf`. These documentation +sections are generated from the same source file as the sample +configuration file. + +{{{ +#!comment + +See notes in doc/RPKI/TOC about the format of link labels containing +square brackets like rpki.conf section names, and be careful here, +because the syntax is somewhat finicky. + +}}} + +* [[wiki:doc/RPKI/CA/Configuration/Common| Common Options ]] +* [[wiki:doc/RPKI/CA/Configuration/myrpki| [myrpki] section ]] +* [[wiki:doc/RPKI/CA/Configuration/rpkid| [rpkid] section ]] +* [[wiki:doc/RPKI/CA/Configuration/irdbd| [irdbd] section ]] +* [[wiki:doc/RPKI/CA/Configuration/pubd| [pubd] section ]] +* [[wiki:doc/RPKI/CA/Configuration/rootd| [rootd] section ]] +* [[wiki:doc/RPKI/CA/Configuration/web_portal| [web_portal] section ]] +* [[wiki:doc/RPKI/CA/Configuration/autoconf| [autoconf] section ]] + +{{{ +#!comment + +Still have to write subsections linking to: + + * [wiki:doc/RPKI/CA/Configuration/CreatingRoot Creating a RPKI Root Certificate] + * [wiki:doc/RPKI/CA/Configuration/Tests Test configuration] + * [wiki:doc/RPKI/CA/Configuration/DifferentServer Using Different Servers] + +}}} + +== 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: + +{{{ +#!ini +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. + +== Running your own RPKI root == + +In general, we do not recommend running your own RPKI root +environment, for various reasons. If, however, you need to do so, you +should read +[[wiki:doc/RPKI/CA/Configuration/rootd| the documentation for the [rootd] section ]], +and +[[wiki:doc/RPKI/CA/Configuration/CreatingRoot| the instructions for creating a RPKI root certificate ]]. + +== 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 most purposes, this is fine, but +in some cases you might want to split these functions up among +different servers. If you need to do this, see +[wiki:doc/RPKI/CA/Configuration/DifferentServer these instructions]. + +== Configuring the test harness == + +We expect the test harness to be of interest primarily to developers, +but if you need to understand how it works, you will probably want to read +[wiki:doc/RPKI/CA/Configuration/Tests these instructions]. + +== Next steps == #nextsteps + +Once you've finished with configuration, the next thing you should +read is the [[MySQLSetup|MySQL setup instructions]]. -- cgit v1.2.3