[ViewVC] Diff of: cvs/gvpe/doc/gvpe.texi

Comparing gvpe/doc/gvpe.texi (file contents):
Revision 1.4 by pcg, Mon Sep 1 05:31:28 2008 UTC vs.
Revision 1.7 by root, Wed Mar 30 04:02:50 2016 UTC

…		…
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	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
…		…
98		98
99	@itemize	99	@itemize
100		100
101		101
102	@item	102	@item
103
104	@cindex Virtual
105	Virtual	103	Virtual
106		104
107	Virtual 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.	105	Virtual 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
109	Usually 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.	107	Usually 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
115	@cindex Private
116	Private	112	Private
117		113
118	Private 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.	114	Private 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
120	In 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.	116	In 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
126	@cindex Network
127	Network	121	Network
128		122
129	Network 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.	123	Network 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
131	GVPE 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.	125	GVPE 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
…		…
162	@end itemize	156	@end itemize
163		157
164		158
165		159
166	@section PROGRAMS	160	@section PROGRAMS
167	Vpe comes with two programs: one daemon (@t{gvpe}) and one control program (@t{gvpectrl}).	161	Gvpe 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	gvpectrl	169	gvpectrl
176		170
177	Is used to generate the keys, check and give an overview of of the configuration and contorl the daemon (restarting etc.).	171	This 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	gvpe	176	gvpe
183		177
184	Is the daemon used to establish and maintain connections to the other network members. It should be run on the gateway machine.	178	This 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
191	Please have a look at the @t{gvpe.osdep(5)} manpage for platform-specific information.	185	Please have a look at the @t{gvpe.osdep(5)} manpage for platform-specific information.
192	@refill	186	@refill
		187	Gvpe 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
193	Here are a few recipes for compiling your gvpe, showing the extremes (fast, small, insecure OR slow, large, more secure), between you should choose:	189	Here 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
204	Minimize 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.	200	Minimize 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 almost trivial.
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
215	Use the fastest cipher and digest algorithms currently available in gvpe. MD4 has been broken and is quite insecure, though.	211	Use 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=12 --enable-digest=ripemd610
224	@end example	220	@end example
225		221
226	This 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.	222	This 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 12 bytes of random data.
227	@refill	223	@refill
228	In 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).	224	In 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
233	In this section I will describe how to get a simple VPN consisting of three hosts up and running.	229	In 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
238	First 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.	234	First 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
240	Put the following lines into @t{/etc/gvpe/gvpe.conf}:	236	Put 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
271	The 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}):	255	The 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
284	This 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.	268	This 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
286	By 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.	270	By 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
291	Run the following command to generate all key pairs (that might take a while):	275	Run 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
…		…
299	This command will put the public keys into @t{/etc/gvpe/pubkeys/@emph{nodename}} and the private keys into @t{/etc/gvpe/hostkeys/@emph{nodename}}.	283	This 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
304	Now 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	288	Now 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
		290	The example uses rsync-over-ssh
305	@refill	291	@refill
306	First all the config files without the hostkeys should be distributed:	292	First 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
326	You should now check the configration by issuing the command @t{gvpectrl -c /etc/gvpe -s} on each node and verify it's output.	312	You 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
331	You should then start gvpe on each node by issuing a command like:	317	You 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
339	This 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 ;).	325	This 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
341	If this works you should check your networking setup by pinging various endpoints.	327	If this works you should check your networking setup by pinging various endpoints.
342	@refill	328	@refill
343	To 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:	329	To 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
…		…
376	This file tries to capture OS-dependent configuration or build issues, quirks and platform limitations, as known.	362	This 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
381	Most 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.	367	Most 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
383	This 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.	369	This 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
385	On 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.	371	On 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
549	The 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.	535	The 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
551	See @t{tincd/netbsd} for more information.	537	See @t{tincd/netbsd} for more information.
552	@refill	538	@refill
553	Completely unstested so far.	539	Completely untested so far.
554	@refill	540	@refill
555		541
556		542
557	@subsection tincd/mingw	543	@subsection tincd/mingw
558	TAP-device; see @t{native/cygwin} for more information.	544	TAP-device; see @t{native/cygwin} for more information.
…		…
569	Completely untested so far.	555	Completely untested so far.
570	@refill	556	@refill
571		557
572		558
573	@subsection tincd/uml_socket	559	@subsection tincd/uml_socket
574	TAP-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.	560	TAP-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
576	No 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.	562	No 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
578	Completely untested so far.	564	Completely 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
629		607
630	@section DESCRIPTION	608	@section DESCRIPTION
631	The 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.	609	The 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
633	The 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.	611	All settings are applied "in order", that is, later settings of the same variable overwrite earlier ones.
634	@refill	612	@refill
		613	The only exceptions to the above are the following directives:
		614	@refill
635		615
636		616
		617	@itemize
		618
		619
		620	@item
		621	node nodename
		622
		623	Introduces a node section. The nodename is used to select the right configuration section and is the same string as is passed as an argument to the gvpe daemon.
		624	@refill
		625	Multiple @t{node} statements with the same node name are supported and will be merged together.
		626	@refill
		627
		628
		629	@item
		630	global
		631
		632	This statement switches back to the global section, which is mainly useful if you want to include a second config file, e..g for local customisations. To do that, simply include this at the very end of your config file:
		633	@refill
		634
		635
		636	@example
		637	global
		638	include local.conf
637	@example	639	@end example
638	name = value	640
		641
		642
		643	@item
		644	on nodename ...
		645
		646
		647
		648	@item
		649	on !nodename ...
		650
		651	You can prefix any configuration directive with @t{on} and a nodename. GVPE will will only "execute" it on the named node, or (if the nodename starts with @t{!}) on all nodes except the named one.
		652	@refill
		653	Example: set the MTU to @t{1450} everywhere, @t{loglevel} to @t{noise} on @t{branch1}, and @t{connect} to @t{ondemand} everywhere but on branch2.
		654	@refill
		655
		656
		657	@example
		658	mtu = 1450
639	on branch1 loglevel = noise	659	on branch1 loglevel = noise
640	on !branch2 connect = ondemand	660	on !branch2 connect = ondemand
641	@end example	661	@end example
642		662
643	All settings are executed "in order", that is, later settings of the same variable overwrite earlier ones.	663
		664
		665	@item
		666	include relative-or-absolute-path
		667
		668	Reads the specified file (the path must not contain whitespace or @t{=} characters) and evaluate all config directives in it as if they were spelled out in place of the @t{include} directive.
644	@refill	669	@refill
		670	The path is a printf format string, that is, you must escape any @t{%} by doubling it, and you can have a single @t{%s} inside, which will be replaced by the current nodename.
		671	@refill
		672	Relative paths are interpreted relative to the GVPE config directory.
		673	@refill
		674	Example: include the file @file{local.conf} in the config directory on every node.
		675	@refill
		676
		677
		678	@example
		679	include local.conf
		680	@end example
		681
		682	Example: include a file @file{conf/}nodename@file{.conf}
		683	@refill
		684
		685
		686	@example
		687	include conf/%s.conf
		688	@end example
		689
		690	@end itemize
		691
645		692
646		693
647	@section ANATOMY OF A CONFIG FILE	694	@section ANATOMY OF A CONFIG FILE
648	Usually, 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.	695	Usually, 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	696	@refill
650	Every 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.	697	Every 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	698	@refill
652	Node-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.	699	Node-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	700	@refill
…		…
663		710
664	@itemize	711	@itemize
665		712
666		713
667	@item	714	@item
		715	chroot = path or /
		716
		717	@cindex chroot
		718	Tells GVPE to chroot(2) to the specified path after reading all necessary files, binding to sockets and running the @t{if-up} script, but before running @t{node-up} or any other scripts.
		719	@refill
		720	The special path @file{/} instructs GVPE to create (and remove) an empty temporary directory to use as new root. This is most secure, but makes it impossible to use any scripts other than the @t{if-up} one.
		721	@refill
		722
		723
		724	@item
		725	chuid = numerical-uid
		726
		727	@cindex chuid
		728
		729
		730	@item
		731	chgid = numerical-gid
		732
		733	@cindex chgid
		734	These two options tell GVPE to change to the given user and/or group id after reading all necessary files, binding to sockets and running the @t{if-up} script.
		735	@refill
		736	Other scripts, such as @t{node-up}, are run with the new user id or group id.
		737	@refill
		738
		739
		740	@item
		741	chuser = username
		742
		743	@cindex chuser
		744	Alternative to @t{chuid} and @t{chgid}: Sets both @t{chuid} and @t{chgid} to the user and (primary) group ids of the specified user (for example, @t{nobody}).
		745	@refill
		746
		747
		748	@item
668	dns-forw-host = hostname/ip	749	dns-forw-host = hostname/ip
669		750
670	@cindex dns-forw-host	751	@cindex dns-forw-host
671	The dns server to forward dns requests to for the DNS tunnel protocol (default: @t{127.0.0.1}, changing it is highly recommended).	752	The 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	753	@refill
673		754
674		755
675	@item	756	@item
676	dns-forw-port = port-number	757	dns-forw-port = port-number
…		…
679	The port where the @t{dns-forw-host} is to be contacted (default: @t{53}, which is fine in most cases).	760	The port where the @t{dns-forw-host} is to be contacted (default: @t{53}, which is fine in most cases).
680	@refill	761	@refill
681		762
682		763
683	@item	764	@item
		765	dns-case-preserving = yes\|true\|on \| no\|false\|off
		766
		767	@cindex dns-case-preserving
		768	Sets whether the DNS transport forwarding server preserves case (DNS servers have to, but some access systems are even more broken than others) (default: true).
		769	@refill
		770	Normally, when the forwarding server changes the case of domain names then GVPE will automatically set this to false.
		771	@refill
		772
		773
		774	@item
