doc/man1/hath.1

   1 .TH hath 1
   2
   3 .SH NAME
   4 hath \- Manipulate network blocks in CIDR notation
   5 .SH SYNOPSIS
   6
   7 \fBhath\fR [\fBregexed|reduced|duped|diffed|listed\fR] [\fB\-hb\fR] \fI<input>\fR
   8 .SH INPUT
   9 .P
  10 The \fIinput\fR (stdin) should be a list of CIDR blocks, separated by
  11 whitespace. Empty lines will be ignored, but otherwise, malformed
  12 entries will cause an error to be displayed.
  13 .SH DESCRIPTION
  14 .P
  15 Hath is a Haskell program for working with network blocks in CIDR
  16 notation. When dealing with blocks of network addresses, there are a
  17 few things that one usually wants to do with them:
  18 .IP \(bu 2
  19 Create a regular expression matching the CIDR block(s). This is
  20 because grep will throw up if you feed it CIDR.
  21 .IP \(bu
  22 Combine small blocks into larger ones. For example, if you have two
  23 consecutive /24s, they might combine into a larger /23.
  24 .IP \(bu
  25 View the result of block combination in a useful way.
  26 .IP \(bu
  27 List them.
  28 .P
  29 Hath does just that. It takes as its input (via stdin) a list of CIDR
  30 blocks.
  31 .SH MODES
  32 .P
  33 Hath has several modes:
  34 .IP \(bu 2
  35 \fBRegexed\fR
  36
  37 This computes a (Perl-compatible) regular expression matching
  38 the input CIDR blocks. It's the default mode of operation.
  39
  40 .nf
  41 .I $ echo \(dq10.0.0.0/29 10.0.0.8/29\(dq | hath
  42 ((10)\.(0)\.(0)\.(15|14|13|12|11|10|9|8|7|6|5|4|3|2|1|0))
  43 .fi
  44 .IP \(bu 2
  45 \fBReduced\fR
  46
  47 This combines small blocks into larger ones where possible, and
  48 eliminates redundant blocks. The output should be equivalent to
  49 the input, though.
  50
  51 .nf
  52 .I $ echo \(dq10.0.0.0/24 10.0.1.0/24\(dq | hath reduced
  53 10.0.0.0/23
  54 .fi
  55 .IP \(bu 2
  56 \fBDuped\fR
  57
  58 Shows only the blocks that would be removed by reduce; that is, it
  59 shows the ones that would get combined into larger blocks or are
  60 simply redundant.
  61
  62 .nf
  63 .I $ echo \(dq10.0.0.0/24 10.0.1.0/24\(dq | hath duped
  64 10.0.0.0/24
  65 10.0.1.0/24
  66 .fi
  67 .IP \(bu 2
  68 \fBDiffed\fR
  69
  70 Shows what would change if you used reduce. Uses diff-like
  71 notation.
  72
  73 .nf
  74 .I $ echo \(dq10.0.0.0/24 10.0.1.0/24\(dq | hath diffed
  75 -10.0.0.0/24
  76 -10.0.1.0/24
  77 +10.0.0.0/23
  78 .fi
  79 .IP \(bu 2
  80 \fBListed\fR
  81
  82 List the IP addresses contained within the given CIDRs.
  83
  84 .nf
  85 .I $ echo 192.168.0.240/29 | hath listed
  86 192.168.0.240
  87 192.168.0.241
  88 192.168.0.242
  89 192.168.0.243
  90 192.168.0.244
  91 192.168.0.245
  92 192.168.0.246
  93 192.168.0.247
  94 .fi
  95 .SH EXAMPLES
  96 .P
  97 Use the \(dqdig\(dq command to look up the PTR records for a netblock:
  98
  99 .nf
 100 .I $ echo 198.41.0.4/30 | hath listed | xargs -I{} dig +noall +answer -x '{}'
 101 4.0.41.198.in-addr.arpa. 897    IN      PTR     a.root-servers.net.
 102 6.0.41.198.in-addr.arpa. 900    IN      PTR     rs.internic.net.
 103 .fi
 104 .SH OPTIONS
 105
 106 .IP \fB\-\-barriers\fR,\ \fB\-b\fR
 107 (regexed mode only)
 108
 109 Place barriers in front/back of the regex to prevent, for
 110 example, '127.0.0.1' from matching '127.0.0.100'. The downside is that
 111 the resulting regexp will match something that is not an IP address.
 112 This can interfere with things like \fIgrep -o\fR.
 113
 114 Without \fB\-\-barriers\fR, you can match things you shouldn't:
 115
 116 .nf
 117 .I $ echo 127.0.0.100 | grep -P $(echo 127.0.0.1/32 | hath)
 118 127.0.0.100
 119 .fi
 120
 121 Using \fB\-\-barriers\fR can prevent this:
 122
 123 .nf
 124 .I $ echo 127.0.0.100 | grep -P $(echo 127.0.0.1/32 | hath -b)
 125 .I $ echo $?
 126 1
 127 .fi
 128
 129 But, this may also cause the regex to match something that isn't an IP
 130 address:
 131
 132 .nf
 133 .I $ echo x127.0.0.1x | grep -Po $(echo 127.0.0.1/32 | hath -b)
 134 x127.0.0.1x
 135 .fi
 136 .IP \fB\-\-normalize\fR,\ \fB\-n\fR
 137 (reduced mode only)
 138
 139 Normalize the output representation of CIDRs by zeroing the host
 140 bits. This option only has an effect in \(dqreduced\(dq mode, because
 141 in the \(dqduped\(dq or \(dqdiffed\(dq modes, it would be confusing to
 142 see CIDRs that you did not input in the first place being removed.
 143
 144 .nf
 145 .I $ echo 127.0.0.1/8 | hath reduced
 146 127.0.0.1/8
 147 .I $ echo 127.0.0.1/8 | hath reduced --normalize
 148 127.0.0.0/8
 149 .fi
 150 .IP \fB\-\-sort\fR,\ \fB\-s\fR
 151 (reduced mode only)
 152
 153 Sort the output CIDRs numerically by octet. The \(dqsort\(dq utility
 154 doesn't understand IP addresses, so the default pipe-to-sort approach
 155 fails in some cases:
 156
 157 .nf
 158 .I $ echo \(dq10.0.121.32/28 10.0.93.248/29\(dq | hath reduced | sort
 159 10.0.121.32/28
 160 10.0.93.248/29
 161 .I $ echo \(dq10.0.121.32/28 10.0.93.248/29\(dq | hath reduced | sort -n
 162 10.0.121.32/28
 163 10.0.93.248/29
 164 .fi
 165
 166 That failure justifies adding the additional option to hath:
 167
 168 .nf
 169 .I $ echo \(dq10.0.121.32/28 10.0.93.248/29\(dq | hath reduced --sort
 170 10.0.93.248/29
 171 10.0.121.32/28
 172 .SH BUGS
 173
 174 Send bugs to michael@orlitzky.com.