.TH fort 8 "2023-12-15" "v1.6.1" "FORT validator"
.SH NAME
fort \- RPKI validator and RTR server
.SH SYNOPSIS
.B fort
[--mode=server] [\fIOPTIONS\fR]
.P
.B fort
--mode=standalone [\fIOPTIONS\fR]
.P
.B fort
--init-tals --tal=\fIPATH\fR
.P
.B fort
[-h|--help|--V|--version|--usage]
.SH DESCRIPTION
Fort is an RPKI "Relying Party" (RP). It's an artifact that validates Route
Origin Attestations (ROAs) and BGPsec Router Keys, by way of a Public Key
Infrastructure (PKI). ROAs are employed by routers, to verify BGP routing
attestations.
.P
The main validation input is one or more Trust Anchor Locator (TAL) files
(\fI--tal\fR), which point to the RPKI Trust Anchors (ie. root certificates).
Fort downloads all the resources governed by the trust anchors into a local
cache (\fI--local-repository\fR), and proceeds to validate their entirety. The
output of the validation is a set of trusted ROAs and Router Keys, which are
printed to files (\fI--output.roa\fR and \fI--output.bgpsec\fR) and/or served to
routers (\fI--mode=server\fR, \fI--server.address\fR, \fI--server.port\fR)
through the RTR protocol (version 0 or 1).
.SH OPTIONS
.TP
.B \-h, \-\-help
.RS 4
Print long usage message and exit.
.RE
.P
.B \-\-usage
.RS 4
Print short usage message and exit.
.RE
.P
.B \-V, \-\-version
.RS 4
Print program version and exit.
.RE
.P
.B \-\-init-tals
.RS 4
Download the currently known core TALs into the existent local directory \fI--tal\fR, then exit.
.P
The "currently known core TALs" are
.P
https://rpki.afrinic.net/tal/afrinic.tal
.br
https://tal.apnic.net/apnic.tal
.br
https://www.arin.net/resources/manage/rpki/arin.tal
.br
https://www.lacnic.net/innovaportal/file/4983/1/lacnic.tal
.br
https://tal.rpki.ripe.net/ripe-ncc.tal
.RE
.B \-\-init-as0-tals
.RS 4
Download the currently known AS0 TALs into the existent local directory \fI--tal\fR, then exit.
.P
The "currently known AS0 TALs" are
.P
https://tal.apnic.net/apnic-as0.tal
.br
https://www.lacnic.net/innovaportal/file/4983/1/lacnic-as0.tal
.P
.RE
.BR \-f ", " \-\-configuration-file=\fIFILE\fR
.RS 4
Path to a JSON file from where additional configuration will be read.
.P
The configuration options are mostly the same as the ones presented in this
manual. Each property is mapped as a member of the main JSON object, the
members that contain a dot '.' must be set as objects (eg.
"--server.port=8323" will be set as "{ "server": { "port": "8323" } }".
.P
An example configuration file can be seen in this manual at the \fBEXAMPLES\fR
section.
.P
Some configuration options can't be set at the JSON configuration file:
\fB--version\fR, \fB--help\fR, \fB--version\fR, and \fB--configuration-file\fR.
.P
Other configuration options can be configured exclusively at the JSON
configuration file:
.P
.B rsync.program
.RS 4
Name of the program needed to invoke an rsync file transfer. The default value
is "rsync".
.RE
.P
.B rsync.arguments-recursive
.RS 4
Arguments needed by
.B rsync.program
to perform a recursive rsync. The arguments are specified as a JSON string
array; its default value is:
[ "-rtz", "--delete", "--omit-dir-times", "--contimeout=20", "--max-size=20MB",
"--timeout=15", "--include=*/", "--include=*.cer", "--include=*.crl",
"--include=*.gbr", "--include=*.mft", "--include=*.roa", "--exclude=*",
"$REMOTE", "$LOCAL" ]
.P
FORT will replace "$REMOTE" with the remote URL it needs to download, and
"$LOCAL" with the target local directory where the file is supposed to be
dropped.
.P
See \fIrsync(1)\fR for a description of each argument.
.RE
.P
.B incidences
.RS 4
A listing of actions to be performed by validation upon encountering certain
common error conditions. This configuration is a means to modify FORTs
validator behavior upon encountering profile violations that, from experience,
are often overlooked.
.P
The incidences are configured inside the member "incidences" as a JSON array
of objects, each with two members "name" and "action", eg:
.P
"incidences": [
.RS 2
{
.RS 2
"name": "incid-hashalg-has-params",
.br
"action": "warn"
.RE
},
{
.RS 2
"name": "incid-obj-not-der-encoded",
.br
"action": "error"
.RE
}
.RE
]
.P
An incidence contains a \fBname\fR and an \fBaction\fR. The \fBname\fR is
merely an identifier defined by FORT that states a particular error condition,
and the \fBaction\fR is an enumeration that states the outcome of a violation
of the corresponding incidence.
.P
The \fBaction\fR can have one of three values:
.br
.RS 4
\fIerror\fR: Print error message in error log level, fail validation of the
offending object (and all of its children).
.br
\fIwarn\fR: Print error message in warning log level, continue validation as if
nothing happened.
.br
\fIignore\fR: Do not print error message, continue validation as if nothing
happened.
.RE
.P
Currently these are the registered incidences, each with a distinct
\fBaction\fR configured by default.
.RS 4
.br
\fIincid-hashalg-has-params\fR (Signed Object's hash algorithm has NULL object
as parameters). [Default action: \fBignore\fR]
.br
\fIincid-obj-not-der-encoded\fR (Object isn't DER encoded). [Default action:
\fBignore\fR]
.br
\fIincid-file-at-mft-not-found\fR (File listed at manifest doesn't exist).
[Default action: \fBerror\fR]
.br
\fIincid-file-at-mft-hash-not-match\fR (File hash listed at manifest doesn't
match the actual file hash). [Default action: \fBerror\fR]
.br
\fIincid-mft-stale\fR (Manifest is stale).
[Default action: \fBerror\fR]
.br
\fIincid-crl-stale\fR (CRL is stale).
[Default action: \fBerror\fR]
.RE
.P
More information about incidences can be consulted at FORT's web docs.
.RE
.RE
.P
.BR \-t ", " \-\-tal=(\fIFILE\fR|\fIDIRECTORY\fR)
.RS 4
Path to a .tal, or a directory containing .tal files. Fort will validate the trees pointed by them.
.P
The TAL ("Trust Anchor Locator") is a text file that lists a few URLs which can be used to access the "Trust Anchor" (the root of a particular RPKI tree) and
its public key. (See RFC 8630.)
.RE
.P
.BR \-r ", " \-\-local-repository=\fIDIRECTORY\fR
.RS 4
Path to a directory where the local cache of the repository will be stored
and/or read.
.P
FORT accesses RPKI repositories either with \fIrsync\fR or \fIRRDP\fR (see RFC
8182). During each validation cycle, and depending on the preferred access
methods defined by the CAs, Fort can do two things:
.RS 4
.br
- Literally invoke an rsync command (see \fBrsync.program\fR and
\fBrsync.arguments-recursive\fR), which will download the files into
\fB--local-repository\fR.
.br
- Fetch the RRDP Update Notification file (which implies an HTTP request) and
fetch the files from there on (can be obtained from a Snapshot file or Delta
files). The files will be downloaed into \fB--local-repository\fR.
.RE
.P
Fort's entire validation process operates on the resulting copy of the files
(doesn't matter if the files where fetched by rsync of https).
.P
Because rsync uses delta encoding, you’re advised to keep this cache around. It
significantly speeds up subsequent validation cycles.
.P
By default, the path is \fI/var/lib/fort\fR.
.RE
.P
.B \-\-daemon
.RS 4
If this flag is activated, Fort will run as a daemon. The process is detached
from the calling terminal and sent to the background.
.P
All the enabled logs will be sent to syslog, so the configured values of
\fB--log.output\fR and \fB--validation-log.output\fR will be ignored.
.RE
.P
.B \-\-work-offline
.RS 4
If this flag is activated, Fort will disable all outgoing requests (currently
done with: \fIrsync\fR and \fIhttps\fR (RRDP protocol uses HTTPS to fetch
data)). All repository files (certificates, ROAs, etc.) are expected to exist
at configured \fB--local-repository\fR.
.P
Otherwise, Fort will perform outgoing requests whenever this is needed. If a
specific protocol needs to be deactivated, use \fB--rsync.enabled\fR or
\fB--http.enabled\fR.
.RE
.P
.B \-\-shuffle-uris
.RS 4
If enabled, FORT will access TAL URLs in random order. This is meant for load
balancing. If disabled, FORT will access TAL URLs in sequential order.
.P
By default, the flag is disabled.
.P
This flag is only relevant if the TAL lists more than one URL. Regardless of
this flag, FORT will stop iterating through the URLs as soon as it finds one
that yields a successful traversal.
.P
If the TAL lists more than one URL, the shuffle is done honoring the priority
of the protocols (see \fB--rsync.priority\fR and \fB--http.priority\fR). i.e.
if the HTTP protocol has a higher priority than RSYNC, then all the shuffled
HTTP URLs will come first.
.RE
.P
.B \-\-maximum-certificate-depth=\fIUNSIGNED_INTEGER\fR
.RS 4
Maximum allowable certificate chain length. Meant to protect FORT from
iterating infinitely due to certificate chain loops.
.P
By default, it has a value of \fI32\fR. The minimum allowed value is 5.
.P
(Required to prevent loops and "other degenerate forms of the logical RPKI
hierarchy." (RFC 6481))
.RE
.P
.B \-\-slurm=(\fIFILE\fR|\fIDIRECTORY\fR)
.RS 4
Path to the SLURM FILE or SLURMs DIRECTORY.
.P
The SLURM definition is from RFC 8416. SLURM stands for "Simplified Local
Internet Number Resource Management with the RPKI", basically is a document
that can override (either as a filter or adding assertions) the global RPKI
repository data fetched by FORT; potentially useful for network operators.
.P
In case a DIRECTORY is set, the files with extension '\fI.slurm\fR' will be the
ones considered as SLURM files and FORT will use them.
.P
The configured SLURM path (either \fIFILE\fR or \fIDIRECTORY\fR) will be read
each time a new validation cycle begins. If there's a syntax or content error,
the last valid version of the SLURM will be applied (if there's one) and a
message will be logged to indicate this action. Note that all this will happen
only if \fI--mode=server\fR and \fI--slurm\fR is configured.
.P
A basic example of a SLURM file can be seen in this manual at the
\fBEXAMPLES\fR section (it's almost the same as the one in RFC 8416).
.P
See more about SLURM configuration at FORT's web docs.
.RE
.P
.B \-\-mode=(\fIserver\fR|\fIstandalone\fR)
.RS 4
Commands the way FORT executes the validation, its possible values are:
.P
.I server
.RS 4
Enable the RTR server using the \fIserver.*\fR arguments.
.RE
.P
.I standalone
.RS 4
Disable the RTR server, the configuration options \fIserver.*\fR are ignored
and FORT performs an in-place standalone validation.
.RE
.P
By default, the mode is \fIserver\fR.
.RE
.P
.B \-\-server.address=\fINODE(S)\fR
.RS 4
List of hostnames or numeric host addresses the RTR server will be bound to.
Must resolve to (or be) bindable IP addresses. IPv4 and IPv6 are supported.
.P
The list of addresses must be comma sepparated, and each address must have the
following format: \fB
[#]\fR. Note that the port is optional; in
case that a port isn't specified, the value of \fI--server.port\fR will be
utilized with the corresponding address.
.P
Here are some examples of valid values for this argument:
.br
- \fI--server.address="localhost"\fR: will bind to 'localhost' and the
configured port at \fI--server.port\fR.
.br
- \fI--server.address="localhost,::1#8324"\fR: same as the previous example,
and also will bind to IPv6 address '::1' at the port '8324'.
.br
- \fI--server.address="localhost#8323,::1#8324"\fR: will bind to 'localhost' at
port '8323', and to '::1' port '8324'. The value of \fI--server.port\fR isn't
utilized.
.P
If this field is omitted, FORT will attempt to bind the server using the IP
address \fIINADDR_ANY\fR (for an IPv4 address) or \fIIN6ADDR_ANY_INIT\fR (for
an IPv6 address). See \fBgetaddrinfo(3)\fR.
.RE
.P
.B \-\-server.port=\fISERVICE\fR
.RS 4
TCP port or service the server address(es) will be bound to by default if no
port is set (see \fI--server.address\fR).
.P
This is a string because a service alias can be used as a valid value. The
alias are commonly located at \fI/etc/services\fR. See also
\fBgetaddrinfo(3)\fR and \fBservices(5)\fR.
.P
The default port (323) is privileged. To improve security, either change or
jail it.
.P
The default \fIfort-validator.service\fR configuration sets the
\fICAP_NET_BIND_SERVICE\fR capability to allow the unprivileged daemon
to bind port 323 anyway.
.RE
.P
.B \-\-server.backlog=\fIUNSIGNED_INTEGER\fR
.RS 4
RTR server’s listen queue length. It’s the second argument of the function
\fIlisten\fR (see more at man \fBlisten(2)\fR). This provides a hint to the
implementation which the implementation shall use to limit the number of
outstanding connections in the socket’s listen queue.
.P
By default, it has a value of \fISOMAXCONN\fR.
.RE
.P
.B \-\-server.interval.validation=\fIUNSIGNED_INTEGER\fR
.RS 4
Number of seconds that FORT will sleep between validation cycles. The timer
starts counting every time a validation is finished, not every time it begins.
Therefore, the actual validation loop is longer than this number.
.P
By default, it has a value of \fI3600\fR.
.RE
.P
.B \-\-server.interval.refresh=\fIUNSIGNED_INTEGER\fR
.RS 4
Number of seconds that a router should wait before the next attempt to poll
FORT using either a Serial Query PDU or Reset Query PDU. Countdown for this
timer starts upon receipt of an End Of Data PDU (this should be administered by
the client).
.P
This value is utilized only on RTR version 1 sessions (more information at RFC
8210 section 6).
.P
By default, it has a value of \fI3600\fR. Minimum allowed value: \fI1\fR,
maximum allowed value \fI86400\fR.
.RE
.P
.B \-\-server.interval.retry=\fIUNSIGNED_INTEGER\fR
.RS 4
Number of seconds that a router should wait before retrying a failed Serial
Query PDU or Reset Query PDU. Countdown for this timer starts upon failure of
the query and restarts after each subsequent failure until a query succeeds
(this should be administered by the client).
.P
This value is utilized only on RTR version 1 sessions (more information at RFC
8210 section 6).
.P
By default, it has a value of \fI600\fR. Minimum allowed value: \fI1\fR,
maximum allowed value \fI7200\fR.
.RE
.P
.B \-\-server.interval.expire=\fIUNSIGNED_INTEGER\fR
.RS 4
Number of seconds that a router can retain the current version of data while
unable to perform a successful subsequent query. Countdown for this timer starts
upon receipt of an End Of Data PDU (this should be administered by the client).
.P
This value is utilized only on RTR version 1 sessions (more information at RFC
8210 section 6).
.P
By default, it has a value of \fI7200\fR. Minimum allowed value: \fI600\fR,
maximum allowed value \fI172800\fR. It must be larger than
\fIserver.interval.refresh\fR and \fIserver.interval.retry\fR.
.RE
.P
.B \-\-server.deltas.lifetime=\fIUNSIGNED_INTEGER\fR
.RS 4
When routers first connect to Fort, they request a snapshot of the validation results. (ROAs and Router Keys.) Because they need to keep their validated objects updated, and snapshots tend to be relatively large amounts of information, they request deltas afterwards over configurable intervals. ("Deltas" being the differences between snapshots.)
.P
During each validation cycle, Fort generates a new snapshot, as well as the deltas needed to build the new snapshot from the previous one. These are all stored in RAM. \fI--server.deltas.lifetime\fR is the number of iterations a set of deltas will be kept before being deallocated. (Recall that every iteration lasts \fI--server.interval.validation\fR seconds, plus however long the validation takes.)
.P
If a router lags behind, to the point Fort has already deleted the deltas it needs to update the router’s snapshot, Fort will have to fall back to fetch the entire latest snapshot instead.
.RE
.P
.B \-\-log.enabled=\fItrue\fR|\fIfalse\fR
.RS 4
Enables the operation logs.
.P
By default, it has a value of \fItrue\fR (these logs are enabled).
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.BR \-\-log.level=(\fIerror\fR|\fIwarning\fR|\fIinfo\fR|\fIdebug\fR)
.RS 4
Defines which operation log messages will be logged according to its priority,
e.g. a value of \fIinfo\fR will log messages of equal or higher level
(\fIinfo\fR, \fIwarning\fR, and \fIerror\fR).
.P
The priority levels, from higher to lowest, are:
.RS 4
.br
- \fIerror\fR
.br
- \fIwarning\fR
.br
- \fIinfo\fR
.br
- \fIdebug\fR
.RE
.P
By default, it has a value of \fIwarning\fR.
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.BR \-\-log.output=(\fIsyslog\fR|\fIconsole\fR)
.RS 4
Desired output where the operation logs will be printed.
.P
The value \fIconsole\fR will log messages at standard output and standard error;
\fIsyslog\fR will log to syslog.
.P
Depending on the OS, distinct implementations of syslog could be installed
(syslog, rsyslog, or syslog-ng are the most common ones). Syslog usage and
configuration is out of this man scope.
.P
By default, it has a value of \fIconsole\fR.
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.BR \-c ", " \-\-log.color-output=\fItrue\fR|\fIfalse\fR
.RS 4
If enabled, the operation logs output will contain ANSI color codes. Meant for
human consumption.
.P
Meaningful only if \fI--log.output\fR value is \fIconsole\fR.
.P
By default, it has a value of \fIfalse\fR (it's disabled).
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.B \-\-log.file-name-format=(\fIglobal-url\fR | \fIlocal-path\fR |
.B \fIfile-name\fR)
.RS 4
Decides which version of file names should be printed during most debug/error
messages at the operation logs.
.P
Suppose a certificate was downloaded from
`rsync://rpki.example.com/foo/bar/baz.cer` into the local cache `repository/`:
.P
.I global-url
.RS 4
Will print the certificate's name as `rsync://rpki.example.com/foo/bar/baz.cer`.
.RE
.P
.I local-path
.RS 4
Will print the certificate's name as
`repository/rpki.example.com/foo/bar/baz.cer`.
.RE
.P
.I file-name
.RS 4
Will print the certificate's name as `baz.cer`.
.RE
.P
By default, it has a value of \fIglobal-url\fR.
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.B \-\-log.facility=(\fIauth\fR | \fIauthpriv\fR | \fIcron\fR | \fIdaemon\fR |
\fIftp\fR | \fIlpr\fR | \fImail\fR | \fInews\fR | \fIuser\fR | \fIuucp\fR |
from \fIlocal0\fR to \fIlocal7\fR)
.RS 4
Syslog facility utilized for operation logs (meaningful only if
\fI--log.output\fR is \fIsyslog\fR).
.P
By default, it has a value of \fIdaemon\fR.
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.B \-\-log.tag=\fISTRING\fR
.RS 4
Text tag that will be added to the operation log messages (it will appear
inside square brackets).
.P
By default, it has a NULL value.
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.B \-\-validation-log.enabled=\fItrue\fR|\fIfalse\fR
.RS 4
Enables the validation logs.
.P
By default, it has a value of \fIfalse\fR (these logs are disabled).
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.BR \-\-validation-log.level=(\fIerror\fR|\fIwarning\fR|\fIinfo\fR|\fIdebug\fR)
.RS 4
Defines which validation log messages will be logged according to its priority,
e.g. a value of \fIinfo\fR will log messages of equal or higher level
(\fIinfo\fR, \fIwarning\fR, and \fIerror\fR).
.P
The priority levels, from higher to lowest, are:
.RS 4
.br
- \fIerror\fR
.br
- \fIwarning\fR
.br
- \fIinfo\fR
.br
- \fIdebug\fR
.RE
.P
By default, it has a value of \fIwarning\fR.
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.BR \-\-validation-log.output=(\fIsyslog\fR|\fIconsole\fR)
.RS 4
Desired output where the validation logs will be printed.
.P
The value \fIconsole\fR will log messages at standard output and standard error;
\fIsyslog\fR will log to syslog.
.P
Depending on the OS, distinct implementations of syslog could be installed
(syslog, rsyslog, or syslog-ng are the most common ones). Syslog usage and
configuration is out of this man scope.
.P
By default, it has a value of \fIconsole\fR.
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.BR \-c ", " \-\-validation-log.color-output=\fItrue\fR|\fIfalse\fR
.RS 4
If enabled, the validation logs output will contain ANSI color codes. Meant for
human consumption.
.P
Meaningful only if \fI--validation-log.output\fR value is \fIconsole\fR.
.P
By default, it has a value of \fIfalse\fR (it's disabled).
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.B \-\-validation-log.file-name-format=(\fIglobal-url\fR | \fIlocal-path\fR |
.B \fIfile-name\fR)
.RS 4
Decides which version of file names should be printed during most debug/error
messages at the validation logs.
.P
Suppose a certificate was downloaded from
`rsync://rpki.example.com/foo/bar/baz.cer` into the local cache `repository/`:
.P
.I global-url
.RS 4
Will print the certificate's name as `rsync://rpki.example.com/foo/bar/baz.cer`.
.RE
.P
.I local-path
.RS 4
Will print the certificate's name as
`repository/rpki.example.com/foo/bar/baz.cer`.
.RE
.P
.I file-name
.RS 4
Will print the certificate's name as `baz.cer`.
.RE
.P
By default, it has a value of \fIglobal-url\fR.
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.B \-\-validation-log.facility=(\fIauth\fR | \fIauthpriv\fR | \fIcron\fR |
\fIdaemon\fR | \fIftp\fR | \fIlpr\fR | \fImail\fR | \fInews\fR | \fIuser\fR |
\fIuucp\fR | from \fIlocal0\fR to \fIlocal7\fR)
.RS 4
Syslog facility utilized for validation logs (meaningful only if
\fI--validation-log.output\fR is \fIsyslog\fR).
.P
By default, it has a value of \fIdaemon\fR.
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.B \-\-validation-log.tag=\fISTRING\fR
.RS 4
Text tag that will be added to the validation log messages (it will appear
inside square brackets).
.P
By default, it has the value \fIValidation\fR.
.P
Read more about logs at FORT validator's web docs, module 'Logging'.
.RE
.P
.B \-\-http.enabled=\fItrue\fR|\fIfalse\fR
.RS 4
Enables outgoing HTTP requests.
.P
If disabled (eg. \fB--http.enabled=false\fR), FORT validator won't request HTTP
URIs, and will expect to find all the corresponding repository files at
\fB--local-repository\fR.
.RE
.P
.B \-\-http.priority=\fIUNSIGNED_INTEGER\fR
.RS 4
Assign priority to use HTTP to fetch repository files. A higher value means a
higher priority.
.P
This argument works along with \fB--rsync.priority\fR, since the higher value
of the two arguments will result in the first protocol to utilize when fetching
repositories files. Of course, this depends also on certificates information or
the TAL URIs, since currently HTTP URIs are optional and not every RIR
repository makes use of them.
.P
Whenever a certificate or a TAL has both RSYNC and HTTP URIs, the following
criteria is followed to prioritize which one to use first:
.RS 4
.br
\- \fI--rsync.priority\fR \fBequals\fR \fI--http.priority\fR: use the order
specified at the certificate or the TAL to fetch the corresponding URI.
.br
\- \fI--rsync.priority\fR \fBgreater than\fR \fI--http.priority\fR: use RSYNC
repository/TAL URI first; if there's an error fetching data, fallback to fetch
HTTP repository/TAL URI.
.br
\- \fI--rsync.priority\fR \fBless than\fR \fI--http.priority\fR: use HTTP
repository/TAL URI first; if there's an error fetching data, fallback to use
RSYNC repository/TAL URI.
.RE
.P
By default, the value is \fI60\fR, so HTTP requests are preferred over rsync
requests.
.RE
.P
.B \-\-http.retry.count=\fIUNSIGNED_INTEGER\fR
.RS 4
Maximum number of retries whenever there's an error requesting an HTTP URI.
.P
A value of \fI0\fR means no retries.
.P
Whenever is necessary to request an HTTP URI, the validator will try the
request at least once. If there was an error requesting the URI, the validator
will retry at most \fI--http.retry.count\fR times to fetch the file, waiting
\fI--http.retry.interval\fR seconds between each retry.
.P
By default, the value is \fI2\fR.
.RE
.P
.B \-\-http.retry.interval=\fIUNSIGNED_INTEGER\fR
.RS 4
Period (in seconds) to wait between retries after an error ocurred requestin
HTTP URIs.
.P
By default, the value is \fI5\fR.
.RE
.P
.BR \-\-http.user\-agent=\fISTRING\fR
.RS 4
User-Agent to use at HTTP requests.
.P
The value specified (either by the argument or the default value) is utilized
in libcurl’s option \fICURLOPT_USERAGENT\fR.
.P
By default, the value is \fIfort/\fR.
.RE
.P
.B \-\-http.connect\-timeout=\fIUNSIGNED_INTEGER\fR
.RS 4
Timeout (in seconds) for the connect phase.
.P
Whenever an HTTP connection will try to be established, the validator will wait
a maximum of \fBhttp.connect-timeout\fR seconds for the peer to respond to the
connection request; if the timeout is reached, the connection attempt will be
ceased.
.P
The value specified (either by the argument or the default value) is utilized
in libcurl’s option \fICURLOPT_CONNECTTIMEOUT\fR.
.P
By default, it has a value of \fI30\fR. The minimum allowed value is \fI1\fR.
.RE
.P
.B \-\-http.transfer\-timeout=\fIUNSIGNED_INTEGER\fR
.RS 4
Maximum time in seconds (once the connection is established) that the request
can last.
.P
Once the connection is established with the server, the request will last a
maximum of \fBhttp.transfer-timeout\fR seconds. A value of \fI0\fR means
unlimited time (default value).
.P
The value specified (either by the argument or the default value) is utilized
in libcurl’s option \fICURLOPT_TIMEOUT\fR.
.P
By default, it has a value of \fI0\fR.
.RE
.P
.B \-\-low\-speed\-limit=\fIUNSIGNED_INTEGER\fR
.RS 4
The value Fort employs as CURLOPT_LOW_SPEED_LIMIT during every HTTP transfer.
.P
"Abort connection if slower than LIMIT bytes/sec during TIME seconds."
.P
(See \-\-low\-speed\-time.)
.P
Default: \fI100000\fR (100 KB/s)
.RE
.P
.B \-\-low\-speed\-time=\fIUNSIGNED_INTEGER\fR
.RS 4
The value Fort employs as CURLOPT_LOW_SPEED_TIME during every HTTP transfer.
.P
"Abort connection if slower than LIMIT bytes/sec during TIME seconds."
.P
(See \-\-low\-speed\-limit.)
.P
Default: \fI10\fR
.RE
.P
.B \-\-http\.max\-file\-size=\fIUNSIGNED_INTEGER\fR
.RS 4
Maximum amount of bytes files are allowed to length during HTTP transfers.
.P
Default: \fI1000000000\fR (1 GB)
.RE
.P
.B \-\-http.ca-path=\fIDIRECTORY\fR
.RS 4
Local path where the CA’s utilized to verify the peers are located.
.P
Useful when the CA from the peer isn’t located at the default OS certificate
bundle. If specified, the peer certificate will be verified using the CAs at
the path. The directory MUST be prepared using the \fIrehash\fR utility from
the SSL library:
.RS 4
.br
\- OpenSSL command (with help):
.B $ openssl rehash \-h
.br
\- LibreSSL command (with help):
.B $ openssl certhash \-h
.RE
.P
The value specified is utilized in libcurl’s option \fICURLOPT_CAPATH\fR.
.P
By default, the path has a NULL value.
.RE
.P
.B \-\-rsync.enabled=\fItrue\fR|\fIfalse\fR
.RS 4
Enables RSYNC requests.
.P
If disabled (eg. \fB--rsync.enabled=false\fR), FORT validator won't download
files nor directories via RSYNC, and will expect to find all repository files
at \fB--local-repository\fR.
.RE
.P
.B \-\-rsync.priority=\fIUNSIGNED_INTEGER\fR
.RS 4
Assign priority to use RSYNC to fetch repository files. A higher value means a
higher priority.
.P
This argument works along with \fB--http.priority\fR, since the higher value
of the two arguments will result in the first protocol to utilize when fetching
repositories files. Of course, this depends also on certificates information or
the TAL URIs, since currently HTTP URIs are optional and not every RIR
repository makes use of them.
.P
Whenever a certificate has both RSYNC and HTTP URIs, the following criteria is
followed to prioritize which one to use first:
.RS 4
.br
\- \fI--rsync.priority\fR \fBequals\fR \fI--http.priority\fR: use the order
specified at the certificate or the TAL to fetch the corresponding URI.
.br
\- \fI--rsync.priority\fR \fBgreater than\fR \fI--http.priority\fR: use RSYNC
repository/TAL URI first; if there's an error fetching data, fallback to use
fetch HTTP repository/TAL URI.
.br
\- \fI--rsync.priority\fR \fBless than\fR \fI--http.priority\fR: use HTTP
repository/TAL URI first; if there's an error fetching data, fallback to use
RSYNC repository/TAL URI.
.RE
.P
By default, the value is \fI50\fR, so HTTP requests are preferred over rsync
requests.
.RE
.P
.B \-\-rsync.strategy=(\fIstrict\fR|\fIroot\fR|\fIroot-except-ta\fR)
.RS 4
\fIrsync\fR download strategy; states the way rsync URLs are approached during
downloads. It can have one of three values:
.IR strict ", "
.IR root ", "
.IB "root-except-ta" "(default value)" \fR. \fR
.P
.I strict
.RS 4
In order to enable this strategy, FORT must be compiled using the flag:
ENABLE\_STRICT\_STRATEGY. e.g.
\fB $ make FORT_FLAGS='-DENABLE_STRICT_STRATEGY'\fR
.P
RSYNC every repository publication point separately. Only skip publication
points that have already been downloaded during the current validation cycle.
(Assuming each synchronization is recursive.)
.P
For example, suppose the validator gets certificates whose caRepository access
methods (in their Subject Information Access extensions) point to the following
publication points:
.P
1. rsync://rpki.example.com/foo/bar/
.br
2. rsync://rpki.example.com/foo/qux/
.br
3. rsync://rpki.example.com/foo/bar/
.br
4. rsync://rpki.example.com/foo/corge/grault/
.br
5. rsync://rpki.example.com/foo/corge/
.br
6. rsync://rpki.example.com/foo/corge/waldo/
.P
A validator following the `strict` strategy would download `bar`, download
`qux`, skip `bar`, download `corge/grault`, download `corge` and skip
`corge/waldo`.
.P
This is the slowest, but also the strictly correct sync strategy.
.RE
.P
.I root
.RS 4
For each publication point found, guess the root of its repository and RSYNC
that instead. Then skip any subsequent children of said root.
.P
(To guess the root of a repository, the validator counts four slashes, and
prunes the rest of the URL.)
.P
Reusing the caRepository URLs from the `strict` strategy (above) as example, a
validator following the `root` strategy would download
`rsync://rpki.example.com/foo`, and then skip everything else.
.P
Assuming that the repository is specifically structured to be found within as
few roots as possible, and they contain minimal RPKI-unrelated noise files, this
is the fastest synchronization strategy. At time of writing, this is true for
all the current official repositories.
.RE
.P
.I root-except-ta
.RS 4
Synchronizes the root certificate (the one pointed by the TAL) in 'strict' mode,
and once it's validated, synchronizes the rest of the repository in 'root' mode.
.P
Useful if you want 'root', but the root certificate is separated from the rest
of the repository. Also useful if you don't want the validator to download the
entire repository without first confirming the integrity and legitimacy of the
root certificate.
.RE
.RE
.P
.B \-\-rsync.retry.count=\fIUNSIGNED_INTEGER\fR
.RS 4
Maximum number of retries whenever there's an error executing RSYNC.
.P
A value of \fI0\fR means no retries.
.P
Whenever is necessary to execute an RSYNC, the validator will try the execution
at least once. If there was an error executing the RSYNC, the validator will
retry it at most \fI--rsync.retry.count\fR times, waiting
\fI--rsync.retry.interval\fR seconds between each retry.
.P
By default, the value is \fI2\fR.
.RE
.P
.B \-\-rsync.retry.interval=\fIUNSIGNED_INTEGER\fR
.RS 4
Period (in seconds) to wait between retries after an RSYNC error ocurred.
.P
By default, the value is \fI5\fR.
.RE
.P
.B \-\-output.roa=\fIFILE\fR
.RS 4
File where the ROAs will be printed in the configured format (see
\fI--output.format\fR).
.P
When the \fIFILE\fR is specified, its content will be overwritten by the
resulting ROAs of the validation (if FILE doesn't exists, it'll be created).
.P
When \fI--output.format=csv\fR (which is the default value), then each line of
the result is printed in the following order: AS, Prefix, Max prefix length; the
first line contains those column descriptors.
.P
When \fI--output.format=json\fR, then each element is printed inside an object
array of "roas"; ie:
.nf
{
"roas": [
{
"asn": "AS64496",
"prefix": "198.51.100.0/24",
"maxLength": 24
},
{
"asn": "AS64496",
"prefix": "2001:DB8::/32",
"maxLength": 48
}
]
}
.fi
.P
In order to print the ROAs at console, use a hyphen as the \fIFILE\fR value, eg.
.B \-\-output.roa=-
.P
By default, it has no value set.
.RE
.P
.B \-\-output.bgpsec=\fIFILE\fR
.RS 4
File where the BGPsec Router Keys will be printed in the configured format (see
\fI--output.format\fR).
.P
Since most of the data is binary (Subject Key Identifier and Subject Public Key
Info), such data is base64url encoded without trailing pads.
.P
When the \fIFILE\fR is specified, its content will be overwritten by the
resulting Router Keys of the validation (if FILE doesn't exists, it'll be
created).
.P
When \fI--output.format=csv\fR (which is the default value), then each line of
the result is printed in the following order: AS, Subject Key Identifier,
Subject Public Key Info; the first line contains those column descriptors.
.P
When \fI--output.format=json\fR, then each element is printed inside an object
array of "router-keys"; ie:
.nf
{
"router-keys": [
{
"asn": "AS64496",
"ski": "",
"spki": ""
},
{
"asn": "AS64496",
"ski": "",
"spki": ""
}
]
}
.fi
.P
In order to print the Router Keys at console, use a hyphen as the \fIFILE\fR
value, eg.
.B \-\-output.bgpsec=-
.P
By default, it has no value set.
.RE
.P
.B \-\-output.format=\fIcsv\fR|\fIjson\fR
.RS 4
Output format for \fI--output.roa\fR and \fI--output.bgpsec\fR.
.P
By default, it has a value of \fIcsv\fR.
.RE
.P
.B \-\-thread-pool.server.max=\fIUNSIGNED_INTEGER\fR
.RS 4
Number of threads the RTR server will reserve for RTR client (router) request handling. The server will be able to handle \fI--thread-pool.server.max\fR requests at most, at once. Additional requests will queue.
.P
Minimum: \fI1\fR
.br
Maximum: \fIUINT_MAX\fR
.br
Default: \fI20\fR
.RE
.B \-\-thread-pool.validation.max=\fIUNSIGNED_INTEGER\fR
.RS 4
Maximum number of threads that will be spawned at an internal thread pool in
order to run validation cycles.
.P
When a validation cycle begins, one thread per configured TAL is utilized; once
the whole RPKI tree of the TAL is validated, the thread is returned to the pool.
.P
If there are more TALs at \fI--tal\fR than \fI--thread-pool.validation.max\fR
threads at the pool, is very likely that the validation cycles take a bit more
of time to complete since only \fI--thread-pool.validation.max\fR threads will
be working at the same time. E.g. if \fI--thread-pool.validation.max=2\fR and
the location at \fI--tal\fR has 4 TAL files, only 2 TALs will be validated
simultaneously while the rest waits in a queue until there's an available thread
at the pool to attend them.
.P
By default, it has a value of \fI5\fR. Minimum allowed value: \fI1\fR,
maximum allowed value \fI100\fR.
.RE
.B \-\-asn1-decode-max-stack=\fIUNSIGNED_INTEGER\fR
.RS 4
ASN1 decoder max allowed stack size in bytes, utilized to avoid a stack
overflow when a large nested ASN1 object is parsed.
.P
By default, it has a value of \fI4096\fR (4 kB).
.RE
.P
.B \-\-stale-repository-period=\fIUNSIGNED_INTEGER\fR
.RS 4
Deprecated; does nothing.
.RE
.P
.SH EXAMPLES
.B fort \-\-init-tals \-\-tal=/tmp/tal
.RS 4
Download the 5 RIR TALs into the /tmp/tal directory.
.RE
.P
.B fort \-t /etc/tals \-r /var/lib/fort \-\-server.port=9323
.RS 4
Run FORT with all the default values, using a custom TALs directory, a
custom repository directory as well, and binding the RTR server to port 9323.
.RE
.P
.B fort \-t /etc/tals \-r /var/lib/fort \-\-mode=standalone \-\-output.roa=-
.RS 4
Run FORT as standalone and output ROAs CSV to the console.
.RE
.P
.nf
\fBfort \-t /etc/tals \-r /var/lib/fort \\
\-\-mode=standalone \\
\-\-slurm=/etc/fort/slurm/\fR
.fi
.RS 4
Run FORT as standalone and using a SLURM file.
.RE
.P
.B fort \-\-configuration-file=conf.json
.RS 4
Run FORT using the JSON configuration file \fIconf.json\fR.
.RE
.P
.nf
\fBfort \-t /etc/tals \-r /var/lib/fort \\
\-\-server.address=::1 \-\-server.port=9323 \\
\-\-server.interval.validation=1800 \\
\-\-output.roa=/var/lib/fort/roas.csv\fR
.fi
.RS 4
Run FORT with RTR server listening on IPv6 address \fI::1\fR, port 9323,
validating every 30 minutes, and printing the ROAs CSV in a file.
.RE
.P
.B Complete configuration file
.RS 4
This is an example of a valid JSON configuration file with all its members set
to a specific value:
.nf
{
"tal": "/etc/tals/",
"local-repository": "/var/lib/fort/",
"work-offline": false,
"maximum-certificate-depth": 32,
"mode": "server",
"daemon": false,
"slurm": "/etc/fort/slurm/",
"asn1-decode-max-stack": 4096,
"server": {
"address": [
"192.0.2.1",
"2001:db8::1"
],
"port": "8323",
"backlog": 4096,
"interval": {
"validation": 3600,
"refresh": 3600,
"retry": 600,
"expire": 7200
},
"deltas": {
"lifetime": 2
}
},
"log": {
"enabled": true,
"output": "console",
"level": "info",
"tag": "Operation",
"facility": "daemon",
"file-name-format": "global-url",
"color-output": false
},
"validation-log": {
"enabled": false,
"output": "console",
"level": "warning",
"tag": "Validation",
"facility": "daemon",
"file-name-format": "global-url",
"color-output": false
},
"http": {
"enabled": true,
"priority": 60,
"retry": {
"count": 1,
"interval": 4
},
"user-agent": "fort/1.6.0",
"max-redirs": 10,
"connect-timeout": 30,
"transfer-timeout": 0,
"low-speed-limit": 100000,
"low-speed-time": 10,
"max-file-size": 1000000000,
"ca-path": "/etc/ssl/certs"
},
"rsync": {
"enabled": true,
"priority": 50,
"retry": {
"count": 1,
"interval": 4
},
"program": "rsync",
"arguments-recursive": [
"-rtz",
"--delete",
"--omit-dir-times",
"--contimeout=20",
"--max-size=20MB",
"--timeout=15",
"--include=*/",
"--include=*.cer",
"--include=*.crl",
"--include=*.gbr",
"--include=*.mft",
"--include=*.roa",
"--exclude=*",
"$REMOTE",
"$LOCAL"
]
},
"incidences": [
{
"name": "incid-hashalg-has-params",
"action": "ignore"
},
{
"name": "incid-obj-not-der-encoded",
"action": "ignore"
},
{
"name": "incid-file-at-mft-not-found",
"action": "error"
},
{
"name": "incid-file-at-mft-hash-not-match",
"action": "error"
},
{
"name": "incid-mft-stale",
"action": "error"
},
{
"name": "incid-crl-stale",
"action": "error"
}
],
"output": {
"roa": "/var/lib/fort/roas.csv",
"bgpsec": "/var/lib/fort/bgpsec.csv",
"format": "csv"
},
"thread-pool": {
"server": {
"max": 20
}
}
}
.fi
.RE
.P
.B Dummy SLURM file
.RS 4
This is an example of a SLURM file with some prefix filters and assertions, as
well as some dummy Router Keys (BGPsec) info:
.nf
{
"slurmVersion": 1,
"validationOutputFilters": {
"prefixFilters": [
{
"prefix": "192.0.2.0/24",
"comment": "All VRPs encompassed by prefix"
},
{
"asn": 64496,
"comment": "All VRPs matching ASN"
},
{
"prefix": "198.51.100.0/24",
"asn": 64497,
"comment": "All VRPs encompassed by prefix, matching ASN"
}
],
"bgpsecFilters": [
{
"asn": 64496,
"comment": "All keys for ASN"
},
{
"SKI": "Q8KMeBsCto1PJ6EuhowleIGNL7A",
"comment": "Key matching Router SKI"
},
{
"asn": 64497,
"SKI": "g5RQYCnkMpDqEbt9WazTeB19nZs",
"comment": "Key for ASN 64497 matching Router SKI"
}
]
},
"locallyAddedAssertions": {
"prefixAssertions": [
{
"asn": 64496,
"prefix": "198.51.100.0/24",
"comment": "My other important route"
},
{
"asn": 64496,
"prefix": "2001:DB8::/32",
"maxPrefixLength": 48,
"comment": "My other important de-aggregated routes"
}
],
"bgpsecAssertions": [
{
"asn": 64496,
"SKI": "Dulqji-sUM5sX5M-3mqngKaFDjE",
"routerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE-rkSLXlPpL_m-L\
7CfCfKrv1FHrM55FsIc8fMlnjHE6Y5nTuCn3UgWfCV6sYuGUZzPZ0Ey6AvezmfcELUB87eBA"
}
]
}
}
.fi
.RE
.P
.\".SH COPYRIGHT
.\" FORT-validator 2021
.\" MIT License
.SH SEE ALSO
https://nicmx.github.io/FORT-validator/