684	dns-max-outstanding = integer-number-of-requests	775	dns-max-outstanding = integer-number-of-requests
685		776
686	@cindex dns-max-outstanding	777	@cindex dns-max-outstanding
687	The 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.	778	The 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	779	@refill
689	The default should be working ok for most links.	780	The default should be working OK for most links.
690	@refill	781	@refill
691		782
692		783
693	@item	784	@item
694	dns-overlap-factor = float	785	dns-overlap-factor = float
695		786
696	@cindex dns-overlap-factor	787	@cindex dns-overlap-factor
697	The 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.	788	The 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	789	@refill
699	For congested or picky dns forwarders you could use a value nearer to or exceeding @t{1}.	790	For congested or picky DNS forwarders you could use a value nearer to or exceeding @t{1}.
700	@refill	791	@refill
701	The default should be working ok for most links.	792	The default should be working OK for most links.
702	@refill	793	@refill
703		794
704		795
705	@item	796	@item
706	dns-send-interval = send-interval-in-seconds	797	dns-send-interval = send-interval-in-seconds
707		798
708	@cindex dns-send-interval	799	@cindex dns-send-interval
709	The 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.	800	The 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	801	@refill
711	The default should be working ok for most links.	802	The default should be working OK for most links.
712	@refill	803	@refill
713		804
714		805
715	@item	806	@item
716	dns-timeout-factor = float	807	dns-timeout-factor = float
…		…
718	@cindex dns-timeout-factor	809	@cindex dns-timeout-factor
719	Factor 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.	810	Factor 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	811	@refill
721	For 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.	812	For 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	813	@refill
723	The default should be working ok for most links but will result in low throughput if packet loss is high.	814	The default should be working OK for most links but will result in low throughput if packet loss is high.
724	@refill	815	@refill
725		816
726		817
727	@item	818	@item
728	if-up = relative-or-absolute-path	819	if-up = relative-or-absolute-path
729		820
730	@cindex if-up	821	@cindex if-up
731	Sets 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).	822	Sets 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	823	@refill
733	Variables that have the same value on all nodes:	824	Variables that have the same value on all nodes:
734	@refill	825	@refill
735		826
736		827
…		…
802	MAC=fe:fd:80:00:00:01	893	MAC=fe:fd:80:00:00:01
803		894
804	@cindex MAC	895	@cindex MAC
805	The MAC address the network interface has to use.	896	The MAC address the network interface has to use.
806	@refill	897	@refill
807	Might 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.	898	Might 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	899	@refill
809		900
810		901
811	@item	902	@item
812	NODENAME=branch1	903	NODENAME=branch1
…		…
836	[ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME	927	[ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME
837	[ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME	928	[ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME
838	ip route add 10.0.0.0/8 dev $IFNAME	929	ip route add 10.0.0.0/8 dev $IFNAME
839	@end example	930	@end example
840		931
841	More complicated examples (using routing to reduce arp traffic) can be found in the etc/ subdirectory of the distribution.	932	More complicated examples (using routing to reduce ARP traffic) can be found in the @file{etc/} subdirectory of the distribution.
842	@refill	933	@refill
843		934
844		935
845	@item	936	@item
846	ifname = devname	937	ifname = devname
…		…
862	ip-proto = numerical-ip-protocol	953	ip-proto = numerical-ip-protocol
863		954
864	@cindex ip-proto	955	@cindex ip-proto
865	Sets 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.	956	Sets 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	957	@refill
867	The 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)	958	The 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).
		959	@refill
		960	Many 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).
868	@refill	961	@refill
869		962
870		963
871	@item	964	@item
872	http-proxy-host = hostname/ip	965	http-proxy-host = hostname/ip
…		…
874	@cindex http-proxy-host	967	@cindex http-proxy-host
875	The @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.	968	The @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	969	@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.	970	@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	971	@refill
879	Please 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.	972	Please 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	973	@refill
881	To 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).	974	To 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	975	@refill
883	If you have a router, connecting to it will suffice. Otherwise tcp must be enabled on all nodes.	976	If you have a router, connecting to it will suffice. Otherwise TCP must be enabled on all nodes.
884	@refill	977	@refill
885	Example:	978	Example:
886	@refill	979	@refill
887		980
888		981
…		…
904		997
905	@item	998	@item
906	http-proxy-auth = login:password	999	http-proxy-auth = login:password
907		1000
908	@cindex http-proxy-auth	1001	@cindex http-proxy-auth
909	The optional login and password used to authenticate to the proxy server, seperated by a literal colon (@t{:}). Only basic authentication is currently supported.	1002	The 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	1003	@refill
911		1004
912		1005
913	@item	1006	@item
914	keepalive = seconds	1007	keepalive = seconds
915		1008
916	@cindex keepalive	1009	@cindex keepalive
917	Sets 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.	1010	Sets 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	1011	@refill
919		1012
920		1013
921	@item	1014	@item
922	loglevel = noise\|trace\|debug\|info\|notice\|warn\|error\|critical	1015	loglevel = noise\|trace\|debug\|info\|notice\|warn\|error\|critical
…		…
928		1021
929	@item	1022	@item
930	mtu = bytes	1023	mtu = bytes
931		1024
932	@cindex mtu	1025	@cindex mtu
933	Sets 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.	1026	Sets 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	1027	@refill
935	Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp).	1028	Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp).
936	@refill	1029	@refill
937	This value must be the minimum of the mtu values of all nodes.	1030	This value must be the minimum of the MTU values of all nodes.
938	@refill	1031	@refill
939		1032
940		1033
941	@item	1034	@item
942	node = nickname	1035	nfmark = integer
943		1036
944	@cindex node	1037	@cindex nfmark
945	Not 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.	1038	This 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.
946	@refill	1039	@refill
		1040	This 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:
		1041	@refill
		1042
		1043
		1044	@example
		1045	ip rule add not fwmark 1000 lookup 99
		1046	@end example
		1047
947		1048
948		1049
949	@item	1050	@item
950	node-up = relative-or-absolute-path	1051	node-up = relative-or-absolute-path
951		1052
952	@cindex node-up	1053	@cindex node-up
953	Sets 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.	1054	Sets 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.
954	@refill	1055	@refill
955	In addition to all the variables passed to @t{if-up} scripts, the following environment variables will be set:	1056	In addition to all the variables passed to @t{if-up} scripts, the following environment variables will be set (values are just examples):
956	@refill	1057	@refill
957		1058
958		1059
959	@itemize	1060	@itemize
960		1061
…		…
974	The node id of the remote node.	1075	The node id of the remote node.
975	@refill	1076	@refill
976		1077
977		1078
978	@item	1079	@item
		1080	DESTSI=rawip/88.99.77.55:0
		1081
		1082	@cindex DESTSI
		1083	The "socket info" of the target node, protocol dependent but usually in the format protocol/ip:port.
		1084	@refill
		1085
		1086
		1087	@item
979	DESTIP=188.13.66.8	1088	DESTIP=188.13.66.8
980		1089
981	@cindex DESTIP	1090	@cindex DESTIP
982	The numerical IP address of the remote node (gvpe accepts connections from everywhere, as long as the other node can authenticate itself).	1091	The numerical IP address of the remote node (gvpe accepts connections from everywhere, as long as the other node can authenticate itself).
983	@refill	1092	@refill
…		…
985		1094
986	@item	1095	@item
987	DESTPORT=655 # deprecated	1096	DESTPORT=655 # deprecated
988		1097
989	@cindex DESTPORT	1098	@cindex DESTPORT
990	The UDP port used by the other side.	1099	The protocol port used by the other side, if applicable.
991	@refill	1100	@refill
992		1101
993		1102
994	@item	1103	@item
995	STATE=UP	1104	STATE=up
996		1105
997	@cindex STATE	1106	@cindex STATE
998	Node-up scripts get called with STATE=UP, node-down scripts get called with STATE=DOWN.	1107	Node-up scripts get called with STATE=up, node-change scripts get called with STATE=change and node-down scripts get called with STATE=down.
999	@refill	1108	@refill
1000	@end itemize	1109	@end itemize
1001		1110
1002	Here is a nontrivial example that uses nsupdate to update the name => ip mapping in some dns zone:	1111	Here is a nontrivial example that uses nsupdate to update the name => ip mapping in some DNS zone:
1003	@refill	1112	@refill
1004		1113
1005		1114
1006	@example	1115	@example
1007	#!/bin/sh	1116	#!/bin/sh
1008	@{	1117	@{
1009	echo update delete $DESTNODE.lowttl.example.net. a	1118	echo update delete $DESTNODE.lowttl.example.net. a
1010	echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP	1119	echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP
1011	echo	1120	echo
1012	@} \| nsupdate -d -k $CONFBASE:key.example.net.	1121	@} \| nsupdate -d -k $CONFBASE:key.example.net.
1013	@end example	1122	@end example
1014		1123
		1124
		1125
		1126	@item
		1127	node-change = relative-or-absolute-path
		1128
		1129	@cindex node-change
		1130	Same as @t{node-change}, but gets called whenever something about a connection changes (such as the source IP address).
		1131	@refill
1015		1132
1016		1133
1017	@item	1134	@item
1018	node-down = relative-or-absolute-path	1135	node-down = relative-or-absolute-path
1019		1136
…		…
1024		1141
1025	@item	1142	@item
1026	pid-file = path	1143	pid-file = path
1027		1144
1028	@cindex pid-file	1145	@cindex pid-file
1029	The path to the pid file to check and create (default: @t{LOCALSTATEDIR/run/gvpe.pid}).	1146	The path to the pid file to check and create (default: @t{LOCALSTATEDIR/run/gvpe.pid}). The first @t{%s} is replaced by the nodename - any other use of @t{%} must be written as @t{%%}.
1030	@refill	1147	@refill
1031		1148
1032		1149
1033	@item	1150	@item
1034	private-key = relative-path-to-key	1151	private-key = relative-path-to-key
1035		1152
1036	@cindex private-key	1153	@cindex private-key
1037	Sets 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.	1154	Sets 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.
1038	@refill	1155	@refill
1039	Since only the private key file of the current node is used and the private key file should be kept secret per-node to avoid spoofings, it is not recommended to use this feature.	1156	Since 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.
1040	@refill	1157	@refill
1041		1158
1042		1159
1043	@item	1160	@item
1044	rekey = seconds	1161	rekey = seconds
1045		1162
1046	@cindex rekey	1163	@cindex rekey
1047	Sets the rekeying interval in seconds (default: @t{3600}). Connections are reestablished every @t{rekey} seconds.	1164	Sets the rekeying interval in seconds (default: @t{3607}). Connections are reestablished every @t{rekey} seconds, making them use a new encryption key.
		1165	@refill
		1166
		1167
		1168	@item
		1169	seed-device = path
		1170
		1171	@cindex seed-device
		1172	The random device used to initially and regularly seed the random number generator (default: @file{/dev/urandom}). Randomness is of paramount importance to the security of the algorithms used in gvpe.
		1173	@refill
		1174	On program start and every seed-interval, gvpe will read 64 octets.
		1175	@refill
		1176	Setting this path to the empty string will disable this functionality completely (the underlying crypto library will likely look for entropy sources on it's own though, so not all is lost).
		1177	@refill
		1178
		1179
		1180	@item
		1181	seed-interval = seconds
		1182
		1183	@cindex seed-interval
		1184	The number of seconds between reseeds of the random number generator (default: @t{3613}). A value of @t{0} disables this regular reseeding.
		1185	@refill
		1186
		1187
		1188	@item
		1189	serial = string
		1190
		1191	@cindex serial
		1192	The configuration serial number. This can be any string up to 16 bytes length. Only when the serial matches on both sides of a conenction will the connection succeed. This is @emph{not} a security mechanism and eay to spoof, this mechanism exists to alert users that their config is outdated.
		1193	@refill
		1194	It's recommended to specify this is a date string such as @t{2013-05-05} or @t{20121205084417}.
		1195	@refill
		1196	The exact algorithm is as this: if a connection request is received form a node with an identical serial, then it succeeds normally.
		1197	@refill
		1198	If the remote serial is lower than the local serial, it is ignored.
		1199	@refill
		1200	If the remote serial is higher than the local serial, a warning message is logged.
1048	@refill	1201	@refill
1049	@end itemize	1202	@end itemize
1050		1203
1051		1204
1052		1205
…		…
1068		1221
1069	@item	1222	@item
1070	compress = yes\|true\|on \| no\|false\|off	1223	compress = yes\|true\|on \| no\|false\|off
1071		1224
1072	@cindex compress	1225	@cindex compress
1073	Wether to compress data packets sent to this node (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.	1226	For 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.
1074	@refill	1227	@refill
1075		1228
1076		1229
1077	@item	1230	@item
1078	connect = ondemand \| never \| always \| disabled	1231	connect = ondemand \| never \| always \| disabled
…		…
1088	deny-direct = nodename \| *	1241	deny-direct = nodename \| *
1089		1242
1090	@cindex deny-direct	1243	@cindex deny-direct
1091	Deny 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.	1244	Deny 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.
1092	@refill	1245	@refill
1093	Sometimes, 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).	1246	Sometimes, 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).
1094	@refill	1247	@refill
1095	The algorithm to check wether a connection may be direct is as follows:	1248	The algorithm to check whether a connection may be direct is as follows:
1096	@refill	1249	@refill
1097	1. Other node mentioned in a @t{allow-direct}? If yes, allow the connection.	1250	1. Other node mentioned in an @t{allow-direct}? If yes, allow the connection.
1098	@refill	1251	@refill
1099	2. Other node mentioned in a @t{deny-direct}? If yes, deny direct connections.	1252	2. Other node mentioned in a @t{deny-direct}? If yes, deny direct connections.
1100	@refill	1253	@refill
1101	3. Allow the connection.	1254	3. Allow the connection.
1102	@refill	1255	@refill
…		…
1162	enable-icmp = yes\|true\|on \| no\|false\|off	1315	enable-icmp = yes\|true\|on \| no\|false\|off
1163		1316
1164	@cindex enable-icmp	1317	@cindex enable-icmp
1165	See gvpe.protocol(7) for a description of the ICMP transport protocol.	1318	See gvpe.protocol(7) for a description of the ICMP transport protocol.
1166	@refill	1319	@refill
1167	Enable the ICMP transport using icmp packets of type @t{icmp-type} on this node.	1320	Enable the ICMP transport using ICMP packets of type @t{icmp-type} on this node.
1168	@refill	1321	@refill
1169		1322
1170		1323
1171	@item	1324	@item
1172	enable-rawip = yes\|true\|on \| no\|false\|off	1325	enable-rawip = yes\|true\|on \| no\|false\|off
…		…
1192	enable-udp = yes\|true\|on \| no\|false\|off	1345	enable-udp = yes\|true\|on \| no\|false\|off
1193		1346
1194	@cindex enable-udp	1347	@cindex enable-udp
1195	See gvpe.protocol(7) for a description of the UDP transport protocol.	1348	See gvpe.protocol(7) for a description of the UDP transport protocol.
1196	@refill	1349	@refill
1197	Enable 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).	1350	Enable the UDPv4 transport using the @t{udp-port} port (default: @t{no}).
1198	@refill
1199	NOTE: 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.
1200	@refill	1351	@refill
1201		1352
1202		1353
1203	@item	1354	@item
1204	hostname = hostname \| ip [can not be defaulted]	1355	hostname = hostname \| ip [can not be defaulted]
1205		1356
1206	@cindex hostname	1357	@cindex hostname
1207	Forces 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.	1358	Forces 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.
		1359	@refill
		1360	Note that DNS resolving is done synchronously, pausing the daemon. If that is an issue you need to specify IP addresses.
