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 2.3 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|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, --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 twice if required, to provide both IPv4 and IPv6
61 addresses.
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, --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 -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 -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 -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 -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 --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 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 --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 -D, --daemon
163 Automatically fork into the background after connecting to the
164 remote server. Implies --syslog.
165 --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 --pidfile=pidfilename
171 when using --daemon, save sshuttle's pid to pidfilename. The
172 default is sshuttle.pid in the current directory.
173 --disable-ipv6
175 If using tproxy or pf methods, this will disable IPv6 support.
176 --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 --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 --version
191 Print program version.
192
194 All the options described above can optionally be specified in a con‐
195 figuration file.
196 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 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 Arguments read from a file must be one per line, as shown below:
208 value
210 --option1
211 value1
212 --option2
213 value2
214
216 Test locally by proxying all local connections, without using ssh:
217 $ sshuttle -v 0/0
219 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 Test connection to a remote server, with automatic hostname and subnet
240 guessing:
241 $ sshuttle -vNHr example.org
243 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 Run sshuttle with a /etc/sshuttle.conf configuration file:
263 $ sshuttle @/etc/sshuttle.conf
265 Use the options defined in /etc/sshuttle.conf but be more verbose:
267 $ sshuttle @/etc/sshuttle.conf -vvv
269 Override the remote server defined in /etc/sshuttle.conf:
271 $ sshuttle @/etc/sshuttle.conf -r otheruser@test.example.com
273 Example configuration file:
275 192.168.0.0/16
277 --remote
278 user@example.com
279
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 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 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 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 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 SEE ALSO:
315 ssh(1), python(1)
316
318 Brian May
319
321 2020, Brian May
3220.78 Jan 31, 2020 SSHUTTLE(1)