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

Comparing gvpe/doc/gvpe.conf.5.pod (file contents):
Revision 1.28 by root, Sun Mar 6 19:40:27 2011 UTC vs.
Revision 1.38 by root, Sat Nov 12 21:45:49 2016 UTC

…		…
31	values, but not within the variable names or values themselves.	31	values, but not within the variable names or values themselves.
32		32
33	All settings are applied "in order", that is, later settings of the same	33	All settings are applied "in order", that is, later settings of the same
34	variable overwrite earlier ones.	34	variable overwrite earlier ones.
35		35
36	The only exceptions to the above are the "on" and "include" directives:	36	The only exceptions to the above are the following directives:
37		37
38	=over 4	38	=over 4
		39
		40	=item node nodename
		41
		42	Introduces a node section. The nodename is used to select the right
		43	configuration section and is the same string as is passed as an argument
		44	to the gvpe daemon.
		45
		46	Multiple C<node> statements with the same node name are supported and will
		47	be merged together.
		48
		49	=item global
		50
		51	This statement switches back to the global section, which is mainly
		52	useful if you want to include a second config file, e..g for local
		53	customisations. To do that, simply include this at the very end of your
		54	config file:
		55
		56	global
		57	include local.conf
39		58
40	=item on nodename ...	59	=item on nodename ...
41		60
42	=item on !nodename ...	61	=item on !nodename ...
43		62
…		…
97	is, they are in some sense node-specific (config files can set different	116	is, they are in some sense node-specific (config files can set different
98	values on different nodes using C<on>), but will affect the behaviour of	117	values on different nodes using C<on>), but will affect the behaviour of
99	the gvpe daemon and all connections it creates.	118	the gvpe daemon and all connections it creates.
100		119
101	=over 4	120	=over 4
		121
		122	=item chroot = path or /
		123
		124	Tells GVPE to chroot(2) to the specified path after reading all necessary
		125	files, binding to sockets and running the C<if-up> script, but before
		126	running C<node-up> or any other scripts.
		127
		128	The special path F</> instructs GVPE to create (and remove) an empty
		129	temporary directory to use as new root. This is most secure, but makes it
		130	impossible to use any scripts other than the C<if-up> one.
		131
		132	=item chuid = numerical-uid
		133
		134	=item chgid = numerical-gid
		135
		136	These two options tell GVPE to change to the given user and/or group id
		137	after reading all necessary files, binding to sockets and running the
		138	C<if-up> script.
		139
		140	Other scripts, such as C<node-up>, are run with the new user id or group id.
		141
		142	=item chuser = username
		143
		144	Alternative to C<chuid> and C<chgid>: Sets both C<chuid> and C<chgid>
		145	to the user and (primary) group ids of the specified user (for example,
		146	C<nobody>).
