WEBDIENSTE/NLnetLabs-krill
1
0
Fork 0
mirror of https://github.com/NLnetLabs/krill.git synced 2026-09-12 20:47:41 +02:00
Code Issues Packages Projects Releases Wiki Activity

First pass of typo and formatting fixes

Browse Source
This commit is contained in:
Alex Band
2024-07-03 12:34:21 +02:00
parent a88636428e
commit f5fbb30d63
9 changed files with 37 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/manual/source/architecture.rst
+3 -8
View File
@@ -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/<your-ca-name>/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 <https://github.com/NLnetLabs/krill/issues/20>`_
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
doc/manual/source/building-from-source.rst
+2 -2
View File
@@ -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 <https://github.com/NLnetLabs/krill/releases>`_
You can install a tagged github release using cargo by saying:
doc/manual/source/ca-keyroll.rst
+2 -7
View File
@@ -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
doc/manual/source/ca-migrate-repo.rst
-2
View File
@@ -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
doc/manual/source/cli.rst
+6 -9
View File
@@ -130,23 +130,20 @@ Other operations:
:ref:`children<cmd_krillc_children>` Manage children for a CA
:ref:`keyroll<cmd_krillc_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
doc/manual/source/hsm.rst
+2 -2
View File
@@ -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::
doc/manual/source/publication-server.rst
+11 -16
View File
@@ -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<doc_krill_using_ui_repository_setup>`.
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
doc/manual/source/testbed.rst
+4 -14
View File
@@ -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 <https://rpki.readthedocs.io/en/latest/krill/install-and-run.html#installing-with-debian-and-ubuntu-packages>`_.
Install Krill according to the :ref:`installation instructions
<doc_krill_install_and_run>` 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]
doc/manual/source/trust-anchor.rst
+7 -5
View File
@@ -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 <https://rpki.readthedocs.io/en/latest/rpki/using-rpki-data.html#connecting-to-the-trust-anchor>`_.
There are currently `five globally used TAs <https://rpki.readthedocs.io/en/latest/rpki/introduction.html#mapping-the-resource-allocation-hierarchy-into-the-rpki>`_
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
<https://rpki.readthedocs.io/en/latest/rpki/using-rpki-data.html#connecting-to-the-trust-anchor>`_.
There are currently `five globally used TAs
<https://rpki.readthedocs.io/en/latest/rpki/introduction.html#mapping-the-resource-allocation-hierarchy-into-the-rpki>`_
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