nlnetlabs-routinator/doc/routinator.1

.TH "routinator" "1" "Febuary 15, 2018" "NLnet Labs" "routinator 0.3.0
.\"
.\" routinator.1 -- RPKI Relying Party software
.\"
.\" Copyright (c) 2018, NLnet Labs.
.\"
.\" See LICENSE for the license.
.\"
.\"
.SH "NAME"
.B routinator
\- RPKI relying party software
.SH "SYNOPSIS"
.B routinator
.RB [ \-b
.IR base-dir ]
.RB [ \-r
.IR repository-dir ]
.RB [ \-t
.IR tal-dir ]
.RB [ \-x
.IR exceptions-file
.RB [ \-x
.IR exceptions-file
[...]]]
.RB [ \-\-strict ]
.RB [ \-\-rsync\-command=\fIcommand\fR]
.RB [ \-\-rsync\-args=\fIargs\fR]
.RB [ \-\-rsync-count=\fIcount\fR]
.RB [ \-\-validation-threads=\fIcount\fR]
.RB [ \-v | \c
.BR \-vv | \c
.BR \-q  | \c
.BR \-qq ]
.RB [ \-h ]
.RB [ \-V ]
command
[args]
.PP
.B routinator
[options]
.B vrps
.RB [ \-o
.IR output-file ]
.RB [ \-f
.IR format ]
.RB [ \-n
]
.PP
.B routinator
[options]
.B rtrd
.RB [ \-l
.I addr:port
.RB [ \-l
.I addr:port
[...]]]
.RB [ \-\-refresh
.IR seconds ]
.RB [ \-\-retry
.IR seconds ]
.RB [ \-\-expire
.IR seconds ]
.RB [ \-\-history
.IR count ]
.PP
.B routinator
[options]
.B update
.PP
.B routinator
.B man
.RB [ \-o
.IR file ]


.SH "DESCRIPTION"
Routinator
collects and processes Resource Public Key Infrastructure (RPKI) data. It
validates the route origin attestations contained in the data and makes
them available to your BGP routing workflow.
.P
It can either run in one-shot mode outputting a list of validated route
origins in various formats or as a server for the RPKI-to-Router (RTR)
protocol that routers often implement to access the data.
.P
These modes and additional operations can be chosen  via commands. For
the available commands, see
.B COMMANDS
below.
.SH "OPTIONS"
.P
The available options are:
.TP
.BI \-c\  path \fR,\ \fB\-\-config= path
Provides the path to a file containing basic configuration. If this option
is not given, Routinator will try to use
.I $HOME/.routinator.conf
if that exists. If that doesn't exist, either, default values for the
options as descrined here are used.
.IP
See
.B CONFIGURATION FILE
below for more information on the format and contents of the configuration
file.
.TP
.BI \-b\  dir \fR,\ \fB\-\-base\-dir= dir
Specifies the base directory to keep status information in. Unless
overwritten by the
.B -r
or
.B -t
options, the local repository will be kept in the sub-directory
.I repository
and the TALs will be kept in the sub-directory
.I tals\fR.
.IP
If omitted, the base directory defaults to
.I $HOME/.rpki-cache\fR.
.TP
.BI \-r\  dir \fR,\ \fB\-\-repository\-dir= dir
Specifies the directory to keep the local repository in. This is the place
where Routinator stores the RPKI data it has collected and thus is a copy of
all the data referenced via the trust anchors.
.TP
.BI \-t\  dir \fR,\ \fB\-\-tal\-dir= dir
Specifies the directory containing the trust anchor locators (TALs) to use.
Trust anchor locators are the starting points for collecting and validating
RPKI data. See
.B TRUST ANCHOR LOCATORS
for more information on what should be present in this directory.
.TP
.BI \-x\  file \fR,\ \fB\-\-exceptions= file
Provides the path to a local exceptions file. The option can be used
multiple times to specify more than one file to use. Each file is a JSON
file as described in RFC 8416. It lists both route origins that should be
filtered out of the output as well as origins that should be added.
.TP
.BR \-\-strict
If this option is present, the repository will be validated in strict mode
following the requirements laid out by the standard documents very closely.
With the current RPKI repository, using this option will lead to a rather
large amount of invalid route origins and should therefore not be used in
practice.
.IP
See
.B RELAXED VALIDATION
below for more information.
.TP
.BI \-\-rsync\-command= command
Provides the command to run for rsync. This is only the command itself.
If you need to provide options to rsync, use the
.B rsync\-args
configuration file setting instead.
.IP
If this option is not given, Routinator will simply run
.I rsync
and hope that it is in the path.
.TP
.BI \-\-rsync\-count= count
Sets the maximum number of rsync commands to be run in parallel. The default
is 4.
.TP
.BI \-\-validation\-threads= count
Sets the number of threads to distribute work to for validation. Note that
the current processing model validates trust anchors all in one go, so you
are likely to see less than that number of threads used throughout the
validation run.
.TP
.BR \-v ,\  \fB\-\-verbose
Print more information. If given twice, even more information is printed.
.IP
More specifically, a single
.B -v
increases the log level from the default of
.I warn
to
.I info\fR,
specifying it more than once increases it to
.I debug\fR.
.TP
.BR \-q ,\  \fB\-\-quiet
Print less information. Given twice, print nothing at all.
.IP
A single
.B -q
will drop the log level to
.I error\fR.
Repeating 
.B -q
more than once turns logging off completely. 
.TP
.BR \-\-syslog
Redirect logging output to syslog.
.IP
This option is implied if a command is used that causes Routinator to run
in daemon mode.
.TP
.BI \-\-syslog-facility= facility
If logging to syslog is used, this option can be used to specify the syslog
facility to use. The default is
.I daemon\fR.
.TP
.BI \-\-logfile= path
Redirect logging output to the given file.
.TP
.BR \-h , " \-\-help"
Print some help information.
.TP
.BR \-V , " \-\-version
Print version information.

.SH COMMANDS
Routinator provides a number of operations around the local RPKI repository.
These can be requested by providing different commands on the command line.

.SS vrps
This command requests that Routinator update the local repository and then
validate the Route Origin Authorizations in the repository and output the
valid route origins, which are also known as Valid ROA Payload or VRPs, as
a list.
.TP
.BI -o\  file \fR,\ \fB\-\-output= file
Specifies the output file to write the list to. If this option is missing
or file is
.I "-"
the list is printed to standard output.
.TP
.BI -f\  format \fR,\ \fB\-\-format= format
The output format to use. Routinator currently supports the following formats:
.RS
.TP
.B 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
.IR ".tal" .
.IP
This is the default format used if the
.B -f
option is missing.
.TP
.B csvext
An extended version of
.I csv
each line contains these comma-separated values: the rsync URI of the ROA
the line is taken from (or "N/A" if it isn't from a ROA), the autonomous
system number, the prefix in slash notation, the maximum prefix length, the
not-before date and not-after date of the validity of the ROA.
.IP
This format was used in the RIPE NCC Validator version 1. That version
produce one file per trust anchor. This is not currently supported by
Routinator -- all entries will be in one single output file.
.TP
.B json
The list is placed into a JSON object with a single element
.I "roas"
which contains an array of objects with four elements each: The autonomous
system number of the network authorized to originate a prefix in
.IR "asn" ,
the prefix in slash notation in
.IR "prefix" ,
the maximum prefix length of the announced route in
.IR "maxLength" ,
and the trust anchor from which the authorization was derived in
.IR "ta" .
This format is identical to that produced by the RIPE NCC validator except
for different naming of the trust anchor. Routinator uses the name of the
TAL file without the extension
.IR ".tal"
whereas the RIPE NCC Validator has a dedicated name for each.
.TP
.B openbgpd
Choosing this format causes Routinator to produce a
.I "roa-set"
configuration item for the OpenBGPD configuration.
.TP
.B rpsl
This format produces a list of RPSL objects with the authorization in the
fields
.IR route ,
.IR origin ,
and
.IR source .
In addition, the fields
.IR descr ,
.IR mnt-by ,
.IR created ,
and
.IR last-modified ,
are present with more or less meaningful values.
.TP
.B none
This format produces no output whatsoever.
.RE
.TP
.BR \-n ,\  \-\-noupdate
The repository will not be updated before producing the list.

.SS rtrd
This command causes Routinator to act as a server for the RPKI-to-Router
protocol (RTR). In this mode, Routinator will read all the TALs (See
.B TRUST ANCHOR LOCATORS
below) and will then detach from the terminal unless the
.B -a
option is given.
.PP
The server will periodically update the local repository, hourly by default,
notify any clients of changes, and let them fetch validated data. It will not,
however, reread the trust anchor locators. Thus, if you update them, you will
have to restart Routinator.
.PP
Routinator supports both protocol version 0 defined in RFC 6810 and version
1 defined in RFC 8210. However, it does not support router keys introduced
in version 1.
.TP
.BI \-l\  addr:port\fR,\ \fB\-\-listen=\fIaddr:port
Specifies the local address and port to listen on for incoming RTR
connections. IPv6 addresses must be enclosed in square brackets. You can
provide the option multiple times to let Routinator listen on multiple
address-port pairs.
.IP
If this options is omitted, Routinator will listen on
.BR 127.0.0.1:3323 .
Note how this is a localhost address for security reasons. We also don't
use the standard RTR port 323 as this is a privileged port that would
require Routinator to be run as root or otherwise receive permission which
otherwise isn't necessary at all.
.IP
Routinator will only start listening on these ports after an intitial
validation run has finished.
.TP
.BI \-\-listen\-http= addr:port
Specifies the address and port to listen on for incoming HTTP connections.
See
.B HTTP SERVICE
below for more information on the HTTP service provided by Routinator.
.IP
If this option is omitted, no HTTP service will be provided.

.TP
.BI \-\-refresh= seconds
The amount of seconds the server should wait after having finished updating
and validating the local repository before starting to update again. The
default value is 3600 seconds.
.TP
.BI \-\-retry= seconds
The amount of seconds to suggest to an RTR client to wait before trying to
request data again if that failed. The default value is 600 seconds, the
value recommended in RFC 8210.
.TP
.BI \-\-expire= seconds
The amount of seconds to an RTR client can keep using data if it cannot
refresh it. After that time, the client should discard the data. Note that
this value was introduced in version 1 of the RTR protocol and is thus not
relevant for clients that only implement version 0. The default value, as
recommended in RFC 8210, is 7200 seconds.
.TP
.BI \-\-history= count
In RTR, a client can request to only receive the changes that happened since
the last version of the data it had seen. This option sets how many change
sets the server will at most keep. If a client requests changes from an older
version, it will get the current full set.
.IP
Note that routers typically stay connected with their RTR server and therefore
really only ever need one single change set. Additionally, if RTR server or
router are restarted, they will have a new session with new change sets and
need to exchange a full data set, too. Thus, increasing the value probably
only ever increases memory consumption.
.IP
The default value is 10.
.TP
.BI \-\-pid\-file= path
States a file which will be used in daemon mode to store the processes PID.
While the process is running, it will keep the file locked.
.TP
.BI \-\-working\-dir= path
The working directory for the daemon process. In daemon mode, Routinator
will change to this directory while detaching from the terminal.
.TP
.BI \-\-chroot= path
The root directory for the daemon process. If this option is provided, the
daemon process will change its root directory to the given directory. This
will only work if all other paths provided via the configuration or command
line options are under this directory.

.SS update
Updates the local repository by resyncing all known publication points. The
command will also validate the updated repository to discover any new
publication points that appear in the repository and fetch their data.
.PP
As such, the command really is a shortcut for running
.B routinator vrps -f none\fR.

.SS man
Displays the manual page, i.e., this page.
.TP
.BI -o\  file \fR,\ \fB\-\-output= file
If this option is provided, the manual page will be written to the given
file instead of displaying it. Use
.I "-"
to output the manual page to standard output.


.SH TRUST ANCHOR LOCATORS
RPKI uses trust anchor locators, or TALs, to identify the location and
public keys of the trusted root CA certificates. Routinator keeps these
TALs in files in the TAL directory which can be set by the
.B \-t
option. If the
.B \-b
option is used instead, the TAL directory will be in the sub-directory
.I tals
under the directory specified in this option. The default location, if
no options are used at all is
.I $HOME/.rpki-cache/tals\fR.
.P
If the specified or default directory does not exist, Routinator will try
to create it and populate it with the TALs of the five Regional Internet
Registries (RIRs). Unfortunately, the terms and conditions of the
North American registry ARIN do not allow us to include their TAL with the
Routinator. We instead include a crippled version that will cause
Routinator to refuse to work and print instructions on how to get the
TAL instead.
.P
If the directory does exist, Routinator will use all files with an extension
of
.I .tal
in this directory. This means that you can add and remove trust anchors by
adding and removing files in this directory. If you add files, make sure they
are in RFC 7730 format.

.SH CONFIGURATION FILE
Instead of providing all options on the command line, they can also be
provided through a configuration file. Such a file can be selected through
the
.B -c
option. If no configuration file is specified this way but a file named
.I $HOME/.routinator.conf
is present, this file is used.
.PP
The configuration file is a file in TOML format. In short, it consists of
a sequence of key-value pairs, each on its own line. Strings are to be
enclosed in double quotes. Lists can be given by enclosing a comma-separated
list of values in square brackets.
.PP
The configuration file can contain the following entries. All path values
are interpreted relative to the directory the configuration file is located.
in. All values can be overwritten via the command line options.
.TP
.B repository-dir
A string containing the path to the directory to store the local repository
in. This entry is mandatory.
.TP
.B tal-dir
A string containing the path to the directory that contains the Trust Anchor
Locators. This entry is mandatory.
.TP
.B exceptions
A list of strings, each containing the path to a file with local exceptions.
If missing, no local exception files are used.
.TP
.B strict
A boolean specifying whether strict validation should be employed. If missing,
strict validation will not be used.
.TP
.B rsync-command
A string specifying the command to use for running rsync. The default is
simply
.IR rsync .
.TP
.B rsync-args
A list of strings containing the arguments to be passed to the rsync command.
Each string is an argument of its own.
.PP
If this
option is not provided, Routinator will try to find out if your rsync
understands the
.B \-\-contimeout
option and, if so, will set it to 10 thus letting connection attempts time
out after ten seconds. If your rsync is too old to support this option, no
arguments are used.
.TP
.B rsync-count
An integer value specifying the number of rsync commands that should at most
be run in parallel. The default if this value is missing is 4 commands.
.TP
.B validation-threads
An integer value specifying the number of threads to be used during
validation of the repository. If this value is missing, the number of CPUs
in the system is used.
.TP
.B log-level
A string value specifying the maximum log level for which log messages should
be emitted. The default is
.IR warn .
.TP
.B log
A string specifying where to send log messages to. This can be one of the
following values:
.RS
.TP
.I default
Log messages will be sent to standard error if Routinator stays attached to
the terminal or to syslog if it runs in daemon mode.
.TP
.I stderr
Log messages will be sent to standard error.
.TP
.I syslog
Log messages will be sent to syslog.
.TP
.I file
Log messages will be sent to the file specified through the
.B log-file
configuration file entry.
.RE
.IP
The default if this value is missing is, unsurprisingly,
.IR default .
.TP
.B log-file
A string value containing the path to a file to which log messages will be
appended if the
.B log
configuration value is set to
.IR file .
In this case, the value is mandatory.
.TP
.B syslog-facility
A string value specifying the syslog facility to use for logging to syslog.
The default value if this entry is missing is
.IR daemon .
.TP
.TP
.B listen-tcp
An array of string values each providing the address and port which the RTR
daemon should listen on in TCP mode. Address and port should be separated by
a colon. IPv6 address should be enclosed in square braces.
.TP
.B listen-http
An array of string values each providing the address and port which the HTTP
service should listen on. Address and port should be separated by
a colon. IPv6 address should be enclosed in square braces.
.B refresh
An integer value specifying the number of seconds Routinator should wait
between consecutive validation runs in RTR server mode. The default is
3600 seconds.
.TP
.B retry
An integer value specifying the number of seconds an RTR client is requested
to wait after it failed to receive a data set. The default is 600 seconds.
.TP
.B expire
An integer value specifying the number of seconds an RTR client is requested
to use a data set if it cannot get an update before throwing it away and
continuing with no data at all. The default is 7200 seconds.
if it cannot get an update before throwing it away and
continuing with no data at all. The default is 7200 seconds.
.TP
.B history-size
An integer value specifying how many change sets Routinator should keep in
RTR server mode. The default is 10.
.TP
.B pid-file
A string value containing a path pointing to the PID file to be used in
daemon mode.
.TP
.B working-dir
A string value containing a path to the working directory for the daemon
process.
.TP
.B chroot
A string value containing the path any daemon process should use as its
root directory.

.SH HTTP SERVICE
When run in
.B rtrd
mode, Routinator can provide an HTTP service in addtion to the RTR service.
The primary intention of this service is to allow integration into
monitoring systems. For this reason, the service does not support HTTPS and
should only be used within the local network.
.P
The service only supports GET requests with the following
paths:

.TP
.B /csv
Returns the current set of VRPs in
.B csv
output format.
.TP
.B /json
Returns the current set of VRPs in
.B json
output format.
.TP
.B /metrics
Returns a set of monitoring metrics in the format used by Prometheus.
.TP
.B /openbgpd
Returns the current set of VRPs in
.B openbgpd
output format.
.TP
.B /rpsl
Returns the current set of VRPs in
.B rpsl
output format.
.TP
.B /version
Returns the version of the Routinator instance.

.SH RELAXED VALIDATION
The documents defining RPKI include a number of very strict rules
regarding the formatting of the objects published in the RPKI repository.
However, because PRKI reuses existing technology, real-world applications
produce objects that do not follow these strict requirements.
.PP
As a consequence, a significant portion of the RPKI repository is actually
invalid if the rules are followed. We therefore introduce two validation
modes: strict and relaxed. Strict mode rejects any object that does not
pass all checks laid out by the relevant RFCs. Relaxed mode ignores a
number of these checks.
.PP
This memo documents the violations we encountered and are dealing with in
relaxed validation mode.

.SS Resource Certificates (RFC 6487)

Resource certificates are defined as a profile on the more general
Internet PKI certificates defined in RFC 5280.

.TP
.B Subject and Issuer
The RFC restricts the type used for CommonName attributes to
PrintableString, allowing only a subset of ASCII characters, while RFC
5280 allows a number of additional string types. At least one CA produces
resource certificates with Utf8Strings.
.IP
In relaxed mode, we will only check that the general structure of the
issuer and subject fields are correct and allow any number and types of
attributes. This seems justified since RPKI explicitly does not use these
fields.

.SS Signed Objects (RFC 6488)
Signed objects are defined as a profile on CMS messages defined in RFC
5652.
.TP
.B DER Encoding
RFC 6488 demands all signed objects to be DER encoded while the more
general CMS format allows any BER encoding -- DER is a stricter subset of
the more general BER. At least one CA does indeed produce BER encoded
signed objects.
.IP
In relaxed mode, we will allow BER encoding.
.IP
Note that this isn't just nit-picking. In BER encoding, octet strings can
be broken up into a sequence of sub-strings. Since those strings are in
some places used to carry encoded content themselves, such an encoding
does make parsing significantly more difficult. At least one CA does
produce such broken-up strings.

.SH AUTHOR
.P
Jaap Akkerhuis wrote the original version of this manual page,
Martin Hoffmann extended it for later versions.
.SH "EXIT CODE"
The Routinator program exits with status code 1 on error, 
.SH BUGS
Sure