--- gvpe/doc/gvpe.conf.5.pod 2004/12/04 18:38:28 1.3 +++ gvpe/doc/gvpe.conf.5.pod 2005/03/06 18:34:46 1.6 @@ -4,7 +4,6 @@ =head1 SYNOPSIS - enable-udp = yes udp-port = 407 mtu = 1492 ifname = vpn0 @@ -63,79 +62,15 @@ =over 4 -=item loglevel = noise|trace|debug|info|notice|warn|error|critical - -Set the logging level. Connection established messages are logged at level -C, notable errors are logged with C. Default is C. - -=item node = nickname +=item dns-forw-host = hostname/ip -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. +The dns server to forward dns requests to for the DNS tunnel protocol +(default: C<127.0.0.1>, changing it is highly recommended). -=item private-key = relative-path-to-key +=item dns-forw-port = port-number -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. - -Since only the private key file of the current node is used and the -private key file should be kept secret per-host to avoid spoofings, it is -not recommended to use this feature. - -=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 C and do an ifconfig down on the -device. - -=item ifname = devname - -Sets the tun interface name to the given name. The default is OS-specific -and most probably something like C. - -=item rekey = seconds - -Sets the rekeying interval in seconds (default: C<3600>). Connections are -reestablished every C seconds. - -=item keepalive = seconds - -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 5 seconds until it receives a reply from the other end. If no reply -is received within 30 seconds, the peer is considered unreachable and the -connection is closed. - -=item mtu = bytes - -Sets the maximum MTU that should be used on outgoing packets (basically -the MTU of the outgoing interface) The daemon will automatically calculate -maximum overhead (e.g. udp header size, encryption blocksize...) and pass -this information to the C script. - -Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp). - -This value must be the minimum of the mtu values of all hosts. - -=item ip-proto = numerical-ip-protocol - -Sets the protocol number to be used for the rawip protocol. This is a -global option because all hosts 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. - -The default is 47 (GRE), which has a good chance of tunneling through -firewalls (but note that the rawip protocol is not GRE compatible). Other -common choices are 50 (IPSEC, ESP), 51 (IPSEC, AH), 4 (IPIP tunnels) or 98 -(ENCAP, rfc1241) +The port where the C is to be contacted (default: C<53>, +which is fine in most cases). =item if-up = relative-or-absolute-path @@ -198,6 +133,100 @@ More complicated examples (using routing to reduce arp traffic) can be found in the etc/ subdirectory of the distribution. +=item ifname = devname + +Sets the tun interface name to the given name. The default is OS-specific +and most probably something like C. + +=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 C and do an ifconfig down on the +device. + +=item ip-proto = numerical-ip-protocol + +Sets the protocol number to be used for the rawip protocol. This is a +global option because all hosts 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. + +The default is 47 (GRE), which has a good chance of tunneling through +firewalls (but note that the rawip protocol is not GRE compatible). Other +common choices are 50 (IPSEC, ESP), 51 (IPSEC, AH), 4 (IPIP tunnels) or 98 +(ENCAP, rfc1241) + +=item http-proxy-host = hostname/ip + +The C family of options are only available if gvpe was +compiled with the C<--enable-http-proxy> option and enable tunneling of +tcp connections through a http proxy server. + +C and C should specify the hostname and +port number of the proxy server. See C if your proxy +requires authentication. + +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 dns +server better use numerical IP addresses. + +To make best use of this option disable all protocols except tcp in your +config file and make sure your routers (or all other hosts) are listening +on a port that the proxy allows (443, https, is a common choice). + +If you have a router, connecting to it will suffice. Otherwise tcp must be +enabled on all hosts. + +Example: + + http-proxy-host = proxy.example.com + http-proxy-port = 3128 # 8080 is another common choice + http-proxy-auth = schmorp:grumbeere + +=item http-proxy-port = proxy-tcp-port + +The port where your proxy server listens. + +=item http-proxy-auth = login:password + +The optional login and password used to authenticate to the proxy server, +seperated by a literal colon (C<:>). Only basic authentication is +currently supported. + +=item keepalive = seconds + +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 5 seconds until it receives a reply from the other end. If no reply +is received within 30 seconds, the peer is considered unreachable and the +connection is closed. + +=item loglevel = noise|trace|debug|info|notice|warn|error|critical + +Set the logging level. Connection established messages are logged at level +C, notable errors are logged with C. Default is C. + +=item mtu = bytes + +Sets the maximum MTU that should be used on outgoing packets (basically +the MTU of the outgoing interface) The daemon will automatically calculate +maximum overhead (e.g. udp header size, encryption blocksize...) and pass +this information to the C script. + +Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp). + +This value must be the minimum of the mtu values of all hosts. + +=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. + =item node-up = relative-or-absolute-path Sets a command (default: no script) that should be called whenever a @@ -245,46 +274,27 @@ Same as C, but gets called whenever a connection is lost. -=item http-proxy-host = hostname/ip - -The C family of options are only available if gvpe was -compiled with the C<--enable-http-proxy> option and enable tunneling of -tcp connections through a http proxy server. - -C and C should specify the hostname and -port number of the proxy server. See C if your proxy -requires authentication. - -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 dns -server better use numerical IP addresses. - -To make best use of this option disable all protocols except tcp in your -config file and make sure your routers (or all other hosts) are listening -on a port that the proxy allows (443, https, is a common choice). - -If you have a router, connecting to it will suffice. Otherwise tcp must be -enabled on all hosts. - -Example: - - http-proxy-host = proxy.example.com - http-proxy-port = 3128 # 8080 is another common choice - http-proxy-auth = schmorp:grumbeere +=item pid-file = path -=item http-proxy-port = proxy-tcp-port +The path to the pid file to check and create +(default: C). -The port where your proxy server listens. +=item private-key = relative-path-to-key -=item http-proxy-auth = login:password +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. -The optional login and password used to authenticate to the proxy server, -seperated by a literal colon (C<:>). Only basic authentication is -currently supported. +Since only the private key file of the current node is used and the +private key file should be kept secret per-host to avoid spoofings, it is +not recommended to use this feature. -=item pid-file = path +=item rekey = seconds -The path to the pid file to check and create (Default: +Sets the rekeying interval in seconds (default: C<3600>). Connections are +reestablished every C seconds. =back @@ -297,14 +307,47 @@ =over 4 -=item udp-port = port-number +=item compress = yes|true|on | no|false|off -Sets the port number used by the UDP protocol (default: C<655>, not -officially assigned by IANA!). +Wether to compress data packets sent to this host (default: C). +Compression is really cheap even on slow computers and has no size +overhead at all, so enabling this is a good idea. -=item tcp-port = port-number +=item connect = ondemand | never | always | disabled -Similar to C (default: C<655>), but sets the TCP port number. +Sets the connect mode (default: C). It can be C (always +try to establish and keep a connection to the given host), C +(never initiate a connection to the given host, but accept connections), +C (try to establish a connection on the first packet sent, and +take it down after the keepalive interval) or C (node is bad, +don't talk to it). + +=item dns-domain = domain-suffix + +The DNS domain suffix that points to the DNS tunnel server. Needs to be +set on both client and server. + +The domain must point to a NS record that points to the I, +i.e. + + dns-domainname = tunnel.example.net + dns-hostname = tunnel-server.example.net + +Corresponds to the following DNS entries in the C domain: + + tunnel.example.net. NS tunnel-server.example.net. + tunnel-server.example.net. A 13.13.13.13 + +=item dns-hostname = hostname/ip + +The address to bind the DNS tunnel socket to, similar to the C, +but for the DNS tunnel protocol only. Default: C<0.0.0.0>, but that might +change. + +=item dns-port = port-number + +The port to bind the DNS tunnel socket to. Must be C<0> on all DNS tunnel +clients and C<53> on the server. =item enable-rawip = yes|true|on | no|false|off @@ -312,15 +355,6 @@ (default: C). This is the best choice, since the overhead per packet is only 38 bytes, as opposed to UDP's 58 (or TCP's 60+). -=item enable-udp = yes|true|on | no|false|off - -Enable the UDPv4 transport using the C port (default: C, -but this will change!). This is a good general choice since UDP tunnels -well through many firewalls. - -NOTE: Please specify C even though it is the default, as -some future version will have all protocols disabled by default. - =item enable-tcp = yes|true|on | no|false|off Enable the TCPv4 transport using the C port @@ -329,6 +363,33 @@ use this transport unless you really must, it is horribly ineffiecent and resource-intensive compared to the other transports. +=item enable-udp = yes|true|on | no|false|off + +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). This is a good general choice since +UDP tunnels well through many firewalls. + +NOTE: Please specify C if you want t use it even though +it might get switched on automatically, as some future version might +default to another default protocol. + +=item inherit-tos = yes|true|on | no|false|off + +Wether 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 max-retry = positive-number + +The maximum interval in seconds (default: C<28800>, 8 hours) between +retries to establish a connection to this node. When a connection cannot +be established, gvpe uses exponential backoff capped at this value. It's +sometimes useful to set this to a much lower value (e.g. C<120>) on +connections to routers that usually are stable but sometimes are down, to +assure quick reconnections. + =item router-priority = 0 | 1 | positive-number>2 Sets the router priority of the given host (default: C<0>, disabled). If @@ -347,36 +408,14 @@ C<0>, then routing will be refused, so C<1> serves as a "enable, but do not use by default" switch. -=item connect = ondemand | never | always | disabled - -Sets the connect mode (default: C). It can be C (always -try to establish and keep a connection to the given host), C -(never initiate a connection to the given host, but accept connections), -C (try to establish a connection on the first packet sent, and -take it down after the keepalive interval) or C (node is bad, -don't talk to it). - -=item inherit-tos = yes|true|on | no|false|off - -Wether 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 compress = yes|true|on | no|false|off +=item tcp-port = port-number -Wether to compress data packets sent to this host (default: C). -Compression is really cheap even on slow computers and has no size -overhead at all, so enabling this is a good idea. +Similar to C (default: C<655>), but sets the TCP port number. -=item max-retry = positive-number +=item udp-port = port-number -The maximum interval in seconds (default: C<28800>, 8 hours) between -retries to establish a connection to this node. When a connection cannot -be established, gvpe uses exponential backoff capped at this value. It's -sometimes useful to set this to a much lower value (e.g. C<120>) on -connections to routers that usually are stable but sometimes are down, to -assure quick reconnections. +Sets the port number used by the UDP protocol (default: C<655>, not +officially assigned by IANA!). =back @@ -386,23 +425,23 @@ =over 4 -=item gvpe.conf +=item X The config file. -=item if-up +=item X The if-up script -=item node-up, node-down +=item X, X If used the node up or node-down scripts. -=item hostkey +=item X The private key (taken from C) of the current host. -=item pubkey/nodename +=item X The public keys of the other nodes, one file per node.