                               IRR PowerTools
                               --------------

Written by Richard A Steenbergen <ras@e-gerbil.net>


Summary
-------

A collection of tools which allow ISPs to easily track, manage, and 
utilize BGP routing information stored in Internet Routing Registry (IRR) 
databases. Some of these tools include automated IRR data retrieval, 
update tracking via CVS, e-mail notifications, e-mail based notification 
for ISPs who still do human processing of routing information, and hooks 
for automatically deploying prefix-lists on routers.


Purpose
-------

Internet Routing Registry (IRR) services have existed in various forms for 
some time, yet many ISPs (particularly those outside of the RIPE region) 
have still not adopted it. One of the biggest reasons given for not using 
IRR data is that, while there are many existing tools (in varying states 
of brokenness) that will query the IRR for prefixes, there are no existing 
tools to track, manage, and deploy these prefix-lists in a reasonable 
fashion. Without the ability to track the the routing changes, many 
networks find that there is not enough accountability to simply deploy any 
prefix that is listed in the IRR.

IRR PowerTools aims to provide the following functionality:
   * Automated retrieval of prefixes registered under an IRR Object.
   * Automatic exclusion of bogon or other configured undesirable routes.
   * Tracking and long-term recording of prefix changes through CVS.
   * Automatic aggregation to optimize data and reduce unnecessary changes.
   * E-mail updates, letting users know that their change was processed.
   * E-mail alerts to the ISP, letting them know of new routing changes.
   * Exporting of data to e-mail form, for non-IRR user compatibility.
   * Router config generation for easy automated deployment.

While many ISPs still rely on error-prone e-mail and human processing to 
handle prefix-lists, a few have developed systems similar to this one in 
order to automate their prefix-list management. Unfortunately each of 
these systems is proprietary and owned by the respective ISPs, leaving 
other networks with a choice between spending money and man-hours writing 
duplicating this work, or more often taking the path of least resistance 
and simply using e-mails and human processing.

This project aims to provide to every network the same features that 
individual ISPs have been developing internally for years. By making it 
easier for every ISP to effectively utilize the IRR data, we hope to 
increase the popularity of the IRR as a prefix-list management tool, which 
will hopefully lead to more accurate data and a more effective system.


Requirements
------------

* Aggregate    >= 1.5     (ftp://ftp.isc.org/isc/aggregate/)
* CVS                     (http://www.gnu.org/software/cvs/)
* PHP                     (http://www.php.net/downloads.php)
* CVSweb       Optional   (http://people.freebsd.org/~scop/cvsweb/)


Documentation
-------------

The operation of IRR PowerTools is broken down into the following distinct 
operations:

* Fetch

    This is the stage where you pull data for the objects that you are 
    tracking off of the IRR, and store them locally. Inside the fetch
    process, the following steps are performed:

    1) Query a IRR whois server for prefixes behind the IRR object.
    2) Match prefixes (including more-specifics) against the Exclusions 
       list, which contains prefixes that can not be registered. 
    3) Store the approved prefixes locally.
    4) Run the prefixes through an aggregation tool to optimize them.
    5) Track changes to both the raw and aggregated prefix lists via CVS.
    6) When changes are detected, send out notification e-mails to 
       customers and optionally a local copy to your operations staff, 
       alerting everyone that the routing change has been successfully 
       processed.

* Nag

    In this stage, any transit providers (or other interested parties) 
    who still track prefix-list updates via e-mail rather than via IRR 
    can be notified of the change.

    As more providers begin to use IRR, and rely on it as their primary 
    prefix tracking tool, this should become less and less necessary. 
    Unfortunately many of the largest ISPs still use human processing of 
    prefix lists, so for the immediate future you will probably still be 
    getting a lot of use out of this tool.

* Pfxgen

    This this stage, actual router configurations are generated based on 
    the aggregated data we have stored. Currently only the following 
    formats are supported, but it should be trivial to add new ones:

    1) Cisco format (ip prefix-list NAME permit x.x.x.x/x le x). This 
       should also work for the Cisco CLI copy-cats like Foundry, etc.

    2) Juniper format (policy-statement NAME / route-filter x.x.x.x upto x).

    These configs can then be deployed automatically using a variety of 
    existing tools. Some of these tools include:

    RANCID       - http://www.shrubbery.net/rancid/
    JUNOScript   - http://www.juniper.net/support/junoscript/
    
    At some point in a future release we may include some example code 
    for this kind of deployment. 


