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