1 HTun: IP-over-HTTP tunnelling VPN network interface
2 ---------------------------------------------------
6 HTun is a tool to allow you to create a fully bidirectional IP VPN over an
7 HTTP proxy or just over port 80, allowing you to bypass restrictive firewalls
8 and use any service you desire.
10 HTun creates an point-to-point virtual IP network over HTTP by encapsulating
11 IP traffic into valid HTTP requests. The HTun server runs on a host with an
12 unrestricted Internet connection. It listens on a common webserver port (80 or
13 443) and accepts HTun client connections. The HTun client daemon runs from
14 within a restrictive network environment, communicating with the HTun server
18 Moshe Jacobson <moshe at runslinux dot net> and
19 Ola Nordström <ola at triblock dot com> under
20 Russell Clark <rjc at cc dot gatech dot edu>.
25 Compiling HTun should be fairly straightforward:
29 cp htund /usr/local/bin
30 cp ../doc/htund.conf /etc
32 To compile with debug support, type "make debug" instead of "make all".
34 Debug support slows down the program, but provides the ability to log debug
35 statements to the logfile through use of the -d commandline option or the
36 "debug yes" config file option. You should use debug mode if you're trying to
40 CONFIGURING THE TUN DEVICE
41 --------------------------
42 HTun uses the Unversal TUN/TAP module (tun.o) available in the Linux kernel.
43 Therefore, you must enable the option in the kernel configuration under
44 "Network Device Support" --> "Universal TUN/TAP device driver support".
45 It is recommended that you compile it as a module rather than statically.
47 You must also create the TUN device file. You may call it whatever you want,
48 but for this example, we will assume you are creating it as /dev/net/tun. Use
49 the mknod command as follows to create the device with major number 10 and
52 $ mknod /dev/net/tun c 10 200
54 Additionally, to cause the device driver to be automatically loaded on
55 request, you must place the following line into your /etc/modules.conf:
57 alias char-major-10-200 tun
59 Once you have made that modification, run depmod -a to reconfigure the module
65 All HTun options can be set from the configuration file. The config file has
72 client- or server-specific options
75 The valid options are as follows. The required options are marked with an
76 asterisk (*), and next to each option, the default value, if any, is shown in
80 logfile {filename} [logging turned off]
81 This is the logfile to which HTun writes errors and information. It is
82 highly suggested that you enable a logfile so that in case of an
83 error, you may determine the cause.
84 * tunfile {filename} []
85 This is the name of the tun device file you created earlier (see the
86 CONFIGURING THE TUN DEVICE section).
88 This tells HTun whether or not to log debug information into its
89 logfile. This is only useful for extreme debugging circumstances, and
90 produces a lot of output. However, it may help someone out there :)
93 do_routing [yes|no] [no]
94 When do_routing is set to yes, HTun modifies your route table so that
95 your default gateway becomes the HTun server, and all Internet-bound
96 data is automatically sent through the HTun interface. The route
97 tables are automatically restored when HTun is killed cleanly.
98 This is usually desirable, as it works well in most circumstances.
100 This option is a bit strange, but it is here due to the fact that HTun
101 came about as a research project. We developed two protocols, one
102 half-duplex (protocol 1) and one full-duplex (protocol 2).
103 The half-duplex protocol can achieve better response times, but is
104 more erratic, especially inbound. The full-duplex protocol is *very*
105 consistent with response times, but they are a bit higher, generally.
106 My suggestion is: start with protocol 2 (make sure you set
107 secondary_server_port as well, in this case). If it doesn't work, then
108 go back to protocol 1.
109 * proxy_ip [dotted.ip.address | hostname] []
110 This is the IP address or hostname of your web proxy server through
111 which you are tunneling. It must be on your local subnet. If not, you
112 must manually add a static host route entry in your routing table so
113 that you may route to it without going through the HTun interface. If
114 you are not using a web proxy server, and only wish to tunnel over
115 HTTP on port 80 (communicating directly with the server), place the
116 server's IP address here.
117 * proxy_port [port] []
118 This is the port on which your proxy server listens for requests. For
119 the squid proxy server, this is usually 3128. For many other proxy
120 servers, it can be 8000. Ask your system administrator for a more
122 proxy_user [username]
123 This is the username by which you wish to authenticate yourself on the
124 proxy server. This is only necessary if your proxy server requires
125 authentication. If it does not, you should not insert this line into
126 the config file, as it creates extra HTTP overhead to support it.
127 proxy_pass [password]
128 This is the password for the user given in proxy_user, by which you
129 wish to authenticate yourself on the proxy server. Although it may be
130 true that this password contains a space, HTun does not support
131 passwords with whitespace in them. If you do have whitespace in your
132 password, you will need to change the password to be able to use it
133 with HTun. This option is only necessary if your proxy server requires
134 authentication. If it does not, you should not insert this line into
135 the config file, as it creates extra HTTP overhead to support it.
136 * server_ip [dotted.ip.address | hostname] []
137 This is the real IP address or hostname of the HTun server machine.
138 This is the address sent to the proxy in all requests, so the proxy
139 must be able to access it.
140 * server_port [port] []
141 This is the port on which the HTun server daemon is listening.
142 Usually, the server will be listening on port 80, 8080, or 8000, as
143 the goal is to have the HTun server seem like a webserver.
144 * secondary_server_port [port] []
145 This is only required if you are using protocol 2. Because the
146 protocol is full duplex, the HTun client must open two channels to
147 different ports on the server (If it attempts to open two connections
148 to the same port, many proxy servers will interleave the requests into
149 one connection, rendering the connection useless). Usually, the
150 secondary port will be something like 8080 or 8000, depending on what
151 the proxy server allows access to.
152 * if_name [network device name] []
153 Because the client must have a unique identifier to give to the
154 server, it uses the MAC address of a physical Ethernet interface,
155 whose name you must provide here. eth0 usually works.
156 * iprange [network/maskbits] []
157 This tells the HTun client what IP addresses it may choose from when
158 picking an address for its virtual point-to-point interface. You must
159 provide a range of IP addresses so that the server can negotiate an
160 address that it is not using either. For example, if you are not using
161 the 10.*.*.* network, you should place 10.0.0.0/8 as your iprange. If
162 you're not using 192.168.*.*, you should place 192.168.0.0/16 there.
163 You may also have more than one iprange statement, for maximum
166 The following options are only for those who wish to tinker, and need not be
167 touched otherwise. However, the ones marked with a * must be present in the
170 * max_poll_interval [seconds] []
171 Only used with protocol 1. Protocol 1 involves regular polling of the
172 server to determine if the server as any data to return to the client.
173 Polling becomes less and less frequent as more and more time passes
174 without sending or receiving data. To place an upper bound on the
175 number of seconds between polls to the server, set max_poll_interval.
176 30 seconds is a reasonable value here.
177 * min_poll_interval_msec [msec]
178 Only used with Protocol 1. This is the number of milliseconds that the
179 client should wait before the first poll to the server. A lower value
180 here will lead to lower latency, but more overhead. Experiment to see
181 what you think is best. I suggest 200 as a starting point.
182 * poll_backoff_rate [integer]
183 Only used with protocol 1. This indicates the number of times that
184 protocol 1 should poll at each time interval, thus determining how
185 fast it backs off in terms of poll frequency. Higher numbers here
186 cause a slower backoff, but much more overhead in general. values from
187 1 to 3 are reasonable.
189 Only used with protocol 2. Protocol 2 uses two channels, one for
190 sending data, and the other for receiving. The receive channel simply
191 makes POST requests and waits for responses containing IP packets.
192 However, it won't wait for data forever, because perhaps there was a
193 problem that it didn't know about. Therefore, it is best that the
194 client make a new poll request on the receive channel every ack_wait
197 The client will try the initial connection to the server this many
198 times before giving up.
200 In the event of a disconnection from the server, the client will try
201 reconnecting to the server this many times before giving up.
202 * reconnect_sleep_sec 30
203 How many seconds the client should wait between reconnect retries.
204 * channel_2_idle_allow 30
205 The maximum number of seconds we'll allow the server to sit idle
206 before responding to the client request, in proto 2 channel 2.
207 Setting this higher cuts down on unnecessary chatter over the network,
208 but your proxy may time out waiting for the server to respond if you
209 set it too high. Experiment to see what your proxy will allow for.
212 Server Options (all are mandatory):
213 max_clients [integer]
214 Maximum number of clients that may be connected to the server at any
217 secondary_server_port [port]
218 The server must listen on two ports for protocol 2 to operate. Set
219 these two options to different values. Suggested ports to choose from
220 are 80, 8000, and 8080.
221 iprange [network/maskbits]
222 This tells the HTun server what IP addresses it may choose from when
223 picking an address for its virtual point-to-point interface. You must
224 provide a range of IP addresses so that the client can negotiate an
225 address that it is not using either. For example, if you are not using
226 the 10.*.*.* network, you should place 10.0.0.0/8 as your iprange. If
227 you're not using 192.168.*.*, you should place 192.168.0.0/16 there.
228 You may also have more than one iprange statement, for maximum
230 redirect_host [hostname]
232 These two directives together tell HTun where to redirect non-HTun
233 requests received by the HTun server. The idea is that HTun will be
234 pretending to be a webserver, so if someone wants to find out what all
235 this proxy traffic is all about, they will visit the HTun server with
236 their web browser, and HTun will invisibly redirect their request to a
237 legitimate web server, and proxy the response back to them, so they
238 are led to believe that the HTun server is a legitimate webserver.
239 The redirect_host would be something of the form "www.microsoft.com".
240 The port is the port on which the remote webserver is running
241 (usually, this would be port 80)
243 The following options are for expert users only. You need not mess with
247 clidata_timeout [seconds]
248 If a client does not close the communication channel cleanly, its
249 state data will be removed from the server after clidata_timeout
250 seconds. This should generally be set high enough that if the client
251 disconnects from a network timeout or something, that it will be able
252 to reconnect soon enough that its data will be maintained, and it can
253 pick up its dropped session without losing data or changing its IP
255 max_pending [integer]
256 Masimum number of pending clients that may be connected. These are
257 clients that aren't being serviced but are connected. I think. Just
258 leave it at some value like 40 and forget about it :)
259 idle_disconnect [seconds]
260 If a client connects but sends no request for idle_disconnect seconds,
261 it is disconnected by the server. This is only mandatory because we
262 haven't gotten around to making htun assign a default. 1800 seconds is
263 a good value to use here.
264 min_nack_delay [msec]
265 Protocol 1 only. The server will wait at least this many msec before
266 replying to the client POST requests. This causes server response data
267 to be more likely to be included in the immediate response from the
268 server to the client, causing lower response times. Set this too high
269 or too low and your response times will rise on average.
270 packet_count_threshold [integer]
271 Proto 1 only. If there are at least packet_count_threshold packets
272 queued to send to the client, the server will respond to the client
273 immediately. In Linux, the limit to the number of TCP packets that can
274 be sent without an ACK response is (I believe) about 6 or 7, so any
275 value above that will have no effect on TCP applications.
276 packet_max_interval [msec]
277 Proto 1 only. If there have been no packets queued to send to the
278 client in packet_max_interval msec, the server will send the response
279 to the client immediately.
281 Once you have finished writing your configuration file, move it to
282 /etc/htund.conf. If you wish to place it elsewhere, you will have to use the
283 -c option on the htun commandline.
288 The HTun daemon must be initalized as the server on the machine with an
289 unrestricted Internet connection, and as a client on the machines with
290 restricted connections. The mode is set in the config file, not on the
291 commandline. The simplest invocation of htund is without any parameters at
295 HTun daemon backgrounding . . .
298 But you may see all the commandline options available with htund -h:
302 Usage: htund [OPTION]...
304 -c cfgfile Use cfgfile as the config file.
305 -f Run htund in the foreground.
306 -v Print the htund version information and exit.
307 -h Print usage information and exit.
308 -t tunfile Use tunfile as the tun device file.
309 -l logfile Use logfile as the log output file.
310 Give - for stdout; this implies -f.
311 -r Do not alter default route.
312 -p port Set server port to given value
313 -o cOnfigtest only, check config syntax
315 All commandline options specified override the corresponding options in the
316 configuration file, if any.
321 Once the client and server have both been invoked, and are communicating
322 properly (see the log file for details), you should be able to see what IP
323 address you have been assigned and what address the server is using by typing
324 ifconfig at the commandline. Look for the tun0 interface, and that should
325 contain the IP addresses.
327 Sending a SIGUSR1 kill signal to the server will generate some interesting
328 statistics, such as information on the connected clients, to the logfile.
330 Sending a SIGHUP kill signal to the htund will cause it to reload its
331 configuration file and put the new changes into effect. For the client side,
332 this may mean reconnecting to the server. For the server side, the currently
333 connected clients may not see the changes until they reconnect.
335 Provided you have told htun to set up the default route ("do_routing yes" in
336 the config file), you should not have to worry about the IP addresses of the
337 virtual interface, though. You should just be able to begin using it.
339 You will also want to set up IP masquerading on the server side so that
340 traffic from the TUN interface will be routed properly. Otherwise, you will be
341 able to communicate only with the HTun server machine. Instructions on setting
342 up IP masquerading are beyond the scope of this document, and can be found at
343 documentation sites such as http://www.linuxdoc.org.
348 I welcome any suggestions, bug reports, etc. that you may have about HTun.
349 Just go to http://htun.runslinux.net/contact.html and submit them to us.
354 The latest version of HTun is always available at http://htun.runslinux.net