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 2.3 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|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, --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  twice  if  required, to provide both IPv4 and IPv6
61              addresses.
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, --remote=[username@]sshserver[:port]
110              The remote hostname and optional username and ssh port number to
111              use for connecting to the remote  server.   For  example,  exam‐
112              ple.com,   testuser@example.com,  testuser@example.com:2222,  or
113              example.com:2244.
114
115       -x, --exclude=subnet
116              Explicitly exclude this subnet from forwarding.  The  format  of
117              this  option  is  the  same as the <subnets> option.  To exclude
118              more than one subnet, specify the -x option more than once.  You
119              can  say  something like 0/0 -x 1.2.3.0/24 to forward everything
120              except the local subnet over the VPN, for example.
121
122       -X, --exclude-from=file
123              Exclude the subnets specified in a file, one  subnet  per  line.
124              Useful when you have lots of subnets to exclude.
125
126       -v, --verbose
127              Print  more  information  about the session.  This option can be
128              used more than once for increased verbosity.  By default, sshut‐
129              tle prints only error messages.
130
131       -e, --ssh-cmd
132              The  command to use to connect to the remote server. The default
133              is just ssh.  Use this if your ssh client is in  a  non-standard
134              location  or  you  want to provide extra options to the ssh com‐
135              mand, for example, -e 'ssh -v'.
136
137       --seed-hosts
138              A comma-separated list of hostnames to  use  to  initialize  the
139              --auto-hosts scan algorithm.  --auto-hosts does things like poll
140              local SMB servers for lists of local hostnames,  but  can  speed
141              things up if you use this option to give it a few names to start
142              from.
143
144              If this option is used without  --auto-hosts,  then  the  listed
145              hostnames  will  be  scanned and added, but no further hostnames
146              will be added.
147
148       --no-latency-control
149              Sacrifice latency to  improve  bandwidth  benchmarks.  ssh  uses
150              really  big socket buffers, which can overload the connection if
151              you start doing large file transfers, thus making all your other
152              sessions  inside  the  same tunnel go slowly. Normally, sshuttle
153              tries to avoid this problem using a "fullness check" that allows
154              only  a  certain  amount of outstanding data to be buffered at a
155              time.  But on high-bandwidth links, this can leave a lot of your
156              bandwidth  underutilized.   It  also makes sshuttle seem slow in
157              bandwidth benchmarks (benchmarks rarely test ping latency, which
158              is  what  sshuttle  is trying to control).  This option disables
159              the latency control feature, maximizing bandwidth usage.  Use at
160              your own risk.
161
162       -D, --daemon
163              Automatically  fork  into the background after connecting to the
164              remote server.  Implies --syslog.
165
166       --syslog
167              after connecting, send all log messages to the syslog(3) service
168              instead of stderr.  This is implicit if you use --daemon.
169
170       --pidfile=pidfilename
171              when  using  --daemon,  save sshuttle's pid to pidfilename.  The
172              default is sshuttle.pid in the current directory.
173
174       --disable-ipv6
175              If using tproxy or pf methods, this will disable IPv6 support.
176
177       --firewall
178              (internal use only) run the firewall manager.  This is the  only
179              part  of  sshuttle that must run as root.  If you start sshuttle
180              as a non-root user, it will automatically  run  sudo  or  su  to
181              start  the firewall manager, but the core of sshuttle still runs
182              as a normal user.
183
184       --hostwatch
185              (internal use only) run the hostwatch daemon.  This process runs
186              on  the  server side and collects hostnames for the --auto-hosts
187              option.  Using this option by itself makes it a  lot  easier  to
188              debug and test the --auto-hosts feature.
189
190       --version
191              Print program version.
192

CONFIGURATION FILE

194       All  the  options described above can optionally be specified in a con‐
195       figuration file.
196
197       To run sshuttle with options defined in, e.g., /etc/sshuttle.conf  just
198       pass   the  path  to  the  file  preceded  by  the  @  character,  e.g.
199       @/etc/sshuttle.conf.
200
201       When running sshuttle with options defined  in  a  configuration  file,
202       options can still be passed via the command line in addition to what is
203       defined in the file. If a given option is defined both in the file  and
204       in  the  command  line,  the value in the command line will take prece‐
205       dence.
206
207       Arguments read from a file must be one per line, as shown below:
208
209          value
210          --option1
211          value1
212          --option2
213          value2
214

EXAMPLES

