--- gvpe/doc/gvpe.conf.5 2005/03/26 03:16:23 1.14 +++ gvpe/doc/gvpe.conf.5 2008/08/10 10:35:26 1.20 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 +.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05) .\" .\" Standard preamble: .\" ======================================================================== @@ -25,11 +25,11 @@ .. .\" 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. | will give a -.\" real vertical bar. \*(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-|\(bv\*(Tr +.\" 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- @@ -48,22 +48,25 @@ . 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 (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. -.if \nF \{\ +.ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na +.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. @@ -129,29 +132,27 @@ .\" ======================================================================== .\" .IX Title "GVPE.CONF 5" -.TH GVPE.CONF 5 "2005-03-26" "1.9" "GNU Virtual Private Ethernet" +.TH GVPE.CONF 5 "2008-08-07" "2.2" "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 3 -\& udp-port = 407 +\& udp\-port = 407 \& mtu = 1492 \& ifname = vpn0 -.Ve -.PP -.Vb 2 +\& \& node = branch1 \& hostname = 1.2.3.4 -.Ve -.PP -.Vb 3 +\& \& node = branch2 \& hostname = www.example.net -\& udp-port = 500 # this host uses a different udp-port -.Ve -.PP -.Vb 2 +\& udp\-port = 500 # this host uses a different udp\-port +\& \& node = branch3 \& connect = ondemand .Ve @@ -247,11 +248,12 @@ 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. +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 ok for most links. +The default should be working ok 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 @@ -373,9 +375,9 @@ Example: .Sp .Vb 3 -\& http-proxy-host = proxy.example.com -\& http-proxy-port = 3128 # 8080 is another common choice -\& http-proxy-auth = schmorp:grumbeere +\& 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" @@ -413,10 +415,13 @@ 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: no script) that should be called whenever a -connection is established (even on rekeying operations). In addition to -all the variables passed to \f(CW\*(C`if\-up\*(C'\fR scripts, the following environment -variables will be set: +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: .RS 4 .IP "DESTNODE=branch2" 4 .IX Item "DESTNODE=branch2" @@ -447,7 +452,7 @@ \& 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. +\& } | nsupdate \-d \-k $CONFBASE:key.example.net. .Ve .RE .IP "node-down = relative-or-absolute-path" 4 @@ -474,10 +479,13 @@ reestablished every \f(CW\*(C`rekey\*(C'\fR seconds. .Sh "\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 +The following settings are node-specific, that is, every node can have different settings, even within the same gvpe instance. Settings that are -executed before the first node section set the defaults, settings that are -executed within a node section only apply to the given node. +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 host (default: \f(CW\*(C`yes\*(C'\fR). @@ -488,9 +496,35 @@ 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 host), \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 on the first packet sent, and -take it down after the keepalive interval) or \f(CW\*(C`disabled\*(C'\fR (node is bad, -don't talk to it). +\&\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). +.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 +conenctions 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 wether a connection may be direct is as follows: +.Sp +1. Other node mentioned in a \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. @@ -499,15 +533,15 @@ i.e. .Sp .Vb 2 -\& dns-domainname = tunnel.example.net -\& dns-hostname = tunnel-server.example.net +\& 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 +\& 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" @@ -555,13 +589,20 @@ \&\s-1NOTE:\s0 Please specify \f(CW\*(C`enable\-udp = yes\*(C'\fR if you want t 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 dns hostname or ip +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. .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\-replies\*(R"). Other useful values include \f(CW8\fR (\f(CW\*(C`echo\-request\*(C'\fR, a.k.a. +\&\*(L"ping-replies\*(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" @@ -581,6 +622,18 @@ 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" 4 +.IX Item "max-queue = positive-number" +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 host (default: \f(CW0\fR, disabled). If @@ -608,19 +661,19 @@ .SH "CONFIG DIRECTORY LAYOUT" .IX Header "CONFIG DIRECTORY LAYOUT" The default (or recommended) directory layout for the config directory is: -.IP "\(bu" 4 +.IP "" 4 .IX Xref "gvpe.conf" The config file. -.IP "\(bu" 4 +.IP "" 4 .IX Xref "if-up" The if-up script .IP "," 4 .IX Xref "node-up node-down" If used the node up or node-down scripts. -.IP "\(bu" 4 +.IP "" 4 .IX Xref "hostkey" The private key (taken from \f(CW\*(C`hostkeys/nodename\*(C'\fR) of the current host. -.IP "\(bu" 4 +.IP "" 4 .IX Xref "pubkey nodename" The public keys of the other nodes, one file per node. .SH "SEE ALSO" @@ -628,4 +681,4 @@ \&\fIgvpe\fR\|(5), \fIgvpe\fR\|(8), \fIgvpectrl\fR\|(8). .SH "AUTHOR" .IX Header "AUTHOR" -Marc Lehmann +Marc Lehmann