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-2009 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-2009 Ivo Timmermans,
+Guus Sliepen <guus@@tinc-vpn.org> and
Wessel Dankers <wsl@@tinc-vpn.org>.
$Id$
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.
-
-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 does 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).
-
-IPv6 packets cannot be tunneled on Solaris.
-
-@c ==================================================================
-@subsection Darwin (MacOS/X)
-
-@cindex Darwin
-@cindex MacOS/X
-Tinc on Darwin relies on the tunnel driver for its data
-acquisition from the kernel. This driver is not part of Darwin but can be
-downloaded from @uref{http://chrisp.de/en/projects/tunnel.html}.
-
-IPv6 packets cannot be tunneled on Darwin.
-
-@c ==================================================================
-@subsection Windows
-
-@cindex Windows
-Tinc on Windows, in a Cygwin environment, relies on the CIPE driver or the TAP-Win32 driver for its data
-acquisition from the kernel. This driver is not part of Windows but can be
-downloaded from @uref{http://cipe-win32.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::
+* Configuration of Linux kernels::
* Configuration of FreeBSD kernels::
* Configuration of OpenBSD kernels::
* Configuration of NetBSD kernels::
@c ==================================================================
-@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:
-
-@example
-Code maturity level options
-[*] Prompt for development and/or incomplete code/drivers
-Networking options
-[*] Kernel/User netlink socket
-<M> Netlink device emulation
-Network device support
-<M> Ethertap network tap
-@end example
-
-If you want to run more than one instance of tinc or other programs that use
-the ethertap, you have to compile the ethertap driver as a module, otherwise
-you can also choose to compile it directly into the kernel.
-
-If you decide to build any of these as dynamic kernel modules, it's a good idea
-to add these lines to @file{/etc/modules.conf}:
-
-@example
-alias char-major-36 netlink_dev
-alias tap0 ethertap
-options tap0 -o tap0 unit=0
-alias tap1 ethertap
-options tap1 -o tap1 unit=1
-...
-alias tap@emph{N} ethertap
-options tap@emph{N} -o tap@emph{N} unit=@emph{N}
-@end example
-
-Add as much alias/options lines as necessary.
-
-
-@c ==================================================================
-@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
+@subsection Configuration of Linux kernels
+@cindex Universal tun/tap
+For tinc to work, 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
It's not necessary to compile this driver as a module, even if you are going to
run more than one instance of tinc.
-If you have an early 2.4 kernel, you can choose both the tun/tap driver and the
-`Ethertap network tap' device. This latter is marked obsolete, and chances are
-that it won't even function correctly anymore. Make sure you select the
-universal tun/tap driver.
-
If you decide to build the tun/tap driver as a kernel module, add these lines
to @file{/etc/modules.conf}:
@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 which should work with tinc,
+but with recent versions of OpenBSD,
+a tun device can act as a tap device by setting the link0 option with ifconfig.
@c ==================================================================
@node Configuration of NetBSD kernels
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
@subsection Configuration of Windows
-You will need to install the CIPE-Win32 driver or the TAP-Win32 driver, it
-doesn't matter which one. You can download the CIPE driver from
-@uref{http://cipe-win32.sourceforge.net}. Using the Network Connections
-control panel, configure the CIPE-Win32 or TAP-Win32 network interface in the same way as you would
-do from the tinc-up script as explained in the rest of the documentation.
+You will need to install the latest TAP-Win32 driver from OpenVPN.
+You can download it from @uref{http://openvpn.sourceforge.net}.
+Using the Network Connections control panel,
+configure the TAP-Win32 network interface in the same way as you would do from the tinc-up script,
+as explained in the rest of the documentation.
@c ==================================================================
@subsection Device files
@cindex device files
-First, you'll need the special device file(s) that form the interface
-between the kernel and the daemon.
+Most operating systems nowadays come with the necessary device files by default,
+or they have a mechanism to create them on demand.
-The permissions for these files have to be such that only the super user
-may read/write to this file. You'd want this, because otherwise
-eavesdropping would become a bit too easy. This does, however, imply
-that you'd have to run tincd as root.
-
-If you use Linux and have a kernel version prior to 2.4.0, you have to make the
-ethertap devices:
-
-@example
-mknod -m 600 /dev/tap0 c 36 16
-mknod -m 600 /dev/tap1 c 36 17
-...
-mknod -m 600 /dev/tap@emph{N} c 36 @emph{N+16}
-@end example
-
-There is a maximum of 16 ethertap devices.
-
-If you use the universal tun/tap driver, you have to create the
-following device file (unless it already exist):
+If you use Linux and do not have udev installed,
+you may need to create the following device file if it does not exist:
@example
-mknod -m 600 /dev/tun c 10 200
+mknod -m 600 /dev/net/tun c 10 200
@end example
-If you use Linux, and you run the new 2.4 kernel using the devfs filesystem,
-then the tun/tap device will probably be automatically generated as
-@file{/dev/net/tun}.
-
-Unlike the ethertap device, you do not need multiple device files if
-you are planning to run multiple tinc daemons.
-
@c ==================================================================
@node Other files
Note that you can only use one device per daemon.
See also @ref{Device files}.
+@cindex DeviceType
+@item DeviceType = <tun|tunnohead|tunifhead|tap> (only supported on BSD platforms)
+The type of the virtual network device.
+Tinc will normally automatically select the right type, and this option should not be used.
+However, in case tinc does not seem to correctly interpret packets received from the virtual network device,
+using this option might help.
+
+@table @asis
+@item tun
+Set type to tun.
+Depending on the platform, this can either be with or without an address family header (see below).
+
+@cindex tunnohead
+@item tunnohead
+Set type to tun without an address family header.
+Tinc will expect packets read from the virtual network device to start with an IP header.
+On some platforms IPv6 packets cannot be read from or written to the device in this mode.
+
+@cindex tunifhead
+@item tunifhead
+Set type to tun with an address family header.
+Tinc will expect packets read from the virtual network device
+to start with a four byte header containing the address family,
+followed by an IP header.
+This mode should support both IPv4 and IPv6 packets.
+
+@item tap
+Set type to tap.
+Tinc will expect packets read from the virtual network device
+to start with an Ethernet header.
+@end table
+
+@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 Name
@item Name = <@var{name}> [required]
-This is a symbolic name for this connection. It can be anything
+This is a symbolic name for this connection.
+The name should consist only of alfanumeric and underscore characters (a-z, A-Z, 0-9 and _).
-@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]
or PrivateKeyFile
specified in the configuration file.
+@cindex TunnelServer
+@item TunnelServer = <yes|no> (no) [experimental]
+When this option is enabled tinc will no longer forward information between other tinc daemons,
+and will only allow nodes and subnets on the VPN which are present in the
+@file{@value{sysconfdir}/tinc/@var{netname}/hosts/} directory.
+
@end table
Can be anything from 0
up to the length of the digest produced by the digest algorithm.
+@cindex PMTU
+@item PMTU = <@var{mtu}> (1514)
+This option controls the initial path MTU to this node.
+
+@cindex PMTUDiscovery
+@item PMTUDiscovery = <yes|no> (yes)
+When this option is enabled, tinc will try to discover the path MTU to this node.
+After the path MTU has been discovered, it will be enforced on the VPN.
+
@cindex Port
@item Port = <@var{port}> (655)
This is the port this tinc daemon listens on.
connection with that host.
@cindex Subnet
-@item Subnet = <@var{address}[/@var{prefixlength}]>
+@item Subnet = <@var{address}[/@var{prefixlength}[#@var{weight}]]>
The subnet which this tinc daemon will serve.
Tinc tries to look up which other daemon it should send a packet to by searching the appropiate subnet.
If the packet matches a subnet,
MAC addresses are notated like 0:1a:2b:3c:4d:5e.
@cindex CIDR notation
-prefixlength is the number of bits set to 1 in the netmask part; for
+Prefixlength is the number of bits set to 1 in the netmask part; for
example: netmask 255.255.255.0 would become /24, 255.255.252.0 becomes
/22. This conforms to standard CIDR notation as described in
@uref{ftp://ftp.isi.edu/in-notes/rfc1519.txt, RFC1519}
+A Subnet can be given a weight to indicate its priority over identical Subnets
+owned by different nodes. The default weight is 10. Lower values indicate
+higher priority. Packets will be sent to the node with the highest priority,
+unless that node is not reachable, in which case the node with the next highest
+priority will be tried, and so on.
+
@cindex TCPonly
-@item TCPonly = <yes|no> (no) [experimental]
+@item TCPonly = <yes|no> (no)
If this variable is set to yes, then the packets are tunnelled over a
TCP connection instead of a UDP connection. This is especially useful
for those who want to run a tinc daemon from behind a masquerading
@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
@example
Name = BranchA
-PrivateKeyFile = @value{sysconfdir}/tinc/company/rsa_key.priv
Device = /dev/tap0
@end example
@example
Name = BranchB
ConnectTo = BranchA
-PrivateKeyFile = @value{sysconfdir}/tinc/company/rsa_key.priv
@end example
Note here that the internal address (on eth0) doesn't have to be the
Name = BranchD
ConnectTo = BranchC
Device = /dev/net/tun
-PrivateKeyFile = @value{sysconfdir}/tinc/company/rsa_key.priv
@end example
D will be connecting to C, which has a tincd running for this network on
@menu
* Runtime options::
+* Signals::
+* Debug levels::
* Solving problems::
* Error messages::
* Sending bug reports::
Disables encryption and authentication.
Only useful for debugging.
+@item -R, --chroot
+Change process root directory to the directory where the config file is
+located (@file{@value{sysconfdir}/tinc/@var{netname}/} as determined by
+-n/--net option or as given by -c/--config option), for added security.
+The chroot is performed after all the initialization is done, after
+writing pid files and opening network sockets.
+
+Note that this option alone does not do any good without -U/--user, below.
+
+Note also that tinc can't run scripts anymore (such as tinc-down or host-up),
+unless it's setup to be runnable inside chroot environment.
+
+@item -U, --user=@var{user}
+Switch to the given @var{user} after initialization, at the same time as
+chroot is performed (see --chroot above). With this option tinc drops
+privileges, for added security.
+
@item --help
Display a short reminder of these runtime options and terminate.
@end table
+@c ==================================================================
+@node Signals
+@section Signals
+
+@cindex signals
+You can also send the following signals to a running tincd process:
+
+@c from the manpage
+@table @samp
+
+@item ALRM
+Forces tinc to try to connect to all uplinks immediately.
+Usually tinc attempts to do this itself,
+but increases the time it waits between the attempts each time it failed,
+and if tinc didn't succeed to connect to an uplink the first time after it started,
+it defaults to the maximum time of 15 minutes.
+
+@item HUP
+Partially rereads configuration files.
+Connections to hosts whose host config file are removed are closed.
+New outgoing connections specified in @file{tinc.conf} will be made.
+
+@item INT
+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 ==================================================================
+@node Debug levels
+@section Debug levels
+
+@cindex debug levels
+The tinc daemon can send a lot of messages to the syslog.
+The higher the debug level, the more messages it will log.
+Each level inherits all messages of the previous level:
+
+@c from the manpage
+@table @samp
+
+@item 0
+This will log a message indicating tinc has started along with a version number.
+It will also log any serious error.
+
+@item 1
+This will log all connections that are made with other tinc daemons.
+
+@item 2
+This will log status and error messages from scripts and other tinc daemons.
+
+@item 3
+This will log all requests that are exchanged with other tinc daemons. These include
+authentication, key exchange and connection list updates.
+
+@item 4
+This will log a copy of everything received on the meta socket.
+
+@item 5
+This will log all network traffic over the virtual private network.
+
+@end table
+
@c ==================================================================
@node Solving problems
@section Solving problems
@cindex ADD_EDGE
@cindex ADD_SUBNET
@example
-daemon message
---------------------------------------------------------------------------
-origin ADD_EDGE node1 node2 21.32.43.54 655 222 0
- | | | | | +-> options
- | | | | +----> weight
- | | | +--------> UDP port of node2
- | | +----------------> real address of node2
- | +-------------------------> name of destination node
- +-------------------------------> name of source node
-
-origin ADD_SUBNET node 192.168.1.0/24
- | | +--> prefixlength
- | +--------> network address
- +------------------> owner of this subnet
---------------------------------------------------------------------------
+message
+------------------------------------------------------------------
+ADD_EDGE node1 node2 21.32.43.54 655 222 0
+ | | | | | +-> options
+ | | | | +----> weight
+ | | | +--------> UDP port of node2
+ | | +----------------> real address of node2
+ | +-------------------------> name of destination node
+ +-------------------------------> name of source node
+
+ADD_SUBNET node 192.168.1.0/24
+ | | +--> prefixlength
+ | +--------> network address
+ +------------------> owner of this subnet
+------------------------------------------------------------------
@end example
The ADD_EDGE messages are to inform other tinc daemons that a connection between
message
------------------------------------------------------------------
DEL_EDGE node1 node2
- | +----> name of destination node
+ | +----> name of destination node
+----------> name of source node
DEL_SUBNET node 192.168.1.0/24
KEY_CHANGED origin
+--> daemon that has changed it's packet key
---------------------------------------------------------------------------
+------------------------------------------------------------------
@end example
The keys used to encrypt VPN packets are not sent out directly. This is
@cindex PONG
@example
daemon message
---------------------------------------------------------------------------
+------------------------------------------------------------------
origin PING
dest. PONG
---------------------------------------------------------------------------
+------------------------------------------------------------------
@end example
There is also a mechanism to check if hosts are still alive. Since network
@item NetBSD
@tab @code{ifconfig} @var{interface} @code{inet6} @var{address} @code{prefixlen} @var{prefixlength}
@item Solaris
-@tab @code{ifconfig} @var{interface} @code{inet6 addif} @var{address}@code{/}@var{prefixlength}
+@tab @code{ifconfig} @var{interface} @code{inet6 plumb up}
+@item
+@tab @code{ifconfig} @var{interface} @code{inet6 addif} @var{address} @var{address}
@item Darwin (MacOS/X)
@tab @code{ifconfig} @var{interface} @code{inet6} @var{address} @code{prefixlen} @var{prefixlength}
@item Windows
@item NetBSD
@tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @var{local_address}
@item Solaris
+@tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @var{local_address} @code{-interface}
@item Darwin (MacOS/X)
@tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @var{local_address}
@item Windows
+@tab @code{netsh routing ip add persistentroute} @var{network_address} @var{netmask} @var{interface} @var{local_address}
@end multitable
Adding routes to IPv6 subnets:
@tab @code{route add -A inet6} @var{network_address}@code{/}@var{prefixlength} @var{interface}
@item Linux iproute2
@tab @code{ip route add} @var{network_address}@code{/}@var{prefixlength} @code{dev} @var{interface}
+@item FreeBSD
+@tab @code{route add -inet6} @var{network_address}@code{/}@var{prefixlength} @var{local_address}
@item OpenBSD
+@tab @code{route add -inet6} @var{network_address} @var{local_address} @code{-prefixlen} @var{prefixlength}
@item NetBSD
+@tab @code{route add -inet6} @var{network_address} @var{local_address} @code{-prefixlen} @var{prefixlength}
@item Solaris
+@tab @code{route add -inet6} @var{network_address}@code{/}@var{prefixlength} @var{local_address} @code{-interface}
@item Darwin (MacOS/X)
+@tab ?
@item Windows
@tab @code{netsh interface ipv6 add route} @var{network address}/@var{prefixlength} @var{interface}
@end multitable
projects / tinc / blobdiff