# rblcheck

## rblcheck Manual

### About rblcheck

rblcheck is a very basic interface to RBL-style DNS listings such as those operated by the MAPS and ORBS projects.

The general idea behind RBL-style listings is rapid lookup of IP addresses using DNS (for example, for blacklisting IP addresses because of abuse). Each IP address is reversed and has a domain name attached to it; for example, the IP address 127.0.0.2 would become 2.0.0.127, and then a domain such as "relays.visi.com" would be added to it. You would then try to resolve the result (ie. 2.0.0.127.relays.visi.com); if you receive a positive reply, then you know that the address is listed. Further information can also be queried, such as text descriptions of why the address was listed.

rblcheck is licensed under the terms of the GNU General Public License, a free software license.

### Building

#### Supported Platforms

I currently perform a manual build and test of rblcheck on the following platforms prior to each release:

- Red Hat Linux 7.0/Intel

- Debian GNU/Linux 2.2r2/Intel

- Sun Solaris 7/SPARC

I speculate that most releases will compile on the following platforms:

- Sun SunOS 4.x

- Sun Solaris 2.x/7/8

- IBM AIX 4.3.3

- BSDI BSD/OS 2.x/3.x/4.x

- FreeBSD 2.x/3.x/4.x

- Compaq Digital UNIX/Tru64 4.0x

- Hewlett-Packard HP/UX 10.x/11.x

- Most versions of Linux (libc5- and glibc-based)

- Almost any relatively POSIX platform with a resolver library.

#### Compiling

Before building rblcheck, edit the file `sites.h` for the listings you wish to check against (to un-comment a listing, remove the `/*` and `*/` around the `SITE(...)` line).

To compile rblcheck, just run ./configure in the main directory, followed by make when the first command is complete.

To make sure that what you now have works correctly, run make check; make sure that you have an Internet connection handy when you do, or a large number of the tests will produce (non-fatal) failures.

