X-Git-Url: http://gitweb.michael.orlitzky.com/?a=blobdiff_plain;f=doc%2Fman1%2Fhath.1;h=69b362fe17079601c155d330918b91e48e61532c;hb=2404313e648301064041c12fdab8d2f976c26a64;hp=7006ac3115c26212571e87b42311776157489384;hpb=81f6f0ca67347de6b3e3f57b5b50bb543cc7c146;p=hath.git
diff --git a/doc/man1/hath.1 b/doc/man1/hath.1
index 7006ac3..69b362f 100644
--- a/doc/man1/hath.1
+++ b/doc/man1/hath.1
@@ -2,57 +2,46 @@
.SH NAME
hath \- Manipulate network blocks in CIDR notation
-
.SH SYNOPSIS
-\fBhath\fR [\fBregexed|reduced|duped|diffed\fR] [\fB\-h\fR] [\fB-i \fIFILE\fR] \fI\fR
-
+\fBhath\fR [\fBregexed|reduced|duped|diffed|listed\fR] [\fB\-hb\fR] \fI\fR
.SH INPUT
-
.P
-The \fIinput\fR (default: stdin) should be a list of CIDR blocks,
-separated by whitespace. Empty lines will be ignored, but otherwise,
-malformed entries will cause an error to be displayed.
-
+The \fIinput\fR (stdin) should be a list of CIDR blocks, separated by
+whitespace. Empty lines will be ignored, but otherwise, malformed
+entries will cause an error to be displayed.
.SH DESCRIPTION
-
.P
Hath is a Haskell program for working with network blocks in CIDR
notation. When dealing with blocks of network addresses, there are a
few things that one usually wants to do with them:
-
-.IP \[bu] 2
+.IP \(bu 2
Create a regular expression matching the CIDR block(s). This is
because grep will throw up if you feed it CIDR.
-
-.IP \[bu]
+.IP \(bu
Combine small blocks into larger ones. For example, if you have two
consecutive /24s, they might combine into a larger /23.
-
-.IP \[bu]
+.IP \(bu
View the result of block combination in a useful way.
-
+.IP \(bu
+List them.
.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 currently has four modes:
-
-.IP \[bu] 2
+Hath has several modes:
+.IP \(bu 2
\fBRegexed\fR
This computes a (Perl-compatible) regular expression matching
the input CIDR blocks. It's the default mode of operation.
.nf
-.B $ hath <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
-([^\.0-9](10)\.(0)\.(0)\.(0)[^\.0-9]|[^\.0-9](10)\.(0)\.(1)
-\.(0)[^\.0-9])
-
-.IP \[bu]
+.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
This combines small blocks into larger ones where possible, and
@@ -60,10 +49,10 @@ eliminates redundant blocks. The output should be equivalent to
the input, though.
.nf
-.B $ 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
-
-.IP \[bu]
+.fi
+.IP \(bu 2
\fBDuped\fR
Shows only the blocks that would be removed by reduce; that is, it
@@ -71,29 +60,115 @@ shows the ones that would get combined into larger blocks or are
simply redundant.
.nf
-.B $ 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
-
-.IP \[bu]
+.fi
+.IP \(bu 2
\fBDiffed\fR
Shows what would change if you used reduce. Uses diff-like
notation.
.nf
-.B $ 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
+List the IP addresses contained within the given CIDRs.
+
+.nf
+.I $ echo 192.168.0.240/29 | hath listed
+192.168.0.240
+192.168.0.241
+192.168.0.242
+192.168.0.243
+192.168.0.244
+192.168.0.245
+192.168.0.246
+192.168.0.247
+.fi
+.SH EXAMPLES
.P
-Each of the modes also supports a present-tense flavor; the following
-are equivalent to their counterparts: \fBregex\fR, \fBreduce\fR,
-\fBdupe\fR, \fBdiff\fR.
+Use the \(dqdig\(dq command to look up the PTR records for a netblock:
+.nf
+.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\-\-input\fR,\ \fB\-i\fR
-Specify the input file containing a list of CIDRs, rather than using
-stdin (the default).
+.IP \fB\-\-barriers\fR,\ \fB\-b\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.
+
+Without \fB\-\-barriers\fR, you can match things you shouldn't:
+
+.nf
+.I $ echo 127.0.0.100 | grep -P $(echo 127.0.0.1/32 | hath)
+127.0.0.100
+.fi
+
+Using \fB\-\-barriers\fR can prevent this:
+
+.nf
+.I $ echo 127.0.0.100 | grep -P $(echo 127.0.0.1/32 | hath -b)
+.I $ echo $?
+1
+.fi
+
+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 $(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
+.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.