ViewVC Help

View File | Revision Log | Show Annotations | Download File

/cvs/gvpe/doc/gvpe.texi

Comparing gvpe/doc/gvpe.texi (file contents):
Revision 1.2 by pcg, Thu Mar 29 17:35:20 2007 UTC vs.
Revision 1.10 by root, Thu Oct 25 06:23:50 2018 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 generating an RSA key-pair on each node 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 pair for each node
291	Run the following command to generate all key pairs (that might take a while):	275	Next you have to generate the RSA keys for the nodes. While you can set up GVPE so you can generate all keys on a single host and centrally distribute all keys, it is safer to generate the key for each node on the node, so that the secret/private key does not have to be copied over the network.
292	@refill	276	@refill
		277	To do so, run the following command to generate a key pair:
		278	@refill
293		279
294		280
295	@example	281	@example
296	gvpectrl -c /etc/gvpe -g	282	gvpectrl -c /etc/gvpe -g nodekey
		283	@end example
		284
		285	This will create two files, @file{nodekey} and @file{nodekey.privkey}. The former should be copied to @file{/etc/gvpe/pubkey/@emph{nodename}} on the host where your config file is (you will have to create the @file{pubkey} directory first):
		286	@refill
		287
		288
297	@end example	289	@example
		290	scp nodekey confighost:/etc/gvpe/pubkey/nodename
		291	@end example
298		292
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}}.	293	The private key @file{nodekey.privkey} should be moved to @file{/etc/gvpe/hostkey}:
300	@refill	294	@refill
		295
		296
		297	@example
		298	mkdir -p /etc/gvpe
		299	mv nodekey.privkey /etc/gvpe/hostkey
		300	@end example
		301
301		302
302		303
303	@subsection STEP 3: distribute the config files to all nodes	304	@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	305	Now distribute the config files and public keys to the other nodes.
305	@refill	306	@refill
306	First all the config files without the hostkeys should be distributed:	307	The example uses rsync-over-ssh to copy the config file and all the public keys:
307	@refill	308	@refill
308		309
309		310
310	@example	311	@example
311	rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkeys	312	rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkey
312	rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkeys	313	rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkey
313	rsync -avzessh /etc/gvpe third.example.net:/etc/. --exclude hostkeys	314	rsync -avzessh /etc/gvpe third.example.net:/etc/. --exclude hostkey
314	@end example
315
316	Then the hostkeys should be copied:
317	@refill
318
319
320	@example	315	@end example
321	rsync -avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey
322	rsync -avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey
323	rsync -avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey
324	@end example
325		316
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.	317	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	318	@refill
328		319
329		320
330	@subsection STEP 4: starting gvpe	321	@subsection STEP 4: starting gvpe
331	You should then start gvpe on each node by issuing a command like:	322	You should then start gvpe on each node by issuing a command like:
332	@refill	323	@refill
333		324
334		325
335	@example	326	@example
336	gvpe -D -linfo first # first is the nodename	327	gvpe -D -l info first # first is the nodename
337	@end example	328	@end example
338		329
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 ;).	330	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	331	@refill
341	If this works you should check your networking setup by pinging various endpoints.	332	If this works you should check your networking setup by pinging various endpoints.
342	@refill	333	@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:	334	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	335	@refill
345		336
346		337
347	@example	338	@example
348	t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1	339	t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1
349	@end example	340	@end example
350		341
351		342
352		343
353	@subsection STEP 5: enjoy	344	@subsection STEP 5: enjoy
354	... and play around. Sending a -HUP (@t{gvpectrl -kHUP}) to the daemon will make it try to connect to all other nodes again. If you run it from inittab, as is recommended, @t{gvpectrl -k} (or simply @t{killall gvpe}) will kill the daemon, start it again, making it read it's configuration files again.	345	... and play around. Sending a -HUP (@t{gvpectrl -kHUP}) to the daemon will make it try to connect to all other nodes again. If you run it from inittab @t{gvpectrl -k} (or simply @t{killall gvpe}) will kill the daemon, start it again, making it read it's configuration files again.
355	@refill	346	@refill
		347	To run the GVPE daemon permanently from your SysV init, you can add it to your @file{inittab}, e.g.:
		348	@refill
		349
		350
		351	@example
		352	t1:2345:respawn:/bin/sh -c "exec nice -n-20 /path/to/gvpe -D node >/var/log/gvpe.log 2>&1"
		353	@end example
		354
		355	For systems using systemd, you can use a unit file similar to this one:
		356	@refill
		357
		358
		359	@example
		360	[Unit]
		361	Description=gvpe
		362	After=network.target
		363	Before=remote-fs.target
		364
		365	[Service]
		366	ExecStart=/path/to/gvpe -D node
		367	KillMode=process
		368	Restart=always
		369
		370	[Install]
		371	WantedBy=multi-user.target
		372	@end example
		373
356		374
357		375
358	@section COPYRIGHTS AND LICENSES	376	@section COPYRIGHTS AND LICENSES
359	GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file COPYING that should be part of your distribution).	377	GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file COPYING that should be part of your distribution).
360	@refill	378	@refill
…		…
376	This file tries to capture OS-dependent configuration or build issues, quirks and platform limitations, as known.	394	This file tries to capture OS-dependent configuration or build issues, quirks and platform limitations, as known.
377	@refill	395	@refill
378		396
379		397
380	@section TUN vs. TAP interface	398	@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.	399	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	400	@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.	401	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	402	@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.	403	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	404	@refill
…		…
433	The MAC address is dynamically being patched into packets and ARP-requests, so only IPv4 works with ARP on this platform.	451	The MAC address is dynamically being patched into packets and ARP-requests, so only IPv4 works with ARP on this platform.
434	@refill	452	@refill
435		453
436		454
437	@subsection tincd/bsd	455	@subsection tincd/bsd
438	TAP-device, maybe; migth work for many bsd variants.	456	TAP-device, maybe; might work for many bsd variants.
439	@refill	457	@refill
440	This driver is a newer version of the @t{tincd/*bsd} drivers. It @emph{might} provide a TAP device, or might not work at all. You might try this interface type first, and, if it doesn't work, try one of the OS-specific drivers.	458	This driver is a newer version of the @t{tincd/*bsd} drivers. It @emph{might} provide a TAP device, or might not work at all. You might try this interface type first, and, if it doesn't work, try one of the OS-specific drivers.
441	@refill	459	@refill
442		460
443		461
…		…
548		566
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.	567	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	568	@refill
551	See @t{tincd/netbsd} for more information.	569	See @t{tincd/netbsd} for more information.
552	@refill	570	@refill
553	Completely unstested so far.	571	Completely untested so far.
554	@refill	572	@refill
555		573
556		574
557	@subsection tincd/mingw	575	@subsection tincd/mingw
558	TAP-device; see @t{native/cygwin} for more information.	576	TAP-device; see @t{native/cygwin} for more information.
…		…
569	Completely untested so far.	587	Completely untested so far.
570	@refill	588	@refill
571		589
572		590
573	@subsection tincd/uml_socket	591	@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.	592	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	593	@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.	594	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	595	@refill
578	Completely untested so far.	596	Completely untested so far.
579	@refill	597	@refill
580		598
581		599
…		…
596		614
597	@section SYNOPSIS	615	@section SYNOPSIS
598		616
599		617
600	@example	618	@example
		619	# global options for all nodes
601	udp-port = 407	620	udp-port = 407
602	mtu = 1492	621	mtu = 1492
603	ifname = vpn0	622	ifname = vpn0
604	@end example
605		623
606		624	# first node is named branch1 and is at 1.2.3.4
607
608	@example
609	node = branch1	625	node = branch1
610	hostname = 1.2.3.4	626	hostname = 1.2.3.4
611	@end example
612		627
613		628	# second node uses dns to resolve the address
614
615	@example
616	node = branch2	629	node = branch2
617	hostname = www.example.net	630	hostname = www.example.net
618	udp-port = 500 # this host uses a different udp-port	631	udp-port = 500 # this host uses a different udp-port
619	@end example
620		632
621		633	# third node has no fixed ip address
622
623	@example
624	node = branch3	634	node = branch3
625	connect = ondemand	635	connect = ondemand
626	@end example	636	@end example
627		637
628		638
629		639
630	@section DESCRIPTION	640	@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.	641	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	642	@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.	643	All settings are applied "in order", that is, later settings of the same variable overwrite earlier ones.
634	@refill	644	@refill
		645	The only exceptions to the above are the following directives:
		646	@refill
635		647
636		648
		649	@itemize
		650
		651
		652	@item
		653	node nodename
		654
		655	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.
		656	@refill
		657	Multiple @t{node} statements with the same node name are supported and will be merged together.
		658	@refill
		659
		660
		661	@item
		662	global
		663
		664	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:
		665	@refill
		666
		667
		668	@example
		669	global
		670	include local.conf
637	@example	671	@end example
638	name = value	672
		673
		674
		675	@item
		676	on nodename ...
		677
		678
		679
		680	@item
		681	on !nodename ...
		682
		683	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.
		684	@refill
		685	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.
		686	@refill
		687
		688
		689	@example
		690	mtu = 1450
639	on branch1 loglevel = noise	691	on branch1 loglevel = noise
640	on !branch2 connect = ondemand	692	on !branch2 connect = ondemand
641	@end example	693	@end example
642		694
643	All settings are executed "in order", that is, later settings of the same variable overwrite earlier ones.	695
		696
		697	@item
		698	include relative-or-absolute-path
		699
		700	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	701	@refill
		702	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.
		703	@refill
		704	Relative paths are interpreted relative to the GVPE config directory.
		705	@refill
		706	Example: include the file @file{local.conf} in the config directory on every node.
		707	@refill
		708
		709
		710	@example
		711	include local.conf
		712	@end example
		713
		714	Example: include a file @file{conf/}nodename@file{.conf}
		715	@refill
		716
		717
		718	@example
		719	include conf/%s.conf
		720	@end example
		721
		722	@end itemize
		723
645		724
646		725
647	@section ANATOMY OF A CONFIG FILE	726	@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.	727	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	728	@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.	729	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	730	@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.	731	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	732	@refill
654		733
655		734
…		…
663		742
664	@itemize	743	@itemize
665		744
666		745
667	@item	746	@item
		747	chroot = path or /
		748
		749	@cindex chroot
		750	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.
		751	@refill
		752	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.
		753	@refill
		754
		755
		756	@item
		757	chuid = numerical-uid
		758
		759	@cindex chuid
		760
		761
		762	@item
		763	chgid = numerical-gid
		764
		765	@cindex chgid
		766	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.
		767	@refill
		768	Other scripts, such as @t{node-up}, are run with the new user id or group id.
		769	@refill
		770
		771
		772	@item
		773	chuser = username
		774
		775	@cindex chuser
		776	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}).
		777	@refill
		778
		779
		780	@item
668	@b{dns-forw-host = hostname/ip}	781	dns-forw-host = hostname/ip
669		782
670	@cindex dns-forw-host	783	@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).	784	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	785	@refill
673		786
674		787
675	@item	788	@item
676	@b{dns-forw-port = port-number}	789	dns-forw-port = port-number
677		790
678	@cindex dns-forw-port	791	@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).	792	The port where the @t{dns-forw-host} is to be contacted (default: @t{53}, which is fine in most cases).
680	@refill	793	@refill
681		794
682		795
683	@item	796	@item
		797	dns-case-preserving = yes|true|on | no|false|off
		798
		799	@cindex dns-case-preserving
		800	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).
		801	@refill
		802	Normally, when the forwarding server changes the case of domain names then GVPE will automatically set this to false.
		803	@refill
		804
		805
		806	@item
684	@b{dns-max-outstanding = integer-number-of-requests}	807	dns-max-outstanding = integer-number-of-requests
685		808
686	@cindex dns-max-outstanding	809	@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.	810	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	811	@refill
689	The default should be working ok for most links.	812	The default should be working OK for most links.
690	@refill	813	@refill
691		814
692		815
693	@item	816	@item
694	@b{dns-overlap-factor = float}	817	dns-overlap-factor = float
695		818
696	@cindex dns-overlap-factor	819	@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.	820	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	821	@refill
699	For congested or picky dns forwarders you could use a value nearer to or exceeding @t{1}.	822	For congested or picky DNS forwarders you could use a value nearer to or exceeding @t{1}.
700	@refill	823	@refill
701	The default should be working ok for most links.	824	The default should be working OK for most links.
702	@refill	825	@refill
703		826
704		827
705	@item	828	@item
706	@b{dns-send-interval = send-interval-in-seconds}	829	dns-send-interval = send-interval-in-seconds
707		830
708	@cindex dns-send-interval	831	@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.	832	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	833	@refill
711	The default should be working ok for most links.	834	The default should be working OK for most links.
712	@refill	835	@refill
713		836
714		837
715	@item	838	@item
716	@b{dns-timeout-factor = float}	839	dns-timeout-factor = float
717		840
718	@cindex dns-timeout-factor	841	@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.	842	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	843	@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.	844	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	845	@refill
723	The default should be working ok for most links but will result in low throughput if packet loss is high.	846	The default should be working OK for most links but will result in low throughput if packet loss is high.
724	@refill	847	@refill
725		848
726		849
727	@item	850	@item
728	@b{if-up = relative-or-absolute-path}	851	if-up = relative-or-absolute-path
729		852
730	@cindex if-up	853	@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).	854	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	855	@refill
733	Variables that have the same value on all nodes:	856	Variables that have the same value on all nodes:
734	@refill	857	@refill
735		858
736		859
737	@itemize	860	@itemize
738		861
739		862
740	@item	863	@item
741	@b{CONFBASE=/etc/gvpe}	864	CONFBASE=/etc/gvpe
742		865
743	@cindex CONFBASE	866	@cindex CONFBASE
744	The configuration base directory.	867	The configuration base directory.
745	@refill	868	@refill
746		869
747		870
748	@item	871	@item
749	@b{IFNAME=vpn0}	872	IFNAME=vpn0
750		873
751	@cindex IFNAME	874	@cindex IFNAME
752	The network interface to initialize.	875	The network interface to initialize.
753	@refill	876	@refill
754		877
755		878
756	@item	879	@item
757	@b{IFTYPE=native # or tincd}	880	IFTYPE=native # or tincd
758		881
759	@cindex IFTYPE	882	@cindex IFTYPE
760		883
761		884
762	@item	885	@item
763	@b{IFSUBTYPE=linux # or freebsd, darwin etc..}	886	IFSUBTYPE=linux # or freebsd, darwin etc..
764		887
765	@cindex IFSUBTYPE	888	@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.	889	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	890	@refill
768		891
769		892
770	@item	893	@item
771	@b{MTU=1436}	894	MTU=1436
772		895
773	@cindex MTU	896	@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.	897	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	898	@refill
776		899
777		900
778	@item	901	@item
779	@b{NODES=5}	902	NODES=5
780		903
781	@cindex NODES	904	@cindex NODES
782	The number of nodes in this GVPE network.	905	The number of nodes in this GVPE network.
783	@refill	906	@refill
784	@end itemize	907	@end itemize
…		…
789		912
790	@itemize	913	@itemize
791		914
792		915
793	@item	916	@item
794	@b{IFUPDATA=string}	917	IFUPDATA=string
795		918
796	@cindex IFUPDATA	919	@cindex IFUPDATA
797	The value of the configuration directive @t{if-up-data}.	920	The value of the configuration directive @t{if-up-data}.
798	@refill	921	@refill
799		922
800		923
801	@item	924	@item
802	@b{MAC=fe:fd:80:00:00:01}	925	MAC=fe:fd:80:00:00:01
803		926
804	@cindex MAC	927	@cindex MAC
805	The MAC address the network interface has to use.	928	The MAC address the network interface has to use.
806	@refill	929	@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.	930	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	931	@refill
809		932
810		933
811	@item	934	@item
812	@b{NODENAME=branch1}	935	NODENAME=branch1
813		936
814	@cindex NODENAME	937	@cindex NODENAME
815	The nickname of the node.	938	The nickname of the node.
816	@refill	939	@refill
817		940
818		941
819	@item	942	@item
820	@b{NODEID=1}	943	NODEID=1
821		944
822	@cindex NODEID	945	@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.	946	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	947	@refill
825	@end itemize	948	@end itemize
…		…
836	[ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME	959	[ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME
837	[ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME	960	[ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME
838	ip route add 10.0.0.0/8 dev $IFNAME	961	ip route add 10.0.0.0/8 dev $IFNAME
839	@end example	962	@end example
840		963
841	More complicated examples (using routing to reduce arp traffic) can be found in the etc/ subdirectory of the distribution.	964	More complicated examples (using routing to reduce ARP traffic) can be found in the @file{etc/} subdirectory of the distribution.
842	@refill	965	@refill
843		966
844		967
845	@item	968	@item
846	@b{ifname = devname}	969	ifname = devname
847		970
848	@cindex ifname	971	@cindex ifname
849	Sets the tun interface name to the given name. The default is OS-specific and most probably something like @t{tun0}.	972	Sets the tun interface name to the given name. The default is OS-specific and most probably something like @t{tun0}.
850	@refill	973	@refill
851		974
852		975
853	@item	976	@item
854	@b{ifpersist = yes|true|on | no|false|off}	977	ifpersist = yes|true|on | no|false|off
855		978
856	@cindex ifpersist	979	@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.	980	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	981	@refill
859		982
860		983
861	@item	984	@item
862	@b{ip-proto = numerical-ip-protocol}	985	ip-proto = numerical-ip-protocol
863		986
864	@cindex ip-proto	987	@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.	988	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	989	@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)	990	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	991	@refill
		992	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).
		993	@refill
869		994
870		995
871	@item	996	@item
872	@b{http-proxy-host = hostname/ip}	997	http-proxy-host = hostname/ip
873		998
874	@cindex http-proxy-host	999	@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.	1000	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	1001	@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.	1002	@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	1003	@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.	1004	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	1005	@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).	1006	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	1007	@refill
883	If you have a router, connecting to it will suffice. Otherwise tcp must be enabled on all hosts.	1008	If you have a router, connecting to it will suffice. Otherwise TCP must be enabled on all nodes.
884	@refill	1009	@refill
885	Example:	1010	Example:
886	@refill	1011	@refill
887		1012
888		1013
…		…
893	@end example	1018	@end example
894		1019
895		1020
896		1021
897	@item	1022	@item
898	@b{http-proxy-port = proxy-tcp-port}	1023	http-proxy-port = proxy-tcp-port
899		1024
900	@cindex http-proxy-port	1025	@cindex http-proxy-port
901	The port where your proxy server listens.	1026	The port where your proxy server listens.
902	@refill	1027	@refill
903		1028
904		1029
905	@item	1030	@item
906	@b{http-proxy-auth = login:password}	1031	http-proxy-auth = login:password
907		1032
908	@cindex http-proxy-auth	1033	@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.	1034	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	1035	@refill
911		1036
912		1037
913	@item	1038	@item
914	@b{keepalive = seconds}	1039	keepalive = seconds
915		1040
916	@cindex keepalive	1041	@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.	1042	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	1043	@refill
919		1044
920		1045
921	@item	1046	@item
922	@b{loglevel = noise|trace|debug|info|notice|warn|error|critical}	1047	loglevel = noise|trace|debug|info|notice|warn|error|critical
923		1048
924	@cindex loglevel	1049	@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}.	1050	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	1051	@refill
927		1052
928		1053
929	@item	1054	@item
930	@b{mtu = bytes}	1055	mtu = bytes
931		1056
932	@cindex mtu	1057	@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.	1058	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	1059	@refill
935	Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp).	1060	Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp).
936	@refill	1061	@refill
937	This value must be the minimum of the mtu values of all hosts.	1062	This value must be the minimum of the MTU values of all nodes.
938	@refill	1063	@refill
939		1064
940		1065
941	@item	1066	@item
942	@b{node = nickname}	1067	nfmark = integer
943		1068
944	@cindex node	1069	@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.	1070	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	1071	@refill
		1072	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:
		1073	@refill
947		1074
948		1075
		1076	@example
		1077	ip rule add not fwmark 1000 lookup 99
		1078	@end example
		1079
		1080
		1081
949	@item	1082	@item
950	@b{node-up = relative-or-absolute-path}	1083	node-up = relative-or-absolute-path
951		1084
952	@cindex node-up	1085	@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:	1086	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.
		1087	@refill
		1088	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	1089	@refill
955		1090
956		1091
957	@itemize	1092	@itemize
958		1093
959		1094
960	@item	1095	@item
961	@b{DESTNODE=branch2}	1096	DESTNODE=branch2
962		1097
963	@cindex DESTNODE	1098	@cindex DESTNODE
964	The name of the remote node.	1099	The name of the remote node.
965	@refill	1100	@refill
966		1101
967		1102
968	@item	1103	@item
969	@b{DESTID=2}	1104	DESTID=2
970		1105
971	@cindex DESTID	1106	@cindex DESTID
972	The node id of the remote node.	1107	The node id of the remote node.
973	@refill	1108	@refill
974		1109
975		1110
976	@item	1111	@item
		1112	DESTSI=rawip/88.99.77.55:0
		1113
		1114	@cindex DESTSI
		1115	The "socket info" of the target node, protocol dependent but usually in the format protocol/ip:port.
		1116	@refill
		1117
		1118
		1119	@item
977	@b{DESTIP=188.13.66.8}	1120	DESTIP=188.13.66.8
978		1121
979	@cindex DESTIP	1122	@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).	1123	The numerical IP address of the remote node (gvpe accepts connections from everywhere, as long as the other node can authenticate itself).
981	@refill	1124	@refill
982		1125
983		1126
984	@item	1127	@item
985	@b{DESTPORT=655 # deprecated}	1128	DESTPORT=655 # deprecated
986		1129
987	@cindex DESTPORT	1130	@cindex DESTPORT
988	The UDP port used by the other side.	1131	The protocol port used by the other side, if applicable.
989	@refill	1132	@refill
990		1133
991		1134
992	@item	1135	@item
993	@b{STATE=UP}	1136	STATE=up
994		1137
995	@cindex STATE	1138	@cindex STATE
996	Node-up scripts get called with STATE=UP, node-down scripts get called with STATE=DOWN.	1139	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	1140	@refill
998	@end itemize	1141	@end itemize
999		1142
1000	Here is a nontrivial example that uses nsupdate to update the name => ip mapping in some dns zone:	1143	Here is a nontrivial example that uses nsupdate to update the name => ip mapping in some DNS zone:
1001	@refill	1144	@refill
1002		1145
1003		1146
1004	@example	1147	@example
1005	#!/bin/sh	1148	#!/bin/sh
1006	@{	1149	@{
1007	echo update delete $DESTNODE.lowttl.example.net. a	1150	echo update delete $DESTNODE.lowttl.example.net. a
1008	echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP	1151	echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP
1009	echo	1152	echo
1010	@} | nsupdate -d -k $CONFBASE:key.example.net.	1153	@} | nsupdate -d -k $CONFBASE:key.example.net.
1011	@end example	1154	@end example
1012		1155
1013		1156
1014		1157
1015	@item	1158	@item
		1159	node-change = relative-or-absolute-path
		1160
		1161	@cindex node-change
		1162	Same as @t{node-change}, but gets called whenever something about a connection changes (such as the source IP address).
		1163	@refill
		1164
		1165
		1166	@item
1016	@b{node-down = relative-or-absolute-path}	1167	node-down = relative-or-absolute-path
1017		1168
1018	@cindex node-down	1169	@cindex node-down
1019	Same as @t{node-up}, but gets called whenever a connection is lost.	1170	Same as @t{node-up}, but gets called whenever a connection is lost.
1020	@refill	1171	@refill
1021		1172
1022		1173
1023	@item	1174	@item
1024	@b{pid-file = path}	1175	pid-file = path
1025		1176
1026	@cindex pid-file	1177	@cindex pid-file
1027	The path to the pid file to check and create (default: @t{LOCALSTATEDIR/run/gvpe.pid}).	1178	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	1179	@refill
1029		1180
1030		1181
1031	@item	1182	@item
1032	@b{private-key = relative-path-to-key}	1183	private-key = relative-path-to-key
1033		1184
1034	@cindex private-key	1185	@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.	1186	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 be able to share the same config directory between nodes.
1036	@refill	1187	@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.	1188	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 this way though.
1038	@refill	1189	@refill
1039		1190
1040		1191
1041	@item	1192	@item
1042	@b{rekey = seconds}	1193	rekey = seconds
1043		1194
1044	@cindex rekey	1195	@cindex rekey
1045	Sets the rekeying interval in seconds (default: @t{3600}). Connections are reestablished every @t{rekey} seconds.	1196	Sets the rekeying interval in seconds (default: @t{3607}). Connections are reestablished every @t{rekey} seconds, making them use a new encryption key.
		1197	@refill
		1198
		1199
		1200	@item
		1201	seed-device = path
		1202
		1203	@cindex seed-device
		1204	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.
		1205	@refill
		1206	On program start and every seed-interval, gvpe will read 64 octets.
		1207	@refill
		1208	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).
		1209	@refill
		1210
		1211
		1212	@item
		1213	seed-interval = seconds
		1214
		1215	@cindex seed-interval
		1216	The number of seconds between reseeds of the random number generator (default: @t{3613}). A value of @t{0} disables this regular reseeding.
		1217	@refill
		1218
		1219
		1220	@item
		1221	serial = string
		1222
		1223	@cindex serial
		1224	The configuration serial number. This can be any string up to 16 bytes length. Only when the serial matches on both sides of a connection 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.
		1225	@refill
		1226	It's recommended to specify this is a date string such as @t{2013-05-05} or @t{20121205084417}.
		1227	@refill
		1228	The exact algorithm is as this: if a connection request is received form a node with an identical serial, then it succeeds normally.
		1229	@refill
		1230	If the remote serial is lower than the local serial, it is ignored.
		1231	@refill
		1232	If the remote serial is higher than the local serial, a warning message is logged.
1046	@refill	1233	@refill
1047	@end itemize	1234	@end itemize
1048		1235
1049		1236
1050		1237
…		…
1055		1242
1056	@itemize	1243	@itemize
1057		1244
1058		1245
1059	@item	1246	@item
1060	@b{allow-direct = nodename}	1247	allow-direct = nodename
1061		1248
1062	@cindex allow-direct	1249	@cindex allow-direct
1063	Allow direct connections to this node. See @t{deny-direct} for more info.	1250	Allow direct connections to this node. See @t{deny-direct} for more info.
1064	@refill	1251	@refill
1065		1252
1066		1253
1067	@item	1254	@item
1068	@b{compress = yes|true|on | no|false|off}	1255	compress = yes|true|on | no|false|off
1069		1256
1070	@cindex compress	1257	@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.	1258	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	1259	@refill
1073		1260
1074		1261
1075	@item	1262	@item
1076	@b{connect = ondemand | never | always | disabled}	1263	connect = ondemand | never | always | disabled
1077		1264
1078	@cindex connect	1265	@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).	1266	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	1267	@refill
		1268	Routers will automatically be forced to @t{always} unless they are @t{disabled}, to ensure all nodes can talk to each other.
		1269	@refill
1081		1270
1082		1271
1083	@item	1272	@item
1084	@b{deny-direct = nodename | *}	1273	deny-direct = nodename | *
1085		1274
1086	@cindex deny-direct	1275	@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.	1276	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	1277	@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).	1278	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	1279	@refill
1091	The algorithm to check wether a connection may be direct is as follows:	1280	The algorithm to check whether a connection may be direct is as follows:
1092	@refill	1281	@refill
1093	1. Other node mentioned in a @t{allow-direct}? If yes, allow the connection.	1282	1. Other node mentioned in an @t{allow-direct}? If yes, allow the connection.
1094	@refill	1283	@refill
1095	2. Other node mentioned in a @t{deny-direct}? If yes, deny direct connections.	1284	2. Other node mentioned in a @t{deny-direct}? If yes, deny direct connections.
1096	@refill	1285	@refill
1097	3. Allow the connection.	1286	3. Allow the connection.
1098	@refill	1287	@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.	1290	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	1291	@refill
1103		1292
1104		1293
1105	@item	1294	@item
1106	@b{dns-domain = domain-suffix}	1295	dns-domain = domain-suffix
1107		1296
1108	@cindex dns-domain	1297	@cindex dns-domain
1109	The DNS domain suffix that points to the DNS tunnel server for this node.	1298	The DNS domain suffix that points to the DNS tunnel server for this node.
1110	@refill	1299	@refill
1111	The domain must point to a NS record that points to the @emph{dns-hostname}, i.e.	1300	The domain must point to a NS record that points to the @emph{dns-hostname}, i.e.
…		…
1127	@end example	1316	@end example
1128		1317
1129		1318
1130		1319
1131	@item	1320	@item
1132	@b{dns-hostname = hostname/ip}	1321	dns-hostname = hostname/ip
1133		1322
1134	@cindex dns-hostname	1323	@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.	1324	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	1325	@refill
1137		1326
1138		1327
1139	@item	1328	@item
1140	@b{dns-port = port-number}	1329	dns-port = port-number
1141		1330
1142	@cindex dns-port	1331	@cindex dns-port
1143	The port to bind the DNS tunnel socket to. Must be @t{53} on DNS tunnel servers.	1332	The port to bind the DNS tunnel socket to. Must be @t{53} on DNS tunnel servers.
1144	@refill	1333	@refill
1145		1334
1146		1335
1147	@item	1336	@item
1148	@b{enable-dns = yes|true|on | no|false|off}	1337	enable-dns = yes|true|on | no|false|off
1149		1338
1150	@cindex enable-dns	1339	@cindex enable-dns
1151	See gvpe.protocol(7) for a description of the DNS transport protocol. Avoid this protocol if you can.	1340	See gvpe.protocol(7) for a description of the DNS transport protocol. Avoid this protocol if you can.
1152	@refill	1341	@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.	1342	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	1343	@refill
1155		1344
1156		1345
1157	@item	1346	@item
1158	@b{enable-icmp = yes|true|on | no|false|off}	1347	enable-icmp = yes|true|on | no|false|off
1159		1348
1160	@cindex enable-icmp	1349	@cindex enable-icmp
1161	See gvpe.protocol(7) for a description of the ICMP transport protocol.	1350	See gvpe.protocol(7) for a description of the ICMP transport protocol.
1162	@refill	1351	@refill
1163	Enable the ICMP transport using icmp packets of type @t{icmp-type} on this node.	1352	Enable the ICMP transport using ICMP packets of type @t{icmp-type} on this node.
1164	@refill	1353	@refill
1165		1354
1166		1355
1167	@item	1356	@item
1168	@b{enable-rawip = yes|true|on | no|false|off}	1357	enable-rawip = yes|true|on | no|false|off
1169		1358
1170	@cindex enable-rawip	1359	@cindex enable-rawip
1171	See gvpe.protocol(7) for a description of the RAW IP transport protocol.	1360	See gvpe.protocol(7) for a description of the RAW IP transport protocol.
1172	@refill	1361	@refill
1173	Enable the RAW IPv4 transport using the @t{ip-proto} protocol (default: @t{no}).	1362	Enable the RAW IPv4 transport using the @t{ip-proto} protocol (default: @t{no}).
1174	@refill	1363	@refill
1175		1364
1176		1365
1177	@item	1366	@item
1178	@b{enable-tcp = yes|true|on | no|false|off}	1367	enable-tcp = yes|true|on | no|false|off
1179		1368
1180	@cindex enable-tcp	1369	@cindex enable-tcp
1181	See gvpe.protocol(7) for a description of the TCP transport protocol.	1370	See gvpe.protocol(7) for a description of the TCP transport protocol.
1182	@refill	1371	@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.	1372	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	1373	@refill
1185		1374
1186		1375
1187	@item	1376	@item
1188	@b{enable-udp = yes|true|on | no|false|off}	1377	enable-udp = yes|true|on | no|false|off
1189		1378
1190	@cindex enable-udp	1379	@cindex enable-udp
1191	See gvpe.protocol(7) for a description of the UDP transport protocol.	1380	See gvpe.protocol(7) for a description of the UDP transport protocol.
1192	@refill	1381	@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).	1382	Enable the UDPv4 transport using the @t{udp-port} port (default: @t{no}).
1194	@refill	1383	@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		1384
1198		1385
1199	@item	1386	@item
1200	@b{hostname = hostname | ip [can not be defaulted]}	1387	hostname = hostname | ip [can not be defaulted]
1201		1388
1202	@cindex hostname	1389	@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.	1390	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	1391	@refill
		1392	Note that DNS resolving is done synchronously, pausing the daemon. If that is an issue you need to specify IP addresses.
		1393	@refill
1205		1394
1206		1395
1207	@item	1396	@item
1208	@b{icmp-type = integer}	1397	icmp-type = integer
1209		1398
1210	@cindex icmp-type	1399	@cindex icmp-type
1211	Sets the type value to be used for outgoing (and incoming) packets sent via the ICMP transport.	1400	Sets the type value to be used for outgoing (and incoming) packets sent via the ICMP transport.
1212	@refill	1401	@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.	1402	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	1403	@refill
1215		1404
1216		1405
1217	@item	1406	@item
1218	@b{if-up-data = value}	1407	if-up-data = value
1219		1408
1220	@cindex if-up-data	1409	@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}.	1410	The value specified using this directive will be passed to the @t{if-up} script in the environment variable @t{IFUPDATA}.
1222	@refill	1411	@refill
1223		1412
1224		1413
1225	@item	1414	@item
1226	@b{inherit-tos = yes|true|on | no|false|off}	1415	inherit-tos = yes|true|on | no|false|off
1227		1416
1228	@cindex inherit-tos	1417	@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.	1418	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	1419	@refill
1231		1420
1232		1421
1233	@item	1422	@item
		1423	low-power = yes|true|on | no|false|off
		1424
		1425	@cindex low-power
		1426	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.
		1427	@refill
		1428	The typical low-power node would be a mobile phone, where wakeups and encryption can significantly increase power drain.
		1429	@refill
		1430
		1431
		1432	@item
1234	@b{max-retry = positive-number}	1433	max-retry = positive-number
1235		1434
1236	@cindex max-retry	1435	@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.	1436	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	1437	@refill
1239		1438
1240		1439
1241	@item	1440	@item
		1441	max-ttl = seconds
		1442
		1443	@cindex max-ttl
		1444	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.
		1445	@refill
		1446
		1447
		1448	@item
		1449	max-queue = positive-number>=1
		1450
		1451	@cindex max-queue
		1452	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.
		1453	@refill
		1454
		1455
		1456	@item
1242	@b{router-priority = 0 | 1 | positive-number>=2}	1457	router-priority = 0 | 1 | positive-number>=2
1243		1458
1244	@cindex router-priority	1459	@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.	1460	Sets the router priority of the given node (default: @t{0}, disabled).
1246	@refill	1461	@refill
1247	Make sure all hosts always connect (@t{connect = always}) to the router hosts, otherwise connecting to them might be impossible.	1462	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	1463	@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.	1464	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	1465	@refill
		1466	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).
		1467	@refill
		1468	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.
		1469	@refill
		1470	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}).
		1471	@refill
1251		1472
1252		1473
1253	@item	1474	@item
1254	@b{tcp-port = port-number}	1475	tcp-port = port-number
1255		1476
1256	@cindex tcp-port	1477	@cindex tcp-port
1257	Similar to @t{udp-port} (default: @t{655}), but sets the TCP port number.	1478	Similar to @t{udp-port} (default: @t{655}), but sets the TCP port number.
1258	@refill	1479	@refill
1259		1480
1260		1481
1261	@item	1482	@item
1262	@b{udp-port = port-number}	1483	udp-port = port-number
1263		1484
1264	@cindex udp-port	1485	@cindex udp-port
1265	Sets the port number used by the UDP protocol (default: @t{655}, not officially assigned by IANA!).	1486	Sets the port number used by the UDP protocol (default: @t{655}, not officially assigned by IANA!).
1266	@refill	1487	@refill
1267	@end itemize	1488	@end itemize
…		…
1275		1496
1276	@itemize	1497	@itemize
1277		1498
1278		1499
1279	@item	1500	@item
1280	@b{
1281	@cindex gvpe.conf
1282	gvpe.conf}	1501	gvpe.conf
1283		1502
1284	The config file.	1503	The config file.
1285	@refill	1504	@refill
1286		1505
1287		1506
1288	@item	1507	@item
1289	@b{
1290	@cindex if-up
1291	if-up}	1508	if-up
1292		1509
1293	The if-up script	1510	The if-up script
1294	@refill	1511	@refill
1295		1512
1296		1513
1297	@item	1514	@item
1298	@b{	1515	node-up, node-down
1299	@cindex node-up
1300	node-up,
1301	@cindex node-down
1302	node-down}
1303		1516
1304	If used the node up or node-down scripts.	1517	If used the node up or node-down scripts.
1305	@refill	1518	@refill
1306		1519
1307		1520
1308	@item	1521	@item
1309	@b{
1310	@cindex hostkey
1311	hostkey}	1522	hostkey
1312		1523
1313	The private key (taken from @t{hostkeys/nodename}) of the current host.	1524	The (default path of the) private key of the current host.
1314	@refill	1525	@refill
1315		1526
1316		1527
1317	@item	1528	@item
1318	@b{
1319	@cindex pubkey/nodename
1320	pubkey/nodename}	1529	pubkey/nodename
1321		1530
1322	The public keys of the other nodes, one file per node.	1531	The public keys of the other nodes, one file per node.
1323	@refill	1532	@refill
1324	@end itemize	1533	@end itemize
1325		1534
…		…
1350		1559
1351	@itemize	1560	@itemize
1352		1561
1353		1562
1354	@item	1563	@item
1355	@b{@strong{-c}, @strong{--config=}@emph{DIR}}	1564	@strong{-c}, @strong{--config=}@emph{DIR}
1356		1565
1357	Read configuration options from @emph{DIR}.	1566	Read configuration options from @emph{DIR}.
1358	@refill	1567	@refill
1359		1568
1360		1569
1361	@item	1570	@item
		1571	@strong{-g}, @strong{--generate-key=path}
		1572
		1573	Generates a single RSA key-pair. The public key will be stored in @file{@emph{path}} while the private key will be stored in @file{@emph{path} .privkey}. Neither file must be non-empty for this to succeed.
		1574	@refill
		1575	The public key file @file{@emph{path}} is normally copied to @file{pubkey/nodename} in the config directory on all nodes, while the private key @file{@emph{path}.privkey} should be copied to the file @file{hostkey} on the node the key is for.
		1576	@refill
		1577	It's recommended to generate the keypair on the node where it will be used, so that the private key file does not have to travel over the network.
		1578	@refill
		1579
		1580
		1581	@item
1362	@b{@strong{-g}, @strong{--generate-keys}}	1582	@strong{-G}, @strong{--generate-keys}
1363		1583
1364	Generate public/private RSA keypair and exit.	1584	Generate public/private RSA key-pairs for all nodes not having a key and exit.
1365	@refill	1585	@refill
		1586	Note that in normal configurations this will fail, as there cna only be one private key per host. To make this configuration work you need to specify separate keyfiles for hostkeys in your config file, e.g.:
		1587	@refill
1366		1588
1367		1589
		1590	@example
		1591	private-key = hostkeys/%s
		1592	@end example
		1593
		1594	Such a configuration makes it easier to distribute a configuration centrally but requires private keys to be transported securely over the network.
		1595	@refill
		1596
		1597
1368	@item	1598	@item
		1599	@strong{-q}, @strong{--quiet}
		1600
		1601	Suppresses messages the author finds nonessential for scripting purposes.
		1602	@refill
		1603
		1604
		1605	@item
1369	@b{@strong{--help}}	1606	@strong{--help}
1370		1607
1371	Display short list of options.	1608	Display short list of options.
1372	@refill	1609	@refill
1373		1610
1374		1611
1375	@item	1612	@item
1376	@b{@strong{--kill}[@strong{=}@emph{SIGNAL}]}	1613	@strong{--kill}[@strong{=}@emph{SIGNAL}]
1377		1614
1378	Attempt to kill a running @t{gvpectrl} (optionally with the specified @emph{SIGNAL} instead of @t{SIGTERM}) and exit.	1615	Attempt to kill a running @t{gvpectrl} (optionally with the specified @emph{SIGNAL} instead of @t{SIGTERM}) and exit.
1379	@refill	1616	@refill
1380		1617
1381		1618
1382	@item	1619	@item
1383	@b{@strong{--show-config}}	1620	@strong{--show-config}
1384		1621
1385	Show a summary of the configuration, and how gvpe interprets it. Can also be very useful when designing firewall scripts.	1622	Show a summary of the configuration, and how gvpe interprets it. Can also be very useful when designing firewall scripts.
1386	@refill	1623	@refill
1387		1624
1388		1625
1389	@item	1626	@item
1390	@b{@strong{--version}}	1627	@strong{--version}
1391		1628
1392	Output version information and exit.	1629	Output version information and exit.
1393	@refill	1630	@refill
1394	@end itemize	1631	@end itemize
1395		1632
…		…
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...}]	1651	@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	1652	@refill
1416		1653
1417		1654
1418	@section DESCRIPTION	1655	@section DESCRIPTION
1419	See the gvpe(5) manpage for an introduction to the gvpe suite.	1656	See the gvpe(5) man page for an introduction to the gvpe suite.
1420	@refill	1657	@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.	1658	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}
		1659	@refill
		1660	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	1661	@refill
1423	The optional arguments after the node name have to be of the form:	1662	The optional arguments after the node name have to be of the form:
1424	@refill	1663	@refill
1425		1664
1426		1665
1427	@example	1666	@example
1428	[I<nodename>.]var=value	1667	[I<nodename>.]var=value
1429	@end example	1668	@end example
1430		1669
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.	1670	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	1671	@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:	1672	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	1673	@refill
1435		1674
1436		1675
…		…
1447		1686
1448	@itemize	1687	@itemize
1449		1688
1450		1689
1451	@item	1690	@item
1452	@b{@strong{-c}, @strong{--config=}@emph{DIR}}	1691	@strong{-c}, @strong{--config=}@emph{DIR}
1453		1692
1454	Read configuration options from @emph{DIR}	1693	Read configuration options from @emph{DIR}
1455	@refill	1694	@refill
1456		1695
1457		1696
1458	@item	1697	@item
1459	@b{@strong{-d}, @strong{--l=}@emph{LEVEL}}	1698	@strong{-d}, @strong{--l=}@emph{LEVEL}
1460		1699
1461	Set logging level to @emph{LEVEL} (one of: noise, trace, debug, info, notice, warn, error, critical).	1700	Set logging level to @emph{LEVEL} (one of: noise, trace, debug, info, notice, warn, error, critical).
1462	@refill	1701	@refill
1463		1702
1464		1703
1465	@item	1704	@item
1466	@b{@strong{--help}}	1705	@strong{--help}
1467		1706
1468	Display short list of options.	1707	Display short list of options.
1469	@refill	1708	@refill
1470		1709
1471		1710
1472	@item	1711	@item
1473	@b{@strong{-D}, @strong{--no-detach}}	1712	@strong{-D}, @strong{--no-detach}
1474		1713
1475	Don't fork and detach but stay in foreground and log messages to stderr in addition to syslog.	1714	Don't fork and detach but stay in foreground and log messages to stderr in addition to syslog.
1476	@refill	1715	@refill
1477		1716
1478		1717
1479	@item	1718	@item
1480	@b{@strong{-L}, @strong{--mlock}}	1719	@strong{-L}, @strong{--mlock}
1481		1720
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.	1721	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	1722	@refill
1484		1723
1485		1724
1486	@item	1725	@item
1487	@b{@strong{--version}}	1726	@strong{--version}
1488		1727
1489	Output version information and exit.	1728	Output version information and exit.
1490	@refill	1729	@refill
1491	@end itemize	1730	@end itemize
1492		1731
…		…
1497		1736
1498	@itemize	1737	@itemize
1499		1738
1500		1739
1501	@item	1740	@item
1502	@b{HUP}	1741	HUP
1503		1742
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.	1743	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	1744	@refill
1506		1745
1507		1746
1508	@item	1747	@item
1509	@b{TERM}	1748	TERM
1510		1749
1511	Closes/resets all connections and exits.	1750	Closes/resets all connections and exits.
1512	@refill	1751	@refill
1513		1752
1514		1753
1515	@item	1754	@item
1516	@b{USR1}	1755	USR1
1517		1756
1518	Dump current network status into the syslog (at loglevel @t{notice}, so make sure your loglevel allows this).	1757	Dump current network status into the syslog (at loglevel @t{notice}, so make sure your loglevel allows this).
1519	@refill	1758	@refill
1520	@end itemize	1759	@end itemize
1521		1760
…		…
1526		1765
1527	@itemize	1766	@itemize
1528		1767
1529		1768
1530	@item	1769	@item
1531	@b{@t{/etc/gvpe/gvpe.conf}}	1770	@t{/etc/gvpe/gvpe.conf}
1532		1771
1533	The configuration file for @t{gvpe}.	1772	The configuration file for @t{gvpe}.
1534	@refill	1773	@refill
1535		1774
1536		1775
1537	@item	1776	@item
1538	@b{@t{/etc/gvpe/if-up}}	1777	@t{/etc/gvpe/if-up}
1539		1778
1540	Script which is executed as soon as the virtual network device has been allocated. Purpose is to further configure that device.	1779	Script which is executed as soon as the virtual network device has been allocated. Purpose is to further configure that device.
1541	@refill	1780	@refill
1542		1781
1543		1782
1544	@item	1783	@item
1545	@b{@t{/etc/gvpe/node-up}}	1784	@t{/etc/gvpe/node-up}
1546		1785
1547	Script which is executed whenever a node connects to this node. This can be used for example to run nsupdate.	1786	Script which is executed whenever a node connects to this node. This can be used for example to run nsupdate.
1548	@refill	1787	@refill
1549		1788
1550		1789
1551	@item	1790	@item
1552	@b{@t{/etc/gvpe/node-down}}	1791	@t{/etc/gvpe/node-down}
1553		1792
1554	Script which is executed whenever a connection to another node is lost. for example to run nsupdate.	1793	Script which is executed whenever a connection to another node is lost. for example to run nsupdate.
1555	@refill	1794	@refill
1556		1795
1557		1796
1558	@item	1797	@item
1559	@b{@t{/etc/gvpe/pubkey/*}}	1798	@t{/etc/gvpe/pubkey/*}
1560		1799
1561	The directory containing the public keys for every node, usually autogenerated by executing @t{gvpectrl --generate-keys}.	1800	The directory containing the public keys for every node, one file per node with the name of the node.
1562	@refill	1801	@refill
1563		1802
1564		1803
1565	@item	1804	@item
		1805	@t{/etc/gvpe/hostkey}
		1806
		1807	The file containing the private key of the node GVPE runs on. Unlike all the other files in the @file{/etc/gvpe} directory, this file usually differes for each node that GVPE runs on.
		1808	@refill
		1809
		1810
		1811	@item
1566	@b{@t{/var/run/gvpe.pid}}	1812	@t{/var/run/gvpe.pid}
1567		1813
1568	The PID of the currently running @t{gvpe} is stored in this file.	1814	The PID of the currently running @t{gvpe} is stored in this file.
1569	@refill	1815	@refill
1570	@end itemize	1816	@end itemize
1571		1817
…		…
1587		1833
1588		1834
1589	@section Overview	1835	@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.	1836	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	1837	@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.	1838	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	1839	@refill
1594		1840
1595		1841
1596	@section PART 1: Transport protocols	1842	@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.	1843	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	1844	@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:	1845	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	1846	@refill
1601		1847
1602		1848
1603	@subsection RAW IP	1849	@subsection RAW IP
1604	This protocol is the best choice, performance-wise, as the minimum overhead per packet is only 38 bytes.	1850	This protocol is the best choice, performance-wise, as the minimum overhead per packet is only 38 bytes.
1605	@refill	1851	@refill
1606	It works by sending the VPN payload using raw ip frames (using the protocol set by @t{ip-proto}).	1852	It works by sending the VPN payload using raw IP frames (using the protocol set by @t{ip-proto}).
1607	@refill	1853	@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.	1854	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	1855	@refill
1610		1856
1611		1857
1612	@subsection ICMP	1858	@subsection ICMP
1613	This protocol offers very low overhead (minimum 42 bytes), and can sometimes tunnel through firewalls when other protocols cannot.	1859	This protocol offers very low overhead (minimum 42 bytes), and can sometimes tunnel through firewalls when other protocols can not.
1614	@refill	1860	@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.	1861	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	1862	@refill
1617	This transport should only be used if other transports (i.e. raw ip) are not available or undesirable (due to their overhead).	1863	This transport should only be used if other transports (i.e. raw IP) are not available or undesirable (due to their overhead).
1618	@refill	1864	@refill
1619		1865
1620		1866
1621	@subsection UDP	1867	@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).	1868	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.	1870	It should be used if RAW IP is not available.
1625	@refill	1871	@refill
1626		1872
1627		1873
1628	@subsection TCP	1874	@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.	1875	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	1876	@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.	1877	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	1878	@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.	1879	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	1880	@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.	1881	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	1882	@refill
1637		1883
1638		1884
1639	@subsection DNS	1885	@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.	1886	@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	1887	@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.	1888	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	1889	@refill
1644	In addition, the same problems as the TCP transport also plague this protocol.	1890	In addition, the same problems as the TCP transport also plague this protocol.
1645	@refill	1891	@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).	1892	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	1893	@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).	1894	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).
		1895	@refill
		1896	Fine-tuning needs to be done by editing @t{src/vpn_dns.C} directly.
1651	@refill	1897	@refill
1652		1898
1653		1899
1654	@section PART 2: The GNU VPE protocol	1900	@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.	1901	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	1902	@refill
1657		1903
1658		1904
1659	@subsection Anatomy of a VPN packet	1905	@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.	1906	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	1907	@refill
1662		1908
1663		1909
1664	@example	1910	@example
1665	+------+------+--------+------+	1911	+------+------+--------+------+
1666	| HMAC | TYPE | SRCDST | DATA |	1912	| HMAC | TYPE | SRCDST | DATA |
1667	+------+------+--------+------+	1913	+------+------+--------+------+
1668	@end example	1914	@end example
1669		1915
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.	1916	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	1917	@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.).	1918	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	1919	@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.	1920	SRCDST is a three byte field which contains the source and destination node IDs (12 bits each).
1675	@refill	1921	@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:	1922	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	1923	@refill
1678		1924
1679		1925
1680	@example	1926	@example
1681	+------+------+--------+------+-------+------+	1927	+------+------+--------+-------+------+
1682	| HMAC | TYPE | SRCDST | RAND | SEQNO | DATA |	1928	| HMAC | TYPE | SRCDST | SEQNO | DATA |
1683	+------+------+--------+------+-------+------+	1929	+------+------+--------+-------+------+
1684	@end example	1930	@end example
1685		1931
1686	RAND is a sequence of fully random bytes, used to increase the entropy of the data for encryption purposes.
1687	@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.	1932	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	1933	@refill
		1934	The encryption is done on SEQNO+DATA in CTR mode with IV generated from the seqno (for AES: seqno || seqno || seqno || (u32)0), which ensures uniqueness for a given key.
		1935	@refill
1690		1936
1691		1937
1692	@subsection The authentification protocol	1938	@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.	1939	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	1940	@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.	1941	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	1942	@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.	1943	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	1944	@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.	1945	In detail, the challenge consist of:
1700	@refill	1946	@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).	1947
		1948
		1949	@example
		1950	RSA-OAEP (SEQNO MAC CIPHER SALT EXTRA-AUTH) ECDH1
		1951	@end example
		1952
		1953	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.
		1954	@refill
		1955	The remote node decrypts the RSA data, generates its own ECDH key (ECDH2), and replies with:
		1956	@refill
		1957
		1958
		1959	@example
		1960	HKDF-Expand (HKDF-Extract (ECDH2, RSA), ECDH1, AUTH_DIGEST_SIZE) ECDH2
		1961	@end example
		1962
		1963	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.
		1964	@refill
		1965	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).
		1966	@refill
		1967	The HMAC key for sending is generated as follow:
		1968	@refill
		1969
		1970
		1971	@example
		1972	HMAC_KEY = HKDF-Expand (HKDF-Extract (REMOTE_SALT, MAC ECDH_SECRET), info, HMAC_MD_SIZE)
		1973	@end example
		1974
		1975	It extracts from MAC and ECDH_SECRET using the @emph{remote} SALT, then expands using a static info string.
		1976	@refill
		1977	The cipher key is generated in the same way, except using the CIPHER part of the original challenge.
		1978	@refill
		1979	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.
		1980	@refill
		1981	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	1982	@refill
1703		1983
1704		1984
1705	@subsection Retrying	1985	@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.	1986	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	1987	@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).	1988	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).
		1989	@refill
		1990	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.
		1991	@refill
		1992	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	1993	@refill
1710		1994
1711		1995
1712	@subsection Routing and Protocol translation	1996	@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.	1997	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	1998	@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.	1999
1716	@refill	2000
		2001	@itemize
		2002
		2003
		2004	@item
		2005	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.
		2006
		2007
		2008
		2009	@item
		2010	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).
		2011
		2012
		2013
		2014	@item
		2015	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.
		2016
		2017
		2018
		2019	@item
		2020	If no such router exists, then GVPE will simply send the packet to the node with the highest priority available.
		2021
		2022
		2023
		2024	@item
		2025	Failing all that, the packet will be dropped.
		2026
		2027	@end itemize
		2028
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.	2029	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	2030	@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.	2031	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	2032	@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.	2033	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	2034	@refill
1727		2035
1728		2036
1729		2037
1730	@node Simple Example,Complex Example,gvpe.protocol,Top	2038	@node Simple Example,Complex Example,gvpe.protocol,Top
…		…
1739	@example	2047	@example
1740	enable-udp = yes # use UDP	2048	enable-udp = yes # use UDP
1741	udp-port = 407 # use this UDP port	2049	udp-port = 407 # use this UDP port
1742	mtu = 1492 # handy for TDSL	2050	mtu = 1492 # handy for TDSL
1743	ifname = vpn0 # I prefer vpn0 over e.g. tap0	2051	ifname = vpn0 # I prefer vpn0 over e.g. tap0
1744	@end example
1745		2052
1746
1747
1748	@example
1749	node = huffy # arbitrary node name	2053	node = huffy # arbitrary node name
1750	hostname = 1.2.3.4 # ip address if this host	2054	hostname = 1.2.3.4 # ip address if this host
1751	@end example
1752		2055
1753
1754
1755	@example
1756	node = welshy	2056	node = welshy
1757	hostname = www.example.net # resolve at connection time	2057	hostname = www.example.net # resolve at connection time
1758	@end example
1759		2058
1760
1761
1762	@example
1763	node = wheelery	2059	node = wheelery
1764	# no hostname, will be determinded dynamically using router1 or router2	2060	# no hostname, will be determinded dynamically using router1 or router2
1765	@end example	2061	@end example
1766		2062
1767	@t{gvpe} will execute the @t{if-up} script on every hosts, which, for linux, could look like this for all three hosts:	2063	@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