--- gvpe/doc/gvpe.conf.5.pod 2005/03/01 06:27:20 1.5 +++ gvpe/doc/gvpe.conf.5.pod 2006/08/02 16:58:49 1.16 @@ -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 @@ -62,85 +62,75 @@ =over 4 -=item loglevel = noise|trace|debug|info|notice|warn|error|critical +=item dns-forw-host = hostname/ip -Set the logging level. Connection established messages are logged at level -C, notable errors are logged with C. Default is C. +The dns server to forward dns requests to for the DNS tunnel protocol +(default: C<127.0.0.1>, changing it is highly recommended). -=item node = nickname +=item dns-forw-port = port-number -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. +The port where the C is to be contacted (default: C<53>, +which is fine in most cases). -=item private-key = relative-path-to-key +=item dns-max-outstanding = integer-number-of-requests -Sets the path (relative to the config directory) to the private key -(default: C). This is a printf format string so every C<%> must -be doubled. A single C<%s> is replaced by the hostname, so you could -use paths like C to fetch the files at the location where -C puts them. +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. -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. +The default should be working ok for most links. -=item ifpersist = yes|true|on | no|false|off +=item dns-overlap-factor = float -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 C and do an ifconfig down on the -device. - -=item ifname = devname +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. -Sets the tun interface name to the given name. The default is OS-specific -and most probably something like C. +For congested or picky dns forwarders you could use a value nearer to or +exceeding C<1>. -=item rekey = seconds - -Sets the rekeying interval in seconds (default: C<3600>). Connections are -reestablished every C seconds. - -=item keepalive = seconds - -Sets the keepalive probe interval in seconds (default: C<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. +The default should be working ok for most links. -=item mtu = bytes +=item dns-send-interval = send-interval-in-seconds -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 C script. +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. -Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp). +The default should be working ok for most links. -This value must be the minimum of the mtu values of all hosts. +=item dns-timeout-factor = float -=item ip-proto = numerical-ip-protocol +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. -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. +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 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) +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 @@ -150,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 number of nodes in this GVPE network. -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: +=back - ip link set $IFNAME address $MAC mtu $MTU up # GNU/Linux - ifconfig $IFNAME ether $MAC mtu $MTU up # FreeBSD +Variables that are node-specific and with values pertaining to the node +running this GVPE: -Please see the C manpage for platform-specific information. +=over 4 -=item IFTYPE=native # or tincd +=item IFUPDATA=string -=item IFSUBTYPE=linux # or freebsd, darwin etc.. +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 @@ -197,11 +205,105 @@ More complicated examples (using routing to reduce arp traffic) can be found in the etc/ subdirectory of the distribution. +=item ifname = devname + +Sets the tun interface name to the given name. The default is OS-specific +and most probably something like C. + +=item ifpersist = yes|true|on | no|false|off + +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 C and do an ifconfig down on the +device. + +=item ip-proto = numerical-ip-protocol + +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. + +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) + +=item http-proxy-host = hostname/ip + +The C family of options are only available if gvpe was +compiled with the C<--enable-http-proxy> option and enable tunneling of +tcp connections through a http proxy server. + +C and C should specify the hostname and +port number of the proxy server. See C if your proxy +requires authentication. + +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. + +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). + +If you have a router, connecting to it will suffice. Otherwise tcp must be +enabled on all hosts. + +Example: + + http-proxy-host = proxy.example.com + http-proxy-port = 3128 # 8080 is another common choice + http-proxy-auth = schmorp:grumbeere + +=item http-proxy-port = proxy-tcp-port + +The port where your proxy server listens. + +=item http-proxy-auth = login:password + +The optional login and password used to authenticate to the proxy server, +seperated by a literal colon (C<:>). Only basic authentication is +currently supported. + +=item keepalive = seconds + +Sets the keepalive probe interval in seconds (default: C<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. + +=item loglevel = noise|trace|debug|info|notice|warn|error|critical + +Set the logging level. Connection established messages are logged at level +C, notable errors are logged with C. Default is C. + +=item mtu = bytes + +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 C script. + +Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp). + +This value must be the minimum of the mtu values of all hosts. + +=item node = nickname + +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. + =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 @@ -244,93 +346,192 @@ Same as C, but gets called whenever a connection is lost. -=item http-proxy-host = hostname/ip +=item pid-file = path -The C family of options are only available if gvpe was -compiled with the C<--enable-http-proxy> option and enable tunneling of -tcp connections through a http proxy server. +The path to the pid file to check and create +(default: C). -C and C should specify the hostname and -port number of the proxy server. See C if your proxy -requires authentication. +=item private-key = relative-path-to-key -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. +Sets the path (relative to the config directory) to the private key +(default: C). This is a printf format string so every C<%> must +be doubled. A single C<%s> is replaced by the hostname, so you could +use paths like C to fetch the files at the location where +C puts them. -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). +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. -If you have a router, connecting to it will suffice. Otherwise tcp must be -enabled on all hosts. +=item rekey = seconds -Example: +Sets the rekeying interval in seconds (default: C<3600>). Connections are +reestablished every C seconds. - http-proxy-host = proxy.example.com - http-proxy-port = 3128 # 8080 is another common choice - http-proxy-auth = schmorp:grumbeere +=back -=item http-proxy-port = proxy-tcp-port +=head2 NODE SPECIFIC SETTINGS -The port where your proxy server listens. +The following settings are node-specific, that is, every node can have +different settings, even within the same gvpe instance. Settings that are +set before the first node section set the defaults, settings that are +set within a node section only apply to the given node. -=item http-proxy-auth = login:password +=over 4 -The optional login and password used to authenticate to the proxy server, -seperated by a literal colon (C<:>). Only basic authentication is -currently supported. +=item allow-direct = nodename -=item pid-file = path +Allow direct connections to this node. See C for more info. -The path to the pid file to check and create (Default: +=item compress = yes|true|on | no|false|off -=back +Wether to compress data packets sent to this host (default: C). +Compression is really cheap even on slow computers and has no size +overhead at all, so enabling this is a good idea. -=head2 NODE SPECIFIC SETTINGS +=item connect = ondemand | never | always | disabled -The following settings are node-specific, that is, every node can have -different settings, even within the same gvpe instance. Settings that are -executed before the first node section set the defaults, settings that are -executed within a node section only apply to the given node. +Sets the connect mode (default: C). It can be C (always +try to establish and keep a connection to the given host), C +(never initiate a connection to the given host, but accept connections), +C (try to establish a connection on the first packet sent, and +take it down after the keepalive interval) or C (node is bad, +don't talk to it). -=over 4 +=item deny-direct = nodename | * -=item udp-port = port-number +Deny direct connections to the specified node (or all nodes when C<*> +is given). Only one node can be specified, but you can use multiple +C and C statements. This only makes sense in +networks with routers, as routers are required for indirect connections. -Sets the port number used by the UDP protocol (default: C<655>, not -officially assigned by IANA!). +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 C and C (the other +node I be a router for this to work). -=item tcp-port = port-number +The algorithm to check wether a connection may be direct is as follows: -Similar to C (default: C<655>), but sets the TCP port number. +1. Other node mentioned in a C? If yes, allow the connection. + +2. Other node mentioned in a C? If yes, deny direct connections. + +3. Allow the connection. + +That is, C takes precedence over C. + +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. + +=item dns-domain = domain-suffix + +The DNS domain suffix that points to the DNS tunnel server for this node. + +The domain must point to a NS record that points to the I, +i.e. + + dns-domainname = tunnel.example.net + dns-hostname = tunnel-server.example.net + +Corresponds to the following DNS entries in the C domain: + + tunnel.example.net. NS tunnel-server.example.net. + tunnel-server.example.net. A 13.13.13.13 + +=item dns-hostname = hostname/ip + +The address to bind the DNS tunnel socket to, similar to the C, +but for the DNS tunnel protocol only. Default: C<0.0.0.0>, but that might +change. + +=item dns-port = port-number + +The port to bind the DNS tunnel socket to. Must be C<53> on DNS tunnel servers. + +=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. Support for this transport protocol is only available when gvpe +was compiled using the C<--enable-dns> option. + +=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 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 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 enable-tcp = yes|true|on | no|false|off +=item hostname = hostname | ip [can not be defaulted] -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 horribly ineffiecent and -resource-intensive compared to the other transports. +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. + +=item icmp-type = integer + +Sets the type value to be used for outgoing (and incoming) packets sent +via the ICMP transport. -=item router-priority = 0 | 1 | positive-number>2 +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 +sending packets to this node (default: C). If set to C then +outgoing tunnel packets will have the same TOS setting as the packets sent +to the tunnel device, which is usually what you want. + +=item max-retry = positive-number + +The maximum interval in seconds (default: C<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. C<120>) on +connections to routers that usually are stable but sometimes are down, to +assure quick reconnections even after longer downtimes. + +=item router-priority = 0 | 1 | positive-number>=2 Sets the router priority of the given host (default: C<0>, disabled). If some host tries to connect to another host without a hostname, it asks @@ -348,36 +549,14 @@ C<0>, then routing will be refused, so C<1> serves as a "enable, but do not use by default" switch. -=item connect = ondemand | never | always | disabled - -Sets the connect mode (default: C). It can be C (always -try to establish and keep a connection to the given host), C -(never initiate a connection to the given host, but accept connections), -C (try to establish a connection on the first packet sent, and -take it down after the keepalive interval) or C (node is bad, -don't talk to it). - -=item inherit-tos = yes|true|on | no|false|off - -Wether to inherit the TOS settings of packets sent to the tunnel when -sending packets to this node (default: C). If set to C then -outgoing tunnel packets will have the same TOS setting as the packets sent -to the tunnel device, which is usually what you want. - -=item compress = yes|true|on | no|false|off +=item tcp-port = port-number -Wether to compress data packets sent to this host (default: C). -Compression is really cheap even on slow computers and has no size -overhead at all, so enabling this is a good idea. +Similar to C (default: C<655>), but sets the TCP port number. -=item max-retry = positive-number +=item udp-port = port-number -The maximum interval in seconds (default: C<28800>, 8 hours) 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. C<120>) on -connections to routers that usually are stable but sometimes are down, to -assure quick reconnections. +Sets the port number used by the UDP protocol (default: C<655>, not +officially assigned by IANA!). =back @@ -415,5 +594,5 @@ =head1 AUTHOR -Marc Lehmann +Marc Lehmann