When you are done, you can type make install to install the software (by default, everything will be installed in `/usr/local`.

For more details on how the configure command works, please see the file `INSTALL` in the main directory, which has a complete breakdown of all of your options.

#### Note to developers

You may have received the version of rblcheck that you're currently working from via a nightly CVS snapshot (the file you downloaded would likely have been called rblcheck-20020101.tar.gz or something similar), or you might have downloaded a version of the source directly from the CVS tree. The most distinguishing feature of these developer-only versions is the lack of a configure script in the main distribution directory, and the presense of a bootstrap script instead. These releases are not for the faint of heart, and you may very well be unable to build them without a bit of work. As a matter of fact, the documentation you're reading right now may not even apply to one of these experimental versions.

If you are not building a development release, you do NOT need to read this section, as none of these instructions apply to you. Please read building_compiling for instructions on how to build a normal rblcheck release.

And with that out of the way, welcome to rblcheck development! You will need a number of utilities to build a development release, above and beyond the usual build requirements:

- Autoconf 2.13

- Automake 1.4

- docbook-tools 0.6.8 (the Red Hat RPM package identifies itself as docbook-utils, other distributions may name the package differently, if they include it at all)

Autoconf and automake are tools which make cross-platform development easier by automatically checking for issues related to particular platforms. The basic idea is to ensure that even though the primary developers of a piece of software may not have access to a wide range of platforms, the chances of a successful "out of the box" build will still work. The reality is a little different, of course, but it works relatively well. If this sounds like your cup of tea, you might be interested in reading the definitive book on GNU Autotools: GNU Autoconf, Automake, and Libtool.

The docbook-tools package is required for building multiple formats of the documentation included with rblcheck. The documentation is written entirely in SGML (Docbook 4.1), and is located in the file `docs/rblcheck.sgml`.

Once you've verified that you have these installed, you'll need to run ./bootstrap from the main rblcheck source directory, which will create a number of the files you need to complete the build. At this point, you should follow the usual instructions for building the application (see building_compiling).

#### Note to distributors and packagers

If you're distributing a pre-built version of rblcheck for your users, I strongly recommend leaving everything in `sites.h` commented out. The ability to add sites there was only added as a convenience feature for people building a personal copy for their own use, and was never intended to be used to pre-set policy for people using pre-packaged versions.

Over the years, there has been a great deal of volatility in the RBL listing "market"; even the venerable MAPS RBL is no longer publically available without making special arrangements. Therefore, along with those pre-defined lists of RBL services is built-in obsolescence.

As a side-note, I don't make new releases just to update the `sites.h` file, and at some point in the future, I'll probably stop seeding it with suggestions. As the package maintainer, you're taking on the burden of keeping that up-to-date. Do you really want that hassle, or would it just be easier to point your users at a list of RBL services that is up-to-date (see the rblcheck homepage for links to several current listings)?

You're also making life a more difficult for the user; users will come to depend on that pre-built list of sites. What happens when, by necessity, you need to change that built-in list (because some listings are no longer available, or because new ones are now online)? Your users will very likely complain about the change in behavior, and rightly so. Even worse, what does the user do when they disagree with your selection of services? Recompile from source (which defeats the purpose of providing them with a pre-compiled binary in the first place)? Let them pick their own listings. You and your users will be much happier.

If you feel that you just can't release rblcheck without a built-in list, may I suggest using the global `rblcheckrc` which the rbl script uses? At least that way, the end user can change your pre-selections on their own, without having to build from source.

### Using

#### rblcheck basics

The program has several command line options:

`-q` | Display only listed addresses, if none is listed then there is no output.
`-t` | Display, if available, a textual description of why the site was originally placed in a particular listing.
`-m` | Stop checking listings after the first successful match of any IP address against any listing.
`-l` | List the currently defined RBL listings. By default, rblcheck has no pre-defined listings; you can change this behavior by editing the file `sites.h` as described in building.
`-c` | Clear the list of defined RBL listings. This is handy if you don't want to use the default listings added by the installation of rblcheck on your system.
`-s` `<service>` | Toggle a service in the list of defined RBL listings.
`-h`, `-?` | Get help about rblcheck.
`-v` | Display the version of rblcheck.

You can check multiple addresses at once, to make life a little easier with scripts; just add additional addresses on the command line after all of the options. By specifying an address of "-", rblcheck will read from stdin and perform a lookup on every line of input (if it is a valid IP address).

#### Return codes

When invoked, rblcheck returns either 0 (to indicated error, or that the address was not in any of the listings), or a positive number (indicating the number of listings that the IP address was found in).

#### Verifying your installation

To verify that the program is working after you've compiled it, try the following test:

    $ ./rblcheck -s relays.ordb.org 127.0.0.1
    127.0.0.1 not RBL filtered by relays.ordb.org
    $ ./rblcheck -s relays.ordb.org 127.0.0.2
    127.0.0.2 RBL filtered by relays.ordb.org

If you see any other result than the above, then something has gone wrong; please see below about reporting bugs and finding help.

#### The rbl wrapper

A recent addition to the rblcheck package is the rbl shell script, which is a simple wrapper around rblcheck, with one special feature: it will read a global `rblcheckrc` (usually in `/etc` or `/usr/etc`), and then a `.rblcheckrc` from the current user's home directory. These files can contain any of the usual rblcheck command-line arguments (see using_rblcheck), but are most useful for setting the most common RBL-style listings you use day-to-day.

For example, your personal `.rblcheckrc` might contain:

    -t
    -m
    -c
    -s relays.ordb.org
    -s relays.visi.com
    -s some.future.rbl.listing

Please note that for mail filtering, or any performance-sensitive use, you should use rblcheck directly, to avoid adding additional latency to the process. rbl is mainly intended as a convenience tool for interactive use.

### Third-Party Software

rblcheck works well as a command-line tool for performing lookups, but it also serves an important role working with other software, such as mail servers and email filtering programs.

#### Procmail

rblcheck was really designed to be used with procmail, as long as you have access to the IP address of the system sending you email. Surprisingly, most MTAs make obtaining this information more difficult than it needs to be. The procmail rule I present here assumes you've found some way to put the IP address of the sender in the variable `TCPREMOTEIP`. See the sections below on Sendmail and QMail for ideas on how you can get ahold of this value.

The following procmail rule will, once you have `TCPREMOTEIP`, use rblcheck to look up the IP address in the built-in filters:

    :0
    * ! ? if [ -n "$TCPREMOTEIP" ]; then rblcheck -q "$TCPREMOTEIP"; fi
    {
    	EXITCODE=100
    	LOGABSTRACT=all
    	LOG="Filter: RBL-filtered address: \"$TCPREMOTEIP\"
    "
    	:0:
    	$FILTER_FOLDER
    }

`FILTERFOLDER` is assumed to have been set up ahead of time as the place to put email that you don't want to see (either another incoming folder, /dev/null, or a 'formail' invokation that rewrites the message and tacks on an extra header or munges the subject so you can easily identify it.

Note that `EXITCODE` above is for QMail, and indicates a permanent error. Under Sendmail, 77 is more appropriate. Under anything else, it's hard to say; your best bet is to refer to the documentation regarding execution of programs.

One more thing: procmail has a nasty habit of munging the environment, but most MTAs already do this for you. Hence, you should add the '-p' flag to the invokation of procmail (either from a local delivery rule in Sendmail, or from a .forward or .qmail file). This will ensure that procmail doesn't clean out the value of `TCPREMOTEIP`.

To test the procmail recipe:

1. Save any mail message, with full headers, to a file.

2. Run procmail with the environment variable `TCPREMOTEIP` set to an offending address, and with the message you just saved as input:

       cat message | env - TCPREMOTEIP=127.0.0.2 procmail -p

3. Check your procmail log and mailbox. If the message went through, you have a problem. If you have a message in your logfile stating that the message was bounced for being in the RBL, you're fine.

4. Run procmail with the environment variable `TCPREMOTEIP` set to a non-filtered address, such as 127.0.0.1, and with the message as input:

       cat message | env - TCPREMOTEIP=127.0.0.1 procmail -p

5. Check your procmail log and mailbox. If the message didn't go through, you have a problem. If you have a copy of the message in your mailbox, and no errors in your log file, you're fine.

#### Sendmail

This solution for obtaining the IP address of the connecting host could be considered to be a bit of a hack, but it works quite reliably. If you're an ordinary user on your system, you won't be able to use this; talk to your system administrator about the possibility of installing the sendmail.cf patch below. Point them at this file as a source of information.

Currently, in your sendmail.cf file, you'll probably have something like:

    Mlocal,	P=/bin/mail, F=lsDFMAw5:/|@SnE, S=10/30, R=20/40,
    	T=DNS/RFC822/X-Unix,
    	A=mail -f $g -d $u

Or, if you're using procmail as the local delivery agent:

    Mlocal,	P=/usr/bin/procmail, F=lsDFMAw5:/|@ShPfn, S=10/30, R=20/40,
    	T=DNS/RFC822/X-Unix,
    	A=procmail -a $h -d $u

This is the local delivery rule used to execute .forward scripts. Your system might use something like rsh or another restricted shell instead of sh for running programs. Don't let that scare you; they all basically work the same.

Change the above lines to look like this (there will also be Mprog lines which look similar; you can modify them in exactly the same manner):

    Mlocal,	P=/usr/bin/env, F=lsDFMAw5:/|@SnE, S=10/30, R=20/40,
    	T=DNS/RFC822/X-Unix,
    	A=env TCPREMOTEIP="${client_addr}" mail -f $g -d $u

(replacing "mail -f $g -d $u" with "procmail -a $h -d $u" appropriately.)

ONLY change the P=... and A=... entries. Most certainly do not mess with F=... unless you know what you are doing.

This will create an environment variable `TCPREMOTEIP`, which you can now use with rblcheck to determine if the address has been blocked. To test this, set up an alias like:

    foo: |mailx -s "$TCPREMOTEIP" user@domain.com

Then, send email to the alias "foo" (or whatever). You should immediately get a piece of email with the IP address which sent the message in the subject line. (Replace mailx with mail on some systems.)

This is about the most efficient means of getting this information to executed programs that I can see with sendmail. What would -really- be nice here would be a way to program how Sendmail sets up the environment before executing an external program, at the point of execution. Bug the Sendmail developers if you agree with me. ;-)

#### QMail

Getting this going under QMail turns out to be a real challenge, since QMail doesn't have the same level of programmability that Sendmail has. Hence, we need to employ an additional script to grab the IP address from the headers. (Thanks to Russell Nelson for confirming QMail's behavior here.)

QMail has a very specific means of adding Received: lines to messages, making them relatively easy to parse. For example, the following headers are typical:

    Return-Path: <emarshal@xnet.com>
    Delivered-To: emarshal@LOGIC.NET
    Received: (qmail 26029 invoked from network); 13 Oct 1997 15:04:13 -0000
    Received: from quake.xnet.com (HELO mail.xnet.com) (198.147.221.35)
      by labyrinth.logic.net with SMTP; 13 Oct 1997 15:04:13 -0000

We can disregard the Return-Path: and Delivered-To: lines; they're unimportant to us. The Received: headers are the most interesting. The first Received: line we'll see is the local delivery of the mail; hence, the "qmail 2609 invoked from network". The second Received: line is the most important to us; it's the one which contains the IP address of the sender...in this case, 198.147.221.35. To complicate things, the "(HELO mail.xnet.com)" section may not exist, and the IP address might have ident information prepended to it (like "qmailr@198.147.221.35").

Two programs are provided to help you retrieve this information automatically from the headers, both with the same semantics. "origip.c" compiles into "origip", and for those who have trouble compiling it (if you do, please email me with any errors), "origip.awk" is provided which behaves the same way.

