From 2a2f511333a511feb35918a01fe71a489ad7cf97 Mon Sep 17 00:00:00 2001 From: durch Date: Mon, 1 Dec 2025 13:14:55 +0100 Subject: [PATCH] Update gateway-probe README with localnet mode docs - Add Test Modes section explaining mixnet/single-hop/two-hop/lp-only - Add Localnet Mode (run-local) usage examples - Add Split Network Configuration for docker setups - Add CLI Reference with all new flags - Add Output section with JSON example Closes: nym-mj2q --- nym-gateway-probe/README.md | 166 ++++++++++++++++++++++++------------ 1 file changed, 113 insertions(+), 53 deletions(-) diff --git a/nym-gateway-probe/README.md b/nym-gateway-probe/README.md index eab109d13f..042de230ee 100644 --- a/nym-gateway-probe/README.md +++ b/nym-gateway-probe/README.md @@ -17,67 +17,127 @@ sudo apt install libdbus-1-dev libmnl-dev libnftnl-dev protobuf-compiler llvm-de Build required libraries and executables ```sh -# build the prober cargo build -p nym-gateway-probe ``` +## Test Modes + +The probe supports different test modes via the `--mode` flag: + +| Mode | Description | +|------|-------------| +| `mixnet` | Traditional mixnet testing - entry/exit pings + WireGuard via authenticator (default) | +| `single-hop` | LP registration + WireGuard on single gateway (no mixnet) | +| `two-hop` | Entry LP + Exit LP (nested forwarding) + WireGuard tunnel | +| `lp-only` | LP registration only - test handshake, skip WireGuard | + ## Usage -```sh -Usage: nym-gateway-probe [OPTIONS] +### Standard Mode (via nym-api) -Options: - -c, --config-env-file - Path pointing to an env file describing the network - -g, --entry-gateway - The specific gateway specified by ID - -n, --node - Identity of the node to test - --min-gateway-mixnet-performance - - --min-gateway-vpn-performance - - --only-wireguard - - -i, --ignore-egress-epoch-role - Disable logging during probe - --no-log - - -a, --amnezia-args - Arguments to be appended to the wireguard config enabling amnezia-wg configuration - - --netstack-download-timeout-sec - [default: 180] - --netstack-v4-dns - [default: 1.1.1.1] - --netstack-v6-dns - [default: 2606:4700:4700::1111] - --netstack-num-ping - [default: 5] - --netstack-send-timeout-sec - [default: 3] - --netstack-recv-timeout-sec - [default: 3] - --netstack-ping-hosts-v4 - [default: nymtech.net] - --netstack-ping-ips-v4 - [default: 1.1.1.1] - --netstack-ping-hosts-v6 - [default: ipv6.google.com] - --netstack-ping-ips-v6 - [default: 2001:4860:4860::8888 2606:4700:4700::1111 2620:fe::fe] - -h, --help - Print help - -V, --version - Print version -``` - -Examples +Test gateways registered in nym-api directory: ```sh -# Run a basic probe against the node with id "qj3GgGYg..." +# Test a specific gateway (mixnet mode) nym-gateway-probe -g "qj3GgGYgGZZ3HkFrtD1GU9UJ5oNXME9eD2xtmPLqYYw" -# Run a probe against the node with id "qj3GgGYg..." using amnezia with junk packets enabled. -nym-gateway-probe -g "qj3GgGYgGZZ3HkFrtD1GU9UJ5oNXME9eD2xtmPLqYYw" -a "jc=4\njmin=40\njmax=70\n" +# Test with amnezia WireGuard +nym-gateway-probe -g "qj3GgGYg..." -a "jc=4\njmin=40\njmax=70\n" + +# WireGuard only (skip entry/exit ping tests) +nym-gateway-probe -g "qj3GgGYg..." --only-wireguard +``` + +### Localnet Mode (run-local) + +Test gateways directly by IP/identity without nym-api: + +```sh +# Single-hop: LP registration + WireGuard on one gateway +nym-gateway-probe run-local \ + --entry-gateway-identity "8yGm5h2KgNwrPgRRxjT2DhXQFCnADkHVyE5FYS4LHWLC" \ + --entry-lp-address "192.168.66.6:41264" \ + --mode single-hop \ + --use-mock-ecash + +# Two-hop: Entry + Exit LP forwarding + WireGuard +nym-gateway-probe run-local \ + --entry-gateway-identity "$ENTRY_ID" \ + --entry-lp-address "192.168.66.6:41264" \ + --exit-gateway-identity "$EXIT_ID" \ + --exit-lp-address "192.168.66.7:41264" \ + --mode two-hop \ + --use-mock-ecash + +# LP-only: Test handshake and registration only +nym-gateway-probe run-local \ + --entry-gateway-identity "$GATEWAY_ID" \ + --entry-lp-address "localhost:41264" \ + --mode lp-only \ + --use-mock-ecash +``` + +**Note:** `--use-mock-ecash` requires gateways started with `--lp-use-mock-ecash`. + +### Split Network Configuration + +For docker/container setups where entry and exit are on different networks: + +```sh +# Entry reachable from host, exit only reachable from entry's internal network +nym-gateway-probe run-local \ + --entry-gateway-identity "$ENTRY_ID" \ + --entry-lp-address "192.168.66.6:41264" \ # Host → Entry + --exit-gateway-identity "$EXIT_ID" \ + --exit-lp-address "172.18.0.5:41264" \ # Entry → Exit (internal) + --mode two-hop \ + --use-mock-ecash +``` + +## CLI Reference + +``` +Usage: nym-gateway-probe [OPTIONS] [COMMAND] + +Commands: + run-local Run probe in localnet mode (direct IP, no nym-api) + +Options: + -c, --config-env-file Path to env file describing the network + -g, --entry-gateway Entry gateway identity (base58) + -n, --node Node to test (defaults to entry gateway) + --gateway-ip Query gateway directly by IP (skip nym-api) + --exit-gateway-ip Exit gateway IP for two-hop testing + --mode Test mode: mixnet, single-hop, two-hop, lp-only + --only-wireguard Skip ping tests, only test WireGuard + --only-lp-registration Test LP registration only (legacy flag) + --test-lp-wg Test LP + WireGuard (legacy flag) + -a, --amnezia-args Amnezia WireGuard config arguments + --no-log Disable logging + -h, --help Print help + -V, --version Print version + +Localnet Options (run-local): + --entry-gateway-identity Entry gateway Ed25519 identity + --entry-lp-address Entry gateway LP listener address + --exit-gateway-identity Exit gateway Ed25519 identity + --exit-lp-address Exit gateway LP listener address + --use-mock-ecash Use mock credentials (dev only) +``` + +## Output + +The probe outputs JSON with test results: + +```json +{ + "node": "gateway-identity", + "used_entry": "entry-gateway-identity", + "outcome": { + "as_entry": { "can_connect": true, "can_route": true }, + "as_exit": { "can_connect": true, "can_route_ip_v4": true, "can_route_ip_v6": true }, + "wg": { "can_register": true, "can_handshake_v4": true, "can_handshake_v6": true }, + "lp": { "can_connect": true, "can_handshake": true, "can_register": true } + } +} ```