ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/gvpe.conf.5.pod
(Generate patch)

Comparing gvpe/doc/gvpe.conf.5.pod (file contents):
Revision 1.5 by pcg, Tue Mar 1 06:27:20 2005 UTC vs.
Revision 1.12 by pcg, Wed Mar 23 17:03:58 2005 UTC

60values on different nodes using C<on>), but will affect the behaviour of 60values on different nodes using C<on>), but will affect the behaviour of
61the gvpe daemon and all connections it creates. 61the gvpe daemon and all connections it creates.
62 62
63=over 4 63=over 4
64 64
65=item loglevel = noise|trace|debug|info|notice|warn|error|critical 65=item dns-forw-host = hostname/ip
66 66
67Set the logging level. Connection established messages are logged at level 67The dns server to forward dns requests to for the DNS tunnel protocol
68C<info>, notable errors are logged with C<error>. Default is C<info>. 68(default: C<127.0.0.1>, changing it is highly recommended).
69 69
70=item node = nickname 70=item dns-forw-port = port-number
71 71
72Not really a config setting but introduces a node section. The nickname is 72The port where the C<dns-forw-host> is to be contacted (default: C<53>,
73used to select the right configuration section and must be passed as an 73which is fine in most cases).
74argument to the gvpe daemon.
75 74
76=item private-key = relative-path-to-key 75=item dns-max-outstanding = integer-number-of-requests
77 76
78Sets the path (relative to the config directory) to the private key 77The maximum number of outstanding DNS transport requests
79(default: C<hostkey>). This is a printf format string so every C<%> must 78(default: C<100>). GVPE will never issue more requests then the given
80be doubled. A single C<%s> is replaced by the hostname, so you could 79limit without receiving replies. In heavily overloaded situations it might
81use paths like C<hostkeys/%s> to fetch the files at the location where 80help to set this to a low number (e.g. C<3> or even C<1>) to limit the
82C<gvpectrl> puts them. 81number of parallel requests.
83 82
84Since only the private key file of the current node is used and the 83The default should be working ok for most links.
85private key file should be kept secret per-host to avoid spoofings, it is 84
86not recommended to use this feature. 85=item dns-overlap-factor = float
86
87The DNS transport uses the minimum request latency (B<min_latency>) seen
88during a connection as it's timing base. This factor (default: C<0.5>,
89must be > 0) is multiplied by B<min_latency> to get the maximum sending
90rate (= minimum send interval), i.e. a factor of C<1> means that a new
91request might be generated every B<min_latency> seconds, which means on
92average there should only ever be one outstanding request. A factor of
93C<0.5> means that GVPE will send requests twice as often as the minimum
94latency measured.
95
96For congested or picky dns forwarders you could use a value nearer to or
97exceeding C<1>.
98
99The default should be working ok for most links.
100
101=item dns-send-interval = send-interval-in-seconds
102
103The minimum send interval (= maximum rate) that the DNS transport will
104use to send new DNS requests. GVPE will not exceed this rate even when
105the latency is very low. The default is C<0.01>, which means GVPE will
106not send more than 100 DNS requests per connection per second. For
107high-bandwidth links you could go lower, e.g. to C<0.001> or so. For
108congested or rate-limited links, you might want to go higher, say C<0.1>,
109C<0.2> or even higher.
110
111The default should be working ok for most links.
112
113=item dns-timeout-factor = float
114
115Factor to multiply the C<min_latency> (see C<dns-overlap-factor>) by to
116get request timeouts. The default of C<8> means that the DNS transport
117will resend the request when no reply has been received for longer than
118eight times the minimum (= expected) latency, assuming the request or
119reply has been lost.
120
121For congested links a higher value might be necessary (e.g. C<30>). If the
122link is very stable lower values (e.g. C<2>) might work nicely. Values
123near or below C<1> makes no sense whatsoever.
124
125The default should be working ok for most links.
126
127=item if-up = relative-or-absolute-path
128
129Sets the path of a script that should be called immediately after the
130network interface is initialized (but not neccessarily up). The following
131environment variables are passed to it (the values are just examples):
132
133=over 4
134
135=item CONFBASE=/etc/gvpe
136
137The configuration base directory.
138
139=item IFNAME=vpn0
140
141The interface to initialize.
142
143=item MTU=1436
144
145The MTU to set the interface to. You can use lower values (if done
146consistently on all hosts), but this is usually ineffective.
147
148=item MAC=fe:fd:80:00:00:01
149
150The MAC address to set the interface to. The script *must* set the
151interface MAC to this value. You will most likely use one of these:
152
153 ip link set $IFNAME address $MAC mtu $MTU up # GNU/Linux
154 ifconfig $IFNAME ether $MAC mtu $MTU up # FreeBSD
155
156Please see the C<gvpe.osdep(5)> manpage for platform-specific information.
157
158=item IFTYPE=native # or tincd
159
160=item IFSUBTYPE=linux # or freebsd, darwin etc..
161
162The interface type (C<native> or C<tincd>) and the subtype (usually the os
163name in lowercase) that this gvpe was configured for. Can be used to select
164the correct syntax to use for network-related commands.
165
166=item NODENAME=branch1
167
168The nickname of the current node, as passed to the gvpe daemon.
169
170=item NODEID=1
171
172The numerical node id of the current node. The first node mentioned in the
173config file gets ID 1, the second ID 2 and so on.
174
175=back
176
177Here is a simple if-up script:
178
179 #!/bin/sh
180 ip link set $IFNAME address $MAC mtu $MTU up
181 [ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME
182 [ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME
183 ip route add 10.0.0.0/8 dev $IFNAME
184
185More complicated examples (using routing to reduce arp traffic) can be
186found in the etc/ subdirectory of the distribution.
187
188=item ifname = devname
189
190Sets the tun interface name to the given name. The default is OS-specific
191and most probably something like C<tun0>.
87 192
88=item ifpersist = yes|true|on | no|false|off 193=item ifpersist = yes|true|on | no|false|off
89 194
90Should the tun/tap device be made persistent, that is, should the device 195Should the tun/tap device be made persistent, that is, should the device
91stay up even when gvpe exits? Some versions of the tunnel device have 196stay up even when gvpe exits? Some versions of the tunnel device have
92problems sending packets when gvpe is restarted in persistent mode, so 197problems sending packets when gvpe is restarted in persistent mode, so
93if the connections can be established but you cannot send packets from 198if the connections can be established but you cannot send packets from
94the local node, try to set this to C<off> and do an ifconfig down on the 199the local node, try to set this to C<off> and do an ifconfig down on the
95device. 200device.
96 201
97=item ifname = devname 202=item ip-proto = numerical-ip-protocol
98 203
99Sets the tun interface name to the given name. The default is OS-specific 204Sets the protocol number to be used for the rawip protocol. This is a
100and most probably something like C<tun0>. 205global option because all hosts must use the same protocol, and since
206there are no port numbers, you cannot easily run more than one gvpe
207instance using the same protocol, nor can you share the protocol with
208other programs.
101 209
102=item rekey = seconds 210The default is 47 (GRE), which has a good chance of tunneling through
211firewalls (but note that the rawip protocol is not GRE compatible). Other
212common choices are 50 (IPSEC, ESP), 51 (IPSEC, AH), 4 (IPIP tunnels) or 98
213(ENCAP, rfc1241)
103 214
104Sets the rekeying interval in seconds (default: C<3600>). Connections are 215=item http-proxy-host = hostname/ip
105reestablished every C<rekey> seconds. 216
217The C<http-proxy-*> family of options are only available if gvpe was
218compiled with the C<--enable-http-proxy> option and enable tunneling of
219tcp connections through a http proxy server.
220
221C<http-proxy-host> and C<http-proxy-port> should specify the hostname and
222port number of the proxy server. See C<http-proxy-loginpw> if your proxy
223requires authentication.
224
225Please note that gvpe will still try to resolve all hostnames in the
226configuration file, so if you are behind a proxy without access to a dns
227server better use numerical IP addresses.
228
229To make best use of this option disable all protocols except tcp in your
230config file and make sure your routers (or all other hosts) are listening
231on a port that the proxy allows (443, https, is a common choice).
232
233If you have a router, connecting to it will suffice. Otherwise tcp must be
234enabled on all hosts.
235
236Example:
237
238 http-proxy-host = proxy.example.com
239 http-proxy-port = 3128 # 8080 is another common choice
240 http-proxy-auth = schmorp:grumbeere
241
242=item http-proxy-port = proxy-tcp-port
243
244The port where your proxy server listens.
245
246=item http-proxy-auth = login:password
247
248The optional login and password used to authenticate to the proxy server,
249seperated by a literal colon (C<:>). Only basic authentication is
250currently supported.
106 251
107=item keepalive = seconds 252=item keepalive = seconds
108 253
109Sets the keepalive probe interval in seconds (default: C<60>). After this 254Sets the keepalive probe interval in seconds (default: C<60>). After this
110many seconds of inactivity the daemon will start to send keepalive probe 255many seconds of inactivity the daemon will start to send keepalive probe
111every 5 seconds until it receives a reply from the other end. If no reply 256every 5 seconds until it receives a reply from the other end. If no reply
112is received within 30 seconds, the peer is considered unreachable and the 257is received within 30 seconds, the peer is considered unreachable and the
113connection is closed. 258connection is closed.
114 259
260=item loglevel = noise|trace|debug|info|notice|warn|error|critical
261
262Set the logging level. Connection established messages are logged at level
263C<info>, notable errors are logged with C<error>. Default is C<info>.
264
115=item mtu = bytes 265=item mtu = bytes
116 266
117Sets the maximum MTU that should be used on outgoing packets (basically 267Sets the maximum MTU that should be used on outgoing packets (basically
118the MTU of the outgoing interface) The daemon will automatically calculate 268the MTU of the outgoing interface) The daemon will automatically calculate
119maximum overhead (e.g. udp header size, encryption blocksize...) and pass 269maximum overhead (e.g. udp header size, encryption blocksize...) and pass
121 271
122Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp). 272Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp).
123 273
124This value must be the minimum of the mtu values of all hosts. 274This value must be the minimum of the mtu values of all hosts.
125 275
126=item ip-proto = numerical-ip-protocol 276=item node = nickname
127 277
128Sets the protocol number to be used for the rawip protocol. This is a 278Not really a config setting but introduces a node section. The nickname is
129global option because all hosts must use the same protocol, and since 279used to select the right configuration section and must be passed as an
130there are no port numbers, you cannot easily run more than one gvpe 280argument to the gvpe daemon.
131instance using the same protocol, nor can you share the protocol with
132other programs.
133
134The default is 47 (GRE), which has a good chance of tunneling through
135firewalls (but note that the rawip protocol is not GRE compatible). Other
136common choices are 50 (IPSEC, ESP), 51 (IPSEC, AH), 4 (IPIP tunnels) or 98
137(ENCAP, rfc1241)
138
139=item if-up = relative-or-absolute-path
140
141Sets the path of a script that should be called immediately after the
142network interface is initialized (but not neccessarily up). The following
143environment variables are passed to it (the values are just examples):
144
145=over 4
146
147=item CONFBASE=/etc/gvpe
148
149The configuration base directory.
150
151=item IFNAME=vpn0
152
153The interface to initialize.
154
155=item MTU=1436
156
157The MTU to set the interface to. You can use lower values (if done
158consistently on all hosts), but this is usually ineffective.
159
160=item MAC=fe:fd:80:00:00:01
161
162The MAC address to set the interface to. The script *must* set the
163interface MAC to this value. You will most likely use one of these:
164
165 ip link set $IFNAME address $MAC mtu $MTU up # GNU/Linux
166 ifconfig $IFNAME ether $MAC mtu $MTU up # FreeBSD
167
168Please see the C<gvpe.osdep(5)> manpage for platform-specific information.
169
170=item IFTYPE=native # or tincd
171
172=item IFSUBTYPE=linux # or freebsd, darwin etc..
173
174The interface type (C<native> or C<tincd>) and the subtype (usually the os
175name in lowercase) that this gvpe was configured for. Can be used to select
176the correct syntax to use for network-related commands.
177
178=item NODENAME=branch1
179
180The nickname of the current node, as passed to the gvpe daemon.
181
182=item NODEID=1
183
184The numerical node id of the current node. The first node mentioned in the
185config file gets ID 1, the second ID 2 and so on.
186
187=back
188
189Here is a simple if-up script:
190
191 #!/bin/sh
192 ip link set $IFNAME address $MAC mtu $MTU up
193 [ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME
194 [ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME
195 ip route add 10.0.0.0/8 dev $IFNAME
196
197More complicated examples (using routing to reduce arp traffic) can be
198found in the etc/ subdirectory of the distribution.
199 281
200=item node-up = relative-or-absolute-path 282=item node-up = relative-or-absolute-path
201 283
202Sets a command (default: no script) that should be called whenever a 284Sets a command (default: no script) that should be called whenever a
203connection is established (even on rekeying operations). In addition 285connection is established (even on rekeying operations). In addition
242 324
243=item node-down = relative-or-absolute-path 325=item node-down = relative-or-absolute-path
244 326
245Same as C<node-up>, but gets called whenever a connection is lost. 327Same as C<node-up>, but gets called whenever a connection is lost.
246 328
247=item http-proxy-host = hostname/ip
248
249The C<http-proxy-*> family of options are only available if gvpe was
250compiled with the C<--enable-http-proxy> option and enable tunneling of
251tcp connections through a http proxy server.
252
253C<http-proxy-host> and C<http-proxy-port> should specify the hostname and
254port number of the proxy server. See C<http-proxy-loginpw> if your proxy
255requires authentication.
256
257Please note that gvpe will still try to resolve all hostnames in the
258configuration file, so if you are behind a proxy without access to a dns
259server better use numerical IP addresses.
260
261To make best use of this option disable all protocols except tcp in your
262config file and make sure your routers (or all other hosts) are listening
263on a port that the proxy allows (443, https, is a common choice).
264
265If you have a router, connecting to it will suffice. Otherwise tcp must be
266enabled on all hosts.
267
268Example:
269
270 http-proxy-host = proxy.example.com
271 http-proxy-port = 3128 # 8080 is another common choice
272 http-proxy-auth = schmorp:grumbeere
273
274=item http-proxy-port = proxy-tcp-port
275
276The port where your proxy server listens.
277
278=item http-proxy-auth = login:password
279
280The optional login and password used to authenticate to the proxy server,
281seperated by a literal colon (C<:>). Only basic authentication is
282currently supported.
283
284=item pid-file = path 329=item pid-file = path
285 330
286The path to the pid file to check and create (Default: 331The path to the pid file to check and create
332(default: C<LOCALSTATEDIR/run/gvpe.pid>).
333
334=item private-key = relative-path-to-key
335
336Sets the path (relative to the config directory) to the private key
337(default: C<hostkey>). This is a printf format string so every C<%> must
338be doubled. A single C<%s> is replaced by the hostname, so you could
339use paths like C<hostkeys/%s> to fetch the files at the location where
340C<gvpectrl> puts them.
341
342Since only the private key file of the current node is used and the
343private key file should be kept secret per-host to avoid spoofings, it is
344not recommended to use this feature.
345
346=item rekey = seconds
347
348Sets the rekeying interval in seconds (default: C<3600>). Connections are
349reestablished every C<rekey> seconds.
287 350
288=back 351=back
289 352
290=head2 NODE SPECIFIC SETTINGS 353=head2 NODE SPECIFIC SETTINGS
291 354
294executed before the first node section set the defaults, settings that are 357executed before the first node section set the defaults, settings that are
295executed within a node section only apply to the given node. 358executed within a node section only apply to the given node.
296 359
297=over 4 360=over 4
298 361
362=item compress = yes|true|on | no|false|off
363
364Wether to compress data packets sent to this host (default: C<yes>).
365Compression is really cheap even on slow computers and has no size
366overhead at all, so enabling this is a good idea.
367
368=item connect = ondemand | never | always | disabled
369
370Sets the connect mode (default: C<always>). It can be C<always> (always
371try to establish and keep a connection to the given host), C<never>
372(never initiate a connection to the given host, but accept connections),
373C<ondemand> (try to establish a connection on the first packet sent, and
374take it down after the keepalive interval) or C<disabled> (node is bad,
375don't talk to it).
376
377=item dns-domain = domain-suffix
378
379The DNS domain suffix that points to the DNS tunnel server for this node.
380
381The domain must point to a NS record that points to the I<dns-hostname>,
382i.e.
383
384 dns-domainname = tunnel.example.net
385 dns-hostname = tunnel-server.example.net
386
387Corresponds to the following DNS entries in the C<example.net> domain:
388
389 tunnel.example.net. NS tunnel-server.example.net.
390 tunnel-server.example.net. A 13.13.13.13
391
392=item dns-hostname = hostname/ip
393
394The address to bind the DNS tunnel socket to, similar to the C<hostname>,
395but for the DNS tunnel protocol only. Default: C<0.0.0.0>, but that might
396change.
397
299=item udp-port = port-number 398=item dns-port = port-number
300 399
301Sets the port number used by the UDP protocol (default: C<655>, not 400The port to bind the DNS tunnel socket to. Must be C<53> on DNS tunnel servers.
302officially assigned by IANA!).
303 401
304=item tcp-port = port-number 402=item enable-dns = yes|true|on | no|false|off
305 403
306Similar to C<udp-port> (default: C<655>), but sets the TCP port number. 404See gvpe.protocol(7) for a description of the DNS transport
405protocol. Avoid this protocol if you can.
406
407Enable the DNS tunneling protocol on this node, either as server or as
408client. Support for this transport protocol is only available when gvpe
409was compiled using the C<--enable-dns> option.
410
411=item enable-icmp = yes|true|on | no|false|off
412
413See gvpe.protocol(7) for a description of the ICMP transport protocol.
414
415Enable the ICMP transport using icmp packets of type C<icmp-type> on this
416node.
307 417
308=item enable-rawip = yes|true|on | no|false|off 418=item enable-rawip = yes|true|on | no|false|off
309 419
420See gvpe.protocol(7) for a description of the RAW IP transport protocol.
421
310Enable the RAW IPv4 transport using the C<ip-proto> protocol 422Enable the RAW IPv4 transport using the C<ip-proto> protocol
311(default: C<no>). This is the best choice, since the overhead per packet 423(default: C<no>).
312is only 38 bytes, as opposed to UDP's 58 (or TCP's 60+). 424
425=item enable-tcp = yes|true|on | no|false|off
426
427See gvpe.protocol(7) for a description of the TCP transport protocol.
428
429Enable the TCPv4 transport using the C<tcp-port> port
430(default: C<no>). Support for this transport protocol is only available
431when gvpe was compiled using the C<--enable-tcp> option.
313 432
314=item enable-udp = yes|true|on | no|false|off 433=item enable-udp = yes|true|on | no|false|off
434
435See gvpe.protocol(7) for a description of the UDP transport protocol.
315 436
316Enable the UDPv4 transport using the C<udp-port> port (default: C<no>, 437Enable the UDPv4 transport using the C<udp-port> port (default: C<no>,
317unless no other protocol is enabled for a node, in which case this 438unless no other protocol is enabled for a node, in which case this
318protocol is enabled automatically). This is a good general choice since 439protocol is enabled automatically).
319UDP tunnels well through many firewalls.
320 440
321NOTE: Please specify C<enable-udp = yes> if you want t use it even though 441NOTE: Please specify C<enable-udp = yes> if you want t use it even though
322it might get switched on automatically, as some future version might 442it might get switched on automatically, as some future version might
323default to another default protocol. 443default to another default protocol.
324 444
445=item icmp-type = integer
446
447Sets the type value to be used for outgoing (and incoming) packets sent
448via the ICMP transport.
449
450The default is C<0> (which is C<echo-reply>, also known as
451"ping-replies"). Other useful values include C<8> (C<echo-request>, a.k.a.
452"ping") and C<11> (C<time-exceeded>), but any 8-bit value can be used.
453
325=item enable-tcp = yes|true|on | no|false|off 454=item inherit-tos = yes|true|on | no|false|off
326 455
327Enable the TCPv4 transport using the C<tcp-port> port 456Wether to inherit the TOS settings of packets sent to the tunnel when
328(default: C<no>). Support for this horribly unsuitable protocol is only 457sending packets to this node (default: C<yes>). If set to C<yes> then
329available when gvpe was compiled using the C<--enable-tcp> option. Never 458outgoing tunnel packets will have the same TOS setting as the packets sent
330use this transport unless you really must, it is horribly ineffiecent and 459to the tunnel device, which is usually what you want.
331resource-intensive compared to the other transports.
332 460
461=item max-retry = positive-number
462
463The maximum interval in seconds (default: C<3600>, one hour) between
464retries to establish a connection to this node. When a connection cannot
465be established, gvpe uses exponential backoff capped at this value. It's
466sometimes useful to set this to a much lower value (e.g. C<120>) on
467connections to routers that usually are stable but sometimes are down, to
468assure quick reconnections even after longer downtimes.
469
333=item router-priority = 0 | 1 | positive-number>2 470=item router-priority = 0 | 1 | positive-number>=2
334 471
335Sets the router priority of the given host (default: C<0>, disabled). If 472Sets the router priority of the given host (default: C<0>, disabled). If
336some host tries to connect to another host without a hostname, it asks 473some host tries to connect to another host without a hostname, it asks
337the router host for it's IP address. The router host is the one with the 474the router host for it's IP address. The router host is the one with the
338highest priority larger than C<1> that is currently reachable. 475highest priority larger than C<1> that is currently reachable.
346required, bump the C<router-priority> setting to higher than C<1> in their 483required, bump the C<router-priority> setting to higher than C<1> in their
347local config to route through specific hosts. If C<router-priority> is 484local config to route through specific hosts. If C<router-priority> is
348C<0>, then routing will be refused, so C<1> serves as a "enable, but do 485C<0>, then routing will be refused, so C<1> serves as a "enable, but do
349not use by default" switch. 486not use by default" switch.
350 487
351=item connect = ondemand | never | always | disabled 488=item tcp-port = port-number
352 489
353Sets the connect mode (default: C<always>). It can be C<always> (always 490Similar to C<udp-port> (default: C<655>), but sets the TCP port number.
354try to establish and keep a connection to the given host), C<never>
355(never initiate a connection to the given host, but accept connections),
356C<ondemand> (try to establish a connection on the first packet sent, and
357take it down after the keepalive interval) or C<disabled> (node is bad,
358don't talk to it).
359 491
360=item inherit-tos = yes|true|on | no|false|off 492=item udp-port = port-number
361 493
362Wether to inherit the TOS settings of packets sent to the tunnel when 494Sets the port number used by the UDP protocol (default: C<655>, not
363sending packets to this node (default: C<yes>). If set to C<yes> then 495officially assigned by IANA!).
364outgoing tunnel packets will have the same TOS setting as the packets sent
365to the tunnel device, which is usually what you want.
366
367=item compress = yes|true|on | no|false|off
368
369Wether to compress data packets sent to this host (default: C<yes>).
370Compression is really cheap even on slow computers and has no size
371overhead at all, so enabling this is a good idea.
372
373=item max-retry = positive-number
374
375The maximum interval in seconds (default: C<28800>, 8 hours) between
376retries to establish a connection to this node. When a connection cannot
377be established, gvpe uses exponential backoff capped at this value. It's
378sometimes useful to set this to a much lower value (e.g. C<120>) on
379connections to routers that usually are stable but sometimes are down, to
380assure quick reconnections.
381 496
382=back 497=back
383 498
384=head1 CONFIG DIRECTORY LAYOUT 499=head1 CONFIG DIRECTORY LAYOUT
385 500

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines