--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename tinc.info
+@settitle tinc Manual
+@setchapternewpage odd
+@c %**end of header
+
+@include include.texi
+
+@ifinfo
+@dircategory Networking tools
+@direntry
+* tinc: (tinc). The tinc Manual.
+@end direntry
+
+This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
+
+Copyright @copyright{} 1998-2014 Ivo Timmermans,
+Guus Sliepen <guus@@tinc-vpn.org> and
+Wessel Dankers <wsl@@tinc-vpn.org>.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+@end ifinfo
+
+@afourpaper
+@paragraphindent none
+@finalout
+
+@titlepage
+@title tinc Manual
+@subtitle Setting up a Virtual Private Network with tinc
+@author Ivo Timmermans and Guus Sliepen
+
+@page
+@vskip 0pt plus 1filll
+This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
+
+Copyright @copyright{} 1998-2014 Ivo Timmermans,
+Guus Sliepen <guus@@tinc-vpn.org> and
+Wessel Dankers <wsl@@tinc-vpn.org>.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+@end titlepage
+
+@ifnottex
+@c ==================================================================
+@node Top
+@top Top
+
+@menu
+* Introduction::
+* Preparations::
+* Installation::
+* Configuration::
+* Running tinc::
+* Controlling tinc::
+* Technical information::
+* Platform specific information::
+* About us::
+* Concept Index:: All used terms explained
+@end menu
+@end ifnottex
+
+@c ==================================================================
+@node Introduction
+@chapter Introduction
+
+@cindex tinc
+Tinc is a Virtual Private Network (VPN) daemon that uses tunneling and
+encryption to create a secure private network between hosts on the
+Internet.
+
+Because the tunnel appears to the IP level network code as a normal
+network device, there is no need to adapt any existing software.
+The encrypted tunnels allows VPN sites to share information with each other
+over the Internet without exposing any information to others.
+
+This document is the manual for tinc. Included are chapters on how to
+configure your computer to use tinc, as well as the configuration
+process of tinc itself.
+
+@menu
+* Virtual Private Networks::
+* tinc:: About tinc
+* Supported platforms::
+@end menu
+
+@c ==================================================================
+@node Virtual Private Networks
+@section Virtual Private Networks
+
+@cindex VPN
+A Virtual Private Network or VPN is a network that can only be accessed
+by a few elected computers that participate. This goal is achievable in
+more than just one way.
+
+@cindex private
+Private networks can consist of a single stand-alone Ethernet LAN. Or
+even two computers hooked up using a null-modem cable. In these cases,
+it is
+obvious that the network is @emph{private}, no one can access it from the
+outside. But if your computers are linked to the Internet, the network
+is not private anymore, unless one uses firewalls to block all private
+traffic. But then, there is no way to send private data to trusted
+computers on the other end of the Internet.
+
+@cindex virtual
+This problem can be solved by using @emph{virtual} networks. Virtual
+networks can live on top of other networks, but they use encapsulation to
+keep using their private address space so they do not interfere with
+the Internet. Mostly, virtual networks appear like a single LAN, even though
+they can span the entire world. But virtual networks can't be secured
+by using firewalls, because the traffic that flows through it has to go
+through the Internet, where other people can look at it.
+
+As is the case with either type of VPN, anybody could eavesdrop. Or
+worse, alter data. Hence it's probably advisable to encrypt the data
+that flows over the network.
+
+When one introduces encryption, we can form a true VPN. Other people may
+see encrypted traffic, but if they don't know how to decipher it (they
+need to know the key for that), they cannot read the information that flows
+through the VPN. This is what tinc was made for.
+
+
+@c ==================================================================
+@node tinc
+@section tinc
+
+@cindex vpnd
+I really don't quite remember what got us started, but it must have been
+Guus' idea. He wrote a simple implementation (about 50 lines of C) that
+used the ethertap device that Linux knows of since somewhere
+about kernel 2.1.60. It didn't work immediately and he improved it a
+bit. At this stage, the project was still simply called "vpnd".
+
+Since then, a lot has changed---to say the least.
+
+@cindex tincd
+Tinc now supports encryption, it consists of a single daemon (tincd) for
+both the receiving and sending end, it has become largely
+runtime-configurable---in short, it has become a full-fledged
+professional package.
+
+@cindex traditional VPNs
+@cindex scalability
+Tinc also allows more than two sites to connect to eachother and form a single VPN.
+Traditionally VPNs are created by making tunnels, which only have two endpoints.
+Larger VPNs with more sites are created by adding more tunnels.
+Tinc takes another approach: only endpoints are specified,
+the software itself will take care of creating the tunnels.
+This allows for easier configuration and improved scalability.
+
+A lot can---and will be---changed. We have a number of things that we would like to
+see in the future releases of tinc. Not everything will be available in
+the near future. Our first objective is to make tinc work perfectly as
+it stands, and then add more advanced features.
+
+Meanwhile, we're always open-minded towards new ideas. And we're
+available too.
+
+
+@c ==================================================================
+@node Supported platforms
+@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),
+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
+likely compile and run, but it will not be able to send or receive data
+packets.
+
+@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/}.
+
+@c
+@c
+@c
+@c
+@c
+@c
+@c Preparing your system
+@c
+@c
+@c
+@c
+@c
+
+@c ==================================================================
+@node Preparations
+@chapter Preparations
+
+This chapter contains information on how to prepare your system to
+support tinc.
+
+@menu
+* Configuring the kernel::
+* Libraries::
+@end menu
+
+
+@c ==================================================================
+@node Configuring the kernel
+@section Configuring the kernel
+
+@menu
+* Configuration of Linux kernels::
+* Configuration of FreeBSD kernels::
+* Configuration of OpenBSD kernels::
+* Configuration of NetBSD kernels::
+* Configuration of Solaris kernels::
+* Configuration of Darwin (MacOS/X) kernels::
+* Configuration of Windows::
+@end menu
+
+
+@c ==================================================================
+@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
+Code maturity level options
+[*] Prompt for development and/or incomplete code/drivers
+Network device support
+<M> Universal tun/tap device driver support
+@end 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 decide to build the tun/tap driver as a kernel module, add these lines
+to @file{/etc/modules.conf}:
+
+@example
+alias char-major-10-200 tun
+@end example
+
+
+@c ==================================================================
+@node Configuration of FreeBSD kernels
+@subsection Configuration of FreeBSD kernels
+
+For FreeBSD version 4.1 and higher, tun and tap drivers are included in the default kernel configuration.
+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 ==================================================================
+@node Configuration of OpenBSD kernels
+@subsection Configuration of OpenBSD kernels
+
+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
+@subsection 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
+@subsection Configuration of Solaris kernels
+
+For Solaris 8 (SunOS 5.8) and higher,
+the tun driver may or may not be included in the default kernel configuration.
+If it isn't, the source can be downloaded from @uref{http://vtun.sourceforge.net/tun/}.
+For x86 and sparc64 architectures, precompiled versions can be found at @uref{http://www.monkey.org/~dugsong/fragroute/}.
+If the @file{net/if_tun.h} header file is missing, install it from the source package.
+
+
+@c ==================================================================
+@node Configuration of Darwin (MacOS/X) kernels
+@subsection Configuration of Darwin (MacOS/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
+
+
+@c ==================================================================
+@node Configuration of Windows
+@subsection Configuration of Windows
+
+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 ==================================================================
+@node Libraries
+@section Libraries
+
+@cindex requirements
+@cindex libraries
+Before you can configure or build tinc, you need to have the OpenSSL, zlib,
+lzo, curses and readline libraries installed on your system. If you try to
+configure tinc without having them installed, configure will give you an error
+message, and stop.
+
+@menu
+* OpenSSL::
+* zlib::
+* lzo::
+* libcurses::
+* libreadline::
+@end menu
+
+
+@c ==================================================================
+@node OpenSSL
+@subsection OpenSSL
+
+@cindex OpenSSL
+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 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
+available. Make sure you install the development AND runtime versions
+of this package.
+
+If you have to install OpenSSL manually, you can get the source code
+from @url{http://www.openssl.org/}. 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).
+
+If you installed the OpenSSL libraries from source, it may be necessary
+to let configure know where they are, by passing configure one of the
+--with-openssl-* parameters.
+
+@example
+--with-openssl=DIR OpenSSL library and headers prefix
+--with-openssl-include=DIR OpenSSL headers directory
+ (Default is OPENSSL_DIR/include)
+--with-openssl-lib=DIR OpenSSL library directory
+ (Default is OPENSSL_DIR/lib)
+@end example
+
+
+@subsubheading License
+
+@cindex license
+The complete source code of tinc is covered by the GNU GPL version 2.
+Since the license under which OpenSSL is distributed is not directly
+compatible with the terms of the GNU GPL
+@uref{http://www.openssl.org/support/faq.html#LEGAL2}, we
+include an exemption to the GPL (see also the file COPYING.README) to allow
+everyone to create a statically or dynamically linked executable:
+
+@quotation
+This program is released under the GPL with the additional exemption
+that compiling, linking, and/or using OpenSSL is allowed. You may
+provide binary packages linked to the OpenSSL libraries, provided that
+all other requirements of the GPL are met.
+@end quotation
+
+Since the LZO library used by tinc is also covered by the GPL,
+we also present the following exemption:
+
+@quotation
+Hereby I grant a special exception to the tinc VPN project
+(http://www.tinc-vpn.org/) to link the LZO library with the OpenSSL library
+(http://www.openssl.org).
+
+Markus F.X.J. Oberhumer
+@end quotation
+
+
+@c ==================================================================
+@node zlib
+@subsection zlib
+
+@cindex zlib
+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 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
+of this package.
+
+If you have to install zlib manually, you can get the source code
+from @url{http://www.gzip.org/zlib/}. 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 ==================================================================
+@node lzo
+@subsection lzo
+
+@cindex lzo
+Another form of compression is offered using the LZO library.
+
+If this library is not installed, you wil 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
+of this package.
+
+If you have to install lzo manually, you can get the source code
+from @url{http://www.oberhumer.com/opensource/lzo/}. 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 ==================================================================
+@node libcurses
+@subsection libcurses
+
+@cindex libcurses
+For the "tinc top" command, tinc requires a curses library.
+
+If this library is not installed, you wil get an error when running the
+configure script. You can either install a suitable curses library, or disable
+all functionality that depends on a curses library by using the
+"--disable-curses" option when running the configure script.
+
+There are several curses libraries. It is recommended that you install
+"ncurses" (@url{http://invisible-island.net/ncurses/}),
+however other curses libraries should also work.
+In particular, "PDCurses" (@url{http://pdcurses.sourceforge.net/})
+is recommended if you want to compile tinc for Windows.
+
+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.
+
+
+@c ==================================================================
+@node libreadline
+@subsection libreadline
+
+@cindex libreadline
+For the "tinc" command's shell functionality, tinc uses the readline library.
+
+If this library is not installed, you wil get an error when running the
+configure script. You can either install a suitable readline library, or
+disable all functionality that depends on a readline library by using the
+"--disable-readline" option when running the configure script.
+
+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 libreadline manually, you can get the source code from
+@url{http://www.gnu.org/software/readline/}. 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
+@c Installing tinc
+@c
+@c
+@c
+@c
+
+@c ==================================================================
+@node Installation
+@chapter Installation
+
+If you use Debian, you may want to install one of the
+precompiled packages for your system. These packages are equipped with
+system startup scripts and sample configurations.
+
+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
+the checksums of these files listed; you may wish to check these with
+md5sum before continuing.
+
+Tinc comes in a convenient autoconf/automake package, which you can just
+treat the same as any other package. Which is just untar it, type
+`./configure' and then `make'.
+More detailed instructions are in the file @file{INSTALL}, which is
+included in the source distribution.
+
+@menu
+* Building and installing tinc::
+* System files::
+@end menu
+
+
+@c ==================================================================
+@node Building and installing tinc
+@section Building and installing tinc
+
+Detailed instructions on configuring the source, building tinc and installing tinc
+can be found in the file called @file{INSTALL}.
+
+@cindex binary package
+If you happen to have a binary package for tinc for your distribution,
+you can use the package management tools of that distribution to install tinc.
+The documentation that comes along with your distribution will tell you how to do that.
+
+@menu
+* Darwin (MacOS/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
+
+In order to build tinc on Darwin, you need to install the MacOS/X Developer Tools
+from @uref{http://developer.apple.com/tools/macosxtools.html} and
+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.
+
+@c ==================================================================
+@node Cygwin (Windows) build environment
+@subsection Cygwin (Windows) build environment
+
+If Cygwin hasn't already been installed, install it directly from
+@uref{http://www.cygwin.com/}.
+
+When tinc is compiled in a Cygwin environment, it can only be run in this environment,
+but all programs, including those started outside the Cygwin environment, will be able to use the VPN.
+It will also support all features.
+
+@c ==================================================================
+@node MinGW (Windows) build environment
+@subsection MinGW (Windows) build environment
+
+You will need to install the MinGW environment from @uref{http://www.mingw.org}.
+
+When tinc is compiled using MinGW it runs natively under Windows,
+it is not necessary to keep MinGW installed.
+
+When detaching, tinc will install itself as a service,
+which will be restarted automatically after reboots.
+
+
+@c ==================================================================
+@node System files
+@section System files
+
+Before you can run tinc, you must make sure you have all the needed
+files on your system.
+
+@menu
+* Device files::
+* Other files::
+@end menu
+
+
+@c ==================================================================
+@node Device files
+@subsection Device files
+
+@cindex device files
+Most operating systems nowadays come with the necessary device files by default,
+or they have a mechanism to create them on demand.
+
+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/net/tun c 10 200
+@end example
+
+
+@c ==================================================================
+@node Other files
+@subsection Other files
+
+@subsubheading @file{/etc/networks}
+
+You may add a line to @file{/etc/networks} so that your VPN will get a
+symbolic name. For example:
+
+@example
+myvpn 10.0.0.0
+@end example
+
+@subsubheading @file{/etc/services}
+
+@cindex port numbers
+You may add this line to @file{/etc/services}. The effect is that you
+may supply a @samp{tinc} as a valid port number to some programs. The
+number 655 is registered with the IANA.
+
+@example
+tinc 655/tcp TINC
+tinc 655/udp TINC
+# Ivo Timmermans <ivo@@tinc-vpn.org>
+@end example
+
+
+@c
+@c
+@c
+@c
+@c Configuring tinc
+@c
+@c
+@c
+@c
+
+
+@c ==================================================================
+@node Configuration
+@chapter Configuration
+
+@menu
+* Configuration introduction::
+* Multiple networks::
+* How connections work::
+* Configuration files::
+* Network interfaces::
+* Example configuration::
+@end menu
+
+@c ==================================================================
+@node Configuration introduction
+@section Configuration introduction
+
+Before actually starting to configure tinc and editing files,
+make sure you have read this entire section so you know what to expect.
+Then, make it clear to yourself how you want to organize your VPN:
+What are the nodes (computers running tinc)?
+What IP addresses/subnets do they have?
+What is the network mask of the entire VPN?
+Do you need special firewall rules?
+Do you have to set up masquerading or forwarding rules?
+Do you want to run tinc in router mode or switch mode?
+These questions can only be answered by yourself,
+you will not find the answers in this documentation.
+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.tldp.org/LDP/nag2/, Linux Network Administrators Guide}.
+
+If you have everything clearly pictured in your mind,
+proceed in the following order:
+First, create the initial configuration files and public/private keypairs using the following command:
+@example
+tinc -n @var{NETNAME} init @var{NAME}
+@end example
+Second, use @samp{tinc -n @var{NETNAME} add ...} to further configure tinc.
+Finally, export your host configuration file using @samp{tinc -n @var{NETNAME} export} and send it to those
+people or computers you want tinc to connect to.
+They should send you their host configuration file back, which you can import using @samp{tinc -n @var{NETNAME} import}.
+
+These steps are described in the subsections below.
+
+
+@c ==================================================================
+@node Multiple networks
+@section Multiple networks
+
+@cindex multiple networks
+@cindex netname
+
+In order to allow you to run more than one tinc daemon on one computer,
+for instance if your computer is part of more than one VPN,
+you can assign a @var{netname} to your VPN.
+It is not required if you only run one tinc daemon,
+it doesn't even have to be the same on all the nodes of your VPN,
+but it is recommended that you choose one anyway.
+
+We will asume you use a netname throughout this document.
+This means that you call tinc with the -n argument,
+which will specify the netname.
+
+The effect of this option is that tinc will set its configuration
+root to @file{@value{sysconfdir}/tinc/@var{netname}/}, where @var{netname} is your argument to the -n option.
+You will also notice that log messages it appears in syslog as coming from @file{tinc.@var{netname}},
+and on Linux, unless specified otherwise, the name of the virtual network interface will be the same as the network name.
+
+However, it is not strictly necessary that you call tinc with the -n
+option. If you don not use it, the network name will just be empty, and
+tinc will look for files in @file{@value{sysconfdir}/tinc/} instead of
+@file{@value{sysconfdir}/tinc/@var{netname}/};
+the configuration file will then be @file{@value{sysconfdir}/tinc/tinc.conf},
+and the host configuration files are expected to be in @file{@value{sysconfdir}/tinc/hosts/}.
+
+
+@c ==================================================================
+@node How connections work
+@section How connections work
+
+When tinc starts up, it parses the command-line options and then
+reads in the configuration file tinc.conf.
+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.
+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,
+and failures to connect to other tinc daemons will not stop your tinc daemon
+for trying again later.
+This means you don't have to intervene if there are temporary network problems.
+
+@cindex client
+@cindex server
+There is no real distinction between a server and a client in tinc.
+If you wish, you can view a tinc daemon without a `ConnectTo' value as a server,
+and one which does specify such a value as a client.
+It does not matter if two tinc daemons have a `ConnectTo' value pointing to each other however.
+
+Connections specified using `ConnectTo' are so-called meta-connections.
+Tinc daemons exchange information about all other daemon they know about via these meta-connections.
+After learning about all the daemons in the VPN,
+tinc will create other connections as necessary in order to communicate with them.
+For example, if there are three daemons named A, B and C, and A has @samp{ConnectTo = B} in its tinc.conf file,
+and C has @samp{ConnectTo = B} in its tinc.conf file, then A will learn about C from B,
+and will be able to exchange VPN packets with C without the need to have @samp{ConnectTo = C} in its tinc.conf file.
+
+It could be that some daemons are located behind a Network Address Translation (NAT) device, or behind a firewall.
+In the above scenario with three daemons, if A and C are behind a NAT,
+B will automatically help A and C punch holes through their NAT,
+in a way similar to the STUN protocol, so that A and C can still communicate with each other directly.
+It is not always possible to do this however, and firewalls might also prevent direct communication.
+In that case, VPN packets between A and C will be forwarded by B.
+
+In effect, all nodes in the VPN will be able to talk to each other, as long as
+their is a path of meta-connections between them, and whenever possible, two
+nodes will communicate with each other directly.
+
+
+@c ==================================================================
+@node Configuration files
+@section Configuration files
+
+The actual configuration of the daemon is done in the file
+@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 optionnal 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
+
+@example
+Variable = Value.
+@end example
+
+The variable names are case insensitive, and any spaces, tabs, newlines
+and carriage returns are ignored. Note: it is not required that you put
+in the `=' sign, but doing so improves readability. If you leave it
+out, remember to replace it with at least one space character.
+
+The server configuration is complemented with host specific configuration (see
+the next section). Although all host configuration options for the local node
+listed in this document can also be put in
+@file{@value{sysconfdir}/tinc/@var{netname}/tinc.conf}, it is recommended to
+put host specific configuration options in the host configuration file, as this
+makes it easy to exchange with other nodes.
+
+You can edit the config file manually, but it is recommended that you use
+the tinc command to change configuration variables for you.
+
+In the following two subsections all valid variables are listed in alphabetical order.
+The default value is given between parentheses,
+other comments are between square brackets.
+
+@menu
+* Main configuration variables::
+* Host configuration variables::
+* Scripts::
+* How to configure::
+@end menu
+
+
+@c ==================================================================
+@node Main configuration variables
+@subsection Main configuration variables
+
+@table @asis
+@cindex AddressFamily
+@item AddressFamily = <ipv4|ipv6|any> (any)
+This option affects the address family of listening and outgoing sockets.
+If any is selected, then depending on the operating system
+both IPv4 and IPv6 or just IPv6 listening sockets will be created.
+
+@cindex AutoConnect
+@item AutoConnect = <count> (0) [experimental]
+If set to a non-zero value,
+tinc will try to only have count meta connections to other nodes,
+by automatically making or breaking connections to known nodes.
+Higher values increase redundancy but also increase meta data overhead.
+When using this option, a good value is 3.
+
+@cindex BindToAddress
+@item BindToAddress = <@var{address}> [<@var{port}>]
+This is the same as ListenAddress, however the address given with the BindToAddress option
+will also be used for outgoing connections.
+This is useful if your computer has more than one IPv4 or IPv6 address,
+and you want tinc to only use a specific one for outgoing packets.
+
+@cindex BindToInterface
+@item BindToInterface = <@var{interface}> [experimental]
+If you have more than one network interface in your computer, tinc will
+by default listen on all of them for incoming connections. It is
+possible to bind tinc to a single interface like eth0 or ppp0 with this
+variable.
+
+This option may not work on all platforms.
+Also, on some platforms it will not actually bind to an interface,
+but rather to the address that the interface has at the moment a socket is created.
+
+@cindex Broadcast
+@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}>
+Specifies which other tinc daemon to connect to on startup.
+Multiple ConnectTo variables may be specified,
+in which case outgoing connections to each specified tinc daemon are made.
+The names should be known to this tinc daemon
+(i.e., there should be a host configuration file for the name on the ConnectTo line).
+
+If you don't specify a host with ConnectTo,
+tinc won't try to connect to other daemons at all,
+and will instead just listen for incoming connections.
+
+@cindex DecrementTTL
+@item DecrementTTL = <yes | no> (no) [experimental]
+When enabled, tinc will decrement the Time To Live field in IPv4 packets, or the Hop Limit field in IPv6 packets,
+before forwarding a received packet to the virtual network device or to another node,
+and will drop packets that have a TTL value of zero,
+in which case it will send an ICMP Time Exceeded packet back.
+
+Do not use this option if you use switch mode and want to use IPv6.
+
+@cindex Device
+@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}.
+
+@cindex DeviceType
+@item DeviceType = <@var{type}> (platform dependent)
+The type of the virtual network device.
+Tinc will normally automatically select the right type of tun/tap interface, and this option should not be used.
+However, this option can be used to select one of the special interface types, if support for them is compiled in.
+
+@table @asis
+@cindex dummy
+@item dummy
+Use a dummy interface.
+No packets are ever read or written to a virtual network device.
+Useful for testing, or when setting up a node that only forwards packets for other nodes.
+
+@cindex raw_socket
+@item raw_socket
+Open a raw socket, and bind it to a pre-existing
+@var{Interface} (eth0 by default).
+All packets are read from this interface.
+Packets received for the local node are written to the raw socket.
+However, at least on Linux, the operating system does not process IP packets destined for the local host.
+
+@cindex multicast
+@item multicast
+Open a multicast UDP socket and bind it to the address and port (separated by spaces) and optionally a TTL value specified using @var{Device}.
+Packets are read from and written to this multicast socket.
+This can be used to connect to UML, QEMU or KVM instances listening on the same multicast address.
+Do NOT connect multiple tinc daemons to the same multicast address, this will very likely cause routing loops.
+Also note that this can cause decrypted VPN packets to be sent out on a real network if misconfigured.
+
+@cindex UML
+@item uml (not compiled in by default)
+Create a UNIX socket with the filename specified by
+@var{Device}, or @file{@value{localstatedir}/run/@var{netname}.umlsocket}
+if not specified.
+Tinc will wait for a User Mode Linux instance to connect to this socket.
+
+@cindex VDE
+@item vde (not compiled in by default)
+Uses the libvdeplug library to connect to a Virtual Distributed Ethernet switch,
+using the UNIX socket specified by
+@var{Device}, or @file{@value{localstatedir}/run/vde.ctl}
+if not specified.
+@end table
+
+Also, in case tinc does not seem to correctly interpret packets received from the virtual network device,
+it can be used to change the way packets are interpreted:
+
+@table @asis
+@item tun (BSD and Linux)
+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 (BSD)
+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 (BSD)
+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 (BSD and Linux)
+Set type to tap.
+Tinc will expect packets read from the virtual network device
+to start with an Ethernet header.
+@end table
+
+@cindex DirectOnly
+@item DirectOnly = <yes|no> (no) [experimental]
+When this option is enabled, packets that cannot be sent directly to the destination node,
+but which would have to be forwarded by an intermediate node, are dropped instead.
+When combined with the IndirectData option,
+packets for nodes for which we do not have a meta connection with are also dropped.
+
+@cindex ECDSAPrivateKeyFile
+@item ECDSAPrivateKeyFile = <@var{path}> (@file{@value{sysconfdir}/tinc/@var{netname}/ecdsa_key.priv})
+The file in which the private ECDSA key of this tinc daemon resides.
+This is only used if ExperimentalProtocol is enabled.
+
+@cindex ExperimentalProtocol
+@item ExperimentalProtocol = <yes|no> (yes)
+When this option is enabled, the SPTPS protocol will be used when connecting to nodes that also support it.
+Ephemeral ECDH will be used for key exchanges,
+and ECDSA will be used instead of RSA for authentication.
+When enabled, an ECDSA key must have been generated before with
+@samp{tinc generate-ecdsa-keys}.
+
+@cindex Forwarding
+@item Forwarding = <off|internal|kernel> (internal) [experimental]
+This option selects the way indirect packets are forwarded.
+
+@table @asis
+@item off
+Incoming packets that are not meant for the local node,
+but which should be forwarded to another node, are dropped.
+
+@item internal
+Incoming packets that are meant for another node are forwarded by tinc internally.
+
+This is the default mode, and unless you really know you need another forwarding mode, don't change it.
+
+@item kernel
+Incoming packets are always sent to the TUN/TAP device, even if the packets are not for the local node.
+This is less efficient, but allows the kernel to apply its routing and firewall rules on them,
+and can also help debugging.
+@end table
+
+@cindex Hostnames
+@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
+it does a lookup if your DNS server is not responding.
+
+This does not affect resolving hostnames to IP addresses from the
+configuration file, but whether hostnames should be resolved while logging.
+
+@cindex Interface
+@item Interface = <@var{interface}>
+Defines the name of the interface corresponding to the virtual network device.
+Depending on the operating system and the type of device this may or may not actually set the name of the 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 ListenAddress
+@item ListenAddress = <@var{address}> [<@var{port}>]
+If your computer has more than one IPv4 or IPv6 address, tinc
+will by default listen on all of them for incoming connections.
+This option can be used to restrict which addresses tinc listens on.
+Multiple ListenAddress variables may be specified,
+in which case listening sockets for each specified address are made.
+
+If no @var{port} is specified, the socket will listen on the port specified by the Port option,
+or to port 655 if neither is given.
+To only listen on a specific port but not to a specific address, use "*" for the @var{address}.
+
+@cindex LocalDiscovery
+@item LocalDiscovery = <yes | no> (no)
+When enabled, tinc will try to detect peers that are on the same local network.
+This will allow direct communication using LAN addresses, even if both peers are behind a NAT
+and they only ConnectTo a third node outside the NAT,
+which normally would prevent the peers from learning each other's LAN address.
+
+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 LocalDiscoveryAddress
+@item LocalDiscoveryAddress <@var{address}>
+If this variable is specified, local discovery packets are sent to the given @var{address}.
+
+@cindex Mode
+@item Mode = <router|switch|hub> (router)
+This option selects the way packets are routed to other daemons.
+
+@table @asis
+@cindex router
+@item router
+In this mode Subnet
+variables in the host configuration files will be used to form a routing table.
+Only packets of routable protocols (IPv4 and IPv6) are supported in this mode.
+
+This is the default mode, and unless you really know you need another mode, don't change it.
+
+@cindex switch
+@item switch
+In this mode the MAC addresses of the packets on the VPN will be used to
+dynamically create a routing table just like an Ethernet switch does.
+Unicast, multicast and broadcast packets of every protocol that runs over Ethernet are supported in this mode
+at the cost of frequent broadcast ARP requests and routing table updates.
+
+This mode is primarily useful if you want to bridge Ethernet segments.
+
+@cindex hub
+@item hub
+This mode is almost the same as the switch mode, but instead
+every packet will be broadcast to the 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 MaxConnectionBurst
+@item MaxConnectionBurst = <@var{count}> (100)
+This option controls how many connections tinc accepts in quick succession.
+If there are more connections than the given number in a short time interval,
+tinc will reduce the number of accepted connections to only one per second,
+until the burst has passed.
+
+@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 _), and is case sensitive.
+
+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)
+The number of seconds of inactivity that tinc will wait before sending a
+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]
+When this option is enabled the value of the TOS field of tunneled IPv4 packets
+will be inherited by the UDP packets that are sent out.
+
+@cindex PrivateKey
+@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.
+
+@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{tinc generate-keys}. It must be a full path, not a
+relative directory.
+
+@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.
+The window is a bitfield which tracks 1 packet per bit, so for example
+the default setting of 16 will track up to 128 packets in the window. In high
+bandwidth scenarios, setting this to a higher value can reduce packet loss from
+the interaction of replay tracking with underlying real packet loss and/or
+reordering. Setting this to zero will disable replay tracking completely and
+pass all traffic, but leaves tinc vulnerable to replay-based attacks on your
+traffic.
+
+@cindex StrictSubnets
+@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]
+When this option is enabled tinc will no longer forward information between other tinc daemons,
+and will only allow connections with nodes for which host config files are present in the local
+@file{@value{sysconfdir}/tinc/@var{netname}/hosts/} directory.
+Setting this options also implicitly sets StrictSubnets.
+
+@cindex UDPRcvBuf
+@item UDPRcvBuf = <bytes> (OS default)
+Sets the socket receive buffer size for the UDP socket, in bytes.
+If unset, the default buffer size will be used by the operating system.
+
+@cindex UDPSndBuf
+@item UDPSndBuf = <bytes> Pq OS default
+Sets the socket send buffer size for the UDP socket, in bytes.
+If unset, the default buffer size will be used by the operating system.
+
+@end table
+
+
+@c ==================================================================
+@node Host configuration variables
+@subsection Host configuration variables
+
+@table @asis
+@cindex Address
+@item Address = <@var{IP address}|@var{hostname}> [<port>] [recommended]
+This variable is only required if you want to connect to this host. It
+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)
+The symmetric cipher algorithm used to encrypt UDP packets using the legacy protocol.
+Any cipher supported by OpenSSL is recognized.
+Furthermore, specifying "none" will turn off packet encryption.
+It is best to use only those ciphers which support CBC mode.
+This option has no effect for connections using the SPTPS protocol, which always use AES-256-CTR.
+
+@cindex ClampMSS
+@item ClampMSS = <yes|no> (yes)
+This option specifies whether tinc should clamp the maximum segment size (MSS)
+of TCP packets to the path MTU. This helps in situations where ICMP
+Fragmentation Needed or Packet too Big messages are dropped by firewalls.
+
+@cindex Compression
+@item Compression = <@var{level}> (0)
+This option sets the level of compression used for UDP packets.
+Possible values are 0 (off), 1 (fast zlib) and any integer up to 9 (best zlib),
+10 (fast lzo) and 11 (best lzo).
+
+@cindex Digest
+@item Digest = <@var{digest}> (sha1)
+The digest algorithm used to authenticate UDP packets using the legacy protocol.
+Any digest supported by OpenSSL is recognized.
+Furthermore, specifying "none" will turn off packet authentication.
+This option has no effect for connections using the SPTPS protocol, which always use HMAC-SHA-256.
+
+@cindex IndirectData
+@item IndirectData = <yes|no> (no)
+When set to yes, other nodes which do not already have a meta connection to you
+will not try to establish direct communication with you.
+It is best to leave this option out or set it to no.
+
+@cindex MACLength
+@item MACLength = <@var{bytes}> (4)
+The length of the message authentication code used to authenticate UDP packets using the legacy protocol.
+Can be anything from 0
+up to the length of the digest produced by the digest algorithm.
+This option has no effect for connections using the SPTPS protocol, which never truncate MACs.
+
+@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.
+You can use decimal portnumbers or symbolic names (as listed in @file{/etc/services}).
+
+@cindex PublicKey
+@item PublicKey = <@var{key}> [obsolete]
+This is the RSA public key for this host.
+
+@cindex PublicKeyFile
+@item PublicKeyFile = <@var{path}> [obsolete]
+This is the full path name of the RSA public key file that was generated
+by @samp{tinc generate-keys}. It must be a full path, not a relative
+directory.
+
+@cindex PEM format
+From version 1.0pre4 on tinc will store the public key directly into the
+host configuration file in PEM format, the above two options then are not
+necessary. Either the PEM format is used, or exactly
+@strong{one of the above two options} must be specified
+in each host configuration file, if you want to be able to establish a
+connection with that host.
+
+@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.
+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.
+
+Subnets can either be single MAC, IPv4 or IPv6 addresses,
+in which case a subnet consisting of only that single address is assumed,
+or they can be a IPv4 or IPv6 network address with a prefixlength.
+For example, IPv4 subnets must be in a form like 192.168.1.0/24,
+where 192.168.1.0 is the network address and 24 is the number of bits set in the netmask.
+Note that subnets like 192.168.1.1/24 are invalid!
+Read a networking HOWTO/FAQ/guide if you don't understand this.
+IPv6 subnets are notated like fec0:0:0:1::/64.
+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
+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{http://www.ietf.org/rfc/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)
+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
+firewall, or if UDP packet routing is disabled somehow.
+Setting this options also implicitly sets IndirectData.
+
+@cindex Weight
+@item Weight = <weight>
+If this variable is set, it overrides the weight given to connections made with
+another host. A higher weight means a lower priority is given to this
+connection when broadcasting or forwarding packets.
+@end table
+
+
+@c ==================================================================
+@node Scripts
+@subsection Scripts
+
+@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 @file{.bat} or @file{.cmd}.
+
+@table @file
+@cindex tinc-up
+@item @value{sysconfdir}/tinc/@var{netname}/tinc-up
+This is the most important script.
+If it is present it will be executed right after the tinc daemon has been
+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
+@item @value{sysconfdir}/tinc/@var{netname}/tinc-down
+This script is started right before the tinc daemon quits.
+
+@item @value{sysconfdir}/tinc/@var{netname}/hosts/@var{host}-up
+This script is started when the tinc daemon with name @var{host} becomes reachable.
+
+@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.
+
+@item @value{sysconfdir}/tinc/@var{netname}/invitation-created
+This script is started when a new invitation has been created.
+
+@item @value{sysconfdir}/tinc/@var{netname}/invitation-accepted
+This script is started when an invitation has been used.
+
+@end table
+
+@cindex environment variables
+The scripts are started without command line arguments,
+but can make use of certain environment variables.
+Under UNIX like operating systems the names of environment variables must be preceded by a $ in scripts.
+Under Windows, in @file{.bat} or @file{.cmd} files, they have to be put between % signs.
+
+@table @env
+@cindex NETNAME
+@item NETNAME
+If a netname was specified, this environment variable contains it.
+
+@cindex NAME
+@item NAME
+Contains the name of this tinc daemon.
+
+@cindex DEVICE
+@item DEVICE
+Contains the name of the virtual network device that tinc uses.
+
+@cindex INTERFACE
+@item INTERFACE
+Contains the name of the virtual network interface that tinc uses.
+This should be used for commands like ifconfig.
+
+@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
+When a host becomes (un)reachable, this is set to its real address.
+
+@cindex REMOTEPORT
+@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.
+
+@cindex WEIGHT
+@item WEIGHT
+When a subnet becomes (un)reachable, this is set to the subnet weight.
+
+@cindex INVITATION_FILE
+@item INVITATION_FILE
+When the @file{invitation-created} script is called,
+this is set to the file where the invitation details will be stored.
+
+@cindex INVITATION_URL
+@item INVITATION_URL
+When the @file{invitation-created} script is called,
+this is set to the invitation URL that has been created.
+@end table
+
+Do not forget that under UNIX operating systems,
+you have to make the scripts executable, using the command @samp{chmod a+x script}.
+
+
+@c ==================================================================
+@node How to configure
+@subsection How to configure
+
+@subsubheading Step 1. Creating initial configuration files.
+
+The initial directory structure, configuration files and public/private keypairs are created using the following command:
+
+@example
+tinc -n @var{netname} init @var{name}
+@end example
+
+(You will need to run this as root, or use "sudo".)
+This will create the configuration directory @file{@value{sysconfdir}/tinc/@var{netname}.},
+and inside it will create another directory named @file{hosts/}.
+In the configuration directory, it will create the file @file{tinc.conf} with the following contents:
+
+@example
+Name = @var{name}
+@end example
+
+It will also create private RSA and ECDSA keys, which will be stored in the files @file{rsa_key.priv} and @file{ecdsa_key.priv}.
+It will also create a host configuration file @file{hosts/@var{name}},
+which will contain the corresponding public RSA and ECDSA keys.
+
+Finally, on UNIX operating systems, it will create an executable script @file{tinc-up},
+which will initially not do anything except warning that you should edit it.
+
+@subsubheading Step 2. Modifying the initial configuration.
+
+Unless you want to use tinc in switch mode,
+you should now configure which range of addresses you will use on the VPN.
+Let's assume you will be part of a VPN which uses the address range 192.168.0.0/16,
+and you yourself have a smaller portion of that range: 192.168.2.0/24.
+Then you should run the following command:
+
+@example
+tinc -n @var{netname} add subnet 192.168.2.0/24
+@end example
+
+This will add a Subnet statement to your host configuration file.
+Try opening the file @file{@value{sysconfdir}/tinc/@var{netname}/hosts/@var{name}} in an editor.
+You should now see a file containing the public RSA and ECDSA keys (which looks like a bunch of random characters),
+and the following line at the bottom:
+
+@example
+Subnet = 192.168.2.0/24
+@end example
+
+If you will use more than one address range, you can add more Subnets.
+For example, if you also use the IPv6 subnet fec0:0:0:2::/64, you can add it as well:
+
+@example
+tinc -n @var{netname} add subnet fec0:0:0:2::/24
+@end example
+
+This will add another line to the file @file{hosts/@var{name}}.
+If you make a mistake, you can undo it by simply using @samp{del} instead of @samp{add}.
+
+If you want other tinc daemons to create meta-connections to your daemon,
+you should add your public IP address or hostname to your host configuration file.
+For example, if your hostname is foo.example.org, run:
+
+@example
+tinc -n @var{netname} add address foo.example.org
+@end example
+
+If you already know to which daemons your daemon should make meta-connections,
+you should configure that now as well.
+Suppose you want to connect to a daemon named "bar", run:
+
+@example
+tinc -n @var{netname} add connectto bar
+@end example
+
+Note that you specify the Name of the other daemon here, not an IP address or hostname!
+When you start tinc, and it tries to make a connection to "bar",
+it will look for a host configuration file named @file{hosts/bar},
+and will read Address statements and public keys from that file.
+
+@subsubheading Step 2. Exchanging configuration files.
+
+If your daemon has a ConnectTo = bar statement in its @file{tinc.conf} file,
+or if bar has a ConnectTo your daemon, then you both need each other's host configuration files.
+You should send @file{hosts/@var{name}} to bar, and bar should send you his file which you should move to @file{hosts/bar}.
+If you are on a UNIX platform, you can easily send an email containing the necessary information using the following command
+(assuming the owner of bar has the email address bar@@example.org):
+
+@example
+tinc -n @var{netname} export | mail -s "My config file" bar@@example.org
+@end example
+
+If the owner of bar does the same to send his host configuration file to you,
+you can probably pipe his email through the following command,
+or you can just start this command in a terminal and copy&paste the email:
+
+@example
+tinc -n @var{netname} import
+@end example
+
+If you are the owner of bar yourself, and you have SSH access to that computer,
+you can also swap the host configuration files using the following command:
+
+@example
+tinc -n @var{netname} export \
+ | ssh bar.example.org tinc -n @var{netname} exchange \
+ | tinc -n @var{netname} import
+@end example
+
+You should repeat this for all nodes you ConnectTo, or which ConnectTo you.
+However, remember that you do not need to ConnectTo all nodes in the VPN;
+it is only necessary to create one or a few meta-connections,
+after the connections are made tinc will learn about all the other nodes in the VPN,
+and will automatically make other connections as necessary.
+
+
+@c ==================================================================
+@node Network interfaces
+@section Network interfaces
+
+Before tinc can start transmitting data over the tunnel, it must
+set up the virtual network interface.
+
+First, decide which IP addresses you want to have associated with these
+devices, and what network mask they must have.
+
+Tinc will open a virtual network device (@file{/dev/tun}, @file{/dev/tap0} or similar),
+which will also create a network interface called something like @samp{tun0}, @samp{tap0}.
+If you are using the Linux tun/tap driver, the network interface will by default have the same name as the @var{netname}.
+Under Windows you can change the name of the network interface from the Network Connections control panel.
+
+@cindex tinc-up
+You can configure the network interface by putting ordinary ifconfig, route, and other commands
+to a script named @file{@value{sysconfdir}/tinc/@var{netname}/tinc-up}.
+When tinc starts, this script will be executed. When tinc exits, it will execute the script named
+@file{@value{sysconfdir}/tinc/@var{netname}/tinc-down}, but normally you don't need to create that script.
+You can manually open the script in an editor, or use the following command:
+
+@example
+tinc -n @var{netname} edit tinc-up
+@end example
+
+An example @file{tinc-up} script, that would be appropriate for the scenario in the previous section, is:
+
+@example
+#!/bin/sh
+ifconfig $INTERFACE 192.168.2.1 netmask 255.255.0.0
+ip addr add fec0:0:0:2::/48 dev $INTERFACE
+@end example
+
+The first command gives the interface an IPv4 address and a netmask.
+The kernel will also automatically add an IPv4 route to this interface, so normally you don't need
+to add route commands to the @file{tinc-up} script.
+The kernel will also bring the interface up after this command.
+@cindex netmask
+The netmask is the mask of the @emph{entire} VPN network, not just your
+own subnet.
+The second command gives the interface an IPv6 address and netmask,
+which will also automatically add an IPv6 route.
+If you only want to use "ip addr" commands on Linux, don't forget that it doesn't bring the interface up, unlike ifconfig,
+so you need to add @samp{ip link set $INTERFACE up} in that case.
+
+The exact syntax of the ifconfig and route commands differs from platform to platform.
+You can look up the commands for setting addresses and adding routes in @ref{Platform specific information},
+but it is best to consult the manpages of those utilities on your platform.
+
+
+@c ==================================================================
+@node Example configuration
+@section Example configuration
+
+
+@cindex example
+Imagine the following situation. Branch A of our example `company' wants to connect
+three branch offices in B, C and D using the Internet. All four offices
+have a 24/7 connection to the Internet.
+
+A is going to serve as the center of the network. B and C will connect
+to A, and D will connect to C. Each office will be assigned their own IP
+network, 10.x.0.0.
+
+@example
+A: net 10.1.0.0 mask 255.255.0.0 gateway 10.1.54.1 internet IP 1.2.3.4
+B: net 10.2.0.0 mask 255.255.0.0 gateway 10.2.1.12 internet IP 2.3.4.5
+C: net 10.3.0.0 mask 255.255.0.0 gateway 10.3.69.254 internet IP 3.4.5.6
+D: net 10.4.0.0 mask 255.255.0.0 gateway 10.4.3.32 internet IP 4.5.6.7
+@end example
+
+Here, ``gateway'' is the VPN IP address of the machine that is running the
+tincd, and ``internet IP'' is the IP address of the firewall, which does not
+need to run tincd, but it must do a port forwarding of TCP and UDP on port
+655 (unless otherwise configured).
+
+In this example, it is assumed that eth0 is the interface that points to
+the inner (physical) LAN of the office, although this could also be the
+same as the interface that leads to the Internet. The configuration of
+the real interface is also shown as a comment, to give you an idea of
+how these example host is set up. All branches use the netname `company'
+for this particular VPN.
+
+Each branch is set up using the @samp{tinc init} and @samp{tinc config} commands,
+here we just show the end results:
+
+@subsubheading For Branch A
+
+@emph{BranchA} would be configured like this:
+
+In @file{@value{sysconfdir}/tinc/company/tinc-up}:
+
+@example
+#!/bin/sh
+
+# Real interface of internal network:
+# ifconfig eth0 10.1.54.1 netmask 255.255.0.0
+
+ifconfig $INTERFACE 10.1.54.1 netmask 255.0.0.0
+@end example
+
+and in @file{@value{sysconfdir}/tinc/company/tinc.conf}:
+
+@example
+Name = BranchA
+@end example
+
+On all hosts, @file{@value{sysconfdir}/tinc/company/hosts/BranchA} contains:
+
+@example
+Subnet = 10.1.0.0/16
+Address = 1.2.3.4
+
+-----BEGIN RSA PUBLIC KEY-----
+...
+-----END RSA PUBLIC KEY-----
+@end example
+
+Note that the IP addresses of eth0 and the VPN interface are the same.
+This is quite possible, if you make sure that the netmasks of the interfaces are different.
+It is in fact recommended to give both real internal network interfaces and VPN interfaces the same IP address,
+since that will make things a lot easier to remember and set up.
+
+
+@subsubheading For Branch B
+
+In @file{@value{sysconfdir}/tinc/company/tinc-up}:
+
+@example
+#!/bin/sh
+
+# Real interface of internal network:
+# ifconfig eth0 10.2.43.8 netmask 255.255.0.0
+
+ifconfig $INTERFACE 10.2.1.12 netmask 255.0.0.0
+@end example
+
+and in @file{@value{sysconfdir}/tinc/company/tinc.conf}:
+
+@example
+Name = BranchB
+ConnectTo = BranchA
+@end example
+
+Note here that the internal address (on eth0) doesn't have to be the
+same as on the VPN interface. Also, ConnectTo is given so that this node will
+always try to connect to BranchA.
+
+On all hosts, in @file{@value{sysconfdir}/tinc/company/hosts/BranchB}:
+
+@example
+Subnet = 10.2.0.0/16
+Address = 2.3.4.5
+
+-----BEGIN RSA PUBLIC KEY-----
+...
+-----END RSA PUBLIC KEY-----
+@end example
+
+
+@subsubheading For Branch C
+
+In @file{@value{sysconfdir}/tinc/company/tinc-up}:
+
+@example
+#!/bin/sh
+
+# Real interface of internal network:
+# ifconfig eth0 10.3.69.254 netmask 255.255.0.0
+
+ifconfig $INTERFACE 10.3.69.254 netmask 255.0.0.0
+@end example
+
+and in @file{@value{sysconfdir}/tinc/company/tinc.conf}:
+
+@example
+Name = BranchC
+ConnectTo = BranchA
+@end example
+
+C already has another daemon that runs on port 655, so they have to
+reserve another port for tinc. It knows the portnumber it has to listen on
+from it's own host configuration file.
+
+On all hosts, in @file{@value{sysconfdir}/tinc/company/hosts/BranchC}:
+
+@example
+Address = 3.4.5.6
+Subnet = 10.3.0.0/16
+Port = 2000
+
+-----BEGIN RSA PUBLIC KEY-----
+...
+-----END RSA PUBLIC KEY-----
+@end example
+
+
+@subsubheading For Branch D
+
+In @file{@value{sysconfdir}/tinc/company/tinc-up}:
+
+@example
+#!/bin/sh
+
+# Real interface of internal network:
+# ifconfig eth0 10.4.3.32 netmask 255.255.0.0
+
+ifconfig $INTERFACE 10.4.3.32 netmask 255.0.0.0
+@end example
+
+and in @file{@value{sysconfdir}/tinc/company/tinc.conf}:
+
+@example
+Name = BranchD
+ConnectTo = BranchC
+@end example
+
+D will be connecting to C, which has a tincd running for this network on
+port 2000. It knows the port number from the host configuration file.
+
+On all hosts, in @file{@value{sysconfdir}/tinc/company/hosts/BranchD}:
+
+@example
+Subnet = 10.4.0.0/16
+Address = 4.5.6.7
+
+-----BEGIN RSA PUBLIC KEY-----
+...
+-----END RSA PUBLIC KEY-----
+@end example
+
+@subsubheading Key files
+
+A, B, C and D all have their own public/private keypairs:
+
+The private RSA key is stored in @file{@value{sysconfdir}/tinc/company/rsa_key.priv},
+the private ECDSA key is stored in @file{@value{sysconfdir}/tinc/company/ecdsa_key.priv},
+and the public RSA and ECDSA keys are put into the host configuration file in the @file{@value{sysconfdir}/tinc/company/hosts/} directory.
+
+@subsubheading Starting
+
+After each branch has finished configuration and they have distributed
+the host configuration files amongst them, they can start their tinc daemons.
+They don't necessarily have to wait for the other branches to have started
+their daemons, tinc will try connecting until they are available.
+
+
+@c ==================================================================
+@node Running tinc
+@chapter Running tinc
+
+If everything else is done, you can start tinc by typing the following command:
+
+@example
+tinc -n @var{netname} start
+@end example
+
+@cindex daemon
+Tinc will detach from the terminal and continue to run in the background like a good daemon.
+If there are any problems however you can try to increase the debug level
+and look in the syslog to find out what the problems are.
+
+@menu
+* Runtime options::
+* Signals::
+* Debug levels::
+* Solving problems::
+* Error messages::
+* Sending bug reports::
+@end menu
+
+
+@c ==================================================================
+@node Runtime options
+@section Runtime options
+
+Besides the settings in the configuration file, tinc also accepts some
+command line options.
+
+@cindex command line
+@cindex runtime options
+@cindex 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 -D, --no-detach
+Don't fork and detach.
+This will also disable the automatic restart mechanism for fatal errors.
+
+@cindex debug level
+@item -d, --debug=@var{level}
+Set debug level to @var{level}. The higher the debug level, the more gets
+logged. Everything goes via syslog.
+
+@item -n, --net=@var{netname}
+Use configuration for net @var{netname}.
+This will let tinc read all configuration files from
+@file{@value{sysconfdir}/tinc/@var{netname}/}.
+Specifying . for @var{netname} is the same as not specifying any @var{netname}.
+@xref{Multiple networks}.
+
+@item --pidfile=@var{filename}
+Store a cookie in @var{filename} which allows tinc to authenticate.
+If unspecified, the default is
+@file{@value{localstatedir}/run/tinc.@var{netname}.pid}.
+
+@item -o, --option=[@var{HOST}.]@var{KEY}=@var{VALUE}
+Without specifying a @var{HOST}, this will set server configuration variable @var{KEY} to @var{VALUE}.
+If specified as @var{HOST}.@var{KEY}=@var{VALUE},
+this will set the host configuration variable @var{KEY} of the host named @var{HOST} to @var{VALUE}.
+This option can be used more than once to specify multiple configuration variables.
+
+@item -L, --mlock
+Lock tinc into main memory.
+This will prevent sensitive data like shared private keys to be written to the system swap files/partitions.
+
+This option is not supported on all platforms.
+
+@item --logfile[=@var{file}]
+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 --bypass-security
+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.
+
+This option is not supported on all platforms.
+@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.
+
+This option is not supported on all platforms.
+
+@item --help
+Display a short reminder of these runtime options and terminate.
+
+@item --version
+Output version information and exit.
+
+@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.
+If the --logfile option is used, this will also close and reopen the log file,
+useful when log rotation is used.
+
+@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
+
+If tinc starts without problems, but if the VPN doesn't work, you will have to find the cause of the problem.
+The first thing to do is to start tinc with a high debug level in the foreground,
+so you can directly see everything tinc logs:
+
+@example
+tincd -n @var{netname} -d5 -D
+@end example
+
+If tinc does not log any error messages, then you might want to check the following things:
+
+@itemize
+@item @file{tinc-up} script
+Does this script contain the right commands?
+Normally you must give the interface the address of this host on the VPN, and the netmask must be big enough so that the entire VPN is covered.
+
+@item Subnet
+Does the Subnet (or Subnets) in the host configuration file of this host match the portion of the VPN that belongs to this host?
+
+@item Firewalls and NATs
+Do you have a firewall or a NAT device (a masquerading firewall or perhaps an ADSL router that performs masquerading)?
+If so, check that it allows TCP and UDP traffic on port 655.
+If it masquerades and the host running tinc is behind it, make sure that it forwards TCP and UDP traffic to port 655 to the host running tinc.
+You can add @samp{TCPOnly = yes} to your host config file to force tinc to only use a single TCP connection,
+this works through most firewalls and NATs.
+
+@end itemize
+
+
+@c ==================================================================
+@node Error messages
+@section Error messages
+
+What follows is a list of the most common error messages you might find in the logs.
+Some of them will only be visible if the debug level is high enough.
+
+@table @samp
+@item Could not open /dev/tap0: No such device
+
+@itemize
+@item You forgot to `modprobe netlink_dev' or `modprobe ethertap'.
+@item You forgot to compile `Netlink device emulation' in the kernel.
+@end itemize
+
+@item Can't write to /dev/net/tun: No such device
+
+@itemize
+@item You forgot to `modprobe tun'.
+@item You forgot to compile `Universal TUN/TAP driver' in the kernel.
+@item The tun device is located somewhere else in @file{/dev/}.
+@end itemize
+
+@item Network address and prefix length do not match!
+
+@itemize
+@item The Subnet field must contain a @emph{network} address, trailing bits should be 0.
+@item If you only want to use one IP address, set the netmask to /32.
+@end itemize
+
+@item Error reading RSA key file `rsa_key.priv': No such file or directory
+
+@itemize
+@item You forgot to create a public/private keypair.
+@item Specify the complete pathname to the private key file with the @samp{PrivateKeyFile} option.
+@end itemize
+
+@item Warning: insecure file permissions for RSA private key file `rsa_key.priv'!
+
+@itemize
+@item The private key file is readable by users other than root.
+Use chmod to correct the file permissions.
+@end itemize
+
+@item Creating metasocket failed: Address family not supported
+
+@itemize
+@item By default tinc tries to create both IPv4 and IPv6 sockets.
+On some platforms this might not be implemented.
+If the logs show @samp{Ready} later on, then at least one metasocket was created,
+and you can ignore this message.
+You can add @samp{AddressFamily = ipv4} to @file{tinc.conf} to prevent this from happening.
+@end itemize
+
+@item Cannot route packet: unknown IPv4 destination 1.2.3.4
+
+@itemize
+@item You try to send traffic to a host on the VPN for which no Subnet is known.
+@item If it is a broadcast address (ending in .255), it probably is a samba server or a Windows host sending broadcast packets.
+You can ignore it.
+@end itemize
+
+@item Cannot route packet: ARP request for unknown address 1.2.3.4
+
+@itemize
+@item You try to send traffic to a host on the VPN for which no Subnet is known.
+@end itemize
+
+@item Packet with destination 1.2.3.4 is looping back to us!
+
+@itemize
+@item Something is not configured right. Packets are being sent out to the
+virtual network device, but according to the Subnet directives in your host configuration
+file, those packets should go to your own host. Most common mistake is that
+you have a Subnet line in your host configuration file with a prefix length which is
+just as large as the prefix of the virtual network interface. The latter should in almost all
+cases be larger. Rethink your configuration.
+Note that you will only see this message if you specified a debug
+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.
+@end itemize
+
+@item Node foo (1.2.3.4) is not reachable
+
+@itemize
+@item Node foo does not have a connection anymore, its tinc daemon is not running or its connection to the Internet is broken.
+@end itemize
+
+@item Received UDP packet from unknown source 1.2.3.4 (port 12345)
+
+@itemize
+@item If you see this only sporadically, it is harmless and caused by a node sending packets using an old key.
+@item If you see this often and another node is not reachable anymore, then a NAT (masquerading firewall) is changing the source address of UDP packets.
+You can add @samp{TCPOnly = yes} to host configuration files to force all VPN traffic to go over a TCP connection.
+@end itemize
+
+@item Got bad/bogus/unauthorized REQUEST from foo (1.2.3.4 port 12345)
+
+@itemize
+@item Node foo does not have the right public/private keypair.
+Generate new keypairs and distribute them again.
+@item An attacker tries to gain access to your VPN.
+@item A network error caused corruption of metadata sent from foo.
+@end itemize
+
+@end table
+
+@c ==================================================================
+@node Sending bug reports
+@section Sending bug reports
+
+If you really can't find the cause of a problem, or if you suspect tinc is not working right,
+you can send us a bugreport, see @ref{Contact information}.
+Be sure to include the following information in your bugreport:
+
+@itemize
+@item A clear description of what you are trying to achieve and what the problem is.
+@item What platform (operating system, version, hardware architecture) and which version of tinc you use.
+@item If compiling tinc fails, a copy of @file{config.log} and the error messages you get.
+@item Otherwise, a copy of @file{tinc.conf}, @file{tinc-up} and all files in the @file{hosts/} directory.
+@item The output of the commands @samp{ifconfig -a} and @samp{route -n} (or @samp{netstat -rn} if that doesn't work).
+@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
+
+@cindex command line interface
+You can start, stop, control and inspect a running tincd through the tinc
+command. A quick example:
+
+@example
+tinc -n @var{netname} reload
+@end example
+
+@cindex shell
+If tinc is started without a command, it will act as a shell; it will display a
+prompt, and commands can be entered on the prompt. If tinc is compiled with
+libreadline, history and command completion are available on the prompt. One
+can also pipe a script containing commands through tinc. In that case, lines
+starting with a # symbol will be ignored.
+
+@menu
+* tinc runtime options::
+* tinc environment variables::
+* tinc commands::
+* tinc examples::
+* tinc top::
+@end menu
+
+
+@c ==================================================================
+@node tinc runtime options
+@section tinc 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 --pidfile=@var{filename}
+Use the cookie from @var{filename} to authenticate with a running tinc daemon.
+If unspecified, the default is
+@file{@value{localstatedir}/run/tinc.@var{netname}.pid}.
+
+@item --help
+Display a short reminder of runtime options and commands, then terminate.
+
+@item --version
+Output version information and exit.
+
+@end table
+
+@c ==================================================================
+@node tinc environment variables
+@section tinc environment variables
+
+@table @env
+@cindex NETNAME
+@item NETNAME
+If no netname is specified on the command line with the @option{-n} option,
+the value of this environment variable is used.
+@end table
+
+@c ==================================================================
+@node tinc commands
+@section tinc commands
+
+@c from the manpage
+@table @code
+
+@cindex init
+@item init [@var{name}]
+Create initial configuration files and RSA and ECDSA keypairs with default length.
+If no @var{name} for this node is given, it will be asked for.
+
+@cindex get
+@item get @var{variable}
+Print the current value of configuration variable @var{variable}.
+If more than one variable with the same name exists,
+the value of each of them will be printed on a separate line.
+
+@cindex set
+@item set @var{variable} @var{value}
+Set configuration variable @var{variable} to the given @var{value}.
+All previously existing configuration variables with the same name are removed.
+To set a variable for a specific host, use the notation @var{host}.@var{variable}.
+
+@cindex add
+@item add @var{variable} @var{value}
+As above, but without removing any previously existing configuration variables.
+
+@cindex del
+@item del @var{variable} [@var{value}]
+Remove configuration variables with the same name and @var{value}.
+If no @var{value} is given, all configuration variables with the same name will be removed.
+
+@cindex edit
+@item edit @var{filename}
+Start an editor for the given configuration file.
+You do not need to specify the full path to the file.
+
+@cindex export
+@item export
+Export the host configuration file of the local node to standard output.
+
+@cindex export-all
+@item export-all
+Export all host configuration files to standard output.
+
+@cindex import
+@item import [--force]
+Import host configuration file(s) generated by the tinc export command from standard input.
+Already existing host configuration files are not overwritten unless the option --force is used.
+
+@cindex exchange
+@item exchange [--force]
+The same as export followed by import.
+
+@cindex exchange-all
+@item exchange-all [--force]
+The same as export-all followed by import.
+
+@cindex invite
+@item invite @var{name}
+Prepares an invitation for a new node with the given @var{name},
+and prints a short invitation URL that can be used with the join command.
+
+@cindex join
+@item join [@var{URL}]
+Join an existing VPN using an invitation URL created using the invite command.
+If no @var{URL} is given, it will be read from standard input.
+
+@cindex start
+@item start [tincd options]
+Start @samp{tincd}, optionally with the given extra options.
+
+@cindex stop
+@item stop
+Stop @samp{tincd}.
+
+@cindex restart
+@item restart [tincd options]
+Restart @samp{tincd}, optionally with the given extra options.
+
+@cindex reload
+@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.
+
+@cindex pid
+@item pid
+Shows the PID of the currently running @samp{tincd}.
+
+@cindex generate-keys
+@item generate-keys [@var{bits}]
+Generate both RSA and ECDSA keypairs (see below) and exit.
+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).
+
+@cindex generate-ecdsa-keys
+@item generate-ecdsa-keys
+Generate public/private ECDSA keypair and exit.
+
+@cindex generate-rsa-keys
+@item generate-rsa-keys [@var{bits}]
+Generate public/private RSA keypair and exit. If @var{bits} is omitted, the
+default length will be 2048 bits. When saving keys to existing files, tinc
+will not delete the old keys; you have to remove them manually.
+
+@cindex dump
+@item dump [reachable] nodes
+Dump a list of all known nodes in the VPN.
+If the reachable keyword is used, only lists reachable nodes.
+
+@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.
+
+@cindex graph
+@item dump graph | digraph
+Dump a graph of the VPN in dotty format.
+Nodes are colored according to their reachability:
+red nodes are unreachable, orange nodes are indirectly reachable, green nodes are directly reachable.
+Black nodes are either directly or indirectly reachable, but direct reachability has not been tried yet.
+
+@cindex info
+@item info @var{node} | @var{subnet} | @var{address}
+Show information about a particular @var{node}, @var{subnet} or @var{address}.
+If an @var{address} is given, any matching subnet will be shown.
+
+@cindex purge
+@item purge
+Purges all information remembered about unreachable nodes.
+
+@cindex debug
+@item debug @var{level}
+Sets debug level to @var{level}.
+
+@cindex log
+@item log [@var{level}]
+Capture log messages from a running tinc daemon.
+An optional debug level can be given that will be applied only for log messages sent to tinc.
+
+@cindex retry
+@item retry
+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.
+
+@cindex disconnect
+@item disconnect @var{node}
+Closes the meta connection with the given @var{node}.
+
+@cindex top
+@item top
+If tinc is compiled with libcurses support, this will display live traffic statistics for all the known nodes,
+similar to the UNIX top command.
+See below for more information.
+
+@cindex pcap
+@item pcap
+Dump VPN traffic going through the local tinc node in pcap-savefile format to standard output,
+from where it can be redirected to a file or piped through a program that can parse it directly,
+such as tcpdump.
+
+@cindex network [@var{netname}]
+@item network
+If @var{netname} is given, switch to that network.
+Otherwise, display a list of all networks for which configuration files exist.
+
+@end table
+
+@c ==================================================================
+@node tinc examples
+@section tinc examples
+
+Examples of some commands:
+
+@example
+tinc -n vpn dump graph | circo -Txlib
+tinc -n vpn pcap | tcpdump -r -
+tinc -n vpn top
+@end example
+
+Examples of changing the configuration using tinc:
+
+@example
+tinc -n vpn init foo
+tinc -n vpn add Subnet 192.168.1.0/24
+tinc -n vpn add bar.Address bar.example.com
+tinc -n vpn add ConnectTo bar
+tinc -n vpn export | gpg --clearsign | mail -s "My config" vpnmaster@@example.com
+@end example
+
+@c ==================================================================
+@node tinc top
+@section tinc top
+
+@cindex top
+The top command connects to a running tinc daemon and repeatedly queries its per-node traffic counters.
+It displays a list of all the known nodes in the left-most column,
+and the amount of bytes and packets read from and sent to each node in the other columns.
+By default, the information is updated every second.
+The behaviour of the top command can be changed using the following keys:
+
+@table @key
+
+@item s
+Change the interval between updates.
+After pressing the @key{s} key, enter the desired interval in seconds, followed by enter.
+Fractional seconds are honored.
+Intervals lower than 0.1 seconds are not allowed.
+
+@item c
+Toggle between displaying current traffic rates (in packets and bytes per second)
+and cummulative traffic (total packets and bytes since the tinc daemon started).
+
+@item n
+Sort the list of nodes by name.
+
+@item i
+Sort the list of nodes by incoming amount of bytes.
+
+@item I
+Sort the list of nodes by incoming amount of packets.
+
+@item o
+Sort the list of nodes by outgoing amount of bytes.
+
+@item O
+Sort the list of nodes by outgoing amount of packets.
+
+@item t
+Sort the list of nodes by sum of incoming and outgoing amount of bytes.
+
+@item T
+Sort the list of nodes by sum of incoming and outgoing amount of packets.
+
+@item b
+Show amount of traffic in bytes.
+
+@item k
+Show amount of traffic in kilobytes.
+
+@item M
+Show amount of traffic in megabytes.
+
+@item G
+Show amount of traffic in gigabytes.
+
+@item q
+Quit.
+
+@end table
+
+
+@c ==================================================================
+@node Technical information
+@chapter Technical information
+
+
+@menu
+* The connection::
+* The meta-protocol::
+* Security::
+@end menu
+
+
+@c ==================================================================
+@node The connection
+@section The connection
+
+@cindex connection
+Tinc is a daemon that takes VPN data and transmit that to another host
+computer over the existing Internet infrastructure.
+
+@menu
+* The UDP tunnel::
+* The meta-connection::
+@end menu
+
+
+@c ==================================================================
+@node The UDP tunnel
+@subsection The UDP tunnel
+
+@cindex virtual network device
+@cindex frame type
+The data itself is read from a character device file, the so-called
+@emph{virtual network device}. This device is associated with a network
+interface. Any data sent to this interface can be read from the device,
+and any data written to the device gets sent from the interface.
+There are two possible types of virtual network devices:
+`tun' style, which are point-to-point devices which can only handle IPv4 and/or IPv6 packets,
+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
+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.
+Since the latter modes only depend on the link layer information,
+any protocol that runs over Ethernet is supported (for instance IPX and Appletalk).
+However, only `tap' style devices provide this information.
+
+After the destination has been determined,
+the packet will be compressed (optionally),
+a sequence number will be added to the packet,
+the packet will then be encrypted
+and a message authentication code will be appended.
+
+@cindex encapsulating
+@cindex UDP
+When that is done, time has come to actually transport the
+packet to the destination computer. We do this by sending the packet
+over an UDP connection to the destination host. This is called
+@emph{encapsulating}, the VPN packet (though now encrypted) is
+encapsulated in another IP datagram.
+
+When the destination receives this packet, the same thing happens, only
+in reverse. So it checks the message authentication code, decrypts the contents of the UDP datagram,
+checks the sequence number
+and writes the decrypted information to its own virtual network device.
+
+If the virtual network device is a `tun' device (a point-to-point tunnel),
+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
+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.
+
+In switch or hub modes ARP does work so the sender already knows the correct destination MAC address.
+In those modes every interface should have a unique MAC address, so make sure they are not the same.
+Because switch and hub modes rely on MAC addresses to function correctly,
+these modes cannot be used on the following operating systems which don't have a `tap' style virtual network device:
+OpenBSD, NetBSD, Darwin and Solaris.
+
+
+@c ==================================================================
+@node The meta-connection
+@subsection The meta-connection
+
+Having only a UDP connection available is not enough. Though suitable
+for transmitting data, we want to be able to reliably send other
+information, such as routing and session key information to somebody.
+
+@cindex TCP
+TCP is a better alternative, because it already contains protection
+against information being lost, unlike UDP.
+
+So we establish two connections. One for the encrypted VPN data, and one
+for other information, the meta-data. Hence, we call the second
+connection the meta-connection. We can now be sure that the
+meta-information doesn't get lost on the way to another computer.
+
+@cindex data-protocol
+@cindex meta-protocol
+Like with any communication, we must have a protocol, so that everybody
+knows what everything stands for, and how she should react. Because we
+have two connections, we also have two protocols. The protocol used for
+the UDP data is the ``data-protocol,'' the other one is the
+``meta-protocol.''
+
+The reason we don't use TCP for both protocols is that UDP is much
+better for encapsulation, even while it is less reliable. The real
+problem is that when TCP would be used to encapsulate a TCP stream
+that's on the private network, for every packet sent there would be
+three ACKs sent instead of just one. Furthermore, if there would be
+a timeout, both TCP streams would sense the timeout, and both would
+start re-sending packets.
+
+
+@c ==================================================================
+@node The meta-protocol
+@section The meta-protocol
+
+The meta protocol is used to tie all tinc daemons together, and
+exchange information about which tinc daemon serves which virtual
+subnet.
+
+The meta protocol consists of requests that can be sent to the other
+side. Each request has a unique number and several parameters. All
+requests are represented in the standard ASCII character set. It is
+possible to use tools such as telnet or netcat to connect to a tinc
+daemon started with the --bypass-security option
+and to read and write requests by hand, provided that one
+understands the numeric codes sent.
+
+The authentication scheme is described in @ref{Security}. After a
+successful authentication, the server and the client will exchange all the
+information about other tinc daemons and subnets they know of, so that both
+sides (and all the other tinc daemons behind them) have their information
+synchronised.
+
+@cindex ADD_EDGE
+@cindex ADD_SUBNET
+@example
+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
+two nodes exist. The address of the destination node is available so that
+VPN packets can be sent directly to that node.
+
+The ADD_SUBNET messages inform other tinc daemons that certain subnets belong
+to certain nodes. tinc will use it to determine to which node a VPN packet has
+to be sent.
+
+@cindex DEL_EDGE
+@cindex DEL_SUBNET
+@example
+message
+------------------------------------------------------------------
+DEL_EDGE node1 node2
+ | +----> name of destination node
+ +----------> name of source node
+
+DEL_SUBNET node 192.168.1.0/24
+ | | +--> prefixlength
+ | +--------> network address
+ +------------------> owner of this subnet
+------------------------------------------------------------------
+@end example
+
+In case a connection between two daemons is closed or broken, DEL_EDGE messages
+are sent to inform the other daemons of that fact. Each daemon will calculate a
+new route to the the daemons, or mark them unreachable if there isn't any.
+
+@cindex REQ_KEY
+@cindex ANS_KEY
+@cindex KEY_CHANGED
+@example
+message
+------------------------------------------------------------------
+REQ_KEY origin destination
+ | +--> name of the tinc daemon it wants the key from
+ +----------> name of the daemon that wants the key
+
+ANS_KEY origin destination 4ae0b0a82d6e0078 91 64 4
+ | | \______________/ | | +--> MAC length
+ | | | | +-----> digest algorithm
+ | | | +--------> cipher algorithm
+ | | +--> 128 bits key
+ | +--> name of the daemon that wants the key
+ +----------> name of the daemon that uses this key
+
+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
+because it would generate a lot of traffic on VPNs with many daemons, and
+chances are that not every tinc daemon will ever send a packet to every
+other daemon. Instead, if a daemon needs a key it sends a request for it
+via the meta connection of the nearest hop in the direction of the
+destination.
+
+@cindex PING
+@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
+failures or a crash can cause a daemon to be killed without properly
+shutting down the TCP connection, this is necessary to keep an up to date
+connection list. PINGs are sent at regular intervals, except when there
+is also some other traffic. A little bit of salt (random data) is added
+with each PING and PONG message, to make sure that long sequences of PING/PONG
+messages without any other traffic won't result in known plaintext.
+
+This basically covers what is sent over the meta connection by tinc.
+
+
+@c ==================================================================
+@node Security
+@section Security
+
+@cindex TINC
+@cindex Cabal
+Tinc got its name from ``TINC,'' short for @emph{There Is No Cabal}; the
+alleged Cabal was/is an organisation that was said to keep an eye on the
+entire Internet. As this is exactly what you @emph{don't} want, we named
+the tinc project after TINC.
+
+@cindex SVPN
+But in order to be ``immune'' to eavesdropping, you'll have to encrypt
+your data. Because tinc is a @emph{Secure} VPN (SVPN) daemon, it does
+exactly that: encrypt.
+However, encryption in itself does not prevent an attacker from modifying the encrypted data.
+Therefore, tinc also authenticates the data.
+Finally, tinc uses sequence numbers (which themselves are also authenticated) to prevent an attacker from replaying valid packets.
+
+Since version 1.1pre3, tinc has two protocols used to protect your data; the legacy protocol, and the new Simple Peer-to-Peer Security (SPTPS) protocol.
+The SPTPS protocol is designed to address some weaknesses in the legacy protocol.
+The new authentication protocol is used when two nodes connect to each other that both have the ExperimentalProtocol option set to yes,
+otherwise the legacy protocol will be used.
+
+@menu
+* Legacy authentication protocol::
+* Simple Peer-to-Peer Security::
+* Encryption of network packets::
+* Security issues::
+@end menu
+
+
+@c ==================================================================
+@node Legacy authentication protocol
+@subsection Legacy authentication protocol
+
+@cindex legacy authentication protocol
+
+@cindex ID
+@cindex META_KEY
+@cindex CHALLENGE
+@cindex CHAL_REPLY
+@cindex ACK
+@example
+daemon message
+--------------------------------------------------------------------------
+client <attempts connection>
+
+server <accepts connection>
+
+client ID client 17.2
+ | | +-> minor protocol version
+ | +----> major protocol version
+ +--------> name of tinc daemon
+
+server ID server 17.2
+ | | +-> minor protocol version
+ | +----> major protocol version
+ +--------> name of tinc daemon
+
+client META_KEY 94 64 0 0 5f0823a93e35b69e...7086ec7866ce582b
+ | | | | \_________________________________/
+ | | | | +-> RSAKEYLEN bits totally random string S1,
+ | | | | encrypted with server's public RSA key
+ | | | +-> compression level
+ | | +---> MAC length
+ | +------> digest algorithm NID
+ +---------> cipher algorithm NID
+
+server META_KEY 94 64 0 0 6ab9c1640388f8f0...45d1a07f8a672630
+ | | | | \_________________________________/
+ | | | | +-> RSAKEYLEN bits totally random string S2,
+ | | | | encrypted with client's public RSA key
+ | | | +-> compression level
+ | | +---> MAC length
+ | +------> digest algorithm NID
+ +---------> cipher algorithm NID
+--------------------------------------------------------------------------
+@end example
+
+The protocol allows each side to specify encryption algorithms and parameters,
+but in practice they are always fixed, since older versions of tinc did not
+allow them to be different from the default values. The cipher is always
+Blowfish in OFB mode, the digest is SHA1, but the MAC length is zero and no
+compression is used.
+
+From now on:
+@itemize
+@item the client will symmetrically encrypt outgoing traffic using S1
+@item the server will symmetrically encrypt outgoing traffic using S2
+@end itemize
+
+@example
+--------------------------------------------------------------------------
+client CHALLENGE da02add1817c1920989ba6ae2a49cecbda0
+ \_________________________________/
+ +-> CHALLEN bits totally random string H1
+
+server CHALLENGE 57fb4b2ccd70d6bb35a64c142f47e61d57f
+ \_________________________________/
+ +-> CHALLEN bits totally random string H2
+
+client CHAL_REPLY 816a86
+ +-> 160 bits SHA1 of H2
+
+server CHAL_REPLY 928ffe
+ +-> 160 bits SHA1 of H1
+
+After the correct challenge replies are received, both ends have proved
+their identity. Further information is exchanged.
+
+client ACK 655 123 0
+ | | +-> options
+ | +----> estimated weight
+ +--------> listening port of client
+
+server ACK 655 321 0
+ | | +-> options
+ | +----> estimated weight
+ +--------> listening port of server
+--------------------------------------------------------------------------
+@end example
+
+This legacy authentication protocol has several weaknesses, pointed out by security export Peter Gutmann.
+First, data is encrypted with RSA without padding.
+Padding schemes are designed to prevent attacks when the size of the plaintext is not equal to the size of the RSA key.
+Tinc always encrypts random nonces that have the same size as the RSA key, so we do not believe this leads to a break of the security.
+There might be timing or other side-channel attacks against RSA encryption and decryption, tinc does not employ any protection against those.
+Furthermore, both sides send identical messages to each other, there is no distinction between server and client,
+which could make a MITM attack easier.
+However, no exploit is known in which a third party who is not already trusted by other nodes in the VPN could gain access.
+Finally, the RSA keys are used to directly encrypt the session keys, which means that if the RSA keys are compromised, it is possible to decrypt all previous VPN traffic.
+In other words, the legacy protocol does not provide perfect forward secrecy.
+
+@c ==================================================================
+@node Simple Peer-to-Peer Security
+@subsection Simple Peer-to-Peer Security
+@cindex SPTPS
+
+The SPTPS protocol is designed to address the weaknesses in the legacy protocol.
+SPTPS is based on TLS 1.2, but has been simplified: there is no support for exchanging public keys, and there is no cipher suite negotiation.
+Instead, SPTPS always uses a very strong cipher suite:
+peers authenticate each other using 521 bits ECC keys,
+Diffie-Hellman using ephemeral 521 bits ECC keys is used to provide perfect forward secrecy (PFS),
+AES-256-CTR is used for encryption, and HMAC-SHA-256 for message authentication.
+
+Similar to TLS, messages are split up in records.
+A complete logical record contains the following information:
+
+@itemize
+@item uint32_t seqno (network byte order)
+@item uint16_t length (network byte order)
+@item uint8_t type
+@item opaque data[length]
+@item opaque hmac[HMAC_SIZE] (HMAC over all preceding fields)
+@end itemize
+
+Depending on whether SPTPS records are sent via TCP or UDP, either the seqno or the length field is omitted on the wire
+(but they are still included in the calculation of the HMAC);
+for TCP packets are guaranteed to arrive in-order so we can infer the seqno, but packets can be split or merged, so we still need the length field to determine the boundaries between records;
+for UDP packets we know that there is exactly one record per packet, and we know the length of a packet, but packets can be dropped, duplicated and/or reordered, so we need to include the seqno.
+
+The type field is used to distinguish between application records or handshake records.
+Types 0 to 127 are application records, type 128 is a handshake record, and types 129 to 255 are reserved.
+
+Before the initial handshake, no fields are encrypted, and the HMAC field is not present.
+After the authentication handshake, the length (if present), type and data fields are encrypted, and the HMAC field is present.
+For UDP packets, the seqno field is not encrypted, as it is used to determine the value of the counter used for encryption.
+
+The authentication consists of an exchange of Key EXchange, SIGnature and ACKnowledge messages, transmitted using type 128 records.
+
+Overview:
+
+@example
+Initiator Responder
+---------------------
+KEX ->
+ <- KEX
+SIG ->
+ <- SIG
+
+...encrypt and HMAC using session keys from now on...
+
+App ->
+ <- App
+...
+ ...
+
+...key renegotiation starts here...
+
+KEX ->
+ <- KEX
+SIG ->
+ <- SIG
+ACK ->
+ <- ACK
+
+...encrypt and HMAC using new session keys from now on...
+
+App ->
+ <- App
+...
+ ...
+---------------------
+@end example
+
+Note that the responder does not need to wait before it receives the first KEX message,
+it can immediately send its own once it has accepted an incoming connection.
+
+Key EXchange message:
+
+@itemize
+@item uint8_t kex_version (always 0 in this version of SPTPS)
+@item opaque nonce[32] (random number)
+@item opaque ecdh_key[ECDH_SIZE]
+@end itemize
+
+SIGnature message:
+
+@itemize
+@item opaque ecdsa_signature[ECDSA_SIZE]
+@end itemize
+
+ACKnowledge message:
+
+@itemize
+@item empty (only sent after key renegotiation)
+@end itemize
+
+Remarks:
+
+@itemize
+@item At the start, both peers generate a random nonce and an Elliptic Curve public key and send it to the other in the KEX message.
+@item After receiving the other's KEX message, both KEX messages are concatenated (see below),
+ and the result is signed using ECDSA.
+ The result is sent to the other.
+@item After receiving the other's SIG message, the signature is verified.
+ If it is correct, the shared secret is calculated from the public keys exchanged in the KEX message using the Elliptic Curve Diffie-Helman algorithm.
+@item The shared secret key is expanded using a PRF.
+ Both nonces and the application specific label are also used as input for the PRF.
+@item An ACK message is sent only when doing key renegotiation, and is sent using the old encryption keys.
+@item The expanded key is used to key the encryption and HMAC algorithms.
+@end itemize
+
+The signature is calculated over this string:
+
+@itemize
+@item uint8_t initiator (0 = local peer, 1 = remote peer is initiator)
+@item opaque remote_kex_message[1 + 32 + ECDH_SIZE]
+@item opaque local_kex_message[1 + 32 + ECDH_SIZE]
+@item opaque label[label_length]
+@end itemize
+
+The PRF is calculated as follows:
+
+@itemize
+@item A HMAC using SHA512 is used, the shared secret is used as the key.
+@item For each block of 64 bytes, a HMAC is calculated. For block n: hmac[n] =
+ HMAC_SHA512(hmac[n - 1] + seed)
+@item For the first block (n = 1), hmac[0] is given by HMAC_SHA512(zeroes + seed),
+ where zeroes is a block of 64 zero bytes.
+@end itemize
+
+The seed is as follows:
+
+@itemize
+@item const char[13] "key expansion"
+@item opaque responder_nonce[32]
+@item opaque initiator_nonce[32]
+@item opaque label[label_length]
+@end itemize
+
+The expanded key is used as follows:
+
+@itemize
+@item opaque responder_cipher_key[CIPHER_KEYSIZE]
+@item opaque responder_digest_key[DIGEST_KEYSIZE]
+@item opaque initiator_cipher_key[CIPHER_KEYSIZE]
+@item opaque initiator_digest_key[DIGEST_KEYSIZE]
+@end itemize
+
+Where initiator_cipher_key is the key used by session initiator to encrypt
+messages sent to the responder.
+
+When using 521 bits EC keys, the AES-256-CTR cipher and HMAC-SHA-256 digest algorithm,
+the sizes are as follows:
+
+@example
+ECDH_SIZE: 67 (= ceil(521/8) + 1)
+ECDSA_SIZE: 141 (= 2 * ceil(521/8) + 9)
+CIPHER_KEYSIZE: 48 (= 256/8 + 128/8)
+DIGEST_KEYSIZE: 32 (= 256/8)
+@end example
+
+Note that the cipher key also includes the initial value for the counter.
+
+@c ==================================================================
+@node Encryption of network packets
+@subsection Encryption of network packets
+@cindex encryption
+
+A data packet can only be sent if the encryption key is known to both
+parties, and the connection is activated. If the encryption key is not
+known, a request is sent to the destination using the meta connection
+to retrieve it.
+
+@cindex UDP
+The UDP packets can be either encrypted with the legacy protocol or with SPTPS.
+In case of the legacy protocol, the UDP packet containing the network packet from the VPN has the following layout:
+
+@example
+... | IP header | UDP header | seqno | VPN packet | MAC | UDP trailer
+ \___________________/\_____/
+ | |
+ V +---> digest algorithm
+ Encrypted with symmetric cipher
+@end example
+
+
+
+
+So, the entire VPN packet is encrypted using a symmetric cipher, including a 32 bits
+sequence number that is added in front of the actual VPN packet, to act as a unique
+IV for each packet and to prevent replay attacks. A message authentication code
+is added to the UDP packet to prevent alteration of packets.
+Tinc by default encrypts network packets using Blowfish with 128 bit keys in CBC mode
+and uses 4 byte long message authentication codes to make sure
+eavesdroppers cannot get and cannot change any information at all from the
+packets they can intercept. The encryption algorithm and message authentication
+algorithm can be changed in the configuration. The length of the message
+authentication codes is also adjustable. The length of the key for the
+encryption algorithm is always the default length used by OpenSSL.
+
+The SPTPS protocol is described in @ref{Simple Peer-to-Peer Security}.
+For comparison, this is how SPTPS UDP packets look:
+
+@example
+... | IP header | UDP header | seqno | type | VPN packet | MAC | UDP trailer
+ \__________________/\_____/
+ | |
+ V +---> digest algorithm
+ Encrypted with symmetric cipher
+@end example
+
+The difference is that the seqno is not encrypted, since the encryption cipher is used in CTR mode,
+and therefore the seqno must be known before the packet can be decrypted.
+Furthermore, the MAC is never truncated.
+The SPTPS protocol always uses the AES-256-CTR cipher and HMAC-SHA-256 digest,
+this cannot be changed.
+
+
+@c ==================================================================
+@node Security issues
+@subsection Security issues
+
+In August 2000, we discovered the existence of a security hole in all versions
+of tinc up to and including 1.0pre2. This had to do with the way we exchanged
+keys. Since then, we have been working on a new authentication scheme to make
+tinc as secure as possible. The current version uses the OpenSSL library and
+uses strong authentication with RSA keys.
+
+On the 29th of December 2001, Jerome Etienne posted a security analysis of tinc
+1.0pre4. Due to a lack of sequence numbers and a message authentication code
+for each packet, an attacker could possibly disrupt certain network services or
+launch a denial of service attack by replaying intercepted packets. The current
+version adds sequence numbers and message authentication codes to prevent such
+attacks.
+
+On the 15th of September 2003, Peter Gutmann posted a security analysis of tinc
+1.0.1. He argues that the 32 bit sequence number used by tinc is not a good IV,
+that tinc's default length of 4 bytes for the MAC is too short, and he doesn't
+like tinc's use of RSA during authentication. We do not know of a security hole
+in the legacy protocol of tinc, but it is not as strong as TLS or IPsec.
+
+This version of tinc comes with an improved protocol, called Simple Peer-to-Peer Security,
+which aims to be as strong as TLS with one of the strongest cipher suites.
+
+Cryptography is a hard thing to get right. We cannot make any
+guarantees. Time, review and feedback are the only things that can
+prove the security of any cryptographic product. If you wish to review
+tinc or give us feedback, you are stronly encouraged to do so.
+
+
+@c ==================================================================
+@node Platform specific information
+@chapter Platform specific information
+
+@menu
+* Interface configuration::
+* Routes::
+@end menu
+
+@c ==================================================================
+@node Interface configuration
+@section Interface configuration
+
+When configuring an interface, one normally assigns it an address and a
+netmask. The address uniquely identifies the host on the network attached to
+the interface. The netmask, combined with the address, forms a subnet. It is
+used to add a route to the routing table instructing the kernel to send all
+packets which fall into that subnet to that interface. Because all packets for
+the entire VPN should go to the virtual network interface used by tinc, the
+netmask should be such that it encompasses the entire VPN.
+
+For IPv4 addresses:
+
+@multitable {Darwin (MacOS/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{ip addr add} @var{address}@code{/}@var{prefixlength} @code{dev} @var{interface}
+@item FreeBSD
+@tab @code{ifconfig} @var{interface} @var{address} @code{netmask} @var{netmask}
+@item OpenBSD
+@tab @code{ifconfig} @var{interface} @var{address} @code{netmask} @var{netmask}
+@item NetBSD
+@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)
+@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}
+@end multitable
+
+For IPv6 addresses:
+
+@multitable {Darwin (MacOS/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} @var{address} @code{prefixlen} @var{prefixlength}
+@item OpenBSD
+@tab @code{ifconfig} @var{interface} @code{inet6} @var{address} @code{prefixlen} @var{prefixlength}
+@item NetBSD
+@tab @code{ifconfig} @var{interface} @code{inet6} @var{address} @code{prefixlen} @var{prefixlength}
+@item Solaris
+@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
+@tab @code{netsh interface ipv6 add address} @var{interface} @code{static} @var{address}/@var{prefixlength}
+@end multitable
+
+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}
+@item OpenBSD
+@tab @code{ifconfig} @var{interface} @code{link0}
+@end multitable
+
+On Linux, it is possible to create a persistent tun/tap interface which will
+continue to exist even if tinc quit, although this is normally not required.
+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}
+@item Linux
+@tab @code{ip tuntap add dev} @var{interface} @code{mode} @var{tun|tap} @code{user} @var{username}
+@end multitable
+
+@c ==================================================================
+@node Routes
+@section Routes
+
+In some cases it might be necessary to add more routes to the virtual network
+interface. There are two ways to indicate which interface a packet should go
+to, one is to use the name of the interface itself, another way is to specify
+the (local) address that is assigned to that interface (@var{local_address}). The
+former way is unambiguous and therefore preferable, but not all platforms
+support this.
+
+Adding routes to IPv4 subnets:
+
+@multitable {Darwin (MacOS/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{ip route add} @var{network_address}@code{/}@var{prefixlength} @code{dev} @var{interface}
+@item FreeBSD
+@tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @var{local_address}
+@item OpenBSD
+@tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @var{local_address}
+@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:
+
+@multitable {Darwin (MacOS/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{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
+
+
+@c ==================================================================
+@node About us
+@chapter About us
+
+
+@menu
+* Contact information::
+* Authors::
+@end menu
+
+
+@c ==================================================================
+@node Contact information
+@section Contact information
+
+@cindex website
+Tinc's website is at @url{http://www.tinc-vpn.org/},
+this server is located in the Netherlands.
+
+@cindex IRC
+We have an IRC channel on the FreeNode and OFTC IRC networks. Connect to
+@uref{http://www.freenode.net/, irc.freenode.net}
+or
+@uref{http://www.oftc.net/, irc.oftc.net}
+and join channel #tinc.
+
+
+@c ==================================================================
+@node Authors
+@section Authors
+
+@table @asis
+@item Ivo Timmermans (zarq)
+@item Guus Sliepen (guus) (@email{guus@@tinc-vpn.org})
+@end table
+
+We have received a lot of valuable input from users. With their help,
+tinc has become the flexible and robust tool that it is today. We have
+composed a list of contributions, in the file called @file{THANKS} in
+the source distribution.
+
+
+@c ==================================================================
+@node Concept Index
+@unnumbered Concept Index
+
+@c ==================================================================
+@printindex cp
+
+
+@c ==================================================================
+@contents
+@bye
projects / meshlink / blobdiff