]> gitweb.michael.orlitzky.com - hath.git/blobdiff - doc/man1/hath.1
projects / hath.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Add a --sort flag to hath and document/test why it was needed after all.
[hath.git] / doc / man1 / hath.1
diff --git a/doc/man1/hath.1 b/doc/man1/hath.1
index 207e87069da13933484907dc3a8c798c8bad647d..69b362fe17079601c155d330918b91e48e61532c 100644 (file)
--- a/doc/man1/hath.1
+++ b/doc/man1/hath.1
@@ -4,7 +4,7 @@
 hath \- Manipulate network blocks in CIDR notation
 .SH SYNOPSIS
 
 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
 .SH INPUT
 .P
 The \fIinput\fR (stdin) should be a list of CIDR blocks, separated by
@@ -25,8 +25,6 @@ consecutive /24s, they might combine into a larger /23.
 View the result of block combination in a useful way.
 .IP \(bu
 List them.
 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) a list of CIDR
 blocks.
 .P
 Hath does just that. It takes as its input (via stdin) a list of CIDR
 blocks.
@@ -35,56 +33,56 @@ blocks.
 Hath has several modes:
 .IP \(bu 2
 \fBRegexed\fR
 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.
 This computes a (Perl-compatible) regular expression matching
 the input CIDR blocks. It's the default mode of operation.
-.P
+
 .nf
 .nf
-.I $ hath <<< \(dq10.0.0.0/29 10.0.0.8/29\(dq
+.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
 ((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.
 This combines small blocks into larger ones where possible, and
 eliminates redundant blocks. The output should be equivalent to
 the input, though.
-.P
+
 .nf
 .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
 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.
 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
 .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
 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.
 Shows what would change if you used reduce. Uses diff-like
 notation.
-.P
+
 .nf
 .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
 -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.
 List the IP addresses contained within the given CIDRs.
-.P
+
 .nf
 .nf
-.I $ hath listed <<< 192.168.0.240/29
+.I $ echo 192.168.0.240/29 | hath listed
 192.168.0.240
 192.168.0.241
 192.168.0.242
 192.168.0.240
 192.168.0.241
 192.168.0.242
@@ -94,63 +92,83 @@ List the IP addresses contained within the given CIDRs.
 192.168.0.246
 192.168.0.247
 .fi
 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 <<< 198.41.0.4/30
-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
 .P
+Use the \(dqdig\(dq command to look up the PTR records for a netblock:
+
 .nf
 .nf
-.I $ hath reversed +RTS -N25 <<< 198.41.0.4/24
-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
 .fi
-
 .SH OPTIONS
 
 .IP \fB\-\-barriers\fR,\ \fB\-b\fR
 .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
 Without \fB\-\-barriers\fR, you can match things you shouldn't:
 
 .nf
-.I $ echo 127.0.0.100 | grep -P $(hath <<< 127.0.0.1/32)
+.I $ echo 127.0.0.100 | grep -P $(echo 127.0.0.1/32 | hath)
 127.0.0.100
 .fi
 
 127.0.0.100
 .fi
 
-.P
 Using \fB\-\-barriers\fR can prevent this:
 
 .nf
 Using \fB\-\-barriers\fR can prevent this:
 
 .nf
-.I $ echo 127.0.0.100 | grep -P $(hath -b <<< 127.0.0.1/32)
+.I $ echo 127.0.0.100 | grep -P $(echo 127.0.0.1/32 | hath -b)
 .I $ echo $?
 1
 .fi
 
 .I $ echo $?
 1
 .fi
 
-.P
 But, this may also cause the regex to match something that isn't an IP
 address:
 
 .nf
 But, this may also cause the regex to match something that isn't an IP
 address:
 
 .nf
-.I $ echo x127.0.0.1x | grep -Po $(hath -b <<< 127.0.0.1/32)
+.I $ echo x127.0.0.1x | grep -Po $(echo 127.0.0.1/32 | hath -b)
 x127.0.0.1x
 .fi
 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
+.IP \fB\-\-sort\fR,\ \fB\-s\fR
+(reduced mode only)
+
+Sort the output CIDRs numerically by octet. The \(dqsort\(dq utility
+doesn't understand IP addresses, so the default pipe-to-sort approach
+fails in some cases:
+
+.nf
+.I $ echo \(dq10.0.121.32/28 10.0.93.248/29\(dq | hath reduced | sort
+10.0.121.32/28
+10.0.93.248/29
+.I $ echo \(dq10.0.121.32/28 10.0.93.248/29\(dq | hath reduced | sort -n
+10.0.121.32/28
+10.0.93.248/29
+.fi
+
+That failure justifies adding the additional option to hath:
+
+.nf
+.I $ echo \(dq10.0.121.32/28 10.0.93.248/29\(dq | hath reduced --sort
+10.0.93.248/29
+10.0.121.32/28
+.SH BUGS
+
+Send bugs to michael@orlitzky.com.
Haskell program for working with network blocks in CIDR notation.