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

Comparing gvpe/doc/gvpe.conf.5.pod (file contents):
Revision 1.10 by pcg, Thu Mar 17 22:24:31 2005 UTC vs.
Revision 1.18 by pcg, Thu Aug 7 17:30:27 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
…		…
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: no script) that should be called whenever a
233	connection is established (even on rekeying operations). In addition	306	connection is established (even on rekeying operations). In addition to
234	to the variables passed to C<if-up> scripts, the following environment	307	all the variables passed to C<if-up> scripts, the following environment
235	variables will be set:	308	variables will be set:
236		309
237	=over 4	310	=over 4
238		311
239	=item DESTNODE=branch2	312	=item DESTNODE=branch2
…		…
300		373
301	=head2 NODE SPECIFIC SETTINGS	374	=head2 NODE SPECIFIC SETTINGS
302		375
303	The following settings are node-specific, that is, every node can have	376	The following settings are node-specific, that is, every node can have
304	different settings, even within the same gvpe instance. Settings that are	377	different settings, even within the same gvpe instance. Settings that are
305	executed before the first node section set the defaults, settings that are	378	set before the first node section set the defaults, settings that are
306	executed within a node section only apply to the given node.	379	set within a node section only apply to the given node.
307		380
308	=over 4	381	=over 4
		382
		383	=item allow-direct = nodename
		384
		385	Allow direct connections to this node. See C<deny-direct> for more info.
309		386
310	=item compress = yes\|true\|on \| no\|false\|off	387	=item compress = yes\|true\|on \| no\|false\|off
311		388
312	Wether to compress data packets sent to this host (default: C<yes>).	389	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	390	Compression is really cheap even on slow computers and has no size
…		…
316	=item connect = ondemand \| never \| always \| disabled	393	=item connect = ondemand \| never \| always \| disabled
317		394
318	Sets the connect mode (default: C<always>). It can be C<always> (always	395	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>	396	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),	397	(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	398	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,	399	packets in the queue and take it down after the keepalive interval) or
323	don't talk to it).	400	C<disabled> (node is bad, don't talk to it).
		401
		402	=item deny-direct = nodename \| *
		403
		404	Deny direct connections to the specified node (or all nodes when C<*>
		405	is given). Only one node can be specified, but you can use multiple
		406	C<allow-direct> and C<deny-direct> statements. This only makes sense in
		407	networks with routers, as routers are required for indirect connections.
		408
		409	Sometimes, a node cannot reach some other nodes for reasons of network
		410	connectivity. For example, a node behind a firewall that only allows
		411	conenctions to/from a single other node in the network. In this case one
		412	should specify C<deny-direct = *> and C<allow-direct = othernodename> (the other
		413	node I<must> be a router for this to work).
		414
		415	The algorithm to check wether a connection may be direct is as follows:
		416
		417	1. Other node mentioned in a C<allow-direct>? If yes, allow the connection.
		418
		419	2. Other node mentioned in a C<deny-direct>? If yes, deny direct connections.
		420
		421	3. Allow the connection.
		422
		423	That is, C<allow-direct> takes precedence over C<deny-direct>.
		424
		425	The check is done in both directions, i.e. both nodes must allow a direct
		426	connection before one is attempted, so you only need to specify connect
		427	limitations on one node.
324		428
325	=item dns-domain = domain-suffix	429	=item dns-domain = domain-suffix
326		430
327	The DNS domain suffix that points to the DNS tunnel server for this node.	431	The DNS domain suffix that points to the DNS tunnel server for this node.
328		432
…		…
387	protocol is enabled automatically).	491	protocol is enabled automatically).
388		492
389	NOTE: Please specify C<enable-udp = yes> if you want t use it even though	493	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	494	it might get switched on automatically, as some future version might
391	default to another default protocol.	495	default to another default protocol.
		496
		497	=item hostname = hostname \| ip [can not be defaulted]
		498
		499	Forces the address of this node to be set to the given dns hostname or ip
		500	address. It will be resolved before each connect request, so dyndns should
		501	work fine. If this setting is not specified and a router is available,
		502	then the router will be queried for the address of this node. Otherwise,
		503	the connection attempt will fail.
		504
		505	=item icmp-type = integer
		506
		507	Sets the type value to be used for outgoing (and incoming) packets sent
		508	via the ICMP transport.
		509
		510	The default is C<0> (which is C<echo-reply>, also known as
		511	"ping-replies"). Other useful values include C<8> (C<echo-request>, a.k.a.
		512	"ping") and C<11> (C<time-exceeded>), but any 8-bit value can be used.
		513
		514	=item if-up-data = value
		515
		516	The value specified using this directive will be passed to the C<if-up>
		517	script in the environment variable C<IFUPDATA>.
392		518
393	=item inherit-tos = yes\|true\|on \| no\|false\|off	519	=item inherit-tos = yes\|true\|on \| no\|false\|off
394		520
395	Wether to inherit the TOS settings of packets sent to the tunnel when	521	Wether to inherit the TOS settings of packets sent to the tunnel when
396	sending packets to this node (default: C<yes>). If set to C<yes> then	522	sending packets to this node (default: C<yes>). If set to C<yes> then
…		…
403	retries to establish a connection to this node. When a connection cannot	529	retries to establish a connection to this node. When a connection cannot
404	be established, gvpe uses exponential backoff capped at this value. It's	530	be established, gvpe uses exponential backoff capped at this value. It's
405	sometimes useful to set this to a much lower value (e.g. C<120>) on	531	sometimes useful to set this to a much lower value (e.g. C<120>) on
406	connections to routers that usually are stable but sometimes are down, to	532	connections to routers that usually are stable but sometimes are down, to
407	assure quick reconnections even after longer downtimes.	533	assure quick reconnections even after longer downtimes.
		534
		535	=item max-ttl = seconds
		536
		537	Expire packets that couldn't be sent after this many seconds
		538	(default: C<60>). Gvpe will normally queue packets for a node without an
		539	active connection, in the hope of establishing a connection soon. This
		540	value specifies the maximum lifetime a packet will stay in the queue, if a
		541	packet gets older, it will be thrown away.
		542
		543	=item max-queue = positive-number
		544
		545	The maximum number of packets that will be queued (default: C<512>)
		546	for this node. If more packets are sent then earlier packets will be
		547	expired. See C<max-ttl>, above.
408		548
409	=item router-priority = 0 \| 1 \| positive-number>=2	549	=item router-priority = 0 \| 1 \| positive-number>=2
410		550
411	Sets the router priority of the given host (default: C<0>, disabled). If	551	Sets the router priority of the given host (default: C<0>, disabled). If
412	some host tries to connect to another host without a hostname, it asks	552	some host tries to connect to another host without a hostname, it asks
…		…
467		607
468	gvpe(5), gvpe(8), gvpectrl(8).	608	gvpe(5), gvpe(8), gvpectrl(8).
469		609
470	=head1 AUTHOR	610	=head1 AUTHOR
471		611
472	Marc Lehmann <gvpe@plan9.de>	612	Marc Lehmann <gvpe@schmorp.de>
473		613

Diff Legend

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

Comparing gvpe/doc/gvpe.conf.5.pod (file contents): Revision 1.10 by pcg, Thu Mar 17 22:24:31 2005 UTC vs. Revision 1.18 by pcg, Thu Aug 7 17:30:27 2008 UTC

Diff Legend

Comparing gvpe/doc/gvpe.conf.5.pod (file contents):
Revision 1.10 by pcg, Thu Mar 17 22:24:31 2005 UTC vs.
Revision 1.18 by pcg, Thu Aug 7 17:30:27 2008 UTC