routinator(1)                  routinator 0.3.3                  routinator(1)



NAME
       routinator - RPKI relying party software

SYNOPSIS
       routinator  [-b  base-dir]  [-r repository-dir] [-t tal-dir] [-x excep-
       tions-file  [-x  exceptions-file  [...]]]    [--strict]   [--rsync-com-
       mand=command]  [--rsync-args=args] [--rsync-count=count] [--rsync-time-
       out=seconds]  [--validation-threads=count]  [-v|-vv|-q|-qq]  [-h]  [-V]
       command [args]

       routinator [options] vrps [-o output-file] [-f format] [-n ]

       routinator   [options]   rtrd   [-l  addr:port  [-l  addr:port  [...]]]
       [--refresh seconds] [--retry  seconds]  [--expire  seconds]  [--history
       count]

       routinator [options] update

       routinator man [-o file]



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.

       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.

       These  modes and additional operations can be chosen  via commands. For
       the available commands, see COMMANDS below.

OPTIONS
       The available options are:

       -c path, --config=path
              Provides the path to a file containing basic  configuration.  If
              this   option   is   not  given,  Routinator  will  try  to  use
              $HOME/.routinator.conf if that exists. If  that  doesn't  exist,
              either,  default  values  for  the options as descrined here are
              used.

              See CONFIGURATION FILE below for more information on the  format
              and contents of the configuration file.

       -b dir, --base-dir=dir
              Specifies  the  base  directory  to  keep status information in.
              Unless overwritten by the -r or -t options, the local repository
              will  be  kept in the sub-directory repository and the TALs will
              be kept in the sub-directory tals.

              If omitted, the base directory defaults to $HOME/.rpki-cache.

       -r dir, --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.

       -t dir, --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 TRUST ANCHOR LOCA-
              TORS for more information on what  should  be  present  in  this
              directory.

       -x file, --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.

       --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.

              See RELAXED VALIDATION below for more information.

       --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
              rsync-args configuration file setting instead.

              If  this  option  is not given, Routinator will simply run rsync
              and hope that it is in the path.

       --rsync-count=count
              Sets the maximum number of rsync commands to be run in parallel.
              The default is 4.

       --rsync-timeout=seconds
              Sets  the  number  of seconds an rsync command is allowed to run
              before it is terminated early.  This  protects  against  hanging
              rsync  commands  that  prevent  Routinator  from continuing. The
              default is 300 seconds which should be long  enough  except  for
              very slow networks.

       --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.

       -v, --verbose
              Print more information. If given twice, even more information is
              printed.

              More  specifically, a single -v increases the log level from the
              default of warn to info, specifying it more than once  increases
              it to debug.

       -q, --quiet
              Print less information. Given twice, print nothing at all.

              A single -q will drop the log level to error.  Repeating -q more
              than once turns logging off completely.

       --syslog
              Redirect logging output to syslog.

              This option is implied if a command is used that causes Routina-
              tor to run in daemon mode.

       --syslog-facility=facility
              If logging to syslog is used, this option can be used to specify
              the syslog facility to use. The default is daemon.

       --logfile=path
              Redirect logging output to the given file.

       -h, --help
              Print some help information.

       -V, --version
              Print version information.


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


   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  Pay-
       load or VRPs, as a list.

       -o file, --output=file
              Specifies  the  output file to write the list to. If this option
              is missing or file is - the list is printed to standard output.

       -f format, --format=format
              The output format to use. Routinator currently supports the fol-
              lowing formats:

              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  lat-
                     ter  is  the  name  of the TAL file without the extension
                     .tal.

                     This is the default format used if the -f option is miss-
                     ing.

              csvext An  extended  version  of  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 au-
                     tonomous 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.

                     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.

              json   The  list is placed into a JSON object with a single ele-
                     ment roas which contains an array of  objects  with  four
                     elements  each:  The autonomous system number of the net-
                     work authorized to originate a prefix in asn, the  prefix
                     in slash notation in prefix, the maximum prefix length of
                     the announced route in maxLength, and  the  trust  anchor
                     from  which  the  authorization  was derived in ta.  This
                     format is identical to that produced by the RIPE NCC val-
                     idator  except  for different naming of the trust anchor.
                     Routinator uses the name of  the  TAL  file  without  the
                     extension .tal whereas the RIPE NCC Validator has a dedi-
                     cated name for each.

              openbgpd
                     Choosing this format causes Routinator to produce a  roa-
                     set configuration item for the OpenBGPD configuration.

              rpsl   This  format  produces  a  list  of RPSL objects with the
                     authorization in the fields route,  origin,  and  source.
                     In addition, the fields descr, mnt-by, created, and last-
                     modified, are present with more or less  meaningful  val-
                     ues.

              none   This format produces no output whatsoever.

       -n, --noupdate
              The repository will not be updated before producing the list.


   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  TRUST ANCHOR LOCATORS below) and will then detach from the termi-
       nal unless the -a option is given.

       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.

       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.

       -l addr:port, --listen=addr: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.

              If  this  options  is  omitted,  Routinator   will   listen   on
              127.0.0.1:3323.   Note how this is a localhost address for secu-
              rity 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.

              Routinator  will  only  start  listening on these ports after an
              intitial validation run has finished.

       --listen-http=addr:port
              Specifies the address and port to listen on  for  incoming  HTTP
              connections.  See HTTP SERVICE below for more information on the
              HTTP service provided by Routinator.

              If this option is omitted, no HTTP service will be provided.


       --refresh=seconds
              The amount of seconds the server should wait after  having  fin-
              ished updating and validating the local repository before start-
              ing to update again. The default value is 3600 seconds.

       --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.

       --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.

       --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.

              Note that routers typically stay connected with their RTR server
              and therefore really only ever need one single change set. Addi-
              tionally,  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.

              The default value is 10.

       --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.

       --working-dir=path
              The working directory for the daemon process.  In  daemon  mode,
              Routinator  will  change  to this directory while detaching from
              the terminal.

       --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 pro-
              vided  via  the  configuration or command line options are under
              this directory.


   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.

       As  such,  the command really is a shortcut for running routinator vrps
       -f none.


   man
       Displays the manual page, i.e., this page.

       -o file, --output=file
              If this option is provided, the manual page will be  written  to
              the  given  file  instead  of displaying it. Use - to output the
              manual page to standard output.



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  -t  option.
       If the -b option is used instead, the TAL directory will be in the sub-
       directory tals under  the  directory  specified  in  this  option.  The
       default  location,  if  no  options  are  used  at  all is $HOME/.rpki-
       cache/tals.

       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.

       If the directory does exist, Routinator will  use  all  files  with  an
       extension  of  .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.


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  -c option. If no configuration file is specified this way
       but a file named $HOME/.routinator.conf is present, this file is used.

       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.

       The configuration file can contain the following entries. All path val-
       ues are interpreted relative to the directory the configuration file is
       located.   in.  All  values  can  be  overwritten  via the command line
       options.

       repository-dir
              A string containing the path to the directory to store the local
              repository in. This entry is mandatory.

       tal-dir
              A  string containing the path to the directory that contains the
              Trust Anchor Locators. This entry is mandatory.

       exceptions
              A list of strings, each containing the path to a file with local
              exceptions.  If missing, no local exception files are used.

       strict A   boolean  specifying  whether  strict  validation  should  be
              employed. If missing, strict validation will not be used.

       rsync-command
              A string specifying the command to use for  running  rsync.  The
              default is simply rsync.

       rsync-args
              A  list  of strings containing the arguments to be passed to the
              rsync command.  Each string is an argument of its own.

       If this option is not provided, Routinator will try to find out if your
       rsync understands the --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.

       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.

       rsync-timeout
              An  integer  value specifying th number seconds an rsync command
              is allowed to run before it is being terminated. The default  if
              the value is missing is 300 seconds.

       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.

       log-level
              A  string  value  specifying the maximum log level for which log
              messages should be emitted. The default is warn.

       log    A string specifying where to send log messages to. This  can  be
              one of the following values:

              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.

              stderr Log messages will be sent to standard error.

              syslog Log messages will be sent to syslog.

              file   Log  messages  will be sent to the file specified through
                     the log-file configuration file entry.

              The  default  if  this  value  is  missing  is,  unsurprisingly,
              default.

       log-file
              A  string  value containing the path to a file to which log mes-
              sages will be appended if the log configuration value is set  to
              file.  In this case, the value is mandatory.

       syslog-facility
              A string value specifying the syslog facility to use for logging
              to syslog.  The default value if this entry is missing  is  dae-
              mon.


       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.

       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.   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.

       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.

       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.

       history-size
              An integer value specifying  how  many  change  sets  Routinator
              should keep in RTR server mode. The default is 10.

       pid-file
              A  string value containing a path pointing to the PID file to be
              used in daemon mode.

       working-dir
              A string value containing a path to the  working  directory  for
              the daemon process.

       chroot A string value containing the path any daemon process should use
              as its root directory.


