--- gvpe/doc/gvpe.conf.5.pod 2008/09/01 05:31:28 1.21 +++ gvpe/doc/gvpe.conf.5.pod 2015/06/25 09:09:29 1.36 @@ -30,19 +30,69 @@ 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 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. -For example, set the MTU to C<1450> everywhere, loglevel to C on -branch1, and connect to C everywhere but on branch2: +=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 ... + +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. + +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 +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 @@ -79,6 +155,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 @@ -239,7 +324,11 @@ The default is 47 (GRE), which has a good chance of tunneling through firewalls (but note that gvpe's rawip protocol is not GRE compatible). Other common choices are 50 (IPSEC, ESP), 51 (IPSEC, AH), 4 -(IPIP tunnels) or 98 (ENCAP, rfc1241) +(IPIP tunnels) or 98 (ENCAP, rfc1241). + +Many versions of Linux seem to have a bug that causes them to reorder +packets for some ip protocols (GRE, ESP) but not for others (AH), so +choose wisely (that is, use 51, AH). =item http-proxy-host = hostname/ip @@ -282,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. @@ -302,11 +391,19 @@ This value must be the minimum of the MTU values of all nodes. -=item node = nickname +=item nfmark = integer + +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: -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 rule add not fwmark 1000 lookup 99 =item node-up = relative-or-absolute-path @@ -316,7 +413,7 @@ will only ever be one such script running. In addition to all the variables passed to C scripts, the following -environment variables will be set: +environment variables will be set (values are just examples): =over 4 @@ -328,6 +425,11 @@ The node id of the remote node. +=item DESTSI=rawip/88.99.77.55:0 + +The "socket info" of the target node, protocol dependent but usually in +the format protocol/ip:port. + =item DESTIP=188.13.66.8 The numerical IP address of the remote node (gvpe accepts connections from @@ -335,12 +437,12 @@ =item DESTPORT=655 # deprecated -The UDP port used by the other side. +The protocol port used by the other side, if applicable. -=item STATE=UP +=item STATE=up -Node-up scripts get called with STATE=UP, node-down scripts get called -with STATE=DOWN. +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. =back @@ -351,9 +453,14 @@ { 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 + +Same as C, but gets called whenever something about a +connection changes (such as the source IP address). + =item node-down = relative-or-absolute-path Same as C, but gets called whenever a connection is lost. @@ -361,7 +468,8 @@ =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 @@ -377,10 +485,45 @@ =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 seed-device = path + +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. + +On program start and every seed-interval, gvpe will read 64 octets. + +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 =head2 NODE SPECIFIC SETTINGS @@ -398,9 +541,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 @@ -501,13 +647,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] @@ -536,11 +676,21 @@ =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. +=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 @@ -609,23 +759,23 @@ =over 4 -=item X +=item gvpe.conf The config file. -=item X +=item if-up The if-up script -=item X, X +=item node-up, node-down If used the node up or node-down scripts. -=item X +=item hostkey -The private key (taken from C) of the current host. +The (default path of the) private key of the current host. -=item X +=item pubkey/nodename The public keys of the other nodes, one file per node.