1208	@refill	1361	@refill
1209		1362
1210		1363
1211	@item	1364	@item
1212	icmp-type = integer	1365	icmp-type = integer
1213		1366
1214	@cindex icmp-type	1367	@cindex icmp-type
1215	Sets the type value to be used for outgoing (and incoming) packets sent via the ICMP transport.	1368	Sets the type value to be used for outgoing (and incoming) packets sent via the ICMP transport.
1216	@refill	1369	@refill
1217	The 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.	1370	The 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.
1218	@refill	1371	@refill
1219		1372
1220		1373
1221	@item	1374	@item
1222	if-up-data = value	1375	if-up-data = value
…		…
1228		1381
1229	@item	1382	@item
1230	inherit-tos = yes\|true\|on \| no\|false\|off	1383	inherit-tos = yes\|true\|on \| no\|false\|off
1231		1384
1232	@cindex inherit-tos	1385	@cindex inherit-tos
1233	Wether 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.	1386	Whether 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.
		1387	@refill
		1388
		1389
		1390	@item
		1391	low-power = yes\|true\|on \| no\|false\|off
		1392
		1393	@cindex low-power
		1394	If true, designates a node as a low-power node. Low-power nodes use larger timeouts and try to reduce cpu time. Other nodes talking to a low-power node will also use larger timeouts, and will use less aggressive optimisations, in the hope of reducing load. Security is not compromised.
		1395	@refill
		1396	The typical low-power node would be a mobile phone, where wakeups and encryption can significantly increase power drain.
