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

CONFIGURATION FILE

221       All  the  options described above can optionally be specified in a con‐
222       figuration file.
223
224       To run sshuttle with options defined in, e.g., /etc/sshuttle.conf  just
225       pass   the  path  to  the  file  preceded  by  the  @  character,  e.g.
226       @/etc/sshuttle.conf.
227
228       When running sshuttle with options defined  in  a  configuration  file,
229       options can still be passed via the command line in addition to what is
230       defined in the file. If a given option is defined both in the file  and
231       in  the  command  line,  the value in the command line will take prece‐
232       dence.
233
234       Arguments read from a file must be one per line, as shown below:
235
236          value
237          --option1
238          value1
239          --option2
240          value2
241

EXAMPLES

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

DISCUSSION

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

AUTHOR

345       Brian May
346
348       2020, Brian May
349
350
351
352
3531.0                              Aug 30, 2020                      SSHUTTLE(1)
Impressum