|
1 | | -iprange - manage IP ranges |
2 | | -========================== |
| 1 | +# iprange |
3 | 2 |
|
4 | | -Getting help |
5 | | ------------- |
| 3 | +`iprange` is a fast command-line tool for reading, normalizing, comparing, and exporting IPv4 address sets. |
6 | 4 |
|
7 | | -~~~~ |
8 | | -iprange --help 2>&1 | more |
9 | | -~~~~ |
| 5 | +It understands single IPs, CIDRs, netmasks, numeric IPs, ranges, and hostnames. You can use it to merge blocklists, compute intersections or exclusions, generate data for `ipset restore`, or compare multiple IP sets as CSV. |
10 | 6 |
|
11 | | -Installation from tar-file |
12 | | --------------------------- |
| 7 | +## What it can read |
13 | 8 |
|
14 | | -~~~~ |
15 | | -./configure && make && make install |
16 | | -~~~~ |
| 9 | +`iprange` accepts one entry per line and can mix formats in the same input: |
17 | 10 |
|
| 11 | +- single IPs |
| 12 | + - `1.2.3.4` |
| 13 | +- CIDRs |
| 14 | + - `1.2.3.0/24` |
| 15 | +- dotted netmasks |
| 16 | + - `1.2.3.0/255.255.255.0` |
| 17 | +- abbreviated IPs |
| 18 | + - `10.1` |
| 19 | + - `10.1.1` |
| 20 | +- IP ranges |
| 21 | + - `1.2.3.0 - 1.2.3.255` |
| 22 | +- ranges where both sides use CIDR or netmask notation |
| 23 | +- numeric IPs |
| 24 | +- hostnames |
18 | 25 |
|
19 | | -Installation from git |
20 | | ---------------------- |
| 26 | +Important input behavior: |
21 | 27 |
|
22 | | -~~~~ |
| 28 | +- Hostnames are resolved in parallel. |
| 29 | +- Comments after `#` or `;` are ignored. |
| 30 | +- Parsing uses `inet_aton()`, so octal and hex forms are accepted too. |
| 31 | +- Inputs can come from `stdin`, files, file lists, or directory expansion. |
| 32 | + |
| 33 | +## Main modes |
| 34 | + |
| 35 | +- `union` / `merge` / `optimize` |
| 36 | + - merge all inputs and print the normalized result |
| 37 | +- `common` |
| 38 | + - print the intersection of all inputs |
| 39 | +- `exclude-next` |
| 40 | + - merge the inputs before the option, then remove anything matched by the inputs after it |
| 41 | +- `ipset-reduce` |
| 42 | + - trade a controlled increase in entries for fewer prefixes |
| 43 | +- `compare` |
| 44 | + - compare all inputs against all other inputs and print CSV |
| 45 | +- `compare-first` |
| 46 | + - compare the first input against every other input |
| 47 | +- `compare-next` |
| 48 | + - compare one group of inputs against the next group |
| 49 | +- `count-unique` |
| 50 | + - merge all inputs and print CSV counts |
| 51 | +- `count-unique-all` |
| 52 | + - print one CSV count line per input |
| 53 | + |
| 54 | +## Quick examples |
| 55 | + |
| 56 | +Merge and normalize: |
| 57 | + |
| 58 | +```bash |
| 59 | +iprange blocklist-a.txt blocklist-b.txt |
| 60 | +``` |
| 61 | + |
| 62 | +Find common IPs: |
| 63 | + |
| 64 | +```bash |
| 65 | +iprange --common blocklist-a.txt blocklist-b.txt |
| 66 | +``` |
| 67 | + |
| 68 | +Exclude one set from another: |
| 69 | + |
| 70 | +```bash |
| 71 | +iprange allow.txt --exclude-next deny.txt |
| 72 | +``` |
| 73 | + |
| 74 | +Count unique entries: |
| 75 | + |
| 76 | +```bash |
| 77 | +iprange -C blocklist-a.txt blocklist-b.txt |
| 78 | +iprange --count-unique-all --header blocklist-a.txt blocklist-b.txt |
| 79 | +``` |
| 80 | + |
| 81 | +Generate single-IP output: |
| 82 | + |
| 83 | +```bash |
| 84 | +iprange -1 hosts.txt |
| 85 | +``` |
| 86 | + |
| 87 | +Generate binary output for fast round-trips on the same architecture: |
| 88 | + |
| 89 | +```bash |
| 90 | +iprange --print-binary blocklist.txt > blocklist.bin |
| 91 | +iprange blocklist.bin |
| 92 | +``` |
| 93 | + |
| 94 | +Generate `ipset restore`-style lines: |
| 95 | + |
| 96 | +```bash |
| 97 | +iprange --print-prefix 'add myset ' --print-suffix '' blocklist.txt |
| 98 | +``` |
| 99 | + |
| 100 | +## Build and install |
| 101 | + |
| 102 | +From a release tarball: |
| 103 | + |
| 104 | +```bash |
| 105 | +./configure |
| 106 | +make |
| 107 | +make install |
| 108 | +``` |
| 109 | + |
| 110 | +From git: |
| 111 | + |
| 112 | +```bash |
23 | 113 | ./autogen.sh |
24 | | -./configure && make && make install |
25 | | -~~~~ |
| 114 | +./configure |
| 115 | +make |
| 116 | +make install |
| 117 | +``` |
| 118 | + |
| 119 | +If you do not want to build the man page: |
| 120 | + |
| 121 | +```bash |
| 122 | +./configure --disable-man |
| 123 | +``` |
| 124 | + |
| 125 | +## Testing |
| 126 | + |
| 127 | +Project test entry points: |
| 128 | + |
| 129 | +- `./run-tests.sh` |
| 130 | + - CLI regression suite |
| 131 | +- `./run-build-tests.sh` |
| 132 | + - build and layout regressions |
| 133 | +- `./run-sanitizer-tests.sh` |
| 134 | + - ASAN/UBSAN/TSAN coverage |
| 135 | +- `make check` |
| 136 | + - normal build-integrated test path |
| 137 | +- `make check-sanitizers` |
| 138 | + - sanitizer-integrated test path |
| 139 | + |
| 140 | +## Repository layout |
| 141 | + |
| 142 | +- `src/` |
| 143 | + - C sources and headers |
| 144 | +- `packaging/` |
| 145 | + - packaging helpers, spec template, ebuild, and release tooling |
| 146 | +- `tests.d/` |
| 147 | + - CLI regression tests |
| 148 | +- `tests.build.d/` |
| 149 | + - build and layout regressions |
| 150 | +- `tests.sanitizers.d/` |
| 151 | + - sanitizer CLI regressions |
| 152 | +- `tests.tsan.d/` |
| 153 | + - TSAN regressions |
| 154 | +- `tests.unit/` |
| 155 | + - unit-style harnesses for internal edge cases |
| 156 | + |
| 157 | +## Getting help |
| 158 | + |
| 159 | +For the full option list: |
26 | 160 |
|
27 | | -When working with git, copy the hooks to the cloned folder: |
| 161 | +```bash |
| 162 | +iprange --help |
| 163 | +``` |
28 | 164 |
|
29 | | -~~~~ |
30 | | -cp hooks/* .git/hooks |
31 | | -~~~~ |
| 165 | +The project wiki content that originally documented the feature set is now folded into this README so the repository landing page explains the tool directly. |
0 commit comments