From f5fbb30d6329ca29cfce7e5b1d39f84db6e83dcc Mon Sep 17 00:00:00 2001 From: Alex Band Date: Wed, 3 Jul 2024 12:34:21 +0200 Subject: [PATCH] First pass of typo and formatting fixes --- doc/manual/source/architecture.rst | 11 +++------ doc/manual/source/building-from-source.rst | 4 ++-- doc/manual/source/ca-keyroll.rst | 9 ++------ doc/manual/source/ca-migrate-repo.rst | 2 -- doc/manual/source/cli.rst | 15 +++++------- doc/manual/source/hsm.rst | 4 ++-- doc/manual/source/publication-server.rst | 27 +++++++++------------- doc/manual/source/testbed.rst | 18 ++++----------- doc/manual/source/trust-anchor.rst | 12 ++++++---- 9 files changed, 37 insertions(+), 65 deletions(-) diff --git a/doc/manual/source/architecture.rst b/doc/manual/source/architecture.rst index a7351965..b087c194 100644 --- a/doc/manual/source/architecture.rst +++ b/doc/manual/source/architecture.rst @@ -47,7 +47,7 @@ called ``archived`` under the relevant data directory, i.e. ``data_dir/pubd/0/archived`` if you are using the Krill Publication Server and ``data_dir/cas//archived`` for each of your CAs. -You can set up a cronjob to delete these events once and for all, but we +You can set up a cron job to delete these events once and for all, but we recommend that you save them in long term storage if you can. The reason is that if (and only if) you have this data, you will be able to rebuild the complete Krill state based on its *audit* log of events, and irrevocably prove that no @@ -60,10 +60,7 @@ Saving State Changes You can skip this section if you're not interested in the gory details. However, understanding this section will help to explain how backup and restore works in -Krill, and why a standby fail-over node can be used, but Krill's locking and -storage mechanism needs to be changed in order to make -`multiple active nodes `_ -work. +Krill, and how a standby fail-over node can be used. State changes in Krill are tracked using *events*. Krill CA(s) and Publication Servers are versioned. They can only be changed by applying an *event* for a @@ -76,9 +73,7 @@ so-called *aggregates*. Events are not applied directly. Rather, users of Krill and background jobs will send their intent to make a change through the API, which then translates this into a so-called *command*. Krill will then *lock* the target aggregate -and send the command to it. This locking mechanism is not aware of any -clustering, and it's a primary reason why Krill cannot run as an active-active -cluster yet. +and send the command to it. Upon receiving a command the aggregate (your CA etc.) will do some work. In some cases a command can have a side-effect. For example it may instruct your CA to diff --git a/doc/manual/source/building-from-source.rst b/doc/manual/source/building-from-source.rst index e99f9621..57f47e1e 100644 --- a/doc/manual/source/building-from-source.rst +++ b/doc/manual/source/building-from-source.rst @@ -85,7 +85,7 @@ this should be as simple as running: Building with Cargo """"""""""""""""""" -Rust uses its own build tool, called ```cargo```. +Rust uses its own build tool, called ``cargo``. https://github.com/NLnetLabs/krill @@ -94,7 +94,7 @@ You can clone the a release and then use ```cargo build --release --locked``` to build the code. An easier way to build a specific release with the need to clone the -repository first is to leave it to ```cargo```. Krill releases and tags +repository first is to leave it to ``cargo``. Krill releases and tags are listed `here `_ You can install a tagged github release using cargo by saying: diff --git a/doc/manual/source/ca-keyroll.rst b/doc/manual/source/ca-keyroll.rst index 67187231..eebe5b5c 100644 --- a/doc/manual/source/ca-keyroll.rst +++ b/doc/manual/source/ca-keyroll.rst @@ -9,13 +9,10 @@ the content of all 'objects', like ROAs and possibly certificates issued to chil is preserved in re-issued objects under the new key, without noticeable interruptions to RPKI validators. -Before we can dive in to key rollovers we need to take a step back and talk a bit -about RPKI CA certificates and keys. - For most users their CA will have only one parent CA and only one key and CA certificate -under that parent. But, krill supports having multiple so-called "Resource Classes" under +under that parent. But, Krill supports having multiple so-called "Resource Classes" under a parent. The term Resource Class stems from :rfc:`6492` - essentially you can think of -these as a way to to group a set of resources that can appear on a single certificate. +these as a way to group a set of resources that can appear on a single certificate. This construct is needed because RPKI CA certificates can have only one signing parent CA certificate. So, if your parent received resources on different certificate (presumably from different sources), then they cannot sign a single certificate to you with all those resources. @@ -43,14 +40,12 @@ First you need to initialise a new key to start the process: krillc keyroll init - Then, you should wait 24 hours and before activating the new key and retiring the old: .. code-block:: text krillc keyroll activate - Caveats: - The ``init`` command will have no effect if your CA is in the middle of a rollover diff --git a/doc/manual/source/ca-migrate-repo.rst b/doc/manual/source/ca-migrate-repo.rst index c602c2ce..e41e40ca 100644 --- a/doc/manual/source/ca-migrate-repo.rst +++ b/doc/manual/source/ca-migrate-repo.rst @@ -17,8 +17,6 @@ new key that will use the new server, and the base URIs it got from that server. Then you need to complete the key rollover (activate the new key), to remove the old key and the dependency on the old server. -There is no web UI support for this (yet), but you can do this using the CLI. - First, get the so-called :rfc:`8183` Publisher Request XML for your CA: .. code-block:: text diff --git a/doc/manual/source/cli.rst b/doc/manual/source/cli.rst index f378e788..a604472f 100644 --- a/doc/manual/source/cli.rst +++ b/doc/manual/source/cli.rst @@ -130,23 +130,20 @@ Other operations: :ref:`children` Manage children for a CA :ref:`keyroll` Perform a manual key rollover for a CA - - .. _cmd_krillc_config: krillc config ------------- -This subcommand is implemented on the CLI only and is intended to help generate a configuration -file which can be used for your Krill server. +This subcommand is implemented on the CLI only and is intended to help +generate a configuration file which can be used for your Krill server. -We currently support two subcommands for this: `krillc config simple` and `krillc config user`. -The first can be used to generate general server configuration. The second can be used to generate -user (`id`) entries to use if you want to have multiple local users access the Krill UI by their own +We currently support two subcommands for this: ``krillc config simple`` and +``krillc config user``. The first can be used to generate general server +configuration. The second can be used to generate user (``id``) entries to +use if you want to have multiple local users access the Krill UI by their own name and password. -.... - .. _cmd_krillc_health: krillc health diff --git a/doc/manual/source/hsm.rst b/doc/manual/source/hsm.rst index 15bac06b..5e105da2 100644 --- a/doc/manual/source/hsm.rst +++ b/doc/manual/source/hsm.rst @@ -41,7 +41,7 @@ Krill uses what it calls a "signer" to create and manage keys and to sign data with them. For the most part the Krill CA code is unaware of which signer implementation is associated with a key. For long-lived key-pairs such as the keys used in RPKI CA certificates (the resource -certificate signed by the parent) and the ID certifcate used in the +certificate signed by the parent) and the ID certificate used in the :RFC:`6492` (provisioning) and :RFC:`8181` (publication) protocols, it will only keep track of the public key identifier. @@ -218,7 +218,7 @@ file, one for each signer that you wish to define. All signers must have a ``type`` and a ``name`` and properties specific to the type of signer. -The default configuration is equivalent to addding the following in +The default configuration is equivalent to adding the following in ``krill.conf``: .. code-block:: diff --git a/doc/manual/source/publication-server.rst b/doc/manual/source/publication-server.rst index 94c75cc6..6f6cf9eb 100644 --- a/doc/manual/source/publication-server.rst +++ b/doc/manual/source/publication-server.rst @@ -100,11 +100,11 @@ Proxy for Remote Publishers --------------------------- Krill runs the RFC8181 Publication Server. Remote publishers, CAs which use your -Publication Server, will need to connect to this under the `/rfc8181` path under -the `service_uri` that you specified in your server. +Publication Server, will need to connect to this under the ``/rfc8181`` path under +the ``service_uri`` that you specified in your server. Make sure that you set up a proxy server such as NGINX, Apache, etc. which uses -a valid HTTPS certificate, and which proxies `/rfc8181` to Krill. +a valid HTTPS certificate, and which proxies ``/rfc8181`` to Krill. Note that you should not add any additional authentication mechanisms to this location. RFC 8181 uses cryptographically signed messages sent over HTTP and is @@ -125,14 +125,14 @@ proxy access to the path '/api' to Krill. Example NGINX configuration --------------------------- -As introduced above krill has two paths that contain the endpoints. `/api` for the -krill API that you may want to restrict. `/rfc8181` is used for publication. A -configuration that allows `192.0.2.0/24` and the IPv6 documentation prefix access to +As introduced above, Krill has two paths that contain the endpoints: ``/api`` for the +Krill API that you may want to restrict and ``/rfc8181`` is used for publication. A +configuration that allows ``192.0.2.0/24`` and the IPv6 documentation prefix access to the API, and all clients to publish is below. It is recommended to publish the RRDP content on a different hostname. -`/etc/nginx/sites-enabled/krill.example.org` +``/etc/nginx/sites-enabled/krill.example.org`` .. code-block:: text @@ -201,8 +201,6 @@ Configure the Repository their content. We use the term **Repository Server** to describe a server which makes this content available to RPKI Validators. - - Synchronise Repository Data """"""""""""""""""""""""""" @@ -237,8 +235,8 @@ sets of data to disk for use by your Repository Servers. Another option is to use some kind of shared file system (NFS, clustered filesystem, network storage) where the **Krill Publication Server** can write, and your **Repository Servers** can read. -If you go down this path, then make sure that the entire `$DATA_DIR/repo` is on a share. -In particular: don't use a mount point at `$DATA_DIR/repo/rsync/current` as this directory +If you go down this path, then make sure that the entire :file:`$DATA_DIR/repo` is on a share. +In particular: don't use a mount point at :file:`$DATA_DIR/repo/rsync/current` as this directory is recreated by Krill whenever it publishes new data. There can be issues with this approach with regards to availability and atomicity of updates @@ -248,8 +246,6 @@ or deltas are available. It will also write new files to temporary files and the to avoid that partially written files are shown to users. However, dependent on the implementation details of the shared data these strategies may not work. - - Rsync """"" @@ -359,13 +355,12 @@ on their certificates. If you should end up in this situation, then you could set up a new Publication Server instead, and then migrate your existing CAs to that server, and then remove your current server altogether. Alternatively, you can remove all -publishers from your server first, then clear and re-inialise it, and then +publishers from your server first, then clear and re-initialise it, and then add your CAs again and migrate them to this newly initialised version. In short: it is best to avoid this and ensure that your are happy with the URIs used before adding publishers. - Repository Stats """""""""""""""" @@ -463,7 +458,7 @@ from the UI, as described :ref:`here`. The XML will include a so-called 'handle' - essentially the name that the CA likes to use for itself. This handle needs to be unique on the server side - we can't have all CAs calling themselves `mr-black`. For this reason the CLI offers an -optional argument ``--publisher`` that allows overriding the handle in the reqeust +optional argument ``--publisher`` that allows overriding the handle in the request with a locally unique value - e.g. a UUID. After adding a publisher the server will respond with the unique :rfc:`8183` Repository diff --git a/doc/manual/source/testbed.rst b/doc/manual/source/testbed.rst index 9a69038d..15729f38 100644 --- a/doc/manual/source/testbed.rst +++ b/doc/manual/source/testbed.rst @@ -59,8 +59,8 @@ Restart nginx and we have our proxy server set up: systemctl restart nginx -Set up Letsencrypt -^^^^^^^^^^^^^^^^^^ +Set up Let's Encrypt +^^^^^^^^^^^^^^^^^^^^ This is as easy as installing the `certbot` and running its interactive script to setup integration with NGINX: @@ -75,16 +75,8 @@ script to setup integration with NGINX: Install Krill ^^^^^^^^^^^^^ -We use our debian package to install Krill on a test system: - -.. code-block:: text - - echo "deb [arch=amd64] https://packages.nlnetlabs.nl/linux/ubuntu/ focal main" >> /etc/apt/sources.list - apt-get update - apt-get install krill - -You can read more about Krill installation options `here `_. - +Install Krill according to the :ref:`installation instructions +` for Debian, Ubuntu or Red Hat Enterprise Linux. Configure Testbed ^^^^^^^^^^^^^^^^^ @@ -102,11 +94,9 @@ public URI for your proxy server: service_uri = "https://krill.example.org/" - Add the following section to your config and change the values to your machine's hostname. - .. code-block:: text [testbed] diff --git a/doc/manual/source/trust-anchor.rst b/doc/manual/source/trust-anchor.rst index 6d3c7b5f..1827ec03 100644 --- a/doc/manual/source/trust-anchor.rst +++ b/doc/manual/source/trust-anchor.rst @@ -3,11 +3,13 @@ Krill as a Trust Anchor ======================= -Krill can be set up to operate an RPKI Trust Anchor (TA). An RPKI TA -serves as an `entry point for RPKI validators `_. -There are currently `five globally used TAs `_ -operated by the five RIRs, where each RIR is responsible for IPv4, IPv6 -and AS number resources that are allocated to them by IANA. +Krill can be set up to operate an RPKI Trust Anchor (TA). An RPKI TA serves +as an `entry point for RPKI validators +`_. +There are currently `five globally used TAs +`_ +operated by the five RIRs, where each RIR is responsible for IPv4, IPv6 and +AS number resources that are allocated to them by IANA. If you are not an RIR, then you will not need to run your own RPKI TA for normal RPKI operations. Instead, you would operate one or more RPKI CAs that get