86 lines
3.6 KiB
Markdown
86 lines
3.6 KiB
Markdown
|
# IPVarch — Internet Protocol Version Architect
|
|||
|
|
|
|||
|
|
A tiny ANSI C (C89, tcc-friendly) command-line tool for inspecting and
|
|||
|
|
planning IP addresses and IPv4 networks. Rules follow `ipaddrinfo.html`
|
|||
|
|
(IPv4 classes A–E, RFC 1918 private ranges, IPv6 unicast/multicast/
|
|||
|
|
link-local/unique-local).
|
|||
|
|
|
|||
|
|
## Usage
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
ipvarch <address> inspect an IPv4 or IPv6 address
|
|||
|
|
ipvarch --plan-network <ipv4>/<prefix> plan a network (/8 /16 /24 /32)
|
|||
|
|
ipvarch --random-ipv4network <scope> <prefix> random valid network plan
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Examples
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
$ ipvarch 192.168.1.1
|
|||
|
|
Address: 192.168.1.1
|
|||
|
|
Type: IPv4
|
|||
|
|
Class: C
|
|||
|
|
Scope: Private (RFC 1918)
|
|||
|
|
Octets: 192, 168, 1, 1
|
|||
|
|
|
|||
|
|
$ ipvarch 2001:db8::1
|
|||
|
|
Address: 2001:db8::1
|
|||
|
|
Type: IPv6
|
|||
|
|
Class: n/a (IPv6 has no address classes)
|
|||
|
|
Scope: Public (global unicast)
|
|||
|
|
Groups: 2001 0db8 0000 0000 0000 0000 0000 0001
|
|||
|
|
Octets: 32, 1, 13, 184, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1
|
|||
|
|
|
|||
|
|
$ ipvarch --plan-network 192.168.1.0/24
|
|||
|
|
┌───────────────────┬───────────────────────────────┐
|
|||
|
|
│ IPVarch Network Plan - 192.168.1.0 /24 │
|
|||
|
|
├───────────────────┼───────────────────────────────┤
|
|||
|
|
│ Network address │ 192.168.1.0 │
|
|||
|
|
│ Netmask │ 255.255.255.0 /24 │
|
|||
|
|
│ Broadcast │ 192.168.1.255 │
|
|||
|
|
│ Usable host range │ 192.168.1.1 - 192.168.1.254 │
|
|||
|
|
│ Usable hosts │ 254 │
|
|||
|
|
│ Class │ C │
|
|||
|
|
│ Scope │ Private (RFC 1918) │
|
|||
|
|
│ Gateway IP │ 192.168.1.1 │
|
|||
|
|
│ DNS/DHCP server │ 192.168.1.2 │
|
|||
|
|
│ DHCP pool │ 192.168.1.100 - 192.168.1.254 │
|
|||
|
|
└───────────────────┴───────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`--plan-network` takes literal CIDR masks (`/8`=255.0.0.0, `/16`, `/24`,
|
|||
|
|
`/32`=single host). Host bits must be zero (it tells you the canonical
|
|||
|
|
network address otherwise). The gateway is the first usable host, the
|
|||
|
|
DNS/DHCP server the second, and the DHCP pool is the fixed last-octet
|
|||
|
|
`.100`–`.254` range.
|
|||
|
|
|
|||
|
|
`--random-ipv4network private|public /8|/16|/24|/32` generates a random
|
|||
|
|
valid network constrained to real private space (10/8, 172.16/12,
|
|||
|
|
192.168/16) or public/global-unicast space (never multicast, loopback,
|
|||
|
|
reserved, or documentation ranges) and prints the same plan table.
|
|||
|
|
|
|||
|
|
## Testing (Make + python3, stdlib only)
|
|||
|
|
|
|||
|
|
```sh
|
|||
|
|
make # build (tcc, falls back to gcc)
|
|||
|
|
make test # full validity matrix: info, canonicalization, plan,
|
|||
|
|
# random (statistical), invalid inputs, edge cases, usage
|
|||
|
|
make test-sanitize # rebuild with gcc/clang ASan+UBSan and run full matrix
|
|||
|
|
make check # strict C89 build: -std=c89 -pedantic -Wall -Wextra
|
|||
|
|
make clean
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Notes:
|
|||
|
|
|
|||
|
|
- The runner prints `PASS`/`FAIL` per case and exits nonzero on failure.
|
|||
|
|
- Run a subset with `python3 tests/runner.py --bin ./ipvarch --filter plan`.
|
|||
|
|
- Add cases as simple dict entries in `tests/cases.py`.
|
|||
|
|
- Memory safety runs through compiler instrumentation (tcc has no
|
|||
|
|
sanitizer support, so `test-sanitize` uses gcc/clang); the runner
|
|||
|
|
detects sanitizer aborts explicitly and reports them per case.
|
|||
|
|
|
|||
|
|
## Exit codes
|
|||
|
|
|
|||
|
|
- `0` — success
|
|||
|
|
- `1` — any error (bad address, bad prefix, bad usage); the message goes
|
|||
|
|
to stderr prefixed with `ipvarch: error:`.
|