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.6 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. 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 --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 -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 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 -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 -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 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 --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 --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 --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 --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 -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 -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 -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 -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 -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 --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 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 --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 --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 -D, --daemon
181 Automatically fork into the background after connecting to the
182 remote server. Implies --syslog.
183 -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 --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 --pidfile=<pidfilename>
193 when using --daemon, save sshuttle's pid to pidfilename. The
194 default is sshuttle.pid in the current directory.
195 --disable-ipv6
197 Disable IPv6 support for methods that support it (nft, tproxy,
198 and pf).
199 --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 --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 --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 --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 --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 --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 -t, --tmark
234 Transproxy optional traffic mark with provided MARK value.
235 --version
237 Print program version.
238
240 All the options described above can optionally be specified in a con‐
241 figuration file.
242 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 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 Arguments read from a file must be one per line, as shown below:
254 value
256 --option1
257 value1
258 --option2
259 value2
260
262 Test locally by proxying all local connections, without using ssh:
263 $ sshuttle -v 0/0
265 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 Test connection to a remote server, with automatic hostname and subnet
286 guessing:
287 $ sshuttle -vNHr example.org
289 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 Run sshuttle with a /etc/sshuttle.conf configuration file:
309 $ sshuttle @/etc/sshuttle.conf
311 Use the options defined in /etc/sshuttle.conf but be more verbose:
313 $ sshuttle @/etc/sshuttle.conf -vvv
315 Override the remote server defined in /etc/sshuttle.conf:
317 $ sshuttle @/etc/sshuttle.conf -r otheruser@test.example.com
319 Example configuration file:
321 192.168.0.0/16
323 --remote
324 user@example.com
325
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 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 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 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 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 SEE ALSO:
361 ssh(1), python(1)
362
364 Brian May
365
367 2021, Brian May
3681.0 Jul 23, 2021 SSHUTTLE(1)