1 files changed, 295 insertions, 0 deletions
diff --git a/doc/14.RPKI.CA.Configuration.myrpki.md b/doc/14.RPKI.CA.Configuration.myrpki.md
new file mode 100644
index 00000000..bf798d65
--- /dev/null
+++ b/doc/14.RPKI.CA.Configuration.myrpki.md
@@ -0,0 +1,295 @@
+# [myrpki] section
+
+The "`[myrpki]`" section contains all the parameters that you really need to
+configure. The name "`myrpki`" is historical and may change in the future.
+
+## handle
+
+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.
+
+The "`handle`" option in the "`[myrpki]`" section specifies the default handle
+for this installation. 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. In the long run, this
+option may go away entirely, but for now you need to set this.
+
+Syntax is an identifier (ASCII letters, digits, hyphen, underscore -- no
+whitespace, non-ASCII characters, or other punctuation).
+
+No default value.
+
+## bpki_servers_directory
+
+Directory for BPKI files generated by rpkic and used by rpkid and pubd. You
+will not normally need to change this.
+
+    bpki_servers_directory = ${autoconf::datarootdir}/rpki
+
+## run_rpkid
+
+Whether you want to run your own copy of rpkid (and irdbd). Leave this alone
+unless you're doing something unusual like running a pubd-only installation.
+
+    run_rpkid = yes
+
+## rpkid_server_host
+
+DNS hostname for rpkid. In most cases, this must resolve to a publicly-
+reachable address to be useful, as your RPKI children will need to contact
+your rpkid at this address.
+
+No default value.
+
+## rpkid_server_port
+
+Server port number for rpkid. This can be any legal TCP port number that
+you're not using for something else.
+
+    rpkid_server_port = 4404
+
+## irdbd_server_host
+
+DNS hostname for irdbd, or "`localhost`". This should be "`localhost`" unless
+you really know what you are doing.
+
+    irdbd_server_host = localhost
+
+## irdbd_server_port
+
+Server port number for irdbd. This can be any legal TCP port number that
+you're not using for something else.
+
+    irdbd_server_port = 4403
+
+## run_pubd
+
+Whether you want to run your own copy of pubd. In general, it's best to use
+your parent's pubd if your parent allows you to do so, because this will
+reduce the overall number of publication sites from which relying parties will
+need to retrieve data. However, not all parents offer publication service, or
+you may need to run pubd yourself for reliability reasons, or because you're
+certifying private address space or private Autonomous System Numbers.
+
+The out of band setup protocol will attempt to negotiate publication service
+for you with whatever publication service your parent is using, if it can and
+if you let it.
+
+    run_pubd = yes
+
+## pubd_server_host
+
+DNS hostname for pubd, if you're running it. This must resolve to a publicly
+reachable address to be useful.
+
+No default value.
+
+## pubd_server_port
+
+Server port number for pubd. This can be any legal TCP port number that you're
+not using for something else.
+
+    pubd_server_port = 4402
+
+## pubd_contact_info
+
+Contact information to include in offers of repository service. This only
+matters when you're running pubd. This should be a human readable string,
+perhaps containing an email address or URL.
+
+No default value.
+
+## run_rootd
+
+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 = no
+
+## rootd_server_host
+
+DNS hostname for rootd, if you're running it. This should be localhost unless
+you really know what you are doing.
+
+    rootd_server_host = localhost
+
+## rootd_server_port
+
+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
+
+## publication_base_directory
+
+Root of local directory tree where pubd 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 it 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 = ${autoconf::datarootdir}/rpki/publication
+
+## publication_root_cert_directory
+
+Root of local directory tree where rootd (sigh) should write out published
+data. This is just like publication_base_directory, but rootd is too dumb to
+use pubd and needs its own directory in which to write one certificate, one
+CRL, and one manifest. Neither rootd 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 rootd's published outputs.
+
+    publication_root_cert_directory = ${myrpki::publication_base_directory}.root
+
+## publication_rsync_module
+
+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
+
+## publication_root_module
+
+rsyncd module name corresponding to publication_root_cert_directory. This has
+to match the module you configured into `rsyncd.conf`. Leave this alone unless
+you have some need to change it.
+
+    publication_root_module = root
+
+## publication_rsync_server
+
+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}
+
+## start_rpkid
+
+rpkid startup control. This should usually have the same value as run_rpkid:
+the only case where you would want to change this is when you are running the
+back-end code on a different machine from one or more of the daemons, in which
+case you need finer control over which daemons to start on which machines. In
+such cases, run_rpkid controls whether the back-end code is doing things to
+manage rpkid, while start_rpkid controls whether rpki-start-servers attempts
+to start rpkid on this machine.
+
+    start_rpkid = ${myrpki::run_rpkid}
+
+## start_irdbd
+
+irdbd startup control. This should usually have the same value as run_rpkid:
+the only case where you would want to change this is when you are running the
+back-end code on a different machine from one or more of the daemons, in which
+case you need finer control over which daemons to start on which machines. In
+such cases, run_rpkid controls whether the back-end code is doing things to
+manage rpkid, while start_irdbd controls whether rpki-start-servers attempts
+to start irdbd on this machine.
+
+    start_irdbd = ${myrpki::run_rpkid}
+
+## start_pubd
+
+pubd startup control. This should usually have the same value as run_pubd: the
+only case where you would want to change this is when you are running the
+back-end code on a different machine from one or more of the daemons, in which
+case you need finer control over which daemons to start on which machines. In
+such cases, run_pubd controls whether the back-end code is doing things to
+manage pubd, while start_pubd controls whether rpki-start-servers attempts to
+start pubd on this machine.
+
+    start_pubd = ${myrpki::run_pubd}
+
+## start_rootd
+
+rootd startup control. This should usually have the same value as run_rootd:
+the only case where you would want to change this is when you are running the
+back-end code on a different machine from one or more of the daemons, in which
+case you need finer control over which daemons to start on which machines. In
+such cases, run_rootd controls whether the back-end code is doing things to
+manage rootd, while start_rootd controls whether rpki-start-servers attempts
+to start rootd on this machine.
+
+    start_rootd = ${myrpki::run_rootd}
+
+## shared_sql_username
+
+If you're comfortable with having all of the databases use the same MySQL
+username, set that value here. The default setting of this variable should be
+fine.
+
+    shared_sql_username = rpki
+
+## shared_sql_password
+
+If you're comfortable with having all of the databases use the same MySQL
+password, set that value here. You should use a locally generated password
+either here or in the individual settings below. The installation process
+generates a random value for this option, which satisfies this requirement, so
+ordinarily you should have no need to change this option.
+
+No default value.
+
+## rpkid_sql_database
+
+SQL database name for rpkid's database. The default setting of this variable
+should be fine.
+
+    rpkid_sql_database = rpkid
+
+## rpkid_sql_username
+
+If you want to use a separate SQL username for rpkid's database, set it here.
+
+    rpkid_sql_username = ${myrpki::shared_sql_username}
+
+## rpkid_sql_password
+
+If you want to use a separate SQL password for rpkid's database, set it here.
+
+    rpkid_sql_password = ${myrpki::shared_sql_password}
+
+## irdbd_sql_database
+
+SQL database for irdbd's database. The default setting of this variable should
+be fine.
+
+    irdbd_sql_database = irdbd
+
+## irdbd_sql_username
+
+If you want to use a separate SQL username for irdbd's database, set it here.
+
+    irdbd_sql_username = ${myrpki::shared_sql_username}
+
+## irdbd_sql_password
+
+If you want to use a separate SQL password for irdbd's database, set it here.
+
+    irdbd_sql_password = ${myrpki::shared_sql_password}
+
+## pubd_sql_database
+
+SQL database name for pubd's database. The default setting of this variable
+should be fine.
+
+    pubd_sql_database = pubd
+
+## pubd_sql_username
+
+If you want to use a separate SQL username for pubd's database, set it here.
+
+    pubd_sql_username = ${myrpki::shared_sql_username}
+
+## pubd_sql_password
+
+If you want to use a separate SQL password for pubd's database, set it here.
+
+    pubd_sql_password = ${myrpki::shared_sql_password}