sshuttle Transparent Proxy VPN

1.3.2 · active · verified Fri Apr 17

sshuttle is a transparent proxy server that acts as a 'poor man's VPN', forwarding network traffic over SSH. It doesn't require admin privileges for basic use and works across Linux and macOS, supporting DNS tunneling. The current stable version is 1.3.2, with releases occurring periodically, often driven by bug fixes and platform compatibility updates.

Common errors

```
sshuttle: failed to connect to remote server: [Errno 111] Connection refused
```
cause The SSH daemon on the remote server is not running, is firewalled, or the specified port is incorrect.

fix Verify the remote server's SSH service is running and accessible from your client. Check firewall rules on both client and server. Ensure the SSH port (default 22) is open and specified correctly if non-standard (e.g., `sshuttle -r user@host:port ...`).
```
Permission denied (publickey,password).
```
cause SSH authentication failure. The username, password, or SSH key is incorrect or not properly configured.

fix Ensure you're using the correct username and password/key for the remote server. Test SSH connectivity independently (e.g., `ssh user@remote_server`). Add your SSH key to your agent (`ssh-add ~/.ssh/id_rsa`).
```
Name or service not known
```
cause DNS resolution is failing, often when using `--dns` and the remote server cannot resolve names or the local client's DNS is misconfigured.

fix Without `--dns`, ensure your local system's DNS resolvers are functional. If using `--dns`, verify the remote SSH server has working DNS resolution and its firewall allows outgoing DNS queries. Try `sshuttle -r user@remote_server 0.0.0.0/0` (without `--dns`) to isolate the issue.
```
sshuttle: Cannot bind to 127.0.0.1:port (or similar IP/port combination)
```
cause The specified local port that sshuttle tries to bind to is already in use by another application.

fix This usually means another instance of sshuttle or a different application is using the required port. Kill existing sshuttle processes (`pgrep sshuttle | xargs kill`) or identify and stop the conflicting application. Rebooting may also resolve transient port issues.

Warnings

gotcha Python version compatibility for sshuttle is strict: it requires Python >=3.9 and <4.0. Using incompatible Python versions can lead to installation failures or runtime errors.
Fix: Ensure your environment uses Python 3.9 or 3.10. Consider using pyenv or virtual environments to manage Python versions for sshuttle.
gotcha DNS tunneling can be problematic. If the remote SSH server's `sshd` configuration or firewall prevents `sshuttle` from making DNS queries, your DNS resolution might fail or leak.
Fix: Verify that `sshuttle --dns` works correctly by checking name resolution after connecting. If issues persist, ensure the remote SSH server allows outgoing connections on port 53 (UDP/TCP) from the `sshuttle` process or disable `--dns` and configure local DNS to a remote server.
gotcha sshuttle can conflict with existing VPN connections or complex network configurations (e.g., specific firewall rules, other routing daemons), potentially leading to routing loops or connection drops.
Fix: Disable other VPNs before starting sshuttle. If you have custom firewall rules, you may need to adjust them to allow sshuttle's traffic manipulation. Test connectivity thoroughly after starting sshuttle.
gotcha Performance can be significantly impacted by high latency or low bandwidth SSH connections, as all traffic is multiplexed and tunneled over a single TCP connection.
Fix: Choose an SSH server with low latency to your client. For specific applications requiring higher throughput, consider alternative VPN solutions. Optimize SSH settings (e.g., Compression, Cipher) if possible, but keep in mind sshuttle itself handles some optimizations.

Install

pip install sshuttle Install with pip

Quickstart

This command will establish a transparent proxy connection to `remote_server` via SSH, routing all local traffic (0.0.0.0/0) through the remote server. Replace `user` with your SSH username and `remote_server` with the IP address or hostname of your SSH server.

sshuttle -r user@remote_server 0.0.0.0/0
# For specific subnets:
# sshuttle -r user@remote_server 192.168.1.0/24 10.0.0.0/8

# To enable DNS tunneling (requires remote_server's sshd to allow dns queries from sshuttle):
# sshuttle --dns -r user@remote_server 0.0.0.0/0

# Example using environment variables for SSH:
# export SSH_USER="your_user"
# export SSH_HOST="your_host.com"
# sshuttle -r "$SSH_USER@$SSH_HOST" 0.0.0.0/0

view raw JSON →