GREPCIDR3(1)

NAME
grepcidr3 — Filter IP addresses matching IPv4 and IPv6 address specifications

SYNOPSIS

grepcidr3 [-V] [-cCDvahisq] PATTERN [FILE ...]

grepcidr3 [-V] [-cCDvahisq] [-e PATTERN | -f FILE] [FILE ...]

DESCRIPTION

grepcidr3 can be used to filter a list of IP addresses and ranges against one or more IPv4 and IPv6 address ranges. As with grep, there are options to invert matching and load patterns from a file. grepcidr3 is designed to scale well, and handle large numbers of patterns and large input files efficiently. This version uses a completely rewritten parser that is typically two or three times faster than previous versions.

OPTIONS

-V  Show software version

-c  Display count of the lines that otherwise would have been printed

-v  Invert the sense of matching, to select lines with IPs that don't match any pattern

-a  (anchor) Only match addresses that occur at the beginning of a line

-e  Specify pattern(s) as an argument

-f  Obtain pattern(s) from a file

-h  Do not print file names with matched lines

-i  Ignore bad patterns

-s  (Sloppy) Don't complain about misaligned CIDR ranges.

-C  Parse CIDR ranges in input and match if a search term covers the entire range.

-D  Parse CIDR ranges in input and match if a search term covers any of the range.

-q  (Quick) Ignore IPv4 addresses that are followed by a dot.

USAGE NOTES

PATTERN specified on the command line may contain multiple patterns separated by white space 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. In a file, each pattern can be followed by a space and comments.

Each pattern, whether on the command line or inside a file, may be:

a.b.c.d/xx        (IPv4 CIDR range)
a.b.c.d-e.f.g.h   (IPv4 range)
a.b.c.d           (Single IPv4 address)
ab:cd::ef	  (Single IPv6 address)
ab:cd::ef/xx	  (IPv6 CIDR range)
ab::cd:a.b.c.d	  (IPv4 address embedded in IPv6)

Invalid patterns are ignored with the -i flag, which can be useful for using files of IPs or CIDRs as patterns that also contain other material. CIDRs are always properly aligned even if the base address wasn't, e.g., 12.34.56.78/24 is treated as 12.34.56.0/24, and 1234:5678::abcd/64 is treated as 1234:5678::0/64. Complaints about misaligned CIDRs can be suppressed with -s.

COMPATIBILITY

In version 2.9 grepcidr3 normally searches for IP addresses anywhere on the input line. It uses a reasonable but ad-hoc parser to look for the beginning of an address. This can cause unexpected results in some cases, e.g. ab:c12.34.56.78 will not match as an IPv4 address because ab:c12 looks like the beginning of an IPv6 address. Addresses written as IPv6 embedded IPv4 addresses will match either the IPv4 or IPv6 address pattern, e.g. ::ffff:12.34.56.78 will match both ::ffff:0/96 and 12.34.0.0/16.

Even though :: is a valid way to write a zero IPv6 address, grepcidr3 won't match it. (If that's what you want, use regular grep.) It will match 0:: or ::0.0.0.0 or 0::0 or or any other form.

Normally grepcidr3 will match every string that looks like an IPv4 address, so in 1.2.3.4.5.6.7.8 it will match both 1.2.3.4 and 5.6.7.8. The -q option ignores addresses preceded or followed by a dot, which avoids false matches in some contexts.

Use the -a option to look for addresses only at the start of the line, optionally preceded by white space. This type of search is stricter, but not significantly faster.

Note that -v outputs only lines that do contain IP addresses, but do not match any of the patterns.

If there is more than one file named on the command line, each matched line is preceded by the file name unless the -h flag is set.

EXAMPLES

grepcidr3 -f ournetworks blocklist > abuse.log

Find customers (CIDR ranges in file) that appear in blocklist

grepcidr3 127.0.0.0/8,::1 iplog

Searches for any localnet IP addresses inside the iplog file

grepcidr3 "192.168.0.1-192.168.10.13" iplog
grepcidr3 "2001:3def:1234::/48" iplog

Searches for IPs matching indicated range in the iplog file

script | grepcidr3 -vf whitelist > blocklist

Create a blocklist, with whitelisted networks removed (inverse)

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

AUTHOR

This software is based on software written by Jem Berkes <jem@berkes.ca>, extensively rewritten by John Levine <johnl@taugh.com>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or any later version published by the Free Software Foundation.