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

CONFIGURATION FILE

240       All the options described above can optionally be specified in  a  con‐
241       figuration file.
242
243       To  run sshuttle with options defined in, e.g., /etc/sshuttle.conf just
244       pass  the  path  to  the  file  preceded  by  the  @  character,   e.g.
245       @/etc/sshuttle.conf.
246
247       When running sshuttle with options defined in a configuration file, op‐
248       tions can still be passed via the command line in addition to  what  is
249       defined  in the file. If a given option is defined both in the file and
250       in the command line, the value in the command  line  will  take  prece‐
251       dence.
252
253       Arguments read from a file must be one per line, as shown below:
254
255          value
256          --option1
257          value1
258          --option2
259          value2
260

EXAMPLES

262       Test locally by proxying all local connections, without using ssh:
263
264          $ sshuttle -v 0/0
265
266          Starting sshuttle proxy.
267          Listening on ('0.0.0.0', 12300).
268          [local sudo] Password:
269          firewall manager ready.
270          c : connecting to server...
271           s: available routes:
272           s:   192.168.42.0/24
273          c : connected.
274          firewall manager: starting transproxy.
275          c : Accept: 192.168.42.106:50035 -> 192.168.42.121:139.
276          c : Accept: 192.168.42.121:47523 -> 77.141.99.22:443.
277              ...etc...
278          ^C
279          firewall manager: undoing changes.
280          KeyboardInterrupt
281          c : Keyboard interrupt: exiting.
282          c : SW#8:192.168.42.121:47523: deleting
283          c : SW#6:192.168.42.106:50035: deleting
284
285       Test  connection to a remote server, with automatic hostname and subnet
286       guessing:
287
288          $ sshuttle -vNHr example.org
289
290          Starting sshuttle proxy.
291          Listening on ('0.0.0.0', 12300).
292          firewall manager ready.
293          c : connecting to server...
294           s: available routes:
295           s:   77.141.99.0/24
296          c : connected.
297          c : seed_hosts: []
298          firewall manager: starting transproxy.
299          hostwatch: Found: testbox1: 1.2.3.4
300          hostwatch: Found: mytest2: 5.6.7.8
301          hostwatch: Found: domaincontroller: 99.1.2.3
302          c : Accept: 192.168.42.121:60554 -> 77.141.99.22:22.
303          ^C
304          firewall manager: undoing changes.
305          c : Keyboard interrupt: exiting.
306          c : SW#6:192.168.42.121:60554: deleting
307
308       Run sshuttle with a /etc/sshuttle.conf configuration file:
309
310          $ sshuttle @/etc/sshuttle.conf
311
312       Use the options defined in /etc/sshuttle.conf but be more verbose:
313
314          $ sshuttle @/etc/sshuttle.conf -vvv
315
316       Override the remote server defined in /etc/sshuttle.conf:
317
318          $ sshuttle @/etc/sshuttle.conf -r otheruser@test.example.com
319
320       Example configuration file:
321
322          192.168.0.0/16
323          --remote
324          user@example.com
325

DISCUSSION

327       When it starts, sshuttle creates an ssh session to the server specified
328       by  the -r option.  If -r is omitted, it will start both its client and
329       server locally, which is sometimes useful for testing.
330
331       After connecting to the remote server, sshuttle  uploads  its  (python)
332       source  code  to the remote end and executes it there.  Thus, you don't
333       need to install sshuttle on the remote  server,  and  there  are  never
334       sshuttle version conflicts between client and server.
335
336       Unlike most VPNs, sshuttle forwards sessions, not packets.  That is, it
337       uses kernel transparent proxying (iptables REDIRECT rules on Linux)  to
338       capture  outgoing TCP sessions, then creates entirely separate TCP ses‐
339       sions out to the original destination at the other end of the tunnel.
340
341       Packet-level forwarding (eg. using the tun/tap devices on Linux)  seems
342       elegant  at first, but it results in several problems, notably the 'tcp
343       over tcp' problem.  The tcp protocol depends fundamentally  on  packets
344       being dropped in order to implement its congestion control agorithm; if
345       you pass tcp packets through a tcp-based tunnel (such as ssh), the  in‐
346       ner  tcp  packets  will never be dropped, and so the inner tcp stream's
347       congestion control will be completely broken, and performance  will  be
348       terrible.   Thus,  packet-based VPNs (such as IPsec and openvpn) cannot
349       use tcp-based encrypted streams like ssh or ssl, and have to  implement
350       their  own  encryption  from  scratch,  which is very complex and error
351       prone.
352
353       sshuttle's simplicity comes from the fact that it can  safely  use  the
354       existing  ssh encrypted tunnel without incurring a performance penalty.
355       It does this by letting the client-side kernel manage the incoming  tcp
356       stream,  and  the  server-side  kernel  manage the outgoing tcp stream;
357       there is no need for congestion control to be shared  between  the  two
358       separate streams, so a tcp-based tunnel is fine.
359
360       SEE ALSO:
361          ssh(1), python(1)
362

AUTHOR

364       Brian May
365
367       2021, Brian May
368
369
370
371
3721.0                              Jan 27, 2021                      SSHUTTLE(1)
Impressum