--- gvpe/doc/gvpe.conf.5	2009/03/23 15:21:59	1.24
+++ gvpe/doc/gvpe.conf.5	2012/12/04 10:29:43	1.30
@@ -1,15 +1,7 @@
-.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
+.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
 .\"
 .\" 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-03-23" "2.22" "GNU Virtual Private Ethernet"
+.TH GVPE.CONF 5 "2012-07-06" "2.24" "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,52 @@
 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 \*(L"on\*(R" and \*(L"include\*(R" directives:
+.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,7 +221,7 @@
 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
@@ -212,6 +235,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 +389,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 +434,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
@@ -429,7 +464,7 @@
 will only ever be one such script running.
 .Sp
 In addition to all the variables passed to \f(CW\*(C`if\-up\*(C'\fR scripts, the following
-environment variables will be set:
+environment variables will be set (values are just examples):
 .RS 4
 .IP "DESTNODE=branch2" 4
 .IX Item "DESTNODE=branch2"
@@ -437,17 +472,21 @@
 .IP "DESTID=2" 4
 .IX Item "DESTID=2"
 The node id of the remote node.
+.IP "DESTSI=rawip/88.99.77.55:0" 4
+.IX Item "DESTSI=rawip/88.99.77.55:0"
+The \*(L"socket info\*(R" of the target node, protocol dependent but usually in
+the format protocol/ip:port.
 .IP "DESTIP=188.13.66.8" 4
 .IX Item "DESTIP=188.13.66.8"
 The numerical \s-1IP\s0 address of the remote node (gvpe accepts connections from
 everywhere, as long as the other node can authenticate itself).
 .IP "DESTPORT=655 # deprecated" 4
 .IX Item "DESTPORT=655 # deprecated"
-The \s-1UDP\s0 port used by the other side.
-.IP "STATE=UP" 4
-.IX Item "STATE=UP"
-Node-up scripts get called with STATE=UP, node-down scripts get called
-with STATE=DOWN.
+The protocol port used by the other side, if applicable.
+.IP "STATE=up" 4
+.IX Item "STATE=up"
+Node-up scripts get called with STATE=up, node-change scripts get called
+with STATE=change and node-down scripts get called with STATE=down.
 .RE
 .RS 4
 .Sp
@@ -463,6 +502,10 @@
 \&   } | nsupdate \-d \-k $CONFBASE:key.example.net.
 .Ve
 .RE
+.IP "node-change = relative-or-absolute-path" 4
+.IX Item "node-change = relative-or-absolute-path"
+Same as \f(CW\*(C`node\-change\*(C'\fR, but gets called whenever something about a
+connection changes (such as the source \s-1IP\s0 address).
 .IP "node-down = relative-or-absolute-path" 4
 .IX Item "node-down = relative-or-absolute-path"
 Same as \f(CW\*(C`node\-up\*(C'\fR, but gets called whenever a connection is lost.
@@ -501,7 +544,7 @@
 .Vb 1
 \&   ip rule add not fwmark 1000 lookup 99
 .Ve
-.Sh "\s-1NODE\s0 \s-1SPECIFIC\s0 \s-1SETTINGS\s0"
+.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
@@ -512,9 +555,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
@@ -609,13 +655,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
@@ -640,7 +680,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.