SSHUTTLE(1)

📦
version 2.0.0 · 13 versions
, in arch rolling

💅 sshuttle(1) — the ssh-powered VPN that's giving main character energy ✨

💖 NAME 💖

sshuttle — sshuttle documentation

Okay bestie, that's the official name line. The vibes? Immaculate.

🌸 SYNOPSIS 🌸

Here's the one-line summoning ritual:

sshuttle [options] -r [username@]sshserver[:port] <subnets ...>

🦋 DESCRIPTION 🦋

Okay so sshuttle allows you to create a VPN connection from your machine to any remote server that you can connect to via ssh, as long as that server has a sufficiently new Python installation. Yes, that's the whole magic trick.

To work, you must have root access on the local machine, but you can have a normal account on the server. Lowkey the best deal.

It's valid to run sshuttle more than once simultaneously on a single client machine, connecting to a different server every time, so you can be on more than one VPN at once. Multi-VPN main character behavior, honestly.

If run on a router, sshuttle can forward traffic for your entire subnet to the VPN. Router era activated.

💅 OPTIONS 💅

Okay, now the part you actually came for: every flag, every placeholder, every default. No skipping, no cap. ✨

  • <subnets> — A list of subnets to route over the VPN, in the form a.b.c.d[/width][port[-port]]. Valid examples are 1.2.3.4 (a single IP address) and 1.2.3.4/32 (equivalent to 1.2.3.4), 1.2.3.0/24 (a 24-bit subnet, ie. with a 255.255.255.0 netmask). Specify subnets 0/0 to match all IPv4 addresses and ::/0 to match all IPv6 addresses. Any of the previous examples are also valid if you append a port or a port range, so 1.2.3.4:8000 will only tunnel traffic that has as the destination port 8000 of 1.2.3.4 and 1.2.3.0/24:8000-9000 will tunnel traffic going to any port between 8000 and 9000 (inclusive) for all IPs in the 1.2.3.0/24 subnet. A hostname can be provided instead of an IP address. If the hostname resolves to multiple IPs, all of the IPs are included. If a width is provided with a hostname, the width is applied to all of the hostname's IPs (if they are all either IPv4 or IPv6). Widths cannot be supplied to hostnames that resolve to both IPv4 and IPv6. Valid examples are example.com, example.com:8000, example.com/24, example.com/24:8000 and example.com:8000-9000. That's the whole subnet vibe check.
  • --method <auto|nat|nft|tproxy|pf|ipfw> — Which firewall method should sshuttle use? For auto, sshuttle attempts to guess the appropriate method depending on what it can find in PATH. The default value is auto. Auto is the default bestie, it's got you.
  • -l <[ip:]port>, --listen=<[ip:]port> — Use this ip address and port number as the transparent proxy port. By default sshuttle finds an available port automatically and listens on IP 127.0.0.1 (localhost), so you don't need to override it, and connections are only proxied from the local machine, not from outside machines. If you want to accept connections from other machines on your network (ie. to run sshuttle on a router) try enabling IP Forwarding in your kernel, then using --listen 0.0.0.0:0. You can use any name resolving to an IP address of the machine running sshuttle, e.g. --listen localhost.

For the nft, tproxy and pf methods this can be an IPv6 address. Use this option with comma separated values if required, to provide both IPv4 and IPv6 addresses, e.g. --listen 127.0.0.1:0,[::1]:0. IPv6 girlies, this one's for you.

  • -H, --auto-hosts — Scan for remote hostnames and update the local /etc/hosts file with matching entries for as long as the VPN is open. This is nicer than changing your system's DNS (/etc/resolv.conf) settings, for several reasons. First, hostnames are added without domain names attached, so you can ssh thatserver without worrying if your local domain matches the remote one. Second, if you sshuttle into more than one VPN at a time, it's impossible to use more than one DNS server at once anyway, but sshuttle correctly merges /etc/hosts entries between all running copies. Third, if you're only routing a few subnets over the VPN, you probably would prefer to keep using your local DNS server for everything else.

sshuttle tries to store a cache of the hostnames in ~/.sshuttle.hosts on the remote host. Similarly, it tries to read the file when you later reconnect to the host with --auto-hosts enabled to quickly populate the host list. When troubleshooting this feature, try removing this file on the remote host when sshuttle is not running. Cache era, but make it cute.

  • -N, --auto-nets — In addition to the subnets provided on the command line, ask the server which subnets it thinks we should route, and route those automatically. The suggestions are taken automatically from the server's routing table.

