diff options
| -rw-r--r-- | rpkid/rpki-confgen.xml | 113 |
1 files changed, 76 insertions, 37 deletions
diff --git a/rpkid/rpki-confgen.xml b/rpkid/rpki-confgen.xml index 4e082ead..4e898783 100644 --- a/rpkid/rpki-confgen.xml +++ b/rpkid/rpki-confgen.xml @@ -24,101 +24,136 @@ <section name = "myrpki"> + <doc> + The `[myrpki]` section contains all the parameters that you + really need to configure. The name `myrpki` is historical and + may change in the future. + </doc> + <option name = "handle"> <doc> - 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. + 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. + </doc> + <doc> + 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. + </doc> + <doc> + Syntax is an identifier (ASCII letters, digits, hyphen, + underscore -- no whitespace, non-ASCII characters, or other + punctuation). </doc> </option> <option name = "bpki_servers_directory" value = "${autoconf::datarootdir}/rpki"> <doc> - Directory for BPKI files generated by rpkic and used by rpkid and pubd. - Default is where we expect autoconf to decide that our data files - belong, you might want or need to change this. In the long term - this should be handled by a setup wizard. + Directory for BPKI files generated by rpkic and used by rpkid + and pubd. You will not normally need to change this. </doc> </option> <option name = "run_rpkid" value = "yes"> <doc> - 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. + 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. </doc> </option> <option name = "rpkid_server_host"> <doc> - DNS hostname for rpkid. Must be publicly reachable to be useful. + 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. </doc> </option> <option name = "rpkid_server_port" value = "4404"> <doc> - Server port number for rpkid, can be any legal TCP port number - that you're not using for something else. + Server port number for rpkid. This can be any legal TCP port + number that you're not using for something else. </doc> </option> <option name = "irdbd_server_host" value = "localhost"> <doc> - DNS hostname for irdbd. This should be localhost unless you - really know what you are doing. + DNS hostname for irdbd, or `localhost`. This should be + `localhost` unless you really know what you are doing. </doc> </option> <option name = "irdbd_server_port" value = "4403"> <doc> - Server port number for irdbd, can be any legal TCP port number - that you're not using for something else. + Server port number for irdbd. This can be any legal TCP port + number that you're not using for something else. </doc> </option> <option name = "run_pubd" value = "yes"> <doc> - 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. + 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. + </doc> + <doc> + 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. </doc> </option> <option name = "pubd_server_host"> <doc> - DNS hostname for pubd, if you're running it. Must be publicly - reachable to be useful. + DNS hostname for pubd, if you're running it. This must + resolve to a publicly reachable address to be useful. </doc> </option> <option name = "pubd_server_port" value = "4402"> <doc> - Server port number for pubd, can be any legal TCP port number that - you're not using for something else. + Server port number for pubd. This can be any legal TCP port + number that you're not using for something else. </doc> </option> <option name = "pubd_contact_info"> <doc> - 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. + 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. </doc> </option> <option name = "run_rootd" value = "no"> <doc> - Whether you want to run your very own copy of rootd. Don't enable - this unless you really know what you're doing. + Whether you want to run your very own copy of rootd. Don't + enable this unless you really know what you're doing. </doc> </option> @@ -133,8 +168,9 @@ <option name = "rootd_server_port" value = "4401"> <doc> - 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. + 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. </doc> </option> @@ -251,16 +287,19 @@ value = "rpki"> <doc> 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. + same MySQL username, set that value here. The default setting + of this variable should be fine. </doc> </option> <option name = "shared_sql_password"> <doc> - 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. + 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. </doc> </option> |