grepcidr 1.4 - Filter IP addresses matching IPv4 CIDR specification
Copyright (C) 2004 - 2013  Jem E. Berkes <jem@berkes.ca>
	http://www.pc-tools.net/unix/grepcidr/
	http://www.berkes.ca/


DESCRIPTION
-----------
grepcidr can be used to filter a list of IP addresses against one or more
Classless Inter-Domain Routing (CIDR) specifications, or arbitrary networks
specified by an address range.  As with grep, there are options to invert
matching and load patterns from a file.  grepcidr is capable of comparing
thousands or even millions of IPs to networks with little memory usage and
in reasonable computation time.

grepcidr has endless uses in network software, including: mail filtering and
processing, network security, log analysis, and many custom applications.


COMPILING & INSTALLING
----------------------
Generally,
	make
	make doc
	make install
	
To compile with performance optimizations, edit Makefile or use:
	make CFLAGS='-O2 -Wall -Werror'


COMMAND USAGE
-------------

	grepcidr [-V] [-c] [-v] [-x] PATTERN [FILE]
	grepcidr [-V] [-c] [-v] [-x] [-e PATTERN | -f FILE] [FILE]


-V	Show software version
-c	Display count of the matching lines, instead of showing the lines
-v	Invert the sense of matching, to select non-matching IP addresses
-x	Strict non-regex search, look for single IP at start of line
-e	Specify pattern(s) on command-line
-f	Obtain CIDR and range pattern(s) from file


IMPORTANT CHANGE
----------------

Note that the default behaviour of grepcidr has changed in version 1.4
to find IP addresses anywhere on the line.  This is the regex-patched
behaviour that many users (including Debian distro) have been using.
Use -x for the original (faster), non-regex behaviour of prior versions.


USAGE NOTES
-----------

PATTERN specified on the command line may contain multiple patterns
separated by whitespace or commas. For long lists of network patterns,
use -f to load a file where each line contains one pattern. Comment
lines starting with # are ignored, as are any lines that don't parse.

Each pattern, whether on the command line or inside a file, may be:
a.b.c.d/xx	(CIDR format)
a.b.c.d-e.f.g.h	(IP range)
a.b.c.d		(Single IP)

By default as of version 1.4, grepcidr searches for IP addresses anywhere
on the input line (using an internal regular expression search).  This can
sometimes lead to unexpected results.  For example the following line will
match the pattern 66.163.166.0/24

122.166.163.66 (abts-kk-dynamic-066.163.166.122.airtelbroadband.in)

In this case, the reverse dotted IP in the hostname for this broadband
user just happened to produce another valid ISP netblock, by coincidence.

Use the -x option to do a non-regex search, and grepcidr will only look
for the single IP address at the start of the line (may be preceded by
whitespace).  This type of search is stricter, and faster.  With -x the
above example will match 122.166.163.0/24 but not 66.163.166.0/24

Note that -v outputs IP addresses that don't match, as opposed to any
line that doesn't match.  When using -v, only lines containing an IP
(which doesn't match the patterns) will be output.


EXAMPLES
--------

grepcidr -f ournetworks blacklist > abuse.log
	Find customers (CIDR ranges in file) that appear in blacklist

grepcidr 127.0.0.0/8 iplog
	Searches for any localnet IP addresses inside the iplog file

grepcidr "192.168.0.1-192.168.10.13" iplog
	Searches for IPs matching indicated range in the iplog file

script | grepcidr -vf whitelist > blacklist
	Create a blacklist, with whitelisted networks removed (inverse)

grepcidr -f list1 list2
	Cross-reference two lists, outputs IPs common to both lists


EXIT STATUS
-----------

As with grep: the exit status is 0 if matching IPs are found, and 1
if not found.  If an error occurred the exit status is 2. 
	
	
THANKS
------

Thanks to Ryan Finnie <ryan@finnie.org> for his work on the Debian package.
I've adopted several of his changes including the Makefile, and the DocBook
format which now is the source of the man page.  Thanks to Ryan for writing
the first manual in DocBook format.

Thanks to Jeff Makey <jeff@sdsc.edu> who contributed a patch using regex to
find IP addresses anywhere on the line.

Many thanks to Dick Wesseling <ftu@fi.uu.nl> who suggested an improved data
structure format as well as binary search, to improve grepcidr performance.
