ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/gvpe.texi
(Generate patch)

Comparing gvpe/doc/gvpe.texi (file contents):
Revision 1.1 by pcg, Wed Jan 18 13:15:07 2006 UTC vs.
Revision 1.5 by root, Tue Feb 15 13:31:22 2011 UTC

… …
18* gvpe: (gvpe). The GNU VPE Manual. 18* gvpe: (gvpe). The GNU VPE Manual.
19@end direntry 19@end direntry
20 20
21This is the info manual for vpe, the Virtual Private Ethernet daemon. 21This is the info manual for vpe, the Virtual Private Ethernet daemon.
22 22
23Copyright @copyright{} 2003-2005 Marc Lehmann <gvpe@@schmorp.de>. 23Copyright @copyright{} 2003-2008 Marc Lehmann <gvpe@@schmorp.de>.
24 24
25Permission is granted to make and distribute verbatim copies of this 25Permission is granted to make and distribute verbatim copies of this
26manual provided the copyright notice and this permission notice are 26manual provided the copyright notice and this permission notice are
27preserved on all copies. 27preserved on all copies.
28 28
… …
33 33
34@end ifinfo 34@end ifinfo
35 35
36@titlepage 36@titlepage
37@title gvpe Manual 37@title gvpe Manual
38@author Marc Lehmann (template by Ivo Timmermans and Guus Sliepen) 38@author Marc Lehmann
39 39
40@page 40@page
41@vskip 0pt plus 1filll 41@vskip 0pt plus 1filll
42@cindex copyright 42@cindex copyright
43 43
44Copyright @copyright{} 2003-2005 Marc Lehmann <gvpe@@schmorp.de>. 44Copyright @copyright{} 2003-2008 Marc Lehmann <gvpe@@schmorp.de>.
45 45
46Permission is granted to make and distribute verbatim copies of this 46Permission is granted to make and distribute verbatim copies of this
47manual provided the copyright notice and this permission notice are 47manual provided the copyright notice and this permission notice are
48preserved on all copies. 48preserved on all copies.
49 49
… …
98 98
99@itemize 99@itemize
100 100
101 101
102@item 102@item
103@b{
104@cindex Virtual
105Virtual} 103Virtual
106 104
107Virtual means that no physical network is created (of course), but a network is @emph{emulated} by creating multiple tunnels between the member nodes by encapsulating and sending data over another transport network. 105Virtual means that no physical network is created (of course), but a network is @emph{emulated} by creating multiple tunnels between the member nodes by encapsulating and sending data over another transport network.
108@refill 106@refill
109Usually the emulated network is a normal IP or Ethernet, and the transport network is the Internet. However, using a VPN system like GVPE to connect nodes over other untrusted networks such as Wireless LAN is not uncommon. 107Usually the emulated network is a normal IP or Ethernet, and the transport network is the Internet. However, using a VPN system like GVPE to connect nodes over other untrusted networks such as Wireless LAN is not uncommon.
110@refill 108@refill
111 109
112 110
113@item 111@item
114@b{
115@cindex Private
116Private} 112Private
117 113
118Private means that non-participating nodes cannot decode ("sniff)" nor inject ("spoof") packets. This means that nodes can be connected over untrusted networks such as the public Internet without fear of being eavesdropped while at the same time being able to trust data sent by other nodes. 114Private means that non-participating nodes cannot decode ("sniff)" nor inject ("spoof") packets. This means that nodes can be connected over untrusted networks such as the public Internet without fear of being eavesdropped while at the same time being able to trust data sent by other nodes.
119@refill 115@refill
120In the case of GVPE, even participating nodes cannot sniff packets send to other nodes or spoof packets as if sent from other nodes, so communications between any two nodes is private to those two nodes. 116In the case of GVPE, even participating nodes cannot sniff packets send to other nodes or spoof packets as if sent from other nodes, so communications between any two nodes is private to those two nodes.
121@refill 117@refill
122 118
123 119
124@item 120@item
125@b{
126@cindex Network
127Network} 121Network
128 122
129Network means that more than two parties can participate in the network, so for instance it's possible to connect multiple branches of a company into a single network. Many so-called "vpn" solutions only create point-to-point tunnels, which in turn can be used to build larger networks. 123Network means that more than two parties can participate in the network, so for instance it's possible to connect multiple branches of a company into a single network. Many so-called "VPN" solutions only create point-to-point tunnels, which in turn can be used to build larger networks.
130@refill 124@refill
131GVPE provides a true multi-point network in wich any number of nodes (at least a few dozen in practise, the theoretical limit is 4095 nodes) can participate. 125GVPE provides a true multi-point network in which any number of nodes (at least a few dozen in practise, the theoretical limit is 4095 nodes) can participate.
132@refill 126@refill
133@end itemize 127@end itemize
134 128
135 129
136 130
… …
139 133
140@itemize 134@itemize
141 135
142 136
143@item 137@item
144@b{SIMPLE DESIGN} 138SIMPLE DESIGN
145 139
146Cipher, HMAC algorithms and other key parameters must be selected at compile time - this makes it possible to only link in algorithms you actually need. It also makes the crypto part of the source very transparent and easy to inspect, and last not least this makes it possible to hardcode the layout of all packets into the binary. GVPE goes a step further and internally reserves blocks of the same length for all packets, which virtually removes all possibilities of buffer overflows, as there is only a single type of buffer and it's always of fixed length. 140Cipher, HMAC algorithms and other key parameters must be selected at compile time - this makes it possible to only link in algorithms you actually need. It also makes the crypto part of the source very transparent and easy to inspect, and last not least this makes it possible to hardcode the layout of all packets into the binary. GVPE goes a step further and internally reserves blocks of the same length for all packets, which virtually removes all possibilities of buffer overflows, as there is only a single type of buffer and it's always of fixed length.
147@refill 141@refill
148 142
149 143
150@item 144@item
151@b{EASY TO SETUP} 145EASY TO SETUP
152 146
153A few lines of config (the config file is shared unmodified between all hosts) and a single run of @t{gvpectrl} to generate the keys suffices to make it work. 147A few lines of config (the config file is shared unmodified between all hosts) and a single run of @t{gvpectrl} to generate the keys suffices to make it work.
154@refill 148@refill
155 149
156 150
157@item 151@item
158@b{MAC-BASED SECURITY} 152MAC-BASED SECURITY
159 153
160Since every host has it's own private key, other hosts cannot spoof traffic from this host. That makes it possible to filter packet by MAC address, e.g. to ensure that packets from a specific IP address come, in fact, from a specific host that is associated with that IP and not from another host. 154Since every host has it's own private key, other hosts cannot spoof traffic from this host. That makes it possible to filter packet by MAC address, e.g. to ensure that packets from a specific IP address come, in fact, from a specific host that is associated with that IP and not from another host.
161@refill 155@refill
162@end itemize 156@end itemize
163 157
164 158
165 159
166@section PROGRAMS 160@section PROGRAMS
167Vpe comes with two programs: one daemon (@t{gvpe}) and one control program (@t{gvpectrl}). 161Gvpe comes with two programs: one daemon (@t{gvpe}) and one control program (@t{gvpectrl}).
168@refill 162@refill
169 163
170 164
171@itemize 165@itemize
172 166
173 167
174@item 168@item
175@b{gvpectrl} 169gvpectrl
176 170
177Is used to generate the keys, check and give an overview of of the configuration and contorl the daemon (restarting etc.). 171This program is used to generate the keys, check and give an overview of of the configuration and to control the daemon (restarting etc.).
178@refill 172@refill
179 173
180 174
181@item 175@item
182@b{gvpe} 176gvpe
183 177
184Is the daemon used to establish and maintain connections to the other network members. It should be run on the gateway machine. 178This is the daemon used to establish and maintain connections to the other network nodes. It should be run on the gateway of each VPN subnet.
185@refill 179@refill
186@end itemize 180@end itemize
187 181
188 182
189 183
190@section COMPILETIME CONFIGURATION 184@section COMPILETIME CONFIGURATION
191Please have a look at the @t{gvpe.osdep(5)} manpage for platform-specific information. 185Please have a look at the @t{gvpe.osdep(5)} manpage for platform-specific information.
192@refill 186@refill
187Gvpe hardcodes most encryption parameters. While this reduces flexibility, it makes the program much simpler and helps making buffer overflows impossible under most circumstances.
188@refill
193Here are a few recipes for compiling your gvpe, showing the extremes (fast, small, insecure OR slow, large, more secure), between you should choose: 189Here are a few recipes for compiling your gvpe, showing the extremes (fast, small, insecure OR slow, large, more secure), between which you should choose:
194@refill 190@refill
195 191
196 192
197@subsection AS LOW PACKET OVERHEAD AS POSSIBLE 193@subsection AS LOW PACKET OVERHEAD AS POSSIBLE
198 194
199 195
200@example 196@example
201 ./configure --enable-hmac-length=4 --enable-rand-length=0 197 ./configure --enable-hmac-length=4 --enable-rand-length=0
202@end example 198@end example
203 199
204Minimize the header overhead of VPN packets (the above will result in only 4 bytes of overhead over the raw ethernet frame). This is a insecure configuration because a HMAC length of 4 makes collision attacks based on the birthday paradox easy, though. 200Minimize the header overhead of VPN packets (the above will result in only 4 bytes of overhead over the raw ethernet frame). This is a insecure configuration because a HMAC length of 4 makes collision attacks based on the birthday paradox pretty easy.
205@refill 201@refill
206 202
207 203
208@subsection MINIMIZE CPU TIME REQUIRED 204@subsection MINIMIZE CPU TIME REQUIRED
209 205
210 206
211@example 207@example
212 ./configure --enable-cipher=bf --enable-digest=md4 208 ./configure --enable-cipher=bf --enable-digest=md4
213@end example 209@end example
214 210
215Use the fastest cipher and digest algorithms currently available in gvpe. MD4 has been broken and is quite insecure, though. 211Use the fastest cipher and digest algorithms currently available in gvpe. MD4 has been broken and is quite insecure, though, so using another digest algorithm is recommended.
216@refill 212@refill
217 213
218 214
219@subsection MAXIMIZE SECURITY 215@subsection MAXIMIZE SECURITY
220 216
221 217
222@example 218@example
223 ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1 219 ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1
224@end example 220@end example
225 221
226This uses a 16 byte HMAC checksum to authenticate packets (I guess 8-12 would also be pretty secure ;) and will additionally prefix each packet with 8 bytes of random data. In the long run, people should move to SHA-224 and beyond, but support in openssl is missing as of writing this document. 222This uses a 16 byte HMAC checksum to authenticate packets (I guess 8-12 would also be pretty secure ;) and will additionally prefix each packet with 8 bytes of random data. In the long run, people should move to SHA-256 and beyond).
227@refill 223@refill
228In general, remember that AES-128 seems to be more secure and faster than AES-192 or AES-256, more randomness helps against sniffing and a longer HMAC helps against spoofing. MD4 is a fast digest, SHA1 or RIPEMD160 are better, and Blowfish is a fast cipher (and also quite secure). 224In general, remember that AES-128 seems to be as secure but faster than AES-192 or AES-256, more randomness helps against sniffing and a longer HMAC helps against spoofing. MD4 is a fast digest, SHA1, RIPEMD160, SHA256 are consecutively better, and Blowfish is a fast cipher (and also quite secure).
229@refill 225@refill
230 226
231 227
232@section HOW TO SET UP A SIMPLE VPN 228@section HOW TO SET UP A SIMPLE VPN
233In this section I will describe how to get a simple VPN consisting of three hosts up and running. 229In this section I will describe how to get a simple VPN consisting of three hosts up and running.
234@refill 230@refill
235 231
236 232
237@subsection STEP 1: configuration 233@subsection STEP 1: configuration
238First you have to create a daemon configuation file and put it into the configuration directory. This is usually @t{/etc/gvpe}, depending on how you configured gvpe, and can be overwritten using the @t{-c} commandline switch. 234First you have to create a daemon configuration file and put it into the configuration directory. This is usually @t{/etc/gvpe}, depending on how you configured gvpe, and can be overwritten using the @t{-c} command line switch.
239@refill 235@refill
240Put the following lines into @t{/etc/gvpe/gvpe.conf}: 236Put the following lines into @t{/etc/gvpe/gvpe.conf}:
241@refill 237@refill
242 238
243 239
244@example 240@example
245 udp-port = 50000 # the external port to listen on (configure your firewall) 241 udp-port = 50000 # the external port to listen on (configure your firewall)
246 mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts 242 mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts
247 ifname = vpn0 # the local network device name 243 ifname = vpn0 # the local network device name
248@end example
249 244
250
251
252@example
253 node = first # just a nickname 245 node = first # just a nickname
254 hostname = first.example.net # the DNS name or IP address of the host 246 hostname = first.example.net # the DNS name or IP address of the host
255@end example
256 247
257
258
259@example
260 node = second 248 node = second
261 hostname = 133.55.82.9 249 hostname = 133.55.82.9
262@end example
263 250
264
265
266@example
267 node = third 251 node = third
268 hostname = third.example.net 252 hostname = third.example.net
269@end example 253@end example
270 254
271The only other file neccessary if the @t{if-up} script that initializes the local ethernet interface. Put the following lines into @t{/etc/gvpe/if-up} and make it execute (@t{chmod 755 /etc/gvpe/if-up}): 255The only other file necessary is the @t{if-up} script that initializes the virtual ethernet interface on the local host. Put the following lines into @t{/etc/gvpe/if-up} and make it executable (@t{chmod 755 /etc/gvpe/if-up}):
272@refill 256@refill
273 257
274 258
275@example 259@example
276 #!/bin/sh 260 #!/bin/sh
… …
279 [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME 263 [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME
280 [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME 264 [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME
281 ip route add 10.0.0.0/16 dev $IFNAME 265 ip route add 10.0.0.0/16 dev $IFNAME
282@end example 266@end example
283 267
284This script will give each node a different IP address in the @t{10.0/16} network. The internal network (e.g. the @t{eth0} interface) should then be set to a subset of that network, e.g. @t{10.0.1.0/24} on node @t{first}, @t{10.0.2.0/24} on node @t{second}, and so on. 268This script will give each node a different IP address in the @t{10.0/16} network. The internal network (if gvpe runs on a router) should then be set to a subset of that network, e.g. @t{10.0.1.0/24} on node @t{first}, @t{10.0.2.0/24} on node @t{second}, and so on.
285@refill 269@refill
286By enabling routing on the gateway host that runs @t{gvpe} all nodes will be able to reach the other nodes. You can, of course, also use proxy arp or other means of pseudo-bridging (or even real briding), or (best) full routing - the choice is yours. 270By enabling routing on the gateway host that runs @t{gvpe} all nodes will be able to reach the other nodes. You can, of course, also use proxy ARP or other means of pseudo-bridging, or (best) full routing - the choice is yours.
287@refill 271@refill
288 272
289 273
290@subsection STEP 2: create the RSA key pairs for all hosts 274@subsection STEP 2: create the RSA key pairs for all hosts
291Run the following command to generate all key pairs (that might take a while): 275Run the following command to generate all key pairs for all nodes (that might take a while):
292@refill 276@refill
293 277
294 278
295@example 279@example
296 gvpectrl -c /etc/gvpe -g 280 gvpectrl -c /etc/gvpe -g
… …
299This command will put the public keys into @t{/etc/gvpe/pubkeys/@emph{nodename}} and the private keys into @t{/etc/gvpe/hostkeys/@emph{nodename}}. 283This command will put the public keys into @t{/etc/gvpe/pubkeys/@emph{nodename}} and the private keys into @t{/etc/gvpe/hostkeys/@emph{nodename}}.
300@refill 284@refill
301 285
302 286
303@subsection STEP 3: distribute the config files to all nodes 287@subsection STEP 3: distribute the config files to all nodes
304Now distribute the config files to the other nodes. This should be done in two steps, since the private keys should not be distributed. The example uses rsync-over-ssh 288Now distribute the config files and private keys to the other nodes. This should be done in two steps, since only the private keys meant for a node should be distributed (so each node has only it's own private key).
289@refill
290The example uses rsync-over-ssh
305@refill 291@refill
306First all the config files without the hostkeys should be distributed: 292First all the config files without the hostkeys should be distributed:
307@refill 293@refill
308 294
309 295
… …
321 rsync -avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey 307 rsync -avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey
322 rsync -avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey 308 rsync -avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey
323 rsync -avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey 309 rsync -avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey
324@end example 310@end example
325 311
326You should now check the configration by issuing the command @t{gvpectrl -c /etc/gvpe -s} on each node and verify it's output. 312You should now check the configuration by issuing the command @t{gvpectrl -c /etc/gvpe -s} on each node and verify it's output.
327@refill 313@refill
328 314
329 315
330@subsection STEP 4: starting gvpe 316@subsection STEP 4: starting gvpe
331You should then start gvpe on each node by issuing a command like: 317You should then start gvpe on each node by issuing a command like:
332@refill 318@refill
333 319
334 320
335@example 321@example
336 gvpe -D -linfo first # first is the nodename 322 gvpe -D -l info first # first is the nodename
337@end example 323@end example
338 324
339This will make the gvpe stay in foreground. You should then see "connection established" messages. If you don't see them check your firewall and routing (use tcpdump ;). 325This will make the gvpe daemon stay in foreground. You should then see "connection established" messages. If you don't see them check your firewall and routing (use tcpdump ;).
340@refill 326@refill
341If this works you should check your networking setup by pinging various endpoints. 327If this works you should check your networking setup by pinging various endpoints.
342@refill 328@refill
343To make gvpe run more permanently you can either run it as a daemon (by starting it without the @t{-D} switch), or, much better, from your inittab. I use a line like this on my systems: 329To make gvpe run more permanently you can either run it as a daemon (by starting it without the @t{-D} switch), or, much better, from your inittab or equivalent. I use a line like this on all my systems:
344@refill 330@refill
345 331
346 332
347@example 333@example
348 t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1 334 t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1
… …
376This file tries to capture OS-dependent configuration or build issues, quirks and platform limitations, as known. 362This file tries to capture OS-dependent configuration or build issues, quirks and platform limitations, as known.
377@refill 363@refill
378 364
379 365
380@section TUN vs. TAP interface 366@section TUN vs. TAP interface
381Most operating systems nowadays support something called a @emph{tunnel}-device, which makes it possible to divert IPv4 (and often other protocols, too) into a userspace daemon like @t{gvpe}. This is being referred to as a TUN-device. 367Most operating systems nowadays support something called a @emph{tunnel}-device, which makes it possible to divert IPv4 (and often other protocols, too) into a user space daemon like @t{gvpe}. This is being referred to as a TUN-device.
382@refill 368@refill
383This is fine for point-to-point tunnels, but for a virtual ethernet, an additional ethernet header is needed. This functionality (called a TAP device here) is only provided by a subset of the configurations. 369This is fine for point-to-point tunnels, but for a virtual ethernet, an additional ethernet header is needed. This functionality (called a TAP device here) is only provided by a subset of the configurations.
384@refill 370@refill
385On platforms only supporting a TUN-device, gvpe will invoke it's magical ethernet emulation package, which currently only handles ARP requests for the IPv4 protocol (but more could be added, bu the tincd network drivers might need to be modified for this to work). This means that on those platforms, only IPv4 will be supported. 371On platforms only supporting a TUN-device, gvpe will invoke it's magical ethernet emulation package, which currently only handles ARP requests for the IPv4 protocol (but more could be added, bu the tincd network drivers might need to be modified for this to work). This means that on those platforms, only IPv4 will be supported.
386@refill 372@refill
… …
548 534
549The interface MAC and MTU are @emph{NOT} set up for you. Please try it out and send me an @t{ifconfig} command invocation that does that. 535The interface MAC and MTU are @emph{NOT} set up for you. Please try it out and send me an @t{ifconfig} command invocation that does that.
550@refill 536@refill
551See @t{tincd/netbsd} for more information. 537See @t{tincd/netbsd} for more information.
552@refill 538@refill
553Completely unstested so far. 539Completely untested so far.
554@refill 540@refill
555 541
556 542
557@subsection tincd/mingw 543@subsection tincd/mingw
558TAP-device; see @t{native/cygwin} for more information. 544TAP-device; see @t{native/cygwin} for more information.
… …
569Completely untested so far. 555Completely untested so far.
570@refill 556@refill
571 557
572 558
573@subsection tincd/uml_socket 559@subsection tincd/uml_socket
574TAP-device; purpose unknown and untested, probably creates a unix datagram socket (path given by @t{ifname}) and reads and writes raw packets, so might be useful in other than UML contexts. 560TAP-device; purpose unknown and untested, probably creates a UNIX datagram socket (path given by @t{ifname}) and reads and writes raw packets, so might be useful in other than UML contexts.
575@refill 561@refill
576No network interface is created, and the MAC and MTU must be set as approriate on the other side of the socket. GVPE will exit if the MAC address doesn't match what it expects. 562No network interface is created, and the MAC and MTU must be set as appropriate on the other side of the socket. GVPE will exit if the MAC address doesn't match what it expects.
577@refill 563@refill
578Completely untested so far. 564Completely untested so far.
579@refill 565@refill
580 566
581 567
… …
596 582
597@section SYNOPSIS 583@section SYNOPSIS
598 584
599 585
600@example 586@example
587 # global options for all nodes
601 udp-port = 407 588 udp-port = 407
602 mtu = 1492 589 mtu = 1492
603 ifname = vpn0 590 ifname = vpn0
604@end example
605 591
606 592 # first node is named branch1 and is at 1.2.3.4
607
608@example
609 node = branch1 593 node = branch1
610 hostname = 1.2.3.4 594 hostname = 1.2.3.4
611@end example
612 595
613 596 # second node uses dns to resolve the address
614
615@example
616 node = branch2 597 node = branch2
617 hostname = www.example.net 598 hostname = www.example.net
618 udp-port = 500 # this host uses a different udp-port 599 udp-port = 500 # this host uses a different udp-port
619@end example
620 600
621 601 # third node has no fixed ip address
622
623@example
624 node = branch3 602 node = branch3
625 connect = ondemand 603 connect = ondemand
626@end example 604@end example
627 605
628 606
… …
630@section DESCRIPTION 608@section DESCRIPTION
631The gvpe config file consists of a series of lines that contain @t{variable = value} pairs. Empty lines are ignored. Comments start with a @t{#} and extend to the end of the line. They can be used on their own lines, or after any directives. Whitespace is allowed around the @t{=} sign or after values, but not within the variable names or values themselves. 609The gvpe config file consists of a series of lines that contain @t{variable = value} pairs. Empty lines are ignored. Comments start with a @t{#} and extend to the end of the line. They can be used on their own lines, or after any directives. Whitespace is allowed around the @t{=} sign or after values, but not within the variable names or values themselves.
632@refill 610@refill
633The only exception to the above is the "on" directive that can prefix any @t{name = value} setting and will only "execute" it on the named node, or (if the nodename starts with "!") on all nodes except the named one. 611The only exception to the above is the "on" directive that can prefix any @t{name = value} setting and will only "execute" it on the named node, or (if the nodename starts with "!") on all nodes except the named one.
634@refill 612@refill
613For example, set the MTU to @t{1450} everywhere, loglevel to @t{noise} on branch1, and connect to @t{ondemand} everywhere but on branch2:
614@refill
635 615
636 616
637@example 617@example
638 name = value 618 mtu = 1450
639 on branch1 loglevel = noise 619 on branch1 loglevel = noise
640 on !branch2 connect = ondemand 620 on !branch2 connect = ondemand
641@end example 621@end example
642 622
643All settings are executed "in order", that is, later settings of the same variable overwrite earlier ones. 623All settings are applied "in order", that is, later settings of the same variable overwrite earlier ones.
644@refill 624@refill
645 625
646 626
647@section ANATOMY OF A CONFIG FILE 627@section ANATOMY OF A CONFIG FILE
648Usually, a config file starts with global settings (like the udp port to listen on), followed by node-specific sections that begin with a @t{node = nickname} line. 628Usually, a config file starts with a few global settings (like the UDP port to listen on), followed by node-specific sections that begin with a @t{node = nickname} line.
649@refill 629@refill
650Every node that is part of the network must have a section that starts with @t{node = nickname}. The number and order of the nodes is important and must be the same on all hosts. It is not uncommon for node sections to be completely empty - if the default values are right. 630Every node that is part of the network must have a section that starts with @t{node = nickname}. The number and order of the nodes is important and must be the same on all nodes. It is not uncommon for node sections to be completely empty - if the default values are right.
651@refill 631@refill
652Node-specific settings can be used at any time. If used before the first node section they will set the default values for all following nodes. 632Node-specific settings can be used at any time. If used before the first node section they will set the default values for all following nodes.
653@refill 633@refill
654 634
655 635
… …
663 643
664@itemize 644@itemize
665 645
666 646
667@item 647@item
668@b{dns-forw-host = hostname/ip} 648dns-forw-host = hostname/ip
669 649
670@cindex dns-forw-host 650@cindex dns-forw-host
671The dns server to forward dns requests to for the DNS tunnel protocol (default: @t{127.0.0.1}, changing it is highly recommended). 651The DNS server to forward DNS requests to for the DNS tunnel protocol (default: @t{127.0.0.1}, changing it is highly recommended).
672@refill 652@refill
673 653
674 654
675@item 655@item
676@b{dns-forw-port = port-number} 656dns-forw-port = port-number
677 657
678@cindex dns-forw-port 658@cindex dns-forw-port
679The port where the @t{dns-forw-host} is to be contacted (default: @t{53}, which is fine in most cases). 659The port where the @t{dns-forw-host} is to be contacted (default: @t{53}, which is fine in most cases).
680@refill 660@refill
681 661
682 662
683@item 663@item
684@b{dns-max-outstanding = integer-number-of-requests} 664dns-max-outstanding = integer-number-of-requests
685 665
686@cindex dns-max-outstanding 666@cindex dns-max-outstanding
687The maximum number of outstanding DNS transport requests (default: @t{100}). GVPE will never issue more requests then the given limit without receiving replies. In heavily overloaded situations it might help to set this to a low number (e.g. @t{3} or even @t{1}) to limit the number of parallel requests. 667The maximum number of outstanding DNS transport requests (default: @t{100}). GVPE will never issue more requests then the given limit without receiving replies. In heavily overloaded situations it might help to set this to a low number (e.g. @t{3} or even @t{1}) to limit the number of parallel requests.
688@refill 668@refill
689The default should be working ok for most links. 669The default should be working OK for most links.
690@refill 670@refill
691 671
692 672
693@item 673@item
694@b{dns-overlap-factor = float} 674dns-overlap-factor = float
695 675
696@cindex dns-overlap-factor 676@cindex dns-overlap-factor
697The DNS transport uses the minimum request latency (@strong{min_latency}) seen during a connection as it's timing base. This factor (default: @t{0.5}, must be > 0) is multiplied by @strong{min_latency} to get the maximum sending rate (= minimum send interval), i.e. a factor of @t{1} means that a new request might be generated every @strong{min_latency} seconds, which means on average there should only ever be one outstanding request. A factor of @t{0.5} means that GVPE will send requests twice as often as the minimum latency measured. 677The DNS transport uses the minimum request latency (@strong{min_latency}) seen during a connection as it's timing base. This factor (default: @t{0.5}, must be > 0) is multiplied by @strong{min_latency} to get the maximum sending rate (= minimum send interval), i.e. a factor of @t{1} means that a new request might be generated every @strong{min_latency} seconds, which means on average there should only ever be one outstanding request. A factor of @t{0.5} means that GVPE will send requests twice as often as the minimum latency measured.
698@refill 678@refill
699For congested or picky dns forwarders you could use a value nearer to or exceeding @t{1}. 679For congested or picky DNS forwarders you could use a value nearer to or exceeding @t{1}.
700@refill 680@refill
701The default should be working ok for most links. 681The default should be working OK for most links.
702@refill 682@refill
703 683
704 684
705@item 685@item
706@b{dns-send-interval = send-interval-in-seconds} 686dns-send-interval = send-interval-in-seconds
707 687
708@cindex dns-send-interval 688@cindex dns-send-interval
709The minimum send interval (= maximum rate) that the DNS transport will use to send new DNS requests. GVPE will not exceed this rate even when the latency is very low. The default is @t{0.01}, which means GVPE will not send more than 100 DNS requests per connection per second. For high-bandwidth links you could go lower, e.g. to @t{0.001} or so. For congested or rate-limited links, you might want to go higher, say @t{0.1}, @t{0.2} or even higher. 689The minimum send interval (= maximum rate) that the DNS transport will use to send new DNS requests. GVPE will not exceed this rate even when the latency is very low. The default is @t{0.01}, which means GVPE will not send more than 100 DNS requests per connection per second. For high-bandwidth links you could go lower, e.g. to @t{0.001} or so. For congested or rate-limited links, you might want to go higher, say @t{0.1}, @t{0.2} or even higher.
710@refill 690@refill
711The default should be working ok for most links. 691The default should be working OK for most links.
712@refill 692@refill
713 693
714 694
715@item 695@item
716@b{dns-timeout-factor = float} 696dns-timeout-factor = float
717 697
718@cindex dns-timeout-factor 698@cindex dns-timeout-factor
719Factor to multiply the @t{min_latency} (see @t{dns-overlap-factor}) by to get request timeouts. The default of @t{8} means that the DNS transport will resend the request when no reply has been received for longer than eight times the minimum (= expected) latency, assuming the request or reply has been lost. 699Factor to multiply the @t{min_latency} (see @t{dns-overlap-factor}) by to get request timeouts. The default of @t{8} means that the DNS transport will resend the request when no reply has been received for longer than eight times the minimum (= expected) latency, assuming the request or reply has been lost.
720@refill 700@refill
721For congested links a higher value might be necessary (e.g. @t{30}). If the link is very stable lower values (e.g. @t{2}) might work nicely. Values near or below @t{1} makes no sense whatsoever. 701For congested links a higher value might be necessary (e.g. @t{30}). If the link is very stable lower values (e.g. @t{2}) might work nicely. Values near or below @t{1} makes no sense whatsoever.
722@refill 702@refill
723The default should be working ok for most links. 703The default should be working OK for most links but will result in low throughput if packet loss is high.
724@refill 704@refill
725 705
726 706
727@item 707@item
728@b{if-up = relative-or-absolute-path} 708if-up = relative-or-absolute-path
729 709
730@cindex if-up 710@cindex if-up
731Sets the path of a script that should be called immediately after the network interface is initialized (but not neccessarily up). The following environment variables are passed to it (the values are just examples). 711Sets the path of a script that should be called immediately after the network interface is initialized (but not necessarily up). The following environment variables are passed to it (the values are just examples).
732@refill 712@refill
733Variables that have the same value on all nodes: 713Variables that have the same value on all nodes:
734@refill 714@refill
735 715
736 716
737@itemize 717@itemize
738 718
739 719
740@item 720@item
741@b{CONFBASE=/etc/gvpe} 721CONFBASE=/etc/gvpe
742 722
743@cindex CONFBASE 723@cindex CONFBASE
744The configuration base directory. 724The configuration base directory.
745@refill 725@refill
746 726
747 727
748@item 728@item
749@b{IFNAME=vpn0} 729IFNAME=vpn0
750 730
751@cindex IFNAME 731@cindex IFNAME
752The network interface to initialize. 732The network interface to initialize.
753@refill 733@refill
754 734
755 735
756@item 736@item
757@b{IFTYPE=native # or tincd} 737IFTYPE=native # or tincd
758 738
759@cindex IFTYPE 739@cindex IFTYPE
760 740
761 741
762@item 742@item
763@b{IFSUBTYPE=linux # or freebsd, darwin etc..} 743IFSUBTYPE=linux # or freebsd, darwin etc..
764 744
765@cindex IFSUBTYPE 745@cindex IFSUBTYPE
766The interface type (@t{native} or @t{tincd}) and the subtype (usually the OS name in lowercase) that this GVPE was configured for. Can be used to select the correct syntax to use for network-related commands. 746The interface type (@t{native} or @t{tincd}) and the subtype (usually the OS name in lowercase) that this GVPE was configured for. Can be used to select the correct syntax to use for network-related commands.
767@refill 747@refill
768 748
769 749
770@item 750@item
771@b{MTU=1436} 751MTU=1436
772 752
773@cindex MTU 753@cindex MTU
774The MTU to set the interface to. You can use lower values (if done consistently on all hosts), but this is usually ineffective. 754The MTU to set the interface to. You can use lower values (if done consistently on all nodes), but this is usually either inefficient or simply ineffective.
775@refill 755@refill
776 756
777 757
778@item 758@item
779@b{NODES=5} 759NODES=5
780 760
781@cindex NODES 761@cindex NODES
782The number of nodes in this GVPE network. 762The number of nodes in this GVPE network.
783@refill 763@refill
784@end itemize 764@end itemize
… …
789 769
790@itemize 770@itemize
791 771
792 772
793@item 773@item
794@b{IFUPDATA=string} 774IFUPDATA=string
795 775
796@cindex IFUPDATA 776@cindex IFUPDATA
797The value of the configuration directive @t{if-up-data}. 777The value of the configuration directive @t{if-up-data}.
798@refill 778@refill
799 779
800 780
801@item 781@item
802@b{MAC=fe:fd:80:00:00:01} 782MAC=fe:fd:80:00:00:01
803 783
804@cindex MAC 784@cindex MAC
805The MAC address the network interface has to use. 785The MAC address the network interface has to use.
806@refill 786@refill
807Might be used to initialize interfaces on platforms where GVPE does not do this automatically. Please see the @t{gvpe.osdep(5)} manpage for platform-specific information. 787Might be used to initialize interfaces on platforms where GVPE does not do this automatically. Please see the @t{gvpe.osdep(5)} man page for platform-specific information.
808@refill 788@refill
809 789
810 790
811@item 791@item
812@b{NODENAME=branch1} 792NODENAME=branch1
813 793
814@cindex NODENAME 794@cindex NODENAME
815The nickname of the node. 795The nickname of the node.
816@refill 796@refill
817 797
818 798
819@item 799@item
820@b{NODEID=1} 800NODEID=1
821 801
822@cindex NODEID 802@cindex NODEID
823The numerical node ID of the node running this instance of GVPE. The first node mentioned in the config file gets ID 1, the second ID 2 and so on. 803The numerical node ID of the node running this instance of GVPE. The first node mentioned in the config file gets ID 1, the second ID 2 and so on.
824@refill 804@refill
825@end itemize 805@end itemize
… …
836 [ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME 816 [ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME
837 [ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME 817 [ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME
838 ip route add 10.0.0.0/8 dev $IFNAME 818 ip route add 10.0.0.0/8 dev $IFNAME
839@end example 819@end example
840 820
841More complicated examples (using routing to reduce arp traffic) can be found in the etc/ subdirectory of the distribution. 821More complicated examples (using routing to reduce ARP traffic) can be found in the @file{etc/} subdirectory of the distribution.
842@refill 822@refill
843 823
844 824
845@item 825@item
846@b{ifname = devname} 826ifname = devname
847 827
848@cindex ifname 828@cindex ifname
849Sets the tun interface name to the given name. The default is OS-specific and most probably something like @t{tun0}. 829Sets the tun interface name to the given name. The default is OS-specific and most probably something like @t{tun0}.
850@refill 830@refill
851 831
852 832
853@item 833@item
854@b{ifpersist = yes|true|on | no|false|off} 834ifpersist = yes|true|on | no|false|off
855 835
856@cindex ifpersist 836@cindex ifpersist
857Should the tun/tap device be made persistent, that is, should the device stay up even when gvpe exits? Some versions of the tunnel device have problems sending packets when gvpe is restarted in persistent mode, so if the connections can be established but you cannot send packets from the local node, try to set this to @t{off} and do an ifconfig down on the device. 837Should the tun/tap device be made persistent, that is, should the device stay up even when gvpe exits? Some versions of the tunnel device have problems sending packets when gvpe is restarted in persistent mode, so if the connections can be established but you cannot send packets from the local node, try to set this to @t{off} and do an ifconfig down on the device.
858@refill 838@refill
859 839
860 840
861@item 841@item
862@b{ip-proto = numerical-ip-protocol} 842ip-proto = numerical-ip-protocol
863 843
864@cindex ip-proto 844@cindex ip-proto
865Sets the protocol number to be used for the rawip protocol. This is a global option because all hosts must use the same protocol, and since there are no port numbers, you cannot easily run more than one gvpe instance using the same protocol, nor can you share the protocol with other programs. 845Sets the protocol number to be used for the rawip protocol. This is a global option because all nodes must use the same protocol, and since there are no port numbers, you cannot easily run more than one gvpe instance using the same protocol, nor can you share the protocol with other programs.
866@refill 846@refill
867The default is 47 (GRE), which has a good chance of tunneling through firewalls (but note that the rawip protocol is not GRE compatible). Other common choices are 50 (IPSEC, ESP), 51 (IPSEC, AH), 4 (IPIP tunnels) or 98 (ENCAP, rfc1241) 847The default is 47 (GRE), which has a good chance of tunneling through firewalls (but note that gvpe's rawip protocol is not GRE compatible). Other common choices are 50 (IPSEC, ESP), 51 (IPSEC, AH), 4 (IPIP tunnels) or 98 (ENCAP, rfc1241).
868@refill 848@refill
849Many versions of Linux seem to have a bug that causes them to reorder packets for some ip protocols (GRE, ESP) but not for others (AH), so choose wisely (that is, use 51, AH).
850@refill
869 851
870 852
871@item 853@item
872@b{http-proxy-host = hostname/ip} 854http-proxy-host = hostname/ip
873 855
874@cindex http-proxy-host 856@cindex http-proxy-host
875The @t{http-proxy-*} family of options are only available if gvpe was compiled with the @t{--enable-http-proxy} option and enable tunneling of tcp connections through a http proxy server. 857The @t{http-proxy-*} family of options are only available if gvpe was compiled with the @t{--enable-http-proxy} option and enable tunneling of tcp connections through a http proxy server.
876@refill 858@refill
877@t{http-proxy-host} and @t{http-proxy-port} should specify the hostname and port number of the proxy server. See @t{http-proxy-loginpw} if your proxy requires authentication. 859@t{http-proxy-host} and @t{http-proxy-port} should specify the hostname and port number of the proxy server. See @t{http-proxy-loginpw} if your proxy requires authentication.
878@refill 860@refill
879Please note that gvpe will still try to resolve all hostnames in the configuration file, so if you are behind a proxy without access to a dns server better use numerical IP addresses. 861Please note that gvpe will still try to resolve all hostnames in the configuration file, so if you are behind a proxy without access to a DNS server better use numerical IP addresses.
880@refill 862@refill
881To make best use of this option disable all protocols except tcp in your config file and make sure your routers (or all other hosts) are listening on a port that the proxy allows (443, https, is a common choice). 863To make best use of this option disable all protocols except TCP in your config file and make sure your routers (or all other nodes) are listening on a port that the proxy allows (443, https, is a common choice).
882@refill 864@refill
883If you have a router, connecting to it will suffice. Otherwise tcp must be enabled on all hosts. 865If you have a router, connecting to it will suffice. Otherwise TCP must be enabled on all nodes.
884@refill 866@refill
885Example: 867Example:
886@refill 868@refill
887 869
888 870
… …
893@end example 875@end example
894 876
895 877
896 878
897@item 879@item
898@b{http-proxy-port = proxy-tcp-port} 880http-proxy-port = proxy-tcp-port
899 881
900@cindex http-proxy-port 882@cindex http-proxy-port
901The port where your proxy server listens. 883The port where your proxy server listens.
902@refill 884@refill
903 885
904 886
905@item 887@item
906@b{http-proxy-auth = login:password} 888http-proxy-auth = login:password
907 889
908@cindex http-proxy-auth 890@cindex http-proxy-auth
909The optional login and password used to authenticate to the proxy server, seperated by a literal colon (@t{:}). Only basic authentication is currently supported. 891The optional login and password used to authenticate to the proxy server, separated by a literal colon (@t{:}). Only basic authentication is currently supported.
910@refill 892@refill
911 893
912 894
913@item 895@item
914@b{keepalive = seconds} 896keepalive = seconds
915 897
916@cindex keepalive 898@cindex keepalive
917Sets the keepalive probe interval in seconds (default: @t{60}). After this many seconds of inactivity the daemon will start to send keepalive probe every 5 seconds until it receives a reply from the other end. If no reply is received within 30 seconds, the peer is considered unreachable and the connection is closed. 899Sets the keepalive probe interval in seconds (default: @t{60}). After this many seconds of inactivity the daemon will start to send keepalive probe every 3 seconds until it receives a reply from the other end. If no reply is received within 15 seconds, the peer is considered unreachable and the connection is closed.
918@refill 900@refill
919 901
920 902
921@item 903@item
922@b{loglevel = noise|trace|debug|info|notice|warn|error|critical} 904loglevel = noise|trace|debug|info|notice|warn|error|critical
923 905
924@cindex loglevel 906@cindex loglevel
925Set the logging level. Connection established messages are logged at level @t{info}, notable errors are logged with @t{error}. Default is @t{info}. 907Set the logging level. Connection established messages are logged at level @t{info}, notable errors are logged with @t{error}. Default is @t{info}.
926@refill 908@refill
927 909
928 910
929@item 911@item
930@b{mtu = bytes} 912mtu = bytes
931 913
932@cindex mtu 914@cindex mtu
933Sets the maximum MTU that should be used on outgoing packets (basically the MTU of the outgoing interface) The daemon will automatically calculate maximum overhead (e.g. udp header size, encryption blocksize...) and pass this information to the @t{if-up} script. 915Sets the maximum MTU that should be used on outgoing packets (basically the MTU of the outgoing interface) The daemon will automatically calculate maximum overhead (e.g. UDP header size, encryption blocksize...) and pass this information to the @t{if-up} script.
934@refill 916@refill
935Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp). 917Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp).
936@refill 918@refill
937This value must be the minimum of the mtu values of all hosts. 919This value must be the minimum of the MTU values of all nodes.
938@refill 920@refill
939 921
940 922
941@item 923@item
942@b{node = nickname} 924node = nickname
943 925
944@cindex node 926@cindex node
945Not really a config setting but introduces a node section. The nickname is used to select the right configuration section and must be passed as an argument to the gvpe daemon. 927Not really a config setting but introduces a node section. The nickname is used to select the right configuration section and must be passed as an argument to the gvpe daemon.
946@refill 928@refill
947 929
948 930
949@item 931@item
950@b{node-up = relative-or-absolute-path} 932node-up = relative-or-absolute-path
951 933
952@cindex node-up 934@cindex node-up
953Sets a command (default: no script) that should be called whenever a connection is established (even on rekeying operations). In addition to all the variables passed to @t{if-up} scripts, the following environment variables will be set: 935Sets a command (default: none) that should be called whenever a connection is established (even on rekeying operations). Note that node-up/down scripts will be run asynchronously, but execution is serialised, so there will only ever be one such script running.
936@refill
937In addition to all the variables passed to @t{if-up} scripts, the following environment variables will be set (values are just examples):
954@refill 938@refill
955 939
956 940
957@itemize 941@itemize
958 942
959 943
960@item 944@item
961@b{DESTNODE=branch2} 945DESTNODE=branch2
962 946
963@cindex DESTNODE 947@cindex DESTNODE
964The name of the remote node. 948The name of the remote node.
965@refill 949@refill
966 950
967 951
968@item 952@item
969@b{DESTID=2} 953DESTID=2
970 954
971@cindex DESTID 955@cindex DESTID
972The node id of the remote node. 956The node id of the remote node.
973@refill 957@refill
974 958
975 959
976@item 960@item
961DESTSI=rawip/88.99.77.55:0
962
963@cindex DESTSI
964The "socket info" of the target node, protocol dependent but usually in the format protocol/ip:port.
965@refill
966
967
968@item
977@b{DESTIP=188.13.66.8} 969DESTIP=188.13.66.8
978 970
979@cindex DESTIP 971@cindex DESTIP
980The numerical IP address of the remote host (gvpe accepts connections from everywhere, as long as the other host can authenticate itself). 972The numerical IP address of the remote node (gvpe accepts connections from everywhere, as long as the other node can authenticate itself).
981@refill 973@refill
982 974
983 975
984@item 976@item
985@b{DESTPORT=655 # deprecated} 977DESTPORT=655 # deprecated
986 978
987@cindex DESTPORT 979@cindex DESTPORT
988The UDP port used by the other side. 980The protocol port used by the other side, if applicable.
989@refill 981@refill
990 982
991 983
992@item 984@item
993@b{STATE=UP} 985STATE=up
994 986
995@cindex STATE 987@cindex STATE
996Node-up scripts get called with STATE=UP, node-down scripts get called with STATE=DOWN. 988Node-up scripts get called with STATE=up, node-change scripts get called with STATE=change and node-down scripts get called with STATE=down.
997@refill 989@refill
998@end itemize 990@end itemize
999 991
1000Here is a nontrivial example that uses nsupdate to update the name => ip mapping in some dns zone: 992Here is a nontrivial example that uses nsupdate to update the name => ip mapping in some DNS zone:
1001@refill 993@refill
1002 994
1003 995
1004@example 996@example
1005 #!/bin/sh 997 #!/bin/sh
… …
1011@end example 1003@end example
1012 1004
1013 1005
1014 1006
1015@item 1007@item
1008node-change = relative-or-absolute-path
1009
1010@cindex node-change
1011Same as @t{node-change}, but gets called whenever something about a connection changes (such as the source IP address).
1012@refill
1013
1014
1015@item
1016@b{node-down = relative-or-absolute-path} 1016node-down = relative-or-absolute-path
1017 1017
1018@cindex node-down 1018@cindex node-down
1019Same as @t{node-up}, but gets called whenever a connection is lost. 1019Same as @t{node-up}, but gets called whenever a connection is lost.
1020@refill 1020@refill
1021 1021
1022 1022
1023@item 1023@item
1024@b{pid-file = path} 1024pid-file = path
1025 1025
1026@cindex pid-file 1026@cindex pid-file
1027The path to the pid file to check and create (default: @t{LOCALSTATEDIR/run/gvpe.pid}). 1027The path to the pid file to check and create (default: @t{LOCALSTATEDIR/run/gvpe.pid}).
1028@refill 1028@refill
1029 1029
1030 1030
1031@item 1031@item
1032@b{private-key = relative-path-to-key} 1032private-key = relative-path-to-key
1033 1033
1034@cindex private-key 1034@cindex private-key
1035Sets the path (relative to the config directory) to the private key (default: @t{hostkey}). This is a printf format string so every @t{%} must be doubled. A single @t{%s} is replaced by the hostname, so you could use paths like @t{hostkeys/%s} to fetch the files at the location where @t{gvpectrl} puts them. 1035Sets the path (relative to the config directory) to the private key (default: @t{hostkey}). This is a printf format string so every @t{%} must be doubled. A single @t{%s} is replaced by the hostname, so you could use paths like @t{hostkeys/%s} to fetch the files at the location where @t{gvpectrl} puts them.
1036@refill 1036@refill
1037Since only the private key file of the current node is used and the private key file should be kept secret per-host to avoid spoofings, it is not recommended to use this feature. 1037Since only the private key file of the current node is used and the private key file should be kept secret per-node to avoid spoofing, it is not recommended to use this feature.
1038@refill 1038@refill
1039 1039
1040 1040
1041@item 1041@item
1042@b{rekey = seconds} 1042rekey = seconds
1043 1043
1044@cindex rekey 1044@cindex rekey
1045Sets the rekeying interval in seconds (default: @t{3600}). Connections are reestablished every @t{rekey} seconds. 1045Sets the rekeying interval in seconds (default: @t{3600}). Connections are reestablished every @t{rekey} seconds, making them use a new encryption key.
1046@refill 1046@refill
1047
1048
1049@item
1050nfmark = integer
1051
1052@cindex nfmark
1053This advanced option, when set to a nonzero value (default: @t{0}), tries to set the netfilter mark (or fwmark) value on all sockets gvpe uses to send packets.
1054@refill
1055This can be used to make gvpe use a different set of routing rules. For example, on GNU/Linux, the @t{if-up} could set @t{nfmark} to 1000 and then put all routing rules into table @t{99} and then use an ip rule to make gvpe traffic avoid that routing table, in effect routing normal traffic via gvpe and gvpe traffic via the normal system routing tables:
1056@refill
1057
1058
1059@example
1060 ip rule add not fwmark 1000 lookup 99
1061@end example
1062
1047@end itemize 1063@end itemize
1048 1064
1049 1065
1050 1066
1051@subsection NODE SPECIFIC SETTINGS 1067@subsection NODE SPECIFIC SETTINGS
… …
1055 1071
1056@itemize 1072@itemize
1057 1073
1058 1074
1059@item 1075@item
1060@b{allow-direct = nodename} 1076allow-direct = nodename
1061 1077
1062@cindex allow-direct 1078@cindex allow-direct
1063Allow direct connections to this node. See @t{deny-direct} for more info. 1079Allow direct connections to this node. See @t{deny-direct} for more info.
1064@refill 1080@refill
1065 1081
1066 1082
1067@item 1083@item
1068@b{compress = yes|true|on | no|false|off} 1084compress = yes|true|on | no|false|off
1069 1085
1070@cindex compress 1086@cindex compress
1071Wether to compress data packets sent to this host (default: @t{yes}). Compression is really cheap even on slow computers and has no size overhead at all, so enabling this is a good idea. 1087For the current node, this specified whether it will accept compressed packets, and for all other nodes, this specifies whether to try to compress data packets sent to this node (default: @t{yes}). Compression is really cheap even on slow computers, has no size overhead at all and will only be used when the other side supports compression, so enabling this is often a good idea.
1072@refill 1088@refill
1073 1089
1074 1090
1075@item 1091@item
1076@b{connect = ondemand | never | always | disabled} 1092connect = ondemand | never | always | disabled
1077 1093
1078@cindex connect 1094@cindex connect
1079Sets the connect mode (default: @t{always}). It can be @t{always} (always try to establish and keep a connection to the given host), @t{never} (never initiate a connection to the given host, but accept connections), @t{ondemand} (try to establish a connection on the first packet sent, and take it down after the keepalive interval) or @t{disabled} (node is bad, don't talk to it). 1095Sets the connect mode (default: @t{always}). It can be @t{always} (always try to establish and keep a connection to the given node), @t{never} (never initiate a connection to the given host, but accept connections), @t{ondemand} (try to establish a connection when there are outstanding packets in the queue and take it down after the keepalive interval) or @t{disabled} (node is bad, don't talk to it).
1080@refill 1096@refill
1097Routers will automatically be forced to @t{always} unless they are @t{disabled}, to ensure all nodes can talk to each other.
1098@refill
1081 1099
1082 1100
1083@item 1101@item
1084@b{deny-direct = nodename | *} 1102deny-direct = nodename | *
1085 1103
1086@cindex deny-direct 1104@cindex deny-direct
1087Deny direct connections to the specified node (or all nodes when @t{*} is given). Only one node can be specified, but you can use multiple @t{allow-direct} and @t{deny-direct} statements. This only makes sense in networks with routers, as routers are required for indirect connections. 1105Deny direct connections to the specified node (or all nodes when @t{*} is given). Only one node can be specified, but you can use multiple @t{allow-direct} and @t{deny-direct} statements. This only makes sense in networks with routers, as routers are required for indirect connections.
1088@refill 1106@refill
1089Sometimes, a node cannot reach some other nodes for reasons of network connectivity. For example, a node behind a firewall that only allows conenctions to/from a single other node in the network. In this case one should specify @t{deny-direct = *} and @t{allow-direct = othernodename} (the other node @emph{must} be a router for this to work). 1107Sometimes, a node cannot reach some other nodes for reasons of network connectivity. For example, a node behind a firewall that only allows connections to/from a single other node in the network. In this case one should specify @t{deny-direct = *} and @t{allow-direct = othernodename} (the other node @emph{must} be a router for this to work).
1090@refill 1108@refill
1091The algorithm to check wether a connection may be direct is as follows: 1109The algorithm to check whether a connection may be direct is as follows:
1092@refill 1110@refill
10931. Other node mentioned in a @t{allow-direct}? If yes, allow the connection. 11111. Other node mentioned in an @t{allow-direct}? If yes, allow the connection.
1094@refill 1112@refill
10952. Other node mentioned in a @t{deny-direct}? If yes, deny direct connections. 11132. Other node mentioned in a @t{deny-direct}? If yes, deny direct connections.
1096@refill 1114@refill
10973. Allow the connection. 11153. Allow the connection.
1098@refill 1116@refill
1099That is, @t{allow-direct} takes precende over @t{deny-direct}. 1117That is, @t{allow-direct} takes precedence over @t{deny-direct}.
1100@refill 1118@refill
1101The check is done in both directions, i.e. both nodes must allow a direct connection before one is attempted, so you only need to specify connect limitations on one node. 1119The check is done in both directions, i.e. both nodes must allow a direct connection before one is attempted, so you only need to specify connect limitations on one node.
1102@refill 1120@refill
1103 1121
1104 1122
1105@item 1123@item
1106@b{dns-domain = domain-suffix} 1124dns-domain = domain-suffix
1107 1125
1108@cindex dns-domain 1126@cindex dns-domain
1109The DNS domain suffix that points to the DNS tunnel server for this node. 1127The DNS domain suffix that points to the DNS tunnel server for this node.
1110@refill 1128@refill
1111The domain must point to a NS record that points to the @emph{dns-hostname}, i.e. 1129The domain must point to a NS record that points to the @emph{dns-hostname}, i.e.
… …
1127@end example 1145@end example
1128 1146
1129 1147
1130 1148
1131@item 1149@item
1132@b{dns-hostname = hostname/ip} 1150dns-hostname = hostname/ip
1133 1151
1134@cindex dns-hostname 1152@cindex dns-hostname
1135The address to bind the DNS tunnel socket to, similar to the @t{hostname}, but for the DNS tunnel protocol only. Default: @t{0.0.0.0}, but that might change. 1153The address to bind the DNS tunnel socket to, similar to the @t{hostname}, but for the DNS tunnel protocol only. Default: @t{0.0.0.0}, but that might change.
1136@refill 1154@refill
1137 1155
1138 1156
1139@item 1157@item
1140@b{dns-port = port-number} 1158dns-port = port-number
1141 1159
1142@cindex dns-port 1160@cindex dns-port
1143The port to bind the DNS tunnel socket to. Must be @t{53} on DNS tunnel servers. 1161The port to bind the DNS tunnel socket to. Must be @t{53} on DNS tunnel servers.
1144@refill 1162@refill
1145 1163
1146 1164
1147@item 1165@item
1148@b{enable-dns = yes|true|on | no|false|off} 1166enable-dns = yes|true|on | no|false|off
1149 1167
1150@cindex enable-dns 1168@cindex enable-dns
1151See gvpe.protocol(7) for a description of the DNS transport protocol. Avoid this protocol if you can. 1169See gvpe.protocol(7) for a description of the DNS transport protocol. Avoid this protocol if you can.
1152@refill 1170@refill
1153Enable the DNS tunneling protocol on this node, either as server or as client. Support for this transport protocol is only available when gvpe was compiled using the @t{--enable-dns} option. 1171Enable the DNS tunneling protocol on this node, either as server or as client. Support for this transport protocol is only available when gvpe was compiled using the @t{--enable-dns} option.
1154@refill 1172@refill
1155 1173
1156 1174
1157@item 1175@item
1158@b{enable-icmp = yes|true|on | no|false|off} 1176enable-icmp = yes|true|on | no|false|off
1159 1177
1160@cindex enable-icmp 1178@cindex enable-icmp
1161See gvpe.protocol(7) for a description of the ICMP transport protocol. 1179See gvpe.protocol(7) for a description of the ICMP transport protocol.
1162@refill 1180@refill
1163Enable the ICMP transport using icmp packets of type @t{icmp-type} on this node. 1181Enable the ICMP transport using ICMP packets of type @t{icmp-type} on this node.
1164@refill 1182@refill
1165 1183
1166 1184
1167@item 1185@item
1168@b{enable-rawip = yes|true|on | no|false|off} 1186enable-rawip = yes|true|on | no|false|off
1169 1187
1170@cindex enable-rawip 1188@cindex enable-rawip
1171See gvpe.protocol(7) for a description of the RAW IP transport protocol. 1189See gvpe.protocol(7) for a description of the RAW IP transport protocol.
1172@refill 1190@refill
1173Enable the RAW IPv4 transport using the @t{ip-proto} protocol (default: @t{no}). 1191Enable the RAW IPv4 transport using the @t{ip-proto} protocol (default: @t{no}).
1174@refill 1192@refill
1175 1193
1176 1194
1177@item 1195@item
1178@b{enable-tcp = yes|true|on | no|false|off} 1196enable-tcp = yes|true|on | no|false|off
1179 1197
1180@cindex enable-tcp 1198@cindex enable-tcp
1181See gvpe.protocol(7) for a description of the TCP transport protocol. 1199See gvpe.protocol(7) for a description of the TCP transport protocol.
1182@refill 1200@refill
1183Enable the TCPv4 transport using the @t{tcp-port} port (default: @t{no}). Support for this transport protocol is only available when gvpe was compiled using the @t{--enable-tcp} option. 1201Enable the TCPv4 transport using the @t{tcp-port} port (default: @t{no}). Support for this transport protocol is only available when gvpe was compiled using the @t{--enable-tcp} option.
1184@refill 1202@refill
1185 1203
1186 1204
1187@item 1205@item
1188@b{enable-udp = yes|true|on | no|false|off} 1206enable-udp = yes|true|on | no|false|off
1189 1207
1190@cindex enable-udp 1208@cindex enable-udp
1191See gvpe.protocol(7) for a description of the UDP transport protocol. 1209See gvpe.protocol(7) for a description of the UDP transport protocol.
1192@refill 1210@refill
1193Enable the UDPv4 transport using the @t{udp-port} port (default: @t{no}, unless no other protocol is enabled for a node, in which case this protocol is enabled automatically). 1211Enable the UDPv4 transport using the @t{udp-port} port (default: @t{no}, unless no other protocol is enabled for a node, in which case this protocol is enabled automatically).
1194@refill 1212@refill
1195NOTE: Please specify @t{enable-udp = yes} if you want t use it even though it might get switched on automatically, as some future version might default to another default protocol. 1213NOTE: Please specify @t{enable-udp = yes} if you want to use it even though it might get switched on automatically, as some future version might default to another default protocol.
1196@refill 1214@refill
1197 1215
1198 1216
1199@item 1217@item
1200@b{hostname = hostname | ip [can not be defaulted]} 1218hostname = hostname | ip [can not be defaulted]
1201 1219
1202@cindex hostname 1220@cindex hostname
1203Forces the address of this node to be set to the given dns hostname or ip address. It will be resolved before each connect request, so dyndns should work fine. If this setting is not specified and a router is available, then the router will be queried for the address of this node. Otherwise, the connection attempt will fail. 1221Forces the address of this node to be set to the given DNS hostname or IP address. It will be resolved before each connect request, so dyndns should work fine. If this setting is not specified and a router is available, then the router will be queried for the address of this node. Otherwise, the connection attempt will fail.
1204@refill 1222@refill
1223Note that DNS resolving is done synchronously, pausing the daemon. If that is an issue you need to specify IP addresses.
1224@refill
1205 1225
1206 1226
1207@item 1227@item
1208@b{icmp-type = integer} 1228icmp-type = integer
1209 1229
1210@cindex icmp-type 1230@cindex icmp-type
1211Sets the type value to be used for outgoing (and incoming) packets sent via the ICMP transport. 1231Sets the type value to be used for outgoing (and incoming) packets sent via the ICMP transport.
1212@refill 1232@refill
1213The default is @t{0} (which is @t{echo-reply}, also known as "ping-replies"). Other useful values include @t{8} (@t{echo-request}, a.k.a. "ping") and @t{11} (@t{time-exceeded}), but any 8-bit value can be used. 1233The default is @t{0} (which is @t{echo-reply}, also known as "ping-reply"). Other useful values include @t{8} (@t{echo-request}, a.k.a. "ping") and @t{11} (@t{time-exceeded}), but any 8-bit value can be used.
1214@refill 1234@refill
1215 1235
1216 1236
1217@item 1237@item
1218@b{if-up-data = value} 1238if-up-data = value
1219 1239
1220@cindex if-up-data 1240@cindex if-up-data
1221The value specified using this directive will be passed to the @t{if-up} script in the environment variable @t{IFUPDATA}. 1241The value specified using this directive will be passed to the @t{if-up} script in the environment variable @t{IFUPDATA}.
1222@refill 1242@refill
1223 1243
1224 1244
1225@item 1245@item
1226@b{inherit-tos = yes|true|on | no|false|off} 1246inherit-tos = yes|true|on | no|false|off
1227 1247
1228@cindex inherit-tos 1248@cindex inherit-tos
1229Wether to inherit the TOS settings of packets sent to the tunnel when sending packets to this node (default: @t{yes}). If set to @t{yes} then outgoing tunnel packets will have the same TOS setting as the packets sent to the tunnel device, which is usually what you want. 1249Whether to inherit the TOS settings of packets sent to the tunnel when sending packets to this node (default: @t{yes}). If set to @t{yes} then outgoing tunnel packets will have the same TOS setting as the packets sent to the tunnel device, which is usually what you want.
1230@refill 1250@refill
1231 1251
1232 1252
1233@item 1253@item
1234@b{max-retry = positive-number} 1254max-retry = positive-number
1235 1255
1236@cindex max-retry 1256@cindex max-retry
1237The maximum interval in seconds (default: @t{3600}, one hour) between retries to establish a connection to this node. When a connection cannot be established, gvpe uses exponential backoff capped at this value. It's sometimes useful to set this to a much lower value (e.g. @t{120}) on connections to routers that usually are stable but sometimes are down, to assure quick reconnections even after longer downtimes. 1257The maximum interval in seconds (default: @t{3600}, one hour) between retries to establish a connection to this node. When a connection cannot be established, gvpe uses exponential back-off capped at this value. It's sometimes useful to set this to a much lower value (e.g. @t{120}) on connections to routers that usually are stable but sometimes are down, to assure quick reconnections even after longer downtimes.
1238@refill 1258@refill
1239 1259
1240 1260
1241@item 1261@item
1262max-ttl = seconds
1263
1264@cindex max-ttl
1265Expire packets that couldn't be sent after this many seconds (default: @t{60}). Gvpe will normally queue packets for a node without an active connection, in the hope of establishing a connection soon. This value specifies the maximum lifetime a packet will stay in the queue, if a packet gets older, it will be thrown away.
1266@refill
1267
1268
1269@item
1270max-queue = positive-number>=1
1271
1272@cindex max-queue
1273The maximum number of packets that will be queued (default: @t{512}) for this node. If more packets are sent then earlier packets will be expired. See @t{max-ttl}, above.
1274@refill
1275
1276
1277@item
1242@b{router-priority = 0 | 1 | positive-number>=2} 1278router-priority = 0 | 1 | positive-number>=2
1243 1279
1244@cindex router-priority 1280@cindex router-priority
1245Sets the router priority of the given host (default: @t{0}, disabled). If some host tries to connect to another host without a hostname, it asks the router host for it's IP address. The router host is the one with the highest priority larger than @t{1} that is currently reachable. 1281Sets the router priority of the given node (default: @t{0}, disabled).
1246@refill 1282@refill
1247Make sure all hosts always connect (@t{connect = always}) to the router hosts, otherwise connecting to them might be impossible. 1283If some node tries to connect to another node but it doesn't have a hostname, it asks a router node for it's IP address. The router node chosen is the one with the highest priority larger than @t{1} that is currently reachable. This is called a @emph{mediated} connection, as the connection itself will still be direct, but it uses another node to mediate between the two nodes.
1248@refill 1284@refill
1249The special value @t{1} allows other hosts to route through the router host, but they will never route through it by default. The value @t{0} disables routing. The idea behind this is that some hosts can, if required, bump the @t{router-priority} setting to higher than @t{1} in their local config to route through specific hosts. If @t{router-priority} is @t{0}, then routing will be refused, so @t{1} serves as a "enable, but do not use by default" switch. 1285The value @t{0} disables routing, that means if the node receives a packet not for itself it will not forward it but instead drop it.
1250@refill 1286@refill
1287The special value @t{1} allows other hosts to route through the router host, but they will never route through it by default (i.e. the config file of another node needs to specify a router priority higher than one to choose such a node for routing).
1288@refill
1289The idea behind this is that some hosts can, if required, bump the @t{router-priority} setting to higher than @t{1} in their local config to route through specific hosts. If @t{router-priority} is @t{0}, then routing will be refused, so @t{1} serves as a "enable, but do not use by default" switch.
1290@refill
1291Nodes with @t{router-priority} set to @t{2} or higher will always be forced to @t{connect} = @t{always} (unless they are @t{disabled}).
1292@refill
1251 1293
1252 1294
1253@item 1295@item
1254@b{tcp-port = port-number} 1296tcp-port = port-number
1255 1297
1256@cindex tcp-port 1298@cindex tcp-port
1257Similar to @t{udp-port} (default: @t{655}), but sets the TCP port number. 1299Similar to @t{udp-port} (default: @t{655}), but sets the TCP port number.
1258@refill 1300@refill
1259 1301
1260 1302
1261@item 1303@item
1262@b{udp-port = port-number} 1304udp-port = port-number
1263 1305
1264@cindex udp-port 1306@cindex udp-port
1265Sets the port number used by the UDP protocol (default: @t{655}, not officially assigned by IANA!). 1307Sets the port number used by the UDP protocol (default: @t{655}, not officially assigned by IANA!).
1266@refill 1308@refill
1267@end itemize 1309@end itemize
… …
1275 1317
1276@itemize 1318@itemize
1277 1319
1278 1320
1279@item 1321@item
1280@b{
1281@cindex gvpe.conf
1282gvpe.conf} 1322gvpe.conf
1283 1323
1284The config file. 1324The config file.
1285@refill 1325@refill
1286 1326
1287 1327
1288@item 1328@item
1289@b{
1290@cindex if-up
1291if-up} 1329if-up
1292 1330
1293The if-up script 1331The if-up script
1294@refill 1332@refill
1295 1333
1296 1334
1297@item 1335@item
1298@b{ 1336node-up, node-down
1299@cindex node-up
1300node-up,
1301@cindex node-down
1302node-down}
1303 1337
1304If used the node up or node-down scripts. 1338If used the node up or node-down scripts.
1305@refill 1339@refill
1306 1340
1307 1341
1308@item 1342@item
1309@b{
1310@cindex hostkey
1311hostkey} 1343hostkey
1312 1344
1313The private key (taken from @t{hostkeys/nodename}) of the current host. 1345The private key (taken from @t{hostkeys/nodename}) of the current host.
1314@refill 1346@refill
1315 1347
1316 1348
1317@item 1349@item
1318@b{
1319@cindex pubkey/nodename
1320pubkey/nodename} 1350pubkey/nodename
1321 1351
1322The public keys of the other nodes, one file per node. 1352The public keys of the other nodes, one file per node.
1323@refill 1353@refill
1324@end itemize 1354@end itemize
1325 1355
… …
1350 1380
1351@itemize 1381@itemize
1352 1382
1353 1383
1354@item 1384@item
1355@b{@strong{-c}, @strong{--config=}@emph{DIR}} 1385@strong{-c}, @strong{--config=}@emph{DIR}
1356 1386
1357Read configuration options from @emph{DIR}. 1387Read configuration options from @emph{DIR}.
1358@refill 1388@refill
1359 1389
1360 1390
1361@item 1391@item
1362@b{@strong{-g}, @strong{--generate-keys}} 1392@strong{-g}, @strong{--generate-keys}
1363 1393
1364Generate public/private RSA keypair and exit. 1394Generate public/private RSA key-pair and exit.
1365@refill 1395@refill
1366 1396
1367 1397
1368@item 1398@item
1399@strong{-q}, @strong{--quiet}
1400
1401Suppresses messages the author finds nonessential for scripting purposes.
1402@refill
1403
1404
1405@item
1369@b{@strong{--help}} 1406@strong{--help}
1370 1407
1371Display short list of options. 1408Display short list of options.
1372@refill 1409@refill
1373 1410
1374 1411
1375@item 1412@item
1376@b{@strong{--kill}[@strong{=}@emph{SIGNAL}]} 1413@strong{--kill}[@strong{=}@emph{SIGNAL}]
1377 1414
1378Attempt to kill a running @t{gvpectrl} (optionally with the specified @emph{SIGNAL} instead of @t{SIGTERM}) and exit. 1415Attempt to kill a running @t{gvpectrl} (optionally with the specified @emph{SIGNAL} instead of @t{SIGTERM}) and exit.
1379@refill 1416@refill
1380 1417
1381 1418
1382@item 1419@item
1383@b{@strong{--show-config}} 1420@strong{--show-config}
1384 1421
1385Show a summary of the configuration, and how gvpe interprets it. Can also be very useful when designing firewall scripts. 1422Show a summary of the configuration, and how gvpe interprets it. Can also be very useful when designing firewall scripts.
1386@refill 1423@refill
1387 1424
1388 1425
1389@item 1426@item
1390@b{@strong{--version}} 1427@strong{--version}
1391 1428
1392Output version information and exit. 1429Output version information and exit.
1393@refill 1430@refill
1394@end itemize 1431@end itemize
1395 1432
… …
1414@t{gvpe} [@strong{-cDlL}] [@strong{--config=}@emph{DIR}] [@strong{--no-detach}] [@strong{-l=}@emph{LEVEL]}] [@strong{--kill}[@strong{=}@emph{SIGNAL}]] [@strong{--mlock}] [@strong{--help}] [@strong{--version}] @emph{NODENAME} [@emph{option...}] 1451@t{gvpe} [@strong{-cDlL}] [@strong{--config=}@emph{DIR}] [@strong{--no-detach}] [@strong{-l=}@emph{LEVEL]}] [@strong{--kill}[@strong{=}@emph{SIGNAL}]] [@strong{--mlock}] [@strong{--help}] [@strong{--version}] @emph{NODENAME} [@emph{option...}]
1415@refill 1452@refill
1416 1453
1417 1454
1418@section DESCRIPTION 1455@section DESCRIPTION
1419See the gvpe(5) manpage for an introduction to the gvpe suite. 1456See the gvpe(5) man page for an introduction to the gvpe suite.
1420@refill 1457@refill
1421This is the manual page for gvpe, the virtual private ethernet daemon. When started, @t{gvpe} will read it's configuration file to determine the network topology, and other configuration information, assuming the role of node @emph{NODENAME}. It will then connect to the tun/tap device and set up a socket for incoming connections. Then a script will be executed to further configure the virtual device. If that succeeds, it will detach from the controlling terminal and continue in the background, accepting and setting up connections to other gvpe daemons that are part of the virtual private ethernet. 1458This is the manual page for gvpe, the virtual private ethernet daemon. When started, @t{gvpe} will read it's configuration file to determine the network topology, and other configuration information, assuming the role of node @emph{NODENAME}
1459@refill
1460It will then create/connect to the tun/tap device and set up a socket for incoming connections. Then a @t{if-up} script will be executed to further configure the virtual network device. If that succeeds, it will detach from the controlling terminal and continue in the background, accepting and setting up connections to other gvpe daemons that are part of the same virtual private ethernet.
1422@refill 1461@refill
1423The optional arguments after the node name have to be of the form: 1462The optional arguments after the node name have to be of the form:
1424@refill 1463@refill
1425 1464
1426 1465
1427@example 1466@example
1428 [I<nodename>.]var=value 1467 [I<nodename>.]var=value
1429@end example 1468@end example
1430 1469
1431If the argument has a prefix of @t{nodename.} (i.e. @t{laptop.enable-dns=yes}) then it will be parsed after all the config directives for that node, if not, it is parsed befroe the first node directive in the config file, and can be used to set global options or default variables. 1470If the argument has a prefix of @t{nodename.} (i.e. @t{laptop.enable-dns=yes}) then it will be parsed after all the config directives for that node, if not, it is parsed before the first node directive in the config file, and can be used to set global options or default variables.
1432@refill 1471@refill
1433For example, to start @t{gvpe} in the foreground, with log-level @t{info} on the node @t{laptop}, with TCP enabled and HTTP-Proxy host and Port set, use this: 1472For example, to start @t{gvpe} in the foreground, with log-level @t{info} on the node @t{laptop}, with TCP enabled and HTTP-Proxy host and Port set, use this:
1434@refill 1473@refill
1435 1474
1436 1475
… …
1447 1486
1448@itemize 1487@itemize
1449 1488
1450 1489
1451@item 1490@item
1452@b{@strong{-c}, @strong{--config=}@emph{DIR}} 1491@strong{-c}, @strong{--config=}@emph{DIR}
1453 1492
1454Read configuration options from @emph{DIR} 1493Read configuration options from @emph{DIR}
1455@refill 1494@refill
1456 1495
1457 1496
1458@item 1497@item
1459@b{@strong{-d}, @strong{--l=}@emph{LEVEL}} 1498@strong{-d}, @strong{--l=}@emph{LEVEL}
1460 1499
1461Set logging level to @emph{LEVEL} (one of: noise, trace, debug, info, notice, warn, error, critical). 1500Set logging level to @emph{LEVEL} (one of: noise, trace, debug, info, notice, warn, error, critical).
1462@refill 1501@refill
1463 1502
1464 1503
1465@item 1504@item
1466@b{@strong{--help}} 1505@strong{--help}
1467 1506
1468Display short list of options. 1507Display short list of options.
1469@refill 1508@refill
1470 1509
1471 1510
1472@item 1511@item
1473@b{@strong{-D}, @strong{--no-detach}} 1512@strong{-D}, @strong{--no-detach}
1474 1513
1475Don't fork and detach but stay in foreground and log messages to stderr in addition to syslog. 1514Don't fork and detach but stay in foreground and log messages to stderr in addition to syslog.
1476@refill 1515@refill
1477 1516
1478 1517
1479@item 1518@item
1480@b{@strong{-L}, @strong{--mlock}} 1519@strong{-L}, @strong{--mlock}
1481 1520
1482Lock @t{gvpe} into main memory. This will prevent sensitive data like shared private keys to be written to the system swap files/partitions. 1521Lock @t{gvpe} into main memory. This will prevent sensitive data like shared private keys to be written to the system swap files/partitions.
1483@refill 1522@refill
1484 1523
1485 1524
1486@item 1525@item
1487@b{@strong{--version}} 1526@strong{--version}
1488 1527
1489Output version information and exit. 1528Output version information and exit.
1490@refill 1529@refill
1491@end itemize 1530@end itemize
1492 1531
… …
1497 1536
1498@itemize 1537@itemize
1499 1538
1500 1539
1501@item 1540@item
1502@b{HUP} 1541HUP
1503 1542
1504Closes/resets all connections, resets the retry time and will start connecting again (it will NOT re-read the config file). This is useful e.g. in a @t{/etc/ppp/if-up} script. 1543Closes/resets all connections, resets the retry time and will start connecting again (it will NOT re-read the config file). This is useful e.g. in a @t{/etc/ppp/if-up} script.
1505@refill 1544@refill
1506 1545
1507 1546
1508@item 1547@item
1509@b{TERM} 1548TERM
1510 1549
1511Closes/resets all connections and exits. 1550Closes/resets all connections and exits.
1512@refill 1551@refill
1513 1552
1514 1553
1515@item 1554@item
1516@b{USR1} 1555USR1
1517 1556
1518Dump current network status into the syslog (at loglevel @t{notice}, so make sure your loglevel allows this). 1557Dump current network status into the syslog (at loglevel @t{notice}, so make sure your loglevel allows this).
1519@refill 1558@refill
1520@end itemize 1559@end itemize
1521 1560
… …
1526 1565
1527@itemize 1566@itemize
1528 1567
1529 1568
1530@item 1569@item
1531@b{@t{/etc/gvpe/gvpe.conf}} 1570@t{/etc/gvpe/gvpe.conf}
1532 1571
1533The configuration file for @t{gvpe}. 1572The configuration file for @t{gvpe}.
1534@refill 1573@refill
1535 1574
1536 1575
1537@item 1576@item
1538@b{@t{/etc/gvpe/if-up}} 1577@t{/etc/gvpe/if-up}
1539 1578
1540Script which is executed as soon as the virtual network device has been allocated. Purpose is to further configure that device. 1579Script which is executed as soon as the virtual network device has been allocated. Purpose is to further configure that device.
1541@refill 1580@refill
1542 1581
1543 1582
1544@item 1583@item
1545@b{@t{/etc/gvpe/node-up}} 1584@t{/etc/gvpe/node-up}
1546 1585
1547Script which is executed whenever a node connects to this node. This can be used for example to run nsupdate. 1586Script which is executed whenever a node connects to this node. This can be used for example to run nsupdate.
1548@refill 1587@refill
1549 1588
1550 1589
1551@item 1590@item
1552@b{@t{/etc/gvpe/node-down}} 1591@t{/etc/gvpe/node-down}
1553 1592
1554Script which is executed whenever a connection to another node is lost. for example to run nsupdate. 1593Script which is executed whenever a connection to another node is lost. for example to run nsupdate.
1555@refill 1594@refill
1556 1595
1557 1596
1558@item 1597@item
1559@b{@t{/etc/gvpe/pubkey/*}} 1598@t{/etc/gvpe/pubkey/*}
1560 1599
1561The directory containing the public keys for every node, usually autogenerated by executing @t{gvpectrl --generate-keys}. 1600The directory containing the public keys for every node, usually autogenerated by executing @t{gvpectrl --generate-keys}.
1562@refill 1601@refill
1563 1602
1564 1603
1565@item 1604@item
1566@b{@t{/var/run/gvpe.pid}} 1605@t{/var/run/gvpe.pid}
1567 1606
1568The PID of the currently running @t{gvpe} is stored in this file. 1607The PID of the currently running @t{gvpe} is stored in this file.
1569@refill 1608@refill
1570@end itemize 1609@end itemize
1571 1610
… …
1592The first part of this document describes the transport protocols which are used by GVPE to send it's data packets over the network. 1631The first part of this document describes the transport protocols which are used by GVPE to send it's data packets over the network.
1593@refill 1632@refill
1594 1633
1595 1634
1596@section PART 1: Transport protocols 1635@section PART 1: Transport protocols
1597GVPE offers a range of transport protocols that can be used to interchange data between nodes. Protocols differ in their overhead, speed, reliability, and robustness. 1636GVPE offers a wide range of transport protocols that can be used to interchange data between nodes. Protocols differ in their overhead, speed, reliability, and robustness.
1598@refill 1637@refill
1599The following sections describe each transport protocol in more detail. They are sorted by overhead/efficiency, the most efficient transport is listed first: 1638The following sections describe each transport protocol in more detail. They are sorted by overhead/efficiency, the most efficient transport is listed first:
1600@refill 1639@refill
1601 1640
1602 1641
1603@subsection RAW IP 1642@subsection RAW IP
1604This protocol is the best choice, performance-wise, as the minimum overhead per packet is only 38 bytes. 1643This protocol is the best choice, performance-wise, as the minimum overhead per packet is only 38 bytes.
1605@refill 1644@refill
1606It works by sending the VPN payload using raw ip frames (using the protocol set by @t{ip-proto}). 1645It works by sending the VPN payload using raw IP frames (using the protocol set by @t{ip-proto}).
1607@refill 1646@refill
1608Using raw ip frames has the drawback that many firewalls block "unknown" protocols, so this transport only works if you have full IP connectivity between nodes. 1647Using raw IP frames has the drawback that many firewalls block "unknown" protocols, so this transport only works if you have full IP connectivity between nodes.
1609@refill 1648@refill
1610 1649
1611 1650
1612@subsection ICMP 1651@subsection ICMP
1613This protocol offers very low overhead (minimum 42 bytes), and can sometimes tunnel through firewalls when other protocols cannot. 1652This protocol offers very low overhead (minimum 42 bytes), and can sometimes tunnel through firewalls when other protocols can not.
1614@refill 1653@refill
1615It works by prepending a ICMP header with type @t{icmp-type} and a code of @t{255}. The default @t{icmp-type} is @t{echo-reply}, so the resulting packets look like echo replies, which looks rather strange to network admins. 1654It works by prepending an ICMP header with type @t{icmp-type} and a code of @t{255}. The default @t{icmp-type} is @t{echo-reply}, so the resulting packets look like echo replies, which looks rather strange to network administrators.
1616@refill 1655@refill
1617This transport should only be used if other transports (i.e. raw ip) are not available or undesirable (due to their overhead). 1656This transport should only be used if other transports (i.e. raw IP) are not available or undesirable (due to their overhead).
1618@refill 1657@refill
1619 1658
1620 1659
1621@subsection UDP 1660@subsection UDP
1622This is a good general choice for the transport protocol as UDP packets tunnel well through most firewalls and routers, and the overhead per packet is moderate (minimum 58 bytes). 1661This is a good general choice for the transport protocol as UDP packets tunnel well through most firewalls and routers, and the overhead per packet is moderate (minimum 58 bytes).
… …
1630@refill 1669@refill
1631It's only useful when tunneling through firewalls that block better protocols. If a node doesn't have direct internet access but a HTTP proxy that supports the CONNECT method it can be used to tunnel through a web proxy. For this to work, the @t{tcp-port} should be @t{443} (@t{https}), as most proxies do not allow connections to other ports. 1670It's only useful when tunneling through firewalls that block better protocols. If a node doesn't have direct internet access but a HTTP proxy that supports the CONNECT method it can be used to tunnel through a web proxy. For this to work, the @t{tcp-port} should be @t{443} (@t{https}), as most proxies do not allow connections to other ports.
1632@refill 1671@refill
1633It is an abuse of the usage a proxy was designed for, so make sure you are allowed to use it for GVPE. 1672It is an abuse of the usage a proxy was designed for, so make sure you are allowed to use it for GVPE.
1634@refill 1673@refill
1635This protocol also has server and client sides. If the @t{tcp-port} is set to zero, other nodes cannot connect to this node directly (and @t{tcp-port} zero cannot be used). If the @t{tcp-port} is non-zero, the node can act both as a client as well as a server. 1674This protocol also has server and client sides. If the @t{tcp-port} is set to zero, other nodes cannot connect to this node directly. If the @t{tcp-port} is non-zero, the node can act both as a client as well as a server.
1636@refill 1675@refill
1637 1676
1638 1677
1639@subsection DNS 1678@subsection DNS
1640@strong{WARNING:} Parsing and generating DNS packets is rather tricky. The code almost certainly contains buffer overflows and other, likely exploitable, bugs. You have been warned. 1679@strong{WARNING:} Parsing and generating DNS packets is rather tricky. The code almost certainly contains buffer overflows and other, likely exploitable, bugs. You have been warned.
1641@refill 1680@refill
1642This is the worst choice of transport protocol with respect to overhead (overhead can be 2-3 times higher than the transferred data), and latency (which can be many seconds). Some DNS servers might not be prepared to handle the traffic and drop or corrupt packets. The client also has to constantly poll the server for data, so the client will constantly create traffic even if it doesn't need to transport packets. 1681This is the worst choice of transport protocol with respect to overhead (overhead can be 2-3 times higher than the transferred data), and latency (which can be many seconds). Some DNS servers might not be prepared to handle the traffic and drop or corrupt packets. The client also has to constantly poll the server for data, so the client will constantly create traffic even if it doesn't need to transport packets.
1643@refill 1682@refill
1644In addition, the same problems as the TCP transport also plague this protocol. 1683In addition, the same problems as the TCP transport also plague this protocol.
1645@refill 1684@refill
1646Most configuration needs to be done by editing @t{src/vpn_dns.C} directly.
1647@refill
1648It's only use is to tunnel through firewalls that do not allow direct internet access. Similar to using a HTTP proxy (as the TCP transport does), it uses a local DNS server/forwarder (given by the @t{dns-forw-host} configuration value) as a proxy to send and receive data as a client, and a @t{NS} record pointing to the GVPE server (as given by the @t{dns-hostname} directive). 1685It's only use is to tunnel through firewalls that do not allow direct internet access. Similar to using a HTTP proxy (as the TCP transport does), it uses a local DNS server/forwarder (given by the @t{dns-forw-host} configuration value) as a proxy to send and receive data as a client, and an @t{NS} record pointing to the GVPE server (as given by the @t{dns-hostname} directive).
1649@refill 1686@refill
1650The only good side of this protocol is that it can tunnel through most firewalls undetected, iff the local DNS server/forwarder is sane (which is true for most routers, wlan gateways and nameservers). 1687The only good side of this protocol is that it can tunnel through most firewalls mostly undetected, iff the local DNS server/forwarder is sane (which is true for most routers, wireless LAN gateways and nameservers).
1688@refill
1689Fine-tuning needs to be done by editing @t{src/vpn_dns.C} directly.
1651@refill 1690@refill
1652 1691
1653 1692
1654@section PART 2: The GNU VPE protocol 1693@section PART 2: The GNU VPE protocol
1655This section, unfortunately, is not yet finished, although the protocol is stable (until bugs in the cryptography are found, which will likely completely change the following description). Nevertheless, it should give you some overview over the protocol. 1694This section, unfortunately, is not yet finished, although the protocol is stable (until bugs in the cryptography are found, which will likely completely change the following description). Nevertheless, it should give you some overview over the protocol.
1656@refill 1695@refill
1657 1696
1658 1697
1659@subsection Anatomy of a VPN packet 1698@subsection Anatomy of a VPN packet
1660The exact layout and field lengths of a VPN packet is determined at compiletime and doesn't change. The same structure is used for all transort protocols, be it RAWIP or TCP. 1699The exact layout and field lengths of a VPN packet is determined at compile time and doesn't change. The same structure is used for all transport protocols, be it RAWIP or TCP.
1661@refill 1700@refill
1662 1701
1663 1702
1664@example 1703@example
1665 +------+------+--------+------+ 1704 +------+------+--------+------+
… …
1669 1708
1670The HMAC field is present in all packets, even if not used (e.g. in auth request packets), in which case it is set to all zeroes. The checksum itself is calculated over the TYPE, SRCDST and DATA fields in all cases. 1709The HMAC field is present in all packets, even if not used (e.g. in auth request packets), in which case it is set to all zeroes. The checksum itself is calculated over the TYPE, SRCDST and DATA fields in all cases.
1671@refill 1710@refill
1672The TYPE field is a single byte and determines the purpose of the packet (e.g. RESET, COMPRESSED/UNCOMPRESSED DATA, PING, AUTH REQUEST/RESPONSE, CONNECT REQUEST/INFO etc.). 1711The TYPE field is a single byte and determines the purpose of the packet (e.g. RESET, COMPRESSED/UNCOMPRESSED DATA, PING, AUTH REQUEST/RESPONSE, CONNECT REQUEST/INFO etc.).
1673@refill 1712@refill
1674SRCDST is a three byte field which contains the source and destination node ids (12 bits each). The protocol does not yet scale well beyond 30+ hosts, since all hosts must connect to each other once on startup. But if restarts are rare or tolerable and most connections are on demand, much larger networks are feasible. 1713SRCDST is a three byte field which contains the source and destination node IDs (12 bits each).
1675@refill 1714@refill
1676The DATA portion differs between each packet type, naturally, and is the only part that can be encrypted. Data packets contain more fields, as shown: 1715The DATA portion differs between each packet type, naturally, and is the only part that can be encrypted. Data packets contain more fields, as shown:
1677@refill 1716@refill
1678 1717
1679 1718
… …
1683 +------+------+--------+------+-------+------+ 1722 +------+------+--------+------+-------+------+
1684@end example 1723@end example
1685 1724
1686RAND is a sequence of fully random bytes, used to increase the entropy of the data for encryption purposes. 1725RAND is a sequence of fully random bytes, used to increase the entropy of the data for encryption purposes.
1687@refill 1726@refill
1688SEQNO is a 32-bit sequence number. It is negotiated at every connection initialization and starts at some random 31 bit value. VPE currently uses a sliding window of 512 packets/sequence numbers to detect reordering, duplication and reply attacks. 1727SEQNO is a 32-bit sequence number. It is negotiated at every connection initialization and starts at some random 31 bit value. VPE currently uses a sliding window of 512 packets/sequence numbers to detect reordering, duplication and replay attacks.
1689@refill 1728@refill
1690 1729
1691 1730
1692@subsection The authentification protocol 1731@subsection The authentication protocol
1693Before hosts can exchange packets, they need to establish authenticity of the other side and a key. Every host has a private RSA key and the public RSA keys of all other hosts. 1732Before nodes can exchange packets, they need to establish authenticity of the other side and a key. Every node has a private RSA key and the public RSA keys of all other nodes.
1694@refill 1733@refill
1695A host establishes a simplex connection by sending the other host a RSA encrypted challenge containing a random challenge (consisting of the encryption key to use when sending packets, more random data and PKCS1_OAEP padding) and a random 16 byte "challenge-id" (used to detect duplicate auth packets). The destination host will respond by replying with an (unencrypted) RIPEMD160 hash of the decrypted challenge, which will authentify that host. The destination host will also set the outgoing encryption parameters as given in the packet. 1734A host establishes a simplex connection by sending the other node an RSA encrypted challenge containing a random challenge (consisting of the encryption key to use when sending packets, more random data and PKCS1_OAEP padding) and a random 16 byte "challenge-id" (used to detect duplicate auth packets). The destination node will respond by replying with an (unencrypted) RIPEMD160 hash of the decrypted challenge, which will authenticate that node. The destination node will also set the outgoing encryption parameters as given in the packet.
1696@refill 1735@refill
1697When the source host receives a correct auth reply (by verifying the hash and the id, which will expire after 120 seconds), it will start to accept data packets from the destination host. 1736When the source node receives a correct auth reply (by verifying the hash and the id, which will expire after 120 seconds), it will start to accept data packets from the destination node.
1698@refill 1737@refill
1699This means that a host can only initate a simplex connection, telling the other side the key it has to use when it sends packets. The challenge reply is only used to set the current IP address of the other side and protocol parameters. 1738This means that a node can only initiate a simplex connection, telling the other side the key it has to use when it sends packets. The challenge reply is only used to set the current IP address of the other side and protocol parameters.
1700@refill 1739@refill
1701This protocol is completely symmetric, so to be able to send packets the destination host must send a challenge in the exact same way as already described (so, in essence, two simplex connections are created per host pair). 1740This protocol is completely symmetric, so to be able to send packets the destination node must send a challenge in the exact same way as already described (so, in essence, two simplex connections are created per node pair).
1702@refill 1741@refill
1703 1742
1704 1743
1705@subsection Retrying 1744@subsection Retrying
1706When there is no response to an auth request, the host will send auth requests in bursts with an exponential backoff. After some time it will resort to PING packets, which are very small (8 bytes) and lightweight (no RSA operations required). A host that receives ping requests from an unconnected peer will respond by trying to create a connection. 1745When there is no response to an auth request, the node will send auth requests in bursts with an exponential back-off. After some time it will resort to PING packets, which are very small (8 bytes + protocol header) and lightweight (no RSA operations required). A node that receives ping requests from an unconnected peer will respond by trying to create a connection.
1707@refill 1746@refill
1708In addition to the exponential backoff, there is a global rate-limit on a per-IP base. It allows long bursts but will limit total packet rate to something like one control packet every ten seconds, to avoid accidental floods due to protocol problems (like a RSA key file mismatch between two hosts). 1747In addition to the exponential back-off, there is a global rate-limit on a per-IP base. It allows long bursts but will limit total packet rate to something like one control packet every ten seconds, to avoid accidental floods due to protocol problems (like a RSA key file mismatch between two nodes).
1748@refill
1749The intervals between retries are limited by the @t{max-retry} configuration value. A node with @t{connect} = @t{always} will always retry, a node with @t{connect} = @t{ondemand} will only try (and re-try) to connect as long as there are packets in the queue, usually this limits the retry period to @t{max-ttl} seconds.
1750@refill
1751Sending packets over the VPN will reset the retry intervals as well, which means as long as somebody is trying to send packets to a given node, GVPE will try to connect every few seconds.
1709@refill 1752@refill
1710 1753
1711 1754
1712@subsection Routing and Protocol translation 1755@subsection Routing and Protocol translation
1713The gvpe routing algorithm is easy: there isn't any routing. GVPE always tries to establish direct connections, if the protocol abilities of the two hosts allow it. 1756The GVPE routing algorithm is easy: there isn't much routing to speak of: When routing packets to another node, GVPE trues the following options, in order:
1714@refill 1757@refill
1715If the two hosts should be able to reach each other (common protocol, ip and port all known), but cannot (network down), then there will be no connection, point. 1758
1716@refill 1759
1760@itemize
1761
1762
1763@item
1764If the two nodes should be able to reach each other directly (common protocol, port known), then GVPE will send the packet directly to the other node.
1765
1766
1767
1768@item
1769If this isn't possible (e.g. because the node doesn't have a @t{hostname} or known port), but the nodes speak a common protocol and a router is available, then GVPE will ask a router to "mediate" between both nodes (see below).
1770
1771
1772
1773@item
1774If a direct connection isn't possible (no common protocols) or forbidden (@t{deny-direct}) and there are any routers, then GVPE will try to send packets to the router with the highest priority that is connected already @emph{and} is able (as specified by the config file) to connect directly to the target node.
1775
1776
1777
1778@item
1779If no such router exists, then GVPE will simply send the packet to the node with the highest priority available.
1780
1781
1782
1783@item
1784Failing all that, the packet will be dropped.
1785
1786@end itemize
1787
1717A host can usually declare itself unreachable directly by setting it's port number(s) to zero. It can declare other hosts as unreachable by using a config-file that disables all protocols for these other hosts. 1788A host can usually declare itself unreachable directly by setting it's port number(s) to zero. It can declare other hosts as unreachable by using a config-file that disables all protocols for these other hosts. Another option is to disable all protocols on that host in the other config files.
1718@refill 1789@refill
1719If two hosts cannot connect to each other because their IP address(es) are not known (such as dialup hosts), one side will send a connection request to a router (routers must be configured to act as routers!), which will send both the originating and the destination host a connection info request with protocol information and IP address of the other host (if known). Both hosts will then try to establish a connection to the other peer, which is usually possible even when both hosts are behind a NAT gateway. 1790If two hosts cannot connect to each other because their IP address(es) are not known (such as dial-up hosts), one side will send a @emph{mediated} connection request to a router (routers must be configured to act as routers!), which will send both the originating and the destination host a connection info request with protocol information and IP address of the other host (if known). Both hosts will then try to establish a direct connection to the other peer, which is usually possible even when both hosts are behind a NAT gateway.
1720@refill 1791@refill
1721If the hosts cannot reach each other because they have no common protocol, the originator instead use the router with highest priority and matching protocol as peer. Since the SRCDST field is not encrypted, the router host can just forward the packet to the destination host. Since each host uses it's own private key, the router will not be able to decrypt or encrypt packets, it will just act as a simple router and protocol translator. 1792Routing via other nodes works because the SRCDST field is not encrypted, so the router can just forward the packet to the destination host. Since each host uses it's own private key, the router will not be able to decrypt or encrypt packets, it will just act as a simple router and protocol translator.
1722@refill
1723When no router is connected, the host will aggressively try to connect to all routers, and if a router is asked for an unconnected host it will try to ask another router to establish the connection.
1724@refill
1725... more not yet written about the details of the routing, please bug me ...
1726@refill 1793@refill
1727 1794
1728 1795
1729 1796
1730@node Simple Example,Complex Example,gvpe.protocol,Top 1797@node Simple Example,Complex Example,gvpe.protocol,Top
… …
1739@example 1806@example
1740 enable-udp = yes # use UDP 1807 enable-udp = yes # use UDP
1741 udp-port = 407 # use this UDP port 1808 udp-port = 407 # use this UDP port
1742 mtu = 1492 # handy for TDSL 1809 mtu = 1492 # handy for TDSL
1743 ifname = vpn0 # I prefer vpn0 over e.g. tap0 1810 ifname = vpn0 # I prefer vpn0 over e.g. tap0
1744@end example
1745 1811
1746
1747
1748@example
1749 node = huffy # arbitrary node name 1812 node = huffy # arbitrary node name
1750 hostname = 1.2.3.4 # ip address if this host 1813 hostname = 1.2.3.4 # ip address if this host
1751@end example
1752 1814
1753
1754
1755@example
1756 node = welshy 1815 node = welshy
1757 hostname = www.example.net # resolve at connection time 1816 hostname = www.example.net # resolve at connection time
1758@end example
1759 1817
1760
1761
1762@example
1763 node = wheelery 1818 node = wheelery
1764 # no hostname, will be determinded dynamically using router1 or router2 1819 # no hostname, will be determinded dynamically using router1 or router2
1765@end example 1820@end example
1766 1821
1767@t{gvpe} will execute the @t{if-up} script on every hosts, which, for linux, could look like this for all three hosts: 1822@t{gvpe} will execute the @t{if-up} script on every hosts, which, for linux, could look like this for all three hosts:

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines