X-Git-Url: https://tinc-vpn.org/git/browse?p=tinc;a=blobdiff_plain;f=doc%2Ftinc.texi;h=5bd4c6c2a4524ee4025f69b6afd8048572811fdd;hp=46af02dd05a02aaa14653f195e76753240cd3caf;hb=54a30e30ad41d7c0e73fcc4e6ff23c3e85af75c4;hpb=1243156a5e03a666b36bc4400f1402243a85c9a7 diff --git a/doc/tinc.texi b/doc/tinc.texi index 46af02dd..5bd4c6c2 100644 --- a/doc/tinc.texi +++ b/doc/tinc.texi @@ -1,362 +1,795 @@ \input texinfo @c -*-texinfo-*- +@c $Id$ @c %**start of header @setfilename tinc.info @settitle tinc Manual @setchapternewpage odd @c %**end of header +@include tincinclude.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. -This is the info manual for tinc, a Virtual Private Network daemon. +Copyright @copyright{} 1998-2004 Ivo Timmermans +, Guus Sliepen and +Wessel Dankers . -Copyright 1998 Ivo Timmermans +$Id$ - 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 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. +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 @titlepage @title tinc Manual @subtitle Setting up a Virtual Private Network with tinc -@author Ivo Timmermans +@author Ivo Timmermans and Guus Sliepen @page @vskip 0pt plus 1filll -Copyright @copyright{} 1998 Ivo Timmermans +@cindex copyright +This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon. + +Copyright @copyright{} 1998-2004 Ivo Timmermans +, Guus Sliepen and +Wessel Dankers . + +$Id$ - 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 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. +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 +@ifinfo @c ================================================================== -@node Top, Introduction, (dir), (dir) +@node Top +@top Top @menu -* Introduction:: Introduction -* Configuring a Linux system:: Before compiling tinc -* Installing tinc:: -* Configuring tinc:: -* Running tinc:: -* Technical information:: -* About us:: +* Introduction:: +* Preparations:: +* Installation:: +* Configuration:: +* Running tinc:: +* Technical information:: +* Platform specific information:: +* About us:: * Concept Index:: All used terms explained @end menu +@end ifinfo @c ================================================================== -@node Introduction, Configuring a Linux system, Top, Top +@node Introduction @chapter Introduction -@c straight from the www page - -tinc is a Virtual Private Network (VPN) daemon that uses tunneling and +@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. - -This tunneling allows VPN sites to share information with eachother +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 +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 -* VPNs:: Virtual Private Networks in general -* tinc:: about tinc +* Virtual Private Networks:: +* tinc:: About tinc +* Supported platforms:: @end menu @c ================================================================== -@node VPNs, tinc, Introduction, Introduction +@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 +by a few elected computers that participate. This goal is achievable in more than just one way. @cindex private -For instance, a VPN can consist of a single standalone ethernet LAN. Or -even two computers hooked up using a nullmodem cable@footnote{Though -discussable, I think it qualifies as a VPN.}. In these cases, it is -obvious that the network is @emph{private}. But there is another type -of VPN, the type tinc was made for. +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 -tinc uses normal IP datagrams to encapsulate data that goes over the VPN -network link. In this case it's also clear that the network is -@emph{virtual}, because no direct network link has to exist between to -participants. - -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 +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 singe 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, , VPNs, Introduction +@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 @emph{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 @samp{vpnd}. +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 hase becom largely +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. -A lot can---and will be---changed. I have a few things that I'd 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 +@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 +Meanwhile, we're always open-minded towards new ideas. And we're available too. @c ================================================================== -@node Configuring a Linux system, Installing tinc, Introduction, Top -@chapter Configuring a Linux system +@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 a Linux system is configured -for the use of tinc. +This chapter contains information on how to prepare your system to +support tinc. @menu -* Configuring the kernel:: -* Files Needed:: -* Setting up the devices:: +* Configuring the kernel:: +* Libraries:: @end menu @c ================================================================== -@node Configuring the kernel, Files Needed, Configuring a Linux system, Configuring a Linux system +@node Configuring the kernel @section Configuring the kernel -Since this particular implementation only runs on 2.1 or higher Linux -kernels, you should grab one (2.2 is current at this time). A 2.0 port -is not really possible, unless someone tells me someone ported the -ethertap and netlink devices back to 2.0. +@menu +* Configuration of Linux kernels 2.1.60 up to 2.4.0:: +* Configuration of Linux kernels 2.4.0 and higher:: +* 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 -If you are unfamiliar with the process of configuring and compiling a -new kernel, you should read the -@uref{http://howto.linuxberg.com/LDP/HOWTO/Kernel-HOWTO.html, Kernel -HOWTO} first. Do that now! -Here are the options you have to turn on/off when configuring a new -kernel. +@c ================================================================== +@node Configuration of Linux kernels 2.1.60 up to 2.4.0 +@subsection Configuration of Linux kernels 2.1.60 up to 2.4.0 + +@cindex ethertap +For kernels up to 2.4.0, you need a kernel that supports the ethertap device. +Most distributions come with kernels that already support this. +If not, here are the options you have to turn on when configuring a new kernel: @example Code maturity level options [*] Prompt for development and/or incomplete code/drivers Networking options [*] Kernel/User netlink socket -<*> Netlink device emulation + Netlink device emulation Network device support -<*> Ethertap network tap + Ethertap network tap @end example -Any other options not mentioned here are not relevant to tinc. If you -decide to build any of these as dynamic kernel modules, it's a good idea -to add these lines to @file{/etc/modules.conf}. +If you want to run more than one instance of tinc or other programs that use +the ethertap, you have to compile the ethertap driver as a module, otherwise +you can also choose to compile it directly into the kernel. + +If you decide to build any of these as dynamic kernel modules, it's a good idea +to add these lines to @file{/etc/modules.conf}: @example -alias tap0 ethertap alias char-major-36 netlink_dev +alias tap0 ethertap +options tap0 -o tap0 unit=0 +alias tap1 ethertap +options tap1 -o tap1 unit=1 +... +alias tap@emph{N} ethertap +options tap@emph{N} -o tap@emph{N} unit=@emph{N} @end example -Finally, after having set up other options, build the kernel and boot -it. Unfortunately it's not possible to insert these modules in a running -kernel. +Add as much alias/options lines as necessary. @c ================================================================== -@node Files Needed, Setting up the devices, Configuring the kernel, Configuring a Linux system -@section Files Needed +@node Configuration of Linux kernels 2.4.0 and higher +@subsection Configuration of Linux kernels 2.4.0 and higher -@subsubheading Device files +@cindex Universal tun/tap +For kernels 2.4.0 and higher, you need a kernel that supports the Universal tun/tap device. +Most distributions come with kernels that already support this. +Here are the options you have to turn on when configuring a new kernel: -First, you'll need the special device file(s) that form the interface -between the kernel and the daemon. +@example +Code maturity level options +[*] Prompt for development and/or incomplete code/drivers +Network device support + 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 have an early 2.4 kernel, you can choose both the tun/tap driver and the +`Ethertap network tap' device. This latter is marked obsolete, and chances are +that it won't even function correctly anymore. Make sure you select the +universal tun/tap driver. + +If you decide to build the tun/tap driver as a kernel module, add these lines +to @file{/etc/modules.conf}: @example -mknod -m 600 /dev/tap0 c 36 16 -chown 0.0 /dev/tap0 +alias char-major-10-200 tun @end example -The permissions now will be such that only the super user may read/write -to this file. You'd want this, because otherwise eavesdropping would -become a tad too easy. This does, however, imply that you'd have to run -tincd as root. -If you want to, you may also create more device files, which would be -numbered 0...15, with minor device numbers 16...31. They all should be -owned by root and have permission 600. +@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. +Using tap devices is recommended. -@subsubheading @file{/etc/networks} -You may add a line to @file{/etc/networks} so that your vpn will get a -symoblic name. For example: +@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. +This should work with tinc. + + +@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://www-user.rhrk.uni-kl.de/~nissler/tuntap/}, +which supports both tun and tap style devices, +and also the driver from from @uref{http://chrisp.de/en/projects/tunnel.html}. +The former driver is recommended. +The tunnel driver must be loaded before starting tinc with the following command: @example -myvpn 10.0.0.0 +kmodload tunnel @end example -@subsubheading @file{/etc/services} +@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. -You may add this line to @file{/etc/services}. The effect is that you -may supply a @samp{vpn} as a valid port number to some programs. The -number 655 is registered with the IANA. + +@c ================================================================== +@node Libraries +@section Libraries + +@cindex requirements +@cindex libraries +Before you can configure or build tinc, you need to have the OpenSSL, +zlib and lzo 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:: +@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 without having OpenSSL +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 -tinc 655/tcp TINC -tinc 655/udp TINC -# Ivo Timmermans +--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 Setting up the devices, , Files Needed, Configuring a Linux system -@section Setting up the devices +@node zlib +@subsection zlib -Before you can start transmitting data over the tinc tunnel, you must -set up the ethertap network devices. +@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 configuring +tinc for build. Support for running tinc without having zlib +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 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). -First, decide which IP addresses you want to have associated with these -devices, and what network mask they must have. You also need these -numbers when you are going to configure tinc itself. @xref{Configuring -tinc}. -It doesn't matter much which part you do first, setting up the network -devices or configure tinc. But they both have to be done before you try -to start a tincd. +@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 configuring +tinc for build. Support for running tinc without having lzo +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 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 +@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 -The actual setup of the ethertap device is quite simple, just repeat -after me: + +@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://fink.sourceforge.net/}. + +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 +First, you'll need the special device file(s) that form the interface +between the kernel and the daemon. + +The permissions for these files have to be such that only the super user +may read/write to this file. You'd want this, because otherwise +eavesdropping would become a bit too easy. This does, however, imply +that you'd have to run tincd as root. + +If you use Linux and have a kernel version prior to 2.4.0, you have to make the +ethertap devices: @example -ifconfig tap@emph{n} hw ether fe:fd:@emph{xx}:@emph{xx}:@emph{xx}:@emph{xx} +mknod -m 600 /dev/tap0 c 36 16 +mknod -m 600 /dev/tap1 c 36 17 +... +mknod -m 600 /dev/tap@emph{N} c 36 @emph{N+16} @end example -The @emph{n} here is the number of the ethertap device you want to -use. It should be the same @emph{n} as the one you use for -@file{/dev/tap@emph{n}}. The @emph{xx}s are four hexadecimal numbers -(0--ff). With previous versions of tincd, it didn't matter what they -were. But newer kernels require properly set up ehternet addresses. -In fact, the old behaviour was wrong. It is required that the @emph{xx}s -match MyOwnVPNIP. +There is a maximum of 16 ethertap devices. + +If you use the universal tun/tap driver, you have to create the +following device file (unless it already exist): @example -ifconfig tap@emph{n} @emph{IP} netmask @emph{mask} +mknod -m 600 /dev/tun c 10 200 @end example -This will activate the device with an IP address @emph{IP} with network -mask @emph{mask}. +If you use Linux, and you run the new 2.4 kernel using the devfs filesystem, +then the tun/tap device will probably be automatically generated as +@file{/dev/net/tun}. +Unlike the ethertap device, you do not need multiple device files if +you are planning to run multiple tinc daemons. @c ================================================================== -@node Installing tinc, Configuring tinc, Configuring a Linux system, Top -@chapter Installing tinc +@node Other files +@subsection Other files -First download it. This is the -@uref{http://tinc.nl.linux.org/download.html, download -page}, which has the checksums of these files listed; you may wish to -check these with md5sum before continuing. +@subsubheading @file{/etc/networks} -tinc comes in a handy autoconf/automake package, which you can just -treat the same as any other package. Which is just untar it, type -`configure' and then `make'. +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 +@end example -More detailed instructions are in the file @file{INSTALL}, which is -included in the source distribution. + +@c +@c +@c +@c +@c Configuring tinc +@c +@c +@c +@c @c ================================================================== -@node Configuring tinc, Running tinc, Installing tinc, Top -@chapter Configuring tinc +@node Configuration +@chapter Configuration @menu -* Multiple networks:: -* How connections work:: -* Configuration file:: -* Example:: +* Configuration introduction:: +* Multiple networks:: +* How connections work:: +* Configuration files:: +* Generating keypairs:: +* 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.linuxdoc.org/LDP/nag2/, Linux Network Administrators Guide}. + +If you have everything clearly pictured in your mind, +proceed in the following order: +First, generate the configuration files (@file{tinc.conf}, your host configuration file, @file{tinc-up} and perhaps @file{tinc-down}). +Then generate the keypairs. +Finally, distribute the host configuration files. +These steps are described in the subsections below. + @c ================================================================== -@node Multiple networks, How connections work, Configuring tinc, Configuring tinc +@node Multiple networks @section Multiple networks -@c from the manpage +@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 sites of your VPN, +but it is recommended that you choose one anyway. -It is perfectly ok for you to run more than one tinc daemon. -However, in its default form, you will soon notice that you can't use -two different configuration files without the -c option. - -We have thought of another way of dealing with this: network names. This -means that you call tincd with the -n argument, which will assign a name -to this daemon. +We will asume you use a netname throughout this document. +This means that you call tincd with the -n argument, +which will assign a netname to this daemon. The effect of this is that the daemon will set its configuration -``root'' to /etc/tinc/nn/, where nn is your argument to the -n -option. You'll notice that it appears in syslog as ``tincd.nn''. +root to @file{@value{sysconfdir}/tinc/@var{netname}/}, where @var{netname} is your argument to the -n +option. You'll notice that it appears in syslog as @file{tinc.@var{netname}}. However, it is not strictly necessary that you call tinc with the -n -option. In this case, the network name would just be empty, and it will -be used as such. tinc now looks for files in /etc/tinc/, instead of -/etc/tinc/nn/; the configuration file should be /etc/tinc/tincd.conf, -and the passphrases are now expected to be in /etc/tinc/passphrases/. +option. In this case, the network name would just be empty, and it will +be used as such. tinc now looks for files in @file{@value{sysconfdir}/tinc/}, instead of +@file{@value{sysconfdir}/tinc/@var{netname}/}; the configuration file should be @file{@value{sysconfdir}/tinc/tinc.conf}, +and the host configuration files are now expected to be in @file{@value{sysconfdir}/tinc/hosts/}. But it is highly recommended that you use this feature of tinc, because -it will be so much clearer whom your daemon talks to. Hence, we will +it will be so much clearer whom your daemon talks to. Hence, we will assume that you use it. @c ================================================================== -@node How connections work, Configuration file, Multiple networks, Configuring tinc +@node How connections work @section How connections work -Before going on, first a bit on how tinc sees connections. - -When tinc starts up, it reads in the configuration file and parses the -commandline options. If it sees a `ConnectTo' value in the file, it will -try to connect to it, on the given port. If this fails, tinc exits. +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. @c ================================================================== -@node Configuration file, Example, How connections work, Configuring tinc -@section Configuration file +@node Configuration files +@section Configuration files The actual configuration of the daemon is done in the file -@file{/etc/tinc/nn/tincd.conf}. +@file{@value{sysconfdir}/tinc/@var{netname}/tinc.conf} and at least one other file in the directory +@file{@value{sysconfdir}/tinc/@var{netname}/hosts/}. -This file consists of comments (lines started with a #) or assignments +These file consists of comments (lines started with a #) or assignments in the form of @example @@ -364,92 +797,466 @@ 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 +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. +In this section all valid variables are listed in alphabetical order. +The default value is given between parentheses, +other comments are between square brackets. + @menu -* Variables:: +* Main configuration variables:: +* Host configuration variables:: +* Scripts:: +* How to configure:: @end menu + @c ================================================================== -@node Variables, , Configuration file, Configuration file -@subsection Variables +@node Main configuration variables +@subsection Main configuration variables -Here are all valid variables, listed in alphabetical order: +@table @asis +@cindex AddressFamily +@item AddressFamily = (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 BindToAddress +@item BindToAddress = <@var{address}> [experimental] +If your computer has more than one IPv4 or IPv6 address, tinc +will by default listen on all of them for incoming connections. +It is possible to bind only to a single address with this variable. + +This option may not work on all platforms. + +@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. + +@cindex BlockingTCP +@item BlockingTCP = (no) [experimental] +This options selects whether TCP connections, when established, should use blocking writes. +When turned off, tinc will never block when a TCP connection becomes congested, +but will have to terminate that connection instead. +If turned on, tinc will not terminate connections but will block, +thereby unable to process data to/from other connections. +Turn this option on if you also use TCPOnly and tinc terminates connections frequently. + +@cindex ConnectTo +@item ConnectTo = <@var{name}> +Specifies which other tinc daemon to connect to on startup. +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 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 Hostnames +@item Hostnames = (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. + +@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 Mode +@item Mode = (router) +This option selects the way packets are routed to other daemons. -@c straight from the manpage @table @asis -@item AllowConnect = (yes|no) -If set to yes, anyone may try to connect to you. If you set this to no, -no incoming connections will be accepted. This does not affect the -outgoing connections. - -@item ConnectPort = port -Connect to the upstream host (given with the ConnectTo directive) on -port port. port may be given in decimal (default), octal (when preceded -by a single zero) or hexadecimal (prefixed with 0x). port is the port -number for both the UDP and the TCP (meta) connections. - -@item ConnectTo = (IP address|hostname) -Specifies which host to connect to on startup. If the ConnectPort -variable is omitted, then tinc will try to connect to port 655. - -If you don't specify a host with ConnectTo, regardless of whether a -value for ConnectPort is given, tinc won't connect at all, and will -instead just listen for incoming connections. Only the initiator of a -tinc VPN should need this. - -@item ListenPort = port -Listen on local port port. The computer connecting to this daemon should -use this number as the argument for his ConnectPort. Again, the -default is 655. - -@item MyOwnVPNIP = local address[/maskbits] -The local address is the number that the daemon will propagate to -other daemons on the network when it is identifying itself. Hence this -will be the file name of the passphrase file that the other end expects -to find the passphrase in. - -The local address is the IP address of the tap device, not the real IP -address of the host running tincd. Due to changes in recent kernels, it -is also necessary that you make the ethernet (also known as MAC) address -equal to the IP address (see the example). - -maskbits is the number of bits set to 1 in the netmask part. - -@item MyVirtualIP = local address[/maskbits] -This is an alias for MyOwnVPNIP. - -@item Passphrases = directory -The directory where tinc will look for passphrases when someone tries to -cennect. Please see the manpage for genauth(8) for more information -about passphrases as used by tinc. - -@item PingTimeout = number +@cindex router +@item router +In this mode Subnet +variables in the host configuration files will be used to form a routing table. +Only unicast 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 Name +@item Name = <@var{name}> [required] +This is a symbolic name for this connection. It can be anything + +@cindex PingTimeout +@item PingTimeout = <@var{seconds}> (60) The number of seconds of inactivity that tinc will wait before sending a -probe to the other end. If that other end doesn't answer within that +probe to the other end. If that other end doesn't answer within that same amount of seconds, the connection is terminated, and the others will be notified of this. -@item TapDevice = device -The ethertap device to use. Note that you can only use one device per -daemon. The info pages of the tinc package contain more information -about configuring an ethertap device for linux. +@cindex PriorityInheritance +@item PriorityInheritance = (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{tincd --generate-keys}. It must be a full path, not a +relative directory. + +Note that there must be exactly one of PrivateKey +or PrivateKeyFile +specified in the configuration file. + +@cindex TunnelServer +@item TunnelServer = (no) [experimental] +When this option is enabled tinc will no longer forward information between other tinc daemons, +and will only allow nodes and subnets on the VPN which are present in the +@file{@value{sysconfdir}/tinc/@var{netname}/hosts/} directory. + +@end table + + +@c ================================================================== +@node Host configuration variables +@subsection Host configuration variables + +@table @asis +@cindex Address +@item Address = <@var{IP address}|@var{hostname}> [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. + +@cindex Cipher +@item Cipher = <@var{cipher}> (blowfish) +The symmetric cipher algorithm used to encrypt UDP packets. +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. + +@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. +Any digest supported by OpenSSL is recognized. +Furthermore, specifying "none" will turn off packet authentication. + +@cindex IndirectData +@item IndirectData = (no) +This option specifies whether other tinc daemons besides the one you +specified with ConnectTo can make a direct connection to you. This is +especially useful if you are behind a firewall and it is impossible to +make a connection from the outside to your tinc daemon. Otherwise, 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. +Can be anything from 0 +up to the length of the digest produced by the digest algorithm. + +@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{tincd --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}]> +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. +Shorthand notations are not supported. +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:0:0:0:0/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{ftp://ftp.isi.edu/in-notes/rfc1519.txt, RFC1519} + +@cindex TCPonly +@item TCPonly = (no) [experimental] +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. +@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 .bat. + +@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}/subnet-up +This script is started when a Subnet becomes reachable. +The Subnet and the node it belongs to are passed in environment variables. + +@item @value{sysconfdir}/tinc/@var{netname}/subnet-down +This script is started when a Subnet becomes unreachable. @end table +@cindex environment variables +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} 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. + +@end table + + +@c ================================================================== +@node How to configure +@subsection How to configure + +@subsubheading Step 1. Creating the main configuration file + +The main configuration file will be called @file{@value{sysconfdir}/tinc/@var{netname}/tinc.conf}. +Adapt the following example to create a basic configuration file: + +@example +Name = @var{yourname} +Device = @file{/dev/tap0} +@end example + +Then, if you know to which other tinc daemon(s) yours is going to connect, +add `ConnectTo' values. + +@subsubheading Step 2. Creating your host configuration file + +If you added a line containing `Name = yourname' in the main configuarion file, +you will need to create a host configuration file @file{@value{sysconfdir}/tinc/@var{netname}/hosts/yourname}. +Adapt the following example to create a host configuration file: + +@example +Address = your.real.hostname.org +Subnet = 192.168.1.0/24 +@end example + +You can also use an IP address instead of a hostname. +The `Subnet' specifies the address range that is local for @emph{your part of the VPN only}. +If you have multiple address ranges you can specify more than one `Subnet'. +You might also need to add a `Port' if you want your tinc daemon to run on a different port number than the default (655). + + +@c ================================================================== +@node Generating keypairs +@section Generating keypairs + +@cindex key generation +Now that you have already created the main configuration file and your host configuration file, +you can easily create a public/private keypair by entering the following command: + +@example +tincd -n @var{netname} -K +@end example + +Tinc will generate a public and a private key and ask you where to put them. +Just press enter to accept the defaults. + + +@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. + +An example @file{tinc-up} script: + +@example +#!/bin/sh +ifconfig $INTERFACE 192.168.1.1 netmask 255.255.0.0 +@end example + +This script gives the interface an IP address and a netmask. +The kernel will also automatically add a 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 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 file, Configuring tinc -@section Example +@node Example configuration +@section Example configuration + -Imagine the following situation. An A-based 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. +@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 +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 @@ -459,216 +1266,261 @@ 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 -``gateway'' is the VPN IP address of the machine that is running the -tincd. ``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&UDP on port -655 (unless otherwise configured).e +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 LAN of the office. This could be the same as the interface -that leads to the internet. +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. + +@subsubheading For Branch A -@subsubheading For A +@emph{BranchA} would be configured like this: -@emph{A} would be configured like this: +In @file{@value{sysconfdir}/tinc/company/tinc-up}: @example -ifconfig tap0 hw ether fe:fd:0a:01:36:01 -ifconfig tap0 10.1.54.1 netmask 255.0.0.0 -ifconfig eth0 10.1.54.1 netmask 255.255.0.0 broadcast 10.1.255.255 +# 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 /etc/tinc/tincd.conf: +and in @file{@value{sysconfdir}/tinc/company/tinc.conf}: @example -TapDevice = /dev/tap0 -MyVirtualIP = 10.1.54.1/16 +Name = BranchA +Device = /dev/tap0 @end example -@subsubheading For B +On all hosts, @file{@value{sysconfdir}/tinc/company/hosts/BranchA} contains: @example -ifconfig tap0 hw ether fe:fd:0a:02:01:0c -ifconfig tap0 10.2.1.12 netmask 255.0.0.0 -ifconfig eth0 10.2.43.8 netmask 255.255.0.0 broadcast 10.2.255.255 +Subnet = 10.1.0.0/16 +Address = 1.2.3.4 + +-----BEGIN RSA PUBLIC KEY----- +... +-----END RSA PUBLIC KEY----- @end example -and in /etc/tinc/tincd.conf: +Note that the IP addresses of eth0 and tap0 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 give both real internal network interfaces and tap 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 -TapDevice = /dev/tap0 -MyVirtualIP = 10.2.1.12/16 -ConnectTo = 1.2.3.4 -AllowConnect = no -@end example +# Real interface of internal network: +# ifconfig eth0 10.2.43.8 netmask 255.255.0.0 -Note here that the internal address (on eth0) doesn't have to be the -same as on the tap0 device. Also, ConnectTo is given so that no-one can -connect to this node. +ifconfig $INTERFACE 10.2.1.12 netmask 255.0.0.0 +@end example -@subsubheading For C +and in @file{@value{sysconfdir}/tinc/company/tinc.conf}: @example -ifconfig tap0 hw ether fe:fd:0a:03:45:fe -ifconfig tap0 10.3.69.254 netmask 255.0.0.0 -ifconfig eth0 10.3.69.254 netmask 255.255.0.0 broadcast 10.3.255.255 +Name = BranchB +ConnectTo = BranchA @end example -and in /etc/tinc/A/tincd.conf: +Note here that the internal address (on eth0) doesn't have to be the +same as on the tap0 device. Also, ConnectTo is given so that no-one can +connect to this node. + +On all hosts, in @file{@value{sysconfdir}/tinc/company/hosts/BranchB}: @example -MyVirtualIP = 10.3.69.254/16 -ConnectTo = 1.2.3.4 -ListenPort = 2000 +Subnet = 10.2.0.0/16 +Address = 2.3.4.5 + +-----BEGIN RSA PUBLIC KEY----- +... +-----END RSA PUBLIC KEY----- @end example -C already has another daemon that runs on port 655, so they have to -reserve another port for tinc. They also use the netname to distinguish -between the two. tinc is started with `tincd -n A'. -@subsubheading For D +@subsubheading For Branch C + +In @file{@value{sysconfdir}/tinc/company/tinc-up}: @example -ifconfig tap0 hw ether fe:fd:0a:04:03:20 -ifconfig tap0 10.4.3.32 netmask 255.0.0.0 -ifconfig tap0 10.4.3.32 netmask 255.255.0.0 broadcast 10.4.255.255 +# 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 /etc/tinc/tincd.conf: +and in @file{@value{sysconfdir}/tinc/company/tinc.conf}: @example -MyVirtualIP = 10.4.3.32/16 -ConnectTo = 3.4.5.6 -ConnectPort = 2000 -AllowConnect = no +Name = BranchC +ConnectTo = BranchA +Device = /dev/tap1 @end example -D will be connecting to C, which has a tincd running for this network on -port 2000. Hence they need to put in a ConnectPort. +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. -@subsubheading Authentication +On all hosts, in @file{@value{sysconfdir}/tinc/company/hosts/BranchC}: -A, B, C and D all generate a passphrase with genauth 2048, the output is -stored in /etc/tinc/passphrases/local, except for C, where it should be -/etc/tinc/A/passphrases/local. +@example +Address = 3.4.5.6 +Subnet = 10.3.0.0/16 +Port = 2000 -A stores a copy of B's passphrase in /etc/tinc/passphrases/10.2.0.0 +-----BEGIN RSA PUBLIC KEY----- +... +-----END RSA PUBLIC KEY----- +@end example -A stores a copy of C's passphrase in /etc/tinc/passphrases/10.3.0.0 -B stores a copy of A's passphrase in /etc/tinc/passphrases/10.1.0.0 +@subsubheading For Branch D -C stores a copy of A's passphrase in /etc/tinc/A/passphrases/10.1.0.0 +In @file{@value{sysconfdir}/tinc/company/tinc-up}: -C stores a copy of D's passphrase in /etc/tinc/A/passphrases/10.4.0.0 +@example +# Real interface of internal network: +# ifconfig eth0 10.4.3.32 netmask 255.255.0.0 -D stores a copy of C's passphrase in /etc/tinc/passphrases/10.3.0.0 +ifconfig $INTERFACE 10.4.3.32 netmask 255.0.0.0 +@end example -@subsubheading Starting +and in @file{@value{sysconfdir}/tinc/company/tinc.conf}: -A has to start their tincd first. Then come B and C, where C has to -provide the option `-n A', because they have more than one tinc -network. Finally, D's tincd is started. +@example +Name = BranchD +ConnectTo = BranchC +Device = /dev/net/tun +@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. +Also note that since D uses the tun/tap driver, the network interface +will not be called `tun' or `tap0' or something like that, but will +have the same name as netname. +On all hosts, in @file{@value{sysconfdir}/tinc/company/hosts/BranchD}: -@c ================================================================== -@node Running tinc, Technical information, Configuring tinc, Top -@chapter Running tinc +@example +Subnet = 10.4.0.0/16 +Address = 4.5.6.7 -Running tinc isn't just as easy as typing `tincd' and hoping everything -will just work out the way you wanted. Instead, the use of tinc is a -project that involves trust relations and more than one computer. +-----BEGIN RSA PUBLIC KEY----- +... +-----END RSA PUBLIC KEY----- +@end example -@menu -* Managing keys:: -* Runtime options:: -@end menu +@subsubheading Key files +A, B, C and D all have generated a public/private keypair with the following command: -@c ================================================================== -@node Managing keys, Runtime options, Running tinc, Running tinc -@section Managing keys +@example +tincd -n company -K +@end example -Before attempting to start tinc, you have to create passphrases. When -tinc tries to make a connection, it exchanges some sensitive -data. Before doing so, it likes to know if the other end is -trustworthy. +The private key is stored in @file{@value{sysconfdir}/tinc/company/rsa_key.priv}, +the public key is put into the host configuration file in the @file{@value{sysconfdir}/tinc/company/hosts/} directory. +During key generation, tinc automatically guesses the right filenames based on the -n option and +the Name directive in the @file{tinc.conf} file (if it is available). -To do this, both ends must have some knowledge about the other. In the -case of tinc this is the authentication passphrase. +@subsubheading Starting -This passphrase is a number, which is chosen at random. This number is -then sent to the other computers which want to talk to us directly. To -avoid breaking security, this should be done over a known secure channel -(such as ssh or similar). +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. -All passphrases are stored in the passphrases directory, which is -normally /etc/tinc/nn/passphrases/, but it may be changed using the -`Passphrases' option in the config file. -To generate a passphrase, run `genauth'. genauth takes one argument, -which is the length of the passphrase in bits. The length of the -passphrase should be in the range 1024--2048 for a key length of 128 -bits. genauth creates a random number of the specified length, and puts -it to stdout. +@c ================================================================== +@node Running tinc +@chapter Running tinc -Every computer that wants to participate in the VPN should do this, and -store the output in the passphrases directory, in the file @file{local}. +If everything else is done, you can start tinc by typing the following command: -When every computer has his own local key, it should copy it to the -computer that it wants to talk to directly. (i.e. the one it connects to -during startup.) This should be done via a secure channel, because it is -sensitive information. If this is not done securely, someone might break -in on you later on. +@example +tincd -n @var{netname} +@end example -Those non-local passphrase files must have the name of the VPN IP -address that they will advertise to you. For instance, if a computer -tells us it likes to be 10.1.1.3 with netmask 255.255.0.0, the file -should still be called 10.1.1.3, and not 10.1.0.0. +@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, , Managing keys, Running tinc +@node Runtime options @section Runtime options Besides the settings in the configuration file, tinc also accepts some command line options. -This list is a longer version of that in the manpage. The latter is -generated automatically, so may be more up-to-date. - +@cindex command line +@cindex runtime options +@cindex options @c from the manpage -@table @asis -@item -c, --config=FILE -Read configuration options from FILE. The default is -@file{/etc/tinc/nn/tincd.conf}. - -@item -d -Increase debug level. The higher it gets, the more gets -logged. Everything goes via syslog. - -0 is the default, only some basic information connection attempts get -logged. Setting it to 1 will log a bit more, still not very -disturbing. With two -d's tincd will log protocol information, which can -get pretty noisy. Three or more -d's will output every single packet -that goes out or comes in, which probably generates more data than the -packets themselves. - -@item -k, --kill -Attempt to kill a running tincd and exit. A TERM signal (15) gets sent -to the daemon that his its PID in /var/run/tincd.nn.pid. - -Because it kills only one tincd, you should use -n here if you use it -normally. - -@item -n, --net=NETNAME -Connect to net NETNAME. @xref{Multiple networks}. - -@item -t, --timeout=TIMEOUT -Seconds to wait before giving a timeout. Should not be set too low, -because every time tincd senses a timeout, it disconnects and reconnects -again, which will cause unnecessary network traffic and log messages. +@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 -k, --kill[=@var{signal}] +Attempt to kill a running tincd (optionally with the specified @var{signal} instead of SIGTERM) and exit. +Use it in conjunction with the -n option to make sure you kill the right tinc daemon. +Under native Windows the optional argument is ignored, +the service will always be stopped and removed. + +@item -n, --net=@var{netname} +Use configuration for net @var{netname}. @xref{Multiple networks}. + +@item -K, --generate-keys[=@var{bits}] +Generate public/private keypair of @var{bits} length. If @var{bits} is not specified, +1024 is the default. tinc will ask where you want to store the files, +but will default to the configuration directory (you can use the -c or -n option +in combination with -K). After that, tinc will quit. + +@item -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. + +@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 --pidfile=@var{file} +Write PID to @var{file} instead of @file{@value{localstatedir}/run/tinc.@var{netname}.pid}. + +@item --bypass-security +Disables encryption and authentication. +Only useful for debugging. @item --help Display a short reminder of these runtime options and terminate. @@ -678,534 +1530,840 @@ Output version information and exit. @end table - @c ================================================================== -@node Technical information, About us, Running tinc, Top -@chapter Technical information +@node Signals +@section Signals +@cindex signals +You can also send the following signals to a running tincd process: -@c ================================================================== -@menu -* The Connection:: -* Security:: -* The Protocol:: -@end menu +@c from the manpage +@table @samp -@node The Connection, Security, Technical information, Technical information -@section The basic philosophy of the way tinc works -@cindex Connection +@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. -tinc is a daemon that takes VPN data and transmit that to another host -computer over the existing Internet infrastructure. +@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. -@menu -* Protocol Preview:: -* The Meta-connection:: -@end menu +@item INT +Temporarily increases debug level to 5. +Send this signal again to revert to the original level. +@item USR1 +Dumps the connection list to syslog. -@c ================================================================== -@node Protocol Preview, The Meta-connection, The Connection, The Connection -@subsection A preview of the way the tinc works +@item USR2 +Dumps virtual network device statistics, all known nodes, edges and subnets to syslog. -@cindex ethertap -@cindex frame type -The data itself is read from a character device file, the so-called -@emph{ethertap} 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. Data to -and from the device is formatted as if it were a normal ethernet card, -so a frame is preceded by two MAC addresses and a @emph{frame type} -field. - -So when tinc reads an ethernet frame from the device, it determines its -type. Right now, tinc can only handle Internet Protocol version 4 (IPv4) -frames. Plans to support other protocols are being made. When tinc knows -which type of frame it has read, it can also read the source and -destination address from it. - -Now it is time that the frame gets encrypted. Currently the only -encryption algorithm available is blowfish. - -@cindex encapsulating -When the encryption is ready, 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 does a decrypt on the contents of the UDP datagram, -and it writes the decrypted information to its own ethertap device. +@item WINCH +Purges all information remembered about unreachable nodes. +@end table @c ================================================================== -@node The Meta-connection, , Protocol Preview, The 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 encryption information to somebody. +@node Debug levels +@section Debug levels -TCP is a better alternative, because it already contains protection -against information being lost, unlike UDP. +@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: -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. +@c from the manpage +@table @samp -@cindex data-protocol -@cindex meta-protocol -Like with any communication, we must have a protocol, so that everybody -knows what everything stands for, an how he 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.'' +@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. -@c ================================================================== -@node Security, The Protocol, The Connection, Technical information -@section About tinc's encryption and other security-related issues. +@item 2 +This will log status and error messages from scripts and other tinc daemons. -@cindex tinc -@cindex Cabal -tinc got its name from ``TINC,'' short for @emph{There Is No Cabal}; the -alleged Cabal was/is an organization 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. +@item 3 +This will log all requests that are exchanged with other tinc daemons. These include +authentication, key exchange and connection list updates. -@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. +@item 4 +This will log a copy of everything received on the meta socket. -This chapter is a mixture of ideas, reasoning and explanation, please -don't take it too serious. - -@menu -* Encryption:: -* Key Management:: -* Authentification:: How to be sure we're talking to the right person -* Protection:: -@end menu +@item 5 +This will log all network traffic over the virtual private network. +@end table @c ================================================================== -@node Encryption, Key Management, Security, Security -@subsection Encryption +@node Solving problems +@section Solving problems -Encryption algorithms come in lots of flavors, most of which are not -safe enough to use on the Internet, if at all. Algorithms that we've -considered using are: RSA, blowfish, twofish and IDEA. +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: -@itemize @bullet -@item -@cindex RSA -@emph{RSA} is patented. A fee must be paid if you use it, so it can't -be used in an Open Source program. +@example +tincd -n @var{netname} -d5 -D +@end example -@item -@cindex blowfish -@emph{blowfish} was the standard encryption method at least up to version -0.2.23, but as Dekan pointed out, it may not be all that secure. It is -also patented, but it may be used freely. +If tinc does not log any error messages, then you might want to check the following things: -@item -@cindex twofish -@emph{twofish} should be better, but i've not seen a useable -ready-to-use implementation somewhere out of the US. I'll remember this -as a future encryption method. +@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 -@cindex IDEA -@emph{IDEA} is patented, and free for non-commercial use. It is going to -be the standard encryption method. +@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? -@end itemize +@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. -You may choose any of the last three encryption methods in tinc. Please -note, however, that ALL computers on your VPN must currenttly use the -same. This should (among other things) be more flexible, tinc could for -instance load a new encryption library the minute it is needed. +@end itemize @c ================================================================== -@node Key Management, Authentification, Encryption, Security -@subsection Key Management -@c FIXME: recheck +@node Error messages +@section Error messages -@cindex Diffie-Hellman -You can't just send a private encryption key to your peer, because -somebody else might already be listening to you. So you'll have to -negotiate over a shared but secret key. One way to do this is by using -the ``Diffie-Hellman key exchange'' protocol -(@uref{http://www.rsa.com/rsalabs/faq/html/3-6-1.html}). The idea is as -follows. +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. -You have two participants A and B that want to agree over a shared -secret encryption key. Both parties have some large prime number p and a -generator g. These numbers may be known to the outside world, and hence -may be included in the source distribution. - -@cindex secret key -Both parties then generate a secret key. A generates a, and computes g^a -mod p. This is then sent to B; while B computes g^b mod p, and transmits -this to A, b being generated by B. Both a and b must be smaller than -p-1. +@table @samp +@item Could not open /dev/tap0: No such device -These private keys are generated upon startup, and they are not changed -while the connection exists. A possible feature in the future is to -dynamically change the keys, every hour for example. +@itemize +@item You forgot to `modprobe netlink_dev' or `modprobe ethertap'. +@item You forgot to compile `Netlink device emulation' in the kernel. +@end itemize -Both parties then calculate g^ab mod p = k. k is the new, shared, but -still secret key. +@item Can't write to /dev/net/tun: No such device -To obtain a key k of a sufficient length (128 bits in our vpnd), p -should be 2^129-1 or more. +@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! -@c ================================================================== -@node Authentification, Protection, Key Management, Security -@subsection Authentification -@c FIXME: recheck +@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 -@cindex man-in-the-middle attack -Because the Diffie-Hellman protocol is in itself vulnerable to the -``man-in-the-middle attack,'' we should introduce an authentification -system. +@item Error reading RSA key file `rsa_key.priv': No such file or directory -We will let A transmit a passphrase that is also known to B encrypted -with g^a, before A sends this to B. This way, B can check whether A is -really A or just someone else. +@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 -@cindex passphrase -This passphrase should be 2304 bits for a symmetric encryption -system. But since an asymmetric system is more secure, we could do with -2048 bits. This only holds if the passphrase is very random. +@item Warning: insecure file permissions for RSA private key file `rsa_key.priv'! -These passphrases could be stored in a file that is non-readable by -anyone else but root; e.g. @file{/etc/vpn/passphrases}. +@itemize +@item The private key file is readable by users other than root. +Use chmod to correct the file permissions. +@end itemize -The only thing that needs to be taken care of is how A announces its -passphrase to B. +@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 -@c ================================================================== -@node Protection, , Authentification, Security -@subsection Protecting your data +@item Cannot route packet: unknown IPv4 destination 1.2.3.4 -Now we have securely hidden our data. But a malicious cracker may still -bother you by randomly altering the encrypted data he intercepts. +@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 -@c ================================================================== -@node The Protocol, , Security, Technical information -@section Detailed protocol specifications +@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 -@menu -* Data protocol:: -* Meta protocol:: -@end menu - -@c ================================================================== -@node Data protocol, Meta protocol, The Protocol, The Protocol -@subsection The data protocol +@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 -The data that is sent through the UDP connection is formatted as follows: +@item Received UDP packet from unknown source 1.2.3.4 (port 12345) -@example +@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 - bytes | Contents ----------------------- - 0-1 | The length of this packet, including all leading fields - 2-5 | The destination IP address - 6-... | The encrypted data +@item Got bad/bogus/unauthorized REQUEST from foo (1.2.3.4 port 12345) -@end example +@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 -The method that was used to encrypt the data should be made known via -the meta-protocol, during early identification stages. +@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 Meta protocol, , Data protocol, The Protocol -@subsection The Meta protocol +@node Technical information +@chapter Technical information -This protocol consists of separate packets of enformation, that are -generally formatted thusly: -@example +@menu +* The connection:: +* The meta-protocol:: +* Security:: +@end menu - bytes | Contents ----------------------- - 0 | The request ID - 1-... | (Optional: arguments) -@end example +@c ================================================================== +@node The connection +@section The connection -What follows is a listing of possible request IDs. +@cindex connection +Tinc is a daemon that takes VPN data and transmit that to another host +computer over the existing Internet infrastructure. -@table @samp -@item ACK -Acknowledge. This generally means that the authentication has been -accepted by the remote computer. Takes no arguments. +@menu +* The UDP tunnel:: +* The meta-connection:: +@end menu -@example - bytes | Contents ----------------------- - 0 | `1' +@c ================================================================== +@node The UDP tunnel +@subsection The UDP tunnel -@end example +@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. -@item AUTH_S_INIT -@itemx AUTH_C_INIT -Obsolete. Use @samp{BASIC_INFO}. +@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. -@item AUTH_S_SPP -@itemx AUTH_C_SPP -Obsolete. Use @samp{PASSPHRASE}. +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. -@item AUTH_S_SKEY -@itemx AUTH_C_SKEY -Obsolete. Use @samp{PUBLIC_KEY}, @samp{REQ_KEY} and @samp{ANS_KEY}. -@item AUTH_S_SACK -@itemx AUTH_C_RACK -Obsolete. Use @samp{ACK}. +@c ================================================================== +@node The meta-connection +@subsection The meta-connection -@item TERMREQ -A request to terminate this connection, for whatever reason. +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. -@example +@cindex TCP +TCP is a better alternative, because it already contains protection +against information being lost, unlike UDP. - bytes | Contents ----------------------- - 0 | `30' - 1-4 | The VPN IP address of the host that has exited +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. -@end example +@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. -@item PINGTIMEOUT -Terminate connection, but the reason must be a ping timeout. +@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{Authentication protocol}. 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 - - bytes | Contents ----------------------- - 0 | `31' - 1-4 | The VPN IP address of the host that has exited - +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. -@item PING -Send probe to the other end, if he hasn't returned a @samp{PONG} within -10 seconds, the connection is considered to be dead and will be -terminated, we should try to notify the other by sending a -@samp{PINGTIMEOUT} packet. +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 - - bytes | Contents ----------------------- - 0 | `40' - +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. -@item PONG -See explanation for @samp{PING} - +@cindex REQ_KEY +@cindex ANS_KEY +@cindex KEY_CHANGED @example - - bytes | Contents ----------------------- - 0 | `41' - +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. -@item ADD_HOST -Send an @samp{ADD_HOST} packet if you want to propagate all your current -connections to a new computer on a network. If we get this request, we -must forward it to everyone that hasn't got it yet. - +@cindex PING +@cindex PONG @example - - bytes | Contents ----------------------- - 0 | `60' - 1-4 | The real IP address of the new host - 5-8 | The VPN IP address of the new host - 9-12 | The VPN netmask - 13-14 | The port number that the new host listens on - +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. -@item BASIC_INFO -This packet will contain all necessary basic information about -ourselves, such as the port we listen on and our desired VPN IP address. +This basically covers what is sent over the meta connection by tinc. -@example - bytes | Contents ----------------------- - 0 | `61' - 1 | The protocol version. - | This chapter describes version 4. - 2-3 | The port number that the new host listens on - 4-7 | The VPN IP address of the new host - 8-11 | The VPN netmask +@c ================================================================== +@node Security +@section Security -@end example +@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. +Tinc by default uses blowfish encryption with 128 bit keys in CBC mode, 32 bit +sequence numbers and 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. +@menu +* Authentication protocol:: +* Encryption of network packets:: +* Security issues:: +@end menu -@item PASSPHRASE -Send an encrypted passphrase. Should be encrypted with our -@strong{public} key, and it must reach us before a @samp{PUBLIC_KEY} -request. +@c ================================================================== +@node Authentication protocol +@subsection Authentication protocol + +@cindex authentication +A new scheme for authentication in tinc has been devised, which offers some +improvements over the protocol used in 1.0pre2 and 1.0pre3. Explanation is +below. + +@cindex ID +@cindex META_KEY +@cindex CHALLENGE +@cindex CHAL_REPLY +@cindex ACK @example +daemon message +-------------------------------------------------------------------------- +client - bytes | Contents ----------------------- - 0 | `62' - 1-2 | The length of the encrypted passphrase - 3-... | The encrypted passphrase +server -@end example +client ID client 12 + | +---> version + +-------> name of tinc daemon +server ID server 12 + | +---> version + +-------> name of tinc daemon -@item PUBLIC_KEY -This is only used during authentication of a new connection, later on we -may use @samp{REQ_KEY} and @samp{ANS_KEY}. +client META_KEY 5f0823a93e35b69e...7086ec7866ce582b + \_________________________________/ + +-> RSAKEYLEN bits totally random string S1, + encrypted with server's public RSA key -@example +server META_KEY 6ab9c1640388f8f0...45d1a07f8a672630 + \_________________________________/ + +-> RSAKEYLEN bits totally random string S2, + encrypted with client's public RSA key - bytes | Contents ----------------------- - 0 | `63' - 1-2 | The length of the key - 3-... | The public key, given in base-36 - -@end example +From now on: + - the client will symmetrically encrypt outgoing traffic using S1 + - the server will symmetrically encrypt outgoing traffic using S2 +client CHALLENGE da02add1817c1920989ba6ae2a49cecbda0 + \_________________________________/ + +-> CHALLEN bits totally random string H1 -@item HOLD -@itemx RESUME -Unused. +server CHALLENGE 57fb4b2ccd70d6bb35a64c142f47e61d57f + \_________________________________/ + +-> CHALLEN bits totally random string H2 -@item CALCULATE -@itemx CALC_RES -@itemx ALMOST_KEY -Never been in use. +client CHAL_REPLY 816a86 + +-> 160 bits SHA1 of H2 -@item REQ_KEY -Request a public key from someone and return it to the sender of this -request using a @samp{ANS_KEY} packet. If we get such request, we must -forward it to the connection that leads to the destination. +server CHAL_REPLY 928ffe + +-> 160 bits SHA1 of H1 -@example +After the correct challenge replies are received, both ends have proved +their identity. Further information is exchanged. - bytes | Contents ----------------------- - 0 | `160' - 1-4 | The source VPN IP address - 5-8 | The destination VPN IP address - 9-14 | `0' +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 new scheme has several improvements, both in efficiency and security. + +First of all, the server sends exactly the same kind of messages over the wire +as the client. The previous versions of tinc first authenticated the client, +and then the server. This scheme even allows both sides to send their messages +simultaneously, there is no need to wait for the other to send something first. +This means that any calculations that need to be done upon sending or receiving +a message can also be done in parallel. This is especially important when doing +RSA encryption/decryption. Given that these calculations are the main part of +the CPU time spent for the authentication, speed is improved by a factor 2. + +Second, only one RSA encrypted message is sent instead of two. This reduces the +amount of information attackers can see (and thus use for a cryptographic +attack). It also improves speed by a factor two, making the total speedup a +factor 4. + +Third, and most important: +The symmetric cipher keys are exchanged first, the challenge is done +afterwards. In the previous authentication scheme, because a man-in-the-middle +could pass the challenge/chal_reply phase (by just copying the messages between +the two real tinc daemons), but no information was exchanged that was really +needed to read the rest of the messages, the challenge/chal_reply phase was of +no real use. The man-in-the-middle was only stopped by the fact that only after +the ACK messages were encrypted with the symmetric cipher. Potentially, it +could even send it's own symmetric key to the server (if it knew the server's +public key) and read some of the metadata the server would send it (it was +impossible for the mitm to read actual network packets though). The new scheme +however prevents this. + +This new scheme makes sure that first of all, symmetric keys are exchanged. The +rest of the messages are then encrypted with the symmetric cipher. Then, each +side can only read received messages if they have their private key. The +challenge is there to let the other side know that the private key is really +known, because a challenge reply can only be sent back if the challenge is +decrypted correctly, and that can only be done with knowledge of the private +key. + +Fourth: the first thing that is sent via the symmetric cipher encrypted +connection is a totally random string, so that there is no known plaintext (for +an attacker) in the beginning of the encrypted stream. -@item ANS_KEY -Answer to a @samp{REQ_KEY} request, forward it to the destination if it -is not meant for us. -@example +@c ================================================================== +@node Encryption of network packets +@subsection Encryption of network packets +@cindex encryption - bytes | Contents ----------------------- - 0 | `161' - 1-4 | The source VPN IP address - 5-8 | The destination VPN IP address - 9-12 | The expiration date/time in seconds - 13-14 | The key length - 15-... | The public key in base-36 +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. The packet is stored in a queue while waiting for the +key to arrive. +@cindex UDP +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. By default the +first 4 bytes of the digest are used for this, but this can be changed using +the MACLength configuration variable. -@item KEY_CHANGED -The source computer wants to tell that it has regenerated its private -and public keys, so anything going there must be encrypted with a new -shared key. +@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 this version of tinc, but tinc's security is not as strong as TLS or IPsec. +We will address these issues in tinc 2.0. + +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. -@example - bytes | Contents ----------------------- - 0 | `162' - 1-4 | The source VPN IP address +@c ================================================================== +@node Platform specific information +@chapter Platform specific information -@end example +@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 -@end table + +@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, Concept Index, Technical information, Top +@node About us @chapter About us @menu -* Contact Information:: -* Authors:: +* Contact information:: +* Authors:: @end menu @c ================================================================== -@node Contact Information, Authors, About us, About us +@node Contact information @section Contact information -tinc's main page is at @url{http://tinc.nl.linux.org/}, +@cindex website +Tinc's website is at @url{http://www.tinc-vpn.org/}, this server is located in the Netherlands. -We have an IRC channel on the Open Projects IRC network. Connect to -@uref{http://openprojects.nu/services/irc.html, irc.openprojects.net}, +@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, , Contact Information, About us +@node Authors @section Authors @table @asis -@item Ivo Timmermans (zarq) (@email{itimmermans@@bigfoot.com}) -Main coder/hacker and maintainer of the package. - -@item Guus Sliepen (guus) -Originator of it all, co-author. - -@item Wessel Dankers (Ubiq) -General obfuscator of the code. - +@item Ivo Timmermans (zarq) (@email{ivo@@tinc-vpn.org}) +@item Guus Sliepen (guus) (@email{guus@@tinc-vpn.org}) @end table -Thank you's to: Dekan, Emphyrio, vDong - -Greetings to: braque, Fluor, giggles, macro, smoke, tribbel +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, , About us, Top -@c node-name, next, previous, up +@node Concept Index @unnumbered Concept Index @c ================================================================== @@ -1215,4 +2373,3 @@ Greetings to: braque, Fluor, giggles, macro, smoke, tribbel @c ================================================================== @contents @bye -