1SSHUTTLE(1) sshuttle SSHUTTLE(1)
2
6 sshuttle - sshuttle documentation
7
9 sshuttle [options] [-r [username@]sshserver[:port]] <subnets ...>
10
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 To work, you must have root access on the local machine, but you can
17 have a normal account on the server.
18 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 If run on a router, sshuttle can forward traffic for your entire subnet
24 to the VPN.
25
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 --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 -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 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 -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 -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 --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 --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 --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 --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 -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 -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 -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 -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 -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 --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 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 --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 --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 -D, --daemon
170 Automatically fork into the background after connecting to the
171 remote server. Implies --syslog.
172 --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 --pidfile=<pidfilename>
178 when using --daemon, save sshuttle's pid to pidfilename. The
179 default is sshuttle.pid in the current directory.
180 --disable-ipv6
182 If using tproxy or pf methods, this will disable IPv6 support.
183 --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 --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 --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 --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 --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 --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 --version
218 Print program version.
219
221 All the options described above can optionally be specified in a con‐
222 figuration file.
223 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 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 Arguments read from a file must be one per line, as shown below:
235 value
237 --option1
238 value1
239 --option2
240 value2
241
243 Test locally by proxying all local connections, without using ssh:
244 $ sshuttle -v 0/0
246 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 Test connection to a remote server, with automatic hostname and subnet
267 guessing:
268 $ sshuttle -vNHr example.org
270 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 Run sshuttle with a /etc/sshuttle.conf configuration file:
290 $ sshuttle @/etc/sshuttle.conf
292 Use the options defined in /etc/sshuttle.conf but be more verbose:
294 $ sshuttle @/etc/sshuttle.conf -vvv
296 Override the remote server defined in /etc/sshuttle.conf:
298 $ sshuttle @/etc/sshuttle.conf -r otheruser@test.example.com
300 Example configuration file:
302 192.168.0.0/16
304 --remote
305 user@example.com
306
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 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 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 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 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 SEE ALSO:
342 ssh(1), python(1)
343
345 Brian May
346
348 2020, Brian May
3491.0 Aug 30, 2020 SSHUTTLE(1)