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

Comparing gvpe/doc/gvpe.conf.5.pod (file contents):
Revision 1.11 by pcg, Thu Mar 17 22:28:53 2005 UTC vs.
Revision 1.19 by pcg, Thu Aug 7 19:07:02 2008 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
		122	the link is very stable lower values (e.g. C<2>) might work
		123	nicely. Values near or below C<1> makes no sense whatsoever.
		124
		125	The default should be working ok for most links but will result in low
		126	throughput if packet loss is high.
		127
75	=item if-up = relative-or-absolute-path	128	=item if-up = relative-or-absolute-path
76		129
77	Sets the path of a script that should be called immediately after the	130	Sets the path of a script that should be called immediately after the
78	network interface is initialized (but not neccessarily up). The following	131	network interface is initialized (but not neccessarily up). The following
79	environment variables are passed to it (the values are just examples):	132	environment variables are passed to it (the values are just examples).
		133
		134	Variables that have the same value on all nodes:
80		135
81	=over 4	136	=over 4
82		137
83	=item CONFBASE=/etc/gvpe	138	=item CONFBASE=/etc/gvpe
84		139
85	The configuration base directory.	140	The configuration base directory.
86		141
87	=item IFNAME=vpn0	142	=item IFNAME=vpn0
88		143
89	The interface to initialize.	144	The network interface to initialize.
		145
		146	=item IFTYPE=native # or tincd
		147
		148	=item IFSUBTYPE=linux # or freebsd, darwin etc..
		149
		150	The interface type (C<native> or C<tincd>) and the subtype (usually the
		151	OS name in lowercase) that this GVPE was configured for. Can be used to
		152	select the correct syntax to use for network-related commands.
90		153
91	=item MTU=1436	154	=item MTU=1436
92		155
93	The MTU to set the interface to. You can use lower values (if done	156	The MTU to set the interface to. You can use lower values (if done
94	consistently on all hosts), but this is usually ineffective.	157	consistently on all hosts), but this is usually ineffective.
95		158
		159	=item NODES=5
		160
		161	The number of nodes in this GVPE network.
		162
		163	=back
		164
		165	Variables that are node-specific and with values pertaining to the node
		166	running this GVPE:
		167
		168	=over 4
		169
		170	=item IFUPDATA=string
		171
		172	The value of the configuration directive C<if-up-data>.
		173
96	=item MAC=fe:fd:80:00:00:01	174	=item MAC=fe:fd:80:00:00:01
97		175
98	The MAC address to set the interface to. The script must set the	176	The MAC address the network interface has to use.
99	interface MAC to this value. You will most likely use one of these:
100		177
101	ip link set $IFNAME address $MAC mtu $MTU up # GNU/Linux	178	Might be used to initialize interfaces on platforms where GVPE does not
102	ifconfig $IFNAME ether $MAC mtu $MTU up # FreeBSD	179	do this automatically. Please see the C<gvpe.osdep(5)> manpage for
103		180	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		181
114	=item NODENAME=branch1	182	=item NODENAME=branch1
115		183
116	The nickname of the current node, as passed to the gvpe daemon.	184	The nickname of the node.
117		185
118	=item NODEID=1	186	=item NODEID=1
119		187
120	The numerical node id of the current node. The first node mentioned in the	188	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.	189	node mentioned in the config file gets ID 1, the second ID 2 and so on.
122		190
123	=back	191	=back
124		192
		193	In addition, all node-specific variables (except C<NODEID>) will be
		194	available with a postfix of C<_nodeid>, which contains the value for that
		195	node, e.g. the C<MAC_1> variable contains the MAC address of node #1, while
		196	the C<NODENAME_22> variable contains the name of node #22.
		197
125	Here is a simple if-up script:	198	Here is a simple if-up script:
126		199
127	#!/bin/sh	200	#!/bin/sh
128	ip link set $IFNAME address $MAC mtu $MTU up	201	ip link set $IFNAME up
129	[ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME	202	[ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME
130	[ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME	203	[ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME
131	ip route add 10.0.0.0/8 dev $IFNAME	204	ip route add 10.0.0.0/8 dev $IFNAME
132		205
133	More complicated examples (using routing to reduce arp traffic) can be	206	More complicated examples (using routing to reduce arp traffic) can be
…		…
227	used to select the right configuration section and must be passed as an	300	used to select the right configuration section and must be passed as an
228	argument to the gvpe daemon.	301	argument to the gvpe daemon.
229		302
230	=item node-up = relative-or-absolute-path	303	=item node-up = relative-or-absolute-path
231		304
232	Sets a command (default: no script) that should be called whenever a	305	Sets a command (default: none) that should be called whenever a connection
233	connection is established (even on rekeying operations). In addition	306	is established (even on rekeying operations). Note that node-up/down
		307	scripts will be run asynchronously, but execution is serialised, so there
		308	will only ever be one such script running.
		309
234	to the variables passed to C<if-up> scripts, the following environment	310	In addition to all the variables passed to C<if-up> scripts, the following
235	variables will be set:	311	environment variables will be set:
236		312
237	=over 4	313	=over 4
238		314
239	=item DESTNODE=branch2	315	=item DESTNODE=branch2
240		316
…		…
300		376
301	=head2 NODE SPECIFIC SETTINGS	377	=head2 NODE SPECIFIC SETTINGS
302		378
303	The following settings are node-specific, that is, every node can have	379	The following settings are node-specific, that is, every node can have
304	different settings, even within the same gvpe instance. Settings that are	380	different settings, even within the same gvpe instance. Settings that are
305	executed before the first node section set the defaults, settings that are	381	set before the first node section set the defaults, settings that are
306	executed within a node section only apply to the given node.	382	set within a node section only apply to the given node.
307		383
308	=over 4	384	=over 4
		385
		386	=item allow-direct = nodename
		387
		388	Allow direct connections to this node. See C<deny-direct> for more info.
309		389
310	=item compress = yes\|true\|on \| no\|false\|off	390	=item compress = yes\|true\|on \| no\|false\|off
311		391
312	Wether to compress data packets sent to this host (default: C<yes>).	392	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	393	Compression is really cheap even on slow computers and has no size
…		…
316	=item connect = ondemand \| never \| always \| disabled	396	=item connect = ondemand \| never \| always \| disabled
317		397
318	Sets the connect mode (default: C<always>). It can be C<always> (always	398	Sets the connect mode (default: C<always>). It can be C<always> (always
319	try to establish and keep a connection to the given host), C<never>	399	try to establish and keep a connection to the given host), C<never>
320	(never initiate a connection to the given host, but accept connections),	400	(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	401	C<ondemand> (try to establish a connection when there are outstanding
322	take it down after the keepalive interval) or C<disabled> (node is bad,	402	packets in the queue and take it down after the keepalive interval) or
323	don't talk to it).	403	C<disabled> (node is bad, don't talk to it).
		404
		405	=item deny-direct = nodename \| *
		406
		407	Deny direct connections to the specified node (or all nodes when C<*>
		408	is given). Only one node can be specified, but you can use multiple
		409	C<allow-direct> and C<deny-direct> statements. This only makes sense in
		410	networks with routers, as routers are required for indirect connections.
		411
		412	Sometimes, a node cannot reach some other nodes for reasons of network
		413	connectivity. For example, a node behind a firewall that only allows
		414	conenctions to/from a single other node in the network. In this case one
		415	should specify C<deny-direct = *> and C<allow-direct = othernodename> (the other
		416	node I<must> be a router for this to work).
		417
		418	The algorithm to check wether a connection may be direct is as follows:
		419
		420	1. Other node mentioned in a C<allow-direct>? If yes, allow the connection.
		421
		422	2. Other node mentioned in a C<deny-direct>? If yes, deny direct connections.
		423
		424	3. Allow the connection.
		425
		426	That is, C<allow-direct> takes precedence over C<deny-direct>.
		427
		428	The check is done in both directions, i.e. both nodes must allow a direct
		429	connection before one is attempted, so you only need to specify connect
		430	limitations on one node.
324		431
325	=item dns-domain = domain-suffix	432	=item dns-domain = domain-suffix
326		433
327	The DNS domain suffix that points to the DNS tunnel server for this node.	434	The DNS domain suffix that points to the DNS tunnel server for this node.
328		435
…		…
388		495
389	NOTE: Please specify C<enable-udp = yes> if you want t use it even though	496	NOTE: Please specify C<enable-udp = yes> if you want t use it even though
390	it might get switched on automatically, as some future version might	497	it might get switched on automatically, as some future version might
391	default to another default protocol.	498	default to another default protocol.
392		499
		500	=item hostname = hostname \| ip [can not be defaulted]
		501
		502	Forces the address of this node to be set to the given dns hostname or ip
		503	address. It will be resolved before each connect request, so dyndns should
		504	work fine. If this setting is not specified and a router is available,
		505	then the router will be queried for the address of this node. Otherwise,
		506	the connection attempt will fail.
		507
393	=item icmp-type = integer	508	=item icmp-type = integer
394		509
395	Sets the type value to be used for outgoing (and incoming) packets sent	510	Sets the type value to be used for outgoing (and incoming) packets sent
396	via the ICMP transport.	511	via the ICMP transport.
397		512
398	The default is C<0> (which is C<echo-reply>, also known as	513	The default is C<0> (which is C<echo-reply>, also known as
399	"ping-replies"). Other useful values include C<8> (C<echo-request>, a.k.a.	514	"ping-replies"). Other useful values include C<8> (C<echo-request>, a.k.a.
400	"ping") and C<11> (C<time-exceeded>), but any 8-bit value can be used.	515	"ping") and C<11> (C<time-exceeded>), but any 8-bit value can be used.
		516
		517	=item if-up-data = value
		518
		519	The value specified using this directive will be passed to the C<if-up>
		520	script in the environment variable C<IFUPDATA>.
401		521
402	=item inherit-tos = yes\|true\|on \| no\|false\|off	522	=item inherit-tos = yes\|true\|on \| no\|false\|off
403		523
404	Wether to inherit the TOS settings of packets sent to the tunnel when	524	Wether to inherit the TOS settings of packets sent to the tunnel when
405	sending packets to this node (default: C<yes>). If set to C<yes> then	525	sending packets to this node (default: C<yes>). If set to C<yes> then
…		…
412	retries to establish a connection to this node. When a connection cannot	532	retries to establish a connection to this node. When a connection cannot
413	be established, gvpe uses exponential backoff capped at this value. It's	533	be established, gvpe uses exponential backoff capped at this value. It's
414	sometimes useful to set this to a much lower value (e.g. C<120>) on	534	sometimes useful to set this to a much lower value (e.g. C<120>) on
415	connections to routers that usually are stable but sometimes are down, to	535	connections to routers that usually are stable but sometimes are down, to
416	assure quick reconnections even after longer downtimes.	536	assure quick reconnections even after longer downtimes.
		537
		538	=item max-ttl = seconds
		539
		540	Expire packets that couldn't be sent after this many seconds
		541	(default: C<60>). Gvpe will normally queue packets for a node without an
		542	active connection, in the hope of establishing a connection soon. This
		543	value specifies the maximum lifetime a packet will stay in the queue, if a
		544	packet gets older, it will be thrown away.
		545
		546	=item max-queue = positive-number
		547
		548	The maximum number of packets that will be queued (default: C<512>)
		549	for this node. If more packets are sent then earlier packets will be
		550	expired. See C<max-ttl>, above.
417		551
418	=item router-priority = 0 \| 1 \| positive-number>=2	552	=item router-priority = 0 \| 1 \| positive-number>=2
419		553
420	Sets the router priority of the given host (default: C<0>, disabled). If	554	Sets the router priority of the given host (default: C<0>, disabled). If
421	some host tries to connect to another host without a hostname, it asks	555	some host tries to connect to another host without a hostname, it asks
…		…
476		610
477	gvpe(5), gvpe(8), gvpectrl(8).	611	gvpe(5), gvpe(8), gvpectrl(8).
478		612
479	=head1 AUTHOR	613	=head1 AUTHOR
480		614
481	Marc Lehmann <gvpe@plan9.de>	615	Marc Lehmann <gvpe@schmorp.de>
482		616

Diff Legend

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

Comparing gvpe/doc/gvpe.conf.5.pod (file contents): Revision 1.11 by pcg, Thu Mar 17 22:28:53 2005 UTC vs. Revision 1.19 by pcg, Thu Aug 7 19:07:02 2008 UTC

Diff Legend

Comparing gvpe/doc/gvpe.conf.5.pod (file contents):
Revision 1.11 by pcg, Thu Mar 17 22:28:53 2005 UTC vs.
Revision 1.19 by pcg, Thu Aug 7 19:07:02 2008 UTC