1234	@refill	1397	@refill
1235		1398
1236		1399
1237	@item	1400	@item
1238	max-retry = positive-number	1401	max-retry = positive-number
1239		1402
1240	@cindex max-retry	1403	@cindex max-retry
1241	The 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.	1404	The 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.
1242	@refill	1405	@refill
1243		1406
1244		1407
1245	@item	1408	@item
1246	max-ttl = seconds	1409	max-ttl = seconds
…		…
1301		1464
1302	@itemize	1465	@itemize
1303		1466
1304		1467
1305	@item	1468	@item
1306
1307	@cindex gvpe.conf
1308	gvpe.conf	1469	gvpe.conf
1309		1470
1310	The config file.	1471	The config file.
1311	@refill	1472	@refill
1312		1473
1313		1474
1314	@item	1475	@item
1315
1316	@cindex if-up
1317	if-up	1476	if-up
1318		1477
1319	The if-up script	1478	The if-up script
1320	@refill	1479	@refill
1321		1480
1322		1481
1323	@item	1482	@item
1324		1483	node-up, node-down
1325	@cindex node-up
1326	node-up,
1327	@cindex node-down
1328	node-down
1329		1484
1330	If used the node up or node-down scripts.	1485	If used the node up or node-down scripts.
1331	@refill	1486	@refill
1332		1487
1333		1488
1334	@item	1489	@item
1335
1336	@cindex hostkey
1337	hostkey	1490	hostkey
1338		1491
1339	The private key (taken from @t{hostkeys/nodename}) of the current host.	1492	The (default path of the) private key of the current host.
1340	@refill	1493	@refill
1341		1494
1342		1495
1343	@item	1496	@item
1344
1345	@cindex pubkey/nodename
1346	pubkey/nodename	1497	pubkey/nodename
1347		1498
1348	The public keys of the other nodes, one file per node.	1499	The public keys of the other nodes, one file per node.
1349	@refill	1500	@refill
1350	@end itemize	1501	@end itemize
…		…
1385		1536
1386		1537
1387	@item	1538	@item
1388	@strong{-g}, @strong{--generate-keys}	1539	@strong{-g}, @strong{--generate-keys}
1389		1540
1390	Generate public/private RSA keypair and exit.	1541	Generate public/private RSA key-pair and exit.
1391	@refill	1542	@refill
1392		1543
1393		1544
1394	@item	1545	@item
1395	@strong{-q}, @strong{--quiet}	1546	@strong{-q}, @strong{--quiet}
…		…
1447	@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...}]	1598	@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...}]
1448	@refill	1599	@refill
1449		1600
1450		1601
1451	@section DESCRIPTION	1602	@section DESCRIPTION
1452	See the gvpe(5) manpage for an introduction to the gvpe suite.	1603	See the gvpe(5) man page for an introduction to the gvpe suite.
1453	@refill	1604	@refill
1454	This 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.	1605	This 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}
		1606	@refill
		1607	It 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.
