OnionMasq: Tor's Experimental Fix for VPN-Style Traffic Isolation

OnionMasq represents the Tor Project's attempt to solve a fundamental problem: making every packet from your application travel through Tor without exceptions. It's an experimental tunnel interface for Arti (Tor's new Rust implementation) that creates VPN-like behavior through kernel-level network isolation.

The technology works by creating a virtual network card that exists only inside a locked-down sandbox. Your application sees this fake network interface and uses it normally, but OnionMasq intercepts everything and routes it through Tor's encrypted circuits.

What Problem OnionMasq Solves

Traditional Tor routing tools rely on proxy interception. Torsocks, the 15-year veteran, uses LD_PRELOAD hacks to catch network function calls and redirect them through Tor's SOCKS proxy. This approach breaks in three ways:

Static binaries ignore library shims entirely.
If your application was compiled with networking code built-in rather than using system libraries, torsocks can't intercept anything.

Raw system calls bypass userspace tricks.
Applications can make direct kernel calls that skip library functions completely.

Misconfiguration creates instant leaks.
One wrong proxy setting and your traffic travels in the clear.

OnionMasq eliminates these failure modes by moving enforcement to the Linux kernel itself.

How the Kernel-Level Approach Works

Linux namespaces are isolation containers that limit what processes can see and access. Network namespaces, introduced around 2000, create separate network environments where processes can only use specific interfaces.

Oniux, the command-line tool that implements OnionMasq, follows this sequence:

Creates isolated environment.
Oniux spawns your application inside network, mount, PID, and user namespaces using the clone(2) system call. The application runs in a sealed container.

Removes access to real networks.
Inside the namespace, your application cannot see eth0, wlan0, or any physical network interfaces. The normal internet doesn't exist.

Installs virtual network card.
OnionMasq creates a TUN device called onion0 - a fake network interface that looks real to applications but is controlled by userspace software.

Routes everything through Tor.
The TUN device feeds all network packets to OnionMasq, which uses smoltcp (a Rust userspace network stack) to reassemble streams and hand them to Arti for Tor circuit routing.

TUN Devices Explained

A TUN device is a virtual network interface that creates a pipe between the kernel and userspace applications. When your application sends an IP packet to a TUN interface, the kernel delivers it to whatever program is managing that interface instead of putting it on the wire.

OnionMasq manages the onion0 TUN device. Every packet your application sends gets intercepted, processed through Tor's routing, and returned as if it came from a normal internet connection. The application never knows the difference.

This is fundamentally different from VPNs, which typically route traffic from your entire system. OnionMasq creates per-application isolation - each program gets its own sealed network environment.

Real-World Usage

Installing and using Oniux requires Rust and works only on Linux:

cargo install --git https://gitlab.torproject.org/tpo/core/oniux oniux@0.4.0

Basic usage wraps any command:

# Route a single command through Tor
oniux curl https://icanhazip.com

# Get your Tor exit IP
oniux curl https://ipinfo.io/ip

# Access onion services
oniux curl http://duckduckgogg42ts72.onion

# Isolate an entire shell session
oniux bash

The sandboxing is comprehensive. Even if you run malicious software that attempts to bypass Tor through raw system calls or direct network access, the kernel prevents it from seeing anything except the onion0 interface.

DNS and Configuration Details

DNS resolution requires special handling in Tor environments. Oniux creates a custom /etc/resolv.conf inside the namespace that points to Tor-compatible name resolution. This prevents DNS queries from leaking through your normal resolvers.

The technical implementation uses rtnetlink(7) operations to configure the virtual interface, assigns IP addresses, and sets up routing tables. OnionMasq then passes the TUN device file descriptor between processes using Unix domain sockets.

Under the hood, OnionMasq communicates with Arti using established interfaces. Arti builds Tor circuits, encrypts traffic, and handles the anonymity routing. OnionMasq simply provides the tunnel plumbing that makes this invisible to applications.

Limitations and Development Status

OnionMasq carries experimental status for good reason. The Tor Project explicitly acknowledges this isn't production-ready software. Current limitations include:

Limited platform support. Linux only, with no Windows or macOS versions planned.

New codebase risks. While torsocks has 15 years of battle-testing, OnionMasq builds on recent Rust components that haven't seen equivalent real-world stress.

Potential performance overhead. Creating isolated namespaces for every application may consume more system resources than proxy-based approaches.

Incomplete feature set. Advanced Tor features and edge cases may not work correctly compared to established tools.

The Tor Project requests community testing and bug reports to accelerate development toward production readiness.

Technical Comparison: OnionMasq vs Torsocks

Future Development and Roadmap

Tor's design work includes expanding OnionMasq capabilities beyond current TCP-only support. Proposal 348 outlines UDP support plans, while Proposal 352 addresses complex DNS scenarios including modern record types like HTTPS/SVCB that matter for HTTP/3 and QUIC protocols.

These enhancements target "VPN-like" usage patterns where users expect comprehensive application support rather than just web browsing.

Operational Security Implications

OnionMasq offers superior protection against several attack vectors:

Application-level bypass attempts fail because the kernel prevents access to non-Tor networks regardless of application behavior.

DNS leak prevention is built-in through namespace-isolated resolution rather than relying on proper application configuration.

Process isolation means even if one application is compromised, it cannot interfere with other applications' Tor routing.

However, the experimental status creates its own operational risks. Production deployments requiring high reliability should continue using torsocks until OnionMasq reaches stability.

The Bottom Line

OnionMasq represents a fundamental shift from application-level Tor integration to kernel-enforced network isolation. The approach eliminates entire categories of traffic leaks that have plagued previous solutions.

The technology works by creating per-application network sandboxes with virtual interfaces that look normal but route everything through Tor circuits. Linux kernel namespaces provide the isolation, while OnionMasq handles the tunnel plumbing between virtual networks and Tor routing.

Early testing shows the concept is sound, but production readiness remains months or years away. For now, OnionMasq serves as a preview of where Tor client technology is heading: toward stronger, kernel-level traffic isolation that's much harder to bypass or misconfigure.