hath \- Manipulate network blocks in CIDR notation
.SH SYNOPSIS
-\fBhath\fR [\fBregexed|reduced|duped|diffed|listed|reversed\fR] [\fB\-hb\fR] \fI<input>\fR
+\fBhath\fR [\fBregexed|reduced|duped|diffed|listed\fR] [\fB\-hb\fR] \fI<input>\fR
.SH INPUT
.P
The \fIinput\fR (stdin) should be a list of CIDR blocks, separated by
View the result of block combination in a useful way.
.IP \(bu
List them.
-.IP \(bu
-Find their associated PTR records.
.P
-Hath does just that. It takes as its input (via stdin, or a file with
-the -i parameter) a list of CIDR blocks.
+Hath does just that. It takes as its input (via stdin) a list of CIDR
+blocks.
.SH MODES
.P
Hath has several modes:
.IP \(bu 2
\fBRegexed\fR
-.P
+
This computes a (Perl-compatible) regular expression matching
the input CIDR blocks. It's the default mode of operation.
-.P
+
.nf
-.I $ hath <<< \(dq10.0.0.0/29 10.0.0.8/29\(dq
-((10)\.(0)\.(0)\.(0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15))
+.I $ echo \(dq10.0.0.0/29 10.0.0.8/29\(dq | hath
+((10)\.(0)\.(0)\.(15|14|13|12|11|10|9|8|7|6|5|4|3|2|1|0))
.fi
.IP \(bu 2
\fBReduced\fR
-.P
+
This combines small blocks into larger ones where possible, and
eliminates redundant blocks. The output should be equivalent to
the input, though.
-.P
+
.nf
-.I $ hath reduced <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
+.I $ echo \(dq10.0.0.0/24 10.0.1.0/24\(dq | hath reduced
10.0.0.0/23
.fi
.IP \(bu 2
\fBDuped\fR
-.P
+
Shows only the blocks that would be removed by reduce; that is, it
shows the ones that would get combined into larger blocks or are
simply redundant.
-.P
+
.nf
-.I $ hath duped <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
+.I $ echo \(dq10.0.0.0/24 10.0.1.0/24\(dq | hath duped
10.0.0.0/24
10.0.1.0/24
.fi
.IP \(bu 2
\fBDiffed\fR
-.P
+
Shows what would change if you used reduce. Uses diff-like
notation.
-.P
+
.nf
-.I $ hath diffed <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
+.I $ echo \(dq10.0.0.0/24 10.0.1.0/24\(dq | hath diffed
-10.0.0.0/24
-10.0.1.0/24
+10.0.0.0/23
.fi
.IP \(bu 2
\fBListed\fR
-.P
+
List the IP addresses contained within the given CIDRs.
-.P
+
.nf
-.I $ hath listed <<< \(dq192.168.0.240/29\(dq
+.I $ echo 192.168.0.240/29 | hath listed
192.168.0.240
192.168.0.241
192.168.0.242
192.168.0.246
192.168.0.247
.fi
-.IP \(bu 2
-\fBReversed\fR
-.P
-Perform reverse DNS (PTR) lookups on the IP addresses contained within
-the given CIDRs.
-.P
-.nf
-.I $ hath reversed <<< \(dq198.41.0.4/30\(dq
-198.41.0.4: a.root-servers.net.
-198.41.0.5:
-198.41.0.6: rs.internic.net.
-198.41.0.7:
-.fi
-.P
-The DNS lookups are usually the bottleneck for this mode, but we can
-perform them in parallel. Simply pass the number of threads to the GHC
-runtime on the command line; for example, the following will perform
-25 lookups in parallel:
+.SH EXAMPLES
.P
+Use the \(dqdig\(dq command to look up the PTR records for a netblock:
+
.nf
-.I $ hath reversed +RTS -N25 <<< \(dq198.41.0.4/24\(dq
-198.41.0.4: a.root-servers.net.
-198.41.0.5:
-198.41.0.6: rs.internic.net.
-\(pc\(pc\(pc
+.I $ echo 198.41.0.4/30 | hath listed | xargs -I{} dig +noall +answer -x '{}'
+4.0.41.198.in-addr.arpa. 897 IN PTR a.root-servers.net.
+6.0.41.198.in-addr.arpa. 900 IN PTR rs.internic.net.
.fi
-
.SH OPTIONS
.IP \fB\-\-barriers\fR,\ \fB\-b\fR
-(regexed mode only) place barriers in front/back of the regex to
-prevent e.g. '127.0.0.1' from matching '127.0.0.100'. The downside is
-that the resulting regexp will match something that is not an IP
-address, and this messes up e.g. \fIgrep -o\fR.
+(regexed mode only)
+
+Place barriers in front/back of the regex to prevent, for
+example, '127.0.0.1' from matching '127.0.0.100'. The downside is that
+the resulting regexp will match something that is not an IP address.
+This can interfere with things like \fIgrep -o\fR.
-.P
Without \fB\-\-barriers\fR, you can match things you shouldn't:
.nf
-.I $ echo \(dq127.0.0.100\(dq | grep -P $(hath <<< \(dq127.0.0.1/32\(dq)
+.I $ echo 127.0.0.100 | grep -P $(echo 127.0.0.1/32 | hath)
127.0.0.100
.fi
-.P
Using \fB\-\-barriers\fR can prevent this:
.nf
-.I $ echo \(dq127.0.0.100\(dq | grep -P $(hath -b <<< \(dq127.0.0.1/32\(dq)
+.I $ echo 127.0.0.100 | grep -P $(echo 127.0.0.1/32 | hath -b)
.I $ echo $?
1
.fi
-.P
But, this may also cause the regex to match something that isn't an IP
address:
.nf
-.I $ echo \(dqx127.0.0.1x\(dq | grep -Po $(hath -b <<< \(dq127.0.0.1/32\(dq)
+.I $ echo x127.0.0.1x | grep -Po $(echo 127.0.0.1/32 | hath -b)
x127.0.0.1x
.fi
+
+.IP \fB\-\-normalize\fR,\ \fB\-n\fR
+(reduced mode only)
+
+Normalize the output representation of CIDRs by zeroing the host
+bits. This option only has an effect in \(dqreduced\(dq mode, because
+in the \(dqduped\(dq or \(dqdiffed\(dq modes, it would be confusing to
+see CIDRs that you did not input in the first place being removed.
+
+.nf
+.I $ echo 127.0.0.1/8 | hath reduced
+127.0.0.1/8
+.I $ echo 127.0.0.1/8 | hath reduced --normalize
+127.0.0.0/8
+.fi
+.SH BUGS
+
+Send bugs to michael@orlitzky.com.