rping/README.md

63 lines
2.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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](https://www.rust-lang.org/tools/install), then run:
```sh
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
```sh
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`:
```sh
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
```sh
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](LICENSE).