This code is a simple implementation of the Internet Control Message Protocol (ICMP) ping utility.
Go to file
Dandaedre 2c7343f57d
Complete ICMP probe controls and add IPv6 support
2026-09-17 16:52:42 +02:00
src Complete ICMP probe controls and add IPv6 support 2026-09-17 16:52:42 +02:00
.gitignore Modernize Rust toolchain, CLI, and CI; fix ICMP handling 2026-09-14 21:23:38 +02:00
Cargo.lock Modernize Rust toolchain, CLI, and CI; fix ICMP handling 2026-09-14 21:23:38 +02:00
Cargo.toml Complete ICMP probe controls and add IPv6 support 2026-09-17 16:52:42 +02:00
Jenkinsfile lessend requiremrent for fmt 2026-09-14 21:25:40 +02:00
LICENSE Initial commit 2022-12-08 12:36:53 +01:00
README.md Complete ICMP probe controls and add IPv6 support 2026-09-17 16:52:42 +02:00
rust-toolchain.toml Modernize Rust toolchain, CLI, and CI; fix ICMP handling 2026-09-14 21:23:38 +02:00

README.md

rping

A small ICMP packet tool for IPv4 and IPv6. It builds packets from explicit fields and payload bytes, sends one or more probes, matches their replies or ICMP errors, and can show the bytes without opening a socket.

Build

cargo build --locked --release

Rust 1.98.1 is pinned in rust-toolchain.toml. Linux is the primary runtime target. Live datagram mode needs permission to create ping sockets (net.ipv4.ping_group_range and, for IPv6, an ICMPv6 datagram socket). Raw mode needs root or CAP_NET_RAW.

Usage

rping [OPTIONS] <DESTINATION>
# Inspect two exact-size IPv4 probes without DNS or socket privileges.
cargo run -- 127.0.0.1 --payload-hex '00 ff 01' --padding none --count 2 --output hex --dry-run

# Inspect IPv6 packets as newline-delimited JSON.
cargo run -- ::1 --family v6 --payload-hex '00 ff' --padding none --output json --dry-run

# Send four echo probes at 500 ms intervals, with a hop limit of 16.
cargo run -- ::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
Option Meaning Default
--family auto, v4, or v6; auto uses the first resolved address 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; increments per probe 16962
-p, --payload UTF-8 payload bytes None
--payload-hex Hex bytes; spaces, colons and underscores allowed None
--payload-file Read binary payload from file None
-s, --size Total ICMP size, header included; 8–65515 bytes 64 unless padding is none
--padding auto, zero, random, or none auto
-c, --count Number of probes 1
--interval-ms Time between probe starts, in milliseconds 1000
--timeout-ms Per-probe response deadline, in milliseconds 1000
--ttl IPv4 TTL or IPv6 unicast hop limit, 1–255 System default
--output summary, hex, or json summary
--raw Use a raw ICMP socket Off
--dry-run Build packets without DNS or socket access Off

Payload options are mutually exclusive. auto fills unused bytes with random alphanumeric bytes when no payload was supplied; otherwise it zero-fills them. random and zero select explicit padding. none makes the packet exactly eight bytes plus the payload; if --size is given, it must match. The sequence wraps after 65535. --count is limited to 65536 so one run does not reuse a sequence number.

The output modes are a per-probe summary, full hex dumps plus summaries, or newline-delimited JSON with one object per probe and a final summary object. JSON probe objects include the status, sequence, requested packet bytes, and received bytes when available. A run exits 0 when every probe receives a matching reply, or when all probes are dry runs. A timeout, ICMP error, invalid input, or socket failure exits nonzero. Unrelated or malformed packets are ignored until each probe's deadline.

The hex dump shows the ICMP packet passed to the socket. In IPv4 datagram mode, Linux may rewrite the identifier and checksum. Use --raw for control over those fields. The kernel supplies the IPv4 header in both modes. For ICMPv6, the kernel calculates the mandatory checksum using the IPv6 pseudo-header, so dry-run output shows zero in the checksum field. It is not the complete on-wire ICMPv6 packet. Sending non-echo types or nonzero codes requires --raw; --dry-run can inspect them without privileges. Only matching echo replies and matching ICMP errors are recognized as responses. A dry run with a hostname defaults to IPv4 unless --family v6 is specified, because dry runs do not resolve hostnames.

Development

cargo fmt --all -- --check
cargo check --locked --all-targets --all-features
cargo test --locked --all-targets --all-features
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo build --locked --release --all-features

Tests do not need network access. CI does not run live pings.

License

MIT.