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

Comparing gvpe/doc/gvpe.conf.5.pod (file contents):
Revision 1.20 by pcg, Sun Aug 10 22:18:58 2008 UTC vs.
Revision 1.21 by pcg, Mon Sep 1 05:31:28 2008 UTC

… …
2 2
3gvpe.conf - configuration file for the GNU VPE daemon 3gvpe.conf - configuration file for the GNU VPE daemon
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 # global options for all nodes
7 udp-port = 407 8 udp-port = 407
8 mtu = 1492 9 mtu = 1492
9 ifname = vpn0 10 ifname = vpn0
10 11
12 # first node is named branch1 and is at 1.2.3.4
11 node = branch1 13 node = branch1
12 hostname = 1.2.3.4 14 hostname = 1.2.3.4
13 15
16 # second node uses dns to resolve the address
14 node = branch2 17 node = branch2
15 hostname = www.example.net 18 hostname = www.example.net
16 udp-port = 500 # this host uses a different udp-port 19 udp-port = 500 # this host uses a different udp-port
17 20
21 # third node has no fixed ip address
18 node = branch3 22 node = branch3
19 connect = ondemand 23 connect = ondemand
20 24
21=head1 DESCRIPTION 25=head1 DESCRIPTION
22 26
… …
28 32
29The only exception to the above is the "on" directive that can prefix any 33The only exception to the above is the "on" directive that can prefix any
30C<name = value> setting and will only "execute" it on the named node, or 34C<name = value> setting and will only "execute" it on the named node, or
31(if the nodename starts with "!") on all nodes except the named one. 35(if the nodename starts with "!") on all nodes except the named one.
32 36
33 name = value 37For example, set the MTU to C<1450> everywhere, loglevel to C<noise> on
38branch1, and connect to C<ondemand> everywhere but on branch2:
39
40 mtu = 1450
34 on branch1 loglevel = noise 41 on branch1 loglevel = noise
35 on !branch2 connect = ondemand 42 on !branch2 connect = ondemand
36 43
37All settings are executed "in order", that is, later settings of the same 44All settings are applied "in order", that is, later settings of the same
38variable overwrite earlier ones. 45variable overwrite earlier ones.
39 46
40=head1 ANATOMY OF A CONFIG FILE 47=head1 ANATOMY OF A CONFIG FILE
41 48
42Usually, a config file starts with global settings (like the udp port to 49Usually, a config file starts with a few global settings (like the UDP
43listen on), followed by node-specific sections that begin with a C<node = 50port to listen on), followed by node-specific sections that begin with a
44nickname> line. 51C<node = nickname> line.
45 52
46Every node that is part of the network must have a section that starts 53Every node that is part of the network must have a section that starts
47with C<node = nickname>. The number and order of the nodes is important 54with C<node = nickname>. The number and order of the nodes is important
48and must be the same on all nodes. It is not uncommon for node sections to 55and must be the same on all nodes. It is not uncommon for node sections to
49be completely empty - if the default values are right. 56be completely empty - if the default values are right.
… …
62 69
63=over 4 70=over 4
64 71
65=item dns-forw-host = hostname/ip 72=item dns-forw-host = hostname/ip
66 73
67The dns server to forward dns requests to for the DNS tunnel protocol 74The DNS server to forward DNS requests to for the DNS tunnel protocol
68(default: C<127.0.0.1>, changing it is highly recommended). 75(default: C<127.0.0.1>, changing it is highly recommended).
69 76
70=item dns-forw-port = port-number 77=item dns-forw-port = port-number
71 78
72The port where the C<dns-forw-host> is to be contacted (default: C<53>, 79The port where the C<dns-forw-host> is to be contacted (default: C<53>,
… …
78(default: C<100>). GVPE will never issue more requests then the given 85(default: C<100>). GVPE will never issue more requests then the given
79limit without receiving replies. In heavily overloaded situations it might 86limit without receiving replies. In heavily overloaded situations it might
80help to set this to a low number (e.g. C<3> or even C<1>) to limit the 87help to set this to a low number (e.g. C<3> or even C<1>) to limit the
81number of parallel requests. 88number of parallel requests.
82 89
83The default should be working ok for most links. 90The default should be working OK for most links.
84 91
85=item dns-overlap-factor = float 92=item dns-overlap-factor = float
86 93
87The DNS transport uses the minimum request latency (B<min_latency>) seen 94The DNS transport uses the minimum request latency (B<min_latency>) seen
88during a connection as it's timing base. This factor (default: C<0.5>, 95during a connection as it's timing base. This factor (default: C<0.5>,
… …
91request might be generated every B<min_latency> seconds, which means on 98request might be generated every B<min_latency> seconds, which means on
92average there should only ever be one outstanding request. A factor of 99average there should only ever be one outstanding request. A factor of
93C<0.5> means that GVPE will send requests twice as often as the minimum 100C<0.5> means that GVPE will send requests twice as often as the minimum
94latency measured. 101latency measured.
95 102
96For congested or picky dns forwarders you could use a value nearer to or 103For congested or picky DNS forwarders you could use a value nearer to or
97exceeding C<1>. 104exceeding C<1>.
98 105
99The default should be working ok for most links. 106The default should be working OK for most links.
100 107
101=item dns-send-interval = send-interval-in-seconds 108=item dns-send-interval = send-interval-in-seconds
102 109
103The minimum send interval (= maximum rate) that the DNS transport will 110The minimum send interval (= maximum rate) that the DNS transport will
104use to send new DNS requests. GVPE will not exceed this rate even when 111use to send new DNS requests. GVPE will not exceed this rate even when
… …
106not send more than 100 DNS requests per connection per second. For 113not send more than 100 DNS requests per connection per second. For
107high-bandwidth links you could go lower, e.g. to C<0.001> or so. For 114high-bandwidth links you could go lower, e.g. to C<0.001> or so. For
108congested or rate-limited links, you might want to go higher, say C<0.1>, 115congested or rate-limited links, you might want to go higher, say C<0.1>,
109C<0.2> or even higher. 116C<0.2> or even higher.
110 117
111The default should be working ok for most links. 118The default should be working OK for most links.
112 119
113=item dns-timeout-factor = float 120=item dns-timeout-factor = float
114 121
115Factor to multiply the C<min_latency> (see C<dns-overlap-factor>) by to 122Factor to multiply the C<min_latency> (see C<dns-overlap-factor>) by to
116get request timeouts. The default of C<8> means that the DNS transport 123get request timeouts. The default of C<8> means that the DNS transport
… …
120 127
121For congested links a higher value might be necessary (e.g. C<30>). If 128For congested links a higher value might be necessary (e.g. C<30>). If
122the link is very stable lower values (e.g. C<2>) might work 129the link is very stable lower values (e.g. C<2>) might work
123nicely. Values near or below C<1> makes no sense whatsoever. 130nicely. Values near or below C<1> makes no sense whatsoever.
124 131
125The default should be working ok for most links but will result in low 132The default should be working OK for most links but will result in low
126throughput if packet loss is high. 133throughput if packet loss is high.
127 134
128=item if-up = relative-or-absolute-path 135=item if-up = relative-or-absolute-path
129 136
130Sets the path of a script that should be called immediately after the 137Sets the path of a script that should be called immediately after the
131network interface is initialized (but not neccessarily up). The following 138network interface is initialized (but not necessarily up). The following
132environment variables are passed to it (the values are just examples). 139environment variables are passed to it (the values are just examples).
133 140
134Variables that have the same value on all nodes: 141Variables that have the same value on all nodes:
135 142
136=over 4 143=over 4
… …
175=item MAC=fe:fd:80:00:00:01 182=item MAC=fe:fd:80:00:00:01
176 183
177The MAC address the network interface has to use. 184The MAC address the network interface has to use.
178 185
179Might be used to initialize interfaces on platforms where GVPE does not 186Might be used to initialize interfaces on platforms where GVPE does not
180do this automatically. Please see the C<gvpe.osdep(5)> manpage for 187do this automatically. Please see the C<gvpe.osdep(5)> man page for
181platform-specific information. 188platform-specific information.
182 189
183=item NODENAME=branch1 190=item NODENAME=branch1
184 191
185The nickname of the node. 192The nickname of the node.
… …
202 ip link set $IFNAME up 209 ip link set $IFNAME up
203 [ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME 210 [ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME
204 [ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME 211 [ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME
205 ip route add 10.0.0.0/8 dev $IFNAME 212 ip route add 10.0.0.0/8 dev $IFNAME
206 213
207More complicated examples (using routing to reduce arp traffic) can be 214More complicated examples (using routing to reduce ARP traffic) can be
208found in the etc/ subdirectory of the distribution. 215found in the F<etc/> subdirectory of the distribution.
209 216
210=item ifname = devname 217=item ifname = devname
211 218
212Sets the tun interface name to the given name. The default is OS-specific 219Sets the tun interface name to the given name. The default is OS-specific
213and most probably something like C<tun0>. 220and most probably something like C<tun0>.
… …
227global option because all nodes must use the same protocol, and since 234global option because all nodes must use the same protocol, and since
228there are no port numbers, you cannot easily run more than one gvpe 235there are no port numbers, you cannot easily run more than one gvpe
229instance using the same protocol, nor can you share the protocol with 236instance using the same protocol, nor can you share the protocol with
230other programs. 237other programs.
231 238
232The default is 47 (GRE), which has a good chance of tunneling through 239The default is 47 (GRE), which has a good chance of tunneling
233firewalls (but note that the rawip protocol is not GRE compatible). Other 240through firewalls (but note that gvpe's rawip protocol is not GRE
234common choices are 50 (IPSEC, ESP), 51 (IPSEC, AH), 4 (IPIP tunnels) or 98 241compatible). Other common choices are 50 (IPSEC, ESP), 51 (IPSEC, AH), 4
235(ENCAP, rfc1241) 242(IPIP tunnels) or 98 (ENCAP, rfc1241)
236 243
237=item http-proxy-host = hostname/ip 244=item http-proxy-host = hostname/ip
238 245
239The C<http-proxy-*> family of options are only available if gvpe was 246The C<http-proxy-*> family of options are only available if gvpe was
240compiled with the C<--enable-http-proxy> option and enable tunneling of 247compiled with the C<--enable-http-proxy> option and enable tunneling of
… …
243C<http-proxy-host> and C<http-proxy-port> should specify the hostname and 250C<http-proxy-host> and C<http-proxy-port> should specify the hostname and
244port number of the proxy server. See C<http-proxy-loginpw> if your proxy 251port number of the proxy server. See C<http-proxy-loginpw> if your proxy
245requires authentication. 252requires authentication.
246 253
247Please note that gvpe will still try to resolve all hostnames in the 254Please note that gvpe will still try to resolve all hostnames in the
248configuration file, so if you are behind a proxy without access to a dns 255configuration file, so if you are behind a proxy without access to a DNS
249server better use numerical IP addresses. 256server better use numerical IP addresses.
250 257
251To make best use of this option disable all protocols except tcp in your 258To make best use of this option disable all protocols except TCP in your
252config file and make sure your routers (or all other nodes) are listening 259config file and make sure your routers (or all other nodes) are listening
253on a port that the proxy allows (443, https, is a common choice). 260on a port that the proxy allows (443, https, is a common choice).
254 261
255If you have a router, connecting to it will suffice. Otherwise tcp must be 262If you have a router, connecting to it will suffice. Otherwise TCP must be
256enabled on all nodes. 263enabled on all nodes.
257 264
258Example: 265Example:
259 266
260 http-proxy-host = proxy.example.com 267 http-proxy-host = proxy.example.com
… …
266The port where your proxy server listens. 273The port where your proxy server listens.
267 274
268=item http-proxy-auth = login:password 275=item http-proxy-auth = login:password
269 276
270The optional login and password used to authenticate to the proxy server, 277The optional login and password used to authenticate to the proxy server,
271seperated by a literal colon (C<:>). Only basic authentication is 278separated by a literal colon (C<:>). Only basic authentication is
272currently supported. 279currently supported.
273 280
274=item keepalive = seconds 281=item keepalive = seconds
275 282
276Sets the keepalive probe interval in seconds (default: C<60>). After this 283Sets the keepalive probe interval in seconds (default: C<60>). After this
277many seconds of inactivity the daemon will start to send keepalive probe 284many seconds of inactivity the daemon will start to send keepalive probe
278every 5 seconds until it receives a reply from the other end. If no reply 285every 3 seconds until it receives a reply from the other end. If no reply
279is received within 30 seconds, the peer is considered unreachable and the 286is received within 15 seconds, the peer is considered unreachable and the
280connection is closed. 287connection is closed.
281 288
282=item loglevel = noise|trace|debug|info|notice|warn|error|critical 289=item loglevel = noise|trace|debug|info|notice|warn|error|critical
283 290
284Set the logging level. Connection established messages are logged at level 291Set the logging level. Connection established messages are logged at level
… …
286 293
287=item mtu = bytes 294=item mtu = bytes
288 295
289Sets the maximum MTU that should be used on outgoing packets (basically 296Sets the maximum MTU that should be used on outgoing packets (basically
290the MTU of the outgoing interface) The daemon will automatically calculate 297the MTU of the outgoing interface) The daemon will automatically calculate
291maximum overhead (e.g. udp header size, encryption blocksize...) and pass 298maximum overhead (e.g. UDP header size, encryption blocksize...) and pass
292this information to the C<if-up> script. 299this information to the C<if-up> script.
293 300
294Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp). 301Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp).
295 302
296This value must be the minimum of the mtu values of all nodes. 303This value must be the minimum of the MTU values of all nodes.
297 304
298=item node = nickname 305=item node = nickname
299 306
300Not really a config setting but introduces a node section. The nickname is 307Not really a config setting but introduces a node section. The nickname is
301used to select the right configuration section and must be passed as an 308used to select the right configuration section and must be passed as an
… …
336with STATE=DOWN. 343with STATE=DOWN.
337 344
338=back 345=back
339 346
340Here is a nontrivial example that uses nsupdate to update the name => ip 347Here is a nontrivial example that uses nsupdate to update the name => ip
341mapping in some dns zone: 348mapping in some DNS zone:
342 349
343 #!/bin/sh 350 #!/bin/sh
344 { 351 {
345 echo update delete $DESTNODE.lowttl.example.net. a 352 echo update delete $DESTNODE.lowttl.example.net. a
346 echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP 353 echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP
… …
363be doubled. A single C<%s> is replaced by the hostname, so you could 370be doubled. A single C<%s> is replaced by the hostname, so you could
364use paths like C<hostkeys/%s> to fetch the files at the location where 371use paths like C<hostkeys/%s> to fetch the files at the location where
365C<gvpectrl> puts them. 372C<gvpectrl> puts them.
366 373
367Since only the private key file of the current node is used and the 374Since only the private key file of the current node is used and the
368private key file should be kept secret per-node to avoid spoofings, it is 375private key file should be kept secret per-node to avoid spoofing, it is
369not recommended to use this feature. 376not recommended to use this feature.
370 377
371=item rekey = seconds 378=item rekey = seconds
372 379
373Sets the rekeying interval in seconds (default: C<3600>). Connections are 380Sets the rekeying interval in seconds (default: C<3600>). Connections are
374reestablished every C<rekey> seconds. 381reestablished every C<rekey> seconds, making them use a new encryption
382key.
375 383
376=back 384=back
377 385
378=head2 NODE SPECIFIC SETTINGS 386=head2 NODE SPECIFIC SETTINGS
379 387
… …
390 398
391=item compress = yes|true|on | no|false|off 399=item compress = yes|true|on | no|false|off
392 400
393Wether to compress data packets sent to this node (default: C<yes>). 401Wether to compress data packets sent to this node (default: C<yes>).
394Compression is really cheap even on slow computers and has no size 402Compression is really cheap even on slow computers and has no size
395overhead at all, so enabling this is a good idea. 403overhead at all, so enabling this is often a good idea.
396 404
397=item connect = ondemand | never | always | disabled 405=item connect = ondemand | never | always | disabled
398 406
399Sets the connect mode (default: C<always>). It can be C<always> (always 407Sets the connect mode (default: C<always>). It can be C<always> (always
400try to establish and keep a connection to the given node), C<never> 408try to establish and keep a connection to the given node), C<never>
… …
413C<allow-direct> and C<deny-direct> statements. This only makes sense in 421C<allow-direct> and C<deny-direct> statements. This only makes sense in
414networks with routers, as routers are required for indirect connections. 422networks with routers, as routers are required for indirect connections.
415 423
416Sometimes, a node cannot reach some other nodes for reasons of network 424Sometimes, a node cannot reach some other nodes for reasons of network
417connectivity. For example, a node behind a firewall that only allows 425connectivity. For example, a node behind a firewall that only allows
418conenctions to/from a single other node in the network. In this case one 426connections to/from a single other node in the network. In this case one
419should specify C<deny-direct = *> and C<allow-direct = othernodename> (the other 427should specify C<deny-direct = *> and C<allow-direct = othernodename> (the other
420node I<must> be a router for this to work). 428node I<must> be a router for this to work).
421 429
422The algorithm to check wether a connection may be direct is as follows: 430The algorithm to check whether a connection may be direct is as follows:
423 431
4241. Other node mentioned in a C<allow-direct>? If yes, allow the connection. 4321. Other node mentioned in an C<allow-direct>? If yes, allow the connection.
425 433
4262. Other node mentioned in a C<deny-direct>? If yes, deny direct connections. 4342. Other node mentioned in a C<deny-direct>? If yes, deny direct connections.
427 435
4283. Allow the connection. 4363. Allow the connection.
429 437
… …
469 477
470=item enable-icmp = yes|true|on | no|false|off 478=item enable-icmp = yes|true|on | no|false|off
471 479
472See gvpe.protocol(7) for a description of the ICMP transport protocol. 480See gvpe.protocol(7) for a description of the ICMP transport protocol.
473 481
474Enable the ICMP transport using icmp packets of type C<icmp-type> on this 482Enable the ICMP transport using ICMP packets of type C<icmp-type> on this
475node. 483node.
476 484
477=item enable-rawip = yes|true|on | no|false|off 485=item enable-rawip = yes|true|on | no|false|off
478 486
479See gvpe.protocol(7) for a description of the RAW IP transport protocol. 487See gvpe.protocol(7) for a description of the RAW IP transport protocol.
… …
495 503
496Enable the UDPv4 transport using the C<udp-port> port (default: C<no>, 504Enable the UDPv4 transport using the C<udp-port> port (default: C<no>,
497unless no other protocol is enabled for a node, in which case this 505unless no other protocol is enabled for a node, in which case this
498protocol is enabled automatically). 506protocol is enabled automatically).
499 507
500NOTE: Please specify C<enable-udp = yes> if you want t use it even though 508NOTE: Please specify C<enable-udp = yes> if you want to use it even though
501it might get switched on automatically, as some future version might 509it might get switched on automatically, as some future version might
502default to another default protocol. 510default to another default protocol.
503 511
504=item hostname = hostname | ip [can not be defaulted] 512=item hostname = hostname | ip [can not be defaulted]
505 513
506Forces the address of this node to be set to the given dns hostname or ip 514Forces the address of this node to be set to the given DNS hostname or IP
507address. It will be resolved before each connect request, so dyndns should 515address. It will be resolved before each connect request, so dyndns should
508work fine. If this setting is not specified and a router is available, 516work fine. If this setting is not specified and a router is available,
509then the router will be queried for the address of this node. Otherwise, 517then the router will be queried for the address of this node. Otherwise,
510the connection attempt will fail. 518the connection attempt will fail.
511 519
520Note that DNS resolving is done synchronously, pausing the daemon. If that
521is an issue you need to specify IP addresses.
522
512=item icmp-type = integer 523=item icmp-type = integer
513 524
514Sets the type value to be used for outgoing (and incoming) packets sent 525Sets the type value to be used for outgoing (and incoming) packets sent
515via the ICMP transport. 526via the ICMP transport.
516 527
517The default is C<0> (which is C<echo-reply>, also known as 528The default is C<0> (which is C<echo-reply>, also known as
518"ping-replies"). Other useful values include C<8> (C<echo-request>, a.k.a. 529"ping-reply"). Other useful values include C<8> (C<echo-request>, a.k.a.
519"ping") and C<11> (C<time-exceeded>), but any 8-bit value can be used. 530"ping") and C<11> (C<time-exceeded>), but any 8-bit value can be used.
520 531
521=item if-up-data = value 532=item if-up-data = value
522 533
523The value specified using this directive will be passed to the C<if-up> 534The value specified using this directive will be passed to the C<if-up>
… …
532 543
533=item max-retry = positive-number 544=item max-retry = positive-number
534 545
535The maximum interval in seconds (default: C<3600>, one hour) between 546The maximum interval in seconds (default: C<3600>, one hour) between
536retries to establish a connection to this node. When a connection cannot 547retries to establish a connection to this node. When a connection cannot
537be established, gvpe uses exponential backoff capped at this value. It's 548be established, gvpe uses exponential back-off capped at this value. It's
538sometimes useful to set this to a much lower value (e.g. C<120>) on 549sometimes useful to set this to a much lower value (e.g. C<120>) on
539connections to routers that usually are stable but sometimes are down, to 550connections to routers that usually are stable but sometimes are down, to
540assure quick reconnections even after longer downtimes. 551assure quick reconnections even after longer downtimes.
541 552
542=item max-ttl = seconds 553=item max-ttl = seconds

Diff Legend

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