sshuttle Deployment and Usage Guide

Prerequisites

Python: Version 2.3 or higher (sshuttle supports Python 2.3+)
SSH: Client access to remote servers
Root privileges: Required for network routing and firewall modifications on both client and server
Network access: Ability to establish SSH connections to target servers

Installation

From Source

Clone the repository:

git clone https://github.com/sshuttle/sshuttle.git
cd sshuttle

Install the package:

sudo python setup.py install

Using pip

pip install sshuttle

System Package Managers

sshuttle is available in many package repositories:

Ubuntu/Debian:

sudo apt-get install sshuttle

Fedora/CentOS:

sudo yum install sshuttle

Configuration

Basic Configuration

No configuration files are required for basic operation. sshuttle uses SSH for authentication, so ensure your SSH keys are properly configured.

Environment Variables

SSHUTTLE_PIDFILE: Path to the PID file when running in daemon mode
SSHUTTLE_LOG_LEVEL: Set logging verbosity (debug, info, warning, error)

SSH Configuration

Ensure your SSH client is configured to connect to the target server without password prompts. Add entries to ~/.ssh/config if needed:

Host myserver
    HostName example.com
    User yourusername
    IdentityFile ~/.ssh/id_rsa

Build & Run

Basic Usage

# Route all traffic through remote server
sshuttle -r user@server 0.0.0.0/0

# Route specific subnets
sshuttle -r user@server 192.168.1.0/24 10.0.0.0/8

# Use sudo for network routing
sudo sshuttle -r user@server 0.0.0.0/0

Advanced Options

# Daemon mode with PID file
sshuttle -D -P /var/run/sshuttle.pid -r user@server 0.0.0.0/0

# Specify method (auto-detects best method)
sshuttle -H -r user@server 0.0.0.0/0

# Use specific method (e.g., pf on BSD, tproxy on Linux)
sshuttle -x pf -r user@server 0.0.0.0/0

Server-Side Requirements

The remote server needs Python installed. sshuttle will automatically detect and use available methods:

Linux: TPROXY with iptables
BSD: PF (Packet Filter)
macOS: PF or manual routing

Deployment

Local Development

For testing and development, run sshuttle directly on your local machine:

# Test connection without routing
sshuttle -v -r user@server --dry-run

# Start with verbose logging
sshuttle -vv -r user@server 0.0.0.0/0

Production Deployment

sshuttle is designed to run on client machines, not servers. Deploy it on your local workstation or any machine that needs to route traffic through a remote server.

Recommended platforms:

Linux: Native support with TPROXY method
macOS: Native support with PF method
Windows: Use WSL (Windows Subsystem for Linux) for best compatibility

Docker Usage

Create a Docker container for sshuttle:

FROM python:3.9-slim
RUN pip install sshuttle
ENTRYPOINT ["sshuttle"]

Troubleshooting

Common Issues

1. Permission Denied

# Solution: Run with sudo for network operations
sudo sshuttle -r user@server 0.0.0.0/0

2. Connection Refused

# Check SSH connectivity first
ssh user@server

# Ensure remote server has Python installed
ssh user@server "python --version"

3. Method Detection Failed

# Manually specify method
sshuttle -x tproxy -r user@server 0.0.0.0/0  # Linux
sshuttle -x pf -r user@server 0.0.0.0/0      # BSD/macOS

4. DNS Resolution Issues

# Enable DNS forwarding
sshuttle --dns -r user@server 0.0.0.0/0

5. PID File Conflicts

# Remove stale PID file
rm -f /var/run/sshuttle.pid
# Or specify a different PID file
sshuttle -P /tmp/sshuttle.pid -r user@server 0.0.0.0/0

Debug Mode

Enable verbose logging for troubleshooting:

sshuttle -vvv -r user@server 0.0.0.0/0

Log Files

Check system logs for sshuttle-related messages:

# Linux
journalctl -u sshuttle

# macOS
log show --predicate 'process == "sshuttle"'

Network Verification

Verify routing is working correctly:

# Check routing table
ip route show

# Test connectivity through tunnel
curl -I http://ifconfig.me

How to Deploy & Use apenwarr/sshuttle