diff --git a/README.md b/README.md index 848a4d7..6474e74 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,71 @@ # 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. +`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 ``` -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`. +The executable is written to `target/release/rping`. -## Usage +## Quick start + +Construct an exact-size IPv4 echo request without DNS lookups or socket access: ```sh -rping [OPTIONS] +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. + +The complete command reference is always available locally: + ```sh -# 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 +cargo run --locked -- --help ``` -| 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 +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 ``` -Tests do not need network access. CI does not run live pings. +See [Development and CI](docs/development.md) for toolchain setup, documentation, and coverage commands. ## License -[MIT](LICENSE). +Licensed under the [MIT License](LICENSE). diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..e1136cd --- /dev/null +++ b/docs/development.md @@ -0,0 +1,80 @@ +# Development and CI + +This page documents contributor and CI workflows for [`rping`](../README.md). Run all commands from the repository root. + +## Toolchains and dependencies + +The project declares Rust 1.70 as its minimum supported Rust version (MSRV). Jenkins checks all targets with Rust 1.70.0 and the locked dependency graph. The lockfile uses format version 3 so Cargo 1.70 can read it. + +The tracked `rust-toolchain.toml` pins Rust 1.98.1 with `rustfmt`, Clippy, and LLVM tools for normal development and coverage. Install the MSRV toolchain separately before running its check: + +```sh +rustup toolchain install 1.70.0 --profile minimal +``` + +The project has four direct runtime dependencies. `clap` is constrained to the Rust-1.70-compatible 4.4 line, and `rand` uses the mature 0.8 line. CI uses locked dependency resolution. + +There is no `no_std` feature. This is an operating-system CLI whose main path uses sockets, DNS resolution, files, clocks, threads, heap allocation, terminal output, and operating-system randomness. A useful `no_std` API would require designing a separate packet-construction library rather than feature-gating the application. + +## Quality gates + +Run the same checks used by CI: + +```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 +cargo doc --locked --all-features --no-deps +``` + +Tests do not require network access. CI intentionally does not run live probes because worker permissions for ICMP sockets are not assumed. + +## Coverage + +CI pins `cargo-llvm-cov` 0.9.0 and enforces a 40% line-coverage floor without excluding production code. Run the exact coverage gate locally with: + +```sh +cargo llvm-cov \ + --locked \ + --all-features \ + --all-targets \ + --json \ + --summary-only \ + --output-path coverage/coverage-summary.json \ + --fail-under-lines 40 +``` + +`coverage/coverage-summary.json` is temporary. CI validates its overall line percentage, renders the coverage badge, and removes the summary. + +## CI badges + +The authoritative version comes from `Cargo.toml` through `cargo metadata`. Jenkins records successful tests and coverage with build-specific markers, then generates version, test, and coverage badges from cleanup so failed builds cannot leave stale passing results. + +Jenkins validates and archives exactly these ignored files with fingerprints: + +```text +coverage/version.svg +coverage/test.svg +coverage/coverage.svg +``` + +In a Jenkins multibranch job, `BRANCH_NAME` restricts publication to the `main` branch. The publisher atomically copies badges to: + +```text +/mnt/assets/coverage/Archive/rping/main/ +``` + +The intended public URLs are: + +```text +https://assets.dandaedre.com/coverage/Archive/rping/main/version.svg +https://assets.dandaedre.com/coverage/Archive/rping/main/test.svg +https://assets.dandaedre.com/coverage/Archive/rping/main/coverage.svg +``` + +These URLs must not be presented as live status badges until a successful default-branch Jenkins build has published them and each response has been verified as SVG XML. The asset server should mount the publication directory read-only, disable directory listings, use a restrictive content security policy for SVG, and revalidate mutable badge URLs or give them a short cache lifetime. + +The generic renderer in `scripts/ci-coverage-badges.sh` was copied from the `agent-tasks` source at revision `fb9d8f7d16f100c2d1377f23394a2302eac9ab18`. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..d2fbb19 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,90 @@ +# Using rping + +This page expands on the [README quick start](../README.md#quick-start). Run commands from the repository root after building with `cargo build --locked --release`, or replace `./target/release/rping` with `cargo run --locked --`. + +## Safe packet inspection + +`--dry-run` builds packets without resolving hostnames or opening a socket. A hostname in a dry run defaults to IPv4 because no DNS lookup occurs; use `--family v6` to inspect an IPv6 packet. + +```sh +# Show the bytes of two exact-size IPv4 packets. +./target/release/rping 127.0.0.1 \ + --payload-hex '00 ff 01' \ + --padding none \ + --count 2 \ + --output hex \ + --dry-run + +# Produce newline-delimited JSON for an IPv6 packet. +./target/release/rping ::1 \ + --family v6 \ + --payload-hex '00 ff' \ + --padding none \ + --output json \ + --dry-run +``` + +## Live probes and permissions + +Linux is the primary runtime target. Datagram mode needs permission to create ping sockets through `net.ipv4.ping_group_range` and, for IPv6, an ICMPv6 datagram socket. Raw mode needs root or the `CAP_NET_RAW` capability. Prefer datagram mode unless control over raw-only fields is required. + +```sh +# Send four IPv6 echo probes at 500 ms intervals with a hop limit of 16. +./target/release/rping ::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 +``` + +Sending non-echo types or nonzero codes requires `--raw`; `--dry-run` can inspect them without privileges. Echo requests require code 0. + +## Payload and packet sizing + +The `--payload`, `--payload-hex`, and `--payload-file` options are mutually exclusive. Hexadecimal input accepts spaces, colons, and underscores. + +The default packet size is 64 bytes. Padding modes behave as follows: + +- `auto` fills unused bytes with random alphanumeric data when no payload is supplied and zeroes them otherwise. +- `zero` fills unused bytes with zeroes. +- `random` fills unused bytes with random alphanumeric data. +- `none` makes the packet exactly eight header bytes plus the payload. If `--size` is also supplied, it must match that exact size. + +Packet sizes must be between 8 and 65515 bytes. `--count` is limited to 65536 so a single run does not reuse a 16-bit sequence number; the sequence wraps after 65535. + +## Output and exit status + +The output modes are: + +- `summary` prints one status line per probe and a final summary. +- `hex` adds full packet dumps. +- `json` emits one JSON object per probe and a final summary object. + +JSON probe objects include status, sequence, requested packet bytes, and received bytes when available. The command exits successfully when every live probe receives a matching reply or when every probe is a dry run. Invalid input, socket failures, timeouts, and matching ICMP errors produce a nonzero exit status. Unrelated or malformed packets are ignored until the probe deadline. + +The hex dump is the ICMP packet passed to the socket. In IPv4 datagram mode, Linux may replace its identifier and checksum; use raw mode when those fields must be controlled. The kernel supplies the IPv4 header in either mode. + +For ICMPv6, the kernel calculates the mandatory checksum from the IPv6 pseudo-header, so dry-run output contains zero in the checksum field and is not the complete on-wire packet. + +## Options + +| Option | Meaning | Default | +| --- | --- | --- | +| `--family` | Address family: `auto`, `v4`, or `v6` | `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 | 16962 | +| `-p`, `--payload` | UTF-8 payload bytes | None | +| `--payload-hex` | Hexadecimal payload bytes | None | +| `--payload-file` | Binary payload file | None | +| `-s`, `--size` | Total ICMP size, including the header | 64 unless padding is `none` | +| `--padding` | `auto`, `zero`, `random`, or `none` | `auto` | +| `-c`, `--count` | Number of probes | 1 | +| `--interval-ms` | Delay between probe starts | 1000 ms | +| `--timeout-ms` | Per-probe response deadline | 1000 ms | +| `--ttl` | IPv4 TTL or IPv6 unicast hop limit | System default | +| `--output` | `summary`, `hex`, or `json` | `summary` | +| `--raw` | Use a raw ICMP socket | Off | +| `--dry-run` | Build packets without DNS or sockets | Off | + +Use `rping --help` for the authoritative command-line reference.