Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 190 lines (144 sloc) 8.159 kB
c339959 @apenwarr README/sshuttle.1: add a note about the MacOS kernel bug.
apenwarr authored
1
2 WARNING:
3 On MacOS 10.6 (at least up to 10.6.6), your network will
4 stop responding about 10 minutes after the first time you
5 start sshuttle, because of a MacOS kernel bug relating to
6 arp and the net.inet.ip.scopedroute sysctl. To fix it,
7 just switch your wireless off and on. Sshuttle makes the
8 kernel setting it changes permanent, so this won't happen
9 again, even after a reboot.
10
11
33a7305 @apenwarr README: update to use real markdown-style headings.
apenwarr authored
12 sshuttle: where transparent proxy meets VPN meets ssh
13 =====================================================
616d068 @apenwarr Add a README file based on my blog entry.
apenwarr authored
14
15 As far as I know, sshuttle is the only program that solves the following
16 common case:
17
6e336c0 @apenwarr README: remove the note about MacOS not working. It works now!
apenwarr authored
18 - Your client machine (or router) is Linux, FreeBSD, or MacOS.
4a93d33 @apenwarr README: fix some formatting for easier text-mode readability.
apenwarr authored
19
20 - You have access to a remote network via ssh.
21
22 - You don't necessarily have admin access on the remote network.
23
24 - The remote network has no VPN, or only stupid/complex VPN
25 protocols (IPsec, PPTP, etc). Or maybe you <i>are</i> the
26 admin and you just got frustrated with the awful state of
27 VPN tools.
28
29 - You don't want to create an ssh port forward for every
30 single host/port on the remote network.
31
32 - You hate openssh's port forwarding because it's randomly
33 slow and/or stupid.
34
35 - You can't use openssh's PermitTunnel feature because
36 it's disabled by default on openssh servers; plus it does
37 TCP-over-TCP, which has terrible performance (see below).
403a088 @apenwarr README: add information about which iptables modules are needed.
apenwarr authored
38
39
40 Prerequisites
41 -------------
42
0cdd72c @apenwarr README: clarify that the server doesn't need Linux or iptables.
apenwarr authored
43 - sudo, su, or logged in as root on your client machine.
44 (The server doesn't need admin access.)
403a088 @apenwarr README: add information about which iptables modules are needed.
apenwarr authored
45
8fe3592 @apenwarr Don't require the remote server to have sshuttle installed.
apenwarr authored
46 - If you use Linux on your client machine:
47 iptables installed on the client, including at
403a088 @apenwarr README: add information about which iptables modules are needed.
apenwarr authored
48 least the iptables DNAT, REDIRECT, and ttl modules.
8fe3592 @apenwarr Don't require the remote server to have sshuttle installed.
apenwarr authored
49 These are installed by default on most Linux distributions.
0cdd72c @apenwarr README: clarify that the server doesn't need Linux or iptables.
apenwarr authored
50 (The server doesn't need iptables and doesn't need to be
51 Linux.)
8fe3592 @apenwarr Don't require the remote server to have sshuttle installed.
apenwarr authored
52
53 - If you use MacOS or BSD on your client machine:
54 Your kernel needs to be compiled with IPFIREWALL_FORWARD
55 (MacOS has this by default) and you need to have ipfw
56 available. (The server doesn't need to be MacOS or BSD.)
616d068 @apenwarr Add a README file based on my blog entry.
apenwarr authored
57
33a7305 @apenwarr README: update to use real markdown-style headings.
apenwarr authored
58
59 This is how you use it:
60 -----------------------
616d068 @apenwarr Add a README file based on my blog entry.
apenwarr authored
61
4a93d33 @apenwarr README: fix some formatting for easier text-mode readability.
apenwarr authored
62 - <tt>git clone git://github.com/apenwarr/sshuttle</tt>
6bdb951 @apenwarr README: fix some out-of-date system requirements stuff.
apenwarr authored
63 on your client machine. You'll need root or sudo
64 access, and python needs to be installed.
4a93d33 @apenwarr README: fix some formatting for easier text-mode readability.
apenwarr authored
65
da2c627 @leto Add some friendly info to the README
leto authored
66 - The most basic use of sshuttle looks like:
67 <tt>./sshuttle -r username@sshserver 0.0.0.0/0 -vv</tt>
68
69 - There is a shortcut for 0.0.0.0/0 for those that value
70 their wrists
71 <tt>./sshuttle -r username@sshserver 0/0 -vv</tt>
72
73 - If you would also like your DNS queries to be proxied
74 through the DNS server of the server you are connect to:
15e26d2 @grissiom README.md: fix little bug
grissiom authored
75 <tt>./sshuttle --dns -vvr username@sshserver 0/0</tt>
da2c627 @leto Add some friendly info to the README
leto authored
76
77 The above is probably what you want to use to prevent
78 local network attacks such as Firesheep and friends.
616d068 @apenwarr Add a README file based on my blog entry.
apenwarr authored
79
bcf1892 @apenwarr Make password prompting more clear.
apenwarr authored
80 (You may be prompted for one or more passwords; first, the
81 local password to become root using either sudo or su, and
82 then the remote ssh password. Or you might have sudo and ssh set
83 up to not require passwords, in which case you won't be
84 prompted at all.)
85
616d068 @apenwarr Add a README file based on my blog entry.
apenwarr authored
86 That's it! Now your local machine can access the remote network as if you
bcf1892 @apenwarr Make password prompting more clear.
apenwarr authored
87 were right there. And if your "client" machine is a router, everyone on
616d068 @apenwarr Add a README file based on my blog entry.
apenwarr authored
88 your local network can make connections to your remote network.
89
8fe3592 @apenwarr Don't require the remote server to have sshuttle installed.
apenwarr authored
90 You don't need to install sshuttle on the remote server;
91 the remote server just needs to have python available.
92 sshuttle will automatically upload and run its source code
93 to the remote python interpreter.
94
616d068 @apenwarr Add a README file based on my blog entry.
apenwarr authored
95 This creates a transparent proxy server on your local machine for all IP
96 addresses that match 0.0.0.0/0. (You can use more specific IP addresses if
97 you want; use any number of IP addresses or subnets to change which
98 addresses get proxied. Using 0.0.0.0/0 proxies <i>everything</i>, which is
99 interesting if you don't trust the people on your local network.)
100
101 Any TCP session you initiate to one of the proxied IP addresses will be
102 captured by sshuttle and sent over an ssh session to the remote copy of
103 sshuttle, which will then regenerate the connection on that end, and funnel
104 the data back and forth through ssh.
105
106 Fun, right? A poor man's instant VPN, and you don't even have to have
107 admin access on the server.
108
33a7305 @apenwarr README: update to use real markdown-style headings.
apenwarr authored
109
110 Theory of Operation
111 -------------------
616d068 @apenwarr Add a README file based on my blog entry.
apenwarr authored
112
113 sshuttle is not exactly a VPN, and not exactly port forwarding. It's kind
114 of both, and kind of neither.
115
116 It's like a VPN, since it can forward every port on an entire network, not
117 just ports you specify. Conveniently, it lets you use the "real" IP
118 addresses of each host rather than faking port numbers on localhost.
119
120 On the other hand, the way it *works* is more like ssh port forwarding than
121 a VPN. Normally, a VPN forwards your data one packet at a time, and
122 doesn't care about individual connections; ie. it's "stateless" with respect
123 to the traffic. sshuttle is the opposite of stateless; it tracks every
124 single connection.
125
126 You could compare sshuttle to something like the old <a
127 href="http://en.wikipedia.org/wiki/Slirp">Slirp</a> program, which was a
128 userspace TCP/IP implementation that did something similar. But it
129 operated on a packet-by-packet basis on the client side, reassembling the
130 packets on the server side. That worked okay back in the "real live serial
131 port" days, because serial ports had predictable latency and buffering.
132
133 But you can't safely just forward TCP packets over a TCP session (like ssh),
134 because TCP's performance depends fundamentally on packet loss; it
135 <i>must</i> experience packet loss in order to know when to slow down! At
136 the same time, the outer TCP session (ssh, in this case) is a reliable
137 transport, which means that what you forward through the tunnel <i>never</i>
138 experiences packet loss. The ssh session itself experiences packet loss, of
139 course, but TCP fixes it up and ssh (and thus you) never know the
140 difference. But neither does your inner TCP session, and extremely screwy
141 performance ensues.
142
143 sshuttle assembles the TCP stream locally, multiplexes it statefully over
144 an ssh session, and disassembles it back into packets at the other end. So
145 it never ends up doing TCP-over-TCP. It's just data-over-TCP, which is
146 safe.
147
33a7305 @apenwarr README: update to use real markdown-style headings.
apenwarr authored
148
149 Useless Trivia
150 --------------
616d068 @apenwarr Add a README file based on my blog entry.
apenwarr authored
151
152 Back in 1998 (12 years ago! Yikes!), I released the first version of <a
153 href="http://alumnit.ca/wiki/?TunnelVisionReadMe">Tunnel Vision</a>, a
154 semi-intelligent VPN client for Linux. Unfortunately, I made two big mistakes:
155 I implemented the key exchange myself (oops), and I ended up doing
156 TCP-over-TCP (double oops). The resulting program worked okay - and people
157 used it for years - but the performance was always a bit funny. And nobody
158 ever found any security flaws in my key exchange, either, but that doesn't
159 mean anything. :)
160
161 The same year, dcoombs and I also released Fast Forward, a proxy server
162 supporting transparent proxying. Among other things, we used it for
163 automatically splitting traffic across more than one Internet connection (a
164 tool we called "Double Vision").
165
166 I was still in university at the time. A couple years after that, one of my
167 professors was working with some graduate students on the technology that
168 would eventually become <a href="http://www.slipstream.com/">Slipstream
169 Internet Acceleration</a>. He asked me to do a contract for him to build an
170 initial prototype of a transparent proxy server for mobile networks. The
171 idea was similar to sshuttle: if you reassemble and then disassemble the TCP
172 packets, you can reduce latency and improve performance vs. just forwarding
173 the packets over a plain VPN or mobile network. (It's unlikely that any of
174 my code has persisted in the Slipstream product today, but the concept is
175 still pretty cool. I'm still horrified that people use plain TCP on
176 complex mobile networks with crazily variable latency, for which it was
177 never really intended.)
178
179 That project I did for Slipstream was what first gave me the idea to merge
180 the concepts of Fast Forward, Double Vision, and Tunnel Vision into a single
181 program that was the best of all worlds. And here we are, at last, 10 years
182 later. You're welcome.
183
184 --
185 Avery Pennarun <apenwarr@gmail.com>
186
d435ed8 @apenwarr Created a googlegroups.com mailing list for sshuttle.
apenwarr authored
187 Mailing list:
188 Subscribe by sending a message to <sshuttle+subscribe@googlegroups.com>
189 List archives are at: http://groups.google.com/group/sshuttle
Something went wrong with that request. Please try again.