1SSHUTTLE(1)                        sshuttle                        SSHUTTLE(1)
2
3
4

NAME

6       sshuttle - sshuttle documentation
7

SYNOPSIS

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

DESCRIPTION

12       sshuttle allows you to create a VPN connection from your machine to any
13       remote server that you can connect to via ssh, as long as  that  server
14       has a sufficiently new Python installation.
15
16       To  work,  you  must have root access on the local machine, but you can
17       have a normal account on the server.
18
19       It's valid to run sshuttle more than once simultaneously  on  a  single
20       client machine, connecting to a different server every time, so you can
21       be on more than one VPN at once.
22
23       If run on a router, sshuttle can forward traffic for your entire subnet
24       to the VPN.
25

OPTIONS

27       <subnets>
28              A   list  of  subnets  to  route  over  the  VPN,  in  the  form
29              a.b.c.d[/width][port[-port]]. Valid examples are 1.2.3.4 (a sin‐
30              gle   IP   address)  and  1.2.3.4/32  (equivalent  to  1.2.3.4),
31              1.2.3.0/24 (a 24-bit subnet, ie. with a 255.255.255.0  netmask).
32              Specify  subnets  0/0  to  match  all IPv4 addresses and ::/0 to
33              match all IPv6 addresses. Any of the previous examples are  also
34              valid if you append a port or a port range, so 1.2.3.4:8000 will
35              only tunnel traffic that has as the  destination  port  8000  of
36              1.2.3.4  and  1.2.3.0/24:8000-9000  will tunnel traffic going to
37              any port between 8000 and 9000 (inclusive) for all  IPs  in  the
38              1.2.3.0/24  subnet.  A hostname can be provided instead of an IP
39              address. If the hostname resolves to multiple IPs,  all  of  the
40              IPs  are  included.  If a width is provided with a hostname, the
41              width is applied to all of the hostnames IPs (if  they  are  all
42              either  IPv4  or  IPv6).  Widths cannot be supplied to hostnames
43              that resolve to both IPv4 and IPv6.  Valid  examples  are  exam‐
44              ple.com,  example.com:8000,  example.com/24, example.com/24:8000
45              and example.com:8000-9000.
46
47       --method <auto|nat|nft|tproxy|pf|ipfw>
48              Which firewall method should sshuttle use?  For  auto,  sshuttle
49              attempts  to  guess  the appropriate method depending on what it
50              can find in PATH. The default value is auto.
51
52       -l <[ip:]port>, --listen=<[ip:]port>
53              Use this ip address and port number  as  the  transparent  proxy
54              port.  By default sshuttle finds an available port automatically
55              and listens on IP 127.0.0.1 (localhost), so you  don't  need  to
56              override it, and connections are only proxied from the local ma‐
57              chine, not from outside machines.  If you want to accept connec‐
58              tions  from  other machines on your network (ie. to run sshuttle
59              on a router) try enabling IP Forwarding in your kernel, then us‐
60              ing --listen 0.0.0.0:0.  You can use any name resolving to an IP
61              address of the machine running sshuttle,  e.g.  --listen  local‐
62              host.
63
64              For  the nft, tproxy and pf methods this can be an IPv6 address.
65              Use this option with comma separated values if required, to pro‐
66              vide    both    IPv4   and   IPv6   addresses,   e.g.   --listen
67              127.0.0.1:0,[::1]:0.
68
69       -H, --auto-hosts
70              Scan for remote hostnames and update the local  /etc/hosts  file
71              with  matching  entries for as long as the VPN is open.  This is
72              nicer than changing your system's  DNS  (/etc/resolv.conf)  set‐
73              tings,  for several reasons.  First, hostnames are added without
74              domain names attached, so you can ssh thatserver without  worry‐
75              ing if your local domain matches the remote one.  Second, if you
76              sshuttle into more than one VPN at a time,  it's  impossible  to
77              use  more  than one DNS server at once anyway, but sshuttle cor‐
78              rectly merges /etc/hosts entries  between  all  running  copies.
79              Third,  if  you're  only routing a few subnets over the VPN, you
80              probably would prefer to keep using your local  DNS  server  for
81              everything else.
82
83              sshuttle  tries  to  store a cache of the hostnames in ~/.sshut‐
84              tle.hosts on the remote host. Similarly, it tries  to  read  the
85              file  when you later reconnect to the host with --auto-hosts en‐
86              abled to quickly populate the host  list.  When  troubleshooting
87              this  feature,  try  removing  this file on the remote host when
88              sshuttle is not running.
89
90       -N, --auto-nets
91              In addition to the subnets provided on the command line, ask the
92              server  which subnets it thinks we should route, and route those
93              automatically.  The suggestions are taken automatically from the
94              server's routing table.
95
96              This  feature  does not detect IPv6 routes. Specify IPv6 subnets
97              manually. For example, specify the ::/0 subnet  on  the  command
98              line to route all IPv6 traffic.
99
100       --dns  Capture local DNS requests and forward to the remote DNS server.
101              All queries to any of the local system's DNS  servers  (/etc/re‐
102              solv.conf  and,  if it exists, /run/systemd/resolve/resolv.conf)
103              will be intercepted and resolved on the remote side of the  tun‐
104              nel  instead,  there using the DNS specified via the --to-ns op‐
105              tion, if specified. Only plain DNS traffic sent to these servers
106              on port 53 are captured.
107
108       --ns-hosts=<server1[,server2[,server3[...]]]>
109              Capture  local  DNS requests to the specified server(s) and for‐
110              ward to the remote DNS server. Contrary  to  the  --dns  option,
111              this  flag  allows  to  specify the DNS server(s) the queries to
112              which to intercept, instead of intercepting all DNS  traffic  on
113              the  local machine. This can be useful when only certain DNS re‐
114              quests should be resolved on the remote side of the tunnel, e.g.
115              in combination with dnsmasq.
116
117       --to-ns=<server>
118              The DNS to forward requests to when remote DNS resolution is en‐
119              abled. If not given, sshuttle will simply resolve using the sys‐
120              tem configured resolver on the remote side (via /etc/resolv.conf
121              on the remote side).
122
123       --python
124              Specify the name/path of the remote python interpreter. The  de‐
125              fault is to use python3 (or python, if python3 fails) in the re‐
126              mote system's PATH.
127
128       -r       <[username@]sshserver[:port]>,       --remote=<[username@]ssh‐
129       server[:port]>
130              The remote hostname and optional username and ssh port number to
131              use for connecting to the remote  server.   For  example,  exam‐
132              ple.com, testuser@example.com, testuser@example.com:2222, or ex‐
133              ample.com:2244. This hostname is passed to ssh, so it will  rec‐
134              ognize  any  aliases  and  settings  you  may have configured in
135              ~/.ssh/config.
136
137       -x <subnet>, --exclude=<subnet>
138              Explicitly exclude this subnet from forwarding.  The  format  of
139              this  option  is  the  same as the <subnets> option.  To exclude
140              more than one subnet, specify the -x option more than once.  You
141              can  say  something like 0/0 -x 1.2.3.0/24 to forward everything
142              except the local subnet over the VPN, for example.
143
144       -X <file>, --exclude-from=<file>
145              Exclude the subnets specified in a file, one  subnet  per  line.
146              Useful when you have lots of subnets to exclude.
147
148       -v, --verbose
149              Print  more  information  about the session.  This option can be
150              used more than once for increased verbosity.  By default, sshut‐
151              tle prints only error messages.
152
153       -e, --ssh-cmd
154              The  command to use to connect to the remote server. The default
155              is just ssh.  Use this if your ssh client is in  a  non-standard
156              location  or  you  want to provide extra options to the ssh com‐
157              mand, for example, -e 'ssh -v'.
158
159       --seed-hosts
160              A comma-separated list of hostnames to  use  to  initialize  the
161              --auto-hosts scan algorithm.  --auto-hosts does things like poll
162              netstat output for lists  of  local  hostnames,  but  can  speed
163              things up if you use this option to give it a few names to start
164              from.
165
166              If this option is used without  --auto-hosts,  then  the  listed
167              hostnames  will  be  scanned and added, but no further hostnames
168              will be added.
169
170       --no-latency-control
171              Sacrifice latency to improve bandwidth benchmarks. ssh uses  re‐
172              ally  big  socket  buffers, which can overload the connection if
173              you start doing large file transfers, thus making all your other
174              sessions  inside  the  same tunnel go slowly. Normally, sshuttle
175              tries to avoid this problem using a "fullness check" that allows
176              only  a  certain  amount of outstanding data to be buffered at a
177              time.  But on high-bandwidth links, this can leave a lot of your
178              bandwidth  underutilized.   It  also makes sshuttle seem slow in
179              bandwidth benchmarks (benchmarks rarely test ping latency, which
180              is  what  sshuttle  is trying to control).  This option disables
181              the latency control feature, maximizing bandwidth usage.  Use at
182              your own risk.
183
184       --latency-buffer-size
185              Set  the size of the buffer used in latency control. The default
186              is 32768. Changing this option allows a compromise  to  be  made
187              between  latency  and bandwidth without completely disabling la‐
188              tency control (with --no-latency-control).
189
190       -D, --daemon
191              Automatically fork into the background after connecting  to  the
192              remote server.  Implies --syslog.
193
194       -s <file>, --subnets=<file>
195              Include  the  subnets specified in a file instead of on the com‐
196              mand line. One subnet per line.
197
198       --syslog
199              after connecting, send all log messages to the syslog(3) service
200              instead of stderr.  This is implicit if you use --daemon.
201
202       --pidfile=<pidfilename>
203              when  using  --daemon,  save sshuttle's pid to pidfilename.  The
204              default is sshuttle.pid in the current directory.
205
206       --disable-ipv6
207              Disable IPv6 support for methods that support it  (nft,  tproxy,
208              and pf).
209
210       --firewall
211              (internal  use only) run the firewall manager.  This is the only
212              part of sshuttle that must run as root.  If you  start  sshuttle
213              as  a  non-root  user,  it  will automatically run sudo or su to
214              start the firewall manager, but the core of sshuttle still  runs
215              as a normal user.
216
217       --hostwatch
218              (internal use only) run the hostwatch daemon.  This process runs
219              on the server side and collects hostnames for  the  --auto-hosts
220              option.   Using  this  option by itself makes it a lot easier to
221              debug and test the --auto-hosts feature.
222
223       --sudoers
224              sshuttle will auto generate the proper sudoers.d config file and
225              add it.  Once this is completed, sshuttle will exit and tell the
226              user if it succeed or not. Do not call this options  with  sudo,
227              it may generate a incorrect config file.
228
229       --sudoers-no-modify
230              sshuttle  will  auto  generate  the  proper sudoers.d config and
231              print it to stdout. The option will not  modify  the  system  at
232              all.
233
234       --sudoers-user
235              Set the user name or group with %group_name for passwordless op‐
236              eration.  Default is the current user.set  ALL  for  all  users.
237              Only works with --sudoers or --sudoers-no-modify option.
238
239       --sudoers-filename
240              Set the file name for the sudoers.d file to be added. Default is
241              "sshuttle_auto". Only works with --sudoers.
242
243       -t <mark>, --tmark=<mark>
244              An option used by the tproxy method: Use the  specified  traffic
245              mark. The mark must be a hexadecimal value. Defaults to 0x01.
246
247       --version
248              Print program version.
249

