--- gvpe/doc/gvpe.conf.5.pod 2011/03/06 19:40:27 1.28 +++ gvpe/doc/gvpe.conf.5.pod 2016/11/02 06:58:35 1.37 @@ -33,10 +33,29 @@ 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: +The only exceptions to the above are the following directives: =over 4 +=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. + +Multiple C statements with the same node name are supported and will +be merged together. + +=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: + + global + include local.conf + =item on nodename ... =item on !nodename ... @@ -100,6 +119,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 @@ -326,7 +371,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. @@ -346,11 +391,19 @@ This value must be the minimum of the MTU values of all nodes. -=item node = nickname +=item nfmark = integer -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. +This advanced option, when set to a nonzero value (default: C<0>), tries +to set the netfilter mark (or fwmark) value on all sockets gvpe uses to +send packets. + +This can be used to make gvpe use a different set of routing rules. For +example, on GNU/Linux, the C could set C to 1000 and then +put all routing rules into table C<99> 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: + + ip rule add not fwmark 1000 lookup 99 =item node-up = relative-or-absolute-path @@ -400,7 +453,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 @@ -415,39 +468,61 @@ =item pid-file = path The path to the pid file to check and create -(default: C). +(default: C). The first C<%s> is replaced by +the nodename - any other use of C<%> must be written as C<%%>. =item private-key = relative-path-to-key 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. +be doubled. A single C<%s> is replaced by the hostname, so you could use +paths like C to be able to share the same config directory +between nodes. Since only the private key file of the current node is used and the private key file should be kept secret per-node to avoid spoofing, it is -not recommended to use this feature. +not recommended to use this feature this way though. =item rekey = seconds -Sets the rekeying interval in seconds (default: C<3600>). Connections are +Sets the rekeying interval in seconds (default: C<3607>). Connections are reestablished every C seconds, making them use a new encryption key. -=item nfmark = integer +=item seed-device = path -This advanced option, when set to a nonzero value (default: C<0>), tries -to set the netfilter mark (or fwmark) value on all sockets gvpe uses to -send packets. +The random device used to initially and regularly seed the random +number generator (default: F). Randomness is of paramount +importance to the security of the algorithms used in gvpe. -This can be used to make gvpe use a different set of routing rules. For -example, on GNU/Linux, the C could set C to 1000 and then -put all routing rules into table C<99> 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: +On program start and every seed-interval, gvpe will read 64 octets. - ip rule add not fwmark 1000 lookup 99 +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). + +=item seed-interval = seconds + +The number of seconds between reseeds of the random number generator +(default: C<3613>). A value of C<0> disables this regular reseeding. + +=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 I a security mechanism and eay to +spoof, this mechanism exists to alert users that their config is outdated. + +It's recommended to specify this is a date string such as C<2013-05-05> or +C<20121205084417>. + +The exact algorithm is as this: if a connection request is received form a +node with an identical serial, then it succeeds normally. + +If the remote serial is lower than the local serial, it is ignored. + +If the remote serial is higher than the local serial, a warning message is +logged. =back @@ -606,6 +681,16 @@ outgoing tunnel packets will have the same TOS setting as the packets sent to the tunnel device, which is usually what you want. +=item low-power = yes|true|on | no|false|off + +If true, designates a node as a low-power node. Low-power nodes use +larger timeouts and try to reduce cpu time. Other nodes talking to a +low-power node will also use larger timeouts, and will use less aggressive +optimisations, in the hope of reducing load. Security is not compromised. + +The typical low-power node would be a mobile phone, where wakeups and +encryption can significantly increase power drain. + =item max-retry = positive-number The maximum interval in seconds (default: C<3600>, one hour) between @@ -688,7 +773,7 @@ =item hostkey -The private key (taken from C) of the current host. +The (default path of the) private key of the current host. =item pubkey/nodename