216       Test locally by proxying all local connections, without using ssh:
217
218          $ sshuttle -v 0/0
219
220          Starting sshuttle proxy.
221          Listening on ('0.0.0.0', 12300).
222          [local sudo] Password:
223          firewall manager ready.
224          c : connecting to server...
225           s: available routes:
226           s:   192.168.42.0/24
227          c : connected.
228          firewall manager: starting transproxy.
229          c : Accept: 192.168.42.106:50035 -> 192.168.42.121:139.
230          c : Accept: 192.168.42.121:47523 -> 77.141.99.22:443.
231              ...etc...
232          ^C
233          firewall manager: undoing changes.
234          KeyboardInterrupt
235          c : Keyboard interrupt: exiting.
236          c : SW#8:192.168.42.121:47523: deleting
237          c : SW#6:192.168.42.106:50035: deleting
238
239       Test connection to a remote server, with automatic hostname and  subnet
240       guessing:
241
242          $ sshuttle -vNHr example.org
243
244          Starting sshuttle proxy.
245          Listening on ('0.0.0.0', 12300).
246          firewall manager ready.
247          c : connecting to server...
248           s: available routes:
249           s:   77.141.99.0/24
250          c : connected.
251          c : seed_hosts: []
252          firewall manager: starting transproxy.
253          hostwatch: Found: testbox1: 1.2.3.4
254          hostwatch: Found: mytest2: 5.6.7.8
255          hostwatch: Found: domaincontroller: 99.1.2.3
256          c : Accept: 192.168.42.121:60554 -> 77.141.99.22:22.
257          ^C
258          firewall manager: undoing changes.
259          c : Keyboard interrupt: exiting.
260          c : SW#6:192.168.42.121:60554: deleting
261
262       Run sshuttle with a /etc/sshuttle.conf configuration file:
263
264          $ sshuttle @/etc/sshuttle.conf
265
266       Use the options defined in /etc/sshuttle.conf but be more verbose:
267
268          $ sshuttle @/etc/sshuttle.conf -vvv
269
270       Override the remote server defined in /etc/sshuttle.conf:
271
272          $ sshuttle @/etc/sshuttle.conf -r otheruser@test.example.com
273
274       Example configuration file:
275
276          192.168.0.0/16
277          --remote
278          user@example.com
279

DISCUSSION

281       When it starts, sshuttle creates an ssh session to the server specified
282       by the -r option.  If -r is omitted, it will start both its client  and
283       server locally, which is sometimes useful for testing.
284
285       After  connecting  to  the remote server, sshuttle uploads its (python)
286       source code to the remote end and executes it there.  Thus,  you  don't
287       need  to  install  sshuttle  on  the remote server, and there are never
288       sshuttle version conflicts between client and server.
289
290       Unlike most VPNs, sshuttle forwards sessions, not packets.  That is, it
291       uses  kernel transparent proxying (iptables REDIRECT rules on Linux) to
292       capture outgoing TCP sessions, then creates entirely separate TCP  ses‐
293       sions out to the original destination at the other end of the tunnel.
294
295       Packet-level  forwarding (eg. using the tun/tap devices on Linux) seems
296       elegant at first, but it results in several problems, notably the  'tcp
297       over  tcp'  problem.  The tcp protocol depends fundamentally on packets
298       being dropped in order to implement its congestion control agorithm; if
299       you  pass  tcp  packets  through  a tcp-based tunnel (such as ssh), the
300       inner tcp packets will never be dropped, and so the inner tcp  stream's
301       congestion  control  will be completely broken, and performance will be
302       terrible.  Thus, packet-based VPNs (such as IPsec and  openvpn)  cannot
303       use  tcp-based encrypted streams like ssh or ssl, and have to implement
304       their own encryption from scratch, which  is  very  complex  and  error
305       prone.
306
307       sshuttle's  simplicity  comes  from the fact that it can safely use the
308       existing ssh encrypted tunnel without incurring a performance  penalty.
309       It  does this by letting the client-side kernel manage the incoming tcp
310       stream, and the server-side kernel  manage  the  outgoing  tcp  stream;
311       there  is  no  need for congestion control to be shared between the two
312       separate streams, so a tcp-based tunnel is fine.
313
314       SEE ALSO:
315          ssh(1), python(1)
316

AUTHOR

318       Brian May
319
321       2020, Brian May
322
323
324
325
3260.78                             Jan 31, 2020                      SSHUTTLE(1)
Impressum