102		147
103	=item dns-forw-host = hostname/ip	148	=item dns-forw-host = hostname/ip
104		149
105	The DNS server to forward DNS requests to for the DNS tunnel protocol	150	The DNS server to forward DNS requests to for the DNS tunnel protocol
106	(default: C<127.0.0.1>, changing it is highly recommended).	151	(default: C<127.0.0.1>, changing it is highly recommended).
…		…
324		369
325	=item keepalive = seconds	370	=item keepalive = seconds
326		371
327	Sets the keepalive probe interval in seconds (default: C<60>). After this	372	Sets the keepalive probe interval in seconds (default: C<60>). After this
328	many seconds of inactivity the daemon will start to send keepalive probe	373	many seconds of inactivity the daemon will start to send keepalive probe
329	every 3 seconds until it receives a reply from the other end. If no reply	374	every 3 seconds until it receives a reply from the other end. If no reply
330	is received within 15 seconds, the peer is considered unreachable and the	375	is received within 15 seconds, the peer is considered unreachable and the
331	connection is closed.	376	connection is closed.
332		377
333	=item loglevel = noise\|trace\|debug\|info\|notice\|warn\|error\|critical	378	=item loglevel = noise\|trace\|debug\|info\|notice\|warn\|error\|critical
334		379
…		…
343	this information to the C<if-up> script.	388	this information to the C<if-up> script.
344		389
345	Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp).	390	Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp).
346		391
347	This value must be the minimum of the MTU values of all nodes.	392	This value must be the minimum of the MTU values of all nodes.
348
349	=item node = nickname
350
351	Not really a config setting but introduces a node section. The nickname is
352	used to select the right configuration section and must be passed as an
353	argument to the gvpe daemon.
354
355	=item node-up = relative-or-absolute-path
356
357	Sets a command (default: none) that should be called whenever a connection
358	is established (even on rekeying operations). Note that node-up/down
359	scripts will be run asynchronously, but execution is serialised, so there
360	will only ever be one such script running.
361
362	In addition to all the variables passed to C<if-up> scripts, the following
363	environment variables will be set (values are just examples):
364
365	=over 4
366
367	=item DESTNODE=branch2
368
369	The name of the remote node.
370
371	=item DESTID=2
372
373	The node id of the remote node.
374
375	=item DESTSI=rawip/88.99.77.55:0
376
377	The "socket info" of the target node, protocol dependent but usually in
378	the format protocol/ip:port.
379
380	=item DESTIP=188.13.66.8
381
382	The numerical IP address of the remote node (gvpe accepts connections from
383	everywhere, as long as the other node can authenticate itself).
384
385	=item DESTPORT=655 # deprecated
386
387	The protocol port used by the other side, if applicable.
388
389	=item STATE=up
390
391	Node-up scripts get called with STATE=up, node-change scripts get called
392	with STATE=change and node-down scripts get called with STATE=down.
393
394	=back
395
396	Here is a nontrivial example that uses nsupdate to update the name => ip
397	mapping in some DNS zone:
398
399	#!/bin/sh
400	{
401	echo update delete $DESTNODE.lowttl.example.net. a
402	echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP
403	echo
404	} \| nsupdate -d -k $CONFBASE:key.example.net.
405
406	=item node-change = relative-or-absolute-path
407
408	Same as C<node-change>, but gets called whenever something about a
409	connection changes (such as the source IP address).
410
411	=item node-down = relative-or-absolute-path
412
413	Same as C<node-up>, but gets called whenever a connection is lost.
414
415	=item pid-file = path
416
417	The path to the pid file to check and create
418	(default: C<LOCALSTATEDIR/run/gvpe.pid>).
419
420	=item private-key = relative-path-to-key
421
422	Sets the path (relative to the config directory) to the private key
423	(default: C<hostkey>). This is a printf format string so every C<%> must
424	be doubled. A single C<%s> is replaced by the hostname, so you could
425	use paths like C<hostkeys/%s> to fetch the files at the location where
426	C<gvpectrl> puts them.
427
428	Since only the private key file of the current node is used and the
429	private key file should be kept secret per-node to avoid spoofing, it is
430	not recommended to use this feature.
431
432	=item rekey = seconds
433
434	Sets the rekeying interval in seconds (default: C<3600>). Connections are
435	reestablished every C<rekey> seconds, making them use a new encryption
436	key.
437		393
438	=item nfmark = integer	394	=item nfmark = integer
439		395
440	This advanced option, when set to a nonzero value (default: C<0>), tries	396	This advanced option, when set to a nonzero value (default: C<0>), tries
441	to set the netfilter mark (or fwmark) value on all sockets gvpe uses to	397	to set the netfilter mark (or fwmark) value on all sockets gvpe uses to
…		…
446	put all routing rules into table C<99> and then use an ip rule to make	402	put all routing rules into table C<99> and then use an ip rule to make
447	gvpe traffic avoid that routing table, in effect routing normal traffic	403	gvpe traffic avoid that routing table, in effect routing normal traffic
448	via gvpe and gvpe traffic via the normal system routing tables:	404	via gvpe and gvpe traffic via the normal system routing tables:
449		405
450	ip rule add not fwmark 1000 lookup 99	406	ip rule add not fwmark 1000 lookup 99
		407
		408	=item node-up = relative-or-absolute-path
		409
		410	Sets a command (default: none) that should be called whenever a connection
		411	is established (even on rekeying operations). Note that node-up/down
		412	scripts will be run asynchronously, but execution is serialised, so there
		413	will only ever be one such script running.
		414
		415	In addition to all the variables passed to C<if-up> scripts, the following
		416	environment variables will be set (values are just examples):
		417
		418	=over 4
		419
		420	=item DESTNODE=branch2
		421
		422	The name of the remote node.
		423
		424	=item DESTID=2
		425
		426	The node id of the remote node.
		427
		428	=item DESTSI=rawip/88.99.77.55:0
		429
		430	The "socket info" of the target node, protocol dependent but usually in
		431	the format protocol/ip:port.
		432
		433	=item DESTIP=188.13.66.8
		434
		435	The numerical IP address of the remote node (gvpe accepts connections from
		436	everywhere, as long as the other node can authenticate itself).
		437
		438	=item DESTPORT=655 # deprecated
		439
		440	The protocol port used by the other side, if applicable.
		441
		442	=item STATE=up
		443
		444	Node-up scripts get called with STATE=up, node-change scripts get called
		445	with STATE=change and node-down scripts get called with STATE=down.
		446
		447	=back
		448
		449	Here is a nontrivial example that uses nsupdate to update the name => ip
		450	mapping in some DNS zone:
		451
		452	#!/bin/sh
		453	{
		454	echo update delete $DESTNODE.lowttl.example.net. a
		455	echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP
		456	echo
		457	} \| nsupdate -d -k $CONFBASE:key.example.net.
		458
		459	=item node-change = relative-or-absolute-path
		460
		461	Same as C<node-change>, but gets called whenever something about a
		462	connection changes (such as the source IP address).
		463
		464	=item node-down = relative-or-absolute-path
		465
		466	Same as C<node-up>, but gets called whenever a connection is lost.
		467
		468	=item pid-file = path
		469
		470	The path to the pid file to check and create
		471	(default: C<LOCALSTATEDIR/run/gvpe.pid>). The first C<%s> is replaced by
		472	the nodename - any other use of C<%> must be written as C<%%>.
		473
		474	=item private-key = relative-path-to-key
		475
		476	Sets the path (relative to the config directory) to the private key
		477	(default: C<hostkey>). This is a printf format string so every C<%> must
		478	be doubled. A single C<%s> is replaced by the hostname, so you could use
		479	paths like C<hostkeys/%s> to be able to share the same config directory
		480	between nodes.
		481
		482	Since only the private key file of the current node is used and the
		483	private key file should be kept secret per-node to avoid spoofing, it is
		484	not recommended to use this feature this way though.
		485
		486	=item rekey = seconds
		487
		488	Sets the rekeying interval in seconds (default: C<3607>). Connections are
		489	reestablished every C<rekey> seconds, making them use a new encryption
		490	key.
		491
		492	=item seed-device = path
		493
		494	The random device used to initially and regularly seed the random
		495	number generator (default: F</dev/urandom>). Randomness is of paramount
		496	importance to the security of the algorithms used in gvpe.
		497
		498	On program start and every seed-interval, gvpe will read 64 octets.
		499
		500	Setting this path to the empty string will disable this functionality
		501	completely (the underlying crypto library will likely look for entropy
		502	sources on it's own though, so not all is lost).
		503
		504	=item seed-interval = seconds
		505
		506	The number of seconds between reseeds of the random number generator
		507	(default: C<3613>). A value of C<0> disables this regular reseeding.
		508
		509	=item serial = string
		510
		511	The configuration serial number. This can be any string up to 16 bytes
		512	length. Only when the serial matches on both sides of a connection will
		513	the connection succeed. This is I<not> a security mechanism and eay to
		514	spoof, this mechanism exists to alert users that their config is outdated.
		515
		516	It's recommended to specify this is a date string such as C<2013-05-05> or
		517	C<20121205084417>.
		518
		519	The exact algorithm is as this: if a connection request is received form a
		520	node with an identical serial, then it succeeds normally.
		521
		522	If the remote serial is lower than the local serial, it is ignored.
		523
		524	If the remote serial is higher than the local serial, a warning message is
		525	logged.
451		526
452	=back	527	=back
453		528
454	=head2 NODE SPECIFIC SETTINGS	529	=head2 NODE SPECIFIC SETTINGS
455		530
…		…
604	Whether to inherit the TOS settings of packets sent to the tunnel when	679	Whether to inherit the TOS settings of packets sent to the tunnel when
605	sending packets to this node (default: C<yes>). If set to C<yes> then	680	sending packets to this node (default: C<yes>). If set to C<yes> then
606	outgoing tunnel packets will have the same TOS setting as the packets sent	681	outgoing tunnel packets will have the same TOS setting as the packets sent
607	to the tunnel device, which is usually what you want.	682	to the tunnel device, which is usually what you want.
608		683
		684	=item low-power = yes\|true\|on \| no\|false\|off
		685
		686	If true, designates a node as a low-power node. Low-power nodes use
		687	larger timeouts and try to reduce cpu time. Other nodes talking to a
		688	low-power node will also use larger timeouts, and will use less aggressive
		689	optimisations, in the hope of reducing load. Security is not compromised.
		690
		691	The typical low-power node would be a mobile phone, where wakeups and
		692	encryption can significantly increase power drain.
		693
609	=item max-retry = positive-number	694	=item max-retry = positive-number
610		695
611	The maximum interval in seconds (default: C<3600>, one hour) between	696	The maximum interval in seconds (default: C<3600>, one hour) between
612	retries to establish a connection to this node. When a connection cannot	697	retries to establish a connection to this node. When a connection cannot
613	be established, gvpe uses exponential back-off capped at this value. It's	698	be established, gvpe uses exponential back-off capped at this value. It's
…		…
686		771
687	If used the node up or node-down scripts.	772	If used the node up or node-down scripts.
688		773
689	=item hostkey	774	=item hostkey
690		775
691	The private key (taken from C<hostkeys/nodename>) of the current host.	776	The (default path of the) private key of the current host.
692		777
693	=item pubkey/nodename	778	=item pubkey/nodename
694		779
695	The public keys of the other nodes, one file per node.	780	The public keys of the other nodes, one file per node.
696		781

Diff Legend

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

Comparing gvpe/doc/gvpe.conf.5.pod (file contents): Revision 1.28 by root, Sun Mar 6 19:40:27 2011 UTC vs. Revision 1.38 by root, Sat Nov 12 21:45:49 2016 UTC

Diff Legend

Comparing gvpe/doc/gvpe.conf.5.pod (file contents):
Revision 1.28 by root, Sun Mar 6 19:40:27 2011 UTC vs.
Revision 1.38 by root, Sat Nov 12 21:45:49 2016 UTC