.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "RTRTR" "1" "Jul 23, 2024" "0.3.1-dev" "RTRTR"
.SH NAME
rtrtr \- RPKI data proxy
.SH SYNOPSIS
.sp
\fBrtrtr\fP [\fBoptions\fP]
.SH DESCRIPTION
.sp
RTRTR is an RPKI data proxy, designed to collect Validated ROA Payloads from
one or more sources in multiple formats and dispatch it onwards. It provides
the means to implement multiple distribution architectures for RPKI such as
centralised RPKI validators that dispatch data to local caching RTR servers.
.sp
RTRTR can read RPKI data from multiple RPKI Relying Party packages via RTR
and JSON and, in turn, provide an RTR service for routers to connect to. The
HTTP server provides the validated data set in JSON format, as well as a
monitoring endpoint in plain text and Prometheus format.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-c path, \-\-config=path
Provides the path to a file containing the configuration for RTRTR. See
\fI\%CONFIGURATION FILE\fP below for more information on the format and
contents of the file.
.sp
This option is required.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-verbose
Print more information. If given twice, even more information is
printed.
.sp
More specifically, a single \fI\%\-v\fP increases the log level from
the default of warn to \fIinfo\fP, specifying it more than once increases
it to \fIdebug\fP\&.
.sp
See \fI\%LOGGING\fP below for more information on what information is logged
at the different levels.
.UNINDENT
.INDENT 0.0
.TP
.B \-q, \-\-quiet
Print less information. Given twice, print nothing at all.
.sp
A single \fI\%\-q\fP will drop the log level to \fIerror\fP\&. Repeating
\fI\%\-q\fP more than once turns logging off completely.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-syslog
Redirect logging output to syslog.
.sp
This option is implied if a command is used that causes Routinator to
run in daemon mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-syslog\-facility=facility
If logging to syslog is used, this option can be used to specify the
syslog facility to use. The default is \fIdaemon\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-logfile=path
Redirect logging output to the given file.
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Print some help information.
.UNINDENT
.INDENT 0.0
.TP
.B \-V, \-\-version
Print version information.
.UNINDENT
.SH CONFIGURATION FILE
.sp
The configuration file describes how and from where RTRTR is collecting data,
how it processes it and how it should provide access to the resulting data
set or data sets.
.sp
The configuration file is a file in TOML format. 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. The file contains multiple sections, each started with a
name enclosed in square brackets.
.sp
The first section without a name at the beginning of the file provides
general configuration for RTRTR as a whole. It is followed by a single
section for each component to be started.
.sp
There are two types of components: \fIunits\fP and \fItargets\fP\&. Units take data
from somewhere and produce a single, constantly updated data set. Targets
take the data set from exactly one other unit and serve it in some specific
way.
.sp
Both units and targets have a name and a type that defines which particular
kind of unit or target this is. For each type, additional arguments need to
be provided. Which these are and what they mean depends on the type.
.sp
The section of a component is named by appending the name of the component to
its class. I.e., a unit named \fBfoo\fP would have a section name of
\fB[unit.foo]\fP while a target \fBbar\fP would have a section name of
\fB[target.bar]\fP\&.
.sp
The following reference lists all configuration options for the global
section as well as all options for each currently defined unit and target
type. For each option it states the name, type, and purpose. Any relative
path given as a configuration value is interpreted relative to the directory
the configuration file is located in.
.SH GLOBAL OPTIONS
.INDENT 0.0
.TP
.B http\-listen
A list of string values each specifying an address and port the HTTP
server should listen on. Address and port should be separated by a
colon. IPv6 address should be enclosed in square brackets.
.sp
RTRTR will listen on all address port combinations specified. All HTTP
endpoints will be available on all of them.
.TP
.B log\-level
A string value specifying the maximum log level for which log messages
should be emitted. The default is warn.
.TP
.B log
A string specifying where to send log messages to. This can be
one of the following values:
.INDENT 7.0
.TP
.B 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
.B stderr
Log messages will be sent to standard error.
.TP
.B syslog
Log messages will be sent to syslog.
.TP
.B file
Log messages will be sent to the file specified through
the log\-file configuration file entry.
.UNINDENT
.sp
The default if this value is missing is, unsurprisingly, default.
.TP
.B log\-file
A string value containing the path to a file to which log messages will
be appended if the log configuration value is set to 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 daemon.
.UNINDENT
.SH RTR UNITS
.sp
There are two units that download RPKI data sets from an upstream server
using the RPKI\-to\-Router protocol (RTR). The unit of type \fB\(dqrtr\(dq\fP uses
unencrypted RTR while \fB\(dqrtr\-tls\(dq\fP uses RTR over TLS.
.sp
The RTR units have the following configuration options:
.INDENT 0.0
.TP
.B remote
A string value specifying the remote server to connect to. The string
must contain both an address and a port separated by a colon. The
address can be given as a an IP address, enclosed in square brackets
for IPv6, or a host name.
.sp
For the \fB\(dqrtr\-tls\(dq\fP unit, the address portion will be used to verify
the server certificate against.
.sp
This option is mandatory.
.TP
.B retry
An integer value specifying the number of seconds to wait before trying
to reconnect to the server if it closed the connection.
.sp
If this option is missing, the default of 60 seconds is used.
.TP
.B cacerts
Only used with the \fB\(dqrtr\-tls\(dq\fP type, a list of paths to files that
contain one or more PEM encoded certificates that should be trusted
when verifying a TLS server certificate.
.sp
The \fB\(dqrtr\-tls\(dq\fP unit also uses the usual set of web trust anchors, so
this option is only necessary when the RTR server doesn’t use a server
certificate that would be trusted by web browser. This is, for
instance, the case if the server uses a self\-signed certificate in
which case this certificate needs to be added via this option.
.UNINDENT
.SH JSON UNIT
.sp
A unit of type \fB\(dqjson\(dq\fP imports and updates an RPKI data set through a
JSON\-encoded file. It accepts the JSON format used by most relying party
packages.
.sp
The \fB\(dqjson\(dq\fP unit has the following configuration options:
.INDENT 0.0
.TP
.B uri
A string value specifying the location of the JSON file expressed as a
URI.
.sp
If this is an \fBhttp:\fP or \fBhttps:\fP URI, the unit will download the
file from the given location.
.sp
If this is a \fBfile:\fP URI, the unit will load the given local file.
Note that the unit just uses the path as given, so relative paths will
interpreted relative to the current directory, whatever that may be.
.TP
.B refresh
An integer value specifying the number of seconds to wait before
attempting to re\-fetch the file.
.sp
This value is used independently of whether the previous fetch has
succeeded or not.
.TP
.B identity
A string value specifying a path to a file containing a client
certificate and a private key in PEM format. Optionally, the file can
also contain any additional certificate necessary for client
authentication.
.sp
The certificate is used when communicating with an HTTPS server to
fetch the JSON data.
.UNINDENT
.SH ANY UNIT
.sp
A unit of type \fB\(dqany\(dq\fP will pick one data set from one of a number of
source units. The unit will only pick a source if it has an updated data set
and can therefore be used to fall back to a different unit if one fails.
.sp
The \fB\(dqany\(dq\fP unit has the following configuration options:
.INDENT 0.0
.TP
.B sources
A list of strings each containing the name of a unit to use as a
source.
.TP
.B random
A boolean value specifying whether the unit should pick a source unit
at random. If the value is \fBfalse\fP or not given, the source units are
picked in the order given.
.UNINDENT
.SH MERGE UNIT
.sp
A unit of type \fB\(dqmerge\(dq\fP will merge the data from all data sets of its
source units. It has the following configuration options:
.INDENT 0.0
.TP
.B sources
A list of strings each containing the name of a unit to use as a
source.
.UNINDENT
.SH SLURM UNIT
.sp
A unit of type \fB\(dqslurm\(dq\fP will apply local exception rules to a data set
provided by another unit. These rules are defined through local JSON files as
described in \X'tty: link https://datatracker.ietf.org/doc/html/rfc8416.html'\fI\%RFC 8416\fP\X'tty: link'\&. They allow to both filter out existing entries in a
data set as well as add new entries.
.sp
The \fB\(dqslurm\(dq\fP unit has the following configuration options:
.INDENT 0.0
.TP
.B source
A string value specifying the name of the unit that provides the
data set to apply the local exceptions to.
.TP
.B files
A list of strings each specifying the path to a local exception file.
.sp
The files are continously checked for updates, so RTRTR does not need
to be restarted if the files are updated.
.UNINDENT
.SH RTR TARGETS
.sp
There are two types of targets that provide a data set as an RTR server. The
target of type \fB\(dqrtr\(dq\fP provides the data set over unencrypted RTR while
the type \fB\(dqrtr\-tls\(dq\fP offers the set through RTR over TLS.
.sp
The RTR targets have the following configuration options:
.INDENT 0.0
.TP
.B listen
A list of string values each specifying an address and port the RTR
target should listen on. Address and port should be separated by a
colon. IPv6 address should be enclosed in square brackets.
.TP
.B unit
A string value specifying the name of the unit that provides the data
set for the RTR target to offer.
.TP
.B history\-size
An integer value specifying the number of diffs the target should keep
in order to process RTR serial queries, i.e., the number of updates to
the data set a client may fall behind before having to fetch the full
data set again.
.sp
If this value is missing, it defaults to 10.
.TP
.B client\-metrics
A boolean value which, if present and set to true, enables providing
metrics per client address.
.UNINDENT
.sp
The \fB\(dqrtr\-tls\(dq\fP target has the following \fIadditional\fP configuration
options:
.INDENT 0.0
.TP
.B certificate
A string value providing a path to a file containing the PEM\-encoded
certificate to be used as the TLS server certificate.
.TP
.B key
A string value providing a path to a file containing the PEM\-encoded
certificate to be used as the private key by the TLS server.
.UNINDENT
.SH HTTP TARGET
.sp
A target of type \fB\(dqhttp\(dq\fP will offer the data set provided by a unit for
download through the HTTP server.
.sp
The \fB\(dqhttp\(dq\fP target has the following configuration options:
.INDENT 0.0
.TP
.B path
A string value specifying the path in the HTTP server under which the
target should offer its data.
.sp
All HTTP targets share the same name space in RTRTR’s global HTTP
server. This value provides the path portion of HTTP URIs. It should
start with a slash.
.TP
.B format
A string value specifying the format of the data set to be offered.
Currently, this has to be \fB\(dqjson\(dq\fP for the JSON format.
.TP
.B unit
A string value specifying the name of the unit that provides the data
set for the RTR target to offer.
.UNINDENT
.SH LOGGING
.sp
In order to allow diagnosis of the operation as well as its overall health,
RTRTR logs an extensive amount of information. The log levels used by
syslog are utilized to allow filtering this information for particular use
cases.
.sp
The log levels represent the following information:
.INDENT 0.0
.TP
.B error
Information  related to events that prevent RTRTR from continuing to
operate at all as well as all issues related to local configuration
even if RTRTR will continue to run.
.TP
.B warn
Information  about  events  and  data that influences the data sets
produced by RTRTR. This includes failures to communicate with
upstream servers, or encountering invalid data.
.TP
.B info
Information about events and data that could be considered abnormal but
do not influence the data set.
.TP
.B debug
Information about the internal state of RTRTR that may be useful for
debugging.
.UNINDENT
.SH AUTHOR
NLnet Labs
.SH COPYRIGHT
2019–2024, NLnet Labs
.\" Generated by docutils manpage writer.
.