sshuttle

Forward all IPv4 TCP traffic via a remote SSH server

$ sshuttle [[-r|--remote]] [username]@[sshserver] [0.0.0.0/0]

$ sshuttle --dns [[-r|--remote]] [username]@[sshserver] [0.0.0.0/0]

$ sshuttle [[-r|--remote]] [username]@[sshserver] [0.0.0.0/0] [[-x|--exclude]] [192.168.0.1/24]

$ sshuttle --method tproxy [[-r|--remote]] [username]@[sshserver] [0.0.0.0/0] [::/0] [[-x|--exclude]] [your_local_ip_address] [[-x|--exclude]] [ssh_server_ip_address]

sshuttle [options] -r [[user@]host[:port]] [<subnet1> <subnet2> ...]

-r [user@]host[:port]
    Specifies the remote server to connect to via SSH. This is a mandatory option.

<subnet...>
    One or more subnets (e.g., 192.168.1.0/24, 0.0.0.0/0) that should be routed through the sshuttle tunnel. If 0.0.0.0/0 is used, all traffic not explicitly excluded will be tunneled.

-l [ip:]port
    Specifies the local IP address and/or port for the transparent proxy. Defaults to 127.0.0.1:12300.

-D, --daemon
    Runs sshuttle in the background as a daemon.

-v, --verbose
    Increases verbosity. Use multiple times (e.g., -vv) for more debug information.

--dns
    Handles DNS queries by proxying them through the remote server. Essential for accessing hostnames on the remote network or resolving public DNS securely.

-x <subnet>
    Excludes a specific subnet from being tunneled. Can be specified multiple times.

--ssh-cmd <command>
    Specifies a custom SSH command to use instead of 'ssh'. Useful for passing specific SSH options (e.g., authentication, proxyjump).

--seed-hosts <file>
    Provides a file with a list of hostnames (one per line) for sshuttle to pre-resolve for its DNS proxy.

--split-dns
    Enables split DNS, where only DNS queries for domains listed in /etc/resolv.conf are sent through the tunnel, others are resolved locally.

--pidfile <file>
    Writes the PID of the daemon process to the specified file when running in daemon mode.

sshuttle is a lightweight, transparent proxy server that creates a VPN-like connection over an SSH tunnel. Unlike traditional VPNs (like OpenVPN or IPsec), sshuttle does not require complex configuration of VPN software or creation of TUN/TAP devices. Instead, it works by forwarding TCP connections and optionally DNS queries through an SSH connection to a remote server. The remote server then acts as the network's gateway for the forwarded traffic.

This makes sshuttle ideal for bypassing firewalls, accessing services on a remote network, or securely browsing the internet from an untrusted network. It achieves transparency by using local firewall rules (e.g., iptables on Linux) to redirect traffic, allowing applications to connect to remote resources as if they were directly accessible, without needing proxy awareness. A key advantage is that sshuttle only requires Python on the remote server (which it can upload automatically) and an SSH client on the local machine, making it highly portable and easy to set up.

sshuttle is a powerful tool but has certain limitations:

Not a full IP-level VPN: Unlike true VPNs that create virtual network interfaces (like TUN/TAP devices) and route all IP traffic, sshuttle operates at the TCP stream level and proxies DNS queries. It does not directly support forwarding arbitrary IP protocols (e.g., ICMP, UDP outside of DNS).

Performance Overhead: Traffic is multiplexed over a single SSH connection. While SSH itself is efficient, the overhead of encryption and the single-stream nature can limit throughput, especially for high-bandwidth applications or when the network latency to the SSH server is significant.

Python Requirement: The remote server needs a Python interpreter (version 2.7+ or 3.x). sshuttle will attempt to upload a minimal python script if Python is not found, but a working interpreter is essential for the server-side proxy to function.

Root Privileges on Client (for iptables): On Linux, sshuttle typically requires root privileges (or sudo access) to modify iptables rules for transparent proxying. Some non-root methods exist but are less common.

While sshuttle operates on TCP streams and doesn't require a virtual network device, it typically needs root privileges (or sudo) on the client machine to configure iptables (Linux) or PF (macOS) rules for transparent traffic redirection. Without these privileges, it cannot transparently intercept and forward all network traffic.

One of sshuttle's major advantages is that it requires no prior installation or configuration on the remote SSH server beyond having a Python interpreter available. sshuttle automatically copies and executes its necessary Python scripts on the remote server once the SSH connection is established, making deployment exceptionally straightforward.

When sshuttle is active, outbound TCP connections (and optionally DNS requests) from the client machine are intercepted by local firewall rules, redirected to the sshuttle process, encapsulated within the SSH tunnel, sent to the remote server, and then decapsulated and forwarded to their original destination by the sshuttle process running on the remote server.

sshuttle was created by Brian May as an attempt to provide a simple, robust, and transparent proxying solution over SSH without the complexities of traditional VPN setups. Its development focused on ease of use, requiring minimal configuration and no special server-side software installation beyond a Python interpreter (which sshuttle can even upload). It gained popularity among developers and system administrators for its ability to quickly and securely bypass network restrictions and access remote resources, especially in scenarios where full VPN access is overkill or unavailable. Its design prioritizes "transparency" – allowing applications to connect directly without proxy awareness – making it highly versatile for various network tunneling needs.

ssh(1), iptables(8), socat(1), openvpn(8), proxychains(1)