mirror/nlnetlabs-routinator
1
0
Fork 0
mirror of https://github.com/NLnetLabs/routinator.git synced 2024-05-19 06:50:04 +00:00
Code Issues Releases Activity

Merge pull request #689 from NLnetLabs/docs-tls-support

Browse Source 
Docs for native TLS support
This commit is contained in:
Alex Band
2022-01-24 12:10:16 +01:00
committed by GitHub
parent c006192983 78d39ade8b
commit c09a503750
4 changed files with 160 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
doc/manual/source/daemon.rst
View File

@ -1,24 +1,26 @@
Running as a Daemon
===================
Routinator can run as a service that periodically fetches RPKI data, verifies it
and makes the resulting data set available through the built-in HTTP server and
via the RTR protocol.
Routinator can run as a service that periodically fetches RPKI data, verifies
it and makes the resulting data set available through the built-in HTTP
server and via the RTR protocol.
If you have installed Routinator through our software package repository, the
RTR and HTTP servers are only available on localhost for security reasons. You
will have to explicitly change this setting in the :doc:`configuration
RTR and HTTP servers are only available on localhost for security reasons.
You will have to explicitly change this setting in the :doc:`configuration
file<configuration>` to make the services available to other machines.
When you have installed Routinator using Cargo, no servers are enbled by default
at all. You can start the Routinator service using the :subcmd:`server`
subcommand and specifying to start the HTTP server with the :option:`--http`
option and the RTR server with the :option:`--rtr` option. You can of course
also start both.
When you have installed Routinator using Cargo, no servers are enbled by
default at all. You can start the Routinator service using the
:subcmd:`server` subcommand and specifying to start the HTTP server with the
:option:`--http` option and the RTR server with the :option:`--rtr` option.
You can of course also start both. HTTPS and RTR-over-TLS are supported
natively as well.
.. Note:: Routinator will not reread the trust anchor locators after it has
started the service. Thus, if you add or change a TAL you must restart
Routinator or send it a :ref:`SIGUSR1 <manual-page:signals>`.
started the service. Thus, if you add or change a TAL you must
restart Routinator or send it a
:ref:`SIGUSR1 <manual-page:signals>`.
If you're running Routinator on the IPv4 address 192.0.2.13 and you want to
start the HTTP server on port 8323 and the RTR server on port 3323, run:
@ -37,23 +39,18 @@ Both servers will only start serving data once the first validation run has
completed.
By default Routinator will stay attached to your terminal and log to standard
error. You can provide the :option:`--detach` option to run it in the background
instead, in which case logging information is written to syslog. To learn more
about what kind of information is returned and how to influence what is logged
and where, refer to the :doc:`logging` section.
error. You can provide the :option:`--detach` option to run it in the
background instead, in which case logging information is written to syslog.
To learn more about what kind of information is returned and how to influence
what is logged and where, refer to the :doc:`logging` section.
.. Attention:: On Linux systems there is an overlap between IPv4 and IPv6. You
can’t bind to all interfaces on both address families on the
same port. For example, this command will result in a *‘address
already in use’* error:
.. code-block:: text
routinator server --rtr 0.0.0.0:3323 --rtr [::]:3323
Instead, to listen to both IPv4 and IPv6 you can simply enter:
.. Attention:: On Linux systems there is an overlap between IPv4 and IPv6.
You can’t bind to all interfaces on both address families,
i.e. ``0.0.0.0`` and ``[::]``, as it will result in a
*‘address already in use’* error. Instead, to listen to both
IPv4 and IPv6 you can simply enter:
.. code-block:: text
.. code-block:: text
routinator server --rtr [::]:3323
routinator server --rtr [::]:3323

92
doc/manual/source/http-service.rst
View File

@ -2,35 +2,34 @@ HTTP Service
============
In addition to the various :doc:`VRP output formats<output-formats>`,
Routinator's HTTP server also provides a :doc:`user interface<user-interface>`,
an :doc:`API<api-endpoints>`, :doc:`monitoring<monitoring>` and
:doc:`logging<logging>` endpoints.
Routinator's HTTP server also provides a :doc:`user
interface<user-interface>`, an :doc:`API<api-endpoints>`,
:doc:`monitoring<monitoring>` and :doc:`logging<logging>` endpoints.
The HTTP server is not enabled by default for security reasons, nor does it have
a default host or port. This service is intended to run on your internal network
and doesn't offer HTTPS natively. If this is a requirement, you can for example
run Routinator behind a :ref:`reverse proxy <user-interface:reverse proxy with
nginx>`.
The HTTP server is not enabled by default for security reasons, nor does it
have a default host or port. Routinator natively supports `TLS Transport`_,
but the endpoints are set up in such a way that it's easy to configure a
:ref:`reverse proxy <http-service:using a reverse proxy>` as well.
In order to start the HTTP server at 192.0.2.13 and 2001:0DB8::13 on port 8323,
run:
In order to start the HTTP server at 192.0.2.13 and 2001:0DB8::13 on port
8323, run:
.. code-block:: text
routinator server --http 192.0.2.13:8323 --http [2001:0DB8::13]:8323
After fetching and verifying all RPKI data, paths are available for each
:doc:`VRP output format <output-formats>`. For example, at the ``/csv`` path you
can fetch a list of all VRPs in CSV format.
:doc:`VRP output format <output-formats>`. For example, at the ``/csv`` path
you can fetch a list of all VRPs in CSV format.
.. code-block:: text
curl http://192.0.2.13:8323/csv
These paths accept selector expressions to limit the VRPs returned in the form
of a query string. You can use ``select-asn`` to select ASNs and
``select-prefix`` to select prefixes. These expressions can be repeated multiple
times.
These paths accept selector expressions to limit the VRPs returned in the
form of a query string. You can use ``select-asn`` to select ASNs and
``select-prefix`` to select prefixes. These expressions can be repeated
multiple times.
For example, to only show the VRPs in JSON format authorising AS196615, use:
@ -52,4 +51,63 @@ This will produce the following output:
{ "asn": "AS196615", "prefix": "2001:7fb:fd04::/48", "maxLength": 48, "ta": "ripe" },
{ "asn": "AS196615", "prefix": "93.175.147.0/24", "maxLength": 24, "ta": "ripe" }
]
}
}
TLS Transport
-------------
Routinator offers native TLS suppport for both HTTP and :doc:`RTR
connections<rtr-service>`. In this example we'll start Routinator's HTTPS
server listening on the IP addresses 192.0.2.13 and 2001:0DB8::13 and use
port 8324.
First, indidate that you want a TLS connection with the :option:`--http-tls`
option. Then use the :option:`--http-tls-cert` option to specify the path to
a file containing the server certificates to be used. This file has to
contain one or more certificates encoded in PEM format. Lastly, use the
:option:`--http-tls-key` option to specify the path to a file containing the
private key to be used for HTTPS connections. The file has to contain exactly
one private key encoded in PEM format:
.. code-block:: text
routinator server --http-tls 192.0.2.13:8324 \
--http-tls [2001:0DB8::13]:8324 \
--http-tls-cert "/path/to/http-tls.crt" \
--http-tls-key "/path/to/http-tls.key"
Using a Reverse Proxy
---------------------
Though TLS is natively supported, it may be more convenient to set up a
reverse proxy to serve HTTPS data. This way you'll be using a production
grade web server that for example allows automation of certificate renewal.
For convenience, all the files and folders for the :doc:`user
interface<user-interface>` are hosted under the ``/ui`` path and the
:doc:`API endpoints<api-endpoints>` are under ``/api``. For example, this
allows you to just expose the UI and not any of the other paths, such as
those serving the various :doc:`VRP output formats<output-formats>`.
In this example we'll use NGINX, but other web servers will allow a similar,
simple configuration. To only expose the user interface, this is what your
configuration needs at a minimum when running it on the same server as
Routinator runs on, using port 8323.
Using the ``=`` modifier, the first entry only forwards if the path is
*exactly* ``/`` so that paths not explicitely mentioned, such as ``/json``,
are not forwarded. For more information, please refer to the `NGINX
documentation <https://nginx.org/en/docs/http/server_names.html>`_.
.. code-block:: text
location = / {
proxy_pass http://127.0.0.1:8323/;
}
location /ui {
proxy_pass http://127.0.0.1:8323/ui;
}
location /api {
proxy_pass http://127.0.0.1:8323/api;
}

