tunnelscope 0.2.2__tar.gz → 0.3.0__tar.gz

{tunnelscope-0.2.2/tunnelscope.egg-info → tunnelscope-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tunnelscope
-Version: 0.2.2
+Version: 0.3.0
 Summary: Evidence-based MTU and packet-size diagnostics for Linux networks
 License-Expression: MIT
 Project-URL: Repository, https://github.com/lazypanic999/tunnelscope
@@ -22,7 +22,7 @@ Dynamic: license-file
 
 Evidence-based MTU and packet-size diagnostics for Linux networks.
 
-**Status: v0.2.2 alpha prototype. UDP delivery probes, Linux IPv4 Don't Fragment mode, per-direction report combination, optional receiver observations and controlled MTU labs are available. Automatic path-MTU discovery and root-cause diagnosis are not implemented.**
+**Status: v0.3.0 alpha. IPv4/IPv6 UDP delivery probes, Linux no-fragment mode, per-direction report combination, optional receiver observations and controlled MTU labs are available. Automatic path-MTU discovery and root-cause diagnosis are not implemented.**
 
 ## The problem
 
@@ -49,7 +49,7 @@ A failed probe alone will not be labeled as proof of an MTU problem. Reports sep
 - [x] **M4 - Observe at the receiver:** record which identified probes reached the cooperating receiver and correlate them with sender outcomes.
 - [x] **M5 - Make evidence usable:** validate receiver-observed timeouts in a controlled lab and provide a concise terminal view of reports.
 
-Kubernetes, VPN-specific workflows, IPv6 and 5G user-plane tunnels are possible later directions. They are not currently supported features.
+The [tunnel and pod workflows](https://github.com/lazypanic999/tunnelscope/blob/main/docs/environments.md) include a validated local VXLAN overlay and guidance for existing VPNs and Kubernetes pods. The VPN and pod workflows have not yet been validated on a real deployment. 5G user-plane tunnels remain outside the current scope.
 
 For a quick walkthrough of both controlled failure modes, see the [two-minute Linux demo](https://github.com/lazypanic999/tunnelscope/blob/main/docs/demo.md).
 The [two-VM validation record](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/two-vm-field-test.md) documents a successful bidirectional DF run between Ubuntu and Debian guests.
@@ -62,6 +62,14 @@ Use `tunnelscope show report.json` for a short terminal table of a probe,
 receiver observation, bidirectional comparison, correlation, or lab report.
 JSON remains the machine-readable source of evidence.
 
+The CLI can also create a [local HTML report view](https://github.com/lazypanic999/tunnelscope/blob/main/docs/report-ui.md):
+
+```sh
+tunnelscope html report.json --output report.html
+```
+
+![TunnelScope HTML report view](https://raw.githubusercontent.com/lazypanic999/tunnelscope/main/docs/images/report-ui.png)
+
 ## Install locally
 
 From the repository root, in a Python 3.10+ virtual environment:
@@ -73,6 +81,17 @@ tunnelscope --help
 
 The package installs the `tunnelscope` command. It has no third-party runtime dependencies. Published releases can be installed with `python3 -m pip install tunnelscope`. The laboratory scripts still run from a source checkout.
 
+The CLI also supports `--sweep START:STOP:STEP` for a bounded
+grid of UDP payload sizes. It includes the stop size even when the step does
+not land on it. For example:
+
+```sh
+tunnelscope probe 192.0.2.2 --sweep 64:1400:100 --count 2 --dont-fragment --output sweep.json
+```
+
+The grid tests at most 16 sizes. The result records observations at those
+sizes; it is not an exact path-MTU measurement. See the [size sweep guide](https://github.com/lazypanic999/tunnelscope/blob/main/docs/size-sweep.md).
+
 ## Getting started
 
 Requires Python 3.10 or newer. No third-party runtime packages are needed. Start with a local experiment in two terminals, from the repository directory. Use `tunnelscope` in place of `python tunnelscope.py` after installing the package.
@@ -93,7 +112,7 @@ The receiver exits after 100 datagrams or 30 seconds without a datagram. Restart
 
 Probe sizes are **UDP payload bytes**, including TunnelScope's 24-byte header. They exclude IP and UDP headers. The receiver sends only a small acknowledgement, so this is not a same-sized round-trip test. Reverse endpoint roles to investigate delivery in the other direction.
 
-Each probe report includes a `source` snapshot taken from the first connected sender socket. It records the local IPv4 address. On Linux, it also records the selected interface and its link MTU when discoverable, plus `kernel_route_mtu_bytes` when the kernel supplies it. The link MTU and kernel route MTU are different facts; neither is an independently measured end-to-end path MTU. A failed connection may leave `source` as `null`, and optional fields may be absent.
+Each probe report includes a `source` snapshot taken from the first connected sender socket. It records the local IPv4 or IPv6 address. On Linux, it also records the selected interface and its link MTU when discoverable, plus `kernel_route_mtu_bytes` when the kernel supplies it. The link MTU and kernel route MTU are different facts; neither is an independently measured end-to-end path MTU. A failed connection may leave `source` as `null`, and optional fields may be absent.
 
 `acknowledged` means that the receiver got that payload and its acknowledgement returned. `timeout` means no matching acknowledgement arrived before the deadline; it does not prove an MTU issue. `socket_error` records a socket error. Without `--dont-fragment`, fragmentation follows OS defaults; the tool does not force it on or off. The CLI exits successfully when it produces a report; inspect per-probe statuses for delivery outcomes.
 
@@ -109,13 +128,13 @@ python tunnelscope.py combine a-to-b.json b-to-a.json --output bidirectional.jso
 
 The command preserves the two reports and aligns per-size assessments; it does not initiate a remote measurement. See the [two-endpoint workflow](https://github.com/lazypanic999/tunnelscope/blob/main/docs/bidirectional.md) for the receiver and sender steps. `endpoint_check` compares the recorded IPv4 addresses but cannot authenticate endpoints or account for address translation.
 
-### Linux IPv4 Don't Fragment mode
+### Linux no-fragment mode
 
 ```sh
 python tunnelscope.py probe 192.0.2.2 --sizes 64,1252,1253,1400 --count 1 --dont-fragment --output report.json
 ```
 
-Use the address of your lab receiver; `192.0.2.2` is an example. This mode sets `IP_MTU_DISCOVER=IP_PMTUDISC_DO` on each sender socket. The kernel sets DF and rejects datagrams above its currently known path MTU. It does not bypass cached PMTU information or search automatically for a boundary. The flag requires Linux, including WSL2. Other platforms reject it; socket-option errors stop the experiment rather than silently reverting to defaults.
+Use the address of your lab receiver; `192.0.2.2` is an example. For IPv4, this mode sets `IP_MTU_DISCOVER=IP_PMTUDISC_DO` on each sender socket. The kernel sets DF and rejects datagrams above its currently known path MTU. For IPv6, it sets Linux `IPV6_DONTFRAG` to prevent source fragmentation. It does not bypass cached PMTU information or search automatically for a boundary. The flag requires Linux, including WSL2. Other platforms reject it; socket-option errors stop the experiment rather than silently reverting to defaults. See the [IPv6 workflow](https://github.com/lazypanic999/tunnelscope/blob/main/docs/ipv6.md).
 
 In DF mode, `EMSGSIZE` is reported as `packet_too_large`, with its numeric `errno`. When available, `kernel_reported_mtu_bytes` contains the connected socket's `IP_MTU` value. That value is kernel knowledge, not an independently measured end-to-end MTU. Timeouts remain inconclusive. The JSON schema version remains 1 with additive fields and the new `packet_too_large` status; consumers must handle it explicitly.
 
@@ -143,7 +162,7 @@ This lab creates a sender, router and receiver in temporary network namespaces.
 
 The known lab topology explains these timeouts; a timeout on an unknown network remains inconclusive. See the [validation record](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/pmtu-blackhole.md) and [captured report](https://github.com/lazypanic999/tunnelscope/blob/main/examples/pmtu-blackhole.json). This lab demonstrates one controlled failure mode; it does not establish automatic black-hole detection.
 
-The receiver binds to loopback by default. For your own two-host lab, use `--bind <receiver-lab-IPv4>` and probe that address. The experimental protocol is unencrypted and unauthenticated; use a controlled lab, not a public service.
+The receiver binds to IPv4 loopback by default. For your own two-host lab, use `--bind <receiver-lab-address>` and probe that address. An IPv6 literal such as `::1` selects IPv6; `--family ipv6` selects an AAAA record for a hostname. The experimental protocol is unencrypted and unauthenticated; use a controlled lab, not a public service.
 
 Run checks:
 

{tunnelscope-0.2.2 → tunnelscope-0.3.0}/README.md

@@ -6,7 +6,7 @@
 
 Evidence-based MTU and packet-size diagnostics for Linux networks.
 
-**Status: v0.2.2 alpha prototype. UDP delivery probes, Linux IPv4 Don't Fragment mode, per-direction report combination, optional receiver observations and controlled MTU labs are available. Automatic path-MTU discovery and root-cause diagnosis are not implemented.**
+**Status: v0.3.0 alpha. IPv4/IPv6 UDP delivery probes, Linux no-fragment mode, per-direction report combination, optional receiver observations and controlled MTU labs are available. Automatic path-MTU discovery and root-cause diagnosis are not implemented.**
 
 ## The problem
 
@@ -33,7 +33,7 @@ A failed probe alone will not be labeled as proof of an MTU problem. Reports sep
 - [x] **M4 - Observe at the receiver:** record which identified probes reached the cooperating receiver and correlate them with sender outcomes.
 - [x] **M5 - Make evidence usable:** validate receiver-observed timeouts in a controlled lab and provide a concise terminal view of reports.
 
-Kubernetes, VPN-specific workflows, IPv6 and 5G user-plane tunnels are possible later directions. They are not currently supported features.
+The [tunnel and pod workflows](https://github.com/lazypanic999/tunnelscope/blob/main/docs/environments.md) include a validated local VXLAN overlay and guidance for existing VPNs and Kubernetes pods. The VPN and pod workflows have not yet been validated on a real deployment. 5G user-plane tunnels remain outside the current scope.
 
 For a quick walkthrough of both controlled failure modes, see the [two-minute Linux demo](https://github.com/lazypanic999/tunnelscope/blob/main/docs/demo.md).
 The [two-VM validation record](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/two-vm-field-test.md) documents a successful bidirectional DF run between Ubuntu and Debian guests.
@@ -46,6 +46,14 @@ Use `tunnelscope show report.json` for a short terminal table of a probe,
 receiver observation, bidirectional comparison, correlation, or lab report.
 JSON remains the machine-readable source of evidence.
 
+The CLI can also create a [local HTML report view](https://github.com/lazypanic999/tunnelscope/blob/main/docs/report-ui.md):
+
+```sh
+tunnelscope html report.json --output report.html
+```
+
+![TunnelScope HTML report view](https://raw.githubusercontent.com/lazypanic999/tunnelscope/main/docs/images/report-ui.png)
+
 ## Install locally
 
 From the repository root, in a Python 3.10+ virtual environment:
@@ -57,6 +65,17 @@ tunnelscope --help
 
 The package installs the `tunnelscope` command. It has no third-party runtime dependencies. Published releases can be installed with `python3 -m pip install tunnelscope`. The laboratory scripts still run from a source checkout.
 
+The CLI also supports `--sweep START:STOP:STEP` for a bounded
+grid of UDP payload sizes. It includes the stop size even when the step does
+not land on it. For example:
+
+```sh
+tunnelscope probe 192.0.2.2 --sweep 64:1400:100 --count 2 --dont-fragment --output sweep.json
+```
+
+The grid tests at most 16 sizes. The result records observations at those
+sizes; it is not an exact path-MTU measurement. See the [size sweep guide](https://github.com/lazypanic999/tunnelscope/blob/main/docs/size-sweep.md).
+
 ## Getting started
 
 Requires Python 3.10 or newer. No third-party runtime packages are needed. Start with a local experiment in two terminals, from the repository directory. Use `tunnelscope` in place of `python tunnelscope.py` after installing the package.
@@ -77,7 +96,7 @@ The receiver exits after 100 datagrams or 30 seconds without a datagram. Restart
 
 Probe sizes are **UDP payload bytes**, including TunnelScope's 24-byte header. They exclude IP and UDP headers. The receiver sends only a small acknowledgement, so this is not a same-sized round-trip test. Reverse endpoint roles to investigate delivery in the other direction.
 
-Each probe report includes a `source` snapshot taken from the first connected sender socket. It records the local IPv4 address. On Linux, it also records the selected interface and its link MTU when discoverable, plus `kernel_route_mtu_bytes` when the kernel supplies it. The link MTU and kernel route MTU are different facts; neither is an independently measured end-to-end path MTU. A failed connection may leave `source` as `null`, and optional fields may be absent.
+Each probe report includes a `source` snapshot taken from the first connected sender socket. It records the local IPv4 or IPv6 address. On Linux, it also records the selected interface and its link MTU when discoverable, plus `kernel_route_mtu_bytes` when the kernel supplies it. The link MTU and kernel route MTU are different facts; neither is an independently measured end-to-end path MTU. A failed connection may leave `source` as `null`, and optional fields may be absent.
 
 `acknowledged` means that the receiver got that payload and its acknowledgement returned. `timeout` means no matching acknowledgement arrived before the deadline; it does not prove an MTU issue. `socket_error` records a socket error. Without `--dont-fragment`, fragmentation follows OS defaults; the tool does not force it on or off. The CLI exits successfully when it produces a report; inspect per-probe statuses for delivery outcomes.
 
@@ -93,13 +112,13 @@ python tunnelscope.py combine a-to-b.json b-to-a.json --output bidirectional.jso
 
 The command preserves the two reports and aligns per-size assessments; it does not initiate a remote measurement. See the [two-endpoint workflow](https://github.com/lazypanic999/tunnelscope/blob/main/docs/bidirectional.md) for the receiver and sender steps. `endpoint_check` compares the recorded IPv4 addresses but cannot authenticate endpoints or account for address translation.
 
-### Linux IPv4 Don't Fragment mode
+### Linux no-fragment mode
 
 ```sh
 python tunnelscope.py probe 192.0.2.2 --sizes 64,1252,1253,1400 --count 1 --dont-fragment --output report.json
 ```
 
-Use the address of your lab receiver; `192.0.2.2` is an example. This mode sets `IP_MTU_DISCOVER=IP_PMTUDISC_DO` on each sender socket. The kernel sets DF and rejects datagrams above its currently known path MTU. It does not bypass cached PMTU information or search automatically for a boundary. The flag requires Linux, including WSL2. Other platforms reject it; socket-option errors stop the experiment rather than silently reverting to defaults.
+Use the address of your lab receiver; `192.0.2.2` is an example. For IPv4, this mode sets `IP_MTU_DISCOVER=IP_PMTUDISC_DO` on each sender socket. The kernel sets DF and rejects datagrams above its currently known path MTU. For IPv6, it sets Linux `IPV6_DONTFRAG` to prevent source fragmentation. It does not bypass cached PMTU information or search automatically for a boundary. The flag requires Linux, including WSL2. Other platforms reject it; socket-option errors stop the experiment rather than silently reverting to defaults. See the [IPv6 workflow](https://github.com/lazypanic999/tunnelscope/blob/main/docs/ipv6.md).
 
 In DF mode, `EMSGSIZE` is reported as `packet_too_large`, with its numeric `errno`. When available, `kernel_reported_mtu_bytes` contains the connected socket's `IP_MTU` value. That value is kernel knowledge, not an independently measured end-to-end MTU. Timeouts remain inconclusive. The JSON schema version remains 1 with additive fields and the new `packet_too_large` status; consumers must handle it explicitly.
 
@@ -127,7 +146,7 @@ This lab creates a sender, router and receiver in temporary network namespaces.
 
 The known lab topology explains these timeouts; a timeout on an unknown network remains inconclusive. See the [validation record](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/pmtu-blackhole.md) and [captured report](https://github.com/lazypanic999/tunnelscope/blob/main/examples/pmtu-blackhole.json). This lab demonstrates one controlled failure mode; it does not establish automatic black-hole detection.
 
-The receiver binds to loopback by default. For your own two-host lab, use `--bind <receiver-lab-IPv4>` and probe that address. The experimental protocol is unencrypted and unauthenticated; use a controlled lab, not a public service.
+The receiver binds to IPv4 loopback by default. For your own two-host lab, use `--bind <receiver-lab-address>` and probe that address. An IPv6 literal such as `::1` selects IPv6; `--family ipv6` selects an AAAA record for a hostname. The experimental protocol is unencrypted and unauthenticated; use a controlled lab, not a public service.
 
 Run checks:
 

tunnelscope-0.3.0/docs/environments.md

@@ -0,0 +1,67 @@
+# Controlled tunnel and pod workflows
+
+TunnelScope sends ordinary UDP payloads between a cooperating sender and
+receiver. The tool does not configure a VPN, container network, Kubernetes
+cluster or network policy. Run it only where both endpoints and the UDP path
+are under your control. Use the tunnel or pod address as the destination, and
+measure each direction separately.
+
+## VXLAN overlay lab
+
+On Linux with root and `iproute2`:
+
+```sh
+sudo python3 labs/vxlan_boundary.py > vxlan-boundary.json
+```
+
+The lab creates two temporary network namespaces. Their 1500-byte underlay
+carries a VXLAN overlay with a 1450-byte interface MTU. In IPv4 DF mode, the
+known maximum UDP payload on that overlay is 1422 bytes (1450 minus 20-byte
+IPv4 and 8-byte UDP headers). The lab checks 1418–1426 bytes in both
+directions, correlates receiver observations and removes its namespaces on
+ordinary completion. It changes no host interface or route.
+
+This validates an encapsulated virtual path, not a real VPN or a Kubernetes
+cluster. A measured local tunnel-interface MTU and a kernel route MTU remain
+different from independent proof of an unknown end-to-end path MTU.
+
+## Existing VPN or tunnel
+
+Use the addresses assigned inside the tunnel. Start the receiver on endpoint
+B, then probe from endpoint A:
+
+```sh
+tunnelscope receive --bind B_TUNNEL_IP --output b-receiver.json
+tunnelscope probe B_TUNNEL_IP --sweep 1200:1400:25 --count 2 --dont-fragment --output a-to-b.json
+```
+
+Run the commands in separate terminals. Repeat with A and B swapped, then use
+`combine` for direction comparison and `correlate` with each receiver report.
+Check the selected `source.interface` and its MTU in the probe report. If the
+route unexpectedly uses a non-tunnel interface, the experiment did not measure
+the intended VPN path. Use `--family ipv6` for an IPv6 hostname or an IPv6
+literal address. Timeouts remain inconclusive without receiver or path
+evidence.
+
+## Existing Kubernetes pods
+
+If two controlled pods already contain TunnelScope v0.3.0 and Python 3.10+,
+use their pod addresses directly. In separate local terminals, for example:
+
+```sh
+kubectl exec -n NAMESPACE POD_B -- tunnelscope receive --bind POD_B_IP --output /tmp/receiver.json
+kubectl exec -n NAMESPACE POD_A -- tunnelscope probe POD_B_IP --sizes 64,1200,1400 --count 2 --dont-fragment --output /tmp/probe.json
+```
+
+Collect the JSON files from the pods and correlate them. Repeat with the roles
+reversed. A pod may have more than one container; add `-c CONTAINER` to
+`kubectl exec` when needed. Ensure that the intended UDP port (default 9471)
+and the small ACK return traffic are allowed by the cluster's network policy.
+Kubernetes [pod networking](https://kubernetes.io/docs/concepts/services-networking/)
+and [NetworkPolicy](https://kubernetes.io/docs/concepts/services-networking/network-policies/)
+are implemented by the cluster's network plugin; behavior can differ between
+clusters. See the official [`kubectl exec` reference](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_exec/).
+
+This pod recipe is untested here because no Kubernetes cluster was available.
+It does not claim cluster-wide MTU discovery, support for every CNI, or the
+ability to distinguish overlay loss from filtering on its own.

tunnelscope-0.3.0/docs/ipv6.md

@@ -0,0 +1,37 @@
+# IPv6 delivery experiments
+
+From v0.3.0, the CLI supports IPv6 UDP payload probes and receiver observations.
+Use an IPv6 literal for `probe` or `receive --bind`; the default receiver still
+binds to IPv4 loopback. For a hostname, `--family ipv6` selects an AAAA record.
+The default hostname behavior continues to prefer IPv4 for compatibility.
+
+On one machine, start the receiver in one terminal:
+
+```sh
+tunnelscope receive --bind ::1 --output receiver-v6.json
+```
+
+In another terminal:
+
+```sh
+tunnelscope probe ::1 --sizes 64,1200,1400 --count 2 --dont-fragment --output probe-v6.json
+```
+
+For a two-host test, use the receiver's reachable IPv6 address and repeat the
+procedure with endpoint roles reversed. Link-local addresses need a zone
+identifier such as `%eth0` on the sender. Reports use `source.ipv6`,
+`target.ipv6`, `receiver.bind_ipv6` and `source_ipv6` in receiver observations.
+The existing report schema version remains 1 with additive IPv6 fields.
+
+On Linux, `--dont-fragment` sets `IPV6_DONTFRAG` on the sender socket. An
+`EMSGSIZE` error is recorded as `packet_too_large`; a reported `IPV6_MTU`
+value is the kernel's current route knowledge, not a separately measured
+end-to-end path MTU. Without the flag, source fragmentation follows OS
+defaults. Timeouts remain inconclusive. The receiver's acknowledgement is
+small, so reverse roles to test the opposite direction with the same payload
+size.
+
+The [isolated IPv6 boundary lab](../labs/ipv6_boundary.py) verifies a
+1280-byte veth link: 1228–1232-byte UDP payloads arrive, while 1233–1236-byte
+payloads are rejected locally in no-fragment mode. It creates and removes
+temporary network namespaces and requires root and `iproute2`.

tunnelscope-0.3.0/docs/releases/v0.3.0.md

@@ -0,0 +1,25 @@
+# TunnelScope v0.3.0
+
+Alpha release of the Python CLI with more controlled network experiments and
+a local report view.
+
+## Highlights
+
+- IPv6 UDP probes, cooperating receiver reports, run correlation and
+  bidirectional comparisons. Linux `--dont-fragment` uses `IPV6_DONTFRAG` for
+  IPv6 and retains IPv4 DF behavior.
+- Bounded `--sweep START:STOP:STEP` payload-size grids (at most 16 sizes).
+- Reproducible network namespace labs for a known IPv6 link boundary and a
+  VXLAN overlay boundary, both checked in each direction.
+- `tunnelscope html report.json --output report.html` creates a searchable
+  local report view. The report content remains in the generated HTML.
+- VPN and Kubernetes pod workflow guidance. Those two deployment types are
+  documented but have not been validated on a real deployment.
+
+## Known limits
+
+The tool does not discover an exact end-to-end path MTU or prove a root cause
+on an unknown network. A timeout remains inconclusive without additional
+receiver or path evidence. The UDP protocol is unauthenticated and unencrypted;
+use it only in a controlled environment. The HTML view fetches the project
+logo from GitHub when online, but does not send the report to a service.

tunnelscope-0.3.0/docs/report-ui.md

@@ -0,0 +1,21 @@
+# Local HTML report view
+
+From v0.3.0, the CLI can turn an existing JSON report into a searchable HTML
+file. It does not start a server or send the report to a remote service.
+
+```sh
+tunnelscope html probe.json --output probe.html
+```
+
+Open `probe.html` in a browser. Search filters visible rows; the raw JSON is
+available in a collapsed section. The view supports probe, receiver,
+correlation, bidirectional comparison and lab reports. It presents evidence
+already in the JSON; it does not run a new measurement or infer a root cause.
+The logo is fetched from the project's GitHub image when online, while report
+content works without network access.
+
+![TunnelScope HTML report view](images/report-ui.png)
+
+The generated HTML contains the complete report, including addresses and any
+other fields in its JSON. Sanitize the JSON before sharing the HTML. Report
+values are HTML-escaped before rendering.

tunnelscope-0.3.0/docs/size-sweep.md

@@ -0,0 +1,29 @@
+# Bounded payload-size sweep
+
+From v0.3.0, `probe --sweep START:STOP:STEP` expands
+an ascending grid of UDP payload sizes, always including `STOP` even if `STEP`
+does not land exactly on it. The bounds are 32 to 8192 bytes and at most 16
+sizes. `--sweep` and `--sizes` cannot be used together. `--count` repeats each
+size; existing per-size status counts and individual results remain in JSON.
+
+On a controlled Linux IPv4 link, start the receiver first and run:
+
+```sh
+tunnelscope receive --bind RECEIVER_IP --output receiver.json
+tunnelscope probe RECEIVER_IP --sweep 1200:1400:25 --count 2 --dont-fragment --output sweep.json
+tunnelscope show sweep.json
+```
+
+Run the receiver and sender commands on separate terminals or hosts. The
+receiver's small acknowledgement does not test a same-sized return packet.
+Repeat with the endpoint roles reversed to test the other direction.
+
+A sweep samples only the listed sizes. A successful size is an observed working
+UDP payload size under these conditions, not the exact path MTU. A
+`packet_too_large` result reflects the sender kernel's DF rejection and
+current route knowledge. A timeout is inconclusive even if nearby smaller
+sizes succeeded. Compare receiver observations with `correlate` to learn
+whether a timed-out probe reached the cooperating receiver.
+
+The [direct-link MTU lab](../labs/mtu_boundary.py) checks this option against a
+known 1280-byte virtual link in both directions.

tunnelscope-0.3.0/docs/validation/two-vm-size-sweep.md

@@ -0,0 +1,44 @@
+# Two-VM payload-size sweep validation
+
+Recorded on 2026-10-28 using separate Ubuntu 24.04 and Debian 12 VirtualBox
+guests connected through a temporary 1500-byte host-only link. Ubuntu ran
+Python 3.12.3 and Debian ran Python 3.11.2. Both guests ran the same
+`tunnelscope.py` file (SHA-256
+`43b0cb76dfa6b58452b9ecc844a5db27c2d057cb7cad4c3735233f75d454a857`).
+The temporary host-only addresses and raw JSON reports are kept locally in
+ignored `output/field-test-2026-10-28/`; they are not committed.
+
+## Procedure
+
+The destination ran `receive --max-packets 5 --idle-timeout 20 --output receiver.json`.
+The source then ran the development CLI in Linux IPv4 DF mode:
+
+```sh
+python3 tunnelscope.py probe PEER_IP --sweep 1468:1476:1 --count 1 --timeout 2 --dont-fragment --output probe.json
+```
+
+The two files were correlated after each direction. The same procedure was
+repeated with guest roles reversed. The direct-link expected UDP payload
+boundary is 1472 bytes: 1500-byte link MTU minus 20-byte IPv4 and 8-byte UDP
+headers.
+
+## Results
+
+| Direction | 1468–1472 bytes | 1473–1476 bytes | Receiver observed | Run ID |
+| --- | --- | --- | ---: | --- |
+| Ubuntu to Debian | 5/5 acknowledged | 4/4 `packet_too_large` | 5/5 | matched |
+| Debian to Ubuntu | 5/5 acknowledged | 4/4 `packet_too_large` | 5/5 | matched |
+
+Each sender identified its host-only interface with MTU 1500. All eight
+oversized attempts reported kernel MTU 1500. Both receiver reports exited at
+`max_packets`; the correlations had zero unmatched observations and no
+receiver-observed timeouts. The source file was checked by SHA-256 on both
+guests before testing.
+
+## Limits
+
+This confirms the size grid and known boundary on one directly connected
+virtual link. It does not discover an unknown multi-hop path MTU. The
+`packet_too_large` statuses are local kernel rejections, and the successful
+ACKs only confirm forward payload delivery plus a small reply. The same
+experiment on an unknown path can produce timeouts for several reasons.

tunnelscope-0.3.0/labs/ipv6_boundary.py

@@ -0,0 +1,102 @@
+"""Validate an IPv6 no-fragment payload boundary on an isolated 1280-byte link."""
+
+import json
+import os
+from pathlib import Path
+import selectors
+import shutil
+import subprocess
+import sys
+import tempfile
+import uuid
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import tunnelscope
+
+
+def ip(*args):
+    return subprocess.run(["ip", *args], check=True, capture_output=True, text=True, timeout=10)
+
+
+def main():
+    if not sys.platform.startswith("linux") or os.geteuid() != 0 or not shutil.which("ip"):
+        raise RuntimeError("This lab requires root on Linux and the iproute2 'ip' command")
+    suffix = uuid.uuid4().hex[:10]
+    left, right = f"ts6-{suffix}-a", f"ts6-{suffix}-b"
+    created = []
+    script = str(Path(tunnelscope.__file__).resolve())
+    report = {"lab": "direct-veth-ipv6-no-fragment", "link_mtu_bytes": 1280,
+              "ipv6_header_bytes": 40, "udp_header_bytes": 8,
+              "expected_payload_boundary_bytes": 1232, "directions": []}
+    try:
+        for namespace in (left, right):
+            ip("netns", "add", namespace)
+            created.append(namespace)
+        ip("-n", left, "link", "add", "ts6-a", "type", "veth", "peer", "name", "ts6-b")
+        ip("-n", left, "link", "set", "ts6-b", "netns", right)
+        for namespace, interface, address in ((left, "ts6-a", "fd00:5453::1/64"),
+                                              (right, "ts6-b", "fd00:5453::2/64")):
+            ip("-n", namespace, "link", "set", "lo", "up")
+            ip("-n", namespace, "link", "set", interface, "mtu", "1280", "up")
+            ip("-n", namespace, "-6", "addr", "add", address, "dev", interface, "nodad")
+        with tempfile.TemporaryDirectory() as directory:
+            for label, source, target, target_ip in (
+                ("a-to-b", left, right, "fd00:5453::2"),
+                ("b-to-a", right, left, "fd00:5453::1"),
+            ):
+                receiver_path = Path(directory) / f"{label}-receiver.json"
+                receiver = subprocess.Popen(
+                    ["ip", "netns", "exec", target, sys.executable, "-u", script,
+                     "receive", "--bind", target_ip, "--max-packets", "5",
+                     "--idle-timeout", "10", "--output", str(receiver_path)],
+                    stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
+                )
+                try:
+                    with selectors.DefaultSelector() as ready:
+                        ready.register(receiver.stdout, selectors.EVENT_READ)
+                        if not ready.select(timeout=5):
+                            raise RuntimeError("IPv6 receiver startup timed out")
+                    if not receiver.stdout.readline().startswith("Listening on"):
+                        raise RuntimeError("IPv6 receiver did not start")
+                    sent = subprocess.run(
+                        ["ip", "netns", "exec", source, sys.executable, script,
+                         "probe", target_ip, "--sweep", "1228:1236:1",
+                         "--count", "1", "--timeout", "2", "--dont-fragment"],
+                        check=True, capture_output=True, text=True, timeout=25,
+                    )
+                    probe = json.loads(sent.stdout)
+                    if receiver.wait(timeout=12) != 0:
+                        raise RuntimeError("IPv6 receiver failed")
+                    observed = json.loads(receiver_path.read_text(encoding="utf-8"))
+                    correlation = tunnelscope.correlate_reports(probe, observed)
+                    expected = ["acknowledged"] * 5 + ["packet_too_large"] * 4
+                    if [row["status"] for row in probe["results"]] != expected:
+                        raise RuntimeError(f"Unexpected IPv6 boundary: {probe}")
+                    if probe["source"].get("interface_mtu_bytes") != 1280:
+                        raise RuntimeError(f"Unexpected IPv6 source interface: {probe['source']}")
+                    if correlation["summary"]["receiver_observed"] != 5:
+                        raise RuntimeError("Unexpected IPv6 receiver observation count")
+                    report["directions"].append({"direction": label, "probe": probe,
+                                                  "receiver": observed, "correlation": correlation})
+                finally:
+                    if receiver.poll() is None:
+                        receiver.terminate()
+                    try:
+                        receiver.wait(timeout=3)
+                    except subprocess.TimeoutExpired:
+                        receiver.kill()
+                        receiver.wait(timeout=3)
+                    receiver.stdout.close()
+                    receiver.stderr.close()
+    finally:
+        for namespace in reversed(created):
+            ip("netns", "delete", namespace)
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (RuntimeError, OSError, subprocess.SubprocessError) as error:
+        print(f"Lab failed: {error}", file=sys.stderr)
+        sys.exit(1)

{tunnelscope-0.2.2 → tunnelscope-0.3.0}/labs/mtu_boundary.py

@@ -55,6 +55,16 @@ def main():
                 for row in direction["results"][2:]:
                     if row.get("kernel_reported_mtu_bytes") != 1280:
                         raise RuntimeError(f"Expected kernel MTU 1280: {row}")
+                sweep_result = subprocess.run(
+                    ["ip", "netns", "exec", source, sys.executable, script, "probe", target_ip,
+                     "--sweep", "1200:1300:25", "--count", "1", "--dont-fragment"],
+                    check=True, capture_output=True, text=True, timeout=15,
+                )
+                sweep = json.loads(sweep_result.stdout)
+                expected_sweep = ["acknowledged"] * 3 + ["packet_too_large"] * 2
+                if [row["status"] for row in sweep["results"]] != expected_sweep:
+                    raise RuntimeError(f"Unexpected sweep result: {sweep}")
+                direction["sweep"] = sweep
                 report["directions"].append(direction)
             finally:
                 if receiver.poll() is None:

tunnelscope-0.3.0/labs/vxlan_boundary.py

@@ -0,0 +1,108 @@
+"""Validate an IPv4 UDP payload boundary across an isolated VXLAN overlay."""
+
+import json
+import os
+from pathlib import Path
+import selectors
+import shutil
+import subprocess
+import sys
+import tempfile
+import uuid
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import tunnelscope
+
+
+def ip(*args):
+    return subprocess.run(["ip", *args], check=True, capture_output=True, text=True, timeout=10)
+
+
+def main():
+    if not sys.platform.startswith("linux") or os.geteuid() != 0 or not shutil.which("ip"):
+        raise RuntimeError("This lab requires root on Linux and the iproute2 'ip' command")
+    suffix = uuid.uuid4().hex[:10]
+    left, right = f"ts-vx-{suffix}-a", f"ts-vx-{suffix}-b"
+    created = []
+    script = str(Path(tunnelscope.__file__).resolve())
+    report = {"lab": "vxlan-overlay-ipv4-df", "underlay_mtu_bytes": 1500,
+              "overlay_mtu_bytes": 1450, "expected_payload_boundary_bytes": 1422,
+              "directions": []}
+    try:
+        for namespace in (left, right):
+            ip("netns", "add", namespace)
+            created.append(namespace)
+        ip("-n", left, "link", "add", "ts-under-a", "type", "veth", "peer", "name", "ts-under-b")
+        ip("-n", left, "link", "set", "ts-under-b", "netns", right)
+        for namespace, underlay, local, remote, overlay in (
+            (left, "ts-under-a", "192.0.2.1", "192.0.2.2", "198.51.100.1"),
+            (right, "ts-under-b", "192.0.2.2", "192.0.2.1", "198.51.100.2"),
+        ):
+            ip("-n", namespace, "link", "set", "lo", "up")
+            ip("-n", namespace, "addr", "add", local + "/30", "dev", underlay)
+            ip("-n", namespace, "link", "set", underlay, "mtu", "1500", "up")
+            ip("-n", namespace, "link", "add", "ts-vx", "type", "vxlan", "id", "42",
+               "local", local, "remote", remote, "dev", underlay, "dstport", "4789", "nolearning")
+            ip("-n", namespace, "addr", "add", overlay + "/24", "dev", "ts-vx")
+            ip("-n", namespace, "link", "set", "ts-vx", "mtu", "1450", "up")
+        with tempfile.TemporaryDirectory() as directory:
+            for label, source, target, target_ip in (
+                ("a-to-b", left, right, "198.51.100.2"),
+                ("b-to-a", right, left, "198.51.100.1"),
+            ):
+                receiver_path = Path(directory) / f"{label}-receiver.json"
+                receiver = subprocess.Popen(
+                    ["ip", "netns", "exec", target, sys.executable, "-u", script,
+                     "receive", "--bind", target_ip, "--max-packets", "5",
+                     "--idle-timeout", "10", "--output", str(receiver_path)],
+                    stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
+                )
+                try:
+                    with selectors.DefaultSelector() as ready:
+                        ready.register(receiver.stdout, selectors.EVENT_READ)
+                        if not ready.select(timeout=5):
+                            raise RuntimeError("VXLAN receiver startup timed out")
+                    if not receiver.stdout.readline().startswith("Listening on"):
+                        raise RuntimeError("VXLAN receiver did not start")
+                    sent = subprocess.run(
+                        ["ip", "netns", "exec", source, sys.executable, script,
+                         "probe", target_ip, "--sweep", "1418:1426:1",
+                         "--count", "1", "--timeout", "2", "--dont-fragment"],
+                        check=True, capture_output=True, text=True, timeout=25,
+                    )
+                    probe = json.loads(sent.stdout)
+                    if receiver.wait(timeout=12) != 0:
+                        raise RuntimeError("VXLAN receiver failed")
+                    observed = json.loads(receiver_path.read_text(encoding="utf-8"))
+                    correlation = tunnelscope.correlate_reports(probe, observed)
+                    expected = ["acknowledged"] * 5 + ["packet_too_large"] * 4
+                    if [row["status"] for row in probe["results"]] != expected:
+                        raise RuntimeError(f"Unexpected VXLAN boundary: {probe}")
+                    if probe["source"].get("interface_mtu_bytes") != 1450:
+                        raise RuntimeError(f"Unexpected VXLAN source interface: {probe['source']}")
+                    if correlation["summary"]["receiver_observed"] != 5:
+                        raise RuntimeError("Unexpected VXLAN receiver observation count")
+                    report["directions"].append({"direction": label, "probe": probe,
+                                                  "receiver": observed, "correlation": correlation})
+                finally:
+                    if receiver.poll() is None:
+                        receiver.terminate()
+                    try:
+                        receiver.wait(timeout=3)
+                    except subprocess.TimeoutExpired:
+                        receiver.kill()
+                        receiver.wait(timeout=3)
+                    receiver.stdout.close()
+                    receiver.stderr.close()
+    finally:
+        for namespace in reversed(created):
+            ip("netns", "delete", namespace)
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (RuntimeError, OSError, subprocess.SubprocessError) as error:
+        print(f"Lab failed: {error}", file=sys.stderr)
+        sys.exit(1)