rping/README.md

2.9 KiB
Raw Blame History

rping

A small IPv4 ICMP ping utility. It sends one packet, waits up to one second for a response, and prints the packet bytes, ICMP fields, and elapsed time.

Build

Install Rust with rustup, then run:

cargo build --locked --release

The repository pins Rust 1.98.1 and uses the Rust 2024 edition. Rustup installs the required toolchain automatically. Dependencies are recorded in Cargo.lock.

Linux is the primary runtime target. The default mode uses an ICMP datagram socket; your system must permit ping sockets for your user (on Linux, through net.ipv4.ping_group_range). Raw mode requires root or CAP_NET_RAW. IPv6 is not supported.

Usage

rping [OPTIONS] <DESTINATION>

Use an IPv4 address or a hostname with an IPv4 address. When running from the checkout, use cargo run -- or ./target/release/rping:

cargo run -- 127.0.0.1
cargo run -- 127.0.0.1 --payload "hello world" --size 64
./target/release/rping 127.0.0.1 --identifier 4660 --sequence 1
sudo ./target/release/rping 127.0.0.1 --raw
cargo run -- --help
Option Meaning Default
-t, --type <TYPE> ICMP type, as a decimal byte; 8 is an echo request 8
-i, --identifier <IDENTIFIER> Decimal 16-bit identifier 16962 (0x4242)
-q, --sequence <SEQUENCE> Decimal 16-bit sequence number 16962 (0x4242)
-p, --payload <PAYLOAD> UTF-8 text; remaining space is zero-filled Random alphanumeric bytes
-s, --size <SIZE> Total ICMP size, including the 8-byte header; 8–65515 bytes 64
--raw Use a raw ICMP socket Off
-h, --help Show usage and options
-V, --version Show version

The payload must fit within --size minus 8 bytes; text is measured in UTF-8 bytes. An empty payload generates random data. The ICMP code is always zero. The OS may replace the identifier and checksum in datagram mode. Large packets may exceed the network's MTU.

The destination is positional. Older README examples using --dest, --request, or --data were incorrect; these are not supported options. Invalid arguments, socket errors, and timeouts return a nonzero exit status.

Development and CI

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

The Jenkins pipeline runs these checks on a rust_nodocker worker with rustup installed and access to the Rust distribution server and crates.io. It uses the repository's toolchain without changing the worker's default. The existing publishChecks step requires the Jenkins Checks API plugin and a configured SCM checks publisher. Tests do not require network access or elevated socket privileges; CI does not run live pings.

License

MIT.