routinator installation

source/krill/ca/api.rst

@@ -1,7 +1,7 @@
 .. _doc_krill_ca_api:
 
 API
----
+===
 
 Placeholder
 

source/krill/ca/configuration.rst

@@ -1,7 +1,7 @@
 .. _doc_krill_ca_configuration:
 
 Configuration
--------------
+=============
 
 Placeholder
 

source/krill/ca/index.rst

@@ -1,5 +1,5 @@
 Certificate Authority
----------------------
+=====================
 
 This implementation allows operators to run their own Certificate Authority (CA) as a child of a Regional Internet Registry or a different parent, such as a National Internet Registry (NIR) or Enterprise. The CA will allow operators to generate their own cryptographic material, including all certificates and ROAs. 
 

source/krill/installation.rst

@@ -1,6 +1,6 @@
 .. _doc_krill_installation:
 
 Installation
-------------
+============
 
 Placeholder for Certificate Authority and Publication Server installation

source/krill/pub/api.rst

@@ -1,7 +1,7 @@
 .. _doc_krill_pub_api:
 
 API
----
+===
 
 This application uses a JSON based REST (in the non-religious interpretation)
 API for managing all administrative tasks, such as managing the configured

source/krill/pub/configuration.rst

@@ -1,7 +1,7 @@
 .. _doc_krill_pub_configuration:
 
 Configuration
--------------
+=============
 
 Placeholder
 

source/krill/pub/index.rst

@@ -1,5 +1,5 @@
 Publication Server
-------------------
+==================
 
 The publication server is developed in tandem with the CA and is intended to support it. It is listed as a separate item because it will allow operators to do the publication of their certificates and ROAs themselves, or let a third party such as a Content Delivery Network do it. 
 

source/ripe-validator/configuration.rst

@@ -1,7 +1,7 @@
 .. _doc_ripe_validator_configuration:
 
 Configuration
--------------
+=============
 
 Placeholder
 

source/ripe-validator/installation.rst

@@ -1,7 +1,7 @@
 .. _doc_ripe_validator_installation:
 
 Installation
-------------
+============
 
 Placeholder
 

source/routinator/configuration.rst

@@ -1,7 +1,7 @@
 .. _doc_routinator_configuration:
 
 Configuration
--------------
+=============
 
 Placeholder
 

source/routinator/index.rst

@@ -1,6 +1,8 @@
 Routinator
 ==========
 
+Routinator is free, open source RPKI Relying Party software written in the Rust programming language. It is designed to be lightweight and have great portability. This means it can run on any Unix-like operating system, but also works on Microsoft Windows. Due to its lean design, it can run effortlessly on minimalist hardware such as a Raspberry Pi. 
+
 .. toctree::
    :maxdepth: 2
    :name: toc-routinator

source/routinator/installation.rst

@@ -1,14 +1,202 @@
 .. _doc_routinator_installation:
 
 Installation
-------------
+============
 
