Skip to main content

TunnelScope blue compass and vortex logo

TunnelScope

Evidence-based MTU and packet-size diagnostics for Linux networks.

v0.6.0 alpha: IPv4/IPv6 UDP probes, repeated measurement summaries, bounded payload-size search, Linux ICMP feedback observations and a single-sender diagnose workflow. Join sender and receiver evidence in JSON and offline HTML reports. Automatic path-MTU discovery and root-cause diagnosis are not implemented.

GitHub Release · PyPI

For the Linux DF/fragmentation-permitted comparison and optional ICMP feedback, see the comparison guide and ICMP guide. The diagnose guide shows the combined workflow and how to join its receiver observations.

Terminal demo of TunnelScope showing a controlled blocked-feedback lab report

The animation runs tunnelscope show on a checked-in controlled lab report. It is not a live network capture. A timeout on an unknown path remains inconclusive.

Why use TunnelScope?

Small pings can work while larger traffic fails. ping checks selected ICMP sizes, tracepath depends on path feedback, and ip route get reports the kernel's route and available MTU information; none alone confirms that a chosen UDP payload reached the other endpoint. TunnelScope sends bounded payloads to a cooperating receiver and saves both endpoints' observations for comparison. Packet captures and these existing tools remain useful for root-cause work.

Quick start

Requires Python 3.10 or newer. In an empty working directory on Linux (or WSL2), install the published package in a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install tunnelscope
tunnelscope --help

Open a second terminal and activate the same environment there with source .venv/bin/activate. Run these commands in order on one machine; no root access or network setup is needed for this loopback example.

Terminal 1 (receiver):

tunnelscope receive --max-packets 2 --output receiver.json

Wait for Listening on 127.0.0.1:9471, then run Terminal 2 (sender):

tunnelscope probe 127.0.0.1 --sizes 64,1200 --count 1 --output probe.json

The receiver exits after the two probes and saves receiver.json. Back in either terminal, inspect the sender report and create a local HTML view:

tunnelscope show probe.json
tunnelscope html probe.json --output probe.html

Open probe.html in a browser. The receiver sends small acknowledgements, so this example checks delivery in one direction only. A timeout is inconclusive; it does not prove an MTU problem. For two machines, see the two-endpoint workflow.

On a controlled Linux path, search tests the endpoints and then narrows an observed interval using repeated no-fragment probes:

tunnelscope search 192.0.2.2 --min 1200 --max 1400 --count 2 --output search.json
tunnelscope show search.json

Start a receiver at that lab address first. A timeout stops the search as inconclusive; even adjacent successful and explicit-error sizes are not an independently measured path MTU. See the size-search guide.

On Linux, v0.6 can also repeat the same sizes with DF enabled and source fragmentation permitted. Use a controlled receiver and read the comparison guide before interpreting differences.

What the results mean

  • acknowledged: the receiver got the UDP payload and a small reply returned.
  • packet_too_large: Linux reported EMSGSIZE in no-fragment mode; optional ICMP evidence can distinguish a local error from received path feedback.
  • timeout: no matching reply arrived; the cause is unknown without more evidence.

Probe sizes are UDP payload bytes, including the 24-byte TunnelScope header. Success does not prove same-sized reverse delivery. The tool reports observed sizes, not an exact end-to-end path MTU.

Documentation

Contributing

Good first issues: Python 3.10 CI, receiver correlation quick start, and Windows PowerShell loopback guide. The roadmap connects all six open issues to the next release and field validation. Read CONTRIBUTING.md before opening a PR; share only synthetic or sanitized reports.

Run the unprivileged checks with python -m unittest discover -s tests -v. Linux network-namespace checks require root and explicit opt-in; see the usage reference.

Metadata

Release files for tunnelscope 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tunnelscope 0.6.0
File Size Uploaded Provenance Actions
tunnelscope-0.6.0.tar.gz 644.4 kB With provenance Details for tunnelscope-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tunnelscope 0.6.0
File Interpreter ABI Platform Actions
tunnelscope-0.6.0-py3-none-any.whl Python 3 none any Details for tunnelscope-0.6.0-py3-none-any.whl

Total release size: 848.4 kB

Release files / tunnelscope-0.6.0.tar.gz

Download URL tunnelscope-0.6.0.tar.gz
Size 644.4 kB
Tags Source
SHA-256 checksum
How to use checksums
07585dc6c95861e0936e4d1fc441bde9839069843d0a8b80e69430fa322c2f36
BLAKE2b-256 checksum
How to use checksums
bd9d1c58e9898d133913060f90651c5ade0818a6648ae25bfc6bc4c82f4b33fe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / tunnelscope-0.6.0-py3-none-any.whl

Download URL tunnelscope-0.6.0-py3-none-any.whl
Size 204.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
88c961d4dd0c56bc988d293d67ff91d0ee0c13f1880ba7e00bcf5a33245a90b8
BLAKE2b-256 checksum
How to use checksums
c1218fd4150d2ee2129dc2861a9d6765a2872a55443ed3fdccb0ef56d56c6bf4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Security for tunnelscope 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tunnelscope-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page