This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
-Copyright @copyright{} 1998-2012 Ivo Timmermans,
+Copyright @copyright{} 1998-2014 Ivo Timmermans,
Guus Sliepen <guus@@tinc-vpn.org> and
Wessel Dankers <wsl@@tinc-vpn.org>.
@vskip 0pt plus 1filll
This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
-Copyright @copyright{} 1998-2012 Ivo Timmermans,
+Copyright @copyright{} 1998-2014 Ivo Timmermans,
Guus Sliepen <guus@@tinc-vpn.org> and
Wessel Dankers <wsl@@tinc-vpn.org>.
@section Supported platforms
@cindex platforms
-Tinc has been verified to work under Linux, FreeBSD, OpenBSD, NetBSD, MacOS/X (Darwin), Solaris, and Windows (both natively and in a Cygwin environment),
+Tinc has been verified to work under Linux, FreeBSD, OpenBSD, NetBSD, Mac OS X (Darwin), Solaris, and Windows (both natively and in a Cygwin environment),
with various hardware architectures. These are some of the platforms
that are supported by the universal tun/tap device driver or other virtual network device drivers.
Without such a driver, tinc will most
@cindex release
For an up to date list of supported platforms, please check the list on
our website:
-@uref{http://www.tinc-vpn.org/platforms}.
+@uref{http://www.tinc-vpn.org/platforms/}.
@c
@c
* Configuration of OpenBSD kernels::
* Configuration of NetBSD kernels::
* Configuration of Solaris kernels::
-* Configuration of Darwin (MacOS/X) kernels::
+* Configuration of Darwin (Mac OS X) kernels::
* Configuration of Windows::
@end menu
@subsection Configuration of FreeBSD kernels
For FreeBSD version 4.1 and higher, tun and tap drivers are included in the default kernel configuration.
-Using tap devices is recommended.
+The tap driver can be loaded with @code{kldload if_tap}, or by adding @code{if_tap_load="YES"} to @file{/boot/loader.conf}.
@c ==================================================================
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
@subsection Configuration of NetBSD kernels
@c ==================================================================
-@node Configuration of Darwin (MacOS/X) kernels
-@subsection Configuration of Darwin (MacOS/X) kernels
+@node Configuration of Darwin (Mac OS X) kernels
+@subsection Configuration of Darwin (Mac OS X) kernels
Tinc on Darwin relies on a tunnel driver for its data acquisition from the kernel.
Tinc supports either the driver from @uref{http://tuntaposx.sourceforge.net/},
-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
+which supports both tun and tap style devices.
@c ==================================================================
For all cryptography-related functions, tinc uses the functions provided
by the OpenSSL library.
-If this library is not installed, you wil get an error when configuring
-tinc for build. Support for running tinc without having OpenSSL
+If this library is not installed, you will get an error when configuring
+tinc for build. Support for running tinc with other cryptographic libraries
installed @emph{may} be added in the future.
You can use your operating system's package manager to install this if
For the optional compression of UDP packets, tinc uses the functions provided
by the zlib library.
-If this library is not installed, you wil get an error when configuring
-tinc for build. Support for running tinc without having zlib
-installed @emph{may} be added in the future.
+If this library is not installed, you will get an error when running the
+configure script. You can either install the zlib library, or disable support
+for zlib compression by using the "--disable-zlib" option when running the
+configure script. Note that if you disable support for zlib, the resulting
+binary will not work correctly on VPNs where zlib compression is used.
You can use your operating system's package manager to install this if
available. Make sure you install the development AND runtime versions
@subsection lzo
@cindex lzo
-Another form of compression is offered using the lzo library.
+Another form of compression is offered using the LZO library.
-If this library is not installed, you wil get an error when configuring
-tinc for build. Support for running tinc without having lzo
-installed @emph{may} be added in the future.
+If this library is not installed, you will get an error when running the
+configure script. You can either install the LZO library, or disable support
+for LZO compression by using the "--disable-lzo" option when running the
+configure script. Note that if you disable support for LZO, the resulting
+binary will not work correctly on VPNs where LZO compression is used.
You can use your operating system's package manager to install this if
available. Make sure you install the development AND runtime versions
If you cannot use one of the precompiled packages, or you want to compile tinc
for yourself, you can use the source. The source is distributed under
the GNU General Public License (GPL). Download the source from the
-@uref{http://www.tinc-vpn.org/download, download page}, which has
+@uref{http://www.tinc-vpn.org/download/, download page}, which has
the checksums of these files listed; you may wish to check these with
md5sum before continuing.
The documentation that comes along with your distribution will tell you how to do that.
@menu
-* Darwin (MacOS/X) build environment::
+* Darwin (Mac OS X) build environment::
* Cygwin (Windows) build environment::
* MinGW (Windows) build environment::
@end menu
@c ==================================================================
-@node Darwin (MacOS/X) build environment
-@subsection Darwin (MacOS/X) build environment
+@node Darwin (Mac OS X) build environment
+@subsection Darwin (Mac OS X) build environment
-In order to build tinc on Darwin, you need to install the MacOS/X Developer Tools
+In order to build tinc on Darwin, you need to install the Mac OS X Developer Tools
from @uref{http://developer.apple.com/tools/macosxtools.html} and
-a recent version of Fink from @uref{http://fink.sourceforge.net/}.
+preferably a recent version of Fink from @uref{http://www.finkproject.org/}.
After installation use fink to download and install the following packages:
autoconf25, automake, dlcompat, m4, openssl, zlib and lzo.
Make sure you have an adequate understanding of networks in general.
@cindex Network Administrators Guide
A good resource on networking is the
-@uref{http://www.linuxdoc.org/LDP/nag2/, Linux Network Administrators Guide}.
+@uref{http://www.tldp.org/LDP/nag2/, Linux Network Administrators Guide}.
If you have everything clearly pictured in your mind,
proceed in the following order:
it doesn't even have to be the same on all the sites of your VPN,
but it is recommended that you choose one anyway.
-We will asume you use a netname throughout this document.
+We will assume you use a netname throughout this document.
This means that you call tincd with the -n argument,
which will assign a netname to this daemon.
If it sees one or more `ConnectTo' values pointing to other tinc daemons in that file,
it will try to connect to those other daemons.
Whether this succeeds or not and whether `ConnectTo' is specified or not,
-tinc will listen for incoming connection from other deamons.
+tinc will listen for incoming connection from other daemons.
If you did specify a `ConnectTo' value and the other side is not responding,
tinc will keep retrying.
This means that once started, tinc will stay running until you tell it to stop,
@file{@value{sysconfdir}/tinc/@var{netname}/tinc.conf} and at least one other file in the directory
@file{@value{sysconfdir}/tinc/@var{netname}/hosts/}.
+An optional directory @file{@value{sysconfdir}/tinc/@var{netname}/conf.d} can be added from which
+any .conf file will be read.
+
These file consists of comments (lines started with a #) or assignments
in the form of
This option may not work on all platforms.
@cindex Broadcast
-@item Broadcast = <yes | no> (yes) [experimental]
-When disabled, tinc will drop all broadcast and multicast packets, in both router and switch mode.
+@item Broadcast = <no | mst | direct> (mst) [experimental]
+This option selects the way broadcast packets are sent to other daemons.
+@emph{NOTE: all nodes in a VPN must use the same Broadcast mode, otherwise routing loops can form.}
+
+@table @asis
+@item no
+Broadcast packets are never sent to other nodes.
+
+@item mst
+Broadcast packets are sent and forwarded via the VPN's Minimum Spanning Tree.
+This ensures broadcast packets reach all nodes.
+
+@item direct
+Broadcast packets are sent directly to all nodes that can be reached directly.
+Broadcast packets received from other nodes are never forwarded.
+If the IndirectData option is also set, broadcast packets will only be sent to nodes which we have a meta connection to.
+@end table
@cindex ConnectTo
@item ConnectTo = <@var{name}>
@item Device = <@var{device}> (@file{/dev/tap0}, @file{/dev/net/tun} or other depending on platform)
The virtual network device to use.
Tinc will automatically detect what kind of device it is.
-Note that you can only use one device per daemon.
Under Windows, use @var{Interface} instead of @var{Device}.
Note that you can only use one device per daemon.
See also @ref{Device files}.
@item Hostnames = <yes|no> (no)
This option selects whether IP addresses (both real and on the VPN)
should be resolved. Since DNS lookups are blocking, it might affect
-tinc's efficiency, even stopping the daemon for a few seconds everytime
+tinc's efficiency, even stopping the daemon for a few seconds every time
it does a lookup if your DNS server is not responding.
This does not affect resolving hostnames to IP addresses from the
-configuration file.
+configuration file, but whether hostnames should be resolved while logging.
+
+@cindex IffOneQueue
+@item IffOneQueue = <yes|no> (no) [experimental]
+(Linux only) Set IFF_ONE_QUEUE flag on TUN/TAP devices.
@cindex Interface
@item Interface = <@var{interface}>
Under Windows, this variable is used to select which network interface will be used.
If you specified a Device, this variable is almost always already correctly set.
+@cindex KeyExpire
+@item KeyExpire = <@var{seconds}> (3600)
+This option controls the time the encryption keys used to encrypt the data
+are valid. It is common practice to change keys at regular intervals to
+make it even harder for crackers, even though it is thought to be nearly
+impossible to crack a single key.
+
@cindex LocalDiscovery
@item LocalDiscovery = <yes | no> (no) [experimental]
When enabled, tinc will try to detect peers that are on the same local network.
Currently, local discovery is implemented by sending broadcast packets to the LAN during path MTU discovery.
This feature may not work in all possible situations.
+@cindex MACExpire
+@item MACExpire = <@var{seconds}> (600)
+This option controls the amount of time MAC addresses are kept before they are removed.
+This only has effect when Mode is set to "switch".
+
+@cindex MaxTimeout
+@item MaxTimeout = <@var{seconds}> (900)
+This is the maximum delay before trying to reconnect to other tinc daemons.
+
@cindex Mode
@item Mode = <router|switch|hub> (router)
This option selects the way packets are routed to other daemons.
while no routing table is managed.
@end table
-@cindex KeyExpire
-@item KeyExpire = <@var{seconds}> (3600)
-This option controls the time the encryption keys used to encrypt the data
-are valid. It is common practice to change keys at regular intervals to
-make it even harder for crackers, even though it is thought to be nearly
-impossible to crack a single key.
-
-@cindex MACExpire
-@item MACExpire = <@var{seconds}> (600)
-This option controls the amount of time MAC addresses are kept before they are removed.
-This only has effect when Mode is set to "switch".
-
@cindex Name
@item Name = <@var{name}> [required]
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 _).
+The name must consist only of alphanumeric and underscore characters (a-z, A-Z, 0-9 and _).
+
+If Name starts with a $, then the contents of the environment variable that follows will be used.
+In that case, invalid characters will be converted to underscores.
+If Name is $HOST, but no such environment variable exist,
+the hostname will be read using the gethostname() system call.
@cindex PingInterval
@item PingInterval = <@var{seconds}> (60)
@item PrivateKey = <@var{key}> [obsolete]
This is the RSA private key for tinc. However, for safety reasons it is
advised to store private keys of any kind in separate files. This prevents
-accidental eavesdropping if you are editting the configuration file.
+accidental eavesdropping if you are editing the configuration file.
@cindex PrivateKeyFile
@item PrivateKeyFile = <@var{path}> (@file{@value{sysconfdir}/tinc/@var{netname}/rsa_key.priv})
generated by @samp{tincd --generate-keys}. It must be a full path, not a
relative directory.
-Note that there must be exactly one of PrivateKey
-or PrivateKeyFile
-specified in the configuration file.
-
@cindex ProcessPriority
@item ProcessPriority = <low|normal|high>
When this option is used the priority of the tincd process will be adjusted.
Increasing the priority may help to reduce latency and packet loss on the VPN.
+@cindex Proxy
+@item Proxy = socks4 | socks5 | http | exec @var{...} [experimental]
+Use a proxy when making outgoing connections.
+The following proxy types are currently supported:
+
+@table @asis
+@cindex socks4
+@item socks4 <@var{address}> <@var{port}> [<@var{username}>]
+Connects to the proxy using the SOCKS version 4 protocol.
+Optionally, a @var{username} can be supplied which will be passed on to the proxy server.
+
+@cindex socks5
+@item socks5 <@var{address}> <@var{port}> [<@var{username}> <@var{password}>]
+Connect to the proxy using the SOCKS version 5 protocol.
+If a @var{username} and @var{password} are given, basic username/password authentication will be used,
+otherwise no authentication will be used.
+
+@cindex http
+@item http <@var{address}> <@var{port}>
+Connects to the proxy and sends a HTTP CONNECT request.
+
+@cindex exec
+@item exec <@var{command}>
+Executes the given command which should set up the outgoing connection.
+The environment variables @env{NAME}, @env{NODE}, @env{REMOTEADDRES} and @env{REMOTEPORT} are available.
+@end table
+
@cindex ReplayWindow
@item ReplayWindow = <bytes> (16)
This is the size of the replay tracking window for each remote node, in bytes.
pass all traffic, but leaves tinc vulnerable to replay-based attacks on your
traffic.
-
@cindex StrictSubnets
-@item StrictSubnets <yes|no> (no) [experimental]
+@item StrictSubnets = <yes|no> (no) [experimental]
When this option is enabled tinc will only use Subnet statements which are
present in the host config files in the local
@file{@value{sysconfdir}/tinc/@var{netname}/hosts/} directory.
+Subnets learned via connections to other nodes and which are not
+present in the local host config files are ignored.
@cindex TunnelServer
@item TunnelServer = <yes|no> (no) [experimental]
must resolve to the external IP address where the host can be reached,
not the one that is internal to the VPN.
If no port is specified, the default Port is used.
+Multiple Address variables can be specified, in which case each address will be
+tried until a working connection has been established.
@cindex Cipher
@item Cipher = <@var{cipher}> (blowfish)
@cindex Subnet
@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.
+Tinc tries to look up which other daemon it should send a packet to by searching the appropriate subnet.
If the packet matches a subnet,
it will be sent to the daemon who has this subnet in his host configuration file.
Multiple subnet lines can be specified for each daemon.
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}
+@uref{http://www.ietf.org/rfc/rfc1519.txt, RFC1519}
@cindex Subnet weight
A Subnet can be given a weight to indicate its priority over identical Subnets
@cindex scripts
Apart from reading the server and host configuration files,
tinc can also run scripts at certain moments.
-Under Windows (not Cygwin), the scripts should have the extension .bat.
+Below is a list of filenames of scripts and a description of when they are run.
+A script is only run if it exists and if it is executable.
+
+Scripts are run synchronously;
+this means that tinc will temporarily stop processing packets until the called script finishes executing.
+This guarantees that scripts will execute in the exact same order as the events that trigger them.
+If you need to run commands asynchronously, you have to ensure yourself that they are being run in the background.
+
+Under Windows (not Cygwin), the scripts must have the extension .bat.
@table @file
@cindex tinc-up
started and has connected to the virtual network device.
It should be used to set up the corresponding network interface,
but can also be used to start other things.
+
Under Windows you can use the Network Connections control panel instead of creating this script.
@cindex tinc-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.
+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.
+This script is started when a subnet becomes unreachable.
@end table
@cindex environment variables
@subsubheading Step 2. Creating your host configuration file
-If you added a line containing `Name = yourname' in the main configuarion file,
+If you added a line containing `Name = yourname' in the main configuration file,
you will need to create a host configuration file @file{@value{sysconfdir}/tinc/@var{netname}/hosts/yourname}.
Adapt the following example to create a host configuration file:
level of 5 or higher!
@item Chances are that a @samp{Subnet = ...} line in the host configuration file of this tinc daemon is wrong.
Change it to a subnet that is accepted locally by another interface,
-or if that is not the case, try changing the prefix length into /32.
+or if that is not the case, try changing the prefix length into /32.
@end itemize
@item Node foo (1.2.3.4) is not reachable
and `tap' style, which are Ethernet devices and handle complete Ethernet frames.
So when tinc reads an Ethernet frame from the device, it determines its
-type. When tinc is in it's default routing mode, it can handle IPv4 and IPv6
+type. When tinc is in its default routing mode, it can handle IPv4 and IPv6
packets. Depending on the Subnet lines, it will send the packets off to their destination IP address.
In the `switch' and `hub' mode, tinc will use broadcasts and MAC address discovery
to deduce the destination of the packets.
there is no problem for the kernel to accept a packet.
However, if it is a `tap' device (this is the only available type on FreeBSD),
the destination MAC address must match that of the virtual network interface.
-If tinc is in it's default routing mode, ARP does not work, so the correct destination MAC
+If tinc is in its default routing mode, ARP does not work, so the correct destination MAC
can not be known by the sending host.
Tinc solves this by letting the receiving end detect the MAC address of its own virtual network interface
and overwriting the destination MAC address of the received packet.
------------------------------------------------------------------
REQ_KEY origin destination
| +--> name of the tinc daemon it wants the key from
- +----------> name of the daemon that wants the key
+ +----------> name of the daemon that wants the key
ANS_KEY origin destination 4ae0b0a82d6e0078 91 64 4
| | \______________/ | | +--> MAC length
client ACK 655 123 0
| | +-> options
- | +----> estimated weight
- +--------> listening port of client
+ | +----> estimated weight
+ +--------> listening port of client
server ACK 655 321 0
| | +-> options
- | +----> estimated weight
- +--------> listening port of server
+ | +----> estimated weight
+ +--------> listening port of server
--------------------------------------------------------------------------
@end example
For IPv4 addresses:
-@multitable {Darwin (MacOS/X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
+@multitable {Darwin (Mac OS X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
@item Linux
@tab @code{ifconfig} @var{interface} @var{address} @code{netmask} @var{netmask}
@item Linux iproute2
@tab @code{ifconfig} @var{interface} @var{address} @code{netmask} @var{netmask}
@item Solaris
@tab @code{ifconfig} @var{interface} @var{address} @code{netmask} @var{netmask}
-@item Darwin (MacOS/X)
+@item Darwin (Mac OS X)
@tab @code{ifconfig} @var{interface} @var{address} @code{netmask} @var{netmask}
@item Windows
@tab @code{netsh interface ip set address} @var{interface} @code{static} @var{address} @var{netmask}
For IPv6 addresses:
-@multitable {Darwin (MacOS/X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
+@multitable {Darwin (Mac OS X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
@item Linux
@tab @code{ifconfig} @var{interface} @code{add} @var{address}@code{/}@var{prefixlength}
@item FreeBSD
@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)
+@item Darwin (Mac OS X)
@tab @code{ifconfig} @var{interface} @code{inet6} @var{address} @code{prefixlen} @var{prefixlength}
@item Windows
@tab @code{netsh interface ipv6 add address} @var{interface} @code{static} @var{address}/@var{prefixlength}
On some platforms, when running tinc in switch mode, the VPN interface must be set to tap mode with an ifconfig command:
-@multitable {Darwin (MacOS/X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
+@multitable {Darwin (Mac OS X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
@item OpenBSD
@tab @code{ifconfig} @var{interface} @code{link0}
@end multitable
It can be useful to set up a tun/tap interface owned by a non-root user, so
tinc can be started without needing any root privileges at all.
-@multitable {Darwin (MacOS/X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
+@multitable {Darwin (Mac OS X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
@item Linux
@tab @code{ip tuntap add dev} @var{interface} @code{mode} @var{tun|tap} @code{user} @var{username}
@end multitable
Adding routes to IPv4 subnets:
-@multitable {Darwin (MacOS/X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
+@multitable {Darwin (Mac OS X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
@item Linux
@tab @code{route add -net} @var{network_address} @code{netmask} @var{netmask} @var{interface}
@item Linux iproute2
@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 Darwin (Mac OS X)
+@tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @code{-interface} @var{interface}
@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:
-@multitable {Darwin (MacOS/X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
+@multitable {Darwin (Mac OS X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
@item Linux
@tab @code{route add -A inet6} @var{network_address}@code{/}@var{prefixlength} @var{interface}
@item Linux iproute2
@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 Darwin (Mac OS X)
+@tab @code{route add -inet6} @var{network_address}@code{/}@var{prefixlength} @code{-interface} @var{interface}
@item Windows
@tab @code{netsh interface ipv6 add route} @var{network address}/@var{prefixlength} @var{interface}
@end multitable
projects / tinc / blobdiff