1455	@refill	1608	@refill
1456	The optional arguments after the node name have to be of the form:	1609	The optional arguments after the node name have to be of the form:
1457	@refill	1610	@refill
1458		1611
1459		1612
1460	@example	1613	@example
1461	[I<nodename>.]var=value	1614	[I<nodename>.]var=value
1462	@end example	1615	@end example
1463		1616
1464	If 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.	1617	If 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.
1465	@refill	1618	@refill
1466	For 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:	1619	For 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:
1467	@refill	1620	@refill
1468		1621
1469		1622
…		…
1510		1663
1511		1664
1512	@item	1665	@item
1513	@strong{-L}, @strong{--mlock}	1666	@strong{-L}, @strong{--mlock}
1514		1667
1515	Lock @t{gvpe} into main memory. This will prevent sensitive data like shared private keys to be written to the system swap files/partitions.	1668	Lock @t{gvpe} into main memory. This will prevent sensitive data like shared private keys to be written to the system swap files/partitions.
1516	@refill	1669	@refill
1517		1670
1518		1671
1519	@item	1672	@item
1520	@strong{--version}	1673	@strong{--version}
…		…
1620		1773
1621		1774
1622	@section Overview	1775	@section Overview
1623	GVPE can make use of a number of protocols. One of them is the GNU VPE protocol which is used to authenticate tunnels and send encrypted data packets. This protocol is described in more detail the second part of this document.	1776	GVPE can make use of a number of protocols. One of them is the GNU VPE protocol which is used to authenticate tunnels and send encrypted data packets. This protocol is described in more detail the second part of this document.
1624	@refill	1777	@refill
1625	The first part of this document describes the transport protocols which are used by GVPE to send it's data packets over the network.	1778	The first part of this document describes the transport protocols which are used by GVPE to send its data packets over the network.
1626	@refill	1779	@refill
1627		1780
1628		1781
1629	@section PART 1: Transport protocols	1782	@section PART 1: Transport protocols
1630	GVPE 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.	1783	GVPE 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.
…		…
1634		1787
1635		1788
1636	@subsection RAW IP	1789	@subsection RAW IP
1637	This protocol is the best choice, performance-wise, as the minimum overhead per packet is only 38 bytes.	1790	This protocol is the best choice, performance-wise, as the minimum overhead per packet is only 38 bytes.
1638	@refill	1791	@refill
1639	It works by sending the VPN payload using raw ip frames (using the protocol set by @t{ip-proto}).	1792	It works by sending the VPN payload using raw IP frames (using the protocol set by @t{ip-proto}).
1640	@refill	1793	@refill
1641	Using 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.	1794	Using 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.
1642	@refill	1795	@refill
1643		1796
1644		1797
1645	@subsection ICMP	1798	@subsection ICMP
1646	This protocol offers very low overhead (minimum 42 bytes), and can sometimes tunnel through firewalls when other protocols can not.	1799	This protocol offers very low overhead (minimum 42 bytes), and can sometimes tunnel through firewalls when other protocols can not.
1647	@refill	1800	@refill
1648	It 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 admins.	1801	It 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.
1649	@refill	1802	@refill
1650	This transport should only be used if other transports (i.e. raw ip) are not available or undesirable (due to their overhead).	1803	This transport should only be used if other transports (i.e. raw IP) are not available or undesirable (due to their overhead).
1651	@refill	1804	@refill
1652		1805
1653		1806
1654	@subsection UDP	1807	@subsection UDP
1655	This 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).	1808	This 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).
…		…
1657	It should be used if RAW IP is not available.	1810	It should be used if RAW IP is not available.
1658	@refill	1811	@refill
1659		1812
1660		1813
1661	@subsection TCP	1814	@subsection TCP
1662	This protocol is a very bad choice, as it not only has high overhead (more than 60 bytes), but the transport also retries on it's own, which leads to congestion when the link has moderate packet loss (as both the TCP transport and the tunneled traffic will retry, increasing congestion more and more). It also has high latency and is quite inefficient.	1815	This protocol is a very bad choice, as it not only has high overhead (more than 60 bytes), but the transport also retries on its own, which leads to congestion when the link has moderate packet loss (as both the TCP transport and the tunneled traffic will retry, increasing congestion more and more). It also has high latency and is quite inefficient.
1663	@refill	1816	@refill
1664	It'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.	1817	It'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.
1665	@refill	1818	@refill
1666	It is an abuse of the usage a proxy was designed for, so make sure you are allowed to use it for GVPE.	1819	It is an abuse of the usage a proxy was designed for, so make sure you are allowed to use it for GVPE.
1667	@refill	1820	@refill
…		…
1674	@refill	1827	@refill
1675	This 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.	1828	This 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.
1676	@refill	1829	@refill
1677	In addition, the same problems as the TCP transport also plague this protocol.	1830	In addition, the same problems as the TCP transport also plague this protocol.
1678	@refill	1831	@refill
1679	It'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).	1832	Its 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).
1680	@refill	1833	@refill
1681	The 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, WLAN gateways and nameservers).	1834	The 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).
1682	@refill	1835	@refill
1683	Finetuning needs to be done by editing @t{src/vpn_dns.C} directly.	1836	Fine-tuning needs to be done by editing @t{src/vpn_dns.C} directly.
1684	@refill	1837	@refill
1685		1838
1686		1839
1687	@section PART 2: The GNU VPE protocol	1840	@section PART 2: The GNU VPE protocol
1688	This 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.	1841	This 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.
1689	@refill	1842	@refill
1690		1843
1691		1844
1692	@subsection Anatomy of a VPN packet	1845	@subsection Anatomy of a VPN packet
1693	The 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.	1846	The 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.
1694	@refill	1847	@refill
1695		1848
1696		1849
1697	@example	1850	@example
1698	+------+------+--------+------+	1851	+------+------+--------+------+
1699	\| HMAC \| TYPE \| SRCDST \| DATA \|	1852	\| HMAC \| TYPE \| SRCDST \| DATA \|
1700	+------+------+--------+------+	1853	+------+------+--------+------+
1701	@end example	1854	@end example
1702		1855
1703	The 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.	1856	The 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 MAC itself is calculated over the TYPE, SRCDST and DATA fields in all cases.
1704	@refill	1857	@refill
1705	The 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.).	1858	The 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.).
1706	@refill	1859	@refill
1707	SRCDST is a three byte field which contains the source and destination node IDs (12 bits each).	1860	SRCDST is a three byte field which contains the source and destination node IDs (12 bits each).
1708	@refill	1861	@refill
1709	The DATA portion differs between each packet type, naturally, and is the only part that can be encrypted. Data packets contain more fields, as shown:	1862	The DATA portion differs between each packet type, naturally, and is the only part that can be encrypted. Data packets contain more fields, as shown:
1710	@refill	1863	@refill
1711		1864
1712		1865
1713	@example	1866	@example
1714	+------+------+--------+------+-------+------+	1867	+------+------+--------+-------+------+
1715	\| HMAC \| TYPE \| SRCDST \| RAND \| SEQNO \| DATA \|	1868	\| HMAC \| TYPE \| SRCDST \| SEQNO \| DATA \|
1716	+------+------+--------+------+-------+------+	1869	+------+------+--------+-------+------+
1717	@end example	1870	@end example
1718		1871
1719	RAND is a sequence of fully random bytes, used to increase the entropy of the data for encryption purposes.
1720	@refill
1721	SEQNO 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.	1872	SEQNO is a 32-bit sequence number. It is negotiated at every connection initialization and starts at some random 31 bit value. GVPE currently uses a sliding window of 512 packets/sequence numbers to detect reordering, duplication and replay attacks.
1722	@refill	1873	@refill
		1874	The encryption is done on SEQNO+DATA in CTR mode with IV generated from the seqno (for AES: seqno \|\| seqno \|\| seqno \|\| (u32)0), which ensures uniqueness for a given key.
		1875	@refill
