--- gvpe/doc/gvpe.conf.5 2010/12/02 07:15:14 1.26 +++ gvpe/doc/gvpe.conf.5 2012/12/04 13:23:17 1.31 @@ -1,728 +0,0 @@ -.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. \*(C+ will -.\" give a nicer C++. Capital omega is used to do unbreakable dashes and -.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, -.\" nothing in troff, for use with C<>. -.tr \(*W- -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` -. ds C' -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" Escape single quotes in literal strings from groff's Unicode transform. -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" 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 \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.el \{\ -. de IX -.. -.\} -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "GVPE.CONF 5" -.TH GVPE.CONF 5 "2010-09-10" "2.22" "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 -.nh -.SH "NAME" -gvpe.conf \- configuration file for the GNU VPE daemon -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 4 -\& # global options for all nodes -\& udp\-port = 407 -\& mtu = 1492 -\& ifname = vpn0 -\& -\& # first node is named branch1 and is at 1.2.3.4 -\& node = branch1 -\& hostname = 1.2.3.4 -\& -\& # second node uses dns to resolve the address -\& node = branch2 -\& hostname = www.example.net -\& udp\-port = 500 # this host uses a different udp\-port -\& -\& # third node has no fixed ip address -\& node = branch3 -\& connect = ondemand -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The gvpe config file consists of a series of lines that contain \f(CW\*(C`variable -= value\*(C'\fR pairs. Empty lines are ignored. Comments start with a \f(CW\*(C`#\*(C'\fR and -extend to the end of the line. They can be used on their own lines, or -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: -.PP -.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. -.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 -port to listen on), followed by node-specific sections that begin with a -\&\f(CW\*(C`node = nickname\*(C'\fR line. -.PP -Every node that is part of the network must have a section that starts -with \f(CW\*(C`node = nickname\*(C'\fR. The number and order of the nodes is important -and must be the same on all nodes. It is not uncommon for node sections to -be completely empty \- if the default values are right. -.PP -Node-specific settings can be used at any time. If used before the first -node section they will set the default values for all following nodes. -.SH "CONFIG VARIABLES" -.IX Header "CONFIG VARIABLES" -.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 "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 -(default: \f(CW127.0.0.1\fR, changing it is highly recommended). -.IP "dns-forw-port = port-number" 4 -.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-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 -(default: \f(CW100\fR). \s-1GVPE\s0 will never issue more requests then the given -limit without receiving replies. In heavily overloaded situations it might -help to set this to a low number (e.g. \f(CW3\fR or even \f(CW1\fR) to limit the -number of parallel requests. -.Sp -The default should be working \s-1OK\s0 for most links. -.IP "dns-overlap-factor = float" 4 -.IX Item "dns-overlap-factor = float" -The \s-1DNS\s0 transport uses the minimum request latency (\fBmin_latency\fR) seen -during a connection as it's timing base. This factor (default: \f(CW0.5\fR, -must be > 0) is multiplied by \fBmin_latency\fR to get the maximum sending -rate (= minimum send interval), i.e. a factor of \f(CW1\fR means that a new -request might be generated every \fBmin_latency\fR seconds, which means on -average there should only ever be one outstanding request. A factor of -\&\f(CW0.5\fR means that \s-1GVPE\s0 will send requests twice as often as the minimum -latency measured. -.Sp -For congested or picky \s-1DNS\s0 forwarders you could use a value nearer to or -exceeding \f(CW1\fR. -.Sp -The default should be working \s-1OK\s0 for most links. -.IP "dns-send-interval = send-interval-in-seconds" 4 -.IX Item "dns-send-interval = send-interval-in-seconds" -The minimum send interval (= maximum rate) that the \s-1DNS\s0 transport will -use to send new \s-1DNS\s0 requests. \s-1GVPE\s0 will not exceed this rate even when -the latency is very low. The default is \f(CW0.01\fR, which means \s-1GVPE\s0 will -not send more than 100 \s-1DNS\s0 requests per connection per second. For -high-bandwidth links you could go lower, e.g. to \f(CW0.001\fR or so. For -congested or rate-limited links, you might want to go higher, say \f(CW0.1\fR, -\&\f(CW0.2\fR or even higher. -.Sp -The default should be working \s-1OK\s0 for most links. -.IP "dns-timeout-factor = float" 4 -.IX Item "dns-timeout-factor = float" -Factor to multiply the \f(CW\*(C`min_latency\*(C'\fR (see \f(CW\*(C`dns\-overlap\-factor\*(C'\fR) by to -get request timeouts. The default of \f(CW8\fR means that the \s-1DNS\s0 transport -will resend the request when no reply has been received for longer than -eight times the minimum (= expected) latency, assuming the request or -reply has been lost. -.Sp -For congested links a higher value might be necessary (e.g. \f(CW30\fR). If -the link is very stable lower values (e.g. \f(CW2\fR) might work -nicely. Values near or below \f(CW1\fR makes no sense whatsoever. -.Sp -The default should be working \s-1OK\s0 for most links but will result in low -throughput if packet loss is high. -.IP "if-up = relative-or-absolute-path" 4 -.IX Item "if-up = relative-or-absolute-path" -Sets the path of a script that should be called immediately after the -network interface is initialized (but not necessarily up). The following -environment variables are passed to it (the values are just examples). -.Sp -Variables that have the same value on all nodes: -.RS 4 -.IP "CONFBASE=/etc/gvpe" 4 -.IX Item "CONFBASE=/etc/gvpe" -The configuration base directory. -.IP "IFNAME=vpn0" 4 -.IX Item "IFNAME=vpn0" -The network interface to initialize. -.IP "IFTYPE=native # or tincd" 4 -.IX Item "IFTYPE=native # or tincd" -.PD 0 -.IP "IFSUBTYPE=linux # or freebsd, darwin etc.." 4 -.IX Item "IFSUBTYPE=linux # or freebsd, darwin etc.." -.PD -The interface type (\f(CW\*(C`native\*(C'\fR or \f(CW\*(C`tincd\*(C'\fR) and the subtype (usually the -\&\s-1OS\s0 name in lowercase) that this \s-1GVPE\s0 was configured for. Can be used to -select the correct syntax to use for network-related commands. -.IP "MTU=1436" 4 -.IX Item "MTU=1436" -The \s-1MTU\s0 to set the interface to. You can use lower values (if done -consistently on all nodes), but this is usually either inefficient or -simply ineffective. -.IP "NODES=5" 4 -.IX Item "NODES=5" -The number of nodes in this \s-1GVPE\s0 network. -.RE -.RS 4 -.Sp -Variables that are node-specific and with values pertaining to the node -running this \s-1GVPE:\s0 -.IP "IFUPDATA=string" 4 -.IX Item "IFUPDATA=string" -The value of the configuration directive \f(CW\*(C`if\-up\-data\*(C'\fR. -.IP "MAC=fe:fd:80:00:00:01" 4 -.IX Item "MAC=fe:fd:80:00:00:01" -The \s-1MAC\s0 address the network interface has to use. -.Sp -Might be used to initialize interfaces on platforms where \s-1GVPE\s0 does not -do this automatically. Please see the \f(CW\*(C`gvpe.osdep(5)\*(C'\fR man page for -platform-specific information. -.IP "NODENAME=branch1" 4 -.IX Item "NODENAME=branch1" -The nickname of the node. -.IP "NODEID=1" 4 -.IX Item "NODEID=1" -The numerical node \s-1ID\s0 of the node running this instance of \s-1GVPE\s0. The first -node mentioned in the config file gets \s-1ID\s0 1, the second \s-1ID\s0 2 and so on. -.RE -.RS 4 -.Sp -In addition, all node-specific variables (except \f(CW\*(C`NODEID\*(C'\fR) will be -available with a postfix of \f(CW\*(C`_nodeid\*(C'\fR, which contains the value for that -node, e.g. the \f(CW\*(C`MAC_1\*(C'\fR variable contains the \s-1MAC\s0 address of node #1, while -the \f(CW\*(C`NODENAME_22\*(C'\fR variable contains the name of node #22. -.Sp -Here is a simple if-up script: -.Sp -.Vb 5 -\& #!/bin/sh -\& ip link set $IFNAME up -\& [ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME -\& [ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME -\& ip route add 10.0.0.0/8 dev $IFNAME -.Ve -.Sp -More complicated examples (using routing to reduce \s-1ARP\s0 traffic) can be -found in the \fIetc/\fR subdirectory of the distribution. -.RE -.IP "ifname = devname" 4 -.IX Item "ifname = devname" -Sets the tun interface name to the given name. The default is OS-specific -and most probably something like \f(CW\*(C`tun0\*(C'\fR. -.IP "ifpersist = yes|true|on | no|false|off" 4 -.IX Item "ifpersist = yes|true|on | no|false|off" -Should the tun/tap device be made persistent, that is, should the device -stay up even when gvpe exits? Some versions of the tunnel device have -problems sending packets when gvpe is restarted in persistent mode, so -if the connections can be established but you cannot send packets from -the local node, try to set this to \f(CW\*(C`off\*(C'\fR and do an ifconfig down on the -device. -.IP "ip-proto = numerical-ip-protocol" 4 -.IX Item "ip-proto = numerical-ip-protocol" -Sets the protocol number to be used for the rawip protocol. This is a -global option because all nodes must use the same protocol, and since -there are no port numbers, you cannot easily run more than one gvpe -instance using the same protocol, nor can you share the protocol with -other programs. -.Sp -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). -.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 -compiled with the \f(CW\*(C`\-\-enable\-http\-proxy\*(C'\fR option and enable tunneling of -tcp connections through a http proxy server. -.Sp -\&\f(CW\*(C`http\-proxy\-host\*(C'\fR and \f(CW\*(C`http\-proxy\-port\*(C'\fR should specify the hostname and -port number of the proxy server. See \f(CW\*(C`http\-proxy\-loginpw\*(C'\fR if your proxy -requires authentication. -.Sp -Please note that gvpe will still try to resolve all hostnames in the -configuration file, so if you are behind a proxy without access to a \s-1DNS\s0 -server better use numerical \s-1IP\s0 addresses. -.Sp -To make best use of this option disable all protocols except \s-1TCP\s0 in your -config file and make sure your routers (or all other nodes) are listening -on a port that the proxy allows (443, https, is a common choice). -.Sp -If you have a router, connecting to it will suffice. Otherwise \s-1TCP\s0 must be -enabled on all nodes. -.Sp -Example: -.Sp -.Vb 3 -\& http\-proxy\-host = proxy.example.com -\& http\-proxy\-port = 3128 # 8080 is another common choice -\& http\-proxy\-auth = schmorp:grumbeere -.Ve -.IP "http-proxy-port = proxy-tcp-port" 4 -.IX Item "http-proxy-port = proxy-tcp-port" -The port where your proxy server listens. -.IP "http-proxy-auth = login:password" 4 -.IX Item "http-proxy-auth = login:password" -The optional login and password used to authenticate to the proxy server, -separated by a literal colon (\f(CW\*(C`:\*(C'\fR). Only basic authentication is -currently supported. -.IP "keepalive = seconds" 4 -.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 -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 -.IX Item "loglevel = noise|trace|debug|info|notice|warn|error|critical" -Set the logging level. Connection established messages are logged at level -\&\f(CW\*(C`info\*(C'\fR, notable errors are logged with \f(CW\*(C`error\*(C'\fR. Default is \f(CW\*(C`info\*(C'\fR. -.IP "mtu = bytes" 4 -.IX Item "mtu = bytes" -Sets the maximum \s-1MTU\s0 that should be used on outgoing packets (basically -the \s-1MTU\s0 of the outgoing interface) The daemon will automatically calculate -maximum overhead (e.g. \s-1UDP\s0 header size, encryption blocksize...) and pass -this information to the \f(CW\*(C`if\-up\*(C'\fR script. -.Sp -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 "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 -is established (even on rekeying operations). Note that node\-up/down -scripts will be run asynchronously, but execution is serialised, so there -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 (values are just examples): -.RS 4 -.IP "DESTNODE=branch2" 4 -.IX Item "DESTNODE=branch2" -The name of the remote node. -.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 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 -Here is a nontrivial example that uses nsupdate to update the name => ip -mapping in some \s-1DNS\s0 zone: -.Sp -.Vb 6 -\& #!/bin/sh -\& { -\& echo update delete $DESTNODE.lowttl.example.net. a -\& echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP -\& echo -\& } | 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. -.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). -.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 -(default: \f(CW\*(C`hostkey\*(C'\fR). This is a printf format string so every \f(CW\*(C`%\*(C'\fR must -be doubled. A single \f(CW%s\fR is replaced by the hostname, so you could -use paths like \f(CW\*(C`hostkeys/%s\*(C'\fR to fetch the files at the location where -\&\f(CW\*(C`gvpectrl\*(C'\fR puts them. -.Sp -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. -.IP "rekey = seconds" 4 -.IX Item "rekey = seconds" -Sets the rekeying interval in seconds (default: \f(CW3600\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 -.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 -set before the first node section set the defaults, settings that are -set within a node section only apply to the given node. -.IP "allow-direct = nodename" 4 -.IX Item "allow-direct = nodename" -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. -.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 -try to establish and keep a connection to the given node), \f(CW\*(C`never\*(C'\fR -(never initiate a connection to the given host, but accept connections), -\&\f(CW\*(C`ondemand\*(C'\fR (try to establish a connection when there are outstanding -packets in the queue and take it down after the keepalive interval) or -\&\f(CW\*(C`disabled\*(C'\fR (node is bad, don't talk to it). -.Sp -Routers will automatically be forced to \f(CW\*(C`always\*(C'\fR unless they are -\&\f(CW\*(C`disabled\*(C'\fR, to ensure all nodes can talk to each other. -.IP "deny-direct = nodename | *" 4 -.IX Item "deny-direct = nodename | *" -Deny direct connections to the specified node (or all nodes when \f(CW\*(C`*\*(C'\fR -is given). Only one node can be specified, but you can use multiple -\&\f(CW\*(C`allow\-direct\*(C'\fR and \f(CW\*(C`deny\-direct\*(C'\fR statements. This only makes sense in -networks with routers, as routers are required for indirect connections. -.Sp -Sometimes, a node cannot reach some other nodes for reasons of network -connectivity. For example, a node behind a firewall that only allows -connections to/from a single other node in the network. In this case one -should specify \f(CW\*(C`deny\-direct = *\*(C'\fR and \f(CW\*(C`allow\-direct = othernodename\*(C'\fR (the other -node \fImust\fR be a router for this to work). -.Sp -The algorithm to check whether a connection may be direct is as follows: -.Sp -1. Other node mentioned in an \f(CW\*(C`allow\-direct\*(C'\fR? If yes, allow the connection. -.Sp -2. Other node mentioned in a \f(CW\*(C`deny\-direct\*(C'\fR? If yes, deny direct connections. -.Sp -3. Allow the connection. -.Sp -That is, \f(CW\*(C`allow\-direct\*(C'\fR takes precedence over \f(CW\*(C`deny\-direct\*(C'\fR. -.Sp -The check is done in both directions, i.e. both nodes must allow a direct -connection before one is attempted, so you only need to specify connect -limitations on one node. -.IP "dns-domain = domain-suffix" 4 -.IX Item "dns-domain = domain-suffix" -The \s-1DNS\s0 domain suffix that points to the \s-1DNS\s0 tunnel server for this node. -.Sp -The domain must point to a \s-1NS\s0 record that points to the \fIdns-hostname\fR, -i.e. -.Sp -.Vb 2 -\& dns\-domainname = tunnel.example.net -\& dns\-hostname = tunnel\-server.example.net -.Ve -.Sp -Corresponds to the following \s-1DNS\s0 entries in the \f(CW\*(C`example.net\*(C'\fR domain: -.Sp -.Vb 2 -\& tunnel.example.net. NS tunnel\-server.example.net. -\& tunnel\-server.example.net. A 13.13.13.13 -.Ve -.IP "dns-hostname = hostname/ip" 4 -.IX Item "dns-hostname = hostname/ip" -The address to bind the \s-1DNS\s0 tunnel socket to, similar to the \f(CW\*(C`hostname\*(C'\fR, -but for the \s-1DNS\s0 tunnel protocol only. Default: \f(CW0.0.0.0\fR, but that might -change. -.IP "dns-port = port-number" 4 -.IX Item "dns-port = port-number" -The port to bind the \s-1DNS\s0 tunnel socket to. Must be \f(CW53\fR on \s-1DNS\s0 tunnel servers. -.IP "enable-dns = yes|true|on | no|false|off" 4 -.IX Item "enable-dns = yes|true|on | no|false|off" -See \fIgvpe.protocol\fR\|(7) for a description of the \s-1DNS\s0 transport -protocol. Avoid this protocol if you can. -.Sp -Enable the \s-1DNS\s0 tunneling protocol on this node, either as server or as -client. Support for this transport protocol is only available when gvpe -was compiled using the \f(CW\*(C`\-\-enable\-dns\*(C'\fR option. -.IP "enable-icmp = yes|true|on | no|false|off" 4 -.IX Item "enable-icmp = yes|true|on | no|false|off" -See \fIgvpe.protocol\fR\|(7) for a description of the \s-1ICMP\s0 transport protocol. -.Sp -Enable the \s-1ICMP\s0 transport using \s-1ICMP\s0 packets of type \f(CW\*(C`icmp\-type\*(C'\fR on this -node. -.IP "enable-rawip = yes|true|on | no|false|off" 4 -.IX Item "enable-rawip = yes|true|on | no|false|off" -See \fIgvpe.protocol\fR\|(7) for a description of the \s-1RAW\s0 \s-1IP\s0 transport protocol. -.Sp -Enable the \s-1RAW\s0 IPv4 transport using the \f(CW\*(C`ip\-proto\*(C'\fR protocol -(default: \f(CW\*(C`no\*(C'\fR). -.IP "enable-tcp = yes|true|on | no|false|off" 4 -.IX Item "enable-tcp = yes|true|on | no|false|off" -See \fIgvpe.protocol\fR\|(7) for a description of the \s-1TCP\s0 transport protocol. -.Sp -Enable the TCPv4 transport using the \f(CW\*(C`tcp\-port\*(C'\fR port -(default: \f(CW\*(C`no\*(C'\fR). Support for this transport protocol is only available -when gvpe was compiled using the \f(CW\*(C`\-\-enable\-tcp\*(C'\fR option. -.IP "enable-udp = yes|true|on | no|false|off" 4 -.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. -.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 -address. It will be resolved before each connect request, so dyndns should -work fine. If this setting is not specified and a router is available, -then the router will be queried for the address of this node. Otherwise, -the connection attempt will fail. -.Sp -Note that \s-1DNS\s0 resolving is done synchronously, pausing the daemon. If that -is an issue you need to specify \s-1IP\s0 addresses. -.IP "icmp-type = integer" 4 -.IX Item "icmp-type = integer" -Sets the type value to be used for outgoing (and incoming) packets sent -via the \s-1ICMP\s0 transport. -.Sp -The default is \f(CW0\fR (which is \f(CW\*(C`echo\-reply\*(C'\fR, also known as -\&\*(L"ping-reply\*(R"). Other useful values include \f(CW8\fR (\f(CW\*(C`echo\-request\*(C'\fR, a.k.a. -\&\*(L"ping\*(R") and \f(CW11\fR (\f(CW\*(C`time\-exceeded\*(C'\fR), but any 8\-bit value can be used. -.IP "if-up-data = value" 4 -.IX Item "if-up-data = value" -The value specified using this directive will be passed to the \f(CW\*(C`if\-up\*(C'\fR -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 -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. -.IP "max-retry = positive-number" 4 -.IX Item "max-retry = positive-number" -The maximum interval in seconds (default: \f(CW3600\fR, one hour) between -retries to establish a connection to this node. When a connection cannot -be established, gvpe uses exponential back-off capped at this value. It's -sometimes useful to set this to a much lower value (e.g. \f(CW120\fR) on -connections to routers that usually are stable but sometimes are down, to -assure quick reconnections even after longer downtimes. -.IP "max-ttl = seconds" 4 -.IX Item "max-ttl = seconds" -Expire packets that couldn't be sent after this many seconds -(default: \f(CW60\fR). Gvpe will normally queue packets for a node without an -active connection, in the hope of establishing a connection soon. This -value specifies the maximum lifetime a packet will stay in the queue, if a -packet gets older, it will be thrown away. -.IP "max-queue = positive\-number>=1" 4 -.IX Item "max-queue = positive-number>=1" -The maximum number of packets that will be queued (default: \f(CW512\fR) -for this node. If more packets are sent then earlier packets will be -expired. See \f(CW\*(C`max\-ttl\*(C'\fR, above. -.IP "router-priority = 0 | 1 | positive\-number>=2" 4 -.IX Item "router-priority = 0 | 1 | positive-number>=2" -Sets the router priority of the given node (default: \f(CW0\fR, disabled). -.Sp -If some node tries to connect to another node but it doesn't have a -hostname, it asks a router node for it's \s-1IP\s0 address. The router node -chosen is the one with the highest priority larger than \f(CW1\fR that is -currently reachable. This is called a \fImediated\fR connection, as the -connection itself will still be direct, but it uses another node to -mediate between the two nodes. -.Sp -The value \f(CW0\fR disables routing, that means if the node receives a packet -not for itself it will not forward it but instead drop it. -.Sp -The special value \f(CW1\fR allows other hosts to route through the router -host, but they will never route through it by default (i.e. the config -file of another node needs to specify a router priority higher than one -to choose such a node for routing). -.Sp -The idea behind this is that some hosts can, if required, bump the -\&\f(CW\*(C`router\-priority\*(C'\fR setting to higher than \f(CW1\fR in their local config to -route through specific hosts. If \f(CW\*(C`router\-priority\*(C'\fR is \f(CW0\fR, then routing -will be refused, so \f(CW1\fR serves as a \*(L"enable, but do not use by default\*(R" -switch. -.Sp -Nodes with \f(CW\*(C`router\-priority\*(C'\fR set to \f(CW2\fR or higher will always be forced -to \f(CW\*(C`connect\*(C'\fR = \f(CW\*(C`always\*(C'\fR (unless they are \f(CW\*(C`disabled\*(C'\fR). -.IP "tcp-port = port-number" 4 -.IX Item "tcp-port = port-number" -Similar to \f(CW\*(C`udp\-port\*(C'\fR (default: \f(CW655\fR), but sets the \s-1TCP\s0 port number. -.IP "udp-port = port-number" 4 -.IX Item "udp-port = port-number" -Sets the port number used by the \s-1UDP\s0 protocol (default: \f(CW655\fR, not -officially assigned by \s-1IANA\s0!). -.SH "CONFIG DIRECTORY LAYOUT" -.IX Header "CONFIG DIRECTORY LAYOUT" -The default (or recommended) directory layout for the config directory is: -.IP "gvpe.conf" 4 -.IX Item "gvpe.conf" -The config file. -.IP "if-up" 4 -.IX Item "if-up" -The if-up script -.IP "node-up, node-down" 4 -.IX Item "node-up, node-down" -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. -.IP "pubkey/nodename" 4 -.IX Item "pubkey/nodename" -The public keys of the other nodes, one file per node. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -\&\fIgvpe\fR\|(5), \fIgvpe\fR\|(8), \fIgvpectrl\fR\|(8). -.SH "AUTHOR" -.IX Header "AUTHOR" -Marc Lehmann