1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename tinc.info 4@settitle tinc Manual 5@setchapternewpage odd 6@c %**end of header 7 8@include tincinclude.texi 9 10@ifinfo 11@dircategory Networking tools 12@direntry 13* tinc: (tinc). The tinc Manual. 14@end direntry 15 16This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon. 17 18Copyright @copyright{} 1998-2019 Ivo Timmermans, 19Guus Sliepen <guus@@tinc-vpn.org> and 20Wessel Dankers <wsl@@tinc-vpn.org>. 21 22Permission is granted to make and distribute verbatim copies of this 23manual provided the copyright notice and this permission notice are 24preserved on all copies. 25 26Permission is granted to copy and distribute modified versions of this 27manual under the conditions for verbatim copying, provided that the 28entire resulting derived work is distributed under the terms of a 29permission notice identical to this one. 30 31@end ifinfo 32 33@titlepage 34@title tinc Manual 35@subtitle Setting up a Virtual Private Network with tinc 36@author Ivo Timmermans and Guus Sliepen 37 38@page 39@vskip 0pt plus 1filll 40This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon. 41 42Copyright @copyright{} 1998-2019 Ivo Timmermans, 43Guus Sliepen <guus@@tinc-vpn.org> and 44Wessel Dankers <wsl@@tinc-vpn.org>. 45 46Permission is granted to make and distribute verbatim copies of this 47manual provided the copyright notice and this permission notice are 48preserved on all copies. 49 50Permission is granted to copy and distribute modified versions of this 51manual under the conditions for verbatim copying, provided that the 52entire resulting derived work is distributed under the terms of a 53permission notice identical to this one. 54 55@end titlepage 56 57@ifnottex 58@c ================================================================== 59@node Top 60@top Top 61 62@menu 63* Introduction:: 64* Preparations:: 65* Installation:: 66* Configuration:: 67* Running tinc:: 68* Technical information:: 69* Platform specific information:: 70* About us:: 71* Concept Index:: All used terms explained 72@end menu 73@end ifnottex 74 75@c ================================================================== 76@node Introduction 77@chapter Introduction 78 79@cindex tinc 80Tinc is a Virtual Private Network (VPN) daemon that uses tunneling and 81encryption to create a secure private network between hosts on the 82Internet. 83 84Because the tunnel appears to the IP level network code as a normal 85network device, there is no need to adapt any existing software. 86The encrypted tunnels allows VPN sites to share information with each other 87over the Internet without exposing any information to others. 88 89This document is the manual for tinc. Included are chapters on how to 90configure your computer to use tinc, as well as the configuration 91process of tinc itself. 92 93@menu 94* Virtual Private Networks:: 95* tinc:: About tinc 96* Supported platforms:: 97@end menu 98 99@c ================================================================== 100@node Virtual Private Networks 101@section Virtual Private Networks 102 103@cindex VPN 104A Virtual Private Network or VPN is a network that can only be accessed 105by a few elected computers that participate. This goal is achievable in 106more than just one way. 107 108@cindex private 109Private networks can consist of a single stand-alone Ethernet LAN. Or 110even two computers hooked up using a null-modem cable. In these cases, 111it is 112obvious that the network is @emph{private}, no one can access it from the 113outside. But if your computers are linked to the Internet, the network 114is not private anymore, unless one uses firewalls to block all private 115traffic. But then, there is no way to send private data to trusted 116computers on the other end of the Internet. 117 118@cindex virtual 119This problem can be solved by using @emph{virtual} networks. Virtual 120networks can live on top of other networks, but they use encapsulation to 121keep using their private address space so they do not interfere with 122the Internet. Mostly, virtual networks appear like a single LAN, even though 123they can span the entire world. But virtual networks can't be secured 124by using firewalls, because the traffic that flows through it has to go 125through the Internet, where other people can look at it. 126 127As is the case with either type of VPN, anybody could eavesdrop. Or 128worse, alter data. Hence it's probably advisable to encrypt the data 129that flows over the network. 130 131When one introduces encryption, we can form a true VPN. Other people may 132see encrypted traffic, but if they don't know how to decipher it (they 133need to know the key for that), they cannot read the information that flows 134through the VPN. This is what tinc was made for. 135 136 137@c ================================================================== 138@node tinc 139@section tinc 140 141@cindex vpnd 142I really don't quite remember what got us started, but it must have been 143Guus' idea. He wrote a simple implementation (about 50 lines of C) that 144used the ethertap device that Linux knows of since somewhere 145about kernel 2.1.60. It didn't work immediately and he improved it a 146bit. At this stage, the project was still simply called "vpnd". 147 148Since then, a lot has changed---to say the least. 149 150@cindex tincd 151Tinc now supports encryption, it consists of a single daemon (tincd) for 152both the receiving and sending end, it has become largely 153runtime-configurable---in short, it has become a full-fledged 154professional package. 155 156@cindex traditional VPNs 157@cindex scalability 158Tinc also allows more than two sites to connect to each other and form a single VPN. 159Traditionally VPNs are created by making tunnels, which only have two endpoints. 160Larger VPNs with more sites are created by adding more tunnels. 161Tinc takes another approach: only endpoints are specified, 162the software itself will take care of creating the tunnels. 163This allows for easier configuration and improved scalability. 164 165A lot can---and will be---changed. We have a number of things that we would like to 166see in the future releases of tinc. Not everything will be available in 167the near future. Our first objective is to make tinc work perfectly as 168it stands, and then add more advanced features. 169 170Meanwhile, we're always open-minded towards new ideas. And we're 171available too. 172 173 174@c ================================================================== 175@node Supported platforms 176@section Supported platforms 177 178@cindex platforms 179Tinc has been verified to work under Linux, FreeBSD, OpenBSD, NetBSD, Mac OS X (Darwin), Solaris, and Windows (both natively and in a Cygwin environment), 180with various hardware architectures. These are some of the platforms 181that are supported by the universal tun/tap device driver or other virtual network device drivers. 182Without such a driver, tinc will most 183likely compile and run, but it will not be able to send or receive data 184packets. 185 186@cindex release 187For an up to date list of supported platforms, please check the list on 188our website: 189@uref{https://www.tinc-vpn.org/platforms/}. 190 191@c 192@c 193@c 194@c 195@c 196@c 197@c Preparing your system 198@c 199@c 200@c 201@c 202@c 203 204@c ================================================================== 205@node Preparations 206@chapter Preparations 207 208This chapter contains information on how to prepare your system to 209support tinc. 210 211@menu 212* Configuring the kernel:: 213* Libraries:: 214@end menu 215 216 217@c ================================================================== 218@node Configuring the kernel 219@section Configuring the kernel 220 221@menu 222* Configuration of Linux kernels:: 223* Configuration of FreeBSD kernels:: 224* Configuration of OpenBSD kernels:: 225* Configuration of NetBSD kernels:: 226* Configuration of Solaris kernels:: 227* Configuration of Darwin (Mac OS X) kernels:: 228* Configuration of Windows:: 229@end menu 230 231 232@c ================================================================== 233@node Configuration of Linux kernels 234@subsection Configuration of Linux kernels 235 236@cindex Universal tun/tap 237For tinc to work, you need a kernel that supports the Universal tun/tap device. 238Most distributions come with kernels that already support this. 239Here are the options you have to turn on when configuring a new kernel: 240 241@example 242Code maturity level options 243[*] Prompt for development and/or incomplete code/drivers 244Network device support 245<M> Universal tun/tap device driver support 246@end example 247 248It's not necessary to compile this driver as a module, even if you are going to 249run more than one instance of tinc. 250 251If you decide to build the tun/tap driver as a kernel module, add these lines 252to @file{/etc/modules.conf}: 253 254@example 255alias char-major-10-200 tun 256@end example 257 258 259@c ================================================================== 260@node Configuration of FreeBSD kernels 261@subsection Configuration of FreeBSD kernels 262 263For FreeBSD version 4.1 and higher, tun and tap drivers are included in the default kernel configuration. 264The tap driver can be loaded with @code{kldload if_tap}, or by adding @code{if_tap_load="YES"} to @file{/boot/loader.conf}. 265 266 267@c ================================================================== 268@node Configuration of OpenBSD kernels 269@subsection Configuration of OpenBSD kernels 270 271Recent versions of OpenBSD come with both tun and tap devices enabled in the default kernel configuration. 272 273 274@c ================================================================== 275@node Configuration of NetBSD kernels 276@subsection Configuration of NetBSD kernels 277 278For NetBSD version 1.5.2 and higher, 279the tun driver is included in the default kernel configuration. 280 281Tunneling IPv6 may not work on NetBSD's tun device. 282 283 284@c ================================================================== 285@node Configuration of Solaris kernels 286@subsection Configuration of Solaris kernels 287 288For Solaris 8 (SunOS 5.8) and higher, 289the tun driver may or may not be included in the default kernel configuration. 290If it isn't, the source can be downloaded from @uref{http://vtun.sourceforge.net/tun/}. 291For x86 and sparc64 architectures, precompiled versions can be found at @uref{https://www.monkey.org/~dugsong/fragroute/}. 292If the @file{net/if_tun.h} header file is missing, install it from the source package. 293 294 295@c ================================================================== 296@node Configuration of Darwin (Mac OS X) kernels 297@subsection Configuration of Darwin (Mac OS X) kernels 298 299Tinc on Darwin relies on a tunnel driver for its data acquisition from the kernel. 300OS X version 10.6.8 and later have a built-in tun driver called "utun". 301Tinc also supports the driver from @uref{http://tuntaposx.sourceforge.net/}, 302which supports both tun and tap style devices. 303 304By default, tinc expects the tuntaposx driver to be installed. 305To use the utun driver, set add @code{Device = utunX} to @file{tinc.conf}, 306where X is the desired number for the utun interface. 307You can also omit the number, in which case the first free number will be chosen. 308 309 310@c ================================================================== 311@node Configuration of Windows 312@subsection Configuration of Windows 313 314You will need to install the latest TAP-Win32 driver from OpenVPN. 315You can download it from @uref{https://openvpn.net/index.php/open-source/downloads.html}. 316Using the Network Connections control panel, 317configure the TAP-Win32 network interface in the same way as you would do from the tinc-up script, 318as explained in the rest of the documentation. 319 320 321@c ================================================================== 322@node Libraries 323@section Libraries 324 325@cindex requirements 326@cindex libraries 327Before you can configure or build tinc, you need to have the LibreSSL or OpenSSL, 328zlib and lzo libraries installed on your system. If you try to configure tinc without 329having them installed, configure will give you an error message, and stop. 330 331@menu 332* LibreSSL/OpenSSL:: 333* zlib:: 334* lzo:: 335@end menu 336 337 338@c ================================================================== 339@node LibreSSL/OpenSSL 340@subsection LibreSSL/OpenSSL 341 342@cindex LibreSSL 343@cindex OpenSSL 344For all cryptography-related functions, tinc uses the functions provided 345by the LibreSSL or the OpenSSL library. 346 347If this library is not installed, you will get an error when configuring 348tinc for build. Support for running tinc with other cryptographic libraries 349installed @emph{may} be added in the future. 350 351You can use your operating system's package manager to install this if 352available. Make sure you install the development AND runtime versions 353of this package. 354 355If your operating system comes neither with LibreSSL or OpenSSL, you have to 356install one manually. It is recommended that you get the latest version of 357LibreSSL from @url{http://www.libressl.org/}. Instructions on how to 358configure, build and install this package are included within the package. 359Please make sure you build development and runtime libraries (which is the 360default). 361 362If you installed the LibreSSL or OpenSSL libraries from source, it may be necessary 363to let configure know where they are, by passing configure one of the 364--with-openssl-* parameters. Note that you even have to use --with-openssl-* if you 365are using LibreSSL. 366 367@example 368--with-openssl=DIR LibreSSL/OpenSSL library and headers prefix 369--with-openssl-include=DIR LibreSSL/OpenSSL headers directory 370 (Default is OPENSSL_DIR/include) 371--with-openssl-lib=DIR LibreSSL/OpenSSL library directory 372 (Default is OPENSSL_DIR/lib) 373@end example 374 375 376@subsubheading License 377 378@cindex license 379The complete source code of tinc is covered by the GNU GPL version 2. 380Since the license under which OpenSSL is distributed is not directly 381compatible with the terms of the GNU GPL 382@uref{https://www.openssl.org/support/faq.html#LEGAL2}, we 383include an exemption to the GPL (see also the file COPYING.README) to allow 384everyone to create a statically or dynamically linked executable: 385 386@quotation 387This program is released under the GPL with the additional exemption 388that compiling, linking, and/or using OpenSSL is allowed. You may 389provide binary packages linked to the OpenSSL libraries, provided that 390all other requirements of the GPL are met. 391@end quotation 392 393Since the LZO library used by tinc is also covered by the GPL, 394we also present the following exemption: 395 396@quotation 397Hereby I grant a special exception to the tinc VPN project 398(https://www.tinc-vpn.org/) to link the LZO library with the OpenSSL library 399(https://www.openssl.org). 400 401Markus F.X.J. Oberhumer 402@end quotation 403 404 405@c ================================================================== 406@node zlib 407@subsection zlib 408 409@cindex zlib 410For the optional compression of UDP packets, tinc uses the functions provided 411by the zlib library. 412 413If this library is not installed, you will get an error when running the 414configure script. You can either install the zlib library, or disable support 415for zlib compression by using the "--disable-zlib" option when running the 416configure script. Note that if you disable support for zlib, the resulting 417binary will not work correctly on VPNs where zlib compression is used. 418 419You can use your operating system's package manager to install this if 420available. Make sure you install the development AND runtime versions 421of this package. 422 423If you have to install zlib manually, you can get the source code 424from @url{https://zlib.net/}. Instructions on how to configure, 425build and install this package are included within the package. Please 426make sure you build development and runtime libraries (which is the 427default). 428 429 430@c ================================================================== 431@node lzo 432@subsection lzo 433 434@cindex lzo 435Another form of compression is offered using the LZO library. 436 437If this library is not installed, you will get an error when running the 438configure script. You can either install the LZO library, or disable support 439for LZO compression by using the "--disable-lzo" option when running the 440configure script. Note that if you disable support for LZO, the resulting 441binary will not work correctly on VPNs where LZO compression is used. 442 443You can use your operating system's package manager to install this if 444available. Make sure you install the development AND runtime versions 445of this package. 446 447If you have to install lzo manually, you can get the source code 448from @url{https://www.oberhumer.com/opensource/lzo/}. Instructions on how to configure, 449build and install this package are included within the package. Please 450make sure you build development and runtime libraries (which is the 451default). 452 453 454@c 455@c 456@c 457@c Installing tinc 458@c 459@c 460@c 461@c 462 463@c ================================================================== 464@node Installation 465@chapter Installation 466 467If you use Debian, you may want to install one of the 468precompiled packages for your system. These packages are equipped with 469system startup scripts and sample configurations. 470 471If you cannot use one of the precompiled packages, or you want to compile tinc 472for yourself, you can use the source. The source is distributed under 473the GNU General Public License (GPL). Download the source from the 474@uref{https://www.tinc-vpn.org/download/, download page}. 475 476Tinc comes in a convenient autoconf/automake package, which you can just 477treat the same as any other package. Which is just untar it, type 478`./configure' and then `make'. 479More detailed instructions are in the file @file{INSTALL}, which is 480included in the source distribution. 481 482@menu 483* Building and installing tinc:: 484* System files:: 485@end menu 486 487 488@c ================================================================== 489@node Building and installing tinc 490@section Building and installing tinc 491 492Detailed instructions on configuring the source, building tinc and installing tinc 493can be found in the file called @file{INSTALL}. 494 495@cindex binary package 496If you happen to have a binary package for tinc for your distribution, 497you can use the package management tools of that distribution to install tinc. 498The documentation that comes along with your distribution will tell you how to do that. 499 500@menu 501* Darwin (Mac OS X) build environment:: 502* Cygwin (Windows) build environment:: 503* MinGW (Windows) build environment:: 504@end menu 505 506 507@c ================================================================== 508@node Darwin (Mac OS X) build environment 509@subsection Darwin (Mac OS X) build environment 510 511In order to build tinc on Darwin, you need to install Xcode from @uref{https://developer.apple.com/xcode/}. 512It might also help to install a recent version of Fink from @uref{http://www.finkproject.org/}. 513 514You need to download and install LibreSSL (or OpenSSL) and LZO, 515either directly from their websites (see @ref{Libraries}) or using Fink. 516 517@c ================================================================== 518@node Cygwin (Windows) build environment 519@subsection Cygwin (Windows) build environment 520 521If Cygwin hasn't already been installed, install it directly from 522@uref{https://www.cygwin.com/}. 523 524When tinc is compiled in a Cygwin environment, it can only be run in this environment, 525but all programs, including those started outside the Cygwin environment, will be able to use the VPN. 526It will also support all features. 527 528@c ================================================================== 529@node MinGW (Windows) build environment 530@subsection MinGW (Windows) build environment 531 532You will need to install the MinGW environment from @uref{http://www.mingw.org}. 533You also need to download and install LibreSSL (or OpenSSL) and LZO. 534 535When tinc is compiled using MinGW it runs natively under Windows, 536it is not necessary to keep MinGW installed. 537 538When detaching, tinc will install itself as a service, 539which will be restarted automatically after reboots. 540 541 542@c ================================================================== 543@node System files 544@section System files 545 546Before you can run tinc, you must make sure you have all the needed 547files on your system. 548 549@menu 550* Device files:: 551* Other files:: 552@end menu 553 554 555@c ================================================================== 556@node Device files 557@subsection Device files 558 559@cindex device files 560Most operating systems nowadays come with the necessary device files by default, 561or they have a mechanism to create them on demand. 562 563If you use Linux and do not have udev installed, 564you may need to create the following device file if it does not exist: 565 566@example 567mknod -m 600 /dev/net/tun c 10 200 568@end example 569 570 571@c ================================================================== 572@node Other files 573@subsection Other files 574 575@subsubheading @file{/etc/networks} 576 577You may add a line to @file{/etc/networks} so that your VPN will get a 578symbolic name. For example: 579 580@example 581myvpn 10.0.0.0 582@end example 583 584@subsubheading @file{/etc/services} 585 586@cindex port numbers 587You may add this line to @file{/etc/services}. The effect is that you 588may supply a @samp{tinc} as a valid port number to some programs. The 589number 655 is registered with the IANA. 590 591@example 592tinc 655/tcp TINC 593tinc 655/udp TINC 594# Ivo Timmermans <ivo@@tinc-vpn.org> 595@end example 596 597 598@c 599@c 600@c 601@c 602@c Configuring tinc 603@c 604@c 605@c 606@c 607 608 609@c ================================================================== 610@node Configuration 611@chapter Configuration 612 613@menu 614* Configuration introduction:: 615* Multiple networks:: 616* How connections work:: 617* Configuration files:: 618* Generating keypairs:: 619* Network interfaces:: 620* Example configuration:: 621@end menu 622 623@c ================================================================== 624@node Configuration introduction 625@section Configuration introduction 626 627Before actually starting to configure tinc and editing files, 628make sure you have read this entire section so you know what to expect. 629Then, make it clear to yourself how you want to organize your VPN: 630What are the nodes (computers running tinc)? 631What IP addresses/subnets do they have? 632What is the network mask of the entire VPN? 633Do you need special firewall rules? 634Do you have to set up masquerading or forwarding rules? 635Do you want to run tinc in router mode or switch mode? 636These questions can only be answered by yourself, 637you will not find the answers in this documentation. 638Make sure you have an adequate understanding of networks in general. 639@cindex Network Administrators Guide 640A good resource on networking is the 641@uref{http://www.tldp.org/LDP/nag2/, Linux Network Administrators Guide}. 642 643If you have everything clearly pictured in your mind, 644proceed in the following order: 645First, generate the configuration files (@file{tinc.conf}, your host configuration file, @file{tinc-up} and perhaps @file{tinc-down}). 646Then generate the keypairs. 647Finally, distribute the host configuration files. 648These steps are described in the subsections below. 649 650 651@c ================================================================== 652@node Multiple networks 653@section Multiple networks 654 655@cindex multiple networks 656@cindex netname 657In order to allow you to run more than one tinc daemon on one computer, 658for instance if your computer is part of more than one VPN, 659you can assign a @var{netname} to your VPN. 660It is not required if you only run one tinc daemon, 661it doesn't even have to be the same on all the sites of your VPN, 662but it is recommended that you choose one anyway. 663 664We will assume you use a netname throughout this document. 665This means that you call tincd with the -n argument, 666which will assign a netname to this daemon. 667 668The effect of this is that the daemon will set its configuration 669root to @file{@value{sysconfdir}/tinc/@var{netname}/}, where @var{netname} is your argument to the -n 670option. You'll notice that it appears in syslog as @file{tinc.@var{netname}}. 671 672However, it is not strictly necessary that you call tinc with the -n 673option. In this case, the network name would just be empty, and it will 674be used as such. tinc now looks for files in @file{@value{sysconfdir}/tinc/}, instead of 675@file{@value{sysconfdir}/tinc/@var{netname}/}; the configuration file should be @file{@value{sysconfdir}/tinc/tinc.conf}, 676and the host configuration files are now expected to be in @file{@value{sysconfdir}/tinc/hosts/}. 677 678But it is highly recommended that you use this feature of tinc, because 679it will be so much clearer whom your daemon talks to. Hence, we will 680assume that you use it. 681 682 683@c ================================================================== 684@node How connections work 685@section How connections work 686 687When tinc starts up, it parses the command-line options and then 688reads in the configuration file tinc.conf. 689If it sees one or more `ConnectTo' values pointing to other tinc daemons in that file, 690it will try to connect to those other daemons. 691Whether this succeeds or not and whether `ConnectTo' is specified or not, 692tinc will listen for incoming connection from other daemons. 693If you did specify a `ConnectTo' value and the other side is not responding, 694tinc will keep retrying. 695This means that once started, tinc will stay running until you tell it to stop, 696and failures to connect to other tinc daemons will not stop your tinc daemon 697for trying again later. 698This means you don't have to intervene if there are temporary network problems. 699 700@cindex client 701@cindex server 702There is no real distinction between a server and a client in tinc. 703If you wish, you can view a tinc daemon without a `ConnectTo' value as a server, 704and one which does specify such a value as a client. 705It does not matter if two tinc daemons have a `ConnectTo' value pointing to each other however. 706 707 708@c ================================================================== 709@node Configuration files 710@section Configuration files 711 712The actual configuration of the daemon is done in the file 713@file{@value{sysconfdir}/tinc/@var{netname}/tinc.conf} and at least one other file in the directory 714@file{@value{sysconfdir}/tinc/@var{netname}/hosts/}. 715 716An optional directory @file{@value{sysconfdir}/tinc/@var{netname}/conf.d} can be added from which 717any .conf file will be read. 718 719These file consists of comments (lines started with a #) or assignments 720in the form of 721 722@example 723Variable = Value. 724@end example 725 726The variable names are case insensitive, and any spaces, tabs, newlines 727and carriage returns are ignored. Note: it is not required that you put 728in the `=' sign, but doing so improves readability. If you leave it 729out, remember to replace it with at least one space character. 730 731The server configuration is complemented with host specific configuration (see 732the next section). Although all host configuration options for the local node 733listed in this document can also be put in 734@file{@value{sysconfdir}/tinc/@var{netname}/tinc.conf}, it is recommended to 735put host specific configuration options in the host configuration file, as this 736makes it easy to exchange with other nodes. 737 738In this section all valid variables are listed in alphabetical order. 739The default value is given between parentheses, 740other comments are between square brackets. 741 742@menu 743* Main configuration variables:: 744* Host configuration variables:: 745* Scripts:: 746* How to configure:: 747@end menu 748 749 750@c ================================================================== 751@node Main configuration variables 752@subsection Main configuration variables 753 754@table @asis 755@cindex AddressFamily 756@item AddressFamily = <ipv4|ipv6|any> (any) 757This option affects the address family of listening and outgoing sockets. 758If any is selected, then depending on the operating system 759both IPv4 and IPv6 or just IPv6 listening sockets will be created. 760 761@cindex BindToAddress 762@item BindToAddress = <@var{address}> [<@var{port}>] [experimental] 763If your computer has more than one IPv4 or IPv6 address, tinc 764will by default listen on all of them for incoming connections. 765Multiple BindToAddress variables may be specified, 766in which case listening sockets for each specified address are made. 767 768If no @var{port} is specified, the socket will be bound to the port specified by the Port option, 769or to port 655 if neither is given. 770To only bind to a specific port but not to a specific address, use "*" for the @var{address}. 771 772This option may not work on all platforms. 773 774@cindex BindToInterface 775@item BindToInterface = <@var{interface}> [experimental] 776If you have more than one network interface in your computer, tinc will 777by default listen on all of them for incoming connections. It is 778possible to bind tinc to a single interface like eth0 or ppp0 with this 779variable. 780 781This option may not work on all platforms. 782 783@cindex Broadcast 784@item Broadcast = <no | mst | direct> (mst) [experimental] 785This option selects the way broadcast packets are sent to other daemons. 786@emph{NOTE: all nodes in a VPN must use the same Broadcast mode, otherwise routing loops can form.} 787 788@table @asis 789@item no 790Broadcast packets are never sent to other nodes. 791 792@item mst 793Broadcast packets are sent and forwarded via the VPN's Minimum Spanning Tree. 794This ensures broadcast packets reach all nodes. 795 796@item direct 797Broadcast packets are sent directly to all nodes that can be reached directly. 798Broadcast packets received from other nodes are never forwarded. 799If the IndirectData option is also set, broadcast packets will only be sent to nodes which we have a meta connection to. 800@end table 801 802@cindex ConnectTo 803@item ConnectTo = <@var{name}> 804Specifies which other tinc daemon to connect to on startup. 805Multiple ConnectTo variables may be specified, 806in which case outgoing connections to each specified tinc daemon are made. 807The names should be known to this tinc daemon 808(i.e., there should be a host configuration file for the name on the ConnectTo line). 809 810If you don't specify a host with ConnectTo, 811tinc won't try to connect to other daemons at all, 812and will instead just listen for incoming connections. 813 814@cindex DecrementTTL 815@item DecrementTTL = <yes | no> (no) [experimental] 816When enabled, tinc will decrement the Time To Live field in IPv4 packets, or the Hop Limit field in IPv6 packets, 817before forwarding a received packet to the virtual network device or to another node, 818and will drop packets that have a TTL value of zero, 819in which case it will send an ICMP Time Exceeded packet back. 820 821Do not use this option if you use switch mode and want to use IPv6. 822 823@cindex Device 824@item Device = <@var{device}> (@file{/dev/tap0}, @file{/dev/net/tun} or other depending on platform) 825The virtual network device to use. 826Tinc will automatically detect what kind of device it is. 827Under Windows, use @var{Interface} instead of @var{Device}. 828Note that you can only use one device per daemon. 829See also @ref{Device files}. 830 831@cindex DeviceType 832@item DeviceType = <@var{type}> (platform dependent) 833The type of the virtual network device. 834Tinc will normally automatically select the right type of tun/tap interface, and this option should not be used. 835However, this option can be used to select one of the special interface types, if support for them is compiled in. 836 837@table @asis 838@cindex dummy 839@item dummy 840Use a dummy interface. 841No packets are ever read or written to a virtual network device. 842Useful for testing, or when setting up a node that only forwards packets for other nodes. 843 844@cindex raw_socket 845@item raw_socket 846Open a raw socket, and bind it to a pre-existing 847@var{Interface} (eth0 by default). 848All packets are read from this interface. 849Packets received for the local node are written to the raw socket. 850However, at least on Linux, the operating system does not process IP packets destined for the local host. 851 852@cindex multicast 853@item multicast 854Open a multicast UDP socket and bind it to the address and port (separated by spaces) and optionally a TTL value specified using @var{Device}. 855Packets are read from and written to this multicast socket. 856This can be used to connect to UML, QEMU or KVM instances listening on the same multicast address. 857Do NOT connect multiple tinc daemons to the same multicast address, this will very likely cause routing loops. 858Also note that this can cause decrypted VPN packets to be sent out on a real network if misconfigured. 859 860@cindex UML 861@item uml (not compiled in by default) 862Create a UNIX socket with the filename specified by 863@var{Device}, or @file{@value{runstatedir}/@var{netname}.umlsocket} 864if not specified. 865Tinc will wait for a User Mode Linux instance to connect to this socket. 866 867@cindex VDE 868@item vde (not compiled in by default) 869Uses the libvdeplug library to connect to a Virtual Distributed Ethernet switch, 870using the UNIX socket specified by 871@var{Device}, or @file{@value{runstatedir}/vde.ctl} 872if not specified. 873@end table 874 875Also, in case tinc does not seem to correctly interpret packets received from the virtual network device, 876it can be used to change the way packets are interpreted: 877 878@table @asis 879@item tun (BSD and Linux) 880Set type to tun. 881Depending on the platform, this can either be with or without an address family header (see below). 882 883@cindex tunnohead 884@item tunnohead (BSD) 885Set type to tun without an address family header. 886Tinc will expect packets read from the virtual network device to start with an IP header. 887On some platforms IPv6 packets cannot be read from or written to the device in this mode. 888 889@cindex tunifhead 890@item tunifhead (BSD) 891Set type to tun with an address family header. 892Tinc will expect packets read from the virtual network device 893to start with a four byte header containing the address family, 894followed by an IP header. 895This mode should support both IPv4 and IPv6 packets. 896 897@cindex utun 898@item utun (OS X) 899Set type to utun. 900This is only supported on OS X version 10.6.8 and higher, but doesn't require the tuntaposx module. 901This mode should support both IPv4 and IPv6 packets. 902 903@item tap (BSD and Linux) 904Set type to tap. 905Tinc will expect packets read from the virtual network device 906to start with an Ethernet header. 907@end table 908 909@cindex DirectOnly 910@item DirectOnly = <yes|no> (no) [experimental] 911When this option is enabled, packets that cannot be sent directly to the destination node, 912but which would have to be forwarded by an intermediate node, are dropped instead. 913When combined with the IndirectData option, 914packets for nodes for which we do not have a meta connection with are also dropped. 915 916@cindex Forwarding 917@item Forwarding = <off|internal|kernel> (internal) [experimental] 918This option selects the way indirect packets are forwarded. 919 920@table @asis 921@item off 922Incoming packets that are not meant for the local node, 923but which should be forwarded to another node, are dropped. 924 925@item internal 926Incoming packets that are meant for another node are forwarded by tinc internally. 927 928This is the default mode, and unless you really know you need another forwarding mode, don't change it. 929 930@item kernel 931Incoming packets are always sent to the TUN/TAP device, even if the packets are not for the local node. 932This is less efficient, but allows the kernel to apply its routing and firewall rules on them, 933and can also help debugging. 934@end table 935 936@cindex GraphDumpFile 937@item GraphDumpFile = <@var{filename}> [experimental] 938If this option is present, 939tinc will dump the current network graph to the file @var{filename} 940every minute, unless there were no changes to the graph. 941The file is in a format that can be read by graphviz tools. 942If @var{filename} starts with a pipe symbol |, 943then the rest of the filename is interpreted as a shell command 944that is executed, the graph is then sent to stdin. 945 946@cindex Hostnames 947@item Hostnames = <yes|no> (no) 948This option selects whether IP addresses (both real and on the VPN) 949should be resolved. Since DNS lookups are blocking, it might affect 950tinc's efficiency, even stopping the daemon for a few seconds every time 951it does a lookup if your DNS server is not responding. 952 953This does not affect resolving hostnames to IP addresses from the 954configuration file, but whether hostnames should be resolved while logging. 955 956@cindex IffOneQueue 957@item IffOneQueue = <yes|no> (no) [experimental] 958(Linux only) Set IFF_ONE_QUEUE flag on TUN/TAP devices. 959 960@cindex Interface 961@item Interface = <@var{interface}> 962Defines the name of the interface corresponding to the virtual network device. 963Depending on the operating system and the type of device this may or may not actually set the name of the interface. 964Under Windows, this variable is used to select which network interface will be used. 965If you specified a Device, this variable is almost always already correctly set. 966 967@cindex KeyExpire 968@item KeyExpire = <@var{seconds}> (3600) 969This option controls the time the encryption keys used to encrypt the data 970are valid. It is common practice to change keys at regular intervals to 971make it even harder for crackers, even though it is thought to be nearly 972impossible to crack a single key. 973 974@cindex LocalDiscovery 975@item LocalDiscovery = <yes | no> (no) [experimental] 976When enabled, tinc will try to detect peers that are on the same local network. 977This will allow direct communication using LAN addresses, even if both peers are behind a NAT 978and they only ConnectTo a third node outside the NAT, 979which normally would prevent the peers from learning each other's LAN address. 980 981Currently, local discovery is implemented by sending broadcast packets to the LAN during path MTU discovery. 982This feature may not work in all possible situations. 983 984@cindex MACExpire 985@item MACExpire = <@var{seconds}> (600) 986This option controls the amount of time MAC addresses are kept before they are removed. 987This only has effect when Mode is set to "switch". 988 989@cindex MaxTimeout 990@item MaxTimeout = <@var{seconds}> (900) 991This is the maximum delay before trying to reconnect to other tinc daemons. 992 993@cindex Mode 994@item Mode = <router|switch|hub> (router) 995This option selects the way packets are routed to other daemons. 996 997@table @asis 998@cindex router 999@item router 1000In this mode Subnet 1001variables in the host configuration files will be used to form a routing table. 1002Only unicast packets of routable protocols (IPv4 and IPv6) are supported in this mode. 1003 1004This is the default mode, and unless you really know you need another mode, don't change it. 1005 1006@cindex switch 1007@item switch 1008In this mode the MAC addresses of the packets on the VPN will be used to 1009dynamically create a routing table just like an Ethernet switch does. 1010Unicast, multicast and broadcast packets of every protocol that runs over Ethernet are supported in this mode 1011at the cost of frequent broadcast ARP requests and routing table updates. 1012 1013This mode is primarily useful if you want to bridge Ethernet segments. 1014 1015@cindex hub 1016@item hub 1017This mode is almost the same as the switch mode, but instead 1018every packet will be broadcast to the other daemons 1019while no routing table is managed. 1020@end table 1021 1022@cindex Name 1023@item Name = <@var{name}> [required] 1024This is a symbolic name for this connection. 1025The name must consist only of alphanumeric and underscore characters (a-z, A-Z, 0-9 and _). 1026 1027If Name starts with a $, then the contents of the environment variable that follows will be used. 1028In that case, invalid characters will be converted to underscores. 1029If Name is $HOST, but no such environment variable exist, 1030the hostname will be read using the gethostname() system call. 1031 1032@cindex PingInterval 1033@item PingInterval = <@var{seconds}> (60) 1034The number of seconds of inactivity that tinc will wait before sending a 1035probe to the other end. 1036 1037@cindex PingTimeout 1038@item PingTimeout = <@var{seconds}> (5) 1039The number of seconds to wait for a response to pings or to allow meta 1040connections to block. If the other end doesn't respond within this time, 1041the connection is terminated, and the others will be notified of this. 1042 1043@cindex PriorityInheritance 1044@item PriorityInheritance = <yes|no> (no) [experimental] 1045When this option is enabled the value of the TOS field of tunneled IPv4 packets 1046will be inherited by the UDP packets that are sent out. 1047 1048@cindex PrivateKey 1049@item PrivateKey = <@var{key}> [obsolete] 1050This is the RSA private key for tinc. However, for safety reasons it is 1051advised to store private keys of any kind in separate files. This prevents 1052accidental eavesdropping if you are editing the configuration file. 1053 1054@cindex PrivateKeyFile 1055@item PrivateKeyFile = <@var{path}> (@file{@value{sysconfdir}/tinc/@var{netname}/rsa_key.priv}) 1056This is the full path name of the RSA private key file that was 1057generated by @samp{tincd --generate-keys}. It must be a full path, not a 1058relative directory. 1059 1060@cindex ProcessPriority 1061@item ProcessPriority = <low|normal|high> 1062When this option is used the priority of the tincd process will be adjusted. 1063Increasing the priority may help to reduce latency and packet loss on the VPN. 1064 1065@cindex Proxy 1066@item Proxy = socks4 | socks5 | http | exec @var{...} [experimental] 1067Use a proxy when making outgoing connections. 1068The following proxy types are currently supported: 1069 1070@table @asis 1071@cindex socks4 1072@item socks4 <@var{address}> <@var{port}> [<@var{username}>] 1073Connects to the proxy using the SOCKS version 4 protocol. 1074Optionally, a @var{username} can be supplied which will be passed on to the proxy server. 1075 1076@cindex socks5 1077@item socks5 <@var{address}> <@var{port}> [<@var{username}> <@var{password}>] 1078Connect to the proxy using the SOCKS version 5 protocol. 1079If a @var{username} and @var{password} are given, basic username/password authentication will be used, 1080otherwise no authentication will be used. 1081 1082@cindex http 1083@item http <@var{address}> <@var{port}> 1084Connects to the proxy and sends a HTTP CONNECT request. 1085 1086@cindex exec 1087@item exec <@var{command}> 1088Executes the given command which should set up the outgoing connection. 1089The environment variables @env{NAME}, @env{NODE}, @env{REMOTEADDRES} and @env{REMOTEPORT} are available. 1090@end table 1091 1092@cindex ReplayWindow 1093@item ReplayWindow = <bytes> (16) 1094This is the size of the replay tracking window for each remote node, in bytes. 1095The window is a bitfield which tracks 1 packet per bit, so for example 1096the default setting of 16 will track up to 128 packets in the window. In high 1097bandwidth scenarios, setting this to a higher value can reduce packet loss from 1098the interaction of replay tracking with underlying real packet loss and/or 1099reordering. Setting this to zero will disable replay tracking completely and 1100pass all traffic, but leaves tinc vulnerable to replay-based attacks on your 1101traffic. 1102 1103@cindex StrictSubnets 1104@item StrictSubnets = <yes|no> (no) [experimental] 1105When this option is enabled tinc will only use Subnet statements which are 1106present in the host config files in the local 1107@file{@value{sysconfdir}/tinc/@var{netname}/hosts/} directory. 1108Subnets learned via connections to other nodes and which are not 1109present in the local host config files are ignored. 1110 1111@cindex TunnelServer 1112@item TunnelServer = <yes|no> (no) [experimental] 1113When this option is enabled tinc will no longer forward information between other tinc daemons, 1114and will only allow connections with nodes for which host config files are present in the local 1115@file{@value{sysconfdir}/tinc/@var{netname}/hosts/} directory. 1116Setting this options also implicitly sets StrictSubnets. 1117 1118@cindex UDPRcvBuf 1119@item UDPRcvBuf = <bytes> (OS default) 1120Sets the socket receive buffer size for the UDP socket, in bytes. 1121If unset, the default buffer size will be used by the operating system. 1122 1123@cindex UDPSndBuf 1124@item UDPSndBuf = <bytes> Pq OS default 1125Sets the socket send buffer size for the UDP socket, in bytes. 1126If unset, the default buffer size will be used by the operating system. 1127 1128@end table 1129 1130 1131@c ================================================================== 1132@node Host configuration variables 1133@subsection Host configuration variables 1134 1135@table @asis 1136@cindex Address 1137@item Address = <@var{IP address}|@var{hostname}> [<port>] [recommended] 1138This variable is only required if you want to connect to this host. It 1139must resolve to the external IP address where the host can be reached, 1140not the one that is internal to the VPN. 1141If no port is specified, the default Port is used. 1142Multiple Address variables can be specified, in which case each address will be 1143tried until a working connection has been established. 1144 1145@cindex Cipher 1146@item Cipher = <@var{cipher}> (aes-256-cbc) 1147The symmetric cipher algorithm used to encrypt UDP packets. 1148Any cipher supported by LibreSSL or OpenSSL is recognized. 1149Furthermore, specifying "none" will turn off packet encryption. 1150It is best to use only those ciphers which support CBC mode. 1151 1152@cindex ClampMSS 1153@item ClampMSS = <yes|no> (yes) 1154This option specifies whether tinc should clamp the maximum segment size (MSS) 1155of TCP packets to the path MTU. This helps in situations where ICMP 1156Fragmentation Needed or Packet too Big messages are dropped by firewalls. 1157 1158@cindex Compression 1159@item Compression = <@var{level}> (0) 1160This option sets the level of compression used for UDP packets. 1161Possible values are 0 (off), 1 (fast zlib) and any integer up to 9 (best zlib), 116210 (fast lzo) and 11 (best lzo). 1163 1164@cindex Digest 1165@item Digest = <@var{digest}> (sha256) 1166The digest algorithm used to authenticate UDP packets. 1167Any digest supported by LibreSSL or OpenSSL is recognized. 1168Furthermore, specifying "none" will turn off packet authentication. 1169 1170@cindex IndirectData 1171@item IndirectData = <yes|no> (no) 1172This option specifies whether other tinc daemons besides the one you 1173specified with ConnectTo can make a direct connection to you. This is 1174especially useful if you are behind a firewall and it is impossible to 1175make a connection from the outside to your tinc daemon. Otherwise, it 1176is best to leave this option out or set it to no. 1177 1178@cindex MACLength 1179@item MACLength = <@var{bytes}> (4) 1180The length of the message authentication code used to authenticate UDP packets. 1181Can be anything from 0 1182up to the length of the digest produced by the digest algorithm. 1183 1184@cindex PMTU 1185@item PMTU = <@var{mtu}> (1514) 1186This option controls the initial path MTU to this node. 1187 1188@cindex PMTUDiscovery 1189@item PMTUDiscovery = <yes|no> (yes) 1190When this option is enabled, tinc will try to discover the path MTU to this node. 1191After the path MTU has been discovered, it will be enforced on the VPN. 1192 1193@cindex Port 1194@item Port = <@var{port}> (655) 1195This is the port this tinc daemon listens on. 1196You can use decimal portnumbers or symbolic names (as listed in @file{/etc/services}). 1197 1198@cindex PublicKey 1199@item PublicKey = <@var{key}> [obsolete] 1200This is the RSA public key for this host. 1201 1202@cindex PublicKeyFile 1203@item PublicKeyFile = <@var{path}> [obsolete] 1204This is the full path name of the RSA public key file that was generated 1205by @samp{tincd --generate-keys}. It must be a full path, not a relative 1206directory. 1207 1208@cindex PEM format 1209From version 1.0pre4 on tinc will store the public key directly into the 1210host configuration file in PEM format, the above two options then are not 1211necessary. Either the PEM format is used, or exactly 1212@strong{one of the above two options} must be specified 1213in each host configuration file, if you want to be able to establish a 1214connection with that host. 1215 1216@cindex Subnet 1217@item Subnet = <@var{address}[/@var{prefixlength}[#@var{weight}]]> 1218The subnet which this tinc daemon will serve. 1219Tinc tries to look up which other daemon it should send a packet to by searching the appropriate subnet. 1220If the packet matches a subnet, 1221it will be sent to the daemon who has this subnet in his host configuration file. 1222Multiple subnet lines can be specified for each daemon. 1223 1224Subnets can either be single MAC, IPv4 or IPv6 addresses, 1225in which case a subnet consisting of only that single address is assumed, 1226or they can be a IPv4 or IPv6 network address with a prefixlength. 1227For example, IPv4 subnets must be in a form like 192.168.1.0/24, 1228where 192.168.1.0 is the network address and 24 is the number of bits set in the netmask. 1229Note that subnets like 192.168.1.1/24 are invalid! 1230Read a networking HOWTO/FAQ/guide if you don't understand this. 1231IPv6 subnets are notated like fec0:0:0:1::/64. 1232MAC addresses are notated like 0:1a:2b:3c:4d:5e. 1233 1234@cindex CIDR notation 1235Prefixlength is the number of bits set to 1 in the netmask part; for 1236example: netmask 255.255.255.0 would become /24, 255.255.252.0 becomes 1237/22. This conforms to standard CIDR notation as described in 1238@uref{https://www.ietf.org/rfc/rfc1519.txt, RFC1519} 1239 1240@cindex Subnet weight 1241A Subnet can be given a weight to indicate its priority over identical Subnets 1242owned by different nodes. The default weight is 10. Lower values indicate 1243higher priority. Packets will be sent to the node with the highest priority, 1244unless that node is not reachable, in which case the node with the next highest 1245priority will be tried, and so on. 1246 1247@cindex TCPonly 1248@item TCPonly = <yes|no> (no) [deprecated] 1249If this variable is set to yes, then the packets are tunnelled over a 1250TCP connection instead of a UDP connection. This is especially useful 1251for those who want to run a tinc daemon from behind a masquerading 1252firewall, or if UDP packet routing is disabled somehow. 1253Setting this options also implicitly sets IndirectData. 1254 1255Since version 1.0.10, tinc will automatically detect whether communication via 1256UDP is possible or not. 1257@end table 1258 1259 1260@c ================================================================== 1261@node Scripts 1262@subsection Scripts 1263 1264@cindex scripts 1265Apart from reading the server and host configuration files, 1266tinc can also run scripts at certain moments. 1267Below is a list of filenames of scripts and a description of when they are run. 1268A script is only run if it exists and if it is executable. 1269 1270Scripts are run synchronously; 1271this means that tinc will temporarily stop processing packets until the called script finishes executing. 1272This guarantees that scripts will execute in the exact same order as the events that trigger them. 1273If you need to run commands asynchronously, you have to ensure yourself that they are being run in the background. 1274 1275Under Windows (not Cygwin), the scripts must have the extension .bat. 1276 1277@table @file 1278@cindex tinc-up 1279@item @value{sysconfdir}/tinc/@var{netname}/tinc-up 1280This is the most important script. 1281If it is present it will be executed right after the tinc daemon has been 1282started and has connected to the virtual network device. 1283It should be used to set up the corresponding network interface, 1284but can also be used to start other things. 1285 1286Under Windows you can use the Network Connections control panel instead of creating this script. 1287 1288@cindex tinc-down 1289@item @value{sysconfdir}/tinc/@var{netname}/tinc-down 1290This script is started right before the tinc daemon quits. 1291 1292@item @value{sysconfdir}/tinc/@var{netname}/hosts/@var{host}-up 1293This script is started when the tinc daemon with name @var{host} becomes reachable. 1294 1295@item @value{sysconfdir}/tinc/@var{netname}/hosts/@var{host}-down 1296This script is started when the tinc daemon with name @var{host} becomes unreachable. 1297 1298@item @value{sysconfdir}/tinc/@var{netname}/host-up 1299This script is started when any host becomes reachable. 1300 1301@item @value{sysconfdir}/tinc/@var{netname}/host-down 1302This script is started when any host becomes unreachable. 1303 1304@item @value{sysconfdir}/tinc/@var{netname}/subnet-up 1305This script is started when a subnet becomes reachable. 1306The Subnet and the node it belongs to are passed in environment variables. 1307 1308@item @value{sysconfdir}/tinc/@var{netname}/subnet-down 1309This script is started when a subnet becomes unreachable. 1310@end table 1311 1312@cindex environment variables 1313The scripts are started without command line arguments, 1314but can make use of certain environment variables. 1315Under UNIX like operating systems the names of environment variables must be preceded by a $ in scripts. 1316Under Windows, in @file{.bat} files, they have to be put between % signs. 1317 1318@table @env 1319@cindex NETNAME 1320@item NETNAME 1321If a netname was specified, this environment variable contains it. 1322 1323@cindex NAME 1324@item NAME 1325Contains the name of this tinc daemon. 1326 1327@cindex DEVICE 1328@item DEVICE 1329Contains the name of the virtual network device that tinc uses. 1330 1331@cindex INTERFACE 1332@item INTERFACE 1333Contains the name of the virtual network interface that tinc uses. 1334This should be used for commands like ifconfig. 1335 1336@cindex NODE 1337@item NODE 1338When a host becomes (un)reachable, this is set to its name. 1339If a subnet becomes (un)reachable, this is set to the owner of that subnet. 1340 1341@cindex REMOTEADDRESS 1342@item REMOTEADDRESS 1343When a host becomes (un)reachable, this is set to its real address. 1344 1345@cindex REMOTEPORT 1346@item REMOTEPORT 1347When a host becomes (un)reachable, 1348this is set to the port number it uses for communication with other tinc daemons. 1349 1350@cindex SUBNET 1351@item SUBNET 1352When a subnet becomes (un)reachable, this is set to the subnet. 1353 1354@cindex WEIGHT 1355@item WEIGHT 1356When a subnet becomes (un)reachable, this is set to the subnet weight. 1357 1358@end table 1359 1360 1361@c ================================================================== 1362@node How to configure 1363@subsection How to configure 1364 1365@subsubheading Step 1. Creating the main configuration file 1366 1367The main configuration file will be called @file{@value{sysconfdir}/tinc/@var{netname}/tinc.conf}. 1368Adapt the following example to create a basic configuration file: 1369 1370@example 1371Name = @var{yourname} 1372Device = @file{/dev/tap0} 1373@end example 1374 1375Then, if you know to which other tinc daemon(s) yours is going to connect, 1376add `ConnectTo' values. 1377 1378@subsubheading Step 2. Creating your host configuration file 1379 1380If you added a line containing `Name = yourname' in the main configuration file, 1381you will need to create a host configuration file @file{@value{sysconfdir}/tinc/@var{netname}/hosts/yourname}. 1382Adapt the following example to create a host configuration file: 1383 1384@example 1385Address = your.real.hostname.org 1386Subnet = 192.168.1.0/24 1387@end example 1388 1389You can also use an IP address instead of a hostname. 1390The `Subnet' specifies the address range that is local for @emph{your part of the VPN only}. 1391If you have multiple address ranges you can specify more than one `Subnet'. 1392You might also need to add a `Port' if you want your tinc daemon to run on a different port number than the default (655). 1393 1394 1395@c ================================================================== 1396@node Generating keypairs 1397@section Generating keypairs 1398 1399@cindex key generation 1400Now that you have already created the main configuration file and your host configuration file, 1401you can easily create a public/private keypair by entering the following command: 1402 1403@example 1404tincd -n @var{netname} -K 1405@end example 1406 1407Tinc will generate a public and a private key and ask you where to put them. 1408Just press enter to accept the defaults. 1409 1410 1411@c ================================================================== 1412@node Network interfaces 1413@section Network interfaces 1414 1415Before tinc can start transmitting data over the tunnel, it must 1416set up the virtual network interface. 1417 1418First, decide which IP addresses you want to have associated with these 1419devices, and what network mask they must have. 1420 1421Tinc will open a virtual network device (@file{/dev/tun}, @file{/dev/tap0} or similar), 1422which will also create a network interface called something like @samp{tun0}, @samp{tap0}. 1423If you are using the Linux tun/tap driver, the network interface will by default have the same name as the @var{netname}. 1424Under Windows you can change the name of the network interface from the Network Connections control panel. 1425 1426@cindex tinc-up 1427You can configure the network interface by putting ordinary ifconfig, route, and other commands 1428to a script named @file{@value{sysconfdir}/tinc/@var{netname}/tinc-up}. 1429When tinc starts, this script will be executed. When tinc exits, it will execute the script named 1430@file{@value{sysconfdir}/tinc/@var{netname}/tinc-down}, but normally you don't need to create that script. 1431 1432An example @file{tinc-up} script: 1433 1434@example 1435#!/bin/sh 1436ifconfig $INTERFACE 192.168.1.1 netmask 255.255.0.0 1437@end example 1438 1439This script gives the interface an IP address and a netmask. 1440The kernel will also automatically add a route to this interface, so normally you don't need 1441to add route commands to the @file{tinc-up} script. 1442The kernel will also bring the interface up after this command. 1443@cindex netmask 1444The netmask is the mask of the @emph{entire} VPN network, not just your 1445own subnet. 1446 1447The exact syntax of the ifconfig and route commands differs from platform to platform. 1448You can look up the commands for setting addresses and adding routes in @ref{Platform specific information}, 1449but it is best to consult the manpages of those utilities on your platform. 1450 1451 1452@c ================================================================== 1453@node Example configuration 1454@section Example configuration 1455 1456 1457@cindex example 1458Imagine the following situation. Branch A of our example `company' wants to connect 1459three branch offices in B, C and D using the Internet. All four offices 1460have a 24/7 connection to the Internet. 1461 1462A is going to serve as the center of the network. B and C will connect 1463to A, and D will connect to C. Each office will be assigned their own IP 1464network, 10.x.0.0. 1465 1466@example 1467A: net 10.1.0.0 mask 255.255.0.0 gateway 10.1.54.1 internet IP 1.2.3.4 1468B: net 10.2.0.0 mask 255.255.0.0 gateway 10.2.1.12 internet IP 2.3.4.5 1469C: net 10.3.0.0 mask 255.255.0.0 gateway 10.3.69.254 internet IP 3.4.5.6 1470D: net 10.4.0.0 mask 255.255.0.0 gateway 10.4.3.32 internet IP 4.5.6.7 1471@end example 1472 1473Here, ``gateway'' is the VPN IP address of the machine that is running the 1474tincd, and ``internet IP'' is the IP address of the firewall, which does not 1475need to run tincd, but it must do a port forwarding of TCP and UDP on port 1476655 (unless otherwise configured). 1477 1478In this example, it is assumed that eth0 is the interface that points to 1479the inner (physical) LAN of the office, although this could also be the 1480same as the interface that leads to the Internet. The configuration of 1481the real interface is also shown as a comment, to give you an idea of 1482how these example host is set up. All branches use the netname `company' 1483for this particular VPN. 1484 1485@subsubheading For Branch A 1486 1487@emph{BranchA} would be configured like this: 1488 1489In @file{@value{sysconfdir}/tinc/company/tinc-up}: 1490 1491@example 1492# Real interface of internal network: 1493# ifconfig eth0 10.1.54.1 netmask 255.255.0.0 1494 1495ifconfig $INTERFACE 10.1.54.1 netmask 255.0.0.0 1496@end example 1497 1498and in @file{@value{sysconfdir}/tinc/company/tinc.conf}: 1499 1500@example 1501Name = BranchA 1502Device = /dev/tap0 1503@end example 1504 1505On all hosts, @file{@value{sysconfdir}/tinc/company/hosts/BranchA} contains: 1506 1507@example 1508Subnet = 10.1.0.0/16 1509Address = 1.2.3.4 1510 1511-----BEGIN RSA PUBLIC KEY----- 1512... 1513-----END RSA PUBLIC KEY----- 1514@end example 1515 1516Note that the IP addresses of eth0 and tap0 are the same. 1517This is quite possible, if you make sure that the netmasks of the interfaces are different. 1518It is in fact recommended to give both real internal network interfaces and tap interfaces the same IP address, 1519since that will make things a lot easier to remember and set up. 1520 1521 1522@subsubheading For Branch B 1523 1524In @file{@value{sysconfdir}/tinc/company/tinc-up}: 1525 1526@example 1527# Real interface of internal network: 1528# ifconfig eth0 10.2.43.8 netmask 255.255.0.0 1529 1530ifconfig $INTERFACE 10.2.1.12 netmask 255.0.0.0 1531@end example 1532 1533and in @file{@value{sysconfdir}/tinc/company/tinc.conf}: 1534 1535@example 1536Name = BranchB 1537ConnectTo = BranchA 1538@end example 1539 1540Note here that the internal address (on eth0) doesn't have to be the 1541same as on the tap0 device. Also, ConnectTo is given so that this node will 1542always try to connect to BranchA. 1543 1544On all hosts, in @file{@value{sysconfdir}/tinc/company/hosts/BranchB}: 1545 1546@example 1547Subnet = 10.2.0.0/16 1548Address = 2.3.4.5 1549 1550-----BEGIN RSA PUBLIC KEY----- 1551... 1552-----END RSA PUBLIC KEY----- 1553@end example 1554 1555 1556@subsubheading For Branch C 1557 1558In @file{@value{sysconfdir}/tinc/company/tinc-up}: 1559 1560@example 1561# Real interface of internal network: 1562# ifconfig eth0 10.3.69.254 netmask 255.255.0.0 1563 1564ifconfig $INTERFACE 10.3.69.254 netmask 255.0.0.0 1565@end example 1566 1567and in @file{@value{sysconfdir}/tinc/company/tinc.conf}: 1568 1569@example 1570Name = BranchC 1571ConnectTo = BranchA 1572Device = /dev/tap1 1573@end example 1574 1575C already has another daemon that runs on port 655, so they have to 1576reserve another port for tinc. It knows the portnumber it has to listen on 1577from it's own host configuration file. 1578 1579On all hosts, in @file{@value{sysconfdir}/tinc/company/hosts/BranchC}: 1580 1581@example 1582Address = 3.4.5.6 1583Subnet = 10.3.0.0/16 1584Port = 2000 1585 1586-----BEGIN RSA PUBLIC KEY----- 1587... 1588-----END RSA PUBLIC KEY----- 1589@end example 1590 1591 1592@subsubheading For Branch D 1593 1594In @file{@value{sysconfdir}/tinc/company/tinc-up}: 1595 1596@example 1597# Real interface of internal network: 1598# ifconfig eth0 10.4.3.32 netmask 255.255.0.0 1599 1600ifconfig $INTERFACE 10.4.3.32 netmask 255.0.0.0 1601@end example 1602 1603and in @file{@value{sysconfdir}/tinc/company/tinc.conf}: 1604 1605@example 1606Name = BranchD 1607ConnectTo = BranchC 1608Device = /dev/net/tun 1609@end example 1610 1611D will be connecting to C, which has a tincd running for this network on 1612port 2000. It knows the port number from the host configuration file. 1613Also note that since D uses the tun/tap driver, the network interface 1614will not be called `tun' or `tap0' or something like that, but will 1615have the same name as netname. 1616 1617On all hosts, in @file{@value{sysconfdir}/tinc/company/hosts/BranchD}: 1618 1619@example 1620Subnet = 10.4.0.0/16 1621Address = 4.5.6.7 1622 1623-----BEGIN RSA PUBLIC KEY----- 1624... 1625-----END RSA PUBLIC KEY----- 1626@end example 1627 1628@subsubheading Key files 1629 1630A, B, C and D all have generated a public/private keypair with the following command: 1631 1632@example 1633tincd -n company -K 1634@end example 1635 1636The private key is stored in @file{@value{sysconfdir}/tinc/company/rsa_key.priv}, 1637the public key is put into the host configuration file in the @file{@value{sysconfdir}/tinc/company/hosts/} directory. 1638During key generation, tinc automatically guesses the right filenames based on the -n option and 1639the Name directive in the @file{tinc.conf} file (if it is available). 1640 1641@subsubheading Starting 1642 1643After each branch has finished configuration and they have distributed 1644the host configuration files amongst them, they can start their tinc daemons. 1645They don't necessarily have to wait for the other branches to have started 1646their daemons, tinc will try connecting until they are available. 1647 1648 1649@c ================================================================== 1650@node Running tinc 1651@chapter Running tinc 1652 1653If everything else is done, you can start tinc by typing the following command: 1654 1655@example 1656tincd -n @var{netname} 1657@end example 1658 1659@cindex daemon 1660Tinc will detach from the terminal and continue to run in the background like a good daemon. 1661If there are any problems however you can try to increase the debug level 1662and look in the syslog to find out what the problems are. 1663 1664@menu 1665* Runtime options:: 1666* Signals:: 1667* Debug levels:: 1668* Solving problems:: 1669* Error messages:: 1670* Sending bug reports:: 1671@end menu 1672 1673 1674@c ================================================================== 1675@node Runtime options 1676@section Runtime options 1677 1678Besides the settings in the configuration file, tinc also accepts some 1679command line options. 1680 1681@cindex command line 1682@cindex runtime options 1683@cindex options 1684@c from the manpage 1685@table @option 1686@item -c, --config=@var{path} 1687Read configuration options from the directory @var{path}. The default is 1688@file{@value{sysconfdir}/tinc/@var{netname}/}. 1689 1690@item -D, --no-detach 1691Don't fork and detach. 1692This will also disable the automatic restart mechanism for fatal errors. 1693 1694@cindex debug level 1695@item -d, --debug=@var{level} 1696Set debug level to @var{level}. The higher the debug level, the more gets 1697logged. Everything goes via syslog. 1698 1699@item -k, --kill[=@var{signal}] 1700Attempt to kill a running tincd (optionally with the specified @var{signal} instead of SIGTERM) and exit. 1701Use it in conjunction with the -n option to make sure you kill the right tinc daemon. 1702Under native Windows the optional argument is ignored, 1703the service will always be stopped and removed. 1704 1705@item -n, --net=@var{netname} 1706Use configuration for net @var{netname}. 1707This will let tinc read all configuration files from 1708@file{@value{sysconfdir}/tinc/@var{netname}/}. 1709Specifying . for @var{netname} is the same as not specifying any @var{netname}. 1710@xref{Multiple networks}. 1711 1712@item -K, --generate-keys[=@var{bits}] 1713Generate public/private keypair of @var{bits} length. If @var{bits} is not specified, 17142048 is the default. tinc will ask where you want to store the files, 1715but will default to the configuration directory (you can use the -c or -n option 1716in combination with -K). After that, tinc will quit. 1717 1718@item -o, --option=[@var{HOST}.]@var{KEY}=@var{VALUE} 1719Without specifying a @var{HOST}, this will set server configuration variable @var{KEY} to @var{VALUE}. 1720If specified as @var{HOST}.@var{KEY}=@var{VALUE}, 1721this will set the host configuration variable @var{KEY} of the host named @var{HOST} to @var{VALUE}. 1722This option can be used more than once to specify multiple configuration variables. 1723 1724@item -L, --mlock 1725Lock tinc into main memory. 1726This will prevent sensitive data like shared private keys to be written to the system swap files/partitions. 1727 1728@item --logfile[=@var{file}] 1729Write log entries to a file instead of to the system logging facility. 1730If @var{file} is omitted, the default is @file{@value{localstatedir}/log/tinc.@var{netname}.log}. 1731 1732@item --pidfile=@var{file} 1733Write PID to @var{file} instead of @file{@value{runstatedir}/tinc.@var{netname}.pid}. 1734 1735@item --bypass-security 1736Disables encryption and authentication. 1737Only useful for debugging. 1738 1739@item -R, --chroot 1740Change process root directory to the directory where the config file is 1741located (@file{@value{sysconfdir}/tinc/@var{netname}/} as determined by 1742-n/--net option or as given by -c/--config option), for added security. 1743The chroot is performed after all the initialization is done, after 1744writing pid files and opening network sockets. 1745 1746This option is best used in combination with the -U/--user option described below. 1747 1748You will need to ensure the chroot environment contains all the files necessary 1749for tinc to run correctly. 1750Most importantly, for tinc to be able to resolve hostnames inside the chroot environment, 1751you must copy @file{/etc/resolv.conf} into the chroot directory. 1752If you want to be able to run scripts other than @file{tinc-up} in the chroot, 1753you must ensure the appropriate shell is also installed in the chroot, along with all its dependencies. 1754 1755@item -U, --user=@var{user} 1756Switch to the given @var{user} after initialization, at the same time as 1757chroot is performed (see --chroot above). With this option tinc drops 1758privileges, for added security. 1759 1760@item --help 1761Display a short reminder of these runtime options and terminate. 1762 1763@item --version 1764Output version information and exit. 1765 1766@end table 1767 1768@c ================================================================== 1769@node Signals 1770@section Signals 1771 1772@cindex signals 1773You can also send the following signals to a running tincd process: 1774 1775@c from the manpage 1776@table @samp 1777 1778@item ALRM 1779Forces tinc to try to connect to all uplinks immediately. 1780Usually tinc attempts to do this itself, 1781but increases the time it waits between the attempts each time it failed, 1782and if tinc didn't succeed to connect to an uplink the first time after it started, 1783it defaults to the maximum time of 15 minutes. 1784 1785@item HUP 1786Partially rereads configuration files. 1787Connections to hosts whose host config file are removed are closed. 1788New outgoing connections specified in @file{tinc.conf} will be made. 1789If the --logfile option is used, this will also close and reopen the log file, 1790useful when log rotation is used. 1791 1792@item INT 1793Temporarily increases debug level to 5. 1794Send this signal again to revert to the original level. 1795 1796@item USR1 1797Dumps the connection list to syslog. 1798 1799@item USR2 1800Dumps virtual network device statistics, all known nodes, edges and subnets to syslog. 1801 1802@item WINCH 1803Purges all information remembered about unreachable nodes. 1804 1805@end table 1806 1807@c ================================================================== 1808@node Debug levels 1809@section Debug levels 1810 1811@cindex debug levels 1812The tinc daemon can send a lot of messages to the syslog. 1813The higher the debug level, the more messages it will log. 1814Each level inherits all messages of the previous level: 1815 1816@c from the manpage 1817@table @samp 1818 1819@item 0 1820This will log a message indicating tinc has started along with a version number. 1821It will also log any serious error. 1822 1823@item 1 1824This will log all connections that are made with other tinc daemons. 1825 1826@item 2 1827This will log status and error messages from scripts and other tinc daemons. 1828 1829@item 3 1830This will log all requests that are exchanged with other tinc daemons. These include 1831authentication, key exchange and connection list updates. 1832 1833@item 4 1834This will log a copy of everything received on the meta socket. 1835 1836@item 5 1837This will log all network traffic over the virtual private network. 1838 1839@end table 1840 1841@c ================================================================== 1842@node Solving problems 1843@section Solving problems 1844 1845If tinc starts without problems, but if the VPN doesn't work, you will have to find the cause of the problem. 1846The first thing to do is to start tinc with a high debug level in the foreground, 1847so you can directly see everything tinc logs: 1848 1849@example 1850tincd -n @var{netname} -d5 -D 1851@end example 1852 1853If tinc does not log any error messages, then you might want to check the following things: 1854 1855@itemize 1856@item @file{tinc-up} script 1857Does this script contain the right commands? 1858Normally 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. 1859 1860@item Subnet 1861Does the Subnet (or Subnets) in the host configuration file of this host match the portion of the VPN that belongs to this host? 1862 1863@item Firewalls and NATs 1864Do you have a firewall or a NAT device (a masquerading firewall or perhaps an ADSL router that performs masquerading)? 1865If so, check that it allows TCP and UDP traffic on port 655. 1866If 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. 1867You can add @samp{TCPOnly = yes} to your host config file to force tinc to only use a single TCP connection, 1868this works through most firewalls and NATs. Since version 1.0.10, tinc will automatically fall back to TCP if direct communication via UDP is not possible. 1869 1870@end itemize 1871 1872 1873@c ================================================================== 1874@node Error messages 1875@section Error messages 1876 1877What follows is a list of the most common error messages you might find in the logs. 1878Some of them will only be visible if the debug level is high enough. 1879 1880@table @samp 1881@item Could not open /dev/tap0: No such device 1882 1883@itemize 1884@item You forgot to `modprobe netlink_dev' or `modprobe ethertap'. 1885@item You forgot to compile `Netlink device emulation' in the kernel. 1886@end itemize 1887 1888@item Can't write to /dev/net/tun: No such device 1889 1890@itemize 1891@item You forgot to `modprobe tun'. 1892@item You forgot to compile `Universal TUN/TAP driver' in the kernel. 1893@item The tun device is located somewhere else in @file{/dev/}. 1894@end itemize 1895 1896@item Network address and prefix length do not match! 1897 1898@itemize 1899@item The Subnet field must contain a @emph{network} address, trailing bits should be 0. 1900@item If you only want to use one IP address, set the netmask to /32. 1901@end itemize 1902 1903@item Error reading RSA key file `rsa_key.priv': No such file or directory 1904 1905@itemize 1906@item You forgot to create a public/private keypair. 1907@item Specify the complete pathname to the private key file with the @samp{PrivateKeyFile} option. 1908@end itemize 1909 1910@item Warning: insecure file permissions for RSA private key file `rsa_key.priv'! 1911 1912@itemize 1913@item The private key file is readable by users other than root. 1914Use chmod to correct the file permissions. 1915@end itemize 1916 1917@item Creating metasocket failed: Address family not supported 1918 1919@itemize 1920@item By default tinc tries to create both IPv4 and IPv6 sockets. 1921On some platforms this might not be implemented. 1922If the logs show @samp{Ready} later on, then at least one metasocket was created, 1923and you can ignore this message. 1924You can add @samp{AddressFamily = ipv4} to @file{tinc.conf} to prevent this from happening. 1925@end itemize 1926 1927@item Cannot route packet: unknown IPv4 destination 1.2.3.4 1928 1929@itemize 1930@item You try to send traffic to a host on the VPN for which no Subnet is known. 1931@item If it is a broadcast address (ending in .255), it probably is a samba server or a Windows host sending broadcast packets. 1932You can ignore it. 1933@end itemize 1934 1935@item Cannot route packet: ARP request for unknown address 1.2.3.4 1936 1937@itemize 1938@item You try to send traffic to a host on the VPN for which no Subnet is known. 1939@end itemize 1940 1941@item Packet with destination 1.2.3.4 is looping back to us! 1942 1943@itemize 1944@item Something is not configured right. Packets are being sent out to the 1945virtual network device, but according to the Subnet directives in your host configuration 1946file, those packets should go to your own host. Most common mistake is that 1947you have a Subnet line in your host configuration file with a prefix length which is 1948just as large as the prefix of the virtual network interface. The latter should in almost all 1949cases be larger. Rethink your configuration. 1950Note that you will only see this message if you specified a debug 1951level of 5 or higher! 1952@item Chances are that a @samp{Subnet = ...} line in the host configuration file of this tinc daemon is wrong. 1953Change it to a subnet that is accepted locally by another interface, 1954or if that is not the case, try changing the prefix length into /32. 1955@end itemize 1956 1957@item Node foo (1.2.3.4) is not reachable 1958 1959@itemize 1960@item Node foo does not have a connection anymore, its tinc daemon is not running or its connection to the Internet is broken. 1961@end itemize 1962 1963@item Received UDP packet from unknown source 1.2.3.4 (port 12345) 1964 1965@itemize 1966@item If you see this only sporadically, it is harmless and caused by a node sending packets using an old key. 1967@end itemize 1968 1969@item Got bad/bogus/unauthorized REQUEST from foo (1.2.3.4 port 12345) 1970 1971@itemize 1972@item Node foo does not have the right public/private keypair. 1973Generate new keypairs and distribute them again. 1974@item An attacker tries to gain access to your VPN. 1975@item A network error caused corruption of metadata sent from foo. 1976@end itemize 1977 1978@end table 1979 1980@c ================================================================== 1981@node Sending bug reports 1982@section Sending bug reports 1983 1984If you really can't find the cause of a problem, or if you suspect tinc is not working right, 1985you can send us a bugreport, see @ref{Contact information}. 1986Be sure to include the following information in your bugreport: 1987 1988@itemize 1989@item A clear description of what you are trying to achieve and what the problem is. 1990@item What platform (operating system, version, hardware architecture) and which version of tinc you use. 1991@item If compiling tinc fails, a copy of @file{config.log} and the error messages you get. 1992@item Otherwise, a copy of @file{tinc.conf}, @file{tinc-up} and all files in the @file{hosts/} directory. 1993@item The output of the commands @samp{ifconfig -a} and @samp{route -n} (or @samp{netstat -rn} if that doesn't work). 1994@item The output of any command that fails to work as it should (like ping or traceroute). 1995@end itemize 1996 1997@c ================================================================== 1998@node Technical information 1999@chapter Technical information 2000 2001 2002@menu 2003* The connection:: 2004* The meta-protocol:: 2005* Security:: 2006@end menu 2007 2008 2009@c ================================================================== 2010@node The connection 2011@section The connection 2012 2013@cindex connection 2014Tinc is a daemon that takes VPN data and transmit that to another host 2015computer over the existing Internet infrastructure. 2016 2017@menu 2018* The UDP tunnel:: 2019* The meta-connection:: 2020@end menu 2021 2022 2023@c ================================================================== 2024@node The UDP tunnel 2025@subsection The UDP tunnel 2026 2027@cindex virtual network device 2028@cindex frame type 2029The data itself is read from a character device file, the so-called 2030@emph{virtual network device}. This device is associated with a network 2031interface. Any data sent to this interface can be read from the device, 2032and any data written to the device gets sent from the interface. 2033There are two possible types of virtual network devices: 2034`tun' style, which are point-to-point devices which can only handle IPv4 and/or IPv6 packets, 2035and `tap' style, which are Ethernet devices and handle complete Ethernet frames. 2036 2037So when tinc reads an Ethernet frame from the device, it determines its 2038type. When tinc is in its default routing mode, it can handle IPv4 and IPv6 2039packets. Depending on the Subnet lines, it will send the packets off to their destination IP address. 2040In the `switch' and `hub' mode, tinc will use broadcasts and MAC address discovery 2041to deduce the destination of the packets. 2042Since the latter modes only depend on the link layer information, 2043any protocol that runs over Ethernet is supported (for instance IPX and Appletalk). 2044However, only `tap' style devices provide this information. 2045 2046After the destination has been determined, 2047the packet will be compressed (optionally), 2048a sequence number will be added to the packet, 2049the packet will then be encrypted 2050and a message authentication code will be appended. 2051 2052@cindex encapsulating 2053@cindex UDP 2054When that is done, time has come to actually transport the 2055packet to the destination computer. We do this by sending the packet 2056over an UDP connection to the destination host. This is called 2057@emph{encapsulating}, the VPN packet (though now encrypted) is 2058encapsulated in another IP datagram. 2059 2060When the destination receives this packet, the same thing happens, only 2061in reverse. So it checks the message authentication code, decrypts the contents of the UDP datagram, 2062checks the sequence number 2063and writes the decrypted information to its own virtual network device. 2064 2065If the virtual network device is a `tun' device (a point-to-point tunnel), 2066there is no problem for the kernel to accept a packet. 2067However, if it is a `tap' device (this is the only available type on FreeBSD), 2068the destination MAC address must match that of the virtual network interface. 2069If tinc is in its default routing mode, ARP does not work, so the correct destination MAC 2070can not be known by the sending host. 2071Tinc solves this by letting the receiving end detect the MAC address of its own virtual network interface 2072and overwriting the destination MAC address of the received packet. 2073 2074In switch or hub modes ARP does work so the sender already knows the correct destination MAC address. 2075In those modes every interface should have a unique MAC address, so make sure they are not the same. 2076Because switch and hub modes rely on MAC addresses to function correctly, 2077these modes cannot be used on the following operating systems which don't have a `tap' style virtual network device: 2078NetBSD, Darwin and Solaris. 2079 2080 2081@c ================================================================== 2082@node The meta-connection 2083@subsection The meta-connection 2084 2085Having only a UDP connection available is not enough. Though suitable 2086for transmitting data, we want to be able to reliably send other 2087information, such as routing and session key information to somebody. 2088 2089@cindex TCP 2090TCP is a better alternative, because it already contains protection 2091against information being lost, unlike UDP. 2092 2093So we establish two connections. One for the encrypted VPN data, and one 2094for other information, the meta-data. Hence, we call the second 2095connection the meta-connection. We can now be sure that the 2096meta-information doesn't get lost on the way to another computer. 2097 2098@cindex data-protocol 2099@cindex meta-protocol 2100Like with any communication, we must have a protocol, so that everybody 2101knows what everything stands for, and how she should react. Because we 2102have two connections, we also have two protocols. The protocol used for 2103the UDP data is the ``data-protocol,'' the other one is the 2104``meta-protocol.'' 2105 2106The reason we don't use TCP for both protocols is that UDP is much 2107better for encapsulation, even while it is less reliable. The real 2108problem is that when TCP would be used to encapsulate a TCP stream 2109that's on the private network, for every packet sent there would be 2110three ACKs sent instead of just one. Furthermore, if there would be 2111a timeout, both TCP streams would sense the timeout, and both would 2112start re-sending packets. 2113 2114 2115@c ================================================================== 2116@node The meta-protocol 2117@section The meta-protocol 2118 2119The meta protocol is used to tie all tinc daemons together, and 2120exchange information about which tinc daemon serves which virtual 2121subnet. 2122 2123The meta protocol consists of requests that can be sent to the other 2124side. Each request has a unique number and several parameters. All 2125requests are represented in the standard ASCII character set. It is 2126possible to use tools such as telnet or netcat to connect to a tinc 2127daemon started with the --bypass-security option 2128and to read and write requests by hand, provided that one 2129understands the numeric codes sent. 2130 2131The authentication scheme is described in @ref{Authentication protocol}. After a 2132successful authentication, the server and the client will exchange all the 2133information about other tinc daemons and subnets they know of, so that both 2134sides (and all the other tinc daemons behind them) have their information 2135synchronised. 2136 2137@cindex ADD_EDGE 2138@cindex ADD_SUBNET 2139@example 2140message 2141------------------------------------------------------------------ 2142ADD_EDGE node1 node2 21.32.43.54 655 222 0 2143 | | | | | +-> options 2144 | | | | +----> weight 2145 | | | +--------> UDP port of node2 2146 | | +----------------> real address of node2 2147 | +-------------------------> name of destination node 2148 +-------------------------------> name of source node 2149 2150ADD_SUBNET node 192.168.1.0/24 2151 | | +--> prefixlength 2152 | +--------> network address 2153 +------------------> owner of this subnet 2154------------------------------------------------------------------ 2155@end example 2156 2157The ADD_EDGE messages are to inform other tinc daemons that a connection between 2158two nodes exist. The address of the destination node is available so that 2159VPN packets can be sent directly to that node. 2160 2161The ADD_SUBNET messages inform other tinc daemons that certain subnets belong 2162to certain nodes. tinc will use it to determine to which node a VPN packet has 2163to be sent. 2164 2165@cindex DEL_EDGE 2166@cindex DEL_SUBNET 2167@example 2168message 2169------------------------------------------------------------------ 2170DEL_EDGE node1 node2 2171 | +----> name of destination node 2172 +----------> name of source node 2173 2174DEL_SUBNET node 192.168.1.0/24 2175 | | +--> prefixlength 2176 | +--------> network address 2177 +------------------> owner of this subnet 2178------------------------------------------------------------------ 2179@end example 2180 2181In case a connection between two daemons is closed or broken, DEL_EDGE messages 2182are sent to inform the other daemons of that fact. Each daemon will calculate a 2183new route to the the daemons, or mark them unreachable if there isn't any. 2184 2185@cindex REQ_KEY 2186@cindex ANS_KEY 2187@cindex KEY_CHANGED 2188@example 2189message 2190------------------------------------------------------------------ 2191REQ_KEY origin destination 2192 | +--> name of the tinc daemon it wants the key from 2193 +----------> name of the daemon that wants the key 2194 2195ANS_KEY origin destination 4ae0b0a82d6e0078 91 64 4 2196 | | \______________/ | | +--> MAC length 2197 | | | | +-----> digest algorithm 2198 | | | +--------> cipher algorithm 2199 | | +--> 128 bits key 2200 | +--> name of the daemon that wants the key 2201 +----------> name of the daemon that uses this key 2202 2203KEY_CHANGED origin 2204 +--> daemon that has changed it's packet key 2205------------------------------------------------------------------ 2206@end example 2207 2208The keys used to encrypt VPN packets are not sent out directly. This is 2209because it would generate a lot of traffic on VPNs with many daemons, and 2210chances are that not every tinc daemon will ever send a packet to every 2211other daemon. Instead, if a daemon needs a key it sends a request for it 2212via the meta connection of the nearest hop in the direction of the 2213destination. 2214 2215@cindex PING 2216@cindex PONG 2217@example 2218daemon message 2219------------------------------------------------------------------ 2220origin PING 2221dest. PONG 2222------------------------------------------------------------------ 2223@end example 2224 2225There is also a mechanism to check if hosts are still alive. Since network 2226failures or a crash can cause a daemon to be killed without properly 2227shutting down the TCP connection, this is necessary to keep an up to date 2228connection list. PINGs are sent at regular intervals, except when there 2229is also some other traffic. A little bit of salt (random data) is added 2230with each PING and PONG message, to make sure that long sequences of PING/PONG 2231messages without any other traffic won't result in known plaintext. 2232 2233This basically covers what is sent over the meta connection by tinc. 2234 2235 2236@c ================================================================== 2237@node Security 2238@section Security 2239 2240@cindex TINC 2241@cindex Cabal 2242Tinc got its name from ``TINC,'' short for @emph{There Is No Cabal}; the 2243alleged Cabal was/is an organisation that was said to keep an eye on the 2244entire Internet. As this is exactly what you @emph{don't} want, we named 2245the tinc project after TINC. 2246 2247@cindex SVPN 2248But in order to be ``immune'' to eavesdropping, you'll have to encrypt 2249your data. Because tinc is a @emph{Secure} VPN (SVPN) daemon, it does 2250exactly that: encrypt. 2251Tinc by default uses blowfish encryption with 128 bit keys in CBC mode, 32 bit 2252sequence numbers and 4 byte long message authentication codes to make sure 2253eavesdroppers cannot get and cannot change any information at all from the 2254packets they can intercept. The encryption algorithm and message authentication 2255algorithm can be changed in the configuration. The length of the message 2256authentication codes is also adjustable. The length of the key for the 2257encryption algorithm is always the default length used by LibreSSL/OpenSSL. 2258 2259@menu 2260* Authentication protocol:: 2261* Encryption of network packets:: 2262* Security issues:: 2263@end menu 2264 2265 2266@c ================================================================== 2267@node Authentication protocol 2268@subsection Authentication protocol 2269 2270@cindex authentication 2271A new scheme for authentication in tinc has been devised, which offers some 2272improvements over the protocol used in 1.0pre2 and 1.0pre3. Explanation is 2273below. 2274 2275@cindex ID 2276@cindex META_KEY 2277@cindex CHALLENGE 2278@cindex CHAL_REPLY 2279@cindex ACK 2280@example 2281daemon message 2282-------------------------------------------------------------------------- 2283client <attempts connection> 2284 2285server <accepts connection> 2286 2287client ID client 12 2288 | +---> version 2289 +-------> name of tinc daemon 2290 2291server ID server 12 2292 | +---> version 2293 +-------> name of tinc daemon 2294 2295client META_KEY 5f0823a93e35b69e...7086ec7866ce582b 2296 \_________________________________/ 2297 +-> RSAKEYLEN bits totally random string S1, 2298 encrypted with server's public RSA key 2299 2300server META_KEY 6ab9c1640388f8f0...45d1a07f8a672630 2301 \_________________________________/ 2302 +-> RSAKEYLEN bits totally random string S2, 2303 encrypted with client's public RSA key 2304 2305From now on: 2306 - the client will symmetrically encrypt outgoing traffic using S1 2307 - the server will symmetrically encrypt outgoing traffic using S2 2308 2309client CHALLENGE da02add1817c1920989ba6ae2a49cecbda0 2310 \_________________________________/ 2311 +-> CHALLEN bits totally random string H1 2312 2313server CHALLENGE 57fb4b2ccd70d6bb35a64c142f47e61d57f 2314 \_________________________________/ 2315 +-> CHALLEN bits totally random string H2 2316 2317client CHAL_REPLY 816a86 2318 +-> 160 bits SHA1 of H2 2319 2320server CHAL_REPLY 928ffe 2321 +-> 160 bits SHA1 of H1 2322 2323After the correct challenge replies are received, both ends have proved 2324their identity. Further information is exchanged. 2325 2326client ACK 655 123 0 2327 | | +-> options 2328 | +----> estimated weight 2329 +--------> listening port of client 2330 2331server ACK 655 321 0 2332 | | +-> options 2333 | +----> estimated weight 2334 +--------> listening port of server 2335-------------------------------------------------------------------------- 2336@end example 2337 2338This new scheme has several improvements, both in efficiency and security. 2339 2340First of all, the server sends exactly the same kind of messages over the wire 2341as the client. The previous versions of tinc first authenticated the client, 2342and then the server. This scheme even allows both sides to send their messages 2343simultaneously, there is no need to wait for the other to send something first. 2344This means that any calculations that need to be done upon sending or receiving 2345a message can also be done in parallel. This is especially important when doing 2346RSA encryption/decryption. Given that these calculations are the main part of 2347the CPU time spent for the authentication, speed is improved by a factor 2. 2348 2349Second, only one RSA encrypted message is sent instead of two. This reduces the 2350amount of information attackers can see (and thus use for a cryptographic 2351attack). It also improves speed by a factor two, making the total speedup a 2352factor 4. 2353 2354Third, and most important: 2355The symmetric cipher keys are exchanged first, the challenge is done 2356afterwards. In the previous authentication scheme, because a man-in-the-middle 2357could pass the challenge/chal_reply phase (by just copying the messages between 2358the two real tinc daemons), but no information was exchanged that was really 2359needed to read the rest of the messages, the challenge/chal_reply phase was of 2360no real use. The man-in-the-middle was only stopped by the fact that only after 2361the ACK messages were encrypted with the symmetric cipher. Potentially, it 2362could even send it's own symmetric key to the server (if it knew the server's 2363public key) and read some of the metadata the server would send it (it was 2364impossible for the mitm to read actual network packets though). The new scheme 2365however prevents this. 2366 2367This new scheme makes sure that first of all, symmetric keys are exchanged. The 2368rest of the messages are then encrypted with the symmetric cipher. Then, each 2369side can only read received messages if they have their private key. The 2370challenge is there to let the other side know that the private key is really 2371known, because a challenge reply can only be sent back if the challenge is 2372decrypted correctly, and that can only be done with knowledge of the private 2373key. 2374 2375Fourth: the first thing that is sent via the symmetric cipher encrypted 2376connection is a totally random string, so that there is no known plaintext (for 2377an attacker) in the beginning of the encrypted stream. 2378 2379 2380@c ================================================================== 2381@node Encryption of network packets 2382@subsection Encryption of network packets 2383@cindex encryption 2384 2385A data packet can only be sent if the encryption key is known to both 2386parties, and the connection is activated. If the encryption key is not 2387known, a request is sent to the destination using the meta connection 2388to retrieve it. The packet is stored in a queue while waiting for the 2389key to arrive. 2390 2391@cindex UDP 2392The UDP packet containing the network packet from the VPN has the following layout: 2393 2394@example 2395... | IP header | UDP header | seqno | VPN packet | MAC | UDP trailer 2396 \___________________/\_____/ 2397 | | 2398 V +---> digest algorithm 2399 Encrypted with symmetric cipher 2400@end example 2401 2402So, the entire VPN packet is encrypted using a symmetric cipher, including a 32 bits 2403sequence number that is added in front of the actual VPN packet, to act as a unique 2404IV for each packet and to prevent replay attacks. A message authentication code 2405is added to the UDP packet to prevent alteration of packets. By default the 2406first 4 bytes of the digest are used for this, but this can be changed using 2407the MACLength configuration variable. 2408 2409@c ================================================================== 2410@node Security issues 2411@subsection Security issues 2412 2413In August 2000, we discovered the existence of a security hole in all versions 2414of tinc up to and including 1.0pre2. This had to do with the way we exchanged 2415keys. Since then, we have been working on a new authentication scheme to make 2416tinc as secure as possible. The current version uses the LibreSSL or OpenSSL library and 2417uses strong authentication with RSA keys. 2418 2419On the 29th of December 2001, Jerome Etienne posted a security analysis of tinc 24201.0pre4. Due to a lack of sequence numbers and a message authentication code 2421for each packet, an attacker could possibly disrupt certain network services or 2422launch a denial of service attack by replaying intercepted packets. The current 2423version adds sequence numbers and message authentication codes to prevent such 2424attacks. 2425 2426On the 15th of September 2003, Peter Gutmann posted a security analysis of tinc 24271.0.1. He argues that the 32 bit sequence number used by tinc is not a good IV, 2428that tinc's default length of 4 bytes for the MAC is too short, and he doesn't 2429like tinc's use of RSA during authentication. We do not know of a security hole 2430in this version of tinc, but tinc's security is not as strong as TLS or IPsec. 2431We will address these issues in tinc 2.0. 2432 2433Cryptography is a hard thing to get right. We cannot make any 2434guarantees. Time, review and feedback are the only things that can 2435prove the security of any cryptographic product. If you wish to review 2436tinc or give us feedback, you are strongly encouraged to do so. 2437 2438 2439@c ================================================================== 2440@node Platform specific information 2441@chapter Platform specific information 2442 2443@menu 2444* Interface configuration:: 2445* Routes:: 2446* Automatically starting tinc:: 2447@end menu 2448 2449@c ================================================================== 2450@node Interface configuration 2451@section Interface configuration 2452 2453When configuring an interface, one normally assigns it an address and a 2454netmask. The address uniquely identifies the host on the network attached to 2455the interface. The netmask, combined with the address, forms a subnet. It is 2456used to add a route to the routing table instructing the kernel to send all 2457packets which fall into that subnet to that interface. Because all packets for 2458the entire VPN should go to the virtual network interface used by tinc, the 2459netmask should be such that it encompasses the entire VPN. 2460 2461For IPv4 addresses: 2462 2463@multitable {Darwin (Mac OS X)} {ifconfig route add -bla network address netmask netmask prefixlength interface} 2464@item Linux 2465@tab @code{ifconfig} @var{interface} @var{address} @code{netmask} @var{netmask} 2466@item Linux iproute2 2467@tab @code{ip addr add} @var{address}@code{/}@var{prefixlength} @code{dev} @var{interface} 2468@item FreeBSD 2469@tab @code{ifconfig} @var{interface} @var{address} @code{netmask} @var{netmask} 2470@item OpenBSD 2471@tab @code{ifconfig} @var{interface} @var{address} @code{netmask} @var{netmask} 2472@item NetBSD 2473@tab @code{ifconfig} @var{interface} @var{address} @code{netmask} @var{netmask} 2474@item Solaris 2475@tab @code{ifconfig} @var{interface} @var{address} @code{netmask} @var{netmask} 2476@item Darwin (Mac OS X) 2477@tab @code{ifconfig} @var{interface} @var{address} @code{netmask} @var{netmask} 2478@item Windows 2479@tab @code{netsh interface ip set address} @var{interface} @code{static} @var{address} @var{netmask} 2480@end multitable 2481 2482For IPv6 addresses: 2483 2484@multitable {Darwin (Mac OS X)} {ifconfig route add -bla network address netmask netmask prefixlength interface} 2485@item Linux 2486@tab @code{ifconfig} @var{interface} @code{add} @var{address}@code{/}@var{prefixlength} 2487@item FreeBSD 2488@tab @code{ifconfig} @var{interface} @code{inet6} @var{address} @code{prefixlen} @var{prefixlength} 2489@item OpenBSD 2490@tab @code{ifconfig} @var{interface} @code{inet6} @var{address} @code{prefixlen} @var{prefixlength} 2491@item NetBSD 2492@tab @code{ifconfig} @var{interface} @code{inet6} @var{address} @code{prefixlen} @var{prefixlength} 2493@item Solaris 2494@tab @code{ifconfig} @var{interface} @code{inet6 plumb up} 2495@item 2496@tab @code{ifconfig} @var{interface} @code{inet6 addif} @var{address} @var{address} 2497@item Darwin (Mac OS X) 2498@tab @code{ifconfig} @var{interface} @code{inet6} @var{address} @code{prefixlen} @var{prefixlength} 2499@item Windows 2500@tab @code{netsh interface ipv6 add address} @var{interface} @code{static} @var{address}/@var{prefixlength} 2501@end multitable 2502 2503On Linux, it is possible to create a persistent tun/tap interface which will 2504continue to exist even if tinc quit, although this is normally not required. 2505It can be useful to set up a tun/tap interface owned by a non-root user, so 2506tinc can be started without needing any root privileges at all. 2507 2508@multitable {Darwin (Mac OS X)} {ifconfig route add -bla network address netmask netmask prefixlength interface} 2509@item Linux 2510@tab @code{ip tuntap add dev} @var{interface} @code{mode} @var{tun|tap} @code{user} @var{username} 2511@end multitable 2512 2513@c ================================================================== 2514@node Routes 2515@section Routes 2516 2517In some cases it might be necessary to add more routes to the virtual network 2518interface. There are two ways to indicate which interface a packet should go 2519to, one is to use the name of the interface itself, another way is to specify 2520the (local) address that is assigned to that interface (@var{local_address}). The 2521former way is unambiguous and therefore preferable, but not all platforms 2522support this. 2523 2524Adding routes to IPv4 subnets: 2525 2526@multitable {Darwin (Mac OS X)} {ifconfig route add -bla network address netmask netmask prefixlength interface} 2527@item Linux 2528@tab @code{route add -net} @var{network_address} @code{netmask} @var{netmask} @var{interface} 2529@item Linux iproute2 2530@tab @code{ip route add} @var{network_address}@code{/}@var{prefixlength} @code{dev} @var{interface} 2531@item FreeBSD 2532@tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @var{local_address} 2533@item OpenBSD 2534@tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @var{local_address} 2535@item NetBSD 2536@tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @var{local_address} 2537@item Solaris 2538@tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @var{local_address} @code{-interface} 2539@item Darwin (Mac OS X) 2540@tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @code{-interface} @var{interface} 2541@item Windows 2542@tab @code{netsh routing ip add persistentroute} @var{network_address} @var{netmask} @var{interface} @var{local_address} 2543@end multitable 2544 2545Adding routes to IPv6 subnets: 2546 2547@multitable {Darwin (Mac OS X)} {ifconfig route add -bla network address netmask netmask prefixlength interface} 2548@item Linux 2549@tab @code{route add -A inet6} @var{network_address}@code{/}@var{prefixlength} @var{interface} 2550@item Linux iproute2 2551@tab @code{ip route add} @var{network_address}@code{/}@var{prefixlength} @code{dev} @var{interface} 2552@item FreeBSD 2553@tab @code{route add -inet6} @var{network_address}@code{/}@var{prefixlength} @var{local_address} 2554@item OpenBSD 2555@tab @code{route add -inet6} @var{network_address} @var{local_address} @code{-prefixlen} @var{prefixlength} 2556@item NetBSD 2557@tab @code{route add -inet6} @var{network_address} @var{local_address} @code{-prefixlen} @var{prefixlength} 2558@item Solaris 2559@tab @code{route add -inet6} @var{network_address}@code{/}@var{prefixlength} @var{local_address} @code{-interface} 2560@item Darwin (Mac OS X) 2561@tab @code{route add -inet6} @var{network_address}@code{/}@var{prefixlength} @code{-interface} @var{interface} 2562@item Windows 2563@tab @code{netsh interface ipv6 add route} @var{network address}/@var{prefixlength} @var{interface} 2564@end multitable 2565 2566@c ================================================================== 2567@node Automatically starting tinc 2568@section Automatically starting tinc 2569 2570@menu 2571* Linux:: 2572* Windows:: 2573* Other platforms:: 2574@end menu 2575 2576@c ================================================================== 2577@node Linux 2578@subsection Linux 2579 2580@cindex systemd 2581There are many Linux distributions, and historically, many of them had their 2582own way of starting programs at boot time. Today, a number of major Linux 2583distributions have chosen to use systemd as their init system. Tinc ships with 2584systemd service files that allow you to start and stop tinc using systemd. 2585There are two service files: @code{tinc.service} is used to globally enable or 2586disable all tinc daemons managed by systemd, and 2587@code{tinc@@@var{netname}.service} is used to enable or disable specific tinc 2588daemons. So if one has created a tinc network with netname @code{foo}, then 2589you have to run the following two commands to ensure it is started at boot 2590time: 2591 2592@example 2593systemctl enable tinc 2594systemctl enable tinc@@foo 2595@end example 2596 2597To start the tinc daemon immediately if it wasn't already running, use the 2598following command: 2599 2600@example 2601systemctl start tinc@@foo 2602@end example 2603 2604You can also use @samp{systemctl start tinc}, this will start all tinc daemons 2605that are enabled. You can stop and disable tinc networks in the same way. 2606 2607If your system is not using systemd, then you have to look up your 2608distribution's way of starting tinc at boot time. 2609 2610@c ================================================================== 2611@node Windows 2612@subsection Windows 2613 2614On Windows, if tinc is started without the @code{-D} or @code{--no-detach} 2615option, it will automatically register itself as a service that is started at 2616boot time. When tinc is stopped using the @code{-k} or @code{--kill}, it will 2617also automatically unregister itself. Once tinc is registered as a service, it 2618is also possible to stop and start tinc using the Windows Services Manager. 2619 2620@c ================================================================== 2621@node Other platforms 2622@subsection Other platforms 2623 2624On platforms other than the ones mentioned in the earlier sections, you have to 2625look up your platform's way of starting programs at boot time. 2626 2627@c ================================================================== 2628@node About us 2629@chapter About us 2630 2631 2632@menu 2633* Contact information:: 2634* Authors:: 2635@end menu 2636 2637 2638@c ================================================================== 2639@node Contact information 2640@section Contact information 2641 2642@cindex website 2643Tinc's website is at @url{https://www.tinc-vpn.org/}, 2644this server is located in the Netherlands. 2645 2646@cindex IRC 2647We have an IRC channel on the FreeNode and OFTC IRC networks. Connect to 2648@uref{https://freenode.net/, irc.freenode.net} 2649or 2650@uref{https://www.oftc.net/, irc.oftc.net} 2651and join channel #tinc. 2652 2653 2654@c ================================================================== 2655@node Authors 2656@section Authors 2657 2658@table @asis 2659@item Ivo Timmermans (zarq) 2660@item Guus Sliepen (guus) (@email{guus@@tinc-vpn.org}) 2661@end table 2662 2663We have received a lot of valuable input from users. With their help, 2664tinc has become the flexible and robust tool that it is today. We have 2665composed a list of contributions, in the file called @file{THANKS} in 2666the source distribution. 2667 2668 2669@c ================================================================== 2670@node Concept Index 2671@unnumbered Concept Index 2672 2673@c ================================================================== 2674@printindex cp 2675 2676 2677@c ================================================================== 2678@contents 2679@bye 2680