CONFIGURATION FILE

251       All  the  options described above can optionally be specified in a con‐
252       figuration file.
253
254       To run sshuttle with options defined in, e.g., /etc/sshuttle.conf  just
255       pass   the  path  to  the  file  preceded  by  the  @  character,  e.g.
256       @/etc/sshuttle.conf.
257
258       When running sshuttle with options defined in a configuration file, op‐
259       tions  can  still be passed via the command line in addition to what is
260       defined in the file. If a given option is defined both in the file  and
261       in  the  command  line,  the value in the command line will take prece‐
262       dence.
263
264       Arguments read from a file must be one per line, as shown below:
265
266          value
267          --option1
268          value1
269          --option2
270          value2
271
272       The configuration file supports  comments  for  human-readable  annota‐
273       tions. For example:
274
275          # company-internal API
276          8.8.8.8/32
277          # home IoT
278          192.168.63.0/24
279

EXAMPLES

281       Use  the following command to route all IPv4 TCP traffic through remote
282       (-r) host example.com (and possibly other traffic too, depending on the
283       selected  --method).  The  0/0 subnet, short for 0.0.0.0/0, matches all
284       IPv4 addresses. The ::/0 subnet, matching all IPv6 addresses  could  be
285       added  to  the  example. We also exclude (-x) example.com:22 so that we
286       can establish ssh connections from our local machine to the remote host
287       without  them  being routed through sshuttle. Excluding the remote host
288       may be necessary on some machines for sshuttle to work properly.  Press
289       Ctrl+C  to exit. To also route DNS queries through sshuttle, try adding
290       --dns. Add or remove -v options to see more or less information:
291
292          $ sshuttle -r example.com -x example.com:22 0/0
293
294          Starting sshuttle proxy (version ...).
295          [local sudo] Password:
296          fw: Starting firewall with Python version 3.9.5
297          fw: ready method name nat.
298          c : IPv6 disabled since it isn't supported by method nat.
299          c : Method: nat
300          c : IPv4: on
301          c : IPv6: off (not available with nat method)
302          c : UDP : off (not available with nat method)
303          c : DNS : off (available)
304          c : User: off (available)
305          c : Subnets to forward through remote host (type, IP, cidr mask width, startPort, endPort):
306          c :   (<AddressFamily.AF_INET: 2>, '0.0.0.0', 0, 0, 0)
307          c : Subnets to exclude from forwarding:
308          c :   (<AddressFamily.AF_INET: 2>, '...', 32, 22, 22)
309          c :   (<AddressFamily.AF_INET: 2>, '127.0.0.1', 32, 0, 0)
310          c : TCP redirector listening on ('127.0.0.1', 12299).
311          c : Starting client with Python version 3.9.5
312          c : Connecting to server...
313          user@example.com's password:
314           s: Starting server with Python version 3.6.8
315           s: latency control setting = True
316           s: auto-nets:False
317          c : Connected to server.
318          fw: setting up.
319          fw: iptables -w -t nat -N sshuttle-12299
320          fw: iptables -w -t nat -F sshuttle-12299
321          ...
322          Accept: 192.168.42.121:60554 -> 77.141.99.22:22.
323          ^C
324          c : Keyboard interrupt: exiting.
325          c : SW'unknown':Mux#1: deleting (1 remain)
326          c : SW#7:192.168.42.121:60554: deleting (0 remain)
327
328       Connect to a remote server, with automatic hostname and  subnet  guess‐
329       ing:
330
331          $ sshuttle -vNHr example.com -x example.com:22
332          Starting sshuttle proxy (version ...).
333          [local sudo] Password:
334          fw: Starting firewall with Python version 3.9.5
335          fw: ready method name nat.
336          c : IPv6 disabled since it isn't supported by method nat.
337          c : Method: nat
338          c : IPv4: on
339          c : IPv6: off (not available with nat method)
340          c : UDP : off (not available with nat method)
341          c : DNS : off (available)
342          c : User: off (available)
343          c : Subnets to forward through remote host (type, IP, cidr mask width, startPort, endPort):
344          c : NOTE: Additional subnets to forward may be added below by --auto-nets.
345          c : Subnets to exclude from forwarding:
346          c :   (<AddressFamily.AF_INET: 2>, '...', 32, 22, 22)
347          c :   (<AddressFamily.AF_INET: 2>, '127.0.0.1', 32, 0, 0)
348          c : TCP redirector listening on ('127.0.0.1', 12300).
349          c : Starting client with Python version 3.9.5
350          c : Connecting to server...
351          user@example.com's password:
352           s: Starting server with Python version 3.6.8
353           s: latency control setting = True
354           s: auto-nets:True
355          c : Connected to server.
356          c : seed_hosts: []
357           s: available routes:
358           s:   77.141.99.0/24
359          fw: setting up.
360          fw: iptables -w -t nat -N sshuttle-12300
361          fw: iptables -w -t nat -F sshuttle-12300
362          ...
363          c : Accept: 192.168.42.121:60554 -> 77.141.99.22:22.
364          ^C
365          c : Keyboard interrupt: exiting.
366          c : SW'unknown':Mux#1: deleting (1 remain)
367          c : SW#7:192.168.42.121:60554: deleting (0 remain)
368
369       Run sshuttle with a /etc/sshuttle.conf configuration file:
370
371          $ sshuttle @/etc/sshuttle.conf
372
373       Use the options defined in /etc/sshuttle.conf but be more verbose:
374
375          $ sshuttle @/etc/sshuttle.conf -vvv
376
377       Override the remote server defined in /etc/sshuttle.conf:
378
379          $ sshuttle @/etc/sshuttle.conf -r otheruser@test.example.com
380
381       Example configuration file:
382
383          192.168.0.0/16
384          --remote
385          user@example.com
386

DISCUSSION

388       When it starts, sshuttle creates an ssh session to the server specified
389       by the -r option.
390
391       After connecting to the remote server, sshuttle  uploads  its  (python)
392       source  code  to the remote end and executes it there.  Thus, you don't
393       need to install sshuttle on the remote  server,  and  there  are  never
394       sshuttle version conflicts between client and server.
395
396       Unlike most VPNs, sshuttle forwards sessions, not packets.  That is, it
397       uses kernel transparent proxying (iptables REDIRECT rules on Linux)  to
398       capture  outgoing TCP sessions, then creates entirely separate TCP ses‐
399       sions out to the original destination at the other end of the tunnel.
400
401       Packet-level forwarding (eg. using the tun/tap devices on Linux)  seems
402       elegant  at first, but it results in several problems, notably the 'tcp
403       over tcp' problem.  The tcp protocol depends fundamentally  on  packets
404       being dropped in order to implement its congestion control agorithm; if
405       you pass tcp packets through a tcp-based tunnel (such as ssh), the  in‐
406       ner  tcp  packets  will never be dropped, and so the inner tcp stream's
407       congestion control will be completely broken, and performance  will  be
408       terrible.   Thus,  packet-based VPNs (such as IPsec and openvpn) cannot
409       use tcp-based encrypted streams like ssh or ssl, and have to  implement
410       their  own  encryption  from  scratch,  which is very complex and error
411       prone.
412
413       sshuttle's simplicity comes from the fact that it can  safely  use  the
414       existing  ssh encrypted tunnel without incurring a performance penalty.
415       It does this by letting the client-side kernel manage the incoming  tcp
416       stream,  and  the  server-side  kernel  manage the outgoing tcp stream;
417       there is no need for congestion control to be shared  between  the  two
418       separate streams, so a tcp-based tunnel is fine.
419
420       SEE ALSO:
421          ssh(1), python(1)
422

AUTHOR

424       Brian May
425
427       2022, Brian May
428
429
430
431
4321.1                              Jul 30, 2022                      SSHUTTLE(1)
Impressum