91 lines
4.4 KiB
Markdown
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.
|