1 files changed, 177 insertions, 0 deletions
diff --git a/doc/12.RPKI.CA.Configuration.md b/doc/12.RPKI.CA.Configuration.md
new file mode 100644
index 00000000..d1ded6fb
--- /dev/null
+++ b/doc/12.RPKI.CA.Configuration.md
@@ -0,0 +1,177 @@
+# 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`.
+
+  * All of the configuration options you're most likely to need to change are in the `[myrpki]` section of `rpki.conf`. 
+
+    [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. 
+
+    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. 
+
+    run_pubd                        = yes
+
+> or
+
+    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. 
+
+    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 next steps.
+
+## Configuration file 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.
+
+    [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
+
+    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.
+
+    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 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.
+
+  * Common Options 
+  * [myrpki] section 
+  * [rpkid] section 
+  * [irdbd] section 
+  * [pubd] section 
+  * [rootd] section 
+  * [web_portal] section 
+  * [autoconf] section 
+
+## 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.
+
+## 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  the
+documentation for the [rootd] section , and  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 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 these
+instructions.
+
+## Next steps
+
+Once you've finished with configuration, the next thing you should read is the
+MySQL setup instructions.