From 3e7ce225e3cb0fc01359bb2f306dfdbe97078000 Mon Sep 17 00:00:00 2001 From: Alex Band Date: Thu, 10 Jan 2019 15:38:49 +0100 Subject: [PATCH] routinator config --- source/routinator/configuration.rst | 94 +++++++++++++++++++---------- source/routinator/installation.rst | 20 +++--- 2 files changed, 71 insertions(+), 43 deletions(-) diff --git a/source/routinator/configuration.rst b/source/routinator/configuration.rst index 85f7da78..9c58044a 100644 --- a/source/routinator/configuration.rst +++ b/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) `_. + + 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 `. -## 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 -``` \ No newline at end of file + routinator rtrd -a -l 192.0.2.13:3323 -l [2001:0DB8::13]:3323 --refresh=900 diff --git a/source/routinator/installation.rst b/source/routinator/installation.rst index a05acff5..9ae90e0a 100644 --- a/source/routinator/installation.rst +++ b/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 `_, `Docker -`_, or building from the `source -`_. +`_, or building from the +`source `_. 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 `_ – 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.