]> 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 tests for the --barriers option.
[hath.git] / doc / man1 / hath.1
diff --git a/doc/man1/hath.1 b/doc/man1/hath.1
index 7006ac3115c26212571e87b42311776157489384..57684f5d2d34a3df75cde65e9ecf409637c82018 100644 (file)
--- a/doc/man1/hath.1
+++ b/doc/man1/hath.1
@@ -2,98 +2,155 @@
 
 .SH NAME
 hath \- Manipulate network blocks in CIDR notation
 
 .SH NAME
 hath \- Manipulate network blocks in CIDR notation
-
 .SH SYNOPSIS
 
 .SH SYNOPSIS
 
-\fBhath\fR [\fBregexed|reduced|duped|diffed\fR] [\fB\-h\fR] [\fB-i \fIFILE\fR] \fI<input>\fR
-
+\fBhath\fR [\fBregexed|reduced|duped|diffed|listed|reversed\fR] [\fB\-hb\fR] \fI<input>\fR
 .SH INPUT
 .SH INPUT
-
 .P
 .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
 .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:
 .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.
 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.
 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.
 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.
 .P
 Hath does just that. It takes as its input (via stdin, or a file with
 the -i parameter) a list of CIDR blocks.
-
 .SH MODES
 .SH MODES
-
 .P
 .P
-Hath currently has four modes:
-
-.IP \[bu] 2
+Hath has several modes:
+.IP \(bu 2
 \fBRegexed\fR
 \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
-.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 $ 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))
+.fi
+.IP \(bu 2
 \fBReduced\fR
 \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
-.B $ hath reduced <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
+.I $ hath reduced <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
 10.0.0.0/23
 10.0.0.0/23
-
-.IP \[bu]
+.fi
+.IP \(bu 2
 \fBDuped\fR
 \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
-.B $ hath duped <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
+.I $ hath duped <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
 10.0.0.0/24
 10.0.1.0/24
 10.0.0.0/24
 10.0.1.0/24
-
-.IP \[bu]
+.fi
+.IP \(bu 2
 \fBDiffed\fR
 \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
-.B $ hath diffed <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
+.I $ hath diffed <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
 -10.0.0.0/24
 -10.0.1.0/24
 +10.0.0.0/23
 -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
+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
+.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:
 .P
 .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.
+.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
+.fi
 
 .SH OPTIONS
 
 
 .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 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.
+
+.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)
+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 $?
+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)
+x127.0.0.1x
+.fi
Haskell program for working with network blocks in CIDR notation.