63 lines
2.9 KiB
Markdown
63 lines
2.9 KiB
Markdown
# 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).
|