SSHUTTLE(1) sshuttle SSHUTTLE(1)
NAME
sshuttle - sshuttle documentation
SYNOPSIS
sshuttle [options] -r [username@]sshserver[:port] <subnets …>
DESCRIPTION
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.
To work, you must have root access on the local machine, but you can
have a normal account on the server.
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.
If run on a router, sshuttle can forward traffic for your entire subnet
to the VPN.
OPTIONS
<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 sin-
gle 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 hostnames 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 exam-
ple.com, example.com:8000, example.com/24, example.com/24:8000
and example.com:8000-9000.
--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.
-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 ma-
chine, not from outside machines. If you want to accept connec-
tions from other machines on your network (ie. to run sshuttle
on a router) try enabling IP Forwarding in your kernel, then us-
ing --listen 0.0.0.0:0. You can use any name resolving to an IP
address of the machine running sshuttle, e.g. --listen local-
host.
For the nft, tproxy and pf methods this can be an IPv6 address.
Use this option with comma separated values if required, to pro-
vide both IPv4 and IPv6 addresses, e.g. --listen
127.0.0.1:0,[::1]:0.
-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) set-
tings, for several reasons. First, hostnames are added without
domain names attached, so you can ssh thatserver without worry-
ing 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 cor-
rectly 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 ~/.sshut-
tle.hosts on the remote host. Similarly, it tries to read the
file when you later reconnect to the host with –auto-hosts en-
abled to quickly populate the host list. When troubleshooting
this feature, try removing this file on the remote host when
sshuttle is not running.
-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.
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.
--dns Capture local DNS requests and forward to the remote DNS server.
All queries to any of the local system’s DNS servers (/etc/re-
solv.conf and, if it exists, /run/systemd/resolve/resolv.conf)
will be intercepted and resolved on the remote side of the tun-
nel instead, there using the DNS specified via the --to-ns op-
tion, if specified. Only plain DNS traffic sent to these servers
on port 53 are captured.
--ns-hosts=<server1[,server2[,server3[...]]]>
Capture local DNS requests to the specified server(s) and for-
ward 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 re-
quests should be resolved on the remote side of the tunnel, e.g.
in combination with dnsmasq.
--to-ns=<server>
The DNS to forward requests to when remote DNS resolution is en-
abled. If not given, sshuttle will simply resolve using the sys-
tem configured resolver on the remote side (via /etc/resolv.conf
on the remote side).
--python
Specify the name/path of the remote python interpreter. The de-
fault is to use python3 (or python, if python3 fails) in the re-
mote system’s PATH.
-r <[username@]sshserver[:port]>, --remote=<[username@]ssh-
server[:port]>
The remote hostname and optional username and ssh port number to
use for connecting to the remote server. For example, exam-
ple.com, testuser@example.com, testuser@example.com:2222, or ex-
ample.com:2244. This hostname is passed to ssh, so it will rec-
ognize any aliases and settings you may have configured in
~/.ssh/config.
-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.
-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.
-v, --verbose
Print more information about the session. This option can be
used more than once for increased verbosity. By default, sshut-
tle prints only error messages.
-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 com-
mand, for example, -e 'ssh -v'.
--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.
--no-latency-control
Sacrifice latency to improve bandwidth benchmarks. ssh uses re-
ally 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.
--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 la-
tency control (with --no-latency-control).
-D, --daemon
Automatically fork into the background after connecting to the
remote server. Implies --syslog.
-s <file>, --subnets=<file>
Include the subnets specified in a file instead of on the com-
mand line. One subnet per line.
--syslog
after connecting, send all log messages to the syslog(3) service
instead of stderr. This is implicit if you use --daemon.
--pidfile=<pidfilename>
when using --daemon, save sshuttle’s pid to pidfilename. The
default is sshuttle.pid in the current directory.
--disable-ipv6
Disable IPv6 support for methods that support it (nat, nft,
tproxy, and pf).
--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.
--hostwatch
(internal use only) run the hostwatch daemon. This process runs
on the server side and collects hostnames for the --auto-hosts
option. Using this option by itself makes it a lot easier to
debug and test the --auto-hosts feature.
--sudoers-no-modify
sshuttle prints a configuration to stdout which allows a user to
run sshuttle without a password. This option is INSECURE be-
cause, with some cleverness, it also allows the user to 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
Set the user name or group with %group_name for passwordless op-
eration. Default is the current user. Set to ALL for all users
(NOT RECOMMENDED: See note about security in –sudoers-no-modify
documentation above). Only works with the –sudoers-no-modify op-
tion.
-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
Print program version.
CONFIGURATION FILE
All the options described above can optionally be specified in a con-
figuration file.
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, op-
tions can still be passed via the command line in addition to what is
defined in the file. If a given option is defined both in the file and
in the command line, the value in the command line will take prece-
dence.
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 annota-
tions. For example:
# company-internal API
8.8.8.8/32
# home IoT
192.168.63.0/24
EXAMPLES
Use the following command to route all IPv4 TCP traffic through 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. We also exclude (-x) example.com:22 so that we
can establish ssh connections from our local machine to the remote host
without them being routed through sshuttle. Excluding the remote host
may be necessary on some machines for sshuttle to work properly. 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 -x example.com:22 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>, '...', 32, 22, 22)
c : (<AddressFamily.AF_INET: 2>, '127.0.0.1', 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 guess-
ing:
$ sshuttle -vNHr example.com -x example.com:22
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>, '...', 32, 22, 22)
c : (<AddressFamily.AF_INET: 2>, '127.0.0.1', 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. Thus, you don’t
need to install sshuttle on the remote server, and there are never
sshuttle version conflicts between client and server.
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 ses-
sions 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
COPYRIGHT
2022, Brian May
1.1 Sep 05, 2022 SSHUTTLE(1)
Generated by dwww version 1.15 on Sat Jun 29 01:59:06 CEST 2024.