routinator config

source/routinator/configuration.rst

@@ -1,76 +1,104 @@
 .. _doc_routinator_configuration:
 
+.. note:: The Routinator comes pre-installed with the Trust Anchor Locators (TALs) 
+          of four out of the five RIRs. The ARIN TAL is not automatically loaded, 
+          as users must confirm their acceptance of the `ARIN Relying Party Agreement
+          (RPA) <https://www.arin.net/resources/rpki/tal.html>`_. 
+
+          When running the Routinator for the first time, follow the instructions
+          closely to download and include the ARIN TAL and get the full RPKI data set.
+
 Configuration
 =============
 
 There are currently two major functions of the Routinator: printing the
-list of valid route origins, also known as _Validated ROA Payload_ or VRP,
+list of valid route origins, also known as Validated ROA Payload (VRP),
 and providing the service for routers to access this list via a protocol
-known as RPKI-to-Router protocol or RTR.
+known as RPKI-to-Router protocol (RTR).
 
 These (and all other functions) of Routinator are accessible on the
-command line via sub-commands. The commands are `vrps` and `rtrd`,
+command line via sub-commands. The commands are ``vrps`` and ``rtrd``,
 respectively.
 
-So, to have Routinator print the list, you say
+Printing a list of valid route origins
+--------------------------------------
+
+The Routinator can print a list of valid route origins in four different formats:
+
+- csv: The list is formatted as lines of comma-separated values of the prefix in 
+slash notation, the maximum prefix length, the autonomous system number, and an abbreviation for the trust anchor the entry is derived from. The latter is the 
+name of the TAL file  without the extension *.tal*. This is the default format 
+used if the ``-f`` option is missing.
+- json: The list is placed into a JSON object with a single  element *roas* which 
+contains an array of objects with four elements each: The autonomous system 
+number of  the  network  authorised to originate a prefix in *asn*, the prefix 
+in slash notation in *prefix*, the maximum prefix length of the announced route 
+in *maxLength*, and the trust anchor from which the authorisation was derived 
+in *ta*. This format is identical to that produced by the RIPE NCC validator 
+except for different naming of the trust anchor. The Routinator uses the name of 
+the TAL file without the extension *.tal* whereas the RIPE NCC Validator has a 
+dedicated name for each.
+- openbgpd: Choosing  this format causes the Routinator to produce a *roa-set* configuration item for the OpenBGPD configuration.
+- rpsl: This format produces a list of RPSL objects with the authorisation in the
+fields *route*, *origin*, and *source*. In addition, the fields *descr*, *mnt-by*, *created*, and *last-modified*, are present with more or less meaningful values.
+- none: This format produces no output whatsoever.
+
+Usage
+"""""
 
-```bash
-routinator vrps
-```
+.. code-block:: bash
 
-If this is the first time you’ve
-been using Routinator, it will create `$HOME/.rpki-cache`, put the
-trust anchor locators of the five RIRs there, and then complain that
-ARIN’s TAL is in fact not really there.
+   routinator vrps
+
+If this is the first time you’ve been using the Routinator, it will create ``$HOME/.rpki-cache``, put the Trust Anchor Locators (TALs) of the five RIRs there, 
+and then complain that ARIN’s TAL is in fact not really there.
 
 Follow the instructions provided and try again. You can also add
 additional trust anchors by simple dropping their TAL file in RFC 7730
-format into `$HOME/.rpki-cache/tals`.
+format into ``$HOME/.rpki-cache/tals``.
 
 Now Routinator will rsync the entire RPKI repository to your machine
 (which will take a while during the first run), validate it and produce
 a long list of AS numbers and prefixes.
 
 Information about additional command line arguments is available via the
-`-h` option or you can look at the more detailed man page via the `man`
+``-h`` option or you can look at the more detailed man page via the ``man``
 sub-command:
 
-```bash
-routinator man
-```
+.. code-block:: bash
 
-It is also available online on the
-[NLnetLabs documentation
-site](https://www.nlnetlabs.nl/documentation/rpki/routinator/).
+   routinator man
 
+It is also available online on the `NLnetLabs documentation site <https://www.nlnetlabs.nl/documentation/rpki/routinator/>`.
 
-## Feeding a Router with RPKI-RTR
+Feeding a Router with RPKI-RTR
+------------------------------
 
 Routinator supports RPKI-RTR as specified in RFC 8210 as well as the older
 version from RFC 6810. It will act as an RTR server if you start it with
-the `rtrd` sub-command. It will do so as a daemon and detach from your
-terminal unless you provide the `-a` (for attached) option.
+the ``rtrd`` sub-command. It will do so as a daemon and detach from your
+terminal unless you provide the ``-a`` (for attached) option.
 
-You can specify the address(es) to listen on via the `-l` (or `--listen`)
-option. If you don’t, it will listen on `127.0.0.1:3323` by default. This
+You can specify the address(es) to listen on via the ``-l`` (or ``--listen``)
+option. If you don’t, it will listen on ``127.0.0.1:3323`` by default. This
 isn’t the IANA-assigned default port for the protocol, which would be 323.
 But since that is a privileged port you’d need to be running Routinator as
 root when otherwise there is no reason to do that. Also, note that the
 default address is a localhost address for security reasons.
 
 So, in order to run Routinator as an RTR server listening on port 3323 on
-both 192.0.2.13 and 2001:0DB8::13 without detaching from the terminal, run
+both 192.0.2.13 and 2001:0DB8::13 without detaching from the terminal, run:
+
+.. code-block:: bash
 
-```bash
-routinator rtrd -a -l 192.0.2.13:3323 -l [2001:0DB8::13]:3323
-```
+   routinator rtrd -a -l 192.0.2.13:3323 -l [2001:0DB8::13]:3323
 
 By default, the repository will be updated and re-validated every hour as
 per the recommendation in the RFC. You can change this via the
-`--refresh` option and specify the interval between re-validations in
+``--refresh`` option and specify the interval between re-validations in
 seconds. That is, if you rather have Routinator validate every fifteen
-minutes, the above command becomes
+minutes, the above command becomes:
+
+.. code-block:: bash
 
-```bash
-routinator rtrd -a -l 192.0.2.13:3323 -l [2001:0DB8::13]:3323 --refresh=900
-```
+    routinator rtrd -a -l 192.0.2.13:3323 -l [2001:0DB8::13]:3323 --refresh=900

source/routinator/installation.rst

@@ -4,10 +4,10 @@ Installation
 ============
 
 At this time, there are no binary packages for Routinator yet, but getting
-started with Routinator is really easy, using either `Cargo
+started is really easy using either `Cargo
 <https://crates.io/crates/routinator>`_, `Docker
-<https://hub.docker.com/r/nlnetlabs/routinator/>`_, or building from the `source
-<https://github.com/NLnetLabs/routinator>`_. 
+<https://hub.docker.com/r/nlnetlabs/routinator/>`_, or building from the
+`source <https://github.com/NLnetLabs/routinator>`_. 
 
 Quick Start
 -----------
@@ -23,7 +23,7 @@ you get the Routinator to run as an RTR server listening on 127.0.0.1 port
    cargo install routinator
    routinator rtrd -l 127.0.0.1:3323
 
-If you have an older version of the Routinator, you can update via
+If you have an older version of the Routinator, you can update via:
 
 .. code-block:: bash
 
@@ -65,14 +65,14 @@ require a C toolchain, so you need that, too.
 rsync
 """""
 
-Currently, Routinator requires the `rsync` executable to be in your path.
+Currently, Routinator requires the ``rsync`` executable to be in your path.
 We are not quite sure which particular version you need at the very least,
 but whatever is being shipped with current Linux and \*BSD distributions
 and macOS should be fine.
 
-On Windows, Routinator requires the `rsync` version that comes with
+On Windows, Routinator requires the ``rsync`` version that comes with
 `Cygwin <https://www.cygwin.com/>`_ – make sure to select rsync during the
-installation phase. And yes, Routinator totally works on Windows, too.
+installation phase. 
 
 If you don’t have rsync, please head to http://rsync.samba.org/
 
@@ -127,10 +127,10 @@ release version, you can run
    cargo install --git https://github.com/NLnetLabs/routinator.git
 
 If you want to update an installed version, you run the same command but
-add the ``-f`` flag (aka force) to approve overwriting the installed
+add the ``-f`` flag, a.k.a. force, to approve overwriting the installed
 version.
 
 The command will build Routinator and install it in the same directory
-that cargo itself lives in (likely ``$HOME/.cargo/bin``).
-Which means Routinator will be in your path, too.
+that cargo itself lives in, likely ``$HOME/.cargo/bin``.This means 
+Routinator will be in your path, too.