Heads up: This feature does not detect IPv6 routes. Specify IPv6 subnets manually. For example, specify the ::/0 subnet on the command line to route all IPv6 traffic. Manual IPv6 bestie, don't forget.

  • --dns — Capture local DNS requests and forward to the remote DNS server. All queries to any of the local system's DNS servers (/etc/resolv.conf and, if it exists, /run/systemd/resolve/resolv.conf) will be intercepted and resolved on the remote side of the tunnel instead, there using the DNS specified via the --to-ns option, if specified. Only plain DNS traffic sent to these servers on port 53 are captured. DNS said "not today, local resolver."
  • --ns-hosts=<server1[,server2[,server3[...]]]> — Capture local DNS requests to the specified server(s) and forward to the remote DNS server. Contrary to the --dns option, this flag allows to specify the DNS server(s) the queries to which to intercept, instead of intercepting all DNS traffic on the local machine. This can be useful when only certain DNS requests should be resolved on the remote side of the tunnel, e.g. in combination with dnsmasq. Selective DNS interception? Obsessed.
  • --to-ns=<server> — The DNS to forward requests to when remote DNS resolution is enabled. If not given, sshuttle will simply resolve using the system configured resolver on the remote side (via /etc/resolv.conf on the remote side). Remote resolver doing its thing.
  • --python — Specify the name/path of the remote python interpreter. The default is to use python3 (or python, if python3 fails) in the remote system's PATH. Python bestie, obviously.
  • -r <[username@]sshserver[:port]>, --remote=<[username@]sshserver[:port]> — The remote hostname and optional username and ssh port number to use for connecting to the remote server. For example, example.com, <testuser@example.com>, <testuser@example.com>:2222, or example.com:2244. This hostname is passed to ssh, so it will recognize any aliases and settings you may have configured in ~/.ssh/config. ssh config girlies rise up.
  • -x <subnet>, --exclude=<subnet> — Explicitly exclude this subnet from forwarding. The format of this option is the same as the <subnets> option. To exclude more than one subnet, specify the -x option more than once. You can say something like 0/0 -x 1.2.3.0/24 to forward everything except the local subnet over the VPN, for example. Not that one, bestie.
  • -X <file>, --exclude-from=<file> — Exclude the subnets specified in a file, one subnet per line. Useful when you have lots of subnets to exclude. List girlies, this is your moment.
  • -v, --verbose — Print more information about the session. This option can be used more than once for increased verbosity. By default, sshuttle prints only error messages. Turn the yapping up, bestie.
  • -e, --ssh-cmd — The command to use to connect to the remote server. The default is just ssh. Use this if your ssh client is in a non-standard location or you want to provide extra options to the ssh command, for example, -e 'ssh -v'. Custom ssh command? Say less.
  • --remote-shell — For Windows targets, specify configured remote shell program alternative to defacto posix shell. It would be either cmd or powershell unless something like git-bash is in use. Windows besties have options.
  • --no-cmd-delimiter — Do not add a double dash (--) delimiter before invoking Python on the remote host. This option is useful when the ssh command used to connect is a custom command that does not interpret this delimiter correctly. No --? No problem.
  • --seed-hosts — A comma-separated list of hostnames to use to initialize the --auto-hosts scan algorithm. --auto-hosts does things like poll netstat output for lists of local hostnames, but can speed things up if you use this option to give it a few names to start from.

If this option is used without --auto-hosts, then the listed hostnames will be scanned and added, but no further hostnames will be added. Seed the host list, queen.

  • --no-latency-control — Sacrifice latency to improve bandwidth benchmarks. ssh uses really big socket buffers, which can overload the connection if you start doing large file transfers, thus making all your other sessions inside the same tunnel go slowly. Normally, sshuttle tries to avoid this problem using a "fullness check" that allows only a certain amount of outstanding data to be buffered at a time. But on high-bandwidth links, this can leave a lot of your bandwidth underutilized. It also makes sshuttle seem slow in bandwidth benchmarks (benchmarks rarely test ping latency, which is what sshuttle is trying to control). This option disables the latency control feature, maximizing bandwidth usage. Use at your own risk. No cap, it's giving chaos.
  • --latency-buffer-size — Set the size of the buffer used in latency control. The default is 32768. Changing this option allows a compromise to be made between latency and bandwidth without completely disabling latency control (with --no-latency-control). Buffer tuning, but make it balanced.
  • -D, --daemon — Automatically fork into the background after connecting to the remote server. Implies --syslog. Background mode: activated.
  • -s <file>, --subnets=<file> — Include the subnets specified in a file instead of on the command line. One subnet per line. File girlies stay winning.
  • --syslog — after connecting, send all log messages to the syslog(3) service instead of stderr. This is implicit if you use --daemon. Logs? To syslog? It's giving organized.
  • --pidfile=<pidfilename> — when using --daemon, save sshuttle's pid to pidfilename. The default is sshuttle.pid in the current directory. PID file, cute.
  • --disable-ipv6 — Disable IPv6 support for methods that support it (nat, nft, tproxy, and pf). IPv6? Not for this method, bestie.
  • --firewall — (internal use only) run the firewall manager. This is the only part of sshuttle that must run as root. If you start sshuttle as a non-root user, it will automatically run sudo or su to start the firewall manager, but the core of sshuttle still runs as a normal user. Internal use only — don't touch unless you know the lore.
  • --hostwatch — (internal use only) runs the hostwatch daemon ✨ this lil process lives on the server side and scoops up hostnames for the --auto-hosts option. Using it on its own makes debugging and testing --auto-hosts so much easier, ngl 🫶
  • --sudoers-no-modify — sshuttle prints a config to stdout that lets a user run sshuttle without a password. Bestie, listen: this option is INSECURE 😭 because with some cleverness it also lets the user run any command as root without a password. The output also includes a suggested method for you to install the configuration. Use --sudoers-user to modify the user that it applies to.
  • --sudoers-user — sets the user name, or group with %group_name, for passwordless operation. Default is the current user. Set it to ALL for all users (NOT RECOMMENDED: See note about security in --sudoers-no-modify documentation above). Only works with the --sudoers-no-modify option 💅
  • -t <mark>, --tmark=<mark> — an option used by the tproxy method: use the specified traffic mark. The mark must be a hexadecimal value. Defaults to 0x01 ⭐
  • --version — prints program version 🎀

🦋 CONFIGURATION FILE 🦋

All the options described above can optionally be specified in a configuration file. Yes, all of them 💖

To run sshuttle with options defined in, e.g., /etc/sshuttle.conf just pass the path to the file preceded by the @ character, e.g. @/etc/sshuttle.conf.

When running sshuttle with options defined in a configuration file, options can still be passed via the command line in addition to what's defined in the file. And if a given option shows up both in the file and on the command line, the value in the command line takes precedence 👑

Arguments read from a file must be one per line, as shown below:

value
--option1
value1
--option2
value2

The configuration file supports comments for human-readable annotations 🧚 For example:

# company-internal API
8.8.8.8/32
# home IoT
192.168.63.0/24

🌈 ENVIRONMENT VARIABLE 🌈

You can specify command line options with the SSHUTTLE_ARGS environment variable ✨ If a given option is defined in both the environment variable and command line, the value on the command line will take precedence.

For example:

SSHUTTLE_ARGS="-e 'ssh -v' --dns" sshuttle -r example.com 0/0

💜 EXAMPLES 💜

Use the following command to route all IPv4 TCP traffic through the remote (-r) host example.com (and possibly other traffic too, depending on the selected --method). The 0/0 subnet, short for 0.0.0.0/0, matches all IPv4 addresses. The ::/0 subnet, matching all IPv6 addresses, could be added to the example. The SSH connection endpoint is automatically excluded from forwarding. When ProxyCommand is configured, automatic exclusion is skipped; use -x to exclude the required address manually. Press Ctrl+C to exit 🙈 To also route DNS queries through sshuttle, try adding --dns. Add or remove -v options to see more or less information:

$ sshuttle -r example.com 0/0

Starting sshuttle proxy (version ...).
[local sudo] Password:
fw: Starting firewall with Python version 3.9.5
fw: ready method name nat.
c : IPv6 disabled since it isn't supported by method nat.
c : Method: nat
c : IPv4: on
c : IPv6: off (not available with nat method)
c : UDP : off (not available with nat method)
c : DNS : off (available)
c : User: off (available)
c : Subnets to forward through remote host (type, IP, cidr mask width, startPort, endPort):
c :   (<AddressFamily.AF_INET: 2>, '0.0.0.0', 0, 0, 0)
c : Subnets to exclude from forwarding:
c :   (<AddressFamily.AF_INET: 2>, '127.0.0.1', 32, 0, 0)
c :   (<AddressFamily.AF_INET: 2>, '...', 32, 0, 0)
c : TCP redirector listening on ('127.0.0.1', 12299).
c : Starting client with Python version 3.9.5
c : Connecting to server...
user@example.com's password:
 s: Starting server with Python version 3.6.8
 s: latency control setting = True
 s: auto-nets:False
