Skip to main content

TunnelScope blue compass and vortex logo

TunnelScope

Find out which packet sizes get through a tunnel, in which direction, and what both ends actually saw.

PyPI version Python versions Tests MIT license

Quick start · Return direction · Reading the results · Tested on · Releases


Ping works, SSH works, but a file copy over the VPN hangs. That pattern usually points at packet size: somewhere on the path, large packets are dropped or their error messages never come back. TunnelScope sends UDP probes of chosen sizes to a small receiver you run on the other end and writes down what happened to each one: acknowledged, rejected locally as too large, or timed out. You then join the sender's log with the receiver's log by probe ID, so you can tell "never arrived" apart from "arrived, but the answer got lost".

With --sized-reply, the receiver answers with a packet as big as the probe, so one run checks both directions. That catches paths where large packets go out fine and can't come back.

Status: alpha (v0.9.6), Python 3.10+, MIT. Reports are plain JSON plus an offline HTML view; nothing is uploaded anywhere.

tunnelscope show output: 64- and 1200-byte probes return same-sized replies; 1400-byte probes reach the receiver but their replies are lost or rejected

HTML view of the same run after joining the receiver log: each probe arrived; the 1400-byte replies were lost or rejected

Both images come from a real run of the asymmetric return-path lab (Ubuntu under WSL2, 2026-11-05). The return link is 1280 bytes. Every 1400-byte probe reached the receiver; the same-sized replies did not make it back, while a normal 24-byte ACK at 1400 bytes did. The lab gives the same result over IPv6. The images are rebuilt from the checked-in report by scripts/build_v07_images.py. There is also a 30-second replay of an OpenVPN return-path run and the report-sharing steps.

Quick start

This runs on one machine over loopback, with no root access and no network changes. On native Windows PowerShell, follow the Windows loopback guide instead. On Linux or WSL2, in an empty directory:

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

Terminal 1, start the receiver:

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

Terminal 2 (same environment), once the receiver prints Listening on 127.0.0.1:9471:

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

The receiver stops after two probes. Join the two logs and open the result:

tunnelscope correlate probe.json receiver.json --output correlation.json --html correlation.html
tunnelscope show correlation.json

correlation.html opens in any browser. A receiver entry for a probe means it arrived, even if the sender never got an ACK. A timeout on its own does not mean there is an MTU problem. For two machines, see the two-endpoint guide.

One command on a Linux sender

With a receiver already running on the other end of a path you control:

tunnelscope diagnose PEER_IP --min 1200 --max 1400 --count 2 --output diagnosis.json

diagnose runs three bounded passes in one sender direction: probes with the don't-fragment bit set, the same sizes with fragmentation allowed, and a size search between --min and --max. It writes JSON and HTML. Once the receiver has saved its log, correlate joins all three passes into one report. The diagnose guide covers setup and how to read it.

Test the return direction

The normal ACK is 24 bytes. It proves the probe arrived, not that a packet of the same size can travel back. With --sized-reply on both ends, the receiver replies with a packet as large as the probe, never larger:

tunnelscope receive --bind B_IP --sized-reply --output receiver.json
tunnelscope probe B_IP --sizes 64,1200,1400 --count 2 --dont-fragment --sized-reply --output probe.json
tunnelscope correlate probe.json receiver.json --html correlation.html

The receiver can be Linux (WSL2 included) or Windows. search, compare-fragmentation and diagnose take the same flag. The sized-reply guide lists every field. Run tunnelscope sanitize before you post a report anywhere, and tunnelscope show REPORT --format markdown gives a summary you can paste into an issue.

Reading the results

Result What it means
acknowledged The payload arrived and the small ACK came back.
packet_too_large Linux refused to send it because it was too big. ICMP data, when present, shows whether the limit was local or reported by a router.
timeout No matching ACK arrived. The cause is unknown.
sized_reply_received With --sized-reply: the payload arrived and a reply of the same size came back.
receiver_observed_sized_reply_missing After correlate: the receiver got the probe and its socket accepted a same-sized reply, but the sender saw nothing before its deadline. Where it was lost is unknown.
receiver_reply_send_unverified The receiver logged the probe, but its log has no outcome for the reply. TunnelScope does not guess whether a reply was sent.

Payload sizes include the 24-byte TunnelScope header.

A few things the tool cannot tell you. An observed size interval is what got through during the run, not a measured end-to-end path MTU. ICMP messages and receiver logs are not authenticated. Clocks on different machines are never compared. ping, tracepath, route tables and packet captures are still worth having next to these reports.

Where it has been tested

Setup What was checked Scope
Ubuntu ↔ Debian VMs over WireGuard Both directions, receiver pairing, a 1252/1253-byte boundary Local tunnel MTU, host-only link
Routed WireGuard Matched ICMP when visible, inconclusive timeouts when blocked 4 namespaces, one kernel
Routed OpenVPN and its return path Matched ICMP, blocked search, missing sized replies joined with the receiver log 3 namespaces, one kernel, IPv4
Routed IPv6 feedback Packet Too Big matched vs. blocked, receiver pairing 3 namespaces, one kernel, in CI
Asymmetric return path 1400-byte probes arrive, replies lost or rejected, small ACK returns 3 namespaces, IPv4 and IPv6, in CI
Windows receiver from WSL2 (IPv6) 3/3 small ACKs, 6/6 sized replies, 8/8 diagnosis replies per family Two kernels, one physical host
Windows oversized replies 1600-byte probes arrive; Windows refuses the same-sized reply (WSAEMSGSIZE) Same host and guest, MTU 1500
Kubernetes with Calico 6/6 baseline deliveries each way, policy block and recovery Two Minikube nodes, IP-in-IP

All of these are controlled setups. Nobody has sent in a report from a real production VPN or a multi-hop physical path yet. If you can test one you are allowed to, the field report guide walks through collecting and sanitizing it, and issue #2 is where it would help most.

Docs

Contributing

Starter tasks are tagged good first issue, and a field report counts as a contribution too. Read CONTRIBUTING.md first and only share synthetic or sanitized reports. CI runs on Linux and Windows with Python 3.10, 3.12 and 3.13. The unprivileged checks run with:

python -m unittest discover -s tests -v

The Linux network labs need root and an explicit opt-in, described in the usage reference.

Metadata

Release files for tunnelscope 0.9.6

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.9.6
File Size Uploaded Provenance Actions
tunnelscope-0.9.6.tar.gz 1.8 MB With provenance Details for tunnelscope-0.9.6.tar.gz

Built distribution (wheel)

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

Total release size: 2.0 MB

Release files / tunnelscope-0.9.6.tar.gz

Download URL tunnelscope-0.9.6.tar.gz
Size 1.8 MB
Tags Source
SHA-256 checksum
How to use checksums
9003965cf6aedce354adb9862758d6f13c3de08a1c8ddd4c35e64e9d9df36417
BLAKE2b-256 checksum
How to use checksums
5d753f908188e5c3818397ede37aa6d69016aa7139c0ca5f8254bb5eb01be85c
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 9, 2026.

Transparency log

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

Download URL tunnelscope-0.9.6-py3-none-any.whl
Size 222.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
28a24be0a441eb549622d01203298d41b0fa45370171b2d4d68ac0e93d3a9a5f
BLAKE2b-256 checksum
How to use checksums
04d43051cbe77905b1a53302545f78fecefc3486869617614c9d0179022ce115
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 9, 2026.

Transparency log

Security for tunnelscope 0.9.6

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.9.6.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 9, 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