sshuttle

library1.3.2pypiunverified

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.

http-networking devops auth-security

pip install sshuttle

homepage ↗

INSTALL

IMPORT

SIG · SSHUTTLE

sshuttle

http-networkingenv1.3.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

sshuttle --version

Debug

Known issues

gotchaPython 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.

affects: <1.3.0

gotchaDNS 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.

affects: All versions

gotchasshuttle 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.

affects: All versions

gotchaPerformance 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.

affects: All versions

Errors

Common errors & fixes

sshuttle: failed to connect to remote server: [Errno 111] Connection refused

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).

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

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)

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.

Upgrade

Version history

1.3.2latest on PyPI · released Aug 10, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

homepagehttps://sshuttle.readthedocs.org ↗