General information
*******************
rpsltool is a suite of libraries and programs which generate configuration
fragments for the BGP sessions of peers and customers.
It supports automatically generating routes and as-paths ACLs by querying
a RPSL whois server.
Some example templates are provided for IOS, Junos and BIRD, but the
program can easily extended to support other targets thanks to
Template::Toolkit.

http://www.linux.it/~md/text/rpsltool-trex.pdf is an introduction to RPSL
and rpsltool.

YAML Configuration
~~~~~~~~~~~~~~~~~~
Most programs use one or more configuration files in YAML format.
YAML is a general purpose data serialization standard, check www.yaml.org
for details about the YAML syntax.
Usually all parameters have sane defaults.
If an element expecting a list contains a scalar, it will be automatically
promoted to a list.


Neighbors configuration
~~~~~~~~~~~~~~~~~~~~~~~
The BGP peers and customers connected to a router are listed in a YAML
configuration file containing three YAML documents (lists of variables
separated by ---):
 * the configuration parameters
 * generic variables made available to the template (accessible in the
   template as members of the "var" associative array)
 * the list of neighbors with their parameters

Elements of the neighbors list with the "template: y" variable are a set
of default parameters to be used for the following neighbors (until a new
template element is defined).

These files can be made executable and run as scripts by using something
like "#!/usr/bin/env rpsltool" as their first line.


Neighbors parameters
~~~~~~~~~~~~~~~~~~~~
* as: the neighbor ASN
* ip: the neighbor IP address. It must be unique.
* backupip: the IP address of a second BGP session with the neighbor,
  which shares the same configuration
* peergroup: the value of the peer-group IOS directive
* description: the value of the description IOS directive
* import, unimport, global_unimport: defaults for the AFI-specific
  paramenters
* default_aspath_filter: automatically creates an as-path filter for the
  ASN resulting from RPSL expansion, even if only prefix filtering was
  requested
* bgp_command: a list of "raw" IOS directives for the neighbor (can be
  used at the AFI level too)
* maxpref: the value of the maximum-prefix directive
* disabled: ignores the element
* an AFI (ipv4, ipv6, ipv4m, ipv6m), which is a list of other parameters:
  * aslist: the number of the as-path access-list
  * import: networks and/or ASN to accept
  * unimport: a filter to be applied to the list of prefixes generated by
    the import statement, matching entries will be removed
  * global_unimport: like unimport, but to be used in a template element

If no AFI is specified, "ipv4" or "ipv6" will be guessed by looking at the
neighbor IP address.


import statements
~~~~~~~~~~~~~~~~~
This is the most important and complex attribute of a peer and contains
a list of elements to be accepted from the neighbor. Valid elements are:
- an explicit prefix (e.g. '2002::/16' or '192.175.48.0/24')
- an explicit ASN (e.g. 'AS112')
- a rs-set (e.g. 'RS-KROOT' or 'AS12654:RS-RIS')
- an as-set (e.g. 'AS-NETNOD-ANYCAST')

Each ASN and as-set will be recursively expanded to the list of routes
registered to be originated by them.
If an ASN or as-set is enclosed by brackets (e.g. '<AS12654:RS-RIS>')
then it will be expanded respectively to itself or to a list of ASN.

All these elements can be combined at will. This means that the output
of an import statement is two different lists, each of them possibly
empty: a list of ASN and a list of routes.
If a list is empty, no filter will be created in the configuration.


Caching
~~~~~~~
By default, all programs which make whois queries cache them in
/tmp/rpsltool/. This can be changed with the cache_root configuration
option. If empty, no caching is performed (please do not do this when
querying a public server! And it will slow down the program in any case).
If your file system cannot handle directories with many files you should
also set the cache_depth configuration option to an appropriate value.
You will need to manually expire the cache when needed, by deleting the
stale files (e.g. using find(1) and rm(1) or just purging everything
every day).


The programs
************
Most programs will display a terse help message when run without arguments.

rpsltool
~~~~~~~~
This program will process a Template::Toolkit template file, usually
after initializing some data structures with data collected from the IRR.
It has two operating modes: it accepts as the only command line argument
either a configuration file name or a template name.
In the first mode, configuration files can be used as scripts by making
them executable and using "#!/usr/bin/env rpsltool" as the first line.
The output will always be printed to stdout.


routesdiff
~~~~~~~~~~
This program parses a routes dump directory generated by the dumppeers
program (from the cisco-tools package) and reports which prefixes have
not been accepted by the filters on BGP sessions.
Networks to be excluded from the report are listed in the script
DATA section.


nagpeer
~~~~~~~
You can specify on the command line either the IP or ASN of the peer
to be checked or the string "report" to print a report to stdout.
In report mode the HTML page showing missing routes and ASN for each
configured neighbor is printed on stdout.
In the normal mode it will check if the neighbor as-set or rs-set lacks
some elements and if so will start a mail reader with a form letter.
The nagpeer.yml configuration file needs to be customized to adapt the
program to your needs and so they will the nagpeer.*.tt2 templates.
Please be sure to not use my email address when emailing your peers!


findextraobjs
~~~~~~~~~~~~~
findextraobjs parses a rpsltool configuration file specified on the
command line and reports which of the manually imported objects should
be removed from the configuration because they are already imported by
expanding the peer as-set or rs-set object.
It's a tool which should be run from time to time to help removing
obsolete cruft from configurations.
If a routes dump directory is specified then it will also report which
of the manually imported objects should be removed because they are not
being announced by the neighbor.
The output formatting needs to be cleaned up and it has false positives
for some corner cases.


testpeerfilter
~~~~~~~~~~~~~~
This program is both a simple proof of concept example of how to use
the RPSL*.pm modules and a way to check the effect of a filter on the
routes received from a peer.
The configuration is stored in the script DATA section and it overrides
the settings in the peers file.


rpslexpand
~~~~~~~~~~
This trivial program will perform RPSL expansion of one or more as-sets
or rs-sets specified on the command line and print the output.
By default it will perform expansion to a list of routes, but if the
argument is enclosed by brackets (e.g. <AS-LINX>) it will only a list of
ASN.
If the --ipv6 switch is used it will query for route6 objects instead of
route objects.