ViewVC Help

View File | Revision Log | Show Annotations | Download File

/cvs/gvpe/doc/gvpe.texi

Comparing gvpe/doc/gvpe.texi (file contents):
Revision 1.1 by pcg, Wed Jan 18 13:15:07 2006 UTC vs.
Revision 1.6 by root, Wed Jun 18 20:40:52 2014 UTC

…		…
18	* gvpe: (gvpe). The GNU VPE Manual.	18	* gvpe: (gvpe). The GNU VPE Manual.
19	@end direntry	19	@end direntry
20		20
21	This is the info manual for vpe, the Virtual Private Ethernet daemon.	21	This is the info manual for vpe, the Virtual Private Ethernet daemon.
22		22
23	Copyright @copyright{} 2003-2005 Marc Lehmann <gvpe@@schmorp.de>.	23	Copyright @copyright{} 2003-2008 Marc Lehmann <gvpe@@schmorp.de>.
24		24
25	Permission is granted to make and distribute verbatim copies of this	25	Permission is granted to make and distribute verbatim copies of this
26	manual provided the copyright notice and this permission notice are	26	manual provided the copyright notice and this permission notice are
27	preserved on all copies.	27	preserved 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
44	Copyright @copyright{} 2003-2005 Marc Lehmann <gvpe@@schmorp.de>.	44	Copyright @copyright{} 2003-2008 Marc Lehmann <gvpe@@schmorp.de>.
45		45
46	Permission is granted to make and distribute verbatim copies of this	46	Permission is granted to make and distribute verbatim copies of this
47	manual provided the copyright notice and this permission notice are	47	manual provided the copyright notice and this permission notice are
48	preserved on all copies.	48	preserved on all copies.
49		49
…		…
98		98
99	@itemize	99	@itemize
100		100
101		101
102	@item	102	@item
103	@b{
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	@b{
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	@b{
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
…		…
139		133
140	@itemize	134	@itemize
141		135
142		136
143	@item	137	@item
144	@b{SIMPLE DESIGN}	138	SIMPLE DESIGN
145		139
146	Cipher, 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.	140	Cipher, 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}	145	EASY TO SETUP
152		146
153	A 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.	147	A 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}	152	MAC-BASED SECURITY
159		153
160	Since 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.	154	Since 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
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	@b{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	@b{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 hosts. 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
654		701
655		702
…		…
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	@b{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	@b{dns-forw-port = port-number}	757	dns-forw-port = port-number
677		758
678	@cindex dns-forw-port	759	@cindex dns-forw-port
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	@b{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	@b{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	@b{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	@b{dns-timeout-factor = float}	807	dns-timeout-factor = float
717		808
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.	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	@b{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
737	@itemize	828	@itemize
738		829
739		830
740	@item	831	@item
741	@b{CONFBASE=/etc/gvpe}	832	CONFBASE=/etc/gvpe
742		833
743	@cindex CONFBASE	834	@cindex CONFBASE
744	The configuration base directory.	835	The configuration base directory.
745	@refill	836	@refill
746		837
747		838
748	@item	839	@item
749	@b{IFNAME=vpn0}	840	IFNAME=vpn0
750		841
751	@cindex IFNAME	842	@cindex IFNAME
752	The network interface to initialize.	843	The network interface to initialize.
753	@refill	844	@refill
754		845
755		846
756	@item	847	@item
757	@b{IFTYPE=native # or tincd}	848	IFTYPE=native # or tincd
758		849
759	@cindex IFTYPE	850	@cindex IFTYPE
760		851
761		852
762	@item	853	@item
763	@b{IFSUBTYPE=linux # or freebsd, darwin etc..}	854	IFSUBTYPE=linux # or freebsd, darwin etc..
764		855
765	@cindex IFSUBTYPE	856	@cindex IFSUBTYPE
766	The 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.	857	The 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	858	@refill
768		859
769		860
770	@item	861	@item
771	@b{MTU=1436}	862	MTU=1436
772		863
773	@cindex MTU	864	@cindex MTU
774	The MTU to set the interface to. You can use lower values (if done consistently on all hosts), but this is usually ineffective.	865	The 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	866	@refill
776		867
777		868
778	@item	869	@item
779	@b{NODES=5}	870	NODES=5
780		871
781	@cindex NODES	872	@cindex NODES
782	The number of nodes in this GVPE network.	873	The number of nodes in this GVPE network.
783	@refill	874	@refill
784	@end itemize	875	@end itemize
…		…
789		880
790	@itemize	881	@itemize
791		882
792		883
793	@item	884	@item
794	@b{IFUPDATA=string}	885	IFUPDATA=string
795		886
796	@cindex IFUPDATA	887	@cindex IFUPDATA
797	The value of the configuration directive @t{if-up-data}.	888	The value of the configuration directive @t{if-up-data}.
798	@refill	889	@refill
799		890
800		891
801	@item	892	@item
802	@b{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	@b{NODENAME=branch1}	903	NODENAME=branch1
813		904
814	@cindex NODENAME	905	@cindex NODENAME
815	The nickname of the node.	906	The nickname of the node.
816	@refill	907	@refill
817		908
818		909
819	@item	910	@item
820	@b{NODEID=1}	911	NODEID=1
821		912
822	@cindex NODEID	913	@cindex NODEID
823	The 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.	914	The 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	915	@refill
825	@end itemize	916	@end itemize
…		…
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	@b{ifname = devname}	937	ifname = devname
847		938
848	@cindex ifname	939	@cindex ifname
849	Sets the tun interface name to the given name. The default is OS-specific and most probably something like @t{tun0}.	940	Sets the tun interface name to the given name. The default is OS-specific and most probably something like @t{tun0}.
850	@refill	941	@refill
851		942
852		943
853	@item	944	@item
854	@b{ifpersist = yes|true|on | no|false|off}	945	ifpersist = yes|true|on | no|false|off
855		946
856	@cindex ifpersist	947	@cindex ifpersist
857	Should 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.	948	Should 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	949	@refill
859		950
860		951
861	@item	952	@item
862	@b{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 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.	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).
868	@refill	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).
		961	@refill
869		962
870		963
871	@item	964	@item
872	@b{http-proxy-host = hostname/ip}	965	http-proxy-host = hostname/ip
873		966
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 hosts) 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 hosts.	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
…		…
893	@end example	986	@end example
894		987
895		988
896		989
897	@item	990	@item
898	@b{http-proxy-port = proxy-tcp-port}	991	http-proxy-port = proxy-tcp-port
899		992
900	@cindex http-proxy-port	993	@cindex http-proxy-port
901	The port where your proxy server listens.	994	The port where your proxy server listens.
902	@refill	995	@refill
903		996
904		997
905	@item	998	@item
906	@b{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	@b{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	@b{loglevel = noise|trace|debug|info|notice|warn|error|critical}	1015	loglevel = noise|trace|debug|info|notice|warn|error|critical
923		1016
924	@cindex loglevel	1017	@cindex loglevel
925	Set the logging level. Connection established messages are logged at level @t{info}, notable errors are logged with @t{error}. Default is @t{info}.	1018	Set 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	1019	@refill
927		1020
928		1021
929	@item	1022	@item
930	@b{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 hosts.	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	@b{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
947		1042
948		1043
		1044	@example
		1045	ip rule add not fwmark 1000 lookup 99
		1046	@end example
		1047
		1048
		1049
949	@item	1050	@item
950	@b{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: 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:	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.
		1055	@refill
		1056	In addition to all the variables passed to @t{if-up} scripts, the following environment variables will be set (values are just examples):
954	@refill	1057	@refill
955		1058
956		1059
957	@itemize	1060	@itemize
958		1061
959		1062
960	@item	1063	@item
961	@b{DESTNODE=branch2}	1064	DESTNODE=branch2
962		1065
963	@cindex DESTNODE	1066	@cindex DESTNODE
964	The name of the remote node.	1067	The name of the remote node.
965	@refill	1068	@refill
966		1069
967		1070
968	@item	1071	@item
969	@b{DESTID=2}	1072	DESTID=2
970		1073
971	@cindex DESTID	1074	@cindex DESTID
972	The node id of the remote node.	1075	The node id of the remote node.
973	@refill	1076	@refill
974		1077
975		1078
976	@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
977	@b{DESTIP=188.13.66.8}	1088	DESTIP=188.13.66.8
978		1089
979	@cindex DESTIP	1090	@cindex DESTIP
980	The numerical IP address of the remote host (gvpe accepts connections from everywhere, as long as the other host 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).
981	@refill	1092	@refill
982		1093
983		1094
984	@item	1095	@item
985	@b{DESTPORT=655 # deprecated}	1096	DESTPORT=655 # deprecated
986		1097
987	@cindex DESTPORT	1098	@cindex DESTPORT
988	The UDP port used by the other side.	1099	The protocol port used by the other side, if applicable.
989	@refill	1100	@refill
990		1101
991		1102
992	@item	1103	@item
993	@b{STATE=UP}	1104	STATE=up
994		1105
995	@cindex STATE	1106	@cindex STATE
996	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.
997	@refill	1108	@refill
998	@end itemize	1109	@end itemize
999		1110
1000	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:
1001	@refill	1112	@refill
1002		1113
1003		1114
1004	@example	1115	@example
1005	#!/bin/sh	1116	#!/bin/sh
1006	@{	1117	@{
1007	echo update delete $DESTNODE.lowttl.example.net. a	1118	echo update delete $DESTNODE.lowttl.example.net. a
1008	echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP	1119	echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP
1009	echo	1120	echo
1010	@} | nsupdate -d -k $CONFBASE:key.example.net.	1121	@} | nsupdate -d -k $CONFBASE:key.example.net.
1011	@end example	1122	@end example
1012		1123
1013		1124
1014		1125
1015	@item	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
		1132
		1133
		1134	@item
1016	@b{node-down = relative-or-absolute-path}	1135	node-down = relative-or-absolute-path
1017		1136
1018	@cindex node-down	1137	@cindex node-down
1019	Same as @t{node-up}, but gets called whenever a connection is lost.	1138	Same as @t{node-up}, but gets called whenever a connection is lost.
1020	@refill	1139	@refill
1021		1140
1022		1141
1023	@item	1142	@item
1024	@b{pid-file = path}	1143	pid-file = path
1025		1144
1026	@cindex pid-file	1145	@cindex pid-file
1027	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{%%}.
1028	@refill	1147	@refill
1029		1148
1030		1149
1031	@item	1150	@item
1032	@b{private-key = relative-path-to-key}	1151	private-key = relative-path-to-key
1033		1152
1034	@cindex private-key	1153	@cindex private-key
1035	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.
1036	@refill	1155	@refill
1037	Since 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.	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.
1038	@refill	1157	@refill
1039		1158
1040		1159
1041	@item	1160	@item
1042	@b{rekey = seconds}	1161	rekey = seconds
1043		1162
1044	@cindex rekey	1163	@cindex rekey
1045	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.
1046	@refill	1201	@refill
1047	@end itemize	1202	@end itemize
1048		1203
1049		1204
1050		1205
…		…
1055		1210
1056	@itemize	1211	@itemize
1057		1212
1058		1213
1059	@item	1214	@item
1060	@b{allow-direct = nodename}	1215	allow-direct = nodename
1061		1216
1062	@cindex allow-direct	1217	@cindex allow-direct
1063	Allow direct connections to this node. See @t{deny-direct} for more info.	1218	Allow direct connections to this node. See @t{deny-direct} for more info.
1064	@refill	1219	@refill
1065		1220
1066		1221
1067	@item	1222	@item
1068	@b{compress = yes|true|on | no|false|off}	1223	compress = yes|true|on | no|false|off
1069		1224
1070	@cindex compress	1225	@cindex compress
1071	Wether 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.	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.
1072	@refill	1227	@refill
1073		1228
1074		1229
1075	@item	1230	@item
1076	@b{connect = ondemand | never | always | disabled}	1231	connect = ondemand | never | always | disabled
1077		1232
1078	@cindex connect	1233	@cindex connect
1079	Sets 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).	1234	Sets 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	1235	@refill
		1236	Routers will automatically be forced to @t{always} unless they are @t{disabled}, to ensure all nodes can talk to each other.
		1237	@refill
1081		1238
1082		1239
1083	@item	1240	@item
1084	@b{deny-direct = nodename | *}	1241	deny-direct = nodename | *
1085		1242
1086	@cindex deny-direct	1243	@cindex deny-direct
1087	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.
1088	@refill	1245	@refill
1089	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).
1090	@refill	1247	@refill
1091	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:
1092	@refill	1249	@refill
1093	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.
1094	@refill	1251	@refill
1095	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.
1096	@refill	1253	@refill
1097	3. Allow the connection.	1254	3. Allow the connection.
1098	@refill	1255	@refill
1099	That is, @t{allow-direct} takes precende over @t{deny-direct}.	1256	That is, @t{allow-direct} takes precedence over @t{deny-direct}.
1100	@refill	1257	@refill
1101	The 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.	1258	The 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	1259	@refill
1103		1260
1104		1261
1105	@item	1262	@item
1106	@b{dns-domain = domain-suffix}	1263	dns-domain = domain-suffix
1107		1264
1108	@cindex dns-domain	1265	@cindex dns-domain
1109	The DNS domain suffix that points to the DNS tunnel server for this node.	1266	The DNS domain suffix that points to the DNS tunnel server for this node.
1110	@refill	1267	@refill
1111	The domain must point to a NS record that points to the @emph{dns-hostname}, i.e.	1268	The domain must point to a NS record that points to the @emph{dns-hostname}, i.e.
…		…
1127	@end example	1284	@end example
1128		1285
1129		1286
1130		1287
1131	@item	1288	@item
1132	@b{dns-hostname = hostname/ip}	1289	dns-hostname = hostname/ip
1133		1290
1134	@cindex dns-hostname	1291	@cindex dns-hostname
1135	The 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.	1292	The 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	1293	@refill
1137		1294
1138		1295
1139	@item	1296	@item
1140	@b{dns-port = port-number}	1297	dns-port = port-number
1141		1298
1142	@cindex dns-port	1299	@cindex dns-port
1143	The port to bind the DNS tunnel socket to. Must be @t{53} on DNS tunnel servers.	1300	The port to bind the DNS tunnel socket to. Must be @t{53} on DNS tunnel servers.
1144	@refill	1301	@refill
1145		1302
1146		1303
1147	@item	1304	@item
1148	@b{enable-dns = yes|true|on | no|false|off}	1305	enable-dns = yes|true|on | no|false|off
1149		1306
1150	@cindex enable-dns	1307	@cindex enable-dns
1151	See gvpe.protocol(7) for a description of the DNS transport protocol. Avoid this protocol if you can.	1308	See gvpe.protocol(7) for a description of the DNS transport protocol. Avoid this protocol if you can.
1152	@refill	1309	@refill
1153	Enable 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.	1310	Enable 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	1311	@refill
1155		1312
1156		1313
1157	@item	1314	@item
1158	@b{enable-icmp = yes|true|on | no|false|off}	1315	enable-icmp = yes|true|on | no|false|off
1159		1316
1160	@cindex enable-icmp	1317	@cindex enable-icmp
1161	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.
1162	@refill	1319	@refill
1163	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.
1164	@refill	1321	@refill
1165		1322
1166		1323
1167	@item	1324	@item
1168	@b{enable-rawip = yes|true|on | no|false|off}	1325	enable-rawip = yes|true|on | no|false|off
1169		1326
1170	@cindex enable-rawip	1327	@cindex enable-rawip
1171	See gvpe.protocol(7) for a description of the RAW IP transport protocol.	1328	See gvpe.protocol(7) for a description of the RAW IP transport protocol.
1172	@refill	1329	@refill
1173	Enable the RAW IPv4 transport using the @t{ip-proto} protocol (default: @t{no}).	1330	Enable the RAW IPv4 transport using the @t{ip-proto} protocol (default: @t{no}).
1174	@refill	1331	@refill
1175		1332
1176		1333
1177	@item	1334	@item
1178	@b{enable-tcp = yes|true|on | no|false|off}	1335	enable-tcp = yes|true|on | no|false|off
1179		1336
1180	@cindex enable-tcp	1337	@cindex enable-tcp
1181	See gvpe.protocol(7) for a description of the TCP transport protocol.	1338	See gvpe.protocol(7) for a description of the TCP transport protocol.
1182	@refill	1339	@refill
1183	Enable 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.	1340	Enable 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	1341	@refill
1185		1342
1186		1343
1187	@item	1344	@item
1188	@b{enable-udp = yes|true|on | no|false|off}	1345	enable-udp = yes|true|on | no|false|off
1189		1346
1190	@cindex enable-udp	1347	@cindex enable-udp
1191	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.
1192	@refill	1349	@refill
1193	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}).
1194	@refill	1351	@refill
1195	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.
1196	@refill
1197		1352
1198		1353
1199	@item	1354	@item
1200	@b{hostname = hostname | ip [can not be defaulted]}	1355	hostname = hostname | ip [can not be defaulted]
1201		1356
1202	@cindex hostname	1357	@cindex hostname
1203	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.
1204	@refill	1359	@refill
		1360	Note that DNS resolving is done synchronously, pausing the daemon. If that is an issue you need to specify IP addresses.
		1361	@refill
1205		1362
1206		1363
1207	@item	1364	@item
1208	@b{icmp-type = integer}	1365	icmp-type = integer
1209		1366
1210	@cindex icmp-type	1367	@cindex icmp-type
1211	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.
1212	@refill	1369	@refill
1213	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.
1214	@refill	1371	@refill
1215		1372
1216		1373
1217	@item	1374	@item
1218	@b{if-up-data = value}	1375	if-up-data = value
1219		1376
1220	@cindex if-up-data	1377	@cindex if-up-data
1221	The value specified using this directive will be passed to the @t{if-up} script in the environment variable @t{IFUPDATA}.	1378	The value specified using this directive will be passed to the @t{if-up} script in the environment variable @t{IFUPDATA}.
1222	@refill	1379	@refill
1223		1380
1224		1381
1225	@item	1382	@item
1226	@b{inherit-tos = yes|true|on | no|false|off}	1383	inherit-tos = yes|true|on | no|false|off
1227		1384
1228	@cindex inherit-tos	1385	@cindex inherit-tos
1229	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.
1230	@refill	1387	@refill
1231		1388
1232		1389
1233	@item	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.
		1397	@refill
		1398
		1399
		1400	@item
1234	@b{max-retry = positive-number}	1401	max-retry = positive-number
1235		1402
1236	@cindex max-retry	1403	@cindex max-retry
1237	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.
1238	@refill	1405	@refill
1239		1406
1240		1407
1241	@item	1408	@item
		1409	max-ttl = seconds
		1410
		1411	@cindex max-ttl
		1412	Expire 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.
		1413	@refill
		1414
		1415
		1416	@item
		1417	max-queue = positive-number>=1
		1418
		1419	@cindex max-queue
		1420	The 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.
		1421	@refill
		1422
		1423
		1424	@item
1242	@b{router-priority = 0 | 1 | positive-number>=2}	1425	router-priority = 0 | 1 | positive-number>=2
1243		1426
1244	@cindex router-priority	1427	@cindex router-priority
1245	Sets 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.	1428	Sets the router priority of the given node (default: @t{0}, disabled).
1246	@refill	1429	@refill
1247	Make sure all hosts always connect (@t{connect = always}) to the router hosts, otherwise connecting to them might be impossible.	1430	If 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	1431	@refill
1249	The 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.	1432	The 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	1433	@refill
		1434	The 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).
		1435	@refill
		1436	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.
		1437	@refill
		1438	Nodes with @t{router-priority} set to @t{2} or higher will always be forced to @t{connect} = @t{always} (unless they are @t{disabled}).
		1439	@refill
1251		1440
1252		1441
1253	@item	1442	@item
1254	@b{tcp-port = port-number}	1443	tcp-port = port-number
1255		1444
1256	@cindex tcp-port	1445	@cindex tcp-port
1257	Similar to @t{udp-port} (default: @t{655}), but sets the TCP port number.	1446	Similar to @t{udp-port} (default: @t{655}), but sets the TCP port number.
1258	@refill	1447	@refill
1259		1448
1260		1449
1261	@item	1450	@item
1262	@b{udp-port = port-number}	1451	udp-port = port-number
1263		1452
1264	@cindex udp-port	1453	@cindex udp-port
1265	Sets the port number used by the UDP protocol (default: @t{655}, not officially assigned by IANA!).	1454	Sets the port number used by the UDP protocol (default: @t{655}, not officially assigned by IANA!).
1266	@refill	1455	@refill
1267	@end itemize	1456	@end itemize
…		…
1275		1464
1276	@itemize	1465	@itemize
1277		1466
1278		1467
1279	@item	1468	@item
1280	@b{
1281	@cindex gvpe.conf
1282	gvpe.conf}	1469	gvpe.conf
1283		1470
1284	The config file.	1471	The config file.
1285	@refill	1472	@refill
1286		1473
1287		1474
1288	@item	1475	@item
1289	@b{
1290	@cindex if-up
1291	if-up}	1476	if-up
1292		1477
1293	The if-up script	1478	The if-up script
1294	@refill	1479	@refill
1295		1480
1296		1481
1297	@item	1482	@item
1298	@b{	1483	node-up, node-down
1299	@cindex node-up
1300	node-up,
1301	@cindex node-down
1302	node-down}
1303		1484
1304	If used the node up or node-down scripts.	1485	If used the node up or node-down scripts.
1305	@refill	1486	@refill
1306		1487
1307		1488
1308	@item	1489	@item
1309	@b{
1310	@cindex hostkey
1311	hostkey}	1490	hostkey
1312		1491
1313	The private key (taken from @t{hostkeys/nodename}) of the current host.	1492	The (default path of the) private key of the current host.
1314	@refill	1493	@refill
1315		1494
1316		1495
1317	@item	1496	@item
1318	@b{
1319	@cindex pubkey/nodename
1320	pubkey/nodename}	1497	pubkey/nodename
1321		1498
1322	The public keys of the other nodes, one file per node.	1499	The public keys of the other nodes, one file per node.
1323	@refill	1500	@refill
1324	@end itemize	1501	@end itemize
1325		1502
…		…
1350		1527
1351	@itemize	1528	@itemize
1352		1529
1353		1530
1354	@item	1531	@item
1355	@b{@strong{-c}, @strong{--config=}@emph{DIR}}	1532	@strong{-c}, @strong{--config=}@emph{DIR}
1356		1533
1357	Read configuration options from @emph{DIR}.	1534	Read configuration options from @emph{DIR}.
1358	@refill	1535	@refill
1359		1536
1360		1537
1361	@item	1538	@item
1362	@b{@strong{-g}, @strong{--generate-keys}}	1539	@strong{-g}, @strong{--generate-keys}
1363		1540
1364	Generate public/private RSA keypair and exit.	1541	Generate public/private RSA key-pair and exit.
1365	@refill	1542	@refill
1366		1543
1367		1544
1368	@item	1545	@item
		1546	@strong{-q}, @strong{--quiet}
		1547
		1548	Suppresses messages the author finds nonessential for scripting purposes.
		1549	@refill
		1550
		1551
		1552	@item
1369	@b{@strong{--help}}	1553	@strong{--help}
1370		1554
1371	Display short list of options.	1555	Display short list of options.
1372	@refill	1556	@refill
1373		1557
1374		1558
1375	@item	1559	@item
1376	@b{@strong{--kill}[@strong{=}@emph{SIGNAL}]}	1560	@strong{--kill}[@strong{=}@emph{SIGNAL}]
1377		1561
1378	Attempt to kill a running @t{gvpectrl} (optionally with the specified @emph{SIGNAL} instead of @t{SIGTERM}) and exit.	1562	Attempt to kill a running @t{gvpectrl} (optionally with the specified @emph{SIGNAL} instead of @t{SIGTERM}) and exit.
1379	@refill	1563	@refill
1380		1564
1381		1565
1382	@item	1566	@item
1383	@b{@strong{--show-config}}	1567	@strong{--show-config}
1384		1568
1385	Show a summary of the configuration, and how gvpe interprets it. Can also be very useful when designing firewall scripts.	1569	Show a summary of the configuration, and how gvpe interprets it. Can also be very useful when designing firewall scripts.
1386	@refill	1570	@refill
1387		1571
1388		1572
1389	@item	1573	@item
1390	@b{@strong{--version}}	1574	@strong{--version}
1391		1575
1392	Output version information and exit.	1576	Output version information and exit.
1393	@refill	1577	@refill
1394	@end itemize	1578	@end itemize
1395		1579
…		…
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...}]	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...}]
1415	@refill	1599	@refill
1416		1600
1417		1601
1418	@section DESCRIPTION	1602	@section DESCRIPTION
1419	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.
1420	@refill	1604	@refill
1421	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.
1422	@refill	1608	@refill
1423	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:
1424	@refill	1610	@refill
1425		1611
1426		1612
1427	@example	1613	@example
1428	[I<nodename>.]var=value	1614	[I<nodename>.]var=value
1429	@end example	1615	@end example
1430		1616
1431	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.
1432	@refill	1618	@refill
1433	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:
1434	@refill	1620	@refill
1435		1621
1436		1622
…		…
1447		1633
1448	@itemize	1634	@itemize
1449		1635
1450		1636
1451	@item	1637	@item
1452	@b{@strong{-c}, @strong{--config=}@emph{DIR}}	1638	@strong{-c}, @strong{--config=}@emph{DIR}
1453		1639
1454	Read configuration options from @emph{DIR}	1640	Read configuration options from @emph{DIR}
1455	@refill	1641	@refill
1456		1642
1457		1643
1458	@item	1644	@item
1459	@b{@strong{-d}, @strong{--l=}@emph{LEVEL}}	1645	@strong{-d}, @strong{--l=}@emph{LEVEL}
1460		1646
1461	Set logging level to @emph{LEVEL} (one of: noise, trace, debug, info, notice, warn, error, critical).	1647	Set logging level to @emph{LEVEL} (one of: noise, trace, debug, info, notice, warn, error, critical).
1462	@refill	1648	@refill
1463		1649
1464		1650
1465	@item	1651	@item
1466	@b{@strong{--help}}	1652	@strong{--help}
1467		1653
1468	Display short list of options.	1654	Display short list of options.
1469	@refill	1655	@refill
1470		1656
1471		1657
1472	@item	1658	@item
1473	@b{@strong{-D}, @strong{--no-detach}}	1659	@strong{-D}, @strong{--no-detach}
1474		1660
1475	Don't fork and detach but stay in foreground and log messages to stderr in addition to syslog.	1661	Don't fork and detach but stay in foreground and log messages to stderr in addition to syslog.
1476	@refill	1662	@refill
1477		1663
1478		1664
1479	@item	1665	@item
1480	@b{@strong{-L}, @strong{--mlock}}	1666	@strong{-L}, @strong{--mlock}
1481		1667
1482	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.
1483	@refill	1669	@refill
1484		1670
1485		1671
1486	@item	1672	@item
1487	@b{@strong{--version}}	1673	@strong{--version}
1488		1674
1489	Output version information and exit.	1675	Output version information and exit.
1490	@refill	1676	@refill
1491	@end itemize	1677	@end itemize
1492		1678
…		…
1497		1683
1498	@itemize	1684	@itemize
1499		1685
1500		1686
1501	@item	1687	@item
1502	@b{HUP}	1688	HUP
1503		1689
1504	Closes/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.	1690	Closes/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	1691	@refill
1506		1692
1507		1693
1508	@item	1694	@item
1509	@b{TERM}	1695	TERM
1510		1696
1511	Closes/resets all connections and exits.	1697	Closes/resets all connections and exits.
1512	@refill	1698	@refill
1513		1699
1514		1700
1515	@item	1701	@item
1516	@b{USR1}	1702	USR1
1517		1703
1518	Dump current network status into the syslog (at loglevel @t{notice}, so make sure your loglevel allows this).	1704	Dump current network status into the syslog (at loglevel @t{notice}, so make sure your loglevel allows this).
1519	@refill	1705	@refill
1520	@end itemize	1706	@end itemize
1521		1707
…		…
1526		1712
1527	@itemize	1713	@itemize
1528		1714
1529		1715
1530	@item	1716	@item
1531	@b{@t{/etc/gvpe/gvpe.conf}}	1717	@t{/etc/gvpe/gvpe.conf}
1532		1718
1533	The configuration file for @t{gvpe}.	1719	The configuration file for @t{gvpe}.
1534	@refill	1720	@refill
1535		1721
1536		1722
1537	@item	1723	@item
1538	@b{@t{/etc/gvpe/if-up}}	1724	@t{/etc/gvpe/if-up}
1539		1725
1540	Script which is executed as soon as the virtual network device has been allocated. Purpose is to further configure that device.	1726	Script which is executed as soon as the virtual network device has been allocated. Purpose is to further configure that device.
1541	@refill	1727	@refill
1542		1728
1543		1729
1544	@item	1730	@item
1545	@b{@t{/etc/gvpe/node-up}}	1731	@t{/etc/gvpe/node-up}
1546		1732
1547	Script which is executed whenever a node connects to this node. This can be used for example to run nsupdate.	1733	Script which is executed whenever a node connects to this node. This can be used for example to run nsupdate.
1548	@refill	1734	@refill
1549		1735
1550		1736
1551	@item	1737	@item
1552	@b{@t{/etc/gvpe/node-down}}	1738	@t{/etc/gvpe/node-down}
1553		1739
1554	Script which is executed whenever a connection to another node is lost. for example to run nsupdate.	1740	Script which is executed whenever a connection to another node is lost. for example to run nsupdate.
1555	@refill	1741	@refill
1556		1742
1557		1743
1558	@item	1744	@item
1559	@b{@t{/etc/gvpe/pubkey/*}}	1745	@t{/etc/gvpe/pubkey/*}
1560		1746
1561	The directory containing the public keys for every node, usually autogenerated by executing @t{gvpectrl --generate-keys}.	1747	The directory containing the public keys for every node, usually autogenerated by executing @t{gvpectrl --generate-keys}.
1562	@refill	1748	@refill
1563		1749
1564		1750
1565	@item	1751	@item
1566	@b{@t{/var/run/gvpe.pid}}	1752	@t{/var/run/gvpe.pid}
1567		1753
1568	The PID of the currently running @t{gvpe} is stored in this file.	1754	The PID of the currently running @t{gvpe} is stored in this file.
1569	@refill	1755	@refill
1570	@end itemize	1756	@end itemize
1571		1757
…		…
1587		1773
1588		1774
1589	@section Overview	1775	@section Overview
1590	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.
1591	@refill	1777	@refill
1592	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.
1593	@refill	1779	@refill
1594		1780
1595		1781
1596	@section PART 1: Transport protocols	1782	@section PART 1: Transport protocols
1597	GVPE offers a 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.
1598	@refill	1784	@refill
1599	The following sections describe each transport protocol in more detail. They are sorted by overhead/efficiency, the most efficient transport is listed first:	1785	The following sections describe each transport protocol in more detail. They are sorted by overhead/efficiency, the most efficient transport is listed first:
1600	@refill	1786	@refill
1601		1787
1602		1788
1603	@subsection RAW IP	1789	@subsection RAW IP
1604	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.
1605	@refill	1791	@refill
1606	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}).
1607	@refill	1793	@refill
1608	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.
1609	@refill	1795	@refill
1610		1796
1611		1797
1612	@subsection ICMP	1798	@subsection ICMP
1613	This protocol offers very low overhead (minimum 42 bytes), and can sometimes tunnel through firewalls when other protocols cannot.	1799	This protocol offers very low overhead (minimum 42 bytes), and can sometimes tunnel through firewalls when other protocols can not.
1614	@refill	1800	@refill
1615	It 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.	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.
1616	@refill	1802	@refill
1617	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).
1618	@refill	1804	@refill
1619		1805
1620		1806
1621	@subsection UDP	1807	@subsection UDP
1622	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).
…		…
1624	It should be used if RAW IP is not available.	1810	It should be used if RAW IP is not available.
1625	@refill	1811	@refill
1626		1812
1627		1813
1628	@subsection TCP	1814	@subsection TCP
1629	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.
1630	@refill	1816	@refill
1631	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.
1632	@refill	1818	@refill
1633	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.
1634	@refill	1820	@refill
1635	This 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.	1821	This 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	1822	@refill
1637		1823
1638		1824
1639	@subsection DNS	1825	@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.	1826	@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	1827	@refill
1642	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.
1643	@refill	1829	@refill
1644	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.
1645	@refill	1831	@refill
1646	Most configuration needs to be done by editing @t{src/vpn_dns.C} directly.
1647	@refill
1648	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 a @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).
1649	@refill	1833	@refill
1650	The 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).	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).
		1835	@refill
		1836	Fine-tuning needs to be done by editing @t{src/vpn_dns.C} directly.
1651	@refill	1837	@refill
1652		1838
1653		1839
1654	@section PART 2: The GNU VPE protocol	1840	@section PART 2: The GNU VPE protocol
1655	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.
1656	@refill	1842	@refill
1657		1843
1658		1844
1659	@subsection Anatomy of a VPN packet	1845	@subsection Anatomy of a VPN packet
1660	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.
1661	@refill	1847	@refill
1662		1848
1663		1849
1664	@example	1850	@example
1665	+------+------+--------+------+	1851	+------+------+--------+------+
1666	| HMAC | TYPE | SRCDST | DATA |	1852	| HMAC | TYPE | SRCDST | DATA |
1667	+------+------+--------+------+	1853	+------+------+--------+------+
1668	@end example	1854	@end example
1669		1855
1670	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.
1671	@refill	1857	@refill
1672	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.).
1673	@refill	1859	@refill
1674	SRCDST 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.	1860	SRCDST is a three byte field which contains the source and destination node IDs (12 bits each).
1675	@refill	1861	@refill
1676	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:
1677	@refill	1863	@refill
1678		1864
1679		1865
…		…
1683	+------+------+--------+------+-------+------+	1869	+------+------+--------+------+-------+------+
1684	@end example	1870	@end example
1685		1871
1686	RAND is a sequence of fully random bytes, used to increase the entropy of the data for encryption purposes.	1872	RAND is a sequence of fully random bytes, used to increase the entropy of the data for encryption purposes.
1687	@refill	1873	@refill
1688	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 reply attacks.	1874	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.
1689	@refill	1875	@refill
		1876	The encryption is done on RAND+SEQNO+DATA in CBC mode with zero IV (or, equivalently, the IV is RAND+SEQNO, encrypted with the block cipher, unless RAND size is decreased or increased over the default value).
		1877	@refill
		1878	The random prefix itself is generated by using AES in CTR mode with a random key and starting value, which should make them unpredictable even before encrypting them again. The sequence number additionally ensures that the IV is unique.
		1879	@refill
1690		1880
1691		1881
1692	@subsection The authentification protocol	1882	@subsection The authentication/key exchange protocol
1693	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.	1883	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.
1694	@refill	1884	@refill
1695	A 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.	1885	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.
1696	@refill	1886	@refill
1697	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.	1887	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.
1698	@refill	1888	@refill
1699	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.	1889	In detail, the challenge consist of:
1700	@refill	1890	@refill
1701	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).	1891
		1892
		1893	@example
		1894	RSA-OAEP (SEQNO MAC CIPHER SALT EXTRA-AUTH) ECDH1
		1895	@end example
		1896
		1897	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.
		1898	@refill
		1899	The remote node decrypts the RSA data, generates its own ECDH key (ECDH2), and replies with:
		1900	@refill
		1901
		1902
		1903	@example
		1904	HKDF-Expand (HKDF-Extract (ECDH2, RSA), ECDH1, AUTH_DIGEST_SIZE) ECDH2
		1905	@end example
		1906
		1907	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.
		1908	@refill
		1909	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).
		1910	@refill
		1911	The HMAC key for sending is generated as follow:
		1912	@refill
		1913
		1914
		1915	@example
		1916	HMAC_KEY = HKDF-Expand (HKDF-Extract (REMOTE_SALT, MAC ECDH_SECRET), info, HMAC_MD_SIZE)
		1917	@end example
		1918
		1919	It extracts from MAC and ECDH_SECRET using the @emph{remote} SALT, then expands using a static info string.
		1920	@refill
		1921	The cipher key is generated in the same way, except using the CIPHER part of the original challenge.
		1922	@refill
		1923	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.
		1924	@refill
		1925	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.
1702	@refill	1926	@refill
1703		1927
1704		1928
1705	@subsection Retrying	1929	@subsection Retrying
1706	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) and lightweight (no RSA operations required). A host that receives ping requests from an unconnected peer will respond by trying to create a connection.	1930	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.
1707	@refill	1931	@refill
1708	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).	1932	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).
		1933	@refill
		1934	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.
		1935	@refill
		1936	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.
1709	@refill	1937	@refill
1710		1938
1711		1939
1712	@subsection Routing and Protocol translation	1940	@subsection Routing and Protocol translation
1713	The 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.	1941	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:
1714	@refill	1942	@refill
1715	If 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.	1943
1716	@refill	1944
		1945	@itemize
		1946
		1947
		1948	@item
		1949	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.
		1950
		1951
		1952
		1953	@item
		1954	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).
		1955
		1956
		1957
		1958	@item
		1959	If 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.
		1960
		1961
		1962
		1963	@item
		1964	If no such router exists, then GVPE will simply send the packet to the node with the highest priority available.
		1965
		1966
		1967
		1968	@item
		1969	Failing all that, the packet will be dropped.
		1970
		1971	@end itemize
		1972
1717	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.	1973	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.
1718	@refill	1974	@refill
1719	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 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.	1975	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.
1720	@refill	1976	@refill
1721	If 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.	1977	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.
1722	@refill
1723	When 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	1978	@refill
1727		1979
1728		1980
1729		1981
1730	@node Simple Example,Complex Example,gvpe.protocol,Top	1982	@node Simple Example,Complex Example,gvpe.protocol,Top
…		…
1739	@example	1991	@example
1740	enable-udp = yes # use UDP	1992	enable-udp = yes # use UDP
1741	udp-port = 407 # use this UDP port	1993	udp-port = 407 # use this UDP port
1742	mtu = 1492 # handy for TDSL	1994	mtu = 1492 # handy for TDSL
1743	ifname = vpn0 # I prefer vpn0 over e.g. tap0	1995	ifname = vpn0 # I prefer vpn0 over e.g. tap0
1744	@end example
1745		1996
1746
1747
1748	@example
1749	node = huffy # arbitrary node name	1997	node = huffy # arbitrary node name
1750	hostname = 1.2.3.4 # ip address if this host	1998	hostname = 1.2.3.4 # ip address if this host
1751	@end example
1752		1999
1753
1754
1755	@example
1756	node = welshy	2000	node = welshy
1757	hostname = www.example.net # resolve at connection time	2001	hostname = www.example.net # resolve at connection time
1758	@end example
1759		2002
1760
1761
1762	@example
1763	node = wheelery	2003	node = wheelery
1764	# no hostname, will be determinded dynamically using router1 or router2	2004	# no hostname, will be determinded dynamically using router1 or router2
1765	@end example	2005	@end example
1766		2006
1767	@t{gvpe} will execute the @t{if-up} script on every hosts, which, for linux, could look like this for all three hosts:	2007	@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