-We are not distributing binary packages just yet, but getting started with Routinator is really easy. There are three things you need: rsync, Rust and a C toolchain. You need rsync because the RPKI repository currently uses rsync as its main means of distribution. You need Rust because that’s what the Routinator has been written in. Some of the cryptographic primitives used by the Routinator require a C toolchain, so you need that, too. 
+At this time, there are no binary packages for Routinator yet, but getting
+started with Routinator 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>`_. 
 
-You can run Routinator on a UNIX-like operating system in just a couple of steps. Assuming you have rsync and the C toolchain but not yet Rust, here’s how you get the the application to run as an RTR server listening on 127.0.0.1 port 3323:
-::
+Quick Start
+-----------
+
+Assuming you have rsync and the C toolchain but not yet Rust, here’s how
+you get the Routinator to run as an RTR server listening on 127.0.0.1 port
+3323:
+
+:: code-block:: bash
 
    curl https://sh.rustup.rs -sSf | sh
    source ~/.cargo/env
    cargo install routinator
-   routinator rtrd -l 127.0.0.1:3323
+   routinator rtrd -l 127.0.0.1:3323
+
+If you have an older version of the Routinator, you can update via
+
+:: code-block:: bash
+
+   cargo install -f routinator
+
+
+Quick Start with Docker
+-----------------------
+
+Due to the impracticality of complying with the ARIN TAL distribution terms
+in an unsupervised Docker environment, prior to launching the container it
+is necessary to first review and agree to the ARIN TAL terms available at
+https://www.arin.net/resources/rpki/tal.html
+
+The ARIN TAL RFC 7730 format file available at that URL will then need to
+be downloaded and mounted into the docker container as a replacement for
+the dummy arin.tal file that is shipped with Routinator.
+
+:: code-block:: bash
+
+   # Create a local directory for the RPKI cache
+   sudo mkdir -p /etc/routinator/tals
+   # Fetch the ARIN TAL (after agreeing to the distribution terms as described above)
+   sudo wget https://www.arin.net/resources/rpki/arin-rfc7730.tal -P /etc/routinator/tals
+   # Launch a detached container named 'routinator' (will listen on 0.0.0.0:3323 and expose that port)
+   sudo docker run -d --name routinator -p 3323:3323 -v /etc/routinator/tals/arin-rfc7730.tal:/root/.rpki-cache/tals/arin.tal nlnetlabs/routinator
+
+
+Getting Started
+---------------
+
+There are three things you need for Routinator: rsync, Rust and a C toolchain. You can install the Routinator on any Operating System when you can fulfil these requirements, so this inclused any UNIX-like OS, as well as Microsoft Windows.
+
+You need rsync because the RPKI repository currently uses rsync as its main
+means of distribution. You need Rust because that’s what the Routinator has
+been written in. Some of the cryptographic primitives used by the Routinator
+require a C toolchain, so you need that, too.
+
+### rsync
+
+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
+[Cygwin](https://www.cygwin.com/) – make sure to select rsync during the
+installation phase. And yes, Routinator totally works on Windows, too.
+
+If you don’t have rsync, please head to http://rsync.samba.org/
+
+### Rust
+
+While some system distributions include Rust as system packages,
+Routinator relies on a relatively new version of Rust, currently 1.30 or
+newer. We therefore suggest to use the canonical Rust installation via a
+tool called *rustup.*
+
+To install *rustup* and Rust, simply do:
+
+```bash
+curl https://sh.rustup.rs -sSf | sh
+```
+
+or, alternatively, get the file, have a look and then run it manually.
+Follow the instructions to get rustup and cargo, the rust build tool, into
+your path.
+
+You can update your Rust installation later by simply running
+
+```bash
+rustup update
+```
+
+### C Toolchain
+
+Some of the libraries Routinator depends on require a C toolchain to be
+present. Your system probably has some easy way to install the minimum
+set of packages to build from C sources. If you are unsure, try to run
+`cc` on a command line and if there’s a complaint about missing input
+files, you are probably good to go.
+
+## Building and Running
+
+The easiest way to get Routinator is to leave it to cargo by saying
+
+```bash
+cargo install routinator
+```
+
+If you want to try the master branch from the repository instead of a
+release version, you can run
+
+```bash
+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
+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.
+
+There are currently two major functions of the Routinator: printing the
+list of valid route origins, also known as _Validated ROA Payload_ or VRP,
+and providing the service for routers to access this list via a protocol
+known as RPKI-to-Router protocol or RTR.
+
+These (and all other functions) of Routinator are accessible on the
+command line via sub-commands. The commands are `vrps` and `rtrd`,
+respectively.
+
+So, to have Routinator print the list, you say
+
+```bash
+routinator vrps
+```
+
+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.
+
+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`.
+
+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`
+sub-command:
+
+```bash
+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
+
+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.
+
+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
+
+```bash
+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
+seconds. That is, if you rather have Routinator validate every fifteen
+minutes, the above command becomes
+
+```bash
+routinator rtrd -a -l 192.0.2.13:3323 -l [2001:0DB8::13]:3323 --refresh=900
+```

source/rpki-client/configuration.rst

@@ -1,7 +1,7 @@
 .. _doc_rpki_client_configuration:
 
 Configuration
--------------
+=============
 
 Placeholder
 

source/rpki-client/installation.rst

@@ -2,7 +2,7 @@
 
 
 Installation
-------------
+============
 
 Placeholder
 