Instructions
------------
    To get started, you probably want to take a look at every file in 
    the /conf directory. The most important information to change will be 
    paths and company-specific information such as the name, ASN, and 
    e-mail addresses.

    irrpt.conf      - This is the master config file which contains global 
                      configuration information, the paths to our internal 
                      locations and external tools, and internal parameters.

    irrdb.conf      - This is the second most important config file, 
                      containing a list of the ASNs and IRR Objects you wish
                      to track.

    nag.conf        - This file contains the settings for the nag process.

    nag.msg         - This file contains the message that will be sent 
                      during the nag process.

    exclusions.conf - This file lists routes which can not be registered. A 
                      good example for this file would be known bogon routes,
                      or routes in known unallocated space.

    The irrdb.conf file should certain a unique ASN, the IRR object (an 
    AS-SET or AUT-NUM record) that you are interested in tracking, and a 
    contact e-mail for change notification. You probably want to track your 
    own ASN and AS-SET record here as well.

    A reasonable deployment would be to crontab the fetch process once or 
    better yet twice a day. If you need to add a new customer outside of 
    the normal fetch schedule, or if a customer needs an emergency 
    prefix-list update, you can add the ASN/IRR Object to irrdb.conf and 
    run a manual pull of just that ASN, with "./fetch ASN".

    After the updates are processed, you should receive a local copy of the 
    e-mail. It is probably reasonable to keep a human being in the loop 
    between prefix fetching and prefix deployment, to make certain that 
    nothing "bad" or unintended is happening. After you are reasonably 
    certain that the changes are ready for deployment, you can generate 
    the router configs use the "pfxgen" tool. Optionally, you can nag 
    any of your transit providers who still require e-mail updates using 
    the nag process.

    If there is anything else that you can't figure out, it is probably 
    either a bug or an oversight in the documentation. Send e-mail about 
    either one, and I'll make certain it gets addressed in a future 
    release.


FAQ
---

Q) Why PHP? Why not Perl, or some other language?
A) Simple. I don't normally write text processing scripts, so I don't 
   particularly care for or regularly use Perl. Since this most definitely 
   falls into the category of a text processing script, it would take much 
   longer to write it in C, and for little gain. With PHP, I can at least 
   close my eyes, hum real loudly, and pretend like I am writing C. :) 

Q) Wouldn't this be more scalable if we stored our configurations in SQL? 
A) Yes it would. However, the purpose of this project is to open up the
   world of automated IRR-based prefix-lists to every ISP. As such, it is 
   designed to be as simple as possible, with the fewest complex external 
   dependencies. A network who maintains customer BGP info in an existing 
   database should be able to easily adapt this code to support it.

Q) Does this tool support RPSLng?
A) Not right now. We're making the basic assumption of IPv4 routes only, 
   especially in so far as the aggregate tool goes. This may change in 
   the future. Feel free to let me know your strong interest (or lack 
   thereof) on this issue.


Long Term Goals
---------------

We understand that this is only one step in the direction of making IRR 
truly and globally useful, but hopefully it will prove to be an important 
one. The next logical step towards improving the overall user experience 
would be to design an intuitive web interface for managing records in the 
IRR, so that BGP speaking end-users are not required to learn the 
complexities of RPSL in order to register their routes.

Hopefully this tool will prove to be useful to a variety of ISPs, and will 
increase the adoption of IRR data over error-prone e-mail updates. When 
more ISPs can make use of this data, and when more end-users are able to 
easily make use of the system, there will hopefully be an increase in 
accurate and maintained data and a reduction in the need to pollute the 
IRR with proxy-registered trash.


Coming Soon
-----------

* More code for automated config deployment to routers.


Thanks
------

Joe Abley for the very useful aggregate tool, Chris Morrow for nagging me 
into releasing this publicly, and all the folks in #ix and #nanog who 
helped pick out the bugs.
