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.