source/rpki/creating-roas.rst

@@ -1,7 +1,7 @@
 .. _doc_rpki_roas:
 
 Creating Route Origin Authorisations
-------------------------------------
+====================================
 
 A Route Origin Authorisation object consists of three elements: the AS Number that you authorise, the prefix that is being originated from it and, lastly, the Maximum Length (MaxLength), which determines the most specific prefix that the AS may originate out of the aggregate. Keep in mind that a single ROA makes the announcement of a prefix from an authorised AS valid, but at the same time, it makes the announcement from an unauthorised (hijacking) AS invalid. You should create as many ROAs as needed to make all legitimate announcements valid.
 

source/rpki/hosted-vs-delegated-rpki.rst

@@ -1,7 +1,7 @@
 .. _doc_rpki_hosted_delegated:
 
 Hosted versus Delegated RPKI
-----------------------------
+============================
 
 The five RIRs are responsible for allocating IP addresses and Autonomous System Numbers in each of their regions. In most cases they allocate resources directly to their members, called Local Internet Registries (LIRs). In turn, LIRs assign resources to ISPs or end user organisations. There is an exception in the APNIC and LACNIC region, where in some countries allocations are handled through National Internet Registry (NIR) organisations to meet particular geographical needs. For example, JPNIC in Japan and NIC.br in Brazil provide these services on a national level.
 

source/rpki/introduction.rst

@@ -1,7 +1,7 @@
 .. _doc_rpki_introduction:
 
 Introduction
-++++++++++++
+============
 
 The global routing system of the Internet consists of a number of functionally independent actors (Autonomous Systems) which use BGP (Border Gateway Protocol) to exchange routing information. The system is very dynamic and flexible by design. Connectivity and routing topologies are subject to change. Changes easily propagate globally within a few minutes. One weakness of this system is that these changes cannot be validated against information existing outside of the BGP protocol itself.
 

source/rpki/route-origin-validation.rst

@@ -1,7 +1,7 @@
 .. _doc_rpki_rov:
 
 Route Origin Validation
------------------------
+=======================
 
 Routing errors on the Internet can be classified as route leaks or route hijacks. A route leak is a propagation of one or more routing announcements that are beyond their intended scope. That is an announcement from an Autonomous System (AS) of a learned BGP route to another AS is in violation of the intended policies of the receiver, the sender, and/or one of the ASes along the preceding AS path.
 
@@ -18,7 +18,7 @@ Using the RPKI system, the legitimate holder of a block of IP addresses can make
 A ROA states which Autonomous System (AS) is authorised to originate a certain IP address prefix. In addition, it can determine the maximum length of the prefix that the AS is authorised to advertise. By comparing the BGP announcements to published ROAs, a network operator can decide to accept the announcement, drop it or treat it in any other way they choose.
 
 Route Announcement Validity
-+++++++++++++++++++++++++++
+---------------------------
 
 When a network operator creates a ROA for a certain combination of origin AS and prefix, this will have an effect on the RPKI validity of one or more route announcements. They can be:
 
@@ -29,7 +29,7 @@ When a network operator creates a ROA for a certain combination of origin AS and
 To understand how more specifics, less specifics and partial overlaps are treated, please refer to `section 2 of RFC 6811 <https://tools.ietf.org/html/rfc6811#section-2>`_.
 
 Path Validation
-+++++++++++++++
+---------------
 
 Currently, RPKI only provides origin validation. While path validation is a desirable characteristic, the existing RPKI origin validation functionality addresses a large portion of the problem surface. 
 

source/rpki/router-support.rst

@@ -1,7 +1,7 @@
 .. _doc_rpki_rtr:
 
 Router Support
---------------
+==============
 
 Placeholder
 

source/rpki/using-rpki-data.rst

@@ -1,7 +1,7 @@
 .. _doc_rpki_relying_party:
 
 Using RPKI Data
----------------
+===============
 
 Operators who want to use RPKI data in their BGP decision making process have to fetch and validate all of the published data. As with any Public Key Infrastructure, you have to start with one or more entities you are prepared to trust. In the case of RPKI, these are the five RIRs. When you want to retrieve all RPKI data, you connect to the Trust Anchor that each of them provides.