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 --python
86 Specify the name/path of the remote python interpreter. The
87 default is just python, which means to use the default python
88 interpreter on the remote system's PATH.
89 -r, --remote=[username@]sshserver[:port]
91 The remote hostname and optional username and ssh port number to
92 use for connecting to the remote server. For example, exam‐
93 ple.com, testuser@example.com, testuser@example.com:2222, or
94 example.com:2244.
95 -x, --exclude=subnet
97 Explicitly exclude this subnet from forwarding. The format of
98 this option is the same as the <subnets> option. To exclude
99 more than one subnet, specify the -x option more than once. You
100 can say something like 0/0 -x 1.2.3.0/24 to forward everything
101 except the local subnet over the VPN, for example.
102 -X, --exclude-from=file
104 Exclude the subnets specified in a file, one subnet per line.
105 Useful when you have lots of subnets to exclude.
106 -v, --verbose
108 Print more information about the session. This option can be
109 used more than once for increased verbosity. By default, sshut‐
110 tle prints only error messages.
111 -e, --ssh-cmd
113 The command to use to connect to the remote server. The default
114 is just ssh. Use this if your ssh client is in a non-standard
115 location or you want to provide extra options to the ssh com‐
116 mand, for example, -e 'ssh -v'.
117 --seed-hosts
119 A comma-separated list of hostnames to use to initialize the
120 --auto-hosts scan algorithm. --auto-hosts does things like poll
121 local SMB servers for lists of local hostnames, but can speed
122 things up if you use this option to give it a few names to start
123 from.
124 If this option is used without --auto-hosts, then the listed
126 hostnames will be scanned and added, but no further hostnames
127 will be added.
128 --no-latency-control
130 Sacrifice latency to improve bandwidth benchmarks. ssh uses
131 really big socket buffers, which can overload the connection if
132 you start doing large file transfers, thus making all your other
133 sessions inside the same tunnel go slowly. Normally, sshuttle
134 tries to avoid this problem using a "fullness check" that allows
135 only a certain amount of outstanding data to be buffered at a
136 time. But on high-bandwidth links, this can leave a lot of your
137 bandwidth underutilized. It also makes sshuttle seem slow in
138 bandwidth benchmarks (benchmarks rarely test ping latency, which
139 is what sshuttle is trying to control). This option disables
140 the latency control feature, maximizing bandwidth usage. Use at
141 your own risk.
142 -D, --daemon
144 Automatically fork into the background after connecting to the
145 remote server. Implies --syslog.
146 --syslog
148 after connecting, send all log messages to the syslog(3) service
149 instead of stderr. This is implicit if you use --daemon.
150 --pidfile=pidfilename
152 when using --daemon, save sshuttle's pid to pidfilename. The
153 default is sshuttle.pid in the current directory.
154 --disable-ipv6
156 If using tproxy or pf methods, this will disable IPv6 support.
157 --firewall
159 (internal use only) run the firewall manager. This is the only
160 part of sshuttle that must run as root. If you start sshuttle
161 as a non-root user, it will automatically run sudo or su to
162 start the firewall manager, but the core of sshuttle still runs
163 as a normal user.
164 --hostwatch
166 (internal use only) run the hostwatch daemon. This process runs
167 on the server side and collects hostnames for the --auto-hosts
168 option. Using this option by itself makes it a lot easier to
169 debug and test the --auto-hosts feature.
170
172 All the options described above can optionally be specified in a con‐
173 figuration file.
174 To run sshuttle with options defined in, e.g., /etc/ssshuttle.conf just
176 pass the path to the file preceded by the @ character, e.g.
177 @/etc/ssshuttle.conf.
178 When running sshuttle with options defined in a configuratio file,
180 options can still be passed via the command line in addition to what is
181 defined in the file. If a given option is defined both in the file and
182 in the command line, the value in the command line will take prece‐
183 dence.
184 Arguments read from a file must be one per line, as shown below:
186 value
188 --option1
189 value1
190 --option2
191 value2
192
194 Test locally by proxying all local connections, without using ssh:
195 $ sshuttle -v 0/0
197 Starting sshuttle proxy.
199 Listening on ('0.0.0.0', 12300).
200 [local sudo] Password:
201 firewall manager ready.
202 c : connecting to server...
203 s: available routes:
204 s: 192.168.42.0/24
205 c : connected.
206 firewall manager: starting transproxy.
207 c : Accept: 192.168.42.106:50035 -> 192.168.42.121:139.
208 c : Accept: 192.168.42.121:47523 -> 77.141.99.22:443.
209 ...etc...
210 ^C
211 firewall manager: undoing changes.
212 KeyboardInterrupt
213 c : Keyboard interrupt: exiting.
214 c : SW#8:192.168.42.121:47523: deleting
215 c : SW#6:192.168.42.106:50035: deleting
216 Test connection to a remote server, with automatic hostname and subnet
218 guessing:
219 $ sshuttle -vNHr example.org
221 Starting sshuttle proxy.
223 Listening on ('0.0.0.0', 12300).
224 firewall manager ready.
225 c : connecting to server...
226 s: available routes:
227 s: 77.141.99.0/24
228 c : connected.
229 c : seed_hosts: []
230 firewall manager: starting transproxy.
231 hostwatch: Found: testbox1: 1.2.3.4
232 hostwatch: Found: mytest2: 5.6.7.8
233 hostwatch: Found: domaincontroller: 99.1.2.3
234 c : Accept: 192.168.42.121:60554 -> 77.141.99.22:22.
235 ^C
236 firewall manager: undoing changes.
237 c : Keyboard interrupt: exiting.
238 c : SW#6:192.168.42.121:60554: deleting
239 Run sshuttle with a /etc/sshuttle.conf configuration file:
241 $ sshuttle @/etc/sshuttle.conf
243 Use the options defined in /etc/sshuttle.conf but be more verbose:
245 $ sshuttle @/etc/sshuttle.conf -vvv
247 Override the remote server defined in /etc/sshuttle.conf:
249 $ sshuttle @/etc/sshuttle.conf -r otheruser@test.example.com
251 Example configuration file:
253 192.168.0.0/16
255 --remote
256 user@example.com
257
259 When it starts, sshuttle creates an ssh session to the server specified
260 by the -r option. If -r is omitted, it will start both its client and
261 server locally, which is sometimes useful for testing.
262 After connecting to the remote server, sshuttle uploads its (python)
264 source code to the remote end and executes it there. Thus, you don't
265 need to install sshuttle on the remote server, and there are never
266 sshuttle version conflicts between client and server.
267 Unlike most VPNs, sshuttle forwards sessions, not packets. That is, it
269 uses kernel transparent proxying (iptables REDIRECT rules on Linux) to
270 capture outgoing TCP sessions, then creates entirely separate TCP ses‐
271 sions out to the original destination at the other end of the tunnel.
272 Packet-level forwarding (eg. using the tun/tap devices on Linux) seems
274 elegant at first, but it results in several problems, notably the 'tcp
275 over tcp' problem. The tcp protocol depends fundamentally on packets
276 being dropped in order to implement its congestion control agorithm; if
277 you pass tcp packets through a tcp-based tunnel (such as ssh), the
278 inner tcp packets will never be dropped, and so the inner tcp stream's
279 congestion control will be completely broken, and performance will be
280 terrible. Thus, packet-based VPNs (such as IPsec and openvpn) cannot
281 use tcp-based encrypted streams like ssh or ssl, and have to implement
282 their own encryption from scratch, which is very complex and error
283 prone.
284 sshuttle's simplicity comes from the fact that it can safely use the
286 existing ssh encrypted tunnel without incurring a performance penalty.
287 It does this by letting the client-side kernel manage the incoming tcp
288 stream, and the server-side kernel manage the outgoing tcp stream;
289 there is no need for congestion control to be shared between the two
290 separate streams, so a tcp-based tunnel is fine.
291 SEE ALSO:
293 ssh(1), python(1)
294
296 Brian May
297
299 2016, Brian May
3000.78 Jul 15, 2018 SSHUTTLE(1)