Essentially, you pass either of these programs an email message, and they in turn extract the sending address and either print it back to you, or exit with a non-zero return value.

To use this in procmail, just use:

    TCPREMOTEIP=`origip || echo 127.0.0.1`

This will pipe the message through origip (replace origip with "origip.awk" in the case of using the awk script), and will capture the address. If there is an error, we'll default to 127.0.0.1, which will allow the mail through.

(If you're undecided which program of the two you want to use, consider that the C version is much faster, and will be maintained more than the awk script. However, the C version is probably more prone to bugs. ;-)

Once you have that line in place, go ahead and use the procmail recipe supplied above in good health.

#### inetd and smtpd

If you use an smtp server which runs from inetd (sendmail can operate this way, as can QMail and a number of other MTAs), here's a good way to do site-wide filtering using rblcheck; add the following to /etc/hosts.allow:

    smtpd: ALL: spawn /usr/local/bin/rblcheck -q %a && \
    	exec /usr/local/bin/smtpd || /bin/echo \
    	"469 Connection refused. See http://maps.vix.com/rbl/\r\b\r\n"

This gives you RBL support on a site-wide basis, even if native support doesn't yet exist for your MTA of choice. This assumes that your inetd has support for tcp_wrappers checks; many Linux variants fall into this category, but other platforms may differ.

A word of warning, however: there are a number of very good reasons to not run a production mail server from inetd, which I won't elaborate on here. You might want to investigate more secure and reliable alternatives, such as tcpserver from D. J. Bernstein's excellent daemontools package.

#### Other Software

Don't ask me. If you figure out a way to make this work under another setup, let me know how you did it, and I'll add it here. If you find better ways of doing this than the ones I'm using above, let me know too, and you'll see your idea show up in here in the next release.

### Future

#### To Do

There are a number of enhancements to rblcheck that are up for consideration, in no particular order. Patches for any of the below will earn you fame, fortune, and a warm fuzzy feeling for having made the world a better place. ;-)

- Follow CNAMEs from rblcheck(). This will let us get at the eventual TXT RRs for a domain name.

- Optional support for adns.

- Timeout option. Should default to no timeout, but apparently there is an issue with rblcheck hanging in an offline environment where the nameserver in use is located off-site. This would compensate for the misconfiguration, and provide a 'quick-fail' mode for people to play with. I'm still not entirely convinced that this should be rblcheck's problem, though; using a local cache like dnscache from djbdns seems like a much more reliable solution to what is a general misconfiguration.

- (from Aaron Schrab aaron@schrab.com, era eriksson era@iki.fi, and torben fjerdingstad tfj@fjerdingstad.dk) Add the ability to only list successful matches, and add a debug mode which outputs what is happening internally, and any errors received. This could be best implemented with a '-v X' option, where 'X' is a number between 0 and 9 (0 being silent, 4 being default/ordinary output, 9 displaying heavy debugging info).

- Add an option to display the PTR address returned by the original query, prior to following it.

