--- gvpe/doc/gvpe.conf.5.pod 2010/09/10 21:13:52 1.25 +++ gvpe/doc/gvpe.conf.5.pod 2012/12/04 13:23:17 1.30 @@ -30,19 +30,50 @@ 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 -(if the nodename starts with "!") on all nodes except the named one. +All settings are applied "in order", that is, later settings of the same +variable overwrite earlier ones. + +The only exceptions to the above are the "on" and "include" directives: + +=over 4 + +=item on nodename ... + +=item on !nodename ... + +You can prefix any configuration directive with C and a nodename. GVPE +will will only "execute" it on the named node, or (if the nodename starts +with C) on all nodes except the named one. -For example, set the MTU to C<1450> everywhere, loglevel to C on -branch1, and connect to C everywhere but on branch2: +Example: set the MTU to C<1450> everywhere, C to C on +C, and C to C everywhere but on branch2. mtu = 1450 on branch1 loglevel = noise on !branch2 connect = ondemand -All settings are applied "in order", that is, later settings of the same -variable overwrite earlier ones. +=item include relative-or-absolute-path + +Reads the specified file (the path must not contain whitespace or C<=> +characters) and evaluate all config directives in it as if they were +spelled out in place of the C directive. + +The path is a printf format string, that is, you must escape any C<%> +by doubling it, and you can have a single C<%s> inside, which will be +replaced by the current nodename. + +Relative paths are interpreted relative to the GVPE config directory. + +Example: include the file F in the config directory on every +node. + + include local.conf + +Example: include a file FnodenameF<.conf> + + include conf/%s.conf + +=back =head1 ANATOMY OF A CONFIG FILE @@ -69,6 +100,32 @@ =over 4 +=item chroot = path or / + +Tells GVPE to chroot(2) to the specified path after reading all necessary +files, binding to sockets and running the C script, but before +running C or any other scripts. + +The special path F 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 C one. + +=item chuid = numerical-uid + +=item chgid = numerical-gid + +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 +C script. + +Other scripts, such as C, are run with the new user id or group id. + +=item chuser = username + +Alternative to C and C: Sets both C and C +to the user and (primary) group ids of the specified user (for example, +C). + =item dns-forw-host = hostname/ip The DNS server to forward DNS requests to for the DNS tunnel protocol @@ -79,6 +136,15 @@ The port where the C is to be contacted (default: C<53>, which is fine in most cases). +=item dns-case-preserving = yes|true|on | no|false|off + +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). + +Normally, when the forwarding server changes the case of domain names then +GVPE will automatically set this to false. + =item dns-max-outstanding = integer-number-of-requests The maximum number of outstanding DNS transport requests @@ -286,7 +352,7 @@ 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 3 seconds until it receives a reply from the other end. If no reply +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. @@ -360,7 +426,7 @@ { echo update delete $DESTNODE.lowttl.example.net. a echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP - echo + echo } | nsupdate -d -k $CONFBASE:key.example.net. =item node-change = relative-or-absolute-path @@ -426,9 +492,12 @@ =item compress = yes|true|on | no|false|off -Wether to compress data packets sent to this node (default: C). -Compression is really cheap even on slow computers and has no size -overhead at all, so enabling this is often a good idea. +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: C). 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. =item connect = ondemand | never | always | disabled @@ -529,13 +598,7 @@ 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). - -NOTE: Please specify C if you want to use it even though -it might get switched on automatically, as some future version might -default to another default protocol. +Enable the UDPv4 transport using the C port (default: C). =item hostname = hostname | ip [can not be defaulted] @@ -564,7 +627,7 @@ =item inherit-tos = yes|true|on | no|false|off -Wether to inherit the TOS settings of packets sent to the tunnel when +Whether 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.