rping/README.md

73 lines
2.2 KiB
Markdown

# rping
`rping` is a Linux command-line utility for constructing and sending IPv4 or IPv6 ICMP packets. It is intended for network troubleshooting and packet inspection when the standard `ping` command does not expose enough control over packet fields and payloads.
## Requirements
- Rust 1.70 or newer; `rustup` uses the repository's pinned toolchain automatically.
- Linux for live probes.
- Permission to create ping sockets for normal live probes. Raw probes require root or `CAP_NET_RAW`.
Dry runs only construct and display packets, so they do not require network access or socket privileges.
## Build
From the repository root:
```sh
cargo build --locked --release
```
The executable is written to `target/release/rping`.
## Quick start
Construct an exact-size IPv4 echo request without DNS lookups or socket access:
```sh
cargo run --locked --quiet -- 127.0.0.1 \
--payload-hex '00 ff 01' \
--padding none \
--dry-run
```
Expected output:
```text
probe 1 seq=16962 dry run
1 probes, 0 replies, 0 ICMP errors, 1 dry runs
```
For a live probe, omit `--dry-run`. Review the Linux permissions described in [Usage](docs/usage.md) first; do not grant broader privileges than necessary.
## Advanced
- [Usage](docs/usage.md) covers address families, payloads, packet sizing, output formats, live probes, and raw sockets.
- [Development and CI](docs/development.md) covers contributor commands, the minimum supported Rust version, dependency policy, coverage, and badge publication.
- [Releasing](docs/releasing.md) covers release preparation, local packaging, collision checks, and publication through `rust_realease`.
The complete command reference is always available locally:
```sh
cargo run --locked -- --help
```
## Development
Run the local quality gates from the repository root:
```sh
cargo fmt --all -- --check
cargo check --locked --all-targets --all-features
cargo +1.70.0 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
```
See [Development and CI](docs/development.md) for toolchain setup, documentation, and coverage commands.
## License
Licensed under the [MIT License](LICENSE).