- (from Craig Callender craig@mosquitonet.com) Add the ability to specify a particular PTR address; for example, when performing a lookup in ORBS, allow for matching against only a specific returned address (such as 127.0.0.2). Perhaps allow a list of these matches. The question is: is this better implemented here, or in the caller via a filter (after the display of PTR addresses is added)?

#### ...or Not To Do?

These are the features that you'll never see in the version of rblcheck that I produce (rblcheck is GPL; you're free to produce your own version if this doesn't suit you well), and the rationale behind why not. I'm hoping that the explainations will make sense, but I'm always open to criticism if you feel my logic is flawed.

Support for doing lookups of FQDNs

- This is a futile method of checking whether a particular system is blackholed; if the originating system has control of reverse DNS for their IP space, they can make their IP address resolve to anything they want, such as system.network.com. If rblcheck were to do a lookup on that, "system.network.com" might resolve to anything (such as "127.0.0.1, which will always pass with every currently known RBL-based blacklist). A compromise that I've considered would be similar to TCP Wrapper's system of multiple lookups: take the IP address, look up the reverse, then resolve the reverse to an IP address. If both lookups match, then proceed, otherwise exit with a failure. I'd consider integrating code from someone who implemented this behavior.

  (A note for the confused: some people might mistake this for my saying that a tool for looking up hosts in DNSBL listings (a means of looking up originating domains in a blacklist, much like the RBL) isn't a good idea. On the contrary, I'd like to see a complimentary dnsblcheck to go along with rblcheck. The problem I have is specifically with resolving the name to an IP address for use by an RBL lookup tool.)

Return codes that identify a particular blacklist

- This took a while to convince me it was wrong. Here are the questions I went over when deciding against this:

  - What do you do with your scripts when the blacklist order changes, or new blacklists appear (assuming a dynamic assignment of identifiers)?

  - If you hard-code a number for each and every blacklist, who becomes responsible for being a registry for those numerical identifiers? What happens to already-assigned values when blacklists shutdown or change incompatibly?

  - How do you scale beyond 256 RBL services? With the advent of software such as rbldns (a part of the djbdns package which allows anyone to host an RBL-style service), and with nearly a dozen OsiruSoft domains alone, does this limitation seem reasonable?

  - How do you report multiple matches with a return code, when the return code can only hold one number?

  Some of these can be solved, but not cleanly; you'll need no end of special cases to accomodate them.

Integrated scanning of email and similar features

- This is a question of UNIX philosophy: design one tool for one task, and do it well. There are plenty of far more powerful text parsing tools available which are more appropriate for the job (email parsing is easily handled by tools such as formail, general text parsing is better suited by tools such as sed, awk, perl, python, etc), and they can do a much better job than something that I could integrate into rblcheck while still maintaining a small footprint.

### Notes on origip

Not convinced that you should use the C version of origip? Here's some data (using test_origip.sh as a testbed) which definitely speaks volumes:

With origip.awk:

    18.60user 22.46system 0:43.59elapsed 94%CPU (0avgtext+0avgdata 0maxresident)k
    0inputs+0outputs (102172major+51041minor)pagefaults 0swaps

With origip.c:

    13.16user 19.41system 0:33.73elapsed 96%CPU (0avgtext+0avgdata 0maxresident)k
    0inputs+0outputs (71381major+46044minor)pagefaults 0swaps

10 seconds faster, 3 seconds less system time used, 5 seconds less user time, and over 30,000 less page faults. In other words: a LOT easier on the box you'll be running this on. This test was run on a little under 600 messages, from various mailing lists and private messages, on a Linux 2.0.31 system.

### Reporting Problems

All software has bugs, and rblcheck has a place for you to report them if you believe you've found one. (Bug tracker)

If you have a SourceForge account already, please log in before reporting a bug so that you can be notified of changes.

### Credits

Thanks, kudos, and other good stuff go to:

Paul Vixie paul@vix.com

For the original RBL, a fantastic tool for the prevention of spam. Often duplicated, never repeated, and all that jazz.

The MAPS Project

- A great gathering point for protection services regarding email. Everyone there should be given a pat on the back for the thankless hours they put into maintaining an excellent resource for everyone.

Stephen R. van den Berg srb@cuci.nl

- For writing Procmail, a nifty little mail filtering tool. While certainly not the only place to use rblcheck, it's certainly one of the more useful.

Dire Straits

- For writing good music to write code to. ;-) I wonder if spam qualifies as a symptom of industrial disease?

