rping/docs/usage.md

91 lines
4.4 KiB
Markdown

# Using rping
This page expands on the [README quick start](../README.md#quick-start). Run commands from the repository root after building with `cargo build --locked --release`, or replace `./target/release/rping` with `cargo run --locked --`.
## Safe packet inspection
`--dry-run` builds packets without resolving hostnames or opening a socket. A hostname in a dry run defaults to IPv4 because no DNS lookup occurs; use `--family v6` to inspect an IPv6 packet.
```sh
# Show the bytes of two exact-size IPv4 packets.
./target/release/rping 127.0.0.1 \
--payload-hex '00 ff 01' \
--padding none \
--count 2 \
--output hex \
--dry-run
# Produce newline-delimited JSON for an IPv6 packet.
./target/release/rping ::1 \
--family v6 \
--payload-hex '00 ff' \
--padding none \
--output json \
--dry-run
```
## Live probes and permissions
Linux is the primary runtime target. Datagram mode needs permission to create ping sockets through `net.ipv4.ping_group_range` and, for IPv6, an ICMPv6 datagram socket. Raw mode needs root or the `CAP_NET_RAW` capability. Prefer datagram mode unless control over raw-only fields is required.
```sh
# Send four IPv6 echo probes at 500 ms intervals with a hop limit of 16.
./target/release/rping ::1 --family v6 --count 4 --interval-ms 500 --ttl 16
# Use a raw socket when the ICMP identifier must be controlled.
sudo ./target/release/rping 127.0.0.1 --raw --identifier 4660 --sequence 1
```
Sending non-echo types or nonzero codes requires `--raw`; `--dry-run` can inspect them without privileges. Echo requests require code 0.
## Payload and packet sizing
The `--payload`, `--payload-hex`, and `--payload-file` options are mutually exclusive. Hexadecimal input accepts spaces, colons, and underscores.
The default packet size is 64 bytes. Padding modes behave as follows:
- `auto` fills unused bytes with random alphanumeric data when no payload is supplied and zeroes them otherwise.
- `zero` fills unused bytes with zeroes.
- `random` fills unused bytes with random alphanumeric data.
- `none` makes the packet exactly eight header bytes plus the payload. If `--size` is also supplied, it must match that exact size.
Packet sizes must be between 8 and 65515 bytes. `--count` is limited to 65536 so a single run does not reuse a 16-bit sequence number; the sequence wraps after 65535.
## Output and exit status
The output modes are:
- `summary` prints one status line per probe and a final summary.
- `hex` adds full packet dumps.
- `json` emits one JSON object per probe and a final summary object.
JSON probe objects include status, sequence, requested packet bytes, and received bytes when available. The command exits successfully when every live probe receives a matching reply or when every probe is a dry run. Invalid input, socket failures, timeouts, and matching ICMP errors produce a nonzero exit status. Unrelated or malformed packets are ignored until the probe deadline.
The hex dump is the ICMP packet passed to the socket. In IPv4 datagram mode, Linux may replace its identifier and checksum; use raw mode when those fields must be controlled. The kernel supplies the IPv4 header in either mode.
For ICMPv6, the kernel calculates the mandatory checksum from the IPv6 pseudo-header, so dry-run output contains zero in the checksum field and is not the complete on-wire packet.
## Options
| Option | Meaning | Default |
| --- | --- | --- |
| `--family` | Address family: `auto`, `v4`, or `v6` | `auto` |
| `-t`, `--type` | ICMP type | 8 for IPv4; 128 for IPv6 |
| `--code` | ICMP code | 0 |
| `-i`, `--identifier` | 16-bit identifier | 16962 (`0x4242`) |
| `-q`, `--sequence` | Initial 16-bit sequence number | 16962 |
| `-p`, `--payload` | UTF-8 payload bytes | None |
| `--payload-hex` | Hexadecimal payload bytes | None |
| `--payload-file` | Binary payload file | None |
| `-s`, `--size` | Total ICMP size, including the header | 64 unless padding is `none` |
| `--padding` | `auto`, `zero`, `random`, or `none` | `auto` |
| `-c`, `--count` | Number of probes | 1 |
| `--interval-ms` | Delay between probe starts | 1000 ms |
| `--timeout-ms` | Per-probe response deadline | 1000 ms |
| `--ttl` | IPv4 TTL or IPv6 unicast hop limit | System default |
| `--output` | `summary`, `hex`, or `json` | `summary` |
| `--raw` | Use a raw ICMP socket | Off |
| `--dry-run` | Build packets without DNS or sockets | Off |
Use `rping --help` for the authoritative command-line reference.