c : Connected to server.
fw: setting up.
fw: iptables -w -t nat -N sshuttle-12299
fw: iptables -w -t nat -F sshuttle-12299
...
Accept: 192.168.42.121:60554 -> 77.141.99.22:22.
^C
c : Keyboard interrupt: exiting.
c : SW'unknown':Mux#1: deleting (1 remain)
c : SW#7:192.168.42.121:60554: deleting (0 remain)

Connect to a remote server, with automatic hostname and subnet guessing 🎀:

$ sshuttle -vNHr example.com
Starting sshuttle proxy (version ...).
[local sudo] Password:
fw: Starting firewall with Python version 3.9.5
fw: ready method name nat.
c : IPv6 disabled since it isn't supported by method nat.
c : Method: nat
c : IPv4: on
c : IPv6: off (not available with nat method)
c : UDP : off (not available with nat method)
c : DNS : off (available)
c : User: off (available)
c : Subnets to forward through remote host (type, IP, cidr mask width, startPort, endPort):
c : NOTE: Additional subnets to forward may be added below by --auto-nets.
c : Subnets to exclude from forwarding:
c :   (<AddressFamily.AF_INET: 2>, '127.0.0.1', 32, 0, 0)
c :   (<AddressFamily.AF_INET: 2>, '...', 32, 0, 0)
c : TCP redirector listening on ('127.0.0.1', 12300).
c : Starting client with Python version 3.9.5
c : Connecting to server...
user@example.com's password:
 s: Starting server with Python version 3.6.8
 s: latency control setting = True
 s: auto-nets:True
c : Connected to server.
c : seed_hosts: []
 s: available routes:
 s:   77.141.99.0/24
fw: setting up.
fw: iptables -w -t nat -N sshuttle-12300
fw: iptables -w -t nat -F sshuttle-12300
...
c : Accept: 192.168.42.121:60554 -> 77.141.99.22:22.
^C
c : Keyboard interrupt: exiting.
c : SW'unknown':Mux#1: deleting (1 remain)
c : SW#7:192.168.42.121:60554: deleting (0 remain)

Run sshuttle with a /etc/sshuttle.conf configuration file 🦋:

$ sshuttle @/etc/sshuttle.conf

Use the options defined in /etc/sshuttle.conf but be more verbose:

$ sshuttle @/etc/sshuttle.conf -vvv

Override the remote server defined in /etc/sshuttle.conf:

$ sshuttle @/etc/sshuttle.conf -r otheruser@test.example.com

Example configuration file 🌸:

192.168.0.0/16
--remote
user@example.com

🔥 DISCUSSION 🔥

When it starts, sshuttle creates an ssh session to the server specified by the -r option ✨

After connecting to the remote server, sshuttle uploads its (python) source code to the remote end and executes it there. So you don't need to install sshuttle on the remote server, and there are never sshuttle version conflicts between client and server 👑 iconic behavior honestly.

Unlike most VPNs, sshuttle forwards sessions, not packets. That is, it uses kernel transparent proxying (iptables REDIRECT rules on Linux) to capture outgoing TCP sessions, then creates entirely separate TCP sessions out to the original destination at the other end of the tunnel 🫶

Packet-level forwarding (eg. using the tun/tap devices on Linux) seems elegant at first, but it results in several problems, notably the 'tcp over tcp' problem 😭 The tcp protocol depends fundamentally on packets being dropped in order to implement its congestion control algorithm; if you pass tcp packets through a tcp-based tunnel (such as ssh), the inner tcp packets will never be dropped, and so the inner tcp stream's congestion control will be completely broken, and performance will be terrible. Thus, packet-based VPNs (such as IPsec and openvpn) cannot use tcp-based encrypted streams like ssh or ssl, and have to implement their own encryption from scratch, which is very complex and error prone 💀

sshuttle's simplicity comes from the fact that it can safely use the existing ssh encrypted tunnel without incurring a performance penalty. It does this by letting the client-side kernel manage the incoming tcp stream, and the server-side kernel manage the outgoing tcp stream; there is no need for congestion control to be shared between the two separate streams, so a tcp-based tunnel is fine ⭐

See also: ssh(1), python(1)

🎀 Author 🎀

Brian May

2016, Brian May

and that's the whole page bestie, you ate that 💅✨ This gorgeous lil manual is from sshuttle 2.0, dated Sep 30, 2026 — go forth and tunnel responsibly 🦋💖

📦 where this page comes from