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$
@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-2007 Ivo Timmermans,
+Guus Sliepen <guus@@tinc-vpn.org> and
Wessel Dankers <wsl@@tinc-vpn.org>.
$Id$
* Installation::
* Configuration::
* Running tinc::
+* Controlling tinc::
* Technical information::
* Platform specific information::
* About us::
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
@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::
@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
@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
@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 ==================================================================
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 ==================================================================
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
@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
-Once loaded, the tunnel driver will automatically create @file{/dev/tun0}..@file{/dev/tun3}
-and the corresponding network interfaces.
-
@c ==================================================================
@node Configuration of Windows
* OpenSSL::
* zlib::
* lzo::
+* libevent::
@end menu
default).
+@c ==================================================================
+@node libevent
+@subsection libevent
+
+@cindex libevent
+For the main event loop, tinc uses the libevent library.
+
+If this library is not installed, you wil get an error when configuring
+tinc for build.
+
+You can use your operating system's package manager to install this if
+available. Make sure you install the development AND runtime versions
+of this package.
+
+If you have to install libevent manually, you can get the source code
+from @url{http://monkey.org/~provos/libevent/}. Instructions on how to configure,
+build and install this package are included within the package. Please
+make sure you build development and runtime libraries (which is the
+default).
+
+
@c
@c
@c
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.
@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
-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 PrivateKeyFile
@item PrivateKeyFile = <@var{path}> (@file{@value{sysconfdir}/tinc/@var{netname}/rsa_key.priv})
This is the full path name of the RSA private key file that was
-generated by @samp{tincd --generate-keys}. It must be a full path, not a
+generated by @samp{tincctl generate-keys}. It must be a full path, not a
relative directory.
Note that there must be exactly one of PrivateKey
@cindex PublicKeyFile
@item PublicKeyFile = <@var{path}> [obsolete]
This is the full path name of the RSA public key file that was generated
-by @samp{tincd --generate-keys}. It must be a full path, not a relative
+by @samp{tincctl generate-keys}. It must be a full path, not a relative
directory.
@cindex PEM format
@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
@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
@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
you can easily create a public/private keypair by entering the following command:
@example
-tincd -n @var{netname} -K
+tincctl -n @var{netname} generate-keys
@end example
Tinc will generate a public and a private key and ask you where to put them.
A, B, C and D all have generated a public/private keypair with the following command:
@example
-tincd -n company -K
+tincctl -n company generate-keys
@end example
The private key is stored in @file{@value{sysconfdir}/tinc/company/rsa_key.priv},
Set debug level to @var{level}. The higher the debug level, the more gets
logged. Everything goes via syslog.
-@item -k, --kill[=@var{signal}]
-Attempt to kill a running tincd (optionally with the specified @var{signal} instead of SIGTERM) and exit.
-Use it in conjunction with the -n option to make sure you kill the right tinc daemon.
-Under native Windows the optional argument is ignored,
-the service will always be stopped and removed.
-
@item -n, --net=@var{netname}
Use configuration for net @var{netname}. @xref{Multiple networks}.
-@item -K, --generate-keys[=@var{bits}]
-Generate public/private keypair of @var{bits} length. If @var{bits} is not specified,
-1024 is the default. tinc will ask where you want to store the files,
-but will default to the configuration directory (you can use the -c or -n option
-in combination with -K). After that, tinc will quit.
+@item --controlsocket=@var{filename}
+Open control socket at @var{filename}. If unspecified, the default is
+@file{@value{localstatedir}/run/tinc.@var{netname}.control}.
@item -L, --mlock
Lock tinc into main memory.
Write log entries to a file instead of to the system logging facility.
If @var{file} is omitted, the default is @file{@value{localstatedir}/log/tinc.@var{netname}.log}.
-@item --pidfile=@var{file}
-Write PID to @var{file} instead of @file{@value{localstatedir}/run/tinc.@var{netname}.pid}.
-
@item --bypass-security
Disables encryption and authentication.
Only useful for debugging.
Temporarily increases debug level to 5.
Send this signal again to revert to the original level.
-@item USR1
-Dumps the connection list to syslog.
-
-@item USR2
-Dumps virtual network device statistics, all known nodes, edges and subnets to syslog.
-
-@item WINCH
-Purges all information remembered about unreachable nodes.
-
@end table
@c ==================================================================
@item The output of any command that fails to work as it should (like ping or traceroute).
@end itemize
+@c ==================================================================
+@node Controlling tinc
+@chapter Controlling tinc
+
+You can control and inspect a running @samp{tincd} through the @samp{tincctl}
+command. A quick example:
+
+@example
+tincctl -n @var{netname} reload
+@end example
+
+@menu
+* tincctl runtime options::
+* tincctl commands::
+@end menu
+
+
+@c ==================================================================
+@node tincctl runtime options
+@section tincctl runtime options
+
+@c from the manpage
+@table @option
+@item -c, --config=@var{path}
+Read configuration options from the directory @var{path}. The default is
+@file{@value{sysconfdir}/tinc/@var{netname}/}.
+
+@item -n, --net=@var{netname}
+Use configuration for net @var{netname}. @xref{Multiple networks}.
+
+@item --controlsocket=@var{filename}
+Open control socket at @var{filename}. If unspecified, the default is
+@file{@value{localstatedir}/run/tinc.@var{netname}.control}.
+
+@item --help
+Display a short reminder of runtime options and commands, then terminate.
+
+@item --version
+Output version information and exit.
+
+@end table
+
+
+@c ==================================================================
+@node tincctl commands
+@section tincctl commands
+
+@c from the manpage
+@table @code
+
+@item start
+Start @samp{tincd}.
+
+@item stop
+Stop @samp{tincd}.
+
+@item restart
+Restart @samp{tincd}.
+
+@item reload
+Partially rereads configuration files. Connections to hosts whose host
+config files are removed are closed. New outgoing connections specified
+in @file{tinc.conf} will be made.
+
+@item pid
+Shows the PID of the currently running @samp{tincd}.
+
+@item generate-keys [@var{bits}]
+Generate public/private keypair of @var{bits} length. If @var{bits} is not specified,
+1024 is the default. tinc will ask where you want to store the files,
+but will default to the configuration directory (you can use the -c or -n
+option).
+
+@item dump nodes
+Dump a list of all known nodes in the VPN.
+
+@item dump edges
+Dump a list of all known connections in the VPN.
+
+@item dump subnets
+Dump a list of all known subnets in the VPN.
+
+@item dump connections
+Dump a list of all meta connections with ourself.
+
+@item dump graph
+Dump a graph of the VPN in dotty format.
+
+@item purge
+Purges all information remembered about unreachable nodes.
+
+@end table
+
+
@c ==================================================================
@node Technical information
@chapter Technical information
projects / tinc / blobdiff