[ViewVC] Diff of: cvs/gvpe/doc/gvpe.conf.5.pod

Comparing gvpe/doc/gvpe.conf.5.pod (file contents):
Revision 1.8 by pcg, Mon Mar 7 01:31:26 2005 UTC vs.
Revision 1.16 by pcg, Wed Aug 2 16:58:49 2006 UTC

…		…
21	=head1 DESCRIPTION	21	=head1 DESCRIPTION
22		22
23	The gvpe config file consists of a series of lines that contain C<variable	23	The gvpe config file consists of a series of lines that contain C<variable
24	= value> pairs. Empty lines are ignored. Comments start with a C<#> and	24	= value> pairs. Empty lines are ignored. Comments start with a C<#> and
25	extend to the end of the line. They can be used on their own lines, or	25	extend to the end of the line. They can be used on their own lines, or
26	after any directives. Spaces are allowed before or after the C<=> sign or	26	after any directives. Whitespace is allowed around the C<=> sign or after
27	after values, but not within the variable names or values themselves.	27	values, but not within the variable names or values themselves.
28		28
29	The only exception to the above is the "on" directive that can prefix any	29	The only exception to the above is the "on" directive that can prefix any
30	C<name = value> setting and will only "execute" it on the named node, or	30	C<name = value> setting and will only "execute" it on the named node, or
31	(if the nodename starts with "!") on all nodes except the named one.	31	(if the nodename starts with "!") on all nodes except the named one.
32		32
…		…
70	=item dns-forw-port = port-number	70	=item dns-forw-port = port-number
71		71
72	The port where the C<dns-forw-host> is to be contacted (default: C<53>,	72	The port where the C<dns-forw-host> is to be contacted (default: C<53>,
73	which is fine in most cases).	73	which is fine in most cases).
74		74
		75	=item dns-max-outstanding = integer-number-of-requests
		76
		77	The maximum number of outstanding DNS transport requests
		78	(default: C<100>). GVPE will never issue more requests then the given
		79	limit without receiving replies. In heavily overloaded situations it might
		80	help to set this to a low number (e.g. C<3> or even C<1>) to limit the
		81	number of parallel requests.
		82
		83	The default should be working ok for most links.
		84
		85	=item dns-overlap-factor = float
		86
		87	The DNS transport uses the minimum request latency (B<min_latency>) seen
		88	during a connection as it's timing base. This factor (default: C<0.5>,
		89	must be > 0) is multiplied by B<min_latency> to get the maximum sending
		90	rate (= minimum send interval), i.e. a factor of C<1> means that a new
		91	request might be generated every B<min_latency> seconds, which means on
		92	average there should only ever be one outstanding request. A factor of
		93	C<0.5> means that GVPE will send requests twice as often as the minimum
		94	latency measured.
		95
		96	For congested or picky dns forwarders you could use a value nearer to or
		97	exceeding C<1>.
		98
		99	The default should be working ok for most links.
		100
		101	=item dns-send-interval = send-interval-in-seconds
		102
		103	The minimum send interval (= maximum rate) that the DNS transport will
		104	use to send new DNS requests. GVPE will not exceed this rate even when
		105	the latency is very low. The default is C<0.01>, which means GVPE will
		106	not send more than 100 DNS requests per connection per second. For
		107	high-bandwidth links you could go lower, e.g. to C<0.001> or so. For
		108	congested or rate-limited links, you might want to go higher, say C<0.1>,
		109	C<0.2> or even higher.
		110
		111	The default should be working ok for most links.
		112
		113	=item dns-timeout-factor = float
		114
		115	Factor to multiply the C<min_latency> (see C<dns-overlap-factor>) by to
		116	get request timeouts. The default of C<8> means that the DNS transport
		117	will resend the request when no reply has been received for longer than
		118	eight times the minimum (= expected) latency, assuming the request or
		119	reply has been lost.
		120
		121	For congested links a higher value might be necessary (e.g. C<30>). If the
		122	link is very stable lower values (e.g. C<2>) might work nicely. Values
		123	near or below C<1> makes no sense whatsoever.
		124
		125	The default should be working ok for most links.
		126
75	=item if-up = relative-or-absolute-path	127	=item if-up = relative-or-absolute-path
76		128
77	Sets the path of a script that should be called immediately after the	129	Sets the path of a script that should be called immediately after the
78	network interface is initialized (but not neccessarily up). The following	130	network interface is initialized (but not neccessarily up). The following
79	environment variables are passed to it (the values are just examples):	131	environment variables are passed to it (the values are just examples).
		132
		133	Variables that have the same value on all nodes:
80		134
81	=over 4	135	=over 4
82		136
83	=item CONFBASE=/etc/gvpe	137	=item CONFBASE=/etc/gvpe
84		138
85	The configuration base directory.	139	The configuration base directory.
86		140
87	=item IFNAME=vpn0	141	=item IFNAME=vpn0
88		142
89	The interface to initialize.	143	The network interface to initialize.
		144
		145	=item IFTYPE=native # or tincd
		146
		147	=item IFSUBTYPE=linux # or freebsd, darwin etc..
		148
		149	The interface type (C<native> or C<tincd>) and the subtype (usually the
		150	OS name in lowercase) that this GVPE was configured for. Can be used to
		151	select the correct syntax to use for network-related commands.
90		152
91	=item MTU=1436	153	=item MTU=1436
92		154
93	The MTU to set the interface to. You can use lower values (if done	155	The MTU to set the interface to. You can use lower values (if done
94	consistently on all hosts), but this is usually ineffective.	156	consistently on all hosts), but this is usually ineffective.
95		157
		158	=item NODES=5
		159
		160	The number of nodes in this GVPE network.
		161
		162	=back
		163
		164	Variables that are node-specific and with values pertaining to the node
		165	running this GVPE:
		166
		167	=over 4
		168
		169	=item IFUPDATA=string
		170
		171	The value of the configuration directive C<if-up-data>.
		172
96	=item MAC=fe:fd:80:00:00:01	173	=item MAC=fe:fd:80:00:00:01
97		174
98	The MAC address to set the interface to. The script must set the	175	The MAC address the network interface has to use.
99	interface MAC to this value. You will most likely use one of these:
100		176
101	ip link set $IFNAME address $MAC mtu $MTU up # GNU/Linux	177	Might be used to initialize interfaces on platforms where GVPE does not
102	ifconfig $IFNAME ether $MAC mtu $MTU up # FreeBSD	178	do this automatically. Please see the C<gvpe.osdep(5)> manpage for
103		179	platform-specific information.
104	Please see the C<gvpe.osdep(5)> manpage for platform-specific information.
105
106	=item IFTYPE=native # or tincd
107
108	=item IFSUBTYPE=linux # or freebsd, darwin etc..
109
110	The interface type (C<native> or C<tincd>) and the subtype (usually the os
111	name in lowercase) that this gvpe was configured for. Can be used to select
112	the correct syntax to use for network-related commands.
113		180
114	=item NODENAME=branch1	181	=item NODENAME=branch1
115		182
116	The nickname of the current node, as passed to the gvpe daemon.	183	The nickname of the node.
117		184
118	=item NODEID=1	185	=item NODEID=1
119		186
120	The numerical node id of the current node. The first node mentioned in the	187	The numerical node ID of the node running this instance of GVPE. The first
121	config file gets ID 1, the second ID 2 and so on.	188	node mentioned in the config file gets ID 1, the second ID 2 and so on.
122		189
123	=back	190	=back
124		191
		192	In addition, all node-specific variables (except C<NODEID>) will be
		193	available with a postfix of C<_nodeid>, which contains the value for that
		194	node, e.g. the C<MAC_1> variable contains the MAC address of node #1, while
		195	the C<NODENAME_22> variable contains the name of node #22.
		196
