--- gvpe/doc/gvpe.conf.5.pod 2005/03/14 17:40:01 1.9 +++ gvpe/doc/gvpe.conf.5.pod 2005/06/21 08:46:53 1.14 @@ -23,8 +23,8 @@ The gvpe config file consists of a series of lines that contain C pairs. Empty lines are ignored. Comments start with a C<#> and extend to the end of the line. They can be used on their own lines, or -after any directives. Spaces are allowed before or after the C<=> sign or -after values, but not within the variable names or values themselves. +after any directives. Whitespace is allowed around the C<=> sign or after +values, but not within the variable names or values themselves. The only exception to the above is the "on" directive that can prefix any C setting and will only "execute" it on the named node, or @@ -72,11 +72,65 @@ The port where the C is to be contacted (default: C<53>, which is fine in most cases). +=item dns-max-outstanding = integer-number-of-requests + +The maximum number of outstanding DNS transport requests +(default: C<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. C<3> or even C<1>) to limit the +number of parallel requests. + +The default should be working ok for most links. + +=item dns-overlap-factor = float + +The DNS transport uses the minimum request latency (B) seen +during a connection as it's timing base. This factor (default: C<0.5>, +must be > 0) is multiplied by B to get the maximum sending +rate (= minimum send interval), i.e. a factor of C<1> means that a new +request might be generated every B seconds, which means on +average there should only ever be one outstanding request. A factor of +C<0.5> means that GVPE will send requests twice as often as the minimum +latency measured. + +For congested or picky dns forwarders you could use a value nearer to or +exceeding C<1>. + +The default should be working ok for most links. + +=item dns-send-interval = send-interval-in-seconds + +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 C<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 C<0.001> or so. For +congested or rate-limited links, you might want to go higher, say C<0.1>, +C<0.2> or even higher. + +The default should be working ok for most links. + +=item dns-timeout-factor = float + +Factor to multiply the C (see C) by to +get request timeouts. The default of C<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. + +For congested links a higher value might be necessary (e.g. C<30>). If the +link is very stable lower values (e.g. C<2>) might work nicely. Values +near or below C<1> makes no sense whatsoever. + +The default should be working ok for most links. + =item if-up = relative-or-absolute-path 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): +environment variables are passed to it (the values are just examples). + +Variables that have the same value on all nodes: =over 4 @@ -86,46 +140,64 @@ =item IFNAME=vpn0 -The interface to initialize. +The network interface to initialize. + +=item IFTYPE=native # or tincd + +=item IFSUBTYPE=linux # or freebsd, darwin etc.. + +The interface type (C or C) 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. =item MTU=1436 The MTU to set the interface to. You can use lower values (if done consistently on all hosts), but this is usually ineffective. -=item MAC=fe:fd:80:00:00:01 +=item NODES=5 -The MAC address to set the interface to. The script *must* set the -interface MAC to this value. You will most likely use one of these: +The number of nodes in this GVPE network. - ip link set $IFNAME address $MAC mtu $MTU up # GNU/Linux - ifconfig $IFNAME ether $MAC mtu $MTU up # FreeBSD +=back -Please see the C manpage for platform-specific information. +Variables that are node-specific and with values pertaining to the node +running this GVPE: -=item IFTYPE=native # or tincd +=over 4 -=item IFSUBTYPE=linux # or freebsd, darwin etc.. +=item IFUPDATA=string + +The value of the configuration directive C. -The interface type (C or C) 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. +=item MAC=fe:fd:80:00:00:01 + +The MAC address the network interface has to use. + +Might be used to initialize interfaces on platforms where GVPE does not +do this automatically. Please see the C manpage for +platform-specific information. =item NODENAME=branch1 -The nickname of the current node, as passed to the gvpe daemon. +The nickname of the node. =item NODEID=1 -The numerical node id of the current node. The first node mentioned in the -config file gets ID 1, the second ID 2 and so on. +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. =back +In addition, all node-specific variables (except C) will be +available with a postfix of C<_nodeid>, which contains the value for that +node, e.g. the C variable contains the MAC address of node #1, while +the C variable contains the name of node #22. + Here is a simple if-up script: #!/bin/sh - ip link set $IFNAME address $MAC mtu $MTU up + ip link set $IFNAME up [ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME [ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME ip route add 10.0.0.0/8 dev $IFNAME @@ -230,8 +302,8 @@ =item node-up = relative-or-absolute-path Sets a command (default: no script) that should be called whenever a -connection is established (even on rekeying operations). In addition -to the variables passed to C scripts, the following environment +connection is established (even on rekeying operations). In addition to +all the variables passed to C scripts, the following environment variables will be set: =over 4 @@ -349,43 +421,61 @@ =item enable-dns = yes|true|on | no|false|off +See gvpe.protocol(7) for a description of the DNS transport +protocol. Avoid this protocol if you can. + Enable the DNS tunneling protocol on this node, either as server or as -client (only available when gvpe was compiled with C<--enable-dns>). +client. Support for this transport protocol is only available when gvpe +was compiled using the C<--enable-dns> option. -B Parsing and generating DNS packets is rather tricky. The code -almost certainly contains buffer overflows and other, likely exploitable, -bugs. You have been warned. - -This is the worst choice of transport protocol with respect to overhead -(overhead can be 2-3 times higher than the transferred data), and probably -the best choice when tunneling through firewalls. +=item enable-icmp = yes|true|on | no|false|off + +See gvpe.protocol(7) for a description of the ICMP transport protocol. + +Enable the ICMP transport using icmp packets of type C on this +node. =item enable-rawip = yes|true|on | no|false|off +See gvpe.protocol(7) for a description of the RAW IP transport protocol. + Enable the RAW IPv4 transport using the C protocol -(default: C). This is the best choice, since the minimum overhead per -packet is only 38 bytes, as opposed to UDP's 58 (or TCP's 60+). +(default: C). =item enable-tcp = yes|true|on | no|false|off +See gvpe.protocol(7) for a description of the TCP transport protocol. + Enable the TCPv4 transport using the C port -(default: C). Support for this horribly unsuitable protocol is only -available when gvpe was compiled using the C<--enable-tcp> option. Never -use this transport unless you really must, it is very inefficient and -resource-intensive compared to the other transports (except for DNS, which -is worse). +(default: C). Support for this transport protocol is only available +when gvpe was compiled using the C<--enable-tcp> option. =item enable-udp = yes|true|on | no|false|off +See gvpe.protocol(7) for a description of the UDP transport protocol. + Enable the UDPv4 transport using the C port (default: C, unless no other protocol is enabled for a node, in which case this -protocol is enabled automatically). This is a good general choice since -UDP tunnels well through many firewalls. +protocol is enabled automatically). NOTE: Please specify C if you want t use it even though it might get switched on automatically, as some future version might default to another default protocol. +=item icmp-type = integer + +Sets the type value to be used for outgoing (and incoming) packets sent +via the ICMP transport. + +The default is C<0> (which is C, also known as +"ping-replies"). Other useful values include C<8> (C, a.k.a. +"ping") and C<11> (C), but any 8-bit value can be used. + +=item if-up-data = value + +The value specified using this directive will be passed to the C +script in the environment variable C. + =item inherit-tos = yes|true|on | no|false|off Wether to inherit the TOS settings of packets sent to the tunnel when @@ -465,5 +555,5 @@ =head1 AUTHOR -Marc Lehmann +Marc Lehmann