Document GraphDumpFile option.

[tinc] / doc / tinc.texi

diff --git a/doc/tinc.texi b/doc/tinc.texi
index c31885d..35b5e69 100644 (file)
--- a/doc/tinc.texi
+++ b/doc/tinc.texi
@@ -16,8 +16,8 @@
 
 This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
 
 
 This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
 

-Copyright @copyright{} 1998-2004 Ivo Timmermans
-<ivo@@tinc-vpn.org>, Guus Sliepen <guus@@tinc-vpn.org> and
+Copyright @copyright{} 1998-2006 Ivo Timmermans,
+Guus Sliepen <guus@@tinc-vpn.org> and

 Wessel Dankers <wsl@@tinc-vpn.org>.
 
 $Id$
 Wessel Dankers <wsl@@tinc-vpn.org>.
 
 $Id$


@@ -43,8 +43,8 @@ permission notice identical to this one.
 @cindex copyright
 This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
 
 @cindex copyright
 This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
 

-Copyright @copyright{} 1998-2004 Ivo Timmermans
-<ivo@@tinc-vpn.org>, Guus Sliepen <guus@@tinc-vpn.org> and
+Copyright @copyright{} 1998-2006 Ivo Timmermans,
+Guus Sliepen <guus@@tinc-vpn.org> and

 Wessel Dankers <wsl@@tinc-vpn.org>.
 
 $Id$
 Wessel Dankers <wsl@@tinc-vpn.org>.
 
 $Id$


@@ -194,84 +194,6 @@ For an up to date list of supported platforms, please check the list on
 our website:
 @uref{http://www.tinc-vpn.org/platforms}.
 
 our website:
 @uref{http://www.tinc-vpn.org/platforms}.
 

-
-@c ==================================================================
-@subsection Linux
-
-@cindex Linux
-Tinc was first written for Linux running on an intel x86 processor, so
-this is the best supported platform.  The protocol however, and actually
-anything about tinc, has been rewritten to support random byte ordering
-and arbitrary word length.  So in theory it should run on other
-processors that Linux runs on.  It has already been verified to run on
-alpha and sparc processors as well.
-
-Tinc uses the ethertap device or the universal tun/tap driver. The former is provided in the standard kernel
-from version 2.1.60 up to 2.3.x, but has been replaced in favour of the tun/tap driver in kernel versions 2.4.0 and later.
-
-
-@c ==================================================================
-@subsection FreeBSD
-
-@cindex FreeBSD
-Tinc on FreeBSD relies on the universal tun/tap driver for its data
-acquisition from the kernel.  Therefore, tinc will work on the same platforms
-as this driver.  These are: FreeBSD 3.x, 4.x, 5.x.
-
-
-@c ==================================================================
-@subsection OpenBSD
-
-@cindex OpenBSD
-Tinc on OpenBSD relies on the tun driver for its data
-acquisition from the kernel. It has been verified to work under at least OpenBSD 2.9.
-There is also a kernel patch from @uref{http://diehard.n-r-g.com/stuff/openbsd/}
-which adds a tap device to OpenBSD.
-This should work with tinc.
-
-Tunneling IPv6 packets may not work on OpenBSD.
-
-
-@c ==================================================================
-@subsection Solaris
-
-@c ==================================================================
-@subsection NetBSD
-
-@cindex NetBSD
-Tinc on NetBSD relies on the tun driver for its data
-acquisition from the kernel. It has been verified to work under at least NetBSD 1.5.2.
-
-Tunneling IPv6 may not work on OpenBSD.
-
-
-@c ==================================================================
-@subsection Solaris
-
-@cindex Solaris
-Tinc on Solaris relies on the universal tun/tap driver for its data
-acquisition from the kernel.  Therefore, tinc will work on the same platforms
-as this driver. It has been verified to work under Solaris 8 (SunOS 5.8).
-
-@c ==================================================================
-@subsection Darwin (MacOS/X)
-
-@cindex Darwin
-@cindex MacOS/X
-Tinc on Darwin relies on a tunnel driver for its data acquisition from the kernel.
-Tinc supports either the driver from @uref{http://www-user.rhrk.uni-kl.de/~nissler/tuntap/},
-which supports both tun and tap style devices,
-and also the driver from from @uref{http://chrisp.de/en/projects/tunnel.html}.
-The former driver is recommended.
-
-@c ==================================================================
-@subsection Windows
-
-@cindex Windows
-Tinc on Windows relies on the TAP-Win32 driver (as shipped by OpenVPN) for its data acquisition from the kernel.
-This driver is not part of Windows but can be downloaded from @uref{http://openvpn.sourceforge.net/}.
-
-

 @c
 @c
 @c
 @c
 @c
 @c


@@ -302,26 +224,6 @@ support tinc.
 @node    Configuring the kernel
 @section Configuring the kernel
 
 @node    Configuring the kernel
 @section Configuring the kernel
 

-@cindex RedHat
-@cindex Debian
-@cindex netlink_dev
-@cindex tun
-@cindex ethertap
-If you are running Linux, chances are good that your kernel already supports
-all the devices that tinc needs for proper operation.  For example, the
-standard kernel from Redhat Linux already has support for ethertap and netlink
-compiled in.  Debian users can use the modconf utility to select the modules.
-If your Linux distribution supports this method of selecting devices, look out
-for something called `ethertap', and `netlink_dev' if it is using a kernel
-version prior to 2.4.0. In that case you will need both these devices.  If you
-are using kernel 2.4.0 or later, you need to select `tun'.
-
-@cindex Kernel-HOWTO
-If you can install these devices in a similar manner, you may skip this section.
-Otherwise, you will have to recompile the kernel in order to turn on the required features.
-If you are unfamiliar with the process of configuring and compiling a new kernel,
-you should read the @uref{http://howto.linuxberg.com/LDP/HOWTO/Kernel-HOWTO.html, Kernel HOWTO} first.
-

 @menu
 * Configuration of Linux kernels 2.1.60 up to 2.4.0::
 * Configuration of Linux kernels 2.4.0 and higher::
 @menu
 * Configuration of Linux kernels 2.1.60 up to 2.4.0::
 * Configuration of Linux kernels 2.4.0 and higher::


@@ -338,7 +240,10 @@ you should read the @uref{http://howto.linuxberg.com/LDP/HOWTO/Kernel-HOWTO.html
 @node       Configuration of Linux kernels 2.1.60 up to 2.4.0
 @subsection Configuration of Linux kernels 2.1.60 up to 2.4.0
 
 @node       Configuration of Linux kernels 2.1.60 up to 2.4.0
 @subsection Configuration of Linux kernels 2.1.60 up to 2.4.0
 

-Here are the options you have to turn on when configuring a new kernel:
+@cindex ethertap
+For kernels up to 2.4.0, you need a kernel that supports the ethertap device.
+Most distributions come with kernels that already support this.
+If not, here are the options you have to turn on when configuring a new kernel:

 
 @example
 Code maturity level options
 
 @example
 Code maturity level options


@@ -375,6 +280,9 @@ Add as much alias/options lines as necessary.
 @node       Configuration of Linux kernels 2.4.0 and higher
 @subsection Configuration of Linux kernels 2.4.0 and higher
 
 @node       Configuration of Linux kernels 2.4.0 and higher
 @subsection Configuration of Linux kernels 2.4.0 and higher
 

+@cindex Universal tun/tap
+For kernels 2.4.0 and higher, you need a kernel that supports the Universal tun/tap device.
+Most distributions come with kernels that already support this.

 Here are the options you have to turn on when configuring a new kernel:
 
 @example
 Here are the options you have to turn on when configuring a new kernel:
 
 @example


@@ -404,9 +312,8 @@ alias char-major-10-200 tun
 @node       Configuration of FreeBSD kernels
 @subsection Configuration of FreeBSD kernels
 
 @node       Configuration of FreeBSD kernels
 @subsection Configuration of FreeBSD kernels
 

-For FreeBSD version 4.1 and higher, the tap driver is included in the default kernel configuration, for earlier
-systems (4.0 and earlier), you need to install the universal tun/tap driver
-yourself.
+For FreeBSD version 4.1 and higher, tun and tap drivers are included in the default kernel configuration.
+Using tap devices is recommended.

 
 
 @c ==================================================================
 
 
 @c ==================================================================


@@ -415,6 +322,9 @@ yourself.
 
 For OpenBSD version 2.9 and higher,
 the tun driver is included in the default kernel configuration.
 
 For OpenBSD version 2.9 and higher,
 the tun driver is included in the default kernel configuration.

+There is also a kernel patch from @uref{http://diehard.n-r-g.com/stuff/openbsd/}
+which adds a tap device to OpenBSD.
+This should work with tinc.

 
 
 @c ==================================================================
 
 
 @c ==================================================================


@@ -424,6 +334,8 @@ the tun driver is included in the default kernel configuration.
 For NetBSD version 1.5.2 and higher,
 the tun driver is included in the default kernel configuration.
 
 For NetBSD version 1.5.2 and higher,
 the tun driver is included in the default kernel configuration.
 

+Tunneling IPv6 may not work on NetBSD's tun device.
+

 
 @c ==================================================================
 @node       Configuration of Solaris kernels
 
 @c ==================================================================
 @node       Configuration of Solaris kernels


@@ -440,18 +352,17 @@ If the @file{net/if_tun.h} header file is missing, install it from the source pa
 @node       Configuration of Darwin (MacOS/X) kernels
 @subsection Configuration of Darwin (MacOS/X) kernels
 
 @node       Configuration of Darwin (MacOS/X) kernels
 @subsection Configuration of Darwin (MacOS/X) kernels
 

-Darwin does not come with a tunnel driver. You must download it at
-@uref{http://chrisp.de/en/projects/tunnel.html}. If compiling the source fails,
-try the binary module. The tunnel driver must be loaded before starting tinc
-with the following command:
+Tinc on Darwin relies on a tunnel driver for its data acquisition from the kernel.
+Tinc supports either the driver from @uref{http://www-user.rhrk.uni-kl.de/~nissler/tuntap/},
+which supports both tun and tap style devices,
+and also the driver from from @uref{http://chrisp.de/en/projects/tunnel.html}.
+The former driver is recommended.
+The tunnel driver must be loaded before starting tinc with the following command:

 
 @example
 kmodload tunnel
 @end example
 
 
 @example
 kmodload tunnel
 @end example
 

-Once loaded, the tunnel driver will automatically create @file{/dev/tun0}..@file{/dev/tun3}
-and the corresponding network interfaces.
-

 
 @c ==================================================================
 @node       Configuration of Windows
 
 @c ==================================================================
 @node       Configuration of Windows


@@ -930,15 +841,6 @@ variable.
 
 This option may not work on all platforms.
 
 
 This option may not work on all platforms.
 

-@cindex BlockingTCP
-@item BlockingTCP = <yes|no> (no) [experimental]
-This options selects whether TCP connections, when established, should use blocking writes.
-When turned off, tinc will never block when a TCP connection becomes congested,
-but will have to terminate that connection instead.
-If turned on, tinc will not terminate connections but will block,
-thereby unable to process data to/from other connections.
-Turn this option on if you also use TCPOnly and tinc terminates connections frequently.
-

 @cindex ConnectTo
 @item ConnectTo = <@var{name}>
 Specifies which other tinc daemon to connect to on startup.
 @cindex ConnectTo
 @item ConnectTo = <@var{name}>
 Specifies which other tinc daemon to connect to on startup.


@@ -960,6 +862,16 @@ Under Windows, use @var{Interface} instead of @var{Device}.
 Note that you can only use one device per daemon.
 See also @ref{Device files}.
 
 Note that you can only use one device per daemon.
 See also @ref{Device files}.
 

+@cindex GraphDumpFile
+@item GraphDumpFile = <@var{filename}> [experimental]
+If this option is present,
+tinc will dump the current network graph to the file @var{filename}
+every minute, unless there were no changes to the graph.
+The file is in a format that can be read by graphviz tools.
+If @var{filename} starts with a pipe symbol |,
+then the rest of the filename is interpreted as a shell command
+that is executed, the graph is then sent to stdin.
+

 @cindex Hostnames
 @item Hostnames = <yes|no> (no)
 This option selects whether IP addresses (both real and on the VPN)
 @cindex Hostnames
 @item Hostnames = <yes|no> (no)
 This option selects whether IP addresses (both real and on the VPN)


@@ -1022,12 +934,16 @@ This only has effect when Mode is set to "switch".
 @item Name = <@var{name}> [required]
 This is a symbolic name for this connection.  It can be anything
 
 @item Name = <@var{name}> [required]
 This is a symbolic name for this connection.  It can be anything
 

-@cindex PingTimeout
-@item PingTimeout = <@var{seconds}> (60)
+@cindex PingInterval
+@item PingInterval = <@var{seconds}> (60)

 The number of seconds of inactivity that tinc will wait before sending a
 The number of seconds of inactivity that tinc will wait before sending a

-probe to the other end.  If that other end doesn't answer within that
-same amount of seconds, the connection is terminated, and the others
-will be notified of this.
+probe to the other end.
+
+@cindex PingTimeout
+@item PingTimeout = <@var{seconds}> (5)
+The number of seconds to wait for a response to pings or to allow meta
+connections to block. If the other end doesn't respond within this time,
+the connection is terminated, and the others will be notified of this.

 
 @cindex PriorityInheritance
 @item PriorityInheritance = <yes|no> (no) [experimental]
 
 @cindex PriorityInheritance
 @item PriorityInheritance = <yes|no> (no) [experimental]


@@ -1189,6 +1105,19 @@ This script is started when the tinc daemon with name @var{host} becomes reachab
 
 @item @value{sysconfdir}/tinc/@var{netname}/hosts/@var{host}-down
 This script is started when the tinc daemon with name @var{host} becomes unreachable.
 
 @item @value{sysconfdir}/tinc/@var{netname}/hosts/@var{host}-down
 This script is started when the tinc daemon with name @var{host} becomes unreachable.

+
+@item @value{sysconfdir}/tinc/@var{netname}/host-up
+This script is started when any host becomes reachable.
+
+@item @value{sysconfdir}/tinc/@var{netname}/host-down
+This script is started when any host becomes unreachable.
+
+@item @value{sysconfdir}/tinc/@var{netname}/subnet-up
+This script is started when a Subnet becomes reachable.
+The Subnet and the node it belongs to are passed in environment variables.
+
+@item @value{sysconfdir}/tinc/@var{netname}/subnet-down
+This script is started when a Subnet becomes unreachable.

 @end table
 
 @cindex environment variables
 @end table
 
 @cindex environment variables


@@ -1218,6 +1147,7 @@ This should be used for commands like ifconfig.
 @cindex NODE
 @item NODE
 When a host becomes (un)reachable, this is set to its name.
 @cindex NODE
 @item NODE
 When a host becomes (un)reachable, this is set to its name.

+If a subnet becomes (un)reachable, this is set to the owner of that subnet.

 
 @cindex REMOTEADDRESS
 @item REMOTEADDRESS
 
 @cindex REMOTEADDRESS
 @item REMOTEADDRESS


@@ -1227,6 +1157,11 @@ When a host becomes (un)reachable, this is set to its real address.
 @item REMOTEPORT
 When a host becomes (un)reachable,
 this is set to the port number it uses for communication with other tinc daemons.
 @item REMOTEPORT
 When a host becomes (un)reachable,
 this is set to the port number it uses for communication with other tinc daemons.

+
+@cindex SUBNET
+@item SUBNET
+When a subnet becomes (un)reachable, this is set to the subnet.
+

 @end table
 
 
 @end table