]> 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
Document a pipe-to-sort and justify the lack of a special CIDR sort.
[hath.git] / doc / man1 / hath.1
diff --git a/doc/man1/hath.1 b/doc/man1/hath.1
index 3b245589da85d2280a617a006a6b862fb2172b30..85978353ab0bdd6ff43dd2876d610ce561d697fe 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
-((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
 .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 <<< \(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.240
 192.168.0.241
 192.168.0.242
@@ -94,63 +92,77 @@ 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.
+.SH EXAMPLES
 .P
 .P
+Use the \(dqdig\(dq command to look up the PTR records for a netblock:
+
 .nf
 .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:
+.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
 .P
 .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:
-.P
+Sort the \(dqreduced\(dq output:
+
 .nf
 .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 \(dq192.168.0.100/24 192.167.1.200/24\(dq | hath reduced | sort
+192.167.1.200/24
+192.168.0.100/24
 .fi
 
 .fi
 
+Sorting the output only makes sense for the \(dqreduced\(dq mode. In
+that mode, two output CIDRs cannot have same the numeric address and a
+different mask: one of them would contain the other, and the redundant
+one would be eliminated. As a result, there is no need for a special
+CIDR sort; the lexical or numerical sort provided by the \(dqsort\(dq
+utility will produce the same results as a more intelligent sort.
 .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 \(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
 
 127.0.0.100
 .fi
 
-.P
 Using \fB\-\-barriers\fR can prevent this:
 
 .nf
 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
 
 .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 \(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
 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.
Haskell program for working with network blocks in CIDR notation.