--- gvpe/doc/gvpe.conf.5	2012/12/04 10:29:43	1.30
+++ gvpe/doc/gvpe.conf.5	2013/07/19 21:01:16	1.33
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -124,7 +124,7 @@
 .\" ========================================================================
 .\"
 .IX Title "GVPE.CONF 5"
-.TH GVPE.CONF 5 "2012-07-06" "2.24" "GNU Virtual Private Ethernet"
+.TH GVPE.CONF 5 "2013-07-18" "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
@@ -163,7 +163,26 @@
 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:
+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
@@ -227,6 +246,31 @@
 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
@@ -451,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
@@ -498,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
@@ -512,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
@@ -526,24 +581,41 @@
 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.
+.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.
+.IP "serial = string" 4
+.IX Item "serial = string"
+The configuration serial number. This can be any string up to 16 bytes
+length. Only when the serial matches on both sides of a conenction will
+the connection succeed. This is \fInot\fR a security mechanism and eay to
+spoof, this mechanism exists to alert users that their config is outdated.
+.Sp
+It's recommended to specify this is a date string such as \f(CW\*(C`2013\-05\-05\*(C'\fR or
+\&\f(CW\*(C`20121205084417).\*(C'\fR
 .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:
+The exact algorithm is as this: if a connection request is received form a
+node with an identical serial, then it succeeds normally.
 .Sp
-.Vb 1
-\&   ip rule add not fwmark 1000 lookup 99
-.Ve
+If the remote serial is lower than the local serial, it is ignored.
+.Sp
+If the remote serial is higher than the local serial, a warning message is
+logged.
 .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
@@ -752,7 +824,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.
@@ -762,3 +834,9 @@
 .SH "AUTHOR"
 .IX Header "AUTHOR"
 Marc Lehmann <gvpe@schmorp.de>
+.SH "POD ERRORS"
+.IX Header "POD ERRORS"
+Hey! \fBThe above document had some coding errors, which are explained below:\fR
+.IP "Around line 516:" 4
+.IX Item "Around line 516:"
+Unterminated C<...> sequence