1723		1876
1724		1877
1725	@subsection The authentication protocol	1878	@subsection The authentication/key exchange protocol
1726	Before 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.	1879	Before 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.
1727	@refill	1880	@refill
1728	A host establishes a simplex connection by sending the other host 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 host will respond by replying with an (unencrypted) RIPEMD160 hash of the decrypted challenge, which will authenticate that host. The destination host will also set the outgoing encryption parameters as given in the packet.	1881	When a node wants to establish a connection to another node, it sends an RSA-OEAP-encrypted challenge and an ECDH (curve25519) key. The other node replies with its own ECDH key and a HKDF of the challenge and both ECDH keys to prove its identity.
1729	@refill	1882	@refill
1730	When 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.	1883	The remote node enganges in exactly the same protocol. When both nodes have exchanged their challenge and verified the response, they calculate a cipher key and a HMAC key and start exchanging data packets.
1731	@refill	1884	@refill
1732	This 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.	1885	In detail, the challenge consist of:
1733	@refill	1886	@refill
1734	This 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).	1887
		1888
		1889	@example
		1890	RSA-OAEP (SEQNO MAC CIPHER SALT EXTRA-AUTH) ECDH1
		1891	@end example
		1892
		1893	That is, it encrypts (with the public key of the remote node) an initial sequence number for data packets, key material for the HMAC key, key material for the cipher key, a salt used by the HKDF (as shown later) and some extra random bytes that are unused except for authentication. It also sends the public key of a curve25519 exchange.
		1894	@refill
		1895	The remote node decrypts the RSA data, generates its own ECDH key (ECDH2), and replies with:
		1896	@refill
		1897
		1898
		1899	@example
		1900	HKDF-Expand (HKDF-Extract (ECDH2, RSA), ECDH1, AUTH_DIGEST_SIZE) ECDH2
		1901	@end example
		1902
		1903	That is, it extracts from the decrypted RSA challenge, using its ECDH key as salt, and then expands using the requesting node's ECDH1 key. The resulting hash is returned as a proof that the node could decrypt the RSA challenge data, together with the ECDH key.
		1904	@refill
		1905	After both nodes have done this to each other, they calculate the shared ECDH secret, cipher and HMAC keys for the session (each node generates two cipher and HMAC keys, one for sending and one for receiving).
		1906	@refill
		1907	The HMAC key for sending is generated as follow:
		1908	@refill
		1909
		1910
		1911	@example
		1912	HMAC_KEY = HKDF-Expand (HKDF-Extract (REMOTE_SALT, MAC ECDH_SECRET), info, HMAC_MD_SIZE)
		1913	@end example
		1914
		1915	It extracts from MAC and ECDH_SECRET using the @emph{remote} SALT, then expands using a static info string.
		1916	@refill
		1917	The cipher key is generated in the same way, except using the CIPHER part of the original challenge.
		1918	@refill
		1919	The result of this process is to authenticate each node to the other node, while exchanging keys using both RSA and ECDH, the latter providing perfect forward secrecy.
		1920	@refill
		1921	The protocol has been overdesigned where this was possible without increasing implementation complexity, in an attempt to protect against implementation or protocol failures. For example, if the ECDH challenge was found to be flawed, perfect forward secrecy would be lost, but the data would likely still be protected. Likewise, standard algorithms and implementations are used where possible.
1735	@refill	1922	@refill
1736		1923
1737		1924
1738	@subsection Retrying	1925	@subsection Retrying
1739	When 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 + protocol header) and lightweight (no RSA operations required). A host that receives ping requests from an unconnected peer will respond by trying to create a connection.	1926	When 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.
1740	@refill	1927	@refill
1741	In 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).	1928	In 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).
1742	@refill	1929	@refill
1743	The 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.	1930	The 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.
1744	@refill	1931	@refill
1745	Sending 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.	1932	Sending 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.
1746	@refill	1933	@refill
1747		1934
1748		1935
1749	@subsection Routing and Protocol translation	1936	@subsection Routing and Protocol translation
1750	The 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:	1937	The GVPE routing algorithm is easy: there isn't much routing to speak of: When routing packets to another node, GVPE tries the following options, in order:
1751	@refill	1938	@refill
1752		1939
1753		1940
1754	@itemize	1941	@itemize
1755		1942
1756		1943
1757	@item	1944	@item
1758	If the two hosts should be able to reach each other directly (common protocol, port known), then GVPE will send the packet directly to the other node.	1945	If 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.
1759		1946
1760		1947
1761		1948
1762	@item	1949	@item
1763	If 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).	1950	If 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).
…		…
1777	@item	1964	@item
1778	Failing all that, the packet will be dropped.	1965	Failing all that, the packet will be dropped.
1779		1966
1780	@end itemize	1967	@end itemize
1781		1968
1782	A 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.	1969	A host can usually declare itself unreachable directly by setting its 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.
1783	@refill	1970	@refill
1784	If two hosts cannot connect to each other because their IP address(es) are not known (such as dialup 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.	1971	If 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.
1785	@refill	1972	@refill
1786	Routing 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.	1973	Routing 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 its 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.
1787	@refill	1974	@refill
1788		1975
1789		1976
1790		1977
1791	@node Simple Example,Complex Example,gvpe.protocol,Top	1978	@node Simple Example,Complex Example,gvpe.protocol,Top
…		…
1800	@example	1987	@example
1801	enable-udp = yes # use UDP	1988	enable-udp = yes # use UDP
1802	udp-port = 407 # use this UDP port	1989	udp-port = 407 # use this UDP port
1803	mtu = 1492 # handy for TDSL	1990	mtu = 1492 # handy for TDSL
1804	ifname = vpn0 # I prefer vpn0 over e.g. tap0	1991	ifname = vpn0 # I prefer vpn0 over e.g. tap0
1805	@end example
1806		1992
1807
1808
1809	@example
1810	node = huffy # arbitrary node name	1993	node = huffy # arbitrary node name
1811	hostname = 1.2.3.4 # ip address if this host	1994	hostname = 1.2.3.4 # ip address if this host
1812	@end example
1813		1995
1814
1815
1816	@example
1817	node = welshy	1996	node = welshy
1818	hostname = www.example.net # resolve at connection time	1997	hostname = www.example.net # resolve at connection time
1819	@end example
1820		1998
1821
1822
1823	@example
1824	node = wheelery	1999	node = wheelery
1825	# no hostname, will be determinded dynamically using router1 or router2	2000	# no hostname, will be determinded dynamically using router1 or router2
1826	@end example	2001	@end example
1827		2002
1828	@t{gvpe} will execute the @t{if-up} script on every hosts, which, for linux, could look like this for all three hosts:	2003	@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

Comparing gvpe/doc/gvpe.texi (file contents): Revision 1.4 by pcg, Mon Sep 1 05:31:28 2008 UTC vs. Revision 1.7 by root, Wed Mar 30 04:02:50 2016 UTC

Diff Legend

Comparing gvpe/doc/gvpe.texi (file contents):
Revision 1.4 by pcg, Mon Sep 1 05:31:28 2008 UTC vs.
Revision 1.7 by root, Wed Mar 30 04:02:50 2016 UTC