110
doc/manual/source/rtr-service.rst
View File

@ -2,49 +2,85 @@ RTR Service
===========
Routinator has a built-in server for the RPKI-to-Router (RTR) protocol. It
supports :RFC:`8210` as well as the older version described in :RFC:`6810`. When
launched as an RTR server, routers with support for route origin validation
(ROV) can connect to Routinator to fetch the processed data.
supports :RFC:`8210` as well as the older version described in :RFC:`6810`.
When launched as an RTR server, routers with support for route origin
validation (ROV) can connect to Routinator to fetch the processed data.
.. Tip:: If you would like to run the RTR server as a separate daemon, for
example because you want to centralise validation and distribute
processed data to various locations where routers can connect, then
NLnet Labs provides :doc:`RTRTR<rtrtr:index>`.
In order to start the RTR server at 192.0.2.13 and 2001:0DB8::13 on port 3323,
run Routinator using the :subcmd:`server` subcommand:
In order to start the RTR server at 192.0.2.13 and 2001:0DB8::13 on port
3323, run Routinator using the :subcmd:`server` subcommand:
.. code-block:: text
routinator server --rtr 192.0.2.13:3323 --rtr [2001:0DB8::13]:3323
Please note that port 3323 is not the :abbr:`IANA (Internet Assigned Numbers
Authority)`-assigned default port for the protocol, which would be 323. But as
this is a privileged port, you would need to be running Routinator as root when
otherwise there is no reason to do that.
Communication between Routinator and the router using the RPKI-RTR protocol is
done via plain TCP. Below, there is an explanation how to secure the transport
using either SSH or TLS.
Authority)`-assigned default port for the protocol, which would be 323. But
as this is a privileged port, you would need to be running Routinator as root
when otherwise there is no reason to do that.
Secure Transports
-----------------
These instructions were contributed by `wk on Github
<https://github.com/NLnetLabs/routinator/blob/master/doc/transports.md>`_.
.. versionadded:: 0.11.0
RTR-over-TLS connections
:rfc:`6810#section-7` defines a number of secure transports for RPKI-RTR that
can be used to secure communication between a router and a RPKI relying party.
Although there is no mandatory-to-implement transport that provides
authentication and integrity protection, :rfc:`6810#section-7` defines a
number of secure transports for RPKI-RTR that can be used to secure
communications. This includes TLS, SSH, TCP MD5 and TCP-AO transports.
However, the RPKI Router Implementation Report documented in
:rfc:`7128#section-5` suggests these secure transports have not been widely
implemented. Implementations, however, do exist, and a secure transport could be
valuable in situations where the RPKI relying party is provided as a public
service, or across a non-trusted network.
Routinator currently has native support for TLS connections, and can be
configured to use `SSH Transport`_ with some additional tooling.
TLS Transport
"""""""""""""
It's possible to natively use RTR-over-TLS connections with Routinator. There
is an :abbr:`IANA (Internet Assigned Numbers Authority)`-assigned default
port for rpki-rtr-tls as well, in this case 324.
Currently, very few routers have implemented support for TLS, but it may be
especially useful to use secure connections when deploying our RTR data proxy
:doc:`RTRTR <rtrtr:index>`, as data may be flowing across the public
Internet.
In this example we'll start Routinator's RTR server listening on the IP
addresses 192.0.2.13 and 2001:0DB8::13 and use port 3324 to make sure it's
not a priviledged port.
First, indidate that you want a TLS connection with the :option:`--rtr-tls`
option. Then use the :option:`--rtr-tls-cert` option to specify the path to a
file containing the server certificates to be used. This file has to contain
one or more certificates encoded in PEM format. Lastly, use the
:option:`--rtr-tls-key` option to specify the path to a file containing the
private key to be used for RTR-over-TLS connections. The file has to contain
exactly one private key encoded in PEM format:
.. code-block:: text
routinator server --rtr-tls 192.0.2.13:3324 \
--rtr-tls [2001:0DB8::13]:3324 \
--rtr-tls-cert "/path/to/rtr-tls.crt" \
--rtr-tls-key "/path/to/rtr-tls.key"
If you want to securly connect to Routinator with RTRTR using the
:ref:`RTR-TLS Unit<rtrtr:configuration:rtr unit>`, a certificate that is
trusted by the usual set of web trust anchors will work with no additional
configuration. In case you generated a self-signed certificate for
Routinator, make sure to copy the certificate to your machine running RTRTR
and refer to the path of the file in your unit using the ``cacerts``
configuration option.
SSH Transport
"""""""""""""
These instructions were contributed by `Wild Kat <https://github.com/wk>`_.
SSH transport for RPKI-RTR can be configured with the help of `netcat
<http://netcat.sourceforge.net/>`_ and `OpenSSH <https://www.openssh.com/>`_.
@ -88,35 +124,3 @@ Make sure Routinator is running as an RTR server on localhost:
username rpki
password <password>
transport ssh port 22
TLS Transport
"""""""""""""
TLS transport for RPKI-RTR can be configured with the help of `stunnel
<https://www.stunnel.org/>`_.
1. Begin by installing the :program:`stunnel` package.
2. Make sure Routinator is running as an RTR server on localhost:
.. code-block:: text
routinator server --rtr 127.0.0.1:3323
3. Acquire (via for example `Let's Encrypt <https://letsencrypt.org/>`_) or generate an SSL certificate. In the example below, an SSL certificate for the domain example.com generated by Let's Encrypt is used.
4. Create an stunnel configuration file by editing :file:`/etc/stunnel/rpki.conf` or equivalent:
.. code-block:: text
[rpki]
; Use a letsencrypt certificate for example.com
cert = /etc/letsencrypt/live/example.com/fullchain.pem
key = /etc/letsencrypt/live/example.com/privkey.pem
; Listen for TLS rpki-rtr on port 323 and proxy to port 3323 on localhost
accept = 323
connect = 127.0.0.1:3323
5. Restart :program:`stunnel` to complete the process.

31
doc/manual/source/user-interface.rst
View File

@ -13,6 +13,9 @@ The application will stay attached to your terminal unless you provide the
user interface from the example above will be available at
http://192.0.2.13:8323/.
For more information, such as configuring TLS or using a reverse proxy,
please refer to the :doc:`http-service` section.
Prefix Check
------------
@ -62,31 +65,3 @@ developed and hosted by NLnet Labs at `bgp-api.net
- Resource allocations retrieved from `statistics
<https://www.nro.net/about/rirs/statistics/>`_ hosted by the five Regional
Internet Registries. These are updated daily.
Reverse Proxy with NGINX
------------------------
Routinator's built-in HTTP server is intended to run on your internal network
and doesn't offer HTTPS natively. If this is a requirement, you can for example
run Routinator behind an `NGINX <https://www.nginx.com>`_ reverse proxy.
For convenience, all the files and folders for the user interface are hosted
under the ``/ui`` path. This allows you to just expose the user interface and
not any of the other paths, such as those serving the various VRP output
formats.
To only make the user interface available through a reverse proxy, this is what
your NGINX configuration needs at a minimum when running it on the same server
as Routinator runs on, using port 8323:
.. code-block:: text
location = / {
proxy_pass http://127.0.0.1:8323/;
}
location /ui {
proxy_pass http://127.0.0.1:8323/ui;
}
location /api {
proxy_pass http://127.0.0.1:8323/api;
}