HTTP SERVICE
       When run in 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 ser-
       vice  does  not  support HTTPS and should only be used within the local
       network.

       The service only supports GET requests with the following paths:


       /csv   Returns the current set of VRPs in csv output format.

       /json  Returns the current set of VRPs in json output format.

       /metrics
              Returns a set of  monitoring  metrics  in  the  format  used  by
              Prometheus.

       /openbgpd
              Returns the current set of VRPs in openbgpd output format.

       /rpsl  Returns the current set of VRPs in rpsl output format.

       /version
              Returns the version of the Routinator instance.


RELAXED VALIDATION
       The  documents  defining  RPKI  include  a  number of very strict rules
       regarding the formatting of the objects published in the  RPKI  reposi-
       tory.   However,  because  PRKI  reuses existing technology, real-world
       applications produce objects that do not follow these  strict  require-
       ments.

       As a consequence, a significant portion of the RPKI repository is actu-
       ally invalid if the rules are followed. We therefore introduce two val-
       idation  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.

       This  memo documents the violations we encountered and are dealing with
       in relaxed validation mode.


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


       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.

              In relaxed mode, we will only check that the  general  structure
              of  the issuer and subject fields are correct and allow any num-
              ber and types of attributes. This  seems  justified  since  RPKI
              explicitly does not use these fields.


   Signed Objects (RFC 6488)
       Signed  objects are defined as a profile on CMS messages defined in RFC
       5652.

       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.

              In relaxed mode, we will allow BER encoding.

              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.


AUTHOR
       Jaap Akkerhuis wrote the original version of this manual  page,  Martin
       Hoffmann extended it for later versions.

EXIT CODE
       The Routinator program exits with status code 1 on error,

BUGS
       Sure



NLnet Labs                       April 1, 2019                   routinator(1)