...and a cast of thousands:

- - Russell Nelson nelson@crynwr.com

  - Frank Tegtmeyer fte@iqweb.de

  - Anders Eriksson aer@cdt.luth.se

  - Kevin Kadow kadokev@ripco.com

  - Ronald F. Guilmette rfg@monkeys.com

  - era eriksson era@iki.fi

  - Ophir Ronen ophir@internap.com

  - Brian Willoughby brianw@sounds.wa.com

  - Jeff A. Earickson jaearick@colby.edu

  - Gerald Pfeifer pfeifer@dbai.tuwien.ac.at

  - Pat Myrto pat@rwing.COM

  - William Yang wyang@freenet.columbus.oh.us

  - Dougal Campbell dougal@advicom.net

  - Jason Gunthorpe jgg@gpu.srv.ualberta.ca

  - Timothy J Luoma luomat@peak.org

  - Adam Shand larry@alaska.net

  - Andrew Kelley kelleya@dimensional.com

  - Thomas Meyer tmeyer@ifi.unizh.ch

  - Jonathan Bradshaw jonathan@NrgUp.Com

  - Jacques Distler distler@golem.ph.utexas.edu

  - Harlan Stenn Harlan.Stenn@pfcs.com

  - Marco d'Itri md@Linux.IT

## Appendixes

Version 2, June 1991

2000 Free Software Foundation, Inc.

    Free Software Foundation, Inc.
    	  59 Temple Place, Suite 330,
    	  Boston,
    	  MA 02111-1307
    	  USA

.

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

### GNU General Public License

#### Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software - to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps:

1. copyright the software, and

2. offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

#### TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

##### Section 0

This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a work based on the Program means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term modification.) Each licensee is addressed as you.

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

##### Section 1

You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

##### Section 2

You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License.

   ###### Exception:

   If the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

##### Section 3

You may copy and distribute the Program (or a work based on it, under Section 2 in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

##### Section 4

You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

##### Section 5

You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

##### Section 6

Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

##### Section 7

If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

##### Section 8

If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

##### Section 9

The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

##### Section 10

If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

##### NO WARRANTY

Section 11

BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

##### Section 12

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Version 1.1, March 2000

2000 Free Software Foundation, Inc.

    Free Software Foundation, Inc. 59 Temple Place,
            Suite 330, Boston, MA
            02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

### GNU Free Documentation License

#### 0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of copyleft, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

#### 1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The Document, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as you.

A Modified Version of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A Secondary Section is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The Invariant Sections are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

The Cover Texts are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

A Transparent copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not Transparent is called Opaque.

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

The Title Page means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, Title Page means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

#### 2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

#### 3. COPYING IN QUANTITY

If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

#### 4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

- #### A

  Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

- #### B

  List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).

- #### C

  State on the Title Page the name of the publisher of the Modified Version, as the publisher.

- #### D

  Preserve all the copyright notices of the Document.

- #### E

  Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

- #### F

  Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

- #### G

  Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

- #### H

  Include an unaltered copy of this License.

- #### I

  Preserve the section entitled History, and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled History in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

- #### J

  Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the History section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

- #### K

  In any section entitled Acknowledgements or Dedications, preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

- #### L

  Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

- #### M

  Delete any section entitled Endorsements. Such a section may not be included in the Modified Version.

- #### N

  Do not retitle any existing section as Endorsements or to conflict in title with any Invariant Section.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section entitled Endorsements, provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version .

#### 5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled History in the various original documents, forming one section entitled History; likewise combine any sections entitled Acknowledgements, and any sections entitled Dedications. You must delete all sections entitled Endorsements.

#### 6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and dispbibute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

#### 7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an aggregate, and this License does not apply to the other self-contained works thus compiled with the Document , on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

#### 8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

#### 9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

#### 10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License or any later version applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

#### Addendum

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

> Copyright © YEAR YOUR NAME.

> Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled GNU Free Documentation License.

If you have no Invariant Sections, write with no Invariant Sections instead of saying which ones are invariant. If you have no Front-Cover Texts, write no Front-Cover Texts instead of Front-Cover Texts being LIST; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.