--- gvpe/doc/gvpe.conf.5	2009/07/18 05:59:16	1.25
+++ gvpe/doc/gvpe.conf.5	2013/07/18 13:35:19	1.32
@@ -1,15 +1,7 @@
-.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
 .de Sp \" Vertical space (when we can't use .PP)
 .if t .sp .5v
 .if n .sp
@@ -53,7 +45,7 @@
 .el       .ds Aq '
 .\"
 .\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
 .ie \nF \{\
@@ -132,7 +124,7 @@
 .\" ========================================================================
 .\"
 .IX Title "GVPE.CONF 5"
-.TH GVPE.CONF 5 "2009-06-01" "2.22" "GNU Virtual Private Ethernet"
+.TH GVPE.CONF 5 "2013-07-17" "2.25" "GNU Virtual Private Ethernet"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -168,21 +160,71 @@
 after any directives. Whitespace is allowed around the \f(CW\*(C`=\*(C'\fR sign or after
 values, but not within the variable names or values themselves.
 .PP
-The only exception to the above is the \*(L"on\*(R" directive that can prefix any
-\&\f(CW\*(C`name = value\*(C'\fR setting and will only \*(L"execute\*(R" it on the named node, or
-(if the nodename starts with \*(L"!\*(R") on all nodes except the named one.
-.PP
-For example, set the \s-1MTU\s0 to \f(CW1450\fR everywhere, loglevel to \f(CW\*(C`noise\*(C'\fR on
-branch1, and connect to \f(CW\*(C`ondemand\*(C'\fR everywhere but on branch2:
+All settings are applied \*(L"in order\*(R", that is, later settings of the same
+variable overwrite earlier ones.
 .PP
+The only exceptions to the above are the following directives:
+.IP "node nodename" 4
+.IX Item "node nodename"
+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.
+.Sp
+Multiple \f(CW\*(C`node\*(C'\fR statements with the same node name are supported and will
+be merged together.
+.IP "global" 4
+.IX Item "global"
+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:
+.Sp
+.Vb 2
+\&   global
+\&   include local.conf
+.Ve
+.IP "on nodename ..." 4
+.IX Item "on nodename ..."
+.PD 0
+.IP "on !nodename ..." 4
+.IX Item "on !nodename ..."
+.PD
+You can prefix any configuration directive with \f(CW\*(C`on\*(C'\fR and a nodename. \s-1GVPE\s0
+will will only \*(L"execute\*(R" it on the named node, or (if the nodename starts
+with \f(CW\*(C`!\*(C'\fR) on all nodes except the named one.
+.Sp
+Example: set the \s-1MTU\s0 to \f(CW1450\fR everywhere, \f(CW\*(C`loglevel\*(C'\fR to \f(CW\*(C`noise\*(C'\fR on
+\&\f(CW\*(C`branch1\*(C'\fR, and \f(CW\*(C`connect\*(C'\fR to \f(CW\*(C`ondemand\*(C'\fR everywhere but on branch2.
+.Sp
 .Vb 3
 \&   mtu = 1450
 \&   on branch1 loglevel = noise
 \&   on !branch2 connect = ondemand
 .Ve
-.PP
-All settings are applied \*(L"in order\*(R", that is, later settings of the same
-variable overwrite earlier ones.
+.IP "include relative-or-absolute-path" 4
+.IX Item "include relative-or-absolute-path"
+Reads the specified file (the path must not contain whitespace or \f(CW\*(C`=\*(C'\fR
+characters) and evaluate all config directives in it as if they were
+spelled out in place of the \f(CW\*(C`include\*(C'\fR directive.
+.Sp
+The path is a printf format string, that is, you must escape any \f(CW\*(C`%\*(C'\fR
+by doubling it, and you can have a single \f(CW%s\fR inside, which will be
+replaced by the current nodename.
+.Sp
+Relative paths are interpreted relative to the \s-1GVPE\s0 config directory.
+.Sp
+Example: include the file \fIlocal.conf\fR in the config directory on every
+node.
+.Sp
+.Vb 1
+\&   include local.conf
+.Ve
+.Sp
+Example: include a file \fIconf/\fRnodename\fI.conf\fR
+.Sp
+.Vb 1
+\&   include conf/%s.conf
+.Ve
 .SH "ANATOMY OF A CONFIG FILE"
 .IX Header "ANATOMY OF A CONFIG FILE"
 Usually, a config file starts with a few global settings (like the \s-1UDP\s0
@@ -198,12 +240,37 @@
 node section they will set the default values for all following nodes.
 .SH "CONFIG VARIABLES"
 .IX Header "CONFIG VARIABLES"
-.Sh "\s-1GLOBAL\s0 \s-1SETTINGS\s0"
+.SS "\s-1GLOBAL\s0 \s-1SETTINGS\s0"
 .IX Subsection "GLOBAL SETTINGS"
 Global settings will affect the behaviour of the running gvpe daemon, that
 is, they are in some sense node-specific (config files can set different
 values on different nodes using \f(CW\*(C`on\*(C'\fR), but will affect the behaviour of
 the gvpe daemon and all connections it creates.
+.IP "chroot = path or /" 4
+.IX Item "chroot = path or /"
+Tells \s-1GVPE\s0 to \fIchroot\fR\|(2) to the specified path after reading all necessary
+files, binding to sockets and running the \f(CW\*(C`if\-up\*(C'\fR script, but before
+running \f(CW\*(C`node\-up\*(C'\fR or any other scripts.
+.Sp
+The special path \fI/\fR instructs \s-1GVPE\s0 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 \f(CW\*(C`if\-up\*(C'\fR one.
+.IP "chuid = numerical-uid" 4
+.IX Item "chuid = numerical-uid"
+.PD 0
+.IP "chgid = numerical-gid" 4
+.IX Item "chgid = numerical-gid"
+.PD
+These two options tell \s-1GVPE\s0 to change to the given user and/or group id
+after reading all necessary files, binding to sockets and running the
+\&\f(CW\*(C`if\-up\*(C'\fR script.
+.Sp
+Other scripts, such as \f(CW\*(C`node\-up\*(C'\fR, are run with the new user id or group id.
+.IP "chuser = username" 4
+.IX Item "chuser = username"
+Alternative to \f(CW\*(C`chuid\*(C'\fR and \f(CW\*(C`chgid\*(C'\fR: Sets both \f(CW\*(C`chuid\*(C'\fR and \f(CW\*(C`chgid\*(C'\fR
+to the user and (primary) group ids of the specified user (for example,
+\&\f(CW\*(C`nobody\*(C'\fR).
 .IP "dns-forw-host = hostname/ip" 4
 .IX Item "dns-forw-host = hostname/ip"
 The \s-1DNS\s0 server to forward \s-1DNS\s0 requests to for the \s-1DNS\s0 tunnel protocol
@@ -212,6 +279,14 @@
 .IX Item "dns-forw-port = port-number"
 The port where the \f(CW\*(C`dns\-forw\-host\*(C'\fR is to be contacted (default: \f(CW53\fR,
 which is fine in most cases).
+.IP "dns-case-preserving = yes|true|on | no|false|off" 4
+.IX Item "dns-case-preserving = yes|true|on | no|false|off"
+Sets whether the \s-1DNS\s0 transport forwarding server preserves case (\s-1DNS\s0
+servers have to, but some access systems are even more broken than others)
+(default: true).
+.Sp
+Normally, when the forwarding server changes the case of domain names then
+\&\s-1GVPE\s0 will automatically set this to false.
 .IP "dns-max-outstanding = integer-number-of-requests" 4
 .IX Item "dns-max-outstanding = integer-number-of-requests"
 The maximum number of outstanding \s-1DNS\s0 transport requests
@@ -358,7 +433,11 @@
 The default is 47 (\s-1GRE\s0), which has a good chance of tunneling
 through firewalls (but note that gvpe's rawip protocol is not \s-1GRE\s0
 compatible). Other common choices are 50 (\s-1IPSEC\s0, \s-1ESP\s0), 51 (\s-1IPSEC\s0, \s-1AH\s0), 4
-(\s-1IPIP\s0 tunnels) or 98 (\s-1ENCAP\s0, rfc1241)
+(\s-1IPIP\s0 tunnels) or 98 (\s-1ENCAP\s0, rfc1241).
+.Sp
+Many versions of Linux seem to have a bug that causes them to reorder
+packets for some ip protocols (\s-1GRE\s0, \s-1ESP\s0) but not for others (\s-1AH\s0), so
+choose wisely (that is, use 51, \s-1AH\s0).
 .IP "http-proxy-host = hostname/ip" 4
 .IX Item "http-proxy-host = hostname/ip"
 The \f(CW\*(C`http\-proxy\-*\*(C'\fR family of options are only available if gvpe was
@@ -399,7 +478,7 @@
 .IX Item "keepalive = seconds"
 Sets the keepalive probe interval in seconds (default: \f(CW60\fR). 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.
 .IP "loglevel = noise|trace|debug|info|notice|warn|error|critical" 4
@@ -416,11 +495,21 @@
 Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp).
 .Sp
 This value must be the minimum of the \s-1MTU\s0 values of all nodes.
-.IP "node = nickname" 4
-.IX 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.
+.IP "nfmark = integer" 4
+.IX Item "nfmark = integer"
+This advanced option, when set to a nonzero value (default: \f(CW0\fR), tries
+to set the netfilter mark (or fwmark) value on all sockets gvpe uses to
+send packets.
+.Sp
+This can be used to make gvpe use a different set of routing rules. For
+example, on GNU/Linux, the \f(CW\*(C`if\-up\*(C'\fR could set \f(CW\*(C`nfmark\*(C'\fR to 1000 and then
+put all routing rules into table \f(CW99\fR 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:
+.Sp
+.Vb 1
+\&   ip rule add not fwmark 1000 lookup 99
+.Ve
 .IP "node-up = relative-or-absolute-path" 4
 .IX Item "node-up = relative-or-absolute-path"
 Sets a command (default: none) that should be called whenever a connection
@@ -463,7 +552,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.
 .Ve
 .RE
@@ -477,7 +566,8 @@
 .IP "pid-file = path" 4
 .IX Item "pid-file = path"
 The path to the pid file to check and create
-(default: \f(CW\*(C`LOCALSTATEDIR/run/gvpe.pid\*(C'\fR).
+(default: \f(CW\*(C`LOCALSTATEDIR/run/gvpe.pid\*(C'\fR). The first \f(CW%s\fR is replaced by
+the nodename \- any other use of \f(CW\*(C`%\*(C'\fR must be written as \f(CW\*(C`%%\*(C'\fR.
 .IP "private-key = relative-path-to-key" 4
 .IX Item "private-key = relative-path-to-key"
 Sets the path (relative to the config directory) to the private key
@@ -491,25 +581,25 @@
 not recommended to use this feature.
 .IP "rekey = seconds" 4
 .IX Item "rekey = seconds"
-Sets the rekeying interval in seconds (default: \f(CW3600\fR). Connections are
+Sets the rekeying interval in seconds (default: \f(CW3607\fR). Connections are
 reestablished every \f(CW\*(C`rekey\*(C'\fR seconds, making them use a new encryption
 key.
-.IP "nfmark = integer" 4
-.IX Item "nfmark = integer"
-This advanced option, when set to a nonzero value (default: \f(CW0\fR), tries
-to set the netfilter mark (or fwmark) value on all sockets gvpe uses to
-send packets.
-.Sp
-This can be used to make gvpe use a different set of routing rules. For
-example, on GNU/Linux, the \f(CW\*(C`if\-up\*(C'\fR could set \f(CW\*(C`nfmark\*(C'\fR to 1000 and then
-put all routing rules into table \f(CW99\fR 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:
-.Sp
-.Vb 1
-\&   ip rule add not fwmark 1000 lookup 99
-.Ve
-.Sh "\s-1NODE\s0 \s-1SPECIFIC\s0 \s-1SETTINGS\s0"
+.IP "seed-device = path" 4
+.IX Item "seed-device = path"
+The random device used to initially and regularly seed the random
+number generator (default: \fI/dev/urandom\fR). Randomness is of paramount
+importance to the security of the algorithms used in gvpe.
+.Sp
+On program start and every seed-interval, gvpe will read 64 octets.
+.Sp
+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).
+.IP "seed-interval = seconds" 4
+.IX Item "seed-interval = seconds"
+The number of seconds between reseeds of the random number generator
+(default: \f(CW3613\fR). A value of \f(CW0\fR disables this regular reseeding.
+.SS "\s-1NODE\s0 \s-1SPECIFIC\s0 \s-1SETTINGS\s0"
 .IX Subsection "NODE SPECIFIC SETTINGS"
 The following settings are node-specific, that is, every node can have
 different settings, even within the same gvpe instance. Settings that are
@@ -520,9 +610,12 @@
 Allow direct connections to this node. See \f(CW\*(C`deny\-direct\*(C'\fR for more info.
 .IP "compress = yes|true|on | no|false|off" 4
 .IX Item "compress = yes|true|on | no|false|off"
-Wether to compress data packets sent to this node (default: \f(CW\*(C`yes\*(C'\fR).
-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: \f(CW\*(C`yes\*(C'\fR). 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.
 .IP "connect = ondemand | never | always | disabled" 4
 .IX Item "connect = ondemand | never | always | disabled"
 Sets the connect mode (default: \f(CW\*(C`always\*(C'\fR). It can be \f(CW\*(C`always\*(C'\fR (always
@@ -617,13 +710,7 @@
 .IX Item "enable-udp = yes|true|on | no|false|off"
 See \fIgvpe.protocol\fR\|(7) for a description of the \s-1UDP\s0 transport protocol.
 .Sp
-Enable the UDPv4 transport using the \f(CW\*(C`udp\-port\*(C'\fR port (default: \f(CW\*(C`no\*(C'\fR,
-unless no other protocol is enabled for a node, in which case this
-protocol is enabled automatically).
-.Sp
-\&\s-1NOTE:\s0 Please specify \f(CW\*(C`enable\-udp = yes\*(C'\fR 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 \f(CW\*(C`udp\-port\*(C'\fR port (default: \f(CW\*(C`no\*(C'\fR).
 .IP "hostname = hostname | ip    [can not be defaulted]" 4
 .IX Item "hostname = hostname | ip    [can not be defaulted]"
 Forces the address of this node to be set to the given \s-1DNS\s0 hostname or \s-1IP\s0
@@ -648,7 +735,7 @@
 script in the environment variable \f(CW\*(C`IFUPDATA\*(C'\fR.
 .IP "inherit-tos = yes|true|on | no|false|off" 4
 .IX Item "inherit-tos = yes|true|on | no|false|off"
-Wether to inherit the \s-1TOS\s0 settings of packets sent to the tunnel when
+Whether to inherit the \s-1TOS\s0 settings of packets sent to the tunnel when
 sending packets to this node (default: \f(CW\*(C`yes\*(C'\fR). If set to \f(CW\*(C`yes\*(C'\fR then
 outgoing tunnel packets will have the same \s-1TOS\s0 setting as the packets sent
 to the tunnel device, which is usually what you want.
@@ -720,7 +807,7 @@
 If used the node up or node-down scripts.
 .IP "hostkey" 4
 .IX Item "hostkey"
-The private key (taken from \f(CW\*(C`hostkeys/nodename\*(C'\fR) of the current host.
+The (default path of the) private key of the current host.
 .IP "pubkey/nodename" 4
 .IX Item "pubkey/nodename"
 The public keys of the other nodes, one file per node.