125	Here is a simple if-up script:	197	Here is a simple if-up script:
126		198
127	#!/bin/sh	199	#!/bin/sh
128	ip link set $IFNAME address $MAC mtu $MTU up	200	ip link set $IFNAME up
129	[ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME	201	[ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME
130	[ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME	202	[ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME
131	ip route add 10.0.0.0/8 dev $IFNAME	203	ip route add 10.0.0.0/8 dev $IFNAME
132		204
133	More complicated examples (using routing to reduce arp traffic) can be	205	More complicated examples (using routing to reduce arp traffic) can be
…		…
228	argument to the gvpe daemon.	300	argument to the gvpe daemon.
229		301
230	=item node-up = relative-or-absolute-path	302	=item node-up = relative-or-absolute-path
231		303
232	Sets a command (default: no script) that should be called whenever a	304	Sets a command (default: no script) that should be called whenever a
233	connection is established (even on rekeying operations). In addition	305	connection is established (even on rekeying operations). In addition to
234	to the variables passed to C<if-up> scripts, the following environment	306	all the variables passed to C<if-up> scripts, the following environment
235	variables will be set:	307	variables will be set:
236		308
237	=over 4	309	=over 4
238		310
239	=item DESTNODE=branch2	311	=item DESTNODE=branch2
…		…
300		372
301	=head2 NODE SPECIFIC SETTINGS	373	=head2 NODE SPECIFIC SETTINGS
302		374
303	The following settings are node-specific, that is, every node can have	375	The following settings are node-specific, that is, every node can have
304	different settings, even within the same gvpe instance. Settings that are	376	different settings, even within the same gvpe instance. Settings that are
305	executed before the first node section set the defaults, settings that are	377	set before the first node section set the defaults, settings that are
306	executed within a node section only apply to the given node.	378	set within a node section only apply to the given node.
307		379
308	=over 4	380	=over 4
		381
		382	=item allow-direct = nodename
		383
		384	Allow direct connections to this node. See C<deny-direct> for more info.
309		385
310	=item compress = yes\|true\|on \| no\|false\|off	386	=item compress = yes\|true\|on \| no\|false\|off
311		387
312	Wether to compress data packets sent to this host (default: C<yes>).	388	Wether to compress data packets sent to this host (default: C<yes>).
313	Compression is really cheap even on slow computers and has no size	389	Compression is really cheap even on slow computers and has no size
…		…
320	(never initiate a connection to the given host, but accept connections),	396	(never initiate a connection to the given host, but accept connections),
321	C<ondemand> (try to establish a connection on the first packet sent, and	397	C<ondemand> (try to establish a connection on the first packet sent, and
322	take it down after the keepalive interval) or C<disabled> (node is bad,	398	take it down after the keepalive interval) or C<disabled> (node is bad,
323	don't talk to it).	399	don't talk to it).
324		400
		401	=item deny-direct = nodename \| *
		402
		403	Deny direct connections to the specified node (or all nodes when C<*>
		404	is given). Only one node can be specified, but you can use multiple
		405	C<allow-direct> and C<deny-direct> statements. This only makes sense in
		406	networks with routers, as routers are required for indirect connections.
		407
		408	Sometimes, a node cannot reach some other nodes for reasons of network
		409	connectivity. For example, a node behind a firewall that only allows
		410	conenctions to/from a single other node in the network. In this case one
		411	should specify C<deny-direct = *> and C<allow-direct = othernodename> (the other
		412	node I<must> be a router for this to work).
		413
		414	The algorithm to check wether a connection may be direct is as follows:
		415
		416	1. Other node mentioned in a C<allow-direct>? If yes, allow the connection.
		417
		418	2. Other node mentioned in a C<deny-direct>? If yes, deny direct connections.
		419
		420	3. Allow the connection.
		421
		422	That is, C<allow-direct> takes precedence over C<deny-direct>.
		423
		424	The check is done in both directions, i.e. both nodes must allow a direct
		425	connection before one is attempted, so you only need to specify connect
		426	limitations on one node.
		427
325	=item dns-domain = domain-suffix	428	=item dns-domain = domain-suffix
326		429
327	The DNS domain suffix that points to the DNS tunnel server for this node.	430	The DNS domain suffix that points to the DNS tunnel server for this node.
328		431
329	The domain must point to a NS record that points to the I<dns-hostname>,	432	The domain must point to a NS record that points to the I<dns-hostname>,
…		…
347		450
348	The port to bind the DNS tunnel socket to. Must be C<53> on DNS tunnel servers.	451	The port to bind the DNS tunnel socket to. Must be C<53> on DNS tunnel servers.
349		452
350	=item enable-dns = yes\|true\|on \| no\|false\|off	453	=item enable-dns = yes\|true\|on \| no\|false\|off
351		454
		455	See gvpe.protocol(7) for a description of the DNS transport
		456	protocol. Avoid this protocol if you can.
		457
352	Enable the DNS tunneling protocol on this node, either as server or as	458	Enable the DNS tunneling protocol on this node, either as server or as
353	client (only available when gvpe was compiled with C<--enable-dns>).	459	client. Support for this transport protocol is only available when gvpe
		460	was compiled using the C<--enable-dns> option.
354		461
355	This is the worst choice of transport protocol with respect to overhead	462	=item enable-icmp = yes\|true\|on \| no\|false\|off
356	(overhead cna be 2-3 times higher than the transferred data), and probably	463
357	the best choice when tunneling through firewalls.	464	See gvpe.protocol(7) for a description of the ICMP transport protocol.
		465
		466	Enable the ICMP transport using icmp packets of type C<icmp-type> on this
		467	node.
358		468
359	=item enable-rawip = yes\|true\|on \| no\|false\|off	469	=item enable-rawip = yes\|true\|on \| no\|false\|off
360		470
		471	See gvpe.protocol(7) for a description of the RAW IP transport protocol.
		472
361	Enable the RAW IPv4 transport using the C<ip-proto> protocol	473	Enable the RAW IPv4 transport using the C<ip-proto> protocol
362	(default: C<no>). This is the best choice, since the minimum overhead per	474	(default: C<no>).
363	packet is only 38 bytes, as opposed to UDP's 58 (or TCP's 60+).
364		475
365	=item enable-tcp = yes\|true\|on \| no\|false\|off	476	=item enable-tcp = yes\|true\|on \| no\|false\|off
366		477
		478	See gvpe.protocol(7) for a description of the TCP transport protocol.
		479
367	Enable the TCPv4 transport using the C<tcp-port> port	480	Enable the TCPv4 transport using the C<tcp-port> port
368	(default: C<no>). Support for this horribly unsuitable protocol is only	481	(default: C<no>). Support for this transport protocol is only available
369	available when gvpe was compiled using the C<--enable-tcp> option. Never	482	when gvpe was compiled using the C<--enable-tcp> option.
370	use this transport unless you really must, it is very inefficient and
371	resource-intensive compared to the other transports (except for DNS, which
372	is worse).
373		483
374	=item enable-udp = yes\|true\|on \| no\|false\|off	484	=item enable-udp = yes\|true\|on \| no\|false\|off
		485
		486	See gvpe.protocol(7) for a description of the UDP transport protocol.
375		487
376	Enable the UDPv4 transport using the C<udp-port> port (default: C<no>,	488	Enable the UDPv4 transport using the C<udp-port> port (default: C<no>,
377	unless no other protocol is enabled for a node, in which case this	489	unless no other protocol is enabled for a node, in which case this
378	protocol is enabled automatically). This is a good general choice since	490	protocol is enabled automatically).
379	UDP tunnels well through many firewalls.
380		491
381	NOTE: Please specify C<enable-udp = yes> if you want t use it even though	492	NOTE: Please specify C<enable-udp = yes> if you want t use it even though
382	it might get switched on automatically, as some future version might	493	it might get switched on automatically, as some future version might
383	default to another default protocol.	494	default to another default protocol.
		495
		496	=item hostname = hostname \| ip [can not be defaulted]
		497
		498	Forces the address of this node to be set to the given dns hostname or ip
		499	address. It will be resolved before each connect request, so dyndns should
		500	work fine. If this setting is not specified and a router is available,
		501	then the router will be queried for the address of this node. Otherwise,
		502	the connection attempt will fail.
		503
		504	=item icmp-type = integer
		505
		506	Sets the type value to be used for outgoing (and incoming) packets sent
		507	via the ICMP transport.
		508
		509	The default is C<0> (which is C<echo-reply>, also known as
		510	"ping-replies"). Other useful values include C<8> (C<echo-request>, a.k.a.
		511	"ping") and C<11> (C<time-exceeded>), but any 8-bit value can be used.
		512
		513	=item if-up-data = value
		514
		515	The value specified using this directive will be passed to the C<if-up>
		516	script in the environment variable C<IFUPDATA>.
384		517
385	=item inherit-tos = yes\|true\|on \| no\|false\|off	518	=item inherit-tos = yes\|true\|on \| no\|false\|off
386		519
387	Wether to inherit the TOS settings of packets sent to the tunnel when	520	Wether to inherit the TOS settings of packets sent to the tunnel when
388	sending packets to this node (default: C<yes>). If set to C<yes> then	521	sending packets to this node (default: C<yes>). If set to C<yes> then
…		…
459		592
460	gvpe(5), gvpe(8), gvpectrl(8).	593	gvpe(5), gvpe(8), gvpectrl(8).
461		594
462	=head1 AUTHOR	595	=head1 AUTHOR
463		596
464	Marc Lehmann <gvpe@plan9.de>	597	Marc Lehmann <gvpe@schmorp.de>
465		598

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing gvpe/doc/gvpe.conf.5.pod (file contents): Revision 1.8 by pcg, Mon Mar 7 01:31:26 2005 UTC vs. Revision 1.16 by pcg, Wed Aug 2 16:58:49 2006 UTC

Diff Legend

Comparing gvpe/doc/gvpe.conf.5.pod (file contents):
Revision 1.8 by pcg, Mon Mar 7 01:31:26 2005 UTC vs.
Revision 1.16 by pcg, Wed Aug 2 16:58:49 2006 UTC