1This is tinc.info, produced by makeinfo version 6.7 from tinc.texi. 2 3INFO-DIR-SECTION Networking tools 4START-INFO-DIR-ENTRY 5* tinc: (tinc). The tinc Manual. 6END-INFO-DIR-ENTRY 7 8This is the info manual for tinc version 1.1pre17-49-g4cc4b9bc, a 9Virtual Private Network daemon. 10 11 Copyright (C) 1998-2021 Ivo Timmermans, Guus Sliepen 12<guus@tinc-vpn.org> and Wessel Dankers <wsl@tinc-vpn.org>. 13 14 Permission is granted to make and distribute verbatim copies of this 15manual provided the copyright notice and this permission notice are 16preserved on all copies. 17 18 Permission is granted to copy and distribute modified versions of 19this manual under the conditions for verbatim copying, provided that the 20entire resulting derived work is distributed under the terms of a 21permission notice identical to this one. 22 23 24File: tinc.info, Node: Top, Next: Introduction, Up: (dir) 25 26Top 27*** 28 29* Menu: 30 31* Introduction:: 32* Preparations:: 33* Installation:: 34* Configuration:: 35* Running tinc:: 36* Controlling tinc:: 37* Invitations:: 38* Technical information:: 39* Platform specific information:: 40* About us:: 41* Concept Index:: All used terms explained 42 43 44File: tinc.info, Node: Introduction, Next: Preparations, Prev: Top, Up: Top 45 461 Introduction 47************** 48 49Tinc is a Virtual Private Network (VPN) daemon that uses tunneling and 50encryption to create a secure private network between hosts on the 51Internet. 52 53Because the tunnel appears to the IP level network code as a normal 54network device, there is no need to adapt any existing software. The 55encrypted tunnels allows VPN sites to share information with each other 56over the Internet without exposing any information to others. 57 58This document is the manual for tinc. Included are chapters on how to 59configure your computer to use tinc, as well as the configuration 60process of tinc itself. 61 62* Menu: 63 64* Virtual Private Networks:: 65* tinc:: About tinc 66* Supported platforms:: 67 68 69File: tinc.info, Node: Virtual Private Networks, Next: tinc, Up: Introduction 70 711.1 Virtual Private Networks 72============================ 73 74A Virtual Private Network or VPN is a network that can only be accessed 75by a few elected computers that participate. This goal is achievable in 76more than just one way. 77 78Private networks can consist of a single stand-alone Ethernet LAN. Or 79even two computers hooked up using a null-modem cable. In these cases, 80it is obvious that the network is _private_, no one can access it from 81the outside. But if your computers are linked to the Internet, the 82network is not private anymore, unless one uses firewalls to block all 83private traffic. But then, there is no way to send private data to 84trusted computers on the other end of the Internet. 85 86This problem can be solved by using _virtual_ networks. Virtual 87networks can live on top of other networks, but they use encapsulation 88to keep using their private address space so they do not interfere with 89the Internet. Mostly, virtual networks appear like a single LAN, even 90though they can span the entire world. But virtual networks can't be 91secured by using firewalls, because the traffic that flows through it 92has to go through the Internet, where other people can look at it. 93 94As is the case with either type of VPN, anybody could eavesdrop. Or 95worse, alter data. Hence it's probably advisable to encrypt the data 96that flows over the network. 97 98When one introduces encryption, we can form a true VPN. Other people may 99see encrypted traffic, but if they don't know how to decipher it (they 100need to know the key for that), they cannot read the information that 101flows through the VPN. This is what tinc was made for. 102 103 104File: tinc.info, Node: tinc, Next: Supported platforms, Prev: Virtual Private Networks, Up: Introduction 105 1061.2 tinc 107======== 108 109I really don't quite remember what got us started, but it must have been 110Guus' idea. He wrote a simple implementation (about 50 lines of C) that 111used the ethertap device that Linux knows of since somewhere about 112kernel 2.1.60. It didn't work immediately and he improved it a bit. At 113this stage, the project was still simply called "vpnd". 114 115Since then, a lot has changed--to say the least. 116 117Tinc now supports encryption, it consists of a single daemon (tincd) for 118both the receiving and sending end, it has become largely 119runtime-configurable--in short, it has become a full-fledged 120professional package. 121 122Tinc also allows more than two sites to connect to each other and form a 123single VPN. Traditionally VPNs are created by making tunnels, which only 124have two endpoints. Larger VPNs with more sites are created by adding 125more tunnels. Tinc takes another approach: only endpoints are 126specified, the software itself will take care of creating the tunnels. 127This allows for easier configuration and improved scalability. 128 129A lot can--and will be--changed. We have a number of things that we 130would like to see in the future releases of tinc. Not everything will 131be available in the near future. Our first objective is to make tinc 132work perfectly as it stands, and then add more advanced features. 133 134Meanwhile, we're always open-minded towards new ideas. And we're 135available too. 136 137 138File: tinc.info, Node: Supported platforms, Prev: tinc, Up: Introduction 139 1401.3 Supported platforms 141======================= 142 143Tinc has been verified to work under Linux, FreeBSD, OpenBSD, NetBSD, 144MacOS/X (Darwin), Solaris, and Windows, with various hardware 145architectures. These are some of the platforms that are supported by 146the universal tun/tap device driver or other virtual network device 147drivers. Without such a driver, tinc will most likely compile and run, 148but it will not be able to send or receive data packets. 149 150For an up to date list of supported platforms, please check the list on 151our website: <https://www.tinc-vpn.org/platforms/>. 152 153 154File: tinc.info, Node: Preparations, Next: Installation, Prev: Introduction, Up: Top 155 1562 Preparations 157************** 158 159This chapter contains information on how to prepare your system to 160support tinc. 161 162* Menu: 163 164* Configuring the kernel:: 165* Libraries:: 166 167 168File: tinc.info, Node: Configuring the kernel, Next: Libraries, Up: Preparations 169 1702.1 Configuring the kernel 171========================== 172 173* Menu: 174 175* Configuration of Linux kernels:: 176* Configuration of FreeBSD kernels:: 177* Configuration of OpenBSD kernels:: 178* Configuration of NetBSD kernels:: 179* Configuration of Solaris kernels:: 180* Configuration of Darwin (MacOS/X) kernels:: 181* Configuration of Windows:: 182 183 184File: tinc.info, Node: Configuration of Linux kernels, Next: Configuration of FreeBSD kernels, Up: Configuring the kernel 185 1862.1.1 Configuration of Linux kernels 187------------------------------------ 188 189For tinc to work, you need a kernel that supports the Universal tun/tap 190device. Most distributions come with kernels that already support this. 191Here are the options you have to turn on when configuring a new kernel: 192 193 Code maturity level options 194 [*] Prompt for development and/or incomplete code/drivers 195 Network device support 196 <M> Universal tun/tap device driver support 197 198It's not necessary to compile this driver as a module, even if you are 199going to run more than one instance of tinc. 200 201If you decide to build the tun/tap driver as a kernel module, add these 202lines to '/etc/modules.conf': 203 204 alias char-major-10-200 tun 205 206 207File: tinc.info, Node: Configuration of FreeBSD kernels, Next: Configuration of OpenBSD kernels, Prev: Configuration of Linux kernels, Up: Configuring the kernel 208 2092.1.2 Configuration of FreeBSD kernels 210-------------------------------------- 211 212For FreeBSD version 4.1 and higher, tun and tap drivers are included in 213the default kernel configuration. The tap driver can be loaded with 214'kldload if_tap', or by adding 'if_tap_load="YES"' to 215'/boot/loader.conf'. 216 217 218File: tinc.info, Node: Configuration of OpenBSD kernels, Next: Configuration of NetBSD kernels, Prev: Configuration of FreeBSD kernels, Up: Configuring the kernel 219 2202.1.3 Configuration of OpenBSD kernels 221-------------------------------------- 222 223Recent versions of OpenBSD come with both tun and tap devices enabled in 224the default kernel configuration. 225 226 227File: tinc.info, Node: Configuration of NetBSD kernels, Next: Configuration of Solaris kernels, Prev: Configuration of OpenBSD kernels, Up: Configuring the kernel 228 2292.1.4 Configuration of NetBSD kernels 230------------------------------------- 231 232For NetBSD version 1.5.2 and higher, the tun driver is included in the 233default kernel configuration. 234 235Tunneling IPv6 may not work on NetBSD's tun device. 236 237 238File: tinc.info, Node: Configuration of Solaris kernels, Next: Configuration of Darwin (MacOS/X) kernels, Prev: Configuration of NetBSD kernels, Up: Configuring the kernel 239 2402.1.5 Configuration of Solaris kernels 241-------------------------------------- 242 243For Solaris 8 (SunOS 5.8) and higher, the tun driver may or may not be 244included in the default kernel configuration. If it isn't, the source 245can be downloaded from <http://vtun.sourceforge.net/tun/>. For x86 and 246sparc64 architectures, precompiled versions can be found at 247<https://www.monkey.org/~dugsong/fragroute/>. If the 'net/if_tun.h' 248header file is missing, install it from the source package. 249 250 251File: tinc.info, Node: Configuration of Darwin (MacOS/X) kernels, Next: Configuration of Windows, Prev: Configuration of Solaris kernels, Up: Configuring the kernel 252 2532.1.6 Configuration of Darwin (MacOS/X) kernels 254----------------------------------------------- 255 256Tinc on Darwin relies on a tunnel driver for its data acquisition from 257the kernel. OS X version 10.6.8 and later have a built-in tun driver 258called "utun". Tinc also supports the driver from 259<http://tuntaposx.sourceforge.net/>, which supports both tun and tap 260style devices, 261 262By default, tinc expects the tuntaposx driver to be installed. To use 263the utun driver, set add 'Device = utunX' to 'tinc.conf', where X is the 264desired number for the utun interface. You can also omit the number, in 265which case the first free number will be chosen. 266 267 268File: tinc.info, Node: Configuration of Windows, Prev: Configuration of Darwin (MacOS/X) kernels, Up: Configuring the kernel 269 2702.1.7 Configuration of Windows 271------------------------------ 272 273You will need to install the latest TAP-Win32 driver from OpenVPN. You 274can download it from 275<https://openvpn.net/index.php/open-source/downloads.html>. Using the 276Network Connections control panel, configure the TAP-Win32 network 277interface in the same way as you would do from the tinc-up script, as 278explained in the rest of the documentation. 279 280 281File: tinc.info, Node: Libraries, Prev: Configuring the kernel, Up: Preparations 282 2832.2 Libraries 284============= 285 286Before you can configure or build tinc, you need to have the LibreSSL or 287OpenSSL, zlib, LZO, curses and readline libraries installed on your 288system. If you try to configure tinc without having them installed, 289configure will give you an error message, and stop. 290 291* Menu: 292 293* LibreSSL/OpenSSL:: 294* zlib:: 295* LZO:: 296* libcurses:: 297* libreadline:: 298 299 300File: tinc.info, Node: LibreSSL/OpenSSL, Next: zlib, Up: Libraries 301 3022.2.1 LibreSSL/OpenSSL 303---------------------- 304 305For all cryptography-related functions, tinc uses the functions provided 306by the LibreSSL or the OpenSSL library. 307 308If this library is not installed, you will get an error when configuring 309tinc for build. Support for running tinc with other cryptographic 310libraries installed _may_ be added in the future. 311 312You can use your operating system's package manager to install this if 313available. Make sure you install the development AND runtime versions 314of this package. 315 316If your operating system comes neither with LibreSSL or OpenSSL, you 317have to install one manually. It is recommended that you get the latest 318version of LibreSSL from <https://www.libressl.org/>. Instructions on 319how to configure, build and install this package are included within the 320package. Please make sure you build development and runtime libraries 321(which is the default). 322 323If you installed the LibreSSL or OpenSSL libraries from source, it may 324be necessary to let configure know where they are, by passing configure 325one of the -with-openssl-* parameters. Note that you even have to use 326-with-openssl-* if you are using LibreSSL. 327 328 --with-openssl=DIR LibreSSL/OpenSSL library and headers prefix 329 --with-openssl-include=DIR LibreSSL/OpenSSL headers directory 330 (Default is OPENSSL_DIR/include) 331 --with-openssl-lib=DIR LibreSSL/OpenSSL library directory 332 (Default is OPENSSL_DIR/lib) 333 334License 335....... 336 337The complete source code of tinc is covered by the GNU GPL version 2. 338Since the license under which OpenSSL is distributed is not directly 339compatible with the terms of the GNU GPL 340<https://www.openssl.org/support/faq.html#LEGAL2>, we include an 341exemption to the GPL (see also the file COPYING.README) to allow 342everyone to create a statically or dynamically linked executable: 343 344 This program is released under the GPL with the additional 345 exemption that compiling, linking, and/or using OpenSSL is allowed. 346 You may provide binary packages linked to the OpenSSL libraries, 347 provided that all other requirements of the GPL are met. 348 349Since the LZO library used by tinc is also covered by the GPL, we also 350present the following exemption: 351 352 Hereby I grant a special exception to the tinc VPN project 353 (https://www.tinc-vpn.org/) to link the LZO library with the 354 OpenSSL library (https://www.openssl.org). 355 356 Markus F.X.J. Oberhumer 357 358 359File: tinc.info, Node: zlib, Next: LZO, Prev: LibreSSL/OpenSSL, Up: Libraries 360 3612.2.2 zlib 362---------- 363 364For the optional compression of UDP packets, tinc uses the functions 365provided by the zlib library. 366 367If this library is not installed, you will get an error when running the 368configure script. You can either install the zlib library, or disable 369support for zlib compression by using the '--disable-zlib' option when 370running the configure script. Note that if you disable support for 371zlib, the resulting binary will not work correctly on VPNs where zlib 372compression is used. 373 374You can use your operating system's package manager to install this if 375available. Make sure you install the development AND runtime versions 376of this package. 377 378If you have to install zlib manually, you can get the source code from 379<https://zlib.net/>. Instructions on how to configure, build and 380install this package are included within the package. Please make sure 381you build development and runtime libraries (which is the default). 382 383 384File: tinc.info, Node: LZO, Next: libcurses, Prev: zlib, Up: Libraries 385 3862.2.3 LZO 387--------- 388 389Another form of compression is offered using the LZO library. 390 391If this library is not installed, you will get an error when running the 392configure script. You can either install the LZO library, or disable 393support for LZO compression by using the '--disable-lzo' option when 394running the configure script. Note that if you disable support for LZO, 395the resulting binary will not work correctly on VPNs where LZO 396compression is used. 397 398You can use your operating system's package manager to install this if 399available. Make sure you install the development AND runtime versions 400of this package. 401 402If you have to install LZO manually, you can get the source code from 403<https://www.oberhumer.com/opensource/lzo/>. Instructions on how to 404configure, build and install this package are included within the 405package. Please make sure you build development and runtime libraries 406(which is the default). 407 408 409File: tinc.info, Node: libcurses, Next: libreadline, Prev: LZO, Up: Libraries 410 4112.2.4 libcurses 412--------------- 413 414For the 'tinc top' command, tinc requires a curses library. 415 416If this library is not installed, you will get an error when running the 417configure script. You can either install a suitable curses library, or 418disable all functionality that depends on a curses library by using the 419'--disable-curses' option when running the configure script. 420 421There are several curses libraries. It is recommended that you install 422"ncurses" (<https://invisible-island.net/ncurses/>), however other 423curses libraries should also work. In particular, "PDCurses" 424(<https://pdcurses.sourceforge.io/>) is recommended if you want to 425compile tinc for Windows. 426 427You can use your operating system's package manager to install this if 428available. Make sure you install the development AND runtime versions 429of this package. 430 431 432File: tinc.info, Node: libreadline, Prev: libcurses, Up: Libraries 433 4342.2.5 libreadline 435----------------- 436 437For the 'tinc' command's shell functionality, tinc uses the readline 438library. 439 440If this library is not installed, you will get an error when running the 441configure script. You can either install a suitable readline library, 442or disable all functionality that depends on a readline library by using 443the '--disable-readline' option when running the configure script. 444 445You can use your operating system's package manager to install this if 446available. Make sure you install the development AND runtime versions 447of this package. 448 449If you have to install libreadline manually, you can get the source code 450from <https://www.gnu.org/software/readline/>. Instructions on how to 451configure, build and install this package are included within the 452package. Please make sure you build development and runtime libraries 453(which is the default). 454 455 456File: tinc.info, Node: Installation, Next: Configuration, Prev: Preparations, Up: Top 457 4583 Installation 459************** 460 461If you use Debian, you may want to install one of the precompiled 462packages for your system. These packages are equipped with system 463startup scripts and sample configurations. 464 465If you cannot use one of the precompiled packages, or you want to 466compile tinc for yourself, you can use the source. The source is 467distributed under the GNU General Public License (GPL). Download the 468source from the download page (https://www.tinc-vpn.org/download/). 469 470Tinc comes in a convenient autoconf/automake package, which you can just 471treat the same as any other package. Which is just untar it, type 472'./configure' and then 'make'. More detailed instructions are in the 473file 'INSTALL', which is included in the source distribution. 474 475* Menu: 476 477* Building and installing tinc:: 478* System files:: 479 480 481File: tinc.info, Node: Building and installing tinc, Next: System files, Up: Installation 482 4833.1 Building and installing tinc 484================================ 485 486Detailed instructions on configuring the source, building tinc and 487installing tinc can be found in the file called 'INSTALL'. 488 489If you happen to have a binary package for tinc for your distribution, 490you can use the package management tools of that distribution to install 491tinc. The documentation that comes along with your distribution will 492tell you how to do that. 493 494* Menu: 495 496* Darwin (MacOS/X) build environment:: 497* MinGW (Windows) build environment:: 498 499 500File: tinc.info, Node: Darwin (MacOS/X) build environment, Next: MinGW (Windows) build environment, Up: Building and installing tinc 501 5023.1.1 Darwin (MacOS/X) build environment 503---------------------------------------- 504 505In order to build tinc on Darwin, you need to install Xcode from 506<https://developer.apple.com/xcode/>. It might also help to install a 507recent version of Fink from <http://www.finkproject.org/>. 508 509You need to download and install LibreSSL (or OpenSSL) and LZO, either 510directly from their websites (see *note Libraries::) or using Fink. 511 512 513File: tinc.info, Node: MinGW (Windows) build environment, Prev: Darwin (MacOS/X) build environment, Up: Building and installing tinc 514 5153.1.2 MinGW (Windows) build environment 516--------------------------------------- 517 518You will need to install the MinGW environment from 519<http://www.mingw.org>. You also need to download and install LibreSSL 520(or OpenSSL) and LZO. 521 522When tinc is compiled using MinGW it runs natively under Windows, it is 523not necessary to keep MinGW installed. 524 525When detaching, tinc will install itself as a service, which will be 526restarted automatically after reboots. 527 528 529File: tinc.info, Node: System files, Prev: Building and installing tinc, Up: Installation 530 5313.2 System files 532================ 533 534Before you can run tinc, you must make sure you have all the needed 535files on your system. 536 537* Menu: 538 539* Device files:: 540* Other files:: 541 542 543File: tinc.info, Node: Device files, Next: Other files, Up: System files 544 5453.2.1 Device files 546------------------ 547 548Most operating systems nowadays come with the necessary device files by 549default, or they have a mechanism to create them on demand. 550 551If you use Linux and do not have udev installed, you may need to create 552the following device file if it does not exist: 553 554 mknod -m 600 /dev/net/tun c 10 200 555 556 557File: tinc.info, Node: Other files, Prev: Device files, Up: System files 558 5593.2.2 Other files 560----------------- 561 562'/etc/networks' 563............... 564 565You may add a line to '/etc/networks' so that your VPN will get a 566symbolic name. For example: 567 568 myvpn 10.0.0.0 569 570'/etc/services' 571............... 572 573You may add this line to '/etc/services'. The effect is that you may 574supply 'tinc' as a valid port number to some programs. The number 655 575is registered with the IANA. 576 577 tinc 655/tcp TINC 578 tinc 655/udp TINC 579 # Ivo Timmermans <ivo@tinc-vpn.org> 580 581 582File: tinc.info, Node: Configuration, Next: Running tinc, Prev: Installation, Up: Top 583 5844 Configuration 585*************** 586 587* Menu: 588 589* Configuration introduction:: 590* Multiple networks:: 591* How connections work:: 592* Configuration files:: 593* Network interfaces:: 594* Example configuration:: 595 596 597File: tinc.info, Node: Configuration introduction, Next: Multiple networks, Up: Configuration 598 5994.1 Configuration introduction 600============================== 601 602Before actually starting to configure tinc and editing files, make sure 603you have read this entire section so you know what to expect. Then, 604make it clear to yourself how you want to organize your VPN: What are 605the nodes (computers running tinc)? What IP addresses/subnets do they 606have? What is the network mask of the entire VPN? Do you need special 607firewall rules? Do you have to set up masquerading or forwarding rules? 608Do you want to run tinc in router mode or switch mode? These questions 609can only be answered by yourself, you will not find the answers in this 610documentation. Make sure you have an adequate understanding of networks 611in general. A good resource on networking is the Linux Network 612Administrators Guide (https://www.tldp.org/LDP/nag2/). 613 614If you have everything clearly pictured in your mind, proceed in the 615following order: First, create the initial configuration files and 616public/private key pairs using the following command: 617 tinc -n NETNAME init NAME 618Second, use 'tinc -n NETNAME add ...' to further configure tinc. 619Finally, export your host configuration file using 'tinc -n NETNAME 620export' and send it to those people or computers you want tinc to 621connect to. They should send you their host configuration file back, 622which you can import using 'tinc -n NETNAME import'. 623 624These steps are described in the subsections below. 625 626 627File: tinc.info, Node: Multiple networks, Next: How connections work, Prev: Configuration introduction, Up: Configuration 628 6294.2 Multiple networks 630===================== 631 632In order to allow you to run more than one tinc daemon on one computer, 633for instance if your computer is part of more than one VPN, you can 634assign a NETNAME to your VPN. It is not required if you only run one 635tinc daemon, it doesn't even have to be the same on all the nodes of 636your VPN, but it is recommended that you choose one anyway. 637 638We will assume you use a netname throughout this document. This means 639that you call tinc with the -n argument, which will specify the netname. 640 641The effect of this option is that tinc will set its configuration root 642to '/usr/local/etc/tinc/NETNAME/', where NETNAME is your argument to the 643-n option. You will also notice that log messages it appears in syslog 644as coming from 'tinc.NETNAME', and on Linux, unless specified otherwise, 645the name of the virtual network interface will be the same as the 646network name. 647 648However, it is not strictly necessary that you call tinc with the -n 649option. If you do not use it, the network name will just be empty, and 650tinc will look for files in '/usr/local/etc/tinc/' instead of 651'/usr/local/etc/tinc/NETNAME/'; the configuration file will then be 652'/usr/local/etc/tinc/tinc.conf', and the host configuration files are 653expected to be in '/usr/local/etc/tinc/hosts/'. 654 655 656File: tinc.info, Node: How connections work, Next: Configuration files, Prev: Multiple networks, Up: Configuration 657 6584.3 How connections work 659======================== 660 661When tinc starts up, it parses the command-line options and then reads 662in the configuration file tinc.conf. It will then start listening for 663incoming connection from other daemons, and will by default also 664automatically try to connect to known peers. By default, tinc will try 665to keep at least 3 working meta-connections alive at all times. 666 667There is no real distinction between a server and a client in tinc. If 668you wish, you can view a tinc daemon without a 'ConnectTo' statement in 669tinc.conf and 'AutoConnect = no' as a server, and one which does have 670one or more 'ConnectTo' statements or 'Autoconnect = yes' (which is the 671default) as a client. It does not matter if two tinc daemons have a 672'ConnectTo' value pointing to each other however. 673 674Connections specified using 'ConnectTo' are so-called meta-connections. 675Tinc daemons exchange information about all other daemon they know about 676via these meta-connections. After learning about all the daemons in the 677VPN, tinc will create other connections as necessary in order to 678communicate with them. For example, if there are three daemons named A, 679B and C, and A has 'ConnectTo = B' in its tinc.conf file, and C has 680'ConnectTo = B' in its tinc.conf file, then A will learn about C from B, 681and will be able to exchange VPN packets with C without the need to have 682'ConnectTo = C' in its tinc.conf file. 683 684It could be that some daemons are located behind a Network Address 685Translation (NAT) device, or behind a firewall. In the above scenario 686with three daemons, if A and C are behind a NAT, B will automatically 687help A and C punch holes through their NAT, in a way similar to the STUN 688protocol, so that A and C can still communicate with each other 689directly. It is not always possible to do this however, and firewalls 690might also prevent direct communication. In that case, VPN packets 691between A and C will be forwarded by B. 692 693In effect, all nodes in the VPN will be able to talk to each other, as 694long as there is a path of meta-connections between them, and whenever 695possible, two nodes will communicate with each other directly. 696 697 698File: tinc.info, Node: Configuration files, Next: Network interfaces, Prev: How connections work, Up: Configuration 699 7004.4 Configuration files 701======================= 702 703The actual configuration of the daemon is done in the file 704'/usr/local/etc/tinc/NETNAME/tinc.conf' and at least one other file in 705the directory '/usr/local/etc/tinc/NETNAME/hosts/'. 706 707An optional directory '/usr/local/etc/tinc/NETNAME/conf.d' can be added 708from which any .conf file will be read. 709 710These file consists of comments (lines started with a #) or assignments 711in the form of 712 713 Variable = Value. 714 715The variable names are case insensitive, and any spaces, tabs, newlines 716and carriage returns are ignored. Note: it is not required that you put 717in the '=' sign, but doing so improves readability. If you leave it 718out, remember to replace it with at least one space character. 719 720The server configuration is complemented with host specific 721configuration (see the next section). Although all host configuration 722options for the local node listed in this document can also be put in 723'/usr/local/etc/tinc/NETNAME/tinc.conf', it is recommended to put host 724specific configuration options in the host configuration file, as this 725makes it easy to exchange with other nodes. 726 727You can edit the config file manually, but it is recommended that you 728use the tinc command to change configuration variables for you. 729 730In the following two subsections all valid variables are listed in 731alphabetical order. The default value is given between parentheses, 732other comments are between square brackets. 733 734* Menu: 735 736* Main configuration variables:: 737* Host configuration variables:: 738* Scripts:: 739* How to configure:: 740 741 742File: tinc.info, Node: Main configuration variables, Next: Host configuration variables, Up: Configuration files 743 7444.4.1 Main configuration variables 745---------------------------------- 746 747AddressFamily = <ipv4|ipv6|any> (any) 748 This option affects the address family of listening and outgoing 749 sockets. If any is selected, then depending on the operating 750 system both IPv4 and IPv6 or just IPv6 listening sockets will be 751 created. 752 753AutoConnect = <yes|no> (yes) 754 If set to yes, tinc will automatically set up meta connections to 755 other nodes, without requiring CONNECTTO variables. 756 757BindToAddress = <ADDRESS> [<PORT>] 758 This is the same as ListenAddress, however the address given with 759 the BindToAddress option will also be used for outgoing 760 connections. This is useful if your computer has more than one 761 IPv4 or IPv6 address, and you want tinc to only use a specific one 762 for outgoing packets. 763 764BindToInterface = <INTERFACE> [experimental] 765 If you have more than one network interface in your computer, tinc 766 will by default listen on all of them for incoming connections. It 767 is possible to bind tinc to a single interface like eth0 or ppp0 768 with this variable. 769 770 This option may not work on all platforms. Also, on some platforms 771 it will not actually bind to an interface, but rather to the 772 address that the interface has at the moment a socket is created. 773 774Broadcast = <no | mst | direct> (mst) [experimental] 775 This option selects the way broadcast packets are sent to other 776 daemons. _NOTE: all nodes in a VPN must use the same Broadcast 777 mode, otherwise routing loops can form._ 778 779 no 780 Broadcast packets are never sent to other nodes. 781 782 mst 783 Broadcast packets are sent and forwarded via the VPN's Minimum 784 Spanning Tree. This ensures broadcast packets reach all 785 nodes. 786 787 direct 788 Broadcast packets are sent directly to all nodes that can be 789 reached directly. Broadcast packets received from other nodes 790 are never forwarded. If the IndirectData option is also set, 791 broadcast packets will only be sent to nodes which we have a 792 meta connection to. 793 794BroadcastSubnet = ADDRESS[/PREFIXLENGTH] 795 Declares a broadcast subnet. Any packet with a destination address 796 falling into such a subnet will be routed as a broadcast (provided 797 all nodes have it declared). This is most useful to declare subnet 798 broadcast addresses (e.g. 10.42.255.255), otherwise tinc won't 799 know what to do with them. 800 801 Note that global broadcast addresses (MAC ff:ff:ff:ff:ff:ff, IPv4 802 255.255.255.255), as well as multicast space (IPv4 224.0.0.0/4, 803 IPv6 ff00::/8) are always considered broadcast addresses and don't 804 need to be declared. 805 806ConnectTo = <NAME> 807 Specifies which other tinc daemon to connect to on startup. 808 Multiple ConnectTo variables may be specified, in which case 809 outgoing connections to each specified tinc daemon are made. The 810 names should be known to this tinc daemon (i.e., there should be a 811 host configuration file for the name on the ConnectTo line). 812 813 If you don't specify a host with ConnectTo and have disabled 814 AutoConnect, tinc won't try to connect to other daemons at all, and 815 will instead just listen for incoming connections. 816 817DecrementTTL = <yes | no> (no) [experimental] 818 When enabled, tinc will decrement the Time To Live field in IPv4 819 packets, or the Hop Limit field in IPv6 packets, before forwarding 820 a received packet to the virtual network device or to another node, 821 and will drop packets that have a TTL value of zero, in which case 822 it will send an ICMP Time Exceeded packet back. 823 824 Do not use this option if you use switch mode and want to use IPv6. 825 826Device = <DEVICE> ('/dev/tap0', '/dev/net/tun' or other depending on platform) 827 The virtual network device to use. Tinc will automatically detect 828 what kind of device it is. Note that you can only use one device 829 per daemon. Under Windows, use INTERFACE instead of DEVICE. Note 830 that you can only use one device per daemon. See also *note Device 831 files::. 832 833DeviceStandby = <yes | no> (no) 834 When disabled, tinc calls 'tinc-up' on startup, and 'tinc-down' on 835 shutdown. When enabled, tinc will only call 'tinc-up' when at 836 least one node is reachable, and will call 'tinc-down' as soon as 837 no nodes are reachable. On Windows, this also determines when the 838 virtual network interface "cable" is "plugged". 839 840DeviceType = <TYPE> (platform dependent) 841 The type of the virtual network device. Tinc will normally 842 automatically select the right type of tun/tap interface, and this 843 option should not be used. However, this option can be used to 844 select one of the special interface types, if support for them is 845 compiled in. 846 847 dummy 848 Use a dummy interface. No packets are ever read or written to 849 a virtual network device. Useful for testing, or when setting 850 up a node that only forwards packets for other nodes. 851 852 raw_socket 853 Open a raw socket, and bind it to a pre-existing INTERFACE 854 (eth0 by default). All packets are read from this interface. 855 Packets received for the local node are written to the raw 856 socket. However, at least on Linux, the operating system does 857 not process IP packets destined for the local host. 858 859 multicast 860 Open a multicast UDP socket and bind it to the address and 861 port (separated by spaces) and optionally a TTL value 862 specified using DEVICE. Packets are read from and written to 863 this multicast socket. This can be used to connect to UML, 864 QEMU or KVM instances listening on the same multicast address. 865 Do NOT connect multiple tinc daemons to the same multicast 866 address, this will very likely cause routing loops. Also note 867 that this can cause decrypted VPN packets to be sent out on a 868 real network if misconfigured. 869 870 fd 871 Use a file descriptor, given directly as an integer or passed 872 through a unix domain socket. On Linux, an abstract socket 873 address can be specified by using '@' as a prefix. All 874 packets are read from this interface. Packets received for 875 the local node are written to it. 876 877 uml (not compiled in by default) 878 Create a UNIX socket with the filename specified by DEVICE, or 879 '/usr/local/var/run/NETNAME.umlsocket' if not specified. Tinc 880 will wait for a User Mode Linux instance to connect to this 881 socket. 882 883 vde (not compiled in by default) 884 Uses the libvdeplug library to connect to a Virtual 885 Distributed Ethernet switch, using the UNIX socket specified 886 by DEVICE, or '/usr/local/var/run/vde.ctl' if not specified. 887 888 Also, in case tinc does not seem to correctly interpret packets 889 received from the virtual network device, it can be used to change 890 the way packets are interpreted: 891 892 tun (BSD and Linux) 893 Set type to tun. Depending on the platform, this can either 894 be with or without an address family header (see below). 895 896 tunnohead (BSD) 897 Set type to tun without an address family header. Tinc will 898 expect packets read from the virtual network device to start 899 with an IP header. On some platforms IPv6 packets cannot be 900 read from or written to the device in this mode. 901 902 tunifhead (BSD) 903 Set type to tun with an address family header. Tinc will 904 expect packets read from the virtual network device to start 905 with a four byte header containing the address family, 906 followed by an IP header. This mode should support both IPv4 907 and IPv6 packets. 908 909 utun (OS X) 910 Set type to utun. This is only supported on OS X version 911 10.6.8 and higher, but doesn't require the tuntaposx module. 912 This mode should support both IPv4 and IPv6 packets. 913 914 tap (BSD and Linux) 915 Set type to tap. Tinc will expect packets read from the 916 virtual network device to start with an Ethernet header. 917 918DirectOnly = <yes|no> (no) [experimental] 919 When this option is enabled, packets that cannot be sent directly 920 to the destination node, but which would have to be forwarded by an 921 intermediate node, are dropped instead. When combined with the 922 IndirectData option, packets for nodes for which we do not have a 923 meta connection with are also dropped. 924 925Ed25519PrivateKeyFile = <PATH> ('/usr/local/etc/tinc/NETNAME/ed25519_key.priv') 926 The file in which the private Ed25519 key of this tinc daemon 927 resides. This is only used if ExperimentalProtocol is enabled. 928 929ExperimentalProtocol = <yes|no> (yes) 930 When this option is enabled, the SPTPS protocol will be used when 931 connecting to nodes that also support it. Ephemeral ECDH will be 932 used for key exchanges, and Ed25519 will be used instead of RSA for 933 authentication. When enabled, an Ed25519 key must have been 934 generated before with 'tinc generate-ed25519-keys'. 935 936Forwarding = <off|internal|kernel> (internal) [experimental] 937 This option selects the way indirect packets are forwarded. 938 939 off 940 Incoming packets that are not meant for the local node, but 941 which should be forwarded to another node, are dropped. 942 943 internal 944 Incoming packets that are meant for another node are forwarded 945 by tinc internally. 946 947 This is the default mode, and unless you really know you need 948 another forwarding mode, don't change it. 949 950 kernel 951 Incoming packets using the legacy protocol are always sent to 952 the TUN/TAP device, even if the packets are not for the local 953 node. This is less efficient, but allows the kernel to apply 954 its routing and firewall rules on them, and can also help 955 debugging. Incoming packets using the SPTPS protocol are 956 dropped, since they are end-to-end encrypted. 957 958FWMark = <VALUE> (0) [experimental] 959 When set to a non-zero value, all TCP and UDP sockets created by 960 tinc will use the given value as the firewall mark. This can be 961 used for mark-based routing or for packet filtering. This option 962 is currently only supported on Linux. 963 964Hostnames = <yes|no> (no) 965 This option selects whether IP addresses (both real and on the VPN) 966 should be resolved. Since DNS lookups are blocking, it might 967 affect tinc's efficiency, even stopping the daemon for a few 968 seconds every time it does a lookup if your DNS server is not 969 responding. 970 971 This does not affect resolving hostnames to IP addresses from the 972 configuration file, but whether hostnames should be resolved while 973 logging. 974 975Interface = <INTERFACE> 976 Defines the name of the interface corresponding to the virtual 977 network device. Depending on the operating system and the type of 978 device this may or may not actually set the name of the interface. 979 Under Windows, this variable is used to select which network 980 interface will be used. If you specified a Device, this variable 981 is almost always already correctly set. 982 983ListenAddress = <ADDRESS> [<PORT>] 984 If your computer has more than one IPv4 or IPv6 address, tinc will 985 by default listen on all of them for incoming connections. This 986 option can be used to restrict which addresses tinc listens on. 987 Multiple ListenAddress variables may be specified, in which case 988 listening sockets for each specified address are made. 989 990 If no PORT is specified, the socket will listen on the port 991 specified by the Port option, or to port 655 if neither is given. 992 To only listen on a specific port but not to a specific address, 993 use '*' for the ADDRESS. 994 995LocalDiscovery = <yes | no> (no) 996 When enabled, tinc will try to detect peers that are on the same 997 local network. This will allow direct communication using LAN 998 addresses, even if both peers are behind a NAT and they only 999 ConnectTo a third node outside the NAT, which normally would 1000 prevent the peers from learning each other's LAN address. 1001 1002 Currently, local discovery is implemented by sending some packets 1003 to the local address of the node during UDP discovery. This will 1004 not work with old nodes that don't transmit their local address. 1005 1006LogLevel = <LEVEL> (0) 1007 This option controls the verbosity of the logging. See *note Debug 1008 levels::. 1009 1010Mode = <router|switch|hub> (router) 1011 This option selects the way packets are routed to other daemons. 1012 1013 router 1014 In this mode Subnet variables in the host configuration files 1015 will be used to form a routing table. Only packets of 1016 routable protocols (IPv4 and IPv6) are supported in this mode. 1017 1018 This is the default mode, and unless you really know you need 1019 another mode, don't change it. 1020 1021 switch 1022 In this mode the MAC addresses of the packets on the VPN will 1023 be used to dynamically create a routing table just like an 1024 Ethernet switch does. Unicast, multicast and broadcast 1025 packets of every protocol that runs over Ethernet are 1026 supported in this mode at the cost of frequent broadcast ARP 1027 requests and routing table updates. 1028 1029 This mode is primarily useful if you want to bridge Ethernet 1030 segments. 1031 1032 hub 1033 This mode is almost the same as the switch mode, but instead 1034 every packet will be broadcast to the other daemons while no 1035 routing table is managed. 1036 1037InvitationExpire = <SECONDS> (604800) 1038 This option controls the time invitations are valid. 1039 1040KeyExpire = <SECONDS> (3600) 1041 This option controls the time the encryption keys used to encrypt 1042 the data are valid. It is common practice to change keys at 1043 regular intervals to make it even harder for crackers, even though 1044 it is thought to be nearly impossible to crack a single key. 1045 1046MACExpire = <SECONDS> (600) 1047 This option controls the amount of time MAC addresses are kept 1048 before they are removed. This only has effect when Mode is set to 1049 'switch'. 1050 1051MaxConnectionBurst = <COUNT> (100) 1052 This option controls how many connections tinc accepts in quick 1053 succession. If there are more connections than the given number in 1054 a short time interval, tinc will reduce the number of accepted 1055 connections to only one per second, until the burst has passed. 1056 1057Name = <NAME> [required] 1058 This is a symbolic name for this connection. The name must consist 1059 only of alfanumeric and underscore characters (a-z, A-Z, 0-9 and 1060 _), and is case sensitive. 1061 1062 If Name starts with a $, then the contents of the environment 1063 variable that follows will be used. In that case, invalid 1064 characters will be converted to underscores. If Name is $HOST, but 1065 no such environment variable exist, the hostname will be read using 1066 the gethostname() system call. 1067 1068PingInterval = <SECONDS> (60) 1069 The number of seconds of inactivity that tinc will wait before 1070 sending a probe to the other end. 1071 1072PingTimeout = <SECONDS> (5) 1073 The number of seconds to wait for a response to pings or to allow 1074 meta connections to block. If the other end doesn't respond within 1075 this time, the connection is terminated, and the others will be 1076 notified of this. 1077 1078PriorityInheritance = <yes|no> (no) [experimental] 1079 When this option is enabled the value of the TOS field of tunneled 1080 IPv4 packets will be inherited by the UDP packets that are sent 1081 out. 1082 1083PrivateKey = <KEY> [obsolete] 1084 This is the RSA private key for tinc. However, for safety reasons 1085 it is advised to store private keys of any kind in separate files. 1086 This prevents accidental eavesdropping if you are editing the 1087 configuration file. 1088 1089PrivateKeyFile = <PATH> ('/usr/local/etc/tinc/NETNAME/rsa_key.priv') 1090 This is the full path name of the RSA private key file that was 1091 generated by 'tinc generate-keys'. It must be a full path, not a 1092 relative directory. 1093 1094ProcessPriority = <low|normal|high> 1095 When this option is used the priority of the tincd process will be 1096 adjusted. Increasing the priority may help to reduce latency and 1097 packet loss on the VPN. 1098 1099Proxy = socks4 | socks5 | http | exec ... [experimental] 1100 Use a proxy when making outgoing connections. The following proxy 1101 types are currently supported: 1102 1103 socks4 <ADDRESS> <PORT> [<USERNAME>] 1104 Connects to the proxy using the SOCKS version 4 protocol. 1105 Optionally, a USERNAME can be supplied which will be passed on 1106 to the proxy server. 1107 1108 socks5 <ADDRESS> <PORT> [<USERNAME> <PASSWORD>] 1109 Connect to the proxy using the SOCKS version 5 protocol. If a 1110 USERNAME and PASSWORD are given, basic username/password 1111 authentication will be used, otherwise no authentication will 1112 be used. 1113 1114 http <ADDRESS> <PORT> 1115 Connects to the proxy and sends a HTTP CONNECT request. 1116 1117 exec <COMMAND> 1118 Executes the given command which should set up the outgoing 1119 connection. The environment variables 'NAME', 'NODE', 1120 'REMOTEADDRES' and 'REMOTEPORT' are available. 1121 1122ReplayWindow = <bytes> (32) 1123 This is the size of the replay tracking window for each remote 1124 node, in bytes. The window is a bitfield which tracks 1 packet per 1125 bit, so for example the default setting of 32 will track up to 256 1126 packets in the window. In high bandwidth scenarios, setting this 1127 to a higher value can reduce packet loss from the interaction of 1128 replay tracking with underlying real packet loss and/or reordering. 1129 Setting this to zero will disable replay tracking completely and 1130 pass all traffic, but leaves tinc vulnerable to replay-based 1131 attacks on your traffic. 1132 1133StrictSubnets = <yes|no> (no) [experimental] 1134 When this option is enabled tinc will only use Subnet statements 1135 which are present in the host config files in the local 1136 '/usr/local/etc/tinc/NETNAME/hosts/' directory. Subnets learned 1137 via connections to other nodes and which are not present in the 1138 local host config files are ignored. 1139 1140TunnelServer = <yes|no> (no) [experimental] 1141 When this option is enabled tinc will no longer forward information 1142 between other tinc daemons, and will only allow connections with 1143 nodes for which host config files are present in the local 1144 '/usr/local/etc/tinc/NETNAME/hosts/' directory. Setting this 1145 options also implicitly sets StrictSubnets. 1146 1147UDPDiscovery = <yes|no> (yes) 1148 When this option is enabled tinc will try to establish UDP 1149 connectivity to nodes, using TCP while it determines if a node is 1150 reachable over UDP. If it is disabled, tinc always assumes a node 1151 is reachable over UDP. Note that tinc will never use UDP with nodes 1152 that have TCPOnly enabled. 1153 1154UDPDiscoveryKeepaliveInterval = <seconds> (9) 1155 The minimum amount of time between sending UDP ping datagrams to 1156 check UDP connectivity once it has been established. Note that 1157 these pings are large, since they are used to verify link MTU as 1158 well. 1159 1160UDPDiscoveryInterval = <seconds> (2) 1161 The minimum amount of time between sending UDP ping datagrams to 1162 try to establish UDP connectivity. 1163 1164UDPDiscoveryTimeout = <seconds> (30) 1165 If tinc doesn't receive any UDP ping replies over the specified 1166 interval, it will assume UDP communication is broken and will fall 1167 back to TCP. 1168 1169UDPInfoInterval = <seconds> (5) 1170 The minimum amount of time between sending periodic updates about 1171 UDP addresses, which are mostly useful for UDP hole punching. 1172 1173UDPRcvBuf = <bytes> (1048576) 1174 Sets the socket receive buffer size for the UDP socket, in bytes. 1175 If set to zero, the default buffer size will be used by the 1176 operating system. Note: this setting can have a significant impact 1177 on performance, especially raw throughput. 1178 1179UDPSndBuf = <bytes> (1048576) 1180 Sets the socket send buffer size for the UDP socket, in bytes. If 1181 set to zero, the default buffer size will be used by the operating 1182 system. Note: this setting can have a significant impact on 1183 performance, especially raw throughput. 1184 1185UPnP = <yes|udponly|no> (no) 1186 If this option is enabled then tinc will search for UPnP-IGD 1187 devices on the local network. It will then create and maintain 1188 port mappings for tinc's listening TCP and UDP ports. If set to 1189 'udponly', tinc will only create a mapping for its UDP (data) port, 1190 not for its TCP (metaconnection) port. Note that tinc must have 1191 been built with miniupnpc support for this feature to be available. 1192 Furthermore, be advised that enabling this can have security 1193 implications, because the miniupnpc library that tinc uses might 1194 not be well-hardened with regard to malicious UPnP replies. 1195 1196UPnPDiscoverWait = <seconds> (5) 1197 The amount of time to wait for replies when probing the local 1198 network for UPnP devices. 1199 1200UPnPRefreshPeriod = <seconds> (5) 1201 How often tinc will re-add the port mapping, in case it gets reset 1202 on the UPnP device. This also controls the duration of the port 1203 mapping itself, which will be set to twice that duration. 1204 1205 1206File: tinc.info, Node: Host configuration variables, Next: Scripts, Prev: Main configuration variables, Up: Configuration files 1207 12084.4.2 Host configuration variables 1209---------------------------------- 1210 1211Address = <IP ADDRESS|HOSTNAME> [<port>] [recommended] 1212 This variable is only required if you want to connect to this host. 1213 It must resolve to the external IP address where the host can be 1214 reached, not the one that is internal to the VPN. If no port is 1215 specified, the default Port is used. Multiple Address variables 1216 can be specified, in which case each address will be tried until a 1217 working connection has been established. 1218 1219Cipher = <CIPHER> (blowfish) 1220 The symmetric cipher algorithm used to encrypt UDP packets using 1221 the legacy protocol. Any cipher supported by LibreSSL or OpenSSL 1222 is recognized. Furthermore, specifying 'none' will turn off packet 1223 encryption. It is best to use only those ciphers which support CBC 1224 mode. This option has no effect for connections using the SPTPS 1225 protocol, which always use AES-256-CTR. 1226 1227ClampMSS = <yes|no> (yes) 1228 This option specifies whether tinc should clamp the maximum segment 1229 size (MSS) of TCP packets to the path MTU. This helps in situations 1230 where ICMP Fragmentation Needed or Packet too Big messages are 1231 dropped by firewalls. 1232 1233Compression = <LEVEL> (0) 1234 This option sets the level of compression used for UDP packets. 1235 Possible values are 0 (off), 1 (fast zlib) and any integer up to 9 1236 (best zlib), 10 (fast LZO) and 11 (best LZO). 1237 1238Digest = <DIGEST> (sha1) 1239 The digest algorithm used to authenticate UDP packets using the 1240 legacy protocol. Any digest supported by LibreSSL or OpenSSL is 1241 recognized. Furthermore, specifying 'none' will turn off packet 1242 authentication. This option has no effect for connections using 1243 the SPTPS protocol, which always use HMAC-SHA-256. 1244 1245IndirectData = <yes|no> (no) 1246 When set to yes, other nodes which do not already have a meta 1247 connection to you will not try to establish direct communication 1248 with you. It is best to leave this option out or set it to no. 1249 1250MACLength = <BYTES> (4) 1251 The length of the message authentication code used to authenticate 1252 UDP packets using the legacy protocol. Can be anything from 0 up 1253 to the length of the digest produced by the digest algorithm. This 1254 option has no effect for connections using the SPTPS protocol, 1255 which never truncate MACs. 1256 1257PMTU = <MTU> (1514) 1258 This option controls the initial path MTU to this node. 1259 1260PMTUDiscovery = <yes|no> (yes) 1261 When this option is enabled, tinc will try to discover the path MTU 1262 to this node. After the path MTU has been discovered, it will be 1263 enforced on the VPN. 1264 1265MTUInfoInterval = <seconds> (5) 1266 The minimum amount of time between sending periodic updates about 1267 relay path MTU. Useful for quickly determining MTU to indirect 1268 nodes. 1269 1270Port = <PORT> (655) 1271 This is the port this tinc daemon listens on. You can use decimal 1272 portnumbers or symbolic names (as listed in '/etc/services'). 1273 1274PublicKey = <KEY> [obsolete] 1275 This is the RSA public key for this host. 1276 1277PublicKeyFile = <PATH> [obsolete] 1278 This is the full path name of the RSA public key file that was 1279 generated by 'tinc generate-keys'. It must be a full path, not a 1280 relative directory. 1281 1282 From version 1.0pre4 on tinc will store the public key directly 1283 into the host configuration file in PEM format, the above two 1284 options then are not necessary. Either the PEM format is used, or 1285 exactly *one of the above two options* must be specified in each 1286 host configuration file, if you want to be able to establish a 1287 connection with that host. 1288 1289Subnet = <ADDRESS[/PREFIXLENGTH[#WEIGHT]]> 1290 The subnet which this tinc daemon will serve. Tinc tries to look 1291 up which other daemon it should send a packet to by searching the 1292 appropriate subnet. If the packet matches a subnet, it will be 1293 sent to the daemon who has this subnet in his host configuration 1294 file. Multiple subnet lines can be specified for each daemon. 1295 1296 Subnets can either be single MAC, IPv4 or IPv6 addresses, in which 1297 case a subnet consisting of only that single address is assumed, or 1298 they can be a IPv4 or IPv6 network address with a prefixlength. 1299 For example, IPv4 subnets must be in a form like 192.168.1.0/24, 1300 where 192.168.1.0 is the network address and 24 is the number of 1301 bits set in the netmask. Note that subnets like 192.168.1.1/24 are 1302 invalid! Read a networking HOWTO/FAQ/guide if you don't understand 1303 this. IPv6 subnets are notated like fec0:0:0:1::/64. MAC 1304 addresses are notated like 0:1a:2b:3c:4d:5e. 1305 1306 Prefixlength is the number of bits set to 1 in the netmask part; 1307 for example: netmask 255.255.255.0 would become /24, 255.255.252.0 1308 becomes /22. This conforms to standard CIDR notation as described 1309 in RFC1519 (https://www.ietf.org/rfc/rfc1519.txt) 1310 1311 A Subnet can be given a weight to indicate its priority over 1312 identical Subnets owned by different nodes. The default weight is 1313 10. Lower values indicate higher priority. Packets will be sent 1314 to the node with the highest priority, unless that node is not 1315 reachable, in which case the node with the next highest priority 1316 will be tried, and so on. 1317 1318TCPonly = <yes|no> (no) 1319 If this variable is set to yes, then the packets are tunnelled over 1320 a TCP connection instead of a UDP connection. This is especially 1321 useful for those who want to run a tinc daemon from behind a 1322 masquerading firewall, or if UDP packet routing is disabled 1323 somehow. Setting this options also implicitly sets IndirectData. 1324 1325Weight = <weight> 1326 If this variable is set, it overrides the weight given to 1327 connections made with another host. A higher weight means a lower 1328 priority is given to this connection when broadcasting or 1329 forwarding packets. 1330 1331 1332File: tinc.info, Node: Scripts, Next: How to configure, Prev: Host configuration variables, Up: Configuration files 1333 13344.4.3 Scripts 1335------------- 1336 1337Apart from reading the server and host configuration files, tinc can 1338also run scripts at certain moments. Below is a list of filenames of 1339scripts and a description of when they are run. A script is only run if 1340it exists and if it is executable. 1341 1342Scripts are run synchronously; this means that tinc will temporarily 1343stop processing packets until the called script finishes executing. 1344This guarantees that scripts will execute in the exact same order as the 1345events that trigger them. If you need to run commands asynchronously, 1346you have to ensure yourself that they are being run in the background. 1347 1348Under Windows, the scripts should have the extension '.bat' or '.cmd'. 1349 1350'/usr/local/etc/tinc/NETNAME/tinc-up' 1351 This is the most important script. If it is present it will be 1352 executed right after the tinc daemon has been started and has 1353 connected to the virtual network device. It should be used to set 1354 up the corresponding network interface, but can also be used to 1355 start other things. 1356 1357 Under Windows you can use the Network Connections control panel 1358 instead of creating this script. 1359 1360'/usr/local/etc/tinc/NETNAME/tinc-down' 1361 This script is started right before the tinc daemon quits. 1362 1363'/usr/local/etc/tinc/NETNAME/hosts/HOST-up' 1364 This script is started when the tinc daemon with name HOST becomes 1365 reachable. 1366 1367'/usr/local/etc/tinc/NETNAME/hosts/HOST-down' 1368 This script is started when the tinc daemon with name HOST becomes 1369 unreachable. 1370 1371'/usr/local/etc/tinc/NETNAME/host-up' 1372 This script is started when any host becomes reachable. 1373 1374'/usr/local/etc/tinc/NETNAME/host-down' 1375 This script is started when any host becomes unreachable. 1376 1377'/usr/local/etc/tinc/NETNAME/subnet-up' 1378 This script is started when a Subnet becomes reachable. The Subnet 1379 and the node it belongs to are passed in environment variables. 1380 1381'/usr/local/etc/tinc/NETNAME/subnet-down' 1382 This script is started when a Subnet becomes unreachable. 1383 1384'/usr/local/etc/tinc/NETNAME/invitation-created' 1385 This script is started when a new invitation has been created. 1386 1387'/usr/local/etc/tinc/NETNAME/invitation-accepted' 1388 This script is started when an invitation has been used. 1389 1390The scripts are started without command line arguments, but can make use 1391of certain environment variables. Under UNIX like operating systems the 1392names of environment variables must be preceded by a $ in scripts. 1393Under Windows, in '.bat' or '.cmd' files, they have to be put between % 1394signs. 1395 1396'NETNAME' 1397 If a netname was specified, this environment variable contains it. 1398 1399'NAME' 1400 Contains the name of this tinc daemon. 1401 1402'DEVICE' 1403 Contains the name of the virtual network device that tinc uses. 1404 1405'INTERFACE' 1406 Contains the name of the virtual network interface that tinc uses. 1407 This should be used for commands like ifconfig. 1408 1409'NODE' 1410 When a host becomes (un)reachable, this is set to its name. If a 1411 subnet becomes (un)reachable, this is set to the owner of that 1412 subnet. 1413 1414'REMOTEADDRESS' 1415 When a host becomes (un)reachable, this is set to its real address. 1416 1417'REMOTEPORT' 1418 When a host becomes (un)reachable, this is set to the port number 1419 it uses for communication with other tinc daemons. 1420 1421'SUBNET' 1422 When a subnet becomes (un)reachable, this is set to the subnet. 1423 1424'WEIGHT' 1425 When a subnet becomes (un)reachable, this is set to the subnet 1426 weight. 1427 1428'INVITATION_FILE' 1429 When the 'invitation-created' script is called, this is set to the 1430 file where the invitation details will be stored. 1431 1432'INVITATION_URL' 1433 When the 'invitation-created' script is called, this is set to the 1434 invitation URL that has been created. 1435 1436Do not forget that under UNIX operating systems, you have to make the 1437scripts executable, using the command 'chmod a+x script'. 1438 1439 1440File: tinc.info, Node: How to configure, Prev: Scripts, Up: Configuration files 1441 14424.4.4 How to configure 1443---------------------- 1444 1445Step 1. Creating initial configuration files. 1446............................................. 1447 1448The initial directory structure, configuration files and public/private 1449key pairs are created using the following command: 1450 1451 tinc -n NETNAME init NAME 1452 1453(You will need to run this as root, or use 'sudo'.) This will create 1454the configuration directory '/usr/local/etc/tinc/NETNAME.', and inside 1455it will create another directory named 'hosts/'. In the configuration 1456directory, it will create the file 'tinc.conf' with the following 1457contents: 1458 1459 Name = NAME 1460 1461It will also create private RSA and Ed25519 keys, which will be stored 1462in the files 'rsa_key.priv' and 'ed25519_key.priv'. It will also create 1463a host configuration file 'hosts/NAME', which will contain the 1464corresponding public RSA and Ed25519 keys. 1465 1466Finally, on UNIX operating systems, it will create an executable script 1467'tinc-up', which will initially not do anything except warning that you 1468should edit it. 1469 1470Step 2. Modifying the initial configuration. 1471............................................ 1472 1473Unless you want to use tinc in switch mode, you should now configure 1474which range of addresses you will use on the VPN. Let's assume you will 1475be part of a VPN which uses the address range 192.168.0.0/16, and you 1476yourself have a smaller portion of that range: 192.168.2.0/24. Then you 1477should run the following command: 1478 1479 tinc -n NETNAME add subnet 192.168.2.0/24 1480 1481This will add a Subnet statement to your host configuration file. Try 1482opening the file '/usr/local/etc/tinc/NETNAME/hosts/NAME' in an editor. 1483You should now see a file containing the public RSA and Ed25519 keys 1484(which looks like a bunch of random characters), and the following line 1485at the bottom: 1486 1487 Subnet = 192.168.2.0/24 1488 1489If you will use more than one address range, you can add more Subnets. 1490For example, if you also use the IPv6 subnet fec0:0:0:2::/64, you can 1491add it as well: 1492 1493 tinc -n NETNAME add subnet fec0:0:0:2::/24 1494 1495This will add another line to the file 'hosts/NAME'. If you make a 1496mistake, you can undo it by simply using 'del' instead of 'add'. 1497 1498If you want other tinc daemons to create meta-connections to your 1499daemon, you should add your public IP address or hostname to your host 1500configuration file. For example, if your hostname is foo.example.org, 1501run: 1502 1503 tinc -n NETNAME add address foo.example.org 1504 1505Step 2. Exchanging configuration files. 1506....................................... 1507 1508In order for two tinc daemons to be able to connect to each other, they 1509each need the other's host configuration files. So if you want foo to 1510be able to connect with bar, You should send 'hosts/NAME' to bar, and 1511bar should send you his file which you should move to 'hosts/bar'. If 1512you are on a UNIX platform, you can easily send an email containing the 1513necessary information using the following command (assuming the owner of 1514bar has the email address bar@example.org): 1515 1516 tinc -n NETNAME export | mail -s "My config file" bar@example.org 1517 1518If the owner of bar does the same to send his host configuration file to 1519you, you can probably pipe his email through the following command, or 1520you can just start this command in a terminal and copy&paste the email: 1521 1522 tinc -n NETNAME import 1523 1524If you are the owner of bar yourself, and you have SSH access to that 1525computer, you can also swap the host configuration files using the 1526following command: 1527 1528 tinc -n NETNAME export \ 1529 | ssh bar.example.org tinc -n NETNAME exchange \ 1530 | tinc -n NETNAME import 1531 1532You can repeat this for a few other nodes as well. It is not necessary 1533to manually exchange host config files between all nodes; after the 1534initial connections are made tinc will learn about all the other nodes 1535in the VPN, and will automatically make other connections as necessary. 1536 1537 1538File: tinc.info, Node: Network interfaces, Next: Example configuration, Prev: Configuration files, Up: Configuration 1539 15404.5 Network interfaces 1541====================== 1542 1543Before tinc can start transmitting data over the tunnel, it must set up 1544the virtual network interface. 1545 1546First, decide which IP addresses you want to have associated with these 1547devices, and what network mask they must have. 1548 1549Tinc will open a virtual network device ('/dev/tun', '/dev/tap0' or 1550similar), which will also create a network interface called something 1551like 'tun0', 'tap0'. If you are using the Linux tun/tap driver, the 1552network interface will by default have the same name as the NETNAME. 1553Under Windows you can change the name of the network interface from the 1554Network Connections control panel. 1555 1556You can configure the network interface by putting ordinary ifconfig, 1557route, and other commands to a script named 1558'/usr/local/etc/tinc/NETNAME/tinc-up'. When tinc starts, this script 1559will be executed. When tinc exits, it will execute the script named 1560'/usr/local/etc/tinc/NETNAME/tinc-down', but normally you don't need to 1561create that script. You can manually open the script in an editor, or 1562use the following command: 1563 1564 tinc -n NETNAME edit tinc-up 1565 1566An example 'tinc-up' script, that would be appropriate for the scenario 1567in the previous section, is: 1568 1569 #!/bin/sh 1570 ifconfig $INTERFACE 192.168.2.1 netmask 255.255.0.0 1571 ip addr add fec0:0:0:2::/48 dev $INTERFACE 1572 1573The first command gives the interface an IPv4 address and a netmask. 1574The kernel will also automatically add an IPv4 route to this interface, 1575so normally you don't need to add route commands to the 'tinc-up' 1576script. The kernel will also bring the interface up after this command. 1577The netmask is the mask of the _entire_ VPN network, not just your own 1578subnet. The second command gives the interface an IPv6 address and 1579netmask, which will also automatically add an IPv6 route. If you only 1580want to use 'ip addr' commands on Linux, don't forget that it doesn't 1581bring the interface up, unlike ifconfig, so you need to add 'ip link set 1582$INTERFACE up' in that case. 1583 1584The exact syntax of the ifconfig and route commands differs from 1585platform to platform. You can look up the commands for setting 1586addresses and adding routes in *note Platform specific information::, 1587but it is best to consult the manpages of those utilities on your 1588platform. 1589 1590 1591File: tinc.info, Node: Example configuration, Prev: Network interfaces, Up: Configuration 1592 15934.6 Example configuration 1594========================= 1595 1596Imagine the following situation. Branch A of our example 'company' 1597wants to connect three branch offices in B, C and D using the Internet. 1598All four offices have a 24/7 connection to the Internet. 1599 1600A is going to serve as the center of the network. B and C will connect 1601to A, and D will connect to C. Each office will be assigned their own IP 1602network, 10.x.0.0. 1603 1604 A: net 10.1.0.0 mask 255.255.0.0 gateway 10.1.54.1 internet IP 1.2.3.4 1605 B: net 10.2.0.0 mask 255.255.0.0 gateway 10.2.1.12 internet IP 2.3.4.5 1606 C: net 10.3.0.0 mask 255.255.0.0 gateway 10.3.69.254 internet IP 3.4.5.6 1607 D: net 10.4.0.0 mask 255.255.0.0 gateway 10.4.3.32 internet IP 4.5.6.7 1608 1609Here, "gateway" is the VPN IP address of the machine that is running the 1610tincd, and "internet IP" is the IP address of the firewall, which does 1611not need to run tincd, but it must do a port forwarding of TCP and UDP 1612on port 655 (unless otherwise configured). 1613 1614In this example, it is assumed that eth0 is the interface that points to 1615the inner (physical) LAN of the office, although this could also be the 1616same as the interface that leads to the Internet. The configuration of 1617the real interface is also shown as a comment, to give you an idea of 1618how these example host is set up. All branches use the netname 1619'company' for this particular VPN. 1620 1621Each branch is set up using the 'tinc init' and 'tinc config' commands, 1622here we just show the end results: 1623 1624For Branch A 1625............ 1626 1627_BranchA_ would be configured like this: 1628 1629In '/usr/local/etc/tinc/company/tinc-up': 1630 1631 #!/bin/sh 1632 1633 # Real interface of internal network: 1634 # ifconfig eth0 10.1.54.1 netmask 255.255.0.0 1635 1636 ifconfig $INTERFACE 10.1.54.1 netmask 255.0.0.0 1637 1638and in '/usr/local/etc/tinc/company/tinc.conf': 1639 1640 Name = BranchA 1641 1642On all hosts, '/usr/local/etc/tinc/company/hosts/BranchA' contains: 1643 1644 Subnet = 10.1.0.0/16 1645 Address = 1.2.3.4 1646 1647 -----BEGIN RSA PUBLIC KEY----- 1648 ... 1649 -----END RSA PUBLIC KEY----- 1650 1651Note that the IP addresses of eth0 and the VPN interface are the same. 1652This is quite possible, if you make sure that the netmasks of the 1653interfaces are different. It is in fact recommended to give both real 1654internal network interfaces and VPN interfaces the same IP address, 1655since that will make things a lot easier to remember and set up. 1656 1657For Branch B 1658............ 1659 1660In '/usr/local/etc/tinc/company/tinc-up': 1661 1662 #!/bin/sh 1663 1664 # Real interface of internal network: 1665 # ifconfig eth0 10.2.43.8 netmask 255.255.0.0 1666 1667 ifconfig $INTERFACE 10.2.1.12 netmask 255.0.0.0 1668 1669and in '/usr/local/etc/tinc/company/tinc.conf': 1670 1671 Name = BranchB 1672 1673Note here that the internal address (on eth0) doesn't have to be the 1674same as on the VPN interface. 1675 1676On all hosts, in '/usr/local/etc/tinc/company/hosts/BranchB': 1677 1678 Subnet = 10.2.0.0/16 1679 Address = 2.3.4.5 1680 1681 -----BEGIN RSA PUBLIC KEY----- 1682 ... 1683 -----END RSA PUBLIC KEY----- 1684 1685For Branch C 1686............ 1687 1688In '/usr/local/etc/tinc/company/tinc-up': 1689 1690 #!/bin/sh 1691 1692 # Real interface of internal network: 1693 # ifconfig eth0 10.3.69.254 netmask 255.255.0.0 1694 1695 ifconfig $INTERFACE 10.3.69.254 netmask 255.0.0.0 1696 1697and in '/usr/local/etc/tinc/company/tinc.conf': 1698 1699 Name = BranchC 1700 1701C already has another daemon that runs on port 655, so they have to 1702reserve another port for tinc. It knows the portnumber it has to listen 1703on from it's own host configuration file. 1704 1705On all hosts, in '/usr/local/etc/tinc/company/hosts/BranchC': 1706 1707 Address = 3.4.5.6 1708 Subnet = 10.3.0.0/16 1709 Port = 2000 1710 1711 -----BEGIN RSA PUBLIC KEY----- 1712 ... 1713 -----END RSA PUBLIC KEY----- 1714 1715For Branch D 1716............ 1717 1718In '/usr/local/etc/tinc/company/tinc-up': 1719 1720 #!/bin/sh 1721 1722 # Real interface of internal network: 1723 # ifconfig eth0 10.4.3.32 netmask 255.255.0.0 1724 1725 ifconfig $INTERFACE 10.4.3.32 netmask 255.0.0.0 1726 1727and in '/usr/local/etc/tinc/company/tinc.conf': 1728 1729 Name = BranchD 1730 1731D will be connecting to C, which has a tincd running for this network on 1732port 2000. It knows the port number from the host configuration file. 1733 1734On all hosts, in '/usr/local/etc/tinc/company/hosts/BranchD': 1735 1736 Subnet = 10.4.0.0/16 1737 Address = 4.5.6.7 1738 1739 -----BEGIN RSA PUBLIC KEY----- 1740 ... 1741 -----END RSA PUBLIC KEY----- 1742 1743Key files 1744......... 1745 1746A, B, C and D all have their own public/private key pairs: 1747 1748The private RSA key is stored in 1749'/usr/local/etc/tinc/company/rsa_key.priv', the private Ed25519 key is 1750stored in '/usr/local/etc/tinc/company/ed25519_key.priv', and the public 1751RSA and Ed25519 keys are put into the host configuration file in the 1752'/usr/local/etc/tinc/company/hosts/' directory. 1753 1754Starting 1755........ 1756 1757After each branch has finished configuration and they have distributed 1758the host configuration files amongst them, they can start their tinc 1759daemons. They don't necessarily have to wait for the other branches to 1760have started their daemons, tinc will try connecting until they are 1761available. 1762 1763 1764File: tinc.info, Node: Running tinc, Next: Controlling tinc, Prev: Configuration, Up: Top 1765 17665 Running tinc 1767************** 1768 1769If everything else is done, you can start tinc by typing the following 1770command: 1771 1772 tinc -n NETNAME start 1773 1774Tinc will detach from the terminal and continue to run in the background 1775like a good daemon. If there are any problems however you can try to 1776increase the debug level and look in the syslog to find out what the 1777problems are. 1778 1779* Menu: 1780 1781* Runtime options:: 1782* Signals:: 1783* Debug levels:: 1784* Solving problems:: 1785* Error messages:: 1786* Sending bug reports:: 1787 1788 1789File: tinc.info, Node: Runtime options, Next: Signals, Up: Running tinc 1790 17915.1 Runtime options 1792=================== 1793 1794Besides the settings in the configuration file, tinc also accepts some 1795command line options. 1796 1797'-c, --config=PATH' 1798 Read configuration options from the directory PATH. The default is 1799 '/usr/local/etc/tinc/NETNAME/'. 1800 1801'-D, --no-detach' 1802 Don't fork and detach. This will also disable the automatic 1803 restart mechanism for fatal errors. 1804 1805'-d, --debug=LEVEL' 1806 Set debug level to LEVEL. The higher the debug level, the more 1807 gets logged. Everything goes via syslog. 1808 1809'-n, --net=NETNAME' 1810 Use configuration for net NETNAME. This will let tinc read all 1811 configuration files from '/usr/local/etc/tinc/NETNAME/'. 1812 Specifying . for NETNAME is the same as not specifying any 1813 NETNAME. *Note Multiple networks::. 1814 1815'--pidfile=FILENAME' 1816 Store a cookie in FILENAME which allows tinc to authenticate. If 1817 unspecified, the default is '/usr/local/var/run/tinc.NETNAME.pid'. 1818 1819'-o, --option=[HOST.]KEY=VALUE' 1820 Without specifying a HOST, this will set server configuration 1821 variable KEY to VALUE. If specified as HOST.KEY=VALUE, this will 1822 set the host configuration variable KEY of the host named HOST to 1823 VALUE. This option can be used more than once to specify multiple 1824 configuration variables. 1825 1826'-L, --mlock' 1827 Lock tinc into main memory. This will prevent sensitive data like 1828 shared private keys to be written to the system swap 1829 files/partitions. 1830 1831 This option is not supported on all platforms. 1832 1833'--logfile[=FILE]' 1834 Write log entries to a file instead of to the system logging 1835 facility. If FILE is omitted, the default is 1836 '/usr/local/var/log/tinc.NETNAME.log'. 1837 1838'--pidfile=FILE' 1839 Write PID to FILE instead of '/usr/local/var/run/tinc.NETNAME.pid'. 1840 1841'--bypass-security' 1842 Disables encryption and authentication. Only useful for debugging. 1843 1844'-R, --chroot' 1845 Change process root directory to the directory where the config 1846 file is located ('/usr/local/etc/tinc/NETNAME/' as determined by 1847 -n/-net option or as given by -c/-config option), for added 1848 security. The chroot is performed after all the initialization is 1849 done, after writing pid files and opening network sockets. 1850 1851 This option is best used in combination with the -U/-user option 1852 described below. 1853 1854 You will need to ensure the chroot environment contains all the 1855 files necessary for tinc to run correctly. Most importantly, for 1856 tinc to be able to resolve hostnames inside the chroot environment, 1857 you must copy '/etc/resolv.conf' into the chroot directory. If you 1858 want to be able to run scripts other than 'tinc-up' in the chroot, 1859 you must ensure the appropriate shell is also installed in the 1860 chroot, along with all its dependencies. 1861 1862 This option is not supported on all platforms. 1863'-U, --user=USER' 1864 Switch to the given USER after initialization, at the same time as 1865 chroot is performed (see -chroot above). With this option tinc 1866 drops privileges, for added security. 1867 1868 This option is not supported on all platforms. 1869 1870'--help' 1871 Display a short reminder of these runtime options and terminate. 1872 1873'--version' 1874 Output version information and exit. 1875 1876 1877File: tinc.info, Node: Signals, Next: Debug levels, Prev: Runtime options, Up: Running tinc 1878 18795.2 Signals 1880=========== 1881 1882You can also send the following signals to a running tincd process: 1883 1884'ALRM' 1885 Forces tinc to try to connect to all uplinks immediately. Usually 1886 tinc attempts to do this itself, but increases the time it waits 1887 between the attempts each time it failed, and if tinc didn't 1888 succeed to connect to an uplink the first time after it started, it 1889 defaults to the maximum time of 15 minutes. 1890 1891'HUP' 1892 Partially rereads configuration files. Connections to hosts whose 1893 host config file are removed are closed. New outgoing connections 1894 specified in 'tinc.conf' will be made. If the -logfile option is 1895 used, this will also close and reopen the log file, useful when log 1896 rotation is used. 1897 1898 1899File: tinc.info, Node: Debug levels, Next: Solving problems, Prev: Signals, Up: Running tinc 1900 19015.3 Debug levels 1902================ 1903 1904The tinc daemon can send a lot of messages to the syslog. The higher 1905the debug level, the more messages it will log. Each level inherits all 1906messages of the previous level: 1907 1908'0' 1909 This will log a message indicating tinc has started along with a 1910 version number. It will also log any serious error. 1911 1912'1' 1913 This will log all connections that are made with other tinc 1914 daemons. 1915 1916'2' 1917 This will log status and error messages from scripts and other tinc 1918 daemons. 1919 1920'3' 1921 This will log all requests that are exchanged with other tinc 1922 daemons. These include authentication, key exchange and connection 1923 list updates. 1924 1925'4' 1926 This will log a copy of everything received on the meta socket. 1927 1928'5' 1929 This will log all network traffic over the virtual private network. 1930 1931 1932File: tinc.info, Node: Solving problems, Next: Error messages, Prev: Debug levels, Up: Running tinc 1933 19345.4 Solving problems 1935==================== 1936 1937If tinc starts without problems, but if the VPN doesn't work, you will 1938have to find the cause of the problem. The first thing to do is to 1939start tinc with a high debug level in the foreground, so you can 1940directly see everything tinc logs: 1941 1942 tincd -n NETNAME -d5 -D 1943 1944If tinc does not log any error messages, then you might want to check 1945the following things: 1946 1947 * 'tinc-up' script Does this script contain the right commands? 1948 Normally you must give the interface the address of this host on 1949 the VPN, and the netmask must be big enough so that the entire VPN 1950 is covered. 1951 1952 * Subnet Does the Subnet (or Subnets) in the host configuration file 1953 of this host match the portion of the VPN that belongs to this 1954 host? 1955 1956 * Firewalls and NATs Do you have a firewall or a NAT device (a 1957 masquerading firewall or perhaps an ADSL router that performs 1958 masquerading)? If so, check that it allows TCP and UDP traffic on 1959 port 655. If it masquerades and the host running tinc is behind 1960 it, make sure that it forwards TCP and UDP traffic to port 655 to 1961 the host running tinc. You can add 'TCPOnly = yes' to your host 1962 config file to force tinc to only use a single TCP connection, this 1963 works through most firewalls and NATs. 1964 1965 1966File: tinc.info, Node: Error messages, Next: Sending bug reports, Prev: Solving problems, Up: Running tinc 1967 19685.5 Error messages 1969================== 1970 1971What follows is a list of the most common error messages you might find 1972in the logs. Some of them will only be visible if the debug level is 1973high enough. 1974 1975'Could not open /dev/tap0: No such device' 1976 1977 * You forgot to 'modprobe netlink_dev' or 'modprobe ethertap'. 1978 * You forgot to compile 'Netlink device emulation' in the 1979 kernel. 1980 1981'Can't write to /dev/net/tun: No such device' 1982 1983 * You forgot to 'modprobe tun'. 1984 * You forgot to compile 'Universal TUN/TAP driver' in the 1985 kernel. 1986 * The tun device is located somewhere else in '/dev/'. 1987 1988'Network address and prefix length do not match!' 1989 1990 * The Subnet field must contain a _network_ address, trailing 1991 bits should be 0. 1992 * If you only want to use one IP address, set the netmask to 1993 /32. 1994 1995'Error reading RSA key file `rsa_key.priv': No such file or directory' 1996 1997 * You forgot to create a public/private key pair. 1998 * Specify the complete pathname to the private key file with the 1999 'PrivateKeyFile' option. 2000 2001'Warning: insecure file permissions for RSA private key file `rsa_key.priv'!' 2002 2003 * The private key file is readable by users other than root. 2004 Use chmod to correct the file permissions. 2005 2006'Creating metasocket failed: Address family not supported' 2007 2008 * By default tinc tries to create both IPv4 and IPv6 sockets. 2009 On some platforms this might not be implemented. If the logs 2010 show 'Ready' later on, then at least one metasocket was 2011 created, and you can ignore this message. You can add 2012 'AddressFamily = ipv4' to 'tinc.conf' to prevent this from 2013 happening. 2014 2015'Cannot route packet: unknown IPv4 destination 1.2.3.4' 2016 2017 * You try to send traffic to a host on the VPN for which no 2018 Subnet is known. 2019 * If it is a broadcast address (ending in .255), it probably is 2020 a samba server or a Windows host sending broadcast packets. 2021 You can ignore it. 2022 2023'Cannot route packet: ARP request for unknown address 1.2.3.4' 2024 2025 * You try to send traffic to a host on the VPN for which no 2026 Subnet is known. 2027 2028'Packet with destination 1.2.3.4 is looping back to us!' 2029 2030 * Something is not configured right. Packets are being sent out 2031 to the virtual network device, but according to the Subnet 2032 directives in your host configuration file, those packets 2033 should go to your own host. Most common mistake is that you 2034 have a Subnet line in your host configuration file with a 2035 prefix length which is just as large as the prefix of the 2036 virtual network interface. The latter should in almost all 2037 cases be larger. Rethink your configuration. Note that you 2038 will only see this message if you specified a debug level of 5 2039 or higher! 2040 * Chances are that a 'Subnet = ...' line in the host 2041 configuration file of this tinc daemon is wrong. Change it to 2042 a subnet that is accepted locally by another interface, or if 2043 that is not the case, try changing the prefix length into /32. 2044 2045'Node foo (1.2.3.4) is not reachable' 2046 2047 * Node foo does not have a connection anymore, its tinc daemon 2048 is not running or its connection to the Internet is broken. 2049 2050'Received UDP packet from unknown source 1.2.3.4 (port 12345)' 2051 2052 * If you see this only sporadically, it is harmless and caused 2053 by a node sending packets using an old key. 2054 * If you see this often and another node is not reachable 2055 anymore, then a NAT (masquerading firewall) is changing the 2056 source address of UDP packets. You can add 'TCPOnly = yes' to 2057 host configuration files to force all VPN traffic to go over a 2058 TCP connection. 2059 2060'Got bad/bogus/unauthorized REQUEST from foo (1.2.3.4 port 12345)' 2061 2062 * Node foo does not have the right public/private key pair. 2063 Generate new key pairs and distribute them again. 2064 * An attacker tries to gain access to your VPN. 2065 * A network error caused corruption of metadata sent from foo. 2066 2067 2068File: tinc.info, Node: Sending bug reports, Prev: Error messages, Up: Running tinc 2069 20705.6 Sending bug reports 2071======================= 2072 2073If you really can't find the cause of a problem, or if you suspect tinc 2074is not working right, you can send us a bugreport, see *note Contact 2075information::. Be sure to include the following information in your 2076bugreport: 2077 2078 * A clear description of what you are trying to achieve and what the 2079 problem is. 2080 * What platform (operating system, version, hardware architecture) 2081 and which version of tinc you use. 2082 * If compiling tinc fails, a copy of 'config.log' and the error 2083 messages you get. 2084 * Otherwise, a copy of 'tinc.conf', 'tinc-up' and all files in the 2085 'hosts/' directory. 2086 * The output of the commands 'ifconfig -a' and 'route -n' (or 2087 'netstat -rn' if that doesn't work). 2088 * The output of any command that fails to work as it should (like 2089 ping or traceroute). 2090 2091 2092File: tinc.info, Node: Controlling tinc, Next: Invitations, Prev: Running tinc, Up: Top 2093 20946 Controlling tinc 2095****************** 2096 2097You can start, stop, control and inspect a running tincd through the 2098tinc command. A quick example: 2099 2100 tinc -n NETNAME reload 2101 2102If tinc is started without a command, it will act as a shell; it will 2103display a prompt, and commands can be entered on the prompt. If tinc is 2104compiled with libreadline, history and command completion are available 2105on the prompt. One can also pipe a script containing commands through 2106tinc. In that case, lines starting with a # symbol will be ignored. 2107 2108* Menu: 2109 2110* tinc runtime options:: 2111* tinc environment variables:: 2112* tinc commands:: 2113* tinc examples:: 2114* tinc top:: 2115 2116 2117File: tinc.info, Node: tinc runtime options, Next: tinc environment variables, Up: Controlling tinc 2118 21196.1 tinc runtime options 2120======================== 2121 2122'-c, --config=PATH' 2123 Read configuration options from the directory PATH. The default is 2124 '/usr/local/etc/tinc/NETNAME/'. 2125 2126'-n, --net=NETNAME' 2127 Use configuration for net NETNAME. *Note Multiple networks::. 2128 2129'--pidfile=FILENAME' 2130 Use the cookie from FILENAME to authenticate with a running tinc 2131 daemon. If unspecified, the default is 2132 '/usr/local/var/run/tinc.NETNAME.pid'. 2133 2134'-b, --batch' 2135 Don't ask for anything (non-interactive mode). 2136 2137'--force' 2138 Force some commands to work despite warnings. 2139 2140'--help' 2141 Display a short reminder of runtime options and commands, then 2142 terminate. 2143 2144'--version' 2145 Output version information and exit. 2146 2147 2148File: tinc.info, Node: tinc environment variables, Next: tinc commands, Prev: tinc runtime options, Up: Controlling tinc 2149 21506.2 tinc environment variables 2151============================== 2152 2153'NETNAME' 2154 If no netname is specified on the command line with the '-n' 2155 option, the value of this environment variable is used. 2156 2157 2158File: tinc.info, Node: tinc commands, Next: tinc examples, Prev: tinc environment variables, Up: Controlling tinc 2159 21606.3 tinc commands 2161================= 2162 2163'init [NAME]' 2164 Create initial configuration files and RSA and Ed25519 key pairs 2165 with default length. If no NAME for this node is given, it will be 2166 asked for. 2167 2168'get VARIABLE' 2169 Print the current value of configuration variable VARIABLE. If 2170 more than one variable with the same name exists, the value of each 2171 of them will be printed on a separate line. 2172 2173'set VARIABLE VALUE' 2174 Set configuration variable VARIABLE to the given VALUE. All 2175 previously existing configuration variables with the same name are 2176 removed. To set a variable for a specific host, use the notation 2177 HOST.VARIABLE. 2178 2179'add VARIABLE VALUE' 2180 As above, but without removing any previously existing 2181 configuration variables. If the variable already exists with the 2182 given value, nothing happens. 2183 2184'del VARIABLE [VALUE]' 2185 Remove configuration variables with the same name and VALUE. If no 2186 VALUE is given, all configuration variables with the same name will 2187 be removed. 2188 2189'edit FILENAME' 2190 Start an editor for the given configuration file. You do not need 2191 to specify the full path to the file. 2192 2193'export' 2194 Export the host configuration file of the local node to standard 2195 output. 2196 2197'export-all' 2198 Export all host configuration files to standard output. 2199 2200'import' 2201 Import host configuration file(s) generated by the tinc export 2202 command from standard input. Already existing host configuration 2203 files are not overwritten unless the option -force is used. 2204 2205'exchange' 2206 The same as export followed by import. 2207 2208'exchange-all' 2209 The same as export-all followed by import. 2210 2211'invite NAME' 2212 Prepares an invitation for a new node with the given NAME, and 2213 prints a short invitation URL that can be used with the join 2214 command. 2215 2216'join [URL]' 2217 Join an existing VPN using an invitation URL created using the 2218 invite command. If no URL is given, it will be read from standard 2219 input. 2220 2221'start [tincd options]' 2222 Start 'tincd', optionally with the given extra options. 2223 2224'stop' 2225 Stop 'tincd'. 2226 2227'restart [tincd options]' 2228 Restart 'tincd', optionally with the given extra options. 2229 2230'reload' 2231 Partially rereads configuration files. Connections to hosts whose 2232 host config files are removed are closed. New outgoing connections 2233 specified in 'tinc.conf' will be made. 2234 2235'pid' 2236 Shows the PID of the currently running 'tincd'. 2237 2238'generate-keys [BITS]' 2239 Generate both RSA and Ed25519 key pairs (see below) and exit. tinc 2240 will ask where you want to store the files, but will default to the 2241 configuration directory (you can use the -c or -n option). 2242 2243'generate-ed25519-keys' 2244 Generate public/private Ed25519 key pair and exit. 2245 2246'generate-rsa-keys [BITS]' 2247 Generate public/private RSA key pair and exit. If BITS is omitted, 2248 the default length will be 2048 bits. When saving keys to existing 2249 files, tinc will not delete the old keys; you have to remove them 2250 manually. 2251 2252'dump [reachable] nodes' 2253 Dump a list of all known nodes in the VPN. If the reachable keyword 2254 is used, only lists reachable nodes. 2255 2256'dump edges' 2257 Dump a list of all known connections in the VPN. 2258 2259'dump subnets' 2260 Dump a list of all known subnets in the VPN. 2261 2262'dump connections' 2263 Dump a list of all meta connections with ourself. 2264 2265'dump graph | digraph' 2266 Dump a graph of the VPN in dotty format. Nodes are colored 2267 according to their reachability: red nodes are unreachable, orange 2268 nodes are indirectly reachable, green nodes are directly reachable. 2269 Black nodes are either directly or indirectly reachable, but direct 2270 reachability has not been tried yet. 2271 2272'dump invitations' 2273 Dump a list of outstanding invitations. The filename of the 2274 invitation, as well as the name of the node that is being invited 2275 is shown for each invitation. 2276 2277'info NODE | SUBNET | ADDRESS' 2278 Show information about a particular NODE, SUBNET or ADDRESS. If an 2279 ADDRESS is given, any matching subnet will be shown. 2280 2281'purge' 2282 Purges all information remembered about unreachable nodes. 2283 2284'debug LEVEL' 2285 Sets debug level to LEVEL. 2286 2287'log [LEVEL]' 2288 Capture log messages from a running tinc daemon. An optional debug 2289 level can be given that will be applied only for log messages sent 2290 to tinc. 2291 2292'retry' 2293 Forces tinc to try to connect to all uplinks immediately. Usually 2294 tinc attempts to do this itself, but increases the time it waits 2295 between the attempts each time it failed, and if tinc didn't 2296 succeed to connect to an uplink the first time after it started, it 2297 defaults to the maximum time of 15 minutes. 2298 2299'disconnect NODE' 2300 Closes the meta connection with the given NODE. 2301 2302'top' 2303 If tinc is compiled with libcurses support, this will display live 2304 traffic statistics for all the known nodes, similar to the UNIX top 2305 command. See below for more information. 2306 2307'pcap' 2308 Dump VPN traffic going through the local tinc node in pcap-savefile 2309 format to standard output, from where it can be redirected to a 2310 file or piped through a program that can parse it directly, such as 2311 tcpdump. 2312 2313'network [NETNAME]' 2314 If NETNAME is given, switch to that network. Otherwise, display a 2315 list of all networks for which configuration files exist. 2316 2317'fsck' 2318 This will check the configuration files for possible problems, such 2319 as unsafe file permissions, missing executable bit on script, 2320 unknown and obsolete configuration variables, wrong public and/or 2321 private keys, and so on. 2322 2323 When problems are found, this will be printed on a line with 2324 WARNING or ERROR in front of it. Most problems must be corrected 2325 by the user itself, however in some cases (like file permissions 2326 and missing public keys), tinc will ask if it should fix the 2327 problem. 2328 2329'sign [FILENAME]' 2330 Sign a file with the local node's private key. If no FILENAME is 2331 given, the file is read from standard input. The signed file is 2332 written to standard output. 2333 2334'verify NAME [FILENAME]' 2335 2336 Check the signature of a file against a node's public key. The 2337 NAME of the node must be given, or can be '.' to check against the 2338 local node's public key, or '*' to allow a signature from any node 2339 whose public key is known. If no FILENAME is given, the file is 2340 read from standard input. If the verification is successful, a 2341 copy of the input with the signature removed is written to standard 2342 output, and the exit code will be zero. If the verification 2343 failed, nothing will be written to standard output, and the exit 2344 code will be non-zero. 2345 2346 2347File: tinc.info, Node: tinc examples, Next: tinc top, Prev: tinc commands, Up: Controlling tinc 2348 23496.4 tinc examples 2350================= 2351 2352Examples of some commands: 2353 2354 tinc -n vpn dump graph | circo -Txlib 2355 tinc -n vpn pcap | tcpdump -r - 2356 tinc -n vpn top 2357 2358Examples of changing the configuration using tinc: 2359 2360 tinc -n vpn init foo 2361 tinc -n vpn add Subnet 192.168.1.0/24 2362 tinc -n vpn add bar.Address bar.example.com 2363 tinc -n vpn set Mode switch 2364 tinc -n vpn export | gpg --clearsign | mail -s "My config" vpnmaster@example.com 2365 2366 2367File: tinc.info, Node: tinc top, Prev: tinc examples, Up: Controlling tinc 2368 23696.5 tinc top 2370============ 2371 2372The top command connects to a running tinc daemon and repeatedly queries 2373its per-node traffic counters. It displays a list of all the known 2374nodes in the left-most column, and the amount of bytes and packets read 2375from and sent to each node in the other columns. By default, the 2376information is updated every second. The behaviour of the top command 2377can be changed using the following keys: 2378 2379<s> 2380 Change the interval between updates. After pressing the <s> key, 2381 enter the desired interval in seconds, followed by enter. 2382 Fractional seconds are honored. Intervals lower than 0.1 seconds 2383 are not allowed. 2384 2385<c> 2386 Toggle between displaying current traffic rates (in packets and 2387 bytes per second) and cumulative traffic (total packets and bytes 2388 since the tinc daemon started). 2389 2390<n> 2391 Sort the list of nodes by name. 2392 2393<i> 2394 Sort the list of nodes by incoming amount of bytes. 2395 2396<I> 2397 Sort the list of nodes by incoming amount of packets. 2398 2399<o> 2400 Sort the list of nodes by outgoing amount of bytes. 2401 2402<O> 2403 Sort the list of nodes by outgoing amount of packets. 2404 2405<t> 2406 Sort the list of nodes by sum of incoming and outgoing amount of 2407 bytes. 2408 2409<T> 2410 Sort the list of nodes by sum of incoming and outgoing amount of 2411 packets. 2412 2413<b> 2414 Show amount of traffic in bytes. 2415 2416<k> 2417 Show amount of traffic in kilobytes. 2418 2419<M> 2420 Show amount of traffic in megabytes. 2421 2422<G> 2423 Show amount of traffic in gigabytes. 2424 2425<q> 2426 Quit. 2427 2428 2429File: tinc.info, Node: Invitations, Next: Technical information, Prev: Controlling tinc, Up: Top 2430 24317 Invitations 2432************* 2433 2434Invitations are an easy way to add new nodes to an existing VPN. 2435Invitations can be created on an existing node using the 'tinc invite' 2436command, which generates a relatively short URL which can be given to 2437someone else, who uses the 'tinc join' command to automatically set up 2438tinc so it can connect to the inviting node. The next sections describe 2439how invitations actually work, and how to further automate the 2440invitations. 2441 2442* Menu: 2443 2444* How invitations work:: 2445* Invitation file format:: 2446* Writing an invitation-created script:: 2447 2448 2449File: tinc.info, Node: How invitations work, Next: Invitation file format, Up: Invitations 2450 24517.1 How invitations work 2452======================== 2453 2454When an invitation is created on a node (which from now on we will call 2455the server) using the 'tinc invite' command, an invitation file is 2456created that contains all the information necessary for the invitee 2457(which we will call the client) to create its configuration files. The 2458invitation file is stays on the server, but a URL is generated that has 2459enough information for the client to contact the server and to retrieve 2460the invitation file. The whole URL is around 80 characters long and 2461looks like this: 2462 2463 server.example.org:12345/cW1NhLHS-1WPFlcFio8ztYHvewTTKYZp8BjEKg3vbMtDz7w4 2464 2465It is composed of four parts: 2466 2467 hostname : port / keyhash cookie 2468 2469The hostname and port tell the client how to reach the tinc daemon on 2470the server. The part after the slash looks like one blob, but is 2471composed of two parts. The keyhash is the hash of the public key of the 2472server. The cookie is a shared secret that identifies the client to the 2473server. 2474 2475When the client connects to the server in order to join the VPN, the 2476client and server will exchange temporary public keys. The client 2477verifies that the hash of the server's public key matches the keyhash 2478from the invitation URL. If not, it will immediately exit with an error. 2479Otherwise, an ECDH exchange will happen so the client and server can 2480communicate privately with each other. The client will then present the 2481cookie to the server. The server uses this to look up the corresponding 2482invitation file it generated earlier. If it exists, it will send the 2483invitation file to the client. The client will also create a permanent 2484public key, and send it to the server. After the exchange is completed, 2485the connection is broken. The server creates a host config file for the 2486client containing the client's permanent public key, and the client 2487creates tinc.conf, host config files and possibly a tinc-up script based 2488on the information in the invitation file. 2489 2490It is important that the invitation URL is kept secret until it is used; 2491if another person gets a copy of the invitation URL before the real 2492client runs the 'tinc join' command, then that other person can try to 2493join the VPN. 2494 2495 2496File: tinc.info, Node: Invitation file format, Next: Writing an invitation-created script, Prev: How invitations work, Up: Invitations 2497 24987.2 Invitation file format 2499========================== 2500 2501The contents of an invitation file that is generated by the 'tinc 2502invite' command looks like this: 2503 2504 Name = client 2505 Netname = vpn 2506 ConnectTo = server 2507 #-------------------------------------# 2508 Name = server 2509 Ed25519PublicKey = augbnwegoij123587... 2510 Address = server.example.com 2511 2512The file is basically a concatenation of several host config blocks. 2513Each host config block starts with 'Name = ...'. Lines that look like 2514'#---#' are not important, it just makes it easier for humans to read 2515the file. However, the first line of an invitation file _must_ always 2516start with 'Name = ...'. 2517 2518The first host config block is always the one representing the invitee. 2519So the first Name statement determines the name that the invitee will 2520get. From the first block, the 'tinc.conf' and 'hosts/client' files 2521will be generated; the 'tinc join' command on the client will 2522automatically separate statements based on whether they should be in 2523'tinc.conf' or in a host config file. Some statements are special and 2524are treated differently: 2525 2526Netname = <NETNAME> 2527 This is a hint to the invitee which netname to use for the VPN. It 2528 is used if the invitee did not already specify a netname, and if 2529 there is no pre-existing configuration with the same netname. 2530 2531Ifconfig = <ADDRESS[/NETMASK] | dhcp | dhcp6 | slaac> 2532 This is a hint for generating a 'tinc-up' script. If an address is 2533 specified, a command will be added to 'tinc-up' so the VPN 2534 interface will be configured to have the given address. If it is 2535 the word 'dhcp', a command will be added to start a DHCP client on 2536 the VPN interface. If it is the word 'dhcpv6', it will be a DHCPv6 2537 client. If it is 'slaac', then it will add commands to enable IPv6 2538 stateless address autoconfiguration. It is also possible to 2539 specify a MAC address, in which case a command will be added to set 2540 the MAC address of the VPN interface. 2541 2542 The exact commands added to the 'tinc-up' script depends on the 2543 operating system the client is using. Multiple Ifconfig statements 2544 can be specified, however one should only use one Ifconfig 2545 statement per address family. 2546 2547Route = <ADDRESS[/NETMASK]> [<GATEWAY>] 2548 This is a hint for generating a 'tinc-up' script. Route statements 2549 are similar to Ifconfig statements, but add routes instead of 2550 addresses. These only allow IPv4 and IPv6 routes. If no gateway 2551 address is specified, the route is directed to the VPN interface. 2552 In general, a gateway is only necessary when running tinc in switch 2553 mode. 2554 2555Subsequent host config blocks are copied verbatim into their respective 2556files in 'hosts/'. The invitation file generated by 'tinc invite' will 2557normally only contain two blocks; one for the client and one for the 2558server. 2559 2560 2561File: tinc.info, Node: Writing an invitation-created script, Prev: Invitation file format, Up: Invitations 2562 25637.3 Writing an invitation-created script 2564======================================== 2565 2566When an invitation is generated, the 'invitation-created' script is 2567called (if it exists) right after the invitation file is written, but 2568before the URL has been written to stdout. This allows one to change 2569the invitation file automatically before the invitation URL is passed to 2570the invitee. Here is an example shell script that approximately 2571recreates the default invitation file: 2572 2573 #!/bin/sh 2574 2575 cat >$INVITATION_FILE <<EOF 2576 Name = $NODE 2577 Netname = $NETNAME 2578 ConnectTo = $NAME 2579 #----------------# 2580 EOF 2581 2582 tinc export >>$INVITATION_FILE 2583 2584You can add more ConnectTo statements, and change 'tinc export' to 'tinc 2585export-all' for example. But you can also use the script to 2586automatically hand out a Subnet to the invitee. Note that the script 2587doesn't have to be a shell script, you can use any language, it just has 2588to be executable. 2589 2590 2591File: tinc.info, Node: Technical information, Next: Platform specific information, Prev: Invitations, Up: Top 2592 25938 Technical information 2594*********************** 2595 2596* Menu: 2597 2598* The connection:: 2599* The meta-protocol:: 2600* Security:: 2601 2602 2603File: tinc.info, Node: The connection, Next: The meta-protocol, Up: Technical information 2604 26058.1 The connection 2606================== 2607 2608Tinc is a daemon that takes VPN data and transmit that to another host 2609computer over the existing Internet infrastructure. 2610 2611* Menu: 2612 2613* The UDP tunnel:: 2614* The meta-connection:: 2615 2616 2617File: tinc.info, Node: The UDP tunnel, Next: The meta-connection, Up: The connection 2618 26198.1.1 The UDP tunnel 2620-------------------- 2621 2622The data itself is read from a character device file, the so-called 2623_virtual network device_. This device is associated with a network 2624interface. Any data sent to this interface can be read from the device, 2625and any data written to the device gets sent from the interface. There 2626are two possible types of virtual network devices: 'tun' style, which 2627are point-to-point devices which can only handle IPv4 and/or IPv6 2628packets, and 'tap' style, which are Ethernet devices and handle complete 2629Ethernet frames. 2630 2631So when tinc reads an Ethernet frame from the device, it determines its 2632type. When tinc is in it's default routing mode, it can handle IPv4 and 2633IPv6 packets. Depending on the Subnet lines, it will send the packets 2634off to their destination IP address. In the 'switch' and 'hub' mode, 2635tinc will use broadcasts and MAC address discovery to deduce the 2636destination of the packets. Since the latter modes only depend on the 2637link layer information, any protocol that runs over Ethernet is 2638supported (for instance IPX and Appletalk). However, only 'tap' style 2639devices provide this information. 2640 2641After the destination has been determined, the packet will be compressed 2642(optionally), a sequence number will be added to the packet, the packet 2643will then be encrypted and a message authentication code will be 2644appended. 2645 2646When that is done, time has come to actually transport the packet to the 2647destination computer. We do this by sending the packet over an UDP 2648connection to the destination host. This is called _encapsulating_, the 2649VPN packet (though now encrypted) is encapsulated in another IP 2650datagram. 2651 2652When the destination receives this packet, the same thing happens, only 2653in reverse. So it checks the message authentication code, decrypts the 2654contents of the UDP datagram, checks the sequence number and writes the 2655decrypted information to its own virtual network device. 2656 2657If the virtual network device is a 'tun' device (a point-to-point 2658tunnel), there is no problem for the kernel to accept a packet. 2659However, if it is a 'tap' device (this is the only available type on 2660FreeBSD), the destination MAC address must match that of the virtual 2661network interface. If tinc is in it's default routing mode, ARP does 2662not work, so the correct destination MAC can not be known by the sending 2663host. Tinc solves this by letting the receiving end detect the MAC 2664address of its own virtual network interface and overwriting the 2665destination MAC address of the received packet. 2666 2667In switch or hub modes ARP does work so the sender already knows the 2668correct destination MAC address. In those modes every interface should 2669have a unique MAC address, so make sure they are not the same. Because 2670switch and hub modes rely on MAC addresses to function correctly, these 2671modes cannot be used on the following operating systems which don't have 2672a 'tap' style virtual network device: NetBSD, Darwin and Solaris. 2673 2674 2675File: tinc.info, Node: The meta-connection, Prev: The UDP tunnel, Up: The connection 2676 26778.1.2 The meta-connection 2678------------------------- 2679 2680Having only a UDP connection available is not enough. Though suitable 2681for transmitting data, we want to be able to reliably send other 2682information, such as routing and session key information to somebody. 2683 2684TCP is a better alternative, because it already contains protection 2685against information being lost, unlike UDP. 2686 2687So we establish two connections. One for the encrypted VPN data, and 2688one for other information, the meta-data. Hence, we call the second 2689connection the meta-connection. We can now be sure that the 2690meta-information doesn't get lost on the way to another computer. 2691 2692Like with any communication, we must have a protocol, so that everybody 2693knows what everything stands for, and how she should react. Because we 2694have two connections, we also have two protocols. The protocol used for 2695the UDP data is the "data-protocol," the other one is the 2696"meta-protocol." 2697 2698The reason we don't use TCP for both protocols is that UDP is much 2699better for encapsulation, even while it is less reliable. The real 2700problem is that when TCP would be used to encapsulate a TCP stream 2701that's on the private network, for every packet sent there would be 2702three ACKs sent instead of just one. Furthermore, if there would be a 2703timeout, both TCP streams would sense the timeout, and both would start 2704re-sending packets. 2705 2706 2707File: tinc.info, Node: The meta-protocol, Next: Security, Prev: The connection, Up: Technical information 2708 27098.2 The meta-protocol 2710===================== 2711 2712The meta protocol is used to tie all tinc daemons together, and exchange 2713information about which tinc daemon serves which virtual subnet. 2714 2715The meta protocol consists of requests that can be sent to the other 2716side. Each request has a unique number and several parameters. All 2717requests are represented in the standard ASCII character set. It is 2718possible to use tools such as telnet or netcat to connect to a tinc 2719daemon started with the -bypass-security option and to read and write 2720requests by hand, provided that one understands the numeric codes sent. 2721 2722The authentication scheme is described in *note Security::. After a 2723successful authentication, the server and the client will exchange all 2724the information about other tinc daemons and subnets they know of, so 2725that both sides (and all the other tinc daemons behind them) have their 2726information synchronised. 2727 2728 message 2729 ------------------------------------------------------------------ 2730 ADD_EDGE node1 node2 21.32.43.54 655 222 0 2731 | | | | | +-> options 2732 | | | | +----> weight 2733 | | | +--------> UDP port of node2 2734 | | +----------------> real address of node2 2735 | +-------------------------> name of destination node 2736 +-------------------------------> name of source node 2737 2738 ADD_SUBNET node 192.168.1.0/24 2739 | | +--> prefixlength 2740 | +--------> network address 2741 +------------------> owner of this subnet 2742 ------------------------------------------------------------------ 2743 2744The ADD_EDGE messages are to inform other tinc daemons that a connection 2745between two nodes exist. The address of the destination node is 2746available so that VPN packets can be sent directly to that node. 2747 2748The ADD_SUBNET messages inform other tinc daemons that certain subnets 2749belong to certain nodes. tinc will use it to determine to which node a 2750VPN packet has to be sent. 2751 2752 message 2753 ------------------------------------------------------------------ 2754 DEL_EDGE node1 node2 2755 | +----> name of destination node 2756 +----------> name of source node 2757 2758 DEL_SUBNET node 192.168.1.0/24 2759 | | +--> prefixlength 2760 | +--------> network address 2761 +------------------> owner of this subnet 2762 ------------------------------------------------------------------ 2763 2764In case a connection between two daemons is closed or broken, DEL_EDGE 2765messages are sent to inform the other daemons of that fact. Each daemon 2766will calculate a new route to the the daemons, or mark them unreachable 2767if there isn't any. 2768 2769 message 2770 ------------------------------------------------------------------ 2771 REQ_KEY origin destination 2772 | +--> name of the tinc daemon it wants the key from 2773 +----------> name of the daemon that wants the key 2774 2775 ANS_KEY origin destination 4ae0b0a82d6e0078 91 64 4 2776 | | \______________/ | | +--> MAC length 2777 | | | | +-----> digest algorithm 2778 | | | +--------> cipher algorithm 2779 | | +--> 128 bits key 2780 | +--> name of the daemon that wants the key 2781 +----------> name of the daemon that uses this key 2782 2783 KEY_CHANGED origin 2784 +--> daemon that has changed it's packet key 2785 ------------------------------------------------------------------ 2786 2787The keys used to encrypt VPN packets are not sent out directly. This is 2788because it would generate a lot of traffic on VPNs with many daemons, 2789and chances are that not every tinc daemon will ever send a packet to 2790every other daemon. Instead, if a daemon needs a key it sends a request 2791for it via the meta connection of the nearest hop in the direction of 2792the destination. 2793 2794 daemon message 2795 ------------------------------------------------------------------ 2796 origin PING 2797 dest. PONG 2798 ------------------------------------------------------------------ 2799 2800There is also a mechanism to check if hosts are still alive. Since 2801network failures or a crash can cause a daemon to be killed without 2802properly shutting down the TCP connection, this is necessary to keep an 2803up to date connection list. PINGs are sent at regular intervals, except 2804when there is also some other traffic. A little bit of salt (random 2805data) is added with each PING and PONG message, to make sure that long 2806sequences of PING/PONG messages without any other traffic won't result 2807in known plaintext. 2808 2809This basically covers what is sent over the meta connection by tinc. 2810 2811 2812File: tinc.info, Node: Security, Prev: The meta-protocol, Up: Technical information 2813 28148.3 Security 2815============ 2816 2817Tinc got its name from "TINC," short for _There Is No Cabal_; the 2818alleged Cabal was/is an organisation that was said to keep an eye on the 2819entire Internet. As this is exactly what you _don't_ want, we named the 2820tinc project after TINC. 2821 2822But in order to be "immune" to eavesdropping, you'll have to encrypt 2823your data. Because tinc is a _Secure_ VPN (SVPN) daemon, it does 2824exactly that: encrypt. However, encryption in itself does not prevent 2825an attacker from modifying the encrypted data. Therefore, tinc also 2826authenticates the data. Finally, tinc uses sequence numbers (which 2827themselves are also authenticated) to prevent an attacker from replaying 2828valid packets. 2829 2830Since version 1.1pre3, tinc has two protocols used to protect your data; 2831the legacy protocol, and the new Simple Peer-to-Peer Security (SPTPS) 2832protocol. The SPTPS protocol is designed to address some weaknesses in 2833the legacy protocol. The new authentication protocol is used when two 2834nodes connect to each other that both have the ExperimentalProtocol 2835option set to yes, otherwise the legacy protocol will be used. 2836 2837* Menu: 2838 2839* Legacy authentication protocol:: 2840* Simple Peer-to-Peer Security:: 2841* Encryption of network packets:: 2842* Security issues:: 2843 2844 2845File: tinc.info, Node: Legacy authentication protocol, Next: Simple Peer-to-Peer Security, Up: Security 2846 28478.3.1 Legacy authentication protocol 2848------------------------------------ 2849 2850 daemon message 2851 -------------------------------------------------------------------------- 2852 client <attempts connection> 2853 2854 server <accepts connection> 2855 2856 client ID client 17.2 2857 | | +-> minor protocol version 2858 | +----> major protocol version 2859 +--------> name of tinc daemon 2860 2861 server ID server 17.2 2862 | | +-> minor protocol version 2863 | +----> major protocol version 2864 +--------> name of tinc daemon 2865 2866 client META_KEY 94 64 0 0 5f0823a93e35b69e...7086ec7866ce582b 2867 | | | | \_________________________________/ 2868 | | | | +-> RSAKEYLEN bits totally random string S1, 2869 | | | | encrypted with server's public RSA key 2870 | | | +-> compression level 2871 | | +---> MAC length 2872 | +------> digest algorithm NID 2873 +---------> cipher algorithm NID 2874 2875 server META_KEY 94 64 0 0 6ab9c1640388f8f0...45d1a07f8a672630 2876 | | | | \_________________________________/ 2877 | | | | +-> RSAKEYLEN bits totally random string S2, 2878 | | | | encrypted with client's public RSA key 2879 | | | +-> compression level 2880 | | +---> MAC length 2881 | +------> digest algorithm NID 2882 +---------> cipher algorithm NID 2883 -------------------------------------------------------------------------- 2884 2885The protocol allows each side to specify encryption algorithms and 2886parameters, but in practice they are always fixed, since older versions 2887of tinc did not allow them to be different from the default values. The 2888cipher is always Blowfish in OFB mode, the digest is SHA1, but the MAC 2889length is zero and no compression is used. 2890 2891From now on: 2892 * the client will symmetrically encrypt outgoing traffic using S1 2893 * the server will symmetrically encrypt outgoing traffic using S2 2894 2895 -------------------------------------------------------------------------- 2896 client CHALLENGE da02add1817c1920989ba6ae2a49cecbda0 2897 \_________________________________/ 2898 +-> CHALLEN bits totally random string H1 2899 2900 server CHALLENGE 57fb4b2ccd70d6bb35a64c142f47e61d57f 2901 \_________________________________/ 2902 +-> CHALLEN bits totally random string H2 2903 2904 client CHAL_REPLY 816a86 2905 +-> 160 bits SHA1 of H2 2906 2907 server CHAL_REPLY 928ffe 2908 +-> 160 bits SHA1 of H1 2909 2910 After the correct challenge replies are received, both ends have proved 2911 their identity. Further information is exchanged. 2912 2913 client ACK 655 123 0 2914 | | +-> options 2915 | +----> estimated weight 2916 +--------> listening port of client 2917 2918 server ACK 655 321 0 2919 | | +-> options 2920 | +----> estimated weight 2921 +--------> listening port of server 2922 -------------------------------------------------------------------------- 2923 2924This legacy authentication protocol has several weaknesses, pointed out 2925by security export Peter Gutmann. First, data is encrypted with RSA 2926without padding. Padding schemes are designed to prevent attacks when 2927the size of the plaintext is not equal to the size of the RSA key. Tinc 2928always encrypts random nonces that have the same size as the RSA key, so 2929we do not believe this leads to a break of the security. There might be 2930timing or other side-channel attacks against RSA encryption and 2931decryption, tinc does not employ any protection against those. 2932Furthermore, both sides send identical messages to each other, there is 2933no distinction between server and client, which could make a MITM attack 2934easier. However, no exploit is known in which a third party who is not 2935already trusted by other nodes in the VPN could gain access. Finally, 2936the RSA keys are used to directly encrypt the session keys, which means 2937that if the RSA keys are compromised, it is possible to decrypt all 2938previous VPN traffic. In other words, the legacy protocol does not 2939provide perfect forward secrecy. 2940 2941 2942File: tinc.info, Node: Simple Peer-to-Peer Security, Next: Encryption of network packets, Prev: Legacy authentication protocol, Up: Security 2943 29448.3.2 Simple Peer-to-Peer Security 2945---------------------------------- 2946 2947The SPTPS protocol is designed to address the weaknesses in the legacy 2948protocol. SPTPS is based on TLS 1.2, but has been simplified: there is 2949no support for exchanging public keys, and there is no cipher suite 2950negotiation. Instead, SPTPS always uses a very strong cipher suite: 2951peers authenticate each other using 521 bits ECC keys, Diffie-Hellman 2952using ephemeral 521 bits ECC keys is used to provide perfect forward 2953secrecy (PFS), AES-256-CTR is used for encryption, and HMAC-SHA-256 for 2954message authentication. 2955 2956Similar to TLS, messages are split up in records. A complete logical 2957record contains the following information: 2958 2959 * uint32_t seqno (network byte order) 2960 * uint16_t length (network byte order) 2961 * uint8_t type 2962 * opaque data[length] 2963 * opaque hmac[HMAC_SIZE] (HMAC over all preceding fields) 2964 2965Depending on whether SPTPS records are sent via TCP or UDP, either the 2966seqno or the length field is omitted on the wire (but they are still 2967included in the calculation of the HMAC); for TCP packets are guaranteed 2968to arrive in-order so we can infer the seqno, but packets can be split 2969or merged, so we still need the length field to determine the boundaries 2970between records; for UDP packets we know that there is exactly one 2971record per packet, and we know the length of a packet, but packets can 2972be dropped, duplicated and/or reordered, so we need to include the 2973seqno. 2974 2975The type field is used to distinguish between application records or 2976handshake records. Types 0 to 127 are application records, type 128 is 2977a handshake record, and types 129 to 255 are reserved. 2978 2979Before the initial handshake, no fields are encrypted, and the HMAC 2980field is not present. After the authentication handshake, the length 2981(if present), type and data fields are encrypted, and the HMAC field is 2982present. For UDP packets, the seqno field is not encrypted, as it is 2983used to determine the value of the counter used for encryption. 2984 2985The authentication consists of an exchange of Key EXchange, SIGnature 2986and ACKnowledge messages, transmitted using type 128 records. 2987 2988Overview: 2989 2990 Initiator Responder 2991 --------------------- 2992 KEX -> 2993 <- KEX 2994 SIG -> 2995 <- SIG 2996 2997 ...encrypt and HMAC using session keys from now on... 2998 2999 App -> 3000 <- App 3001 ... 3002 ... 3003 3004 ...key renegotiation starts here... 3005 3006 KEX -> 3007 <- KEX 3008 SIG -> 3009 <- SIG 3010 ACK -> 3011 <- ACK 3012 3013 ...encrypt and HMAC using new session keys from now on... 3014 3015 App -> 3016 <- App 3017 ... 3018 ... 3019 --------------------- 3020 3021Note that the responder does not need to wait before it receives the 3022first KEX message, it can immediately send its own once it has accepted 3023an incoming connection. 3024 3025Key EXchange message: 3026 3027 * uint8_t kex_version (always 0 in this version of SPTPS) 3028 * opaque nonce[32] (random number) 3029 * opaque ecdh_key[ECDH_SIZE] 3030 3031SIGnature message: 3032 3033 * opaque ecdsa_signature[ECDSA_SIZE] 3034 3035ACKnowledge message: 3036 3037 * empty (only sent after key renegotiation) 3038 3039Remarks: 3040 3041 * At the start, both peers generate a random nonce and an Elliptic 3042 Curve public key and send it to the other in the KEX message. 3043 * After receiving the other's KEX message, both KEX messages are 3044 concatenated (see below), and the result is signed using ECDSA. The 3045 result is sent to the other. 3046 * After receiving the other's SIG message, the signature is verified. 3047 If it is correct, the shared secret is calculated from the public 3048 keys exchanged in the KEX message using the Elliptic Curve 3049 Diffie-Helman algorithm. 3050 * The shared secret key is expanded using a PRF. Both nonces and the 3051 application specific label are also used as input for the PRF. 3052 * An ACK message is sent only when doing key renegotiation, and is 3053 sent using the old encryption keys. 3054 * The expanded key is used to key the encryption and HMAC algorithms. 3055 3056The signature is calculated over this string: 3057 3058 * uint8_t initiator (0 = local peer, 1 = remote peer is initiator) 3059 * opaque remote_kex_message[1 + 32 + ECDH_SIZE] 3060 * opaque local_kex_message[1 + 32 + ECDH_SIZE] 3061 * opaque label[label_length] 3062 3063The PRF is calculated as follows: 3064 3065 * A HMAC using SHA512 is used, the shared secret is used as the key. 3066 * For each block of 64 bytes, a HMAC is calculated. For block n: 3067 hmac[n] = HMAC_SHA512(hmac[n - 1] + seed) 3068 * For the first block (n = 1), hmac[0] is given by HMAC_SHA512(zeroes 3069 + seed), where zeroes is a block of 64 zero bytes. 3070 3071The seed is as follows: 3072 3073 * const char[13] "key expansion" 3074 * opaque responder_nonce[32] 3075 * opaque initiator_nonce[32] 3076 * opaque label[label_length] 3077 3078The expanded key is used as follows: 3079 3080 * opaque responder_cipher_key[CIPHER_KEYSIZE] 3081 * opaque responder_digest_key[DIGEST_KEYSIZE] 3082 * opaque initiator_cipher_key[CIPHER_KEYSIZE] 3083 * opaque initiator_digest_key[DIGEST_KEYSIZE] 3084 3085Where initiator_cipher_key is the key used by session initiator to 3086encrypt messages sent to the responder. 3087 3088When using 256 bits Ed25519 keys, the AES-256-CTR cipher and 3089HMAC-SHA-256 digest algorithm, the sizes are as follows: 3090 3091 ECDH_SIZE: 32 (= 256/8) 3092 ECDSA_SIZE: 64 (= 2 * 256/8) 3093 CIPHER_KEYSIZE: 48 (= 256/8 + 128/8) 3094 DIGEST_KEYSIZE: 32 (= 256/8) 3095 3096Note that the cipher key also includes the initial value for the 3097counter. 3098 3099 3100File: tinc.info, Node: Encryption of network packets, Next: Security issues, Prev: Simple Peer-to-Peer Security, Up: Security 3101 31028.3.3 Encryption of network packets 3103----------------------------------- 3104 3105A data packet can only be sent if the encryption key is known to both 3106parties, and the connection is activated. If the encryption key is not 3107known, a request is sent to the destination using the meta connection to 3108retrieve it. 3109 3110The UDP packets can be either encrypted with the legacy protocol or with 3111SPTPS. In case of the legacy protocol, the UDP packet containing the 3112network packet from the VPN has the following layout: 3113 3114 ... | IP header | UDP header | seqno | VPN packet | MAC | UDP trailer 3115 \___________________/\_____/ 3116 | | 3117 V +---> digest algorithm 3118 Encrypted with symmetric cipher 3119 3120So, the entire VPN packet is encrypted using a symmetric cipher, 3121including a 32 bits sequence number that is added in front of the actual 3122VPN packet, to act as a unique IV for each packet and to prevent replay 3123attacks. A message authentication code is added to the UDP packet to 3124prevent alteration of packets. Tinc by default encrypts network packets 3125using Blowfish with 128 bit keys in CBC mode and uses 4 byte long 3126message authentication codes to make sure eavesdroppers cannot get and 3127cannot change any information at all from the packets they can 3128intercept. The encryption algorithm and message authentication 3129algorithm can be changed in the configuration. The length of the 3130message authentication codes is also adjustable. The length of the key 3131for the encryption algorithm is always the default length used by 3132LibreSSL/OpenSSL. 3133 3134The SPTPS protocol is described in *note Simple Peer-to-Peer Security::. 3135For comparison, this is how SPTPS UDP packets look: 3136 3137 ... | IP header | UDP header | seqno | type | VPN packet | MAC | UDP trailer 3138 \__________________/\_____/ 3139 | | 3140 V +---> digest algorithm 3141 Encrypted with symmetric cipher 3142 3143The difference is that the seqno is not encrypted, since the encryption 3144cipher is used in CTR mode, and therefore the seqno must be known before 3145the packet can be decrypted. Furthermore, the MAC is never truncated. 3146The SPTPS protocol always uses the AES-256-CTR cipher and HMAC-SHA-256 3147digest, this cannot be changed. 3148 3149 3150File: tinc.info, Node: Security issues, Prev: Encryption of network packets, Up: Security 3151 31528.3.4 Security issues 3153--------------------- 3154 3155In August 2000, we discovered the existence of a security hole in all 3156versions of tinc up to and including 1.0pre2. This had to do with the 3157way we exchanged keys. Since then, we have been working on a new 3158authentication scheme to make tinc as secure as possible. The current 3159version uses the LibreSSL or OpenSSL library and uses strong 3160authentication with RSA keys. 3161 3162On the 29th of December 2001, Jerome Etienne posted a security analysis 3163of tinc 1.0pre4. Due to a lack of sequence numbers and a message 3164authentication code for each packet, an attacker could possibly disrupt 3165certain network services or launch a denial of service attack by 3166replaying intercepted packets. The current version adds sequence 3167numbers and message authentication codes to prevent such attacks. 3168 3169On the 15th of September 2003, Peter Gutmann posted a security analysis 3170of tinc 1.0.1. He argues that the 32 bit sequence number used by tinc 3171is not a good IV, that tinc's default length of 4 bytes for the MAC is 3172too short, and he doesn't like tinc's use of RSA during authentication. 3173We do not know of a security hole in the legacy protocol of tinc, but it 3174is not as strong as TLS or IPsec. 3175 3176The Sweet32 attack affects versions of tinc prior to 1.0.30. 3177 3178On September 6th, 2018, Michael Yonly contacted us and provided 3179proof-of-concept code that allowed a remote attacker to create an 3180authenticated, one-way connection with a node, and also that there was a 3181possibility for a man-in-the-middle to force UDP packets from a node to 3182be sent in plaintext. The first issue was trivial to exploit on tinc 3183versions prior to 1.0.30, but the changes in 1.0.30 to mitigate the 3184Sweet32 attack made this weakness much harder to exploit. These issues 3185have been fixed in tinc 1.0.35. 3186 3187This version of tinc comes with an improved protocol, called Simple 3188Peer-to-Peer Security (SPTPS), which aims to be as strong as TLS with 3189one of the strongest cipher suites. None of the above security issues 3190affected SPTPS. However, be aware that SPTPS is only used between nodes 3191running tinc 1.1pre* or later, and in a VPN with nodes running different 3192versions, the security might only be as good as that of the oldest 3193version. 3194 3195Cryptography is a hard thing to get right. We cannot make any 3196guarantees. Time, review and feedback are the only things that can 3197prove the security of any cryptographic product. If you wish to review 3198tinc or give us feedback, you are strongly encouraged to do so. 3199 3200 3201File: tinc.info, Node: Platform specific information, Next: About us, Prev: Technical information, Up: Top 3202 32039 Platform specific information 3204******************************* 3205 3206* Menu: 3207 3208* Interface configuration:: 3209* Routes:: 3210* Automatically starting tinc:: 3211 3212 3213File: tinc.info, Node: Interface configuration, Next: Routes, Up: Platform specific information 3214 32159.1 Interface configuration 3216=========================== 3217 3218When configuring an interface, one normally assigns it an address and a 3219netmask. The address uniquely identifies the host on the network 3220attached to the interface. The netmask, combined with the address, 3221forms a subnet. It is used to add a route to the routing table 3222instructing the kernel to send all packets which fall into that subnet 3223to that interface. Because all packets for the entire VPN should go to 3224the virtual network interface used by tinc, the netmask should be such 3225that it encompasses the entire VPN. 3226 3227For IPv4 addresses: 3228 3229Linux 'ifconfig' INTERFACE ADDRESS 'netmask' NETMASK 3230Linux iproute2 'ip addr add' ADDRESS'/'PREFIXLENGTH 'dev' INTERFACE 3231FreeBSD 'ifconfig' INTERFACE ADDRESS 'netmask' NETMASK 3232OpenBSD 'ifconfig' INTERFACE ADDRESS 'netmask' NETMASK 3233NetBSD 'ifconfig' INTERFACE ADDRESS 'netmask' NETMASK 3234Solaris 'ifconfig' INTERFACE ADDRESS 'netmask' NETMASK 3235Darwin (MacOS/X) 'ifconfig' INTERFACE ADDRESS 'netmask' NETMASK 3236Windows 'netsh interface ip set address' INTERFACE 'static' ADDRESS NETMASK 3237 3238For IPv6 addresses: 3239 3240Linux 'ifconfig' INTERFACE 'add' ADDRESS'/'PREFIXLENGTH 3241FreeBSD 'ifconfig' INTERFACE 'inet6' ADDRESS 'prefixlen' PREFIXLENGTH 3242OpenBSD 'ifconfig' INTERFACE 'inet6' ADDRESS 'prefixlen' PREFIXLENGTH 3243NetBSD 'ifconfig' INTERFACE 'inet6' ADDRESS 'prefixlen' PREFIXLENGTH 3244Solaris 'ifconfig' INTERFACE 'inet6 plumb up' 3245 'ifconfig' INTERFACE 'inet6 addif' ADDRESS ADDRESS 3246Darwin (MacOS/X) 'ifconfig' INTERFACE 'inet6' ADDRESS 'prefixlen' PREFIXLENGTH 3247Windows 'netsh interface ipv6 add address' INTERFACE 'static' ADDRESS/PREFIXLENGTH 3248 3249On Linux, it is possible to create a persistent tun/tap interface which 3250will continue to exist even if tinc quit, although this is normally not 3251required. It can be useful to set up a tun/tap interface owned by a 3252non-root user, so tinc can be started without needing any root 3253privileges at all. 3254 3255Linux 'ip tuntap add dev' INTERFACE 'mode' TUN|TAP 'user' USERNAME 3256 3257 3258File: tinc.info, Node: Routes, Next: Automatically starting tinc, Prev: Interface configuration, Up: Platform specific information 3259 32609.2 Routes 3261========== 3262 3263In some cases it might be necessary to add more routes to the virtual 3264network interface. There are two ways to indicate which interface a 3265packet should go to, one is to use the name of the interface itself, 3266another way is to specify the (local) address that is assigned to that 3267interface (LOCAL_ADDRESS). The former way is unambiguous and therefore 3268preferable, but not all platforms support this. 3269 3270Adding routes to IPv4 subnets: 3271 3272Linux 'route add -net' NETWORK_ADDRESS 'netmask' NETMASK INTERFACE 3273Linux iproute2 'ip route add' NETWORK_ADDRESS'/'PREFIXLENGTH 'dev' INTERFACE 3274FreeBSD 'route add' NETWORK_ADDRESS'/'PREFIXLENGTH LOCAL_ADDRESS 3275OpenBSD 'route add' NETWORK_ADDRESS'/'PREFIXLENGTH LOCAL_ADDRESS 3276NetBSD 'route add' NETWORK_ADDRESS'/'PREFIXLENGTH LOCAL_ADDRESS 3277Solaris 'route add' NETWORK_ADDRESS'/'PREFIXLENGTH LOCAL_ADDRESS '-interface' 3278Darwin (MacOS/X) 'route add' NETWORK_ADDRESS'/'PREFIXLENGTH LOCAL_ADDRESS 3279Windows 'netsh routing ip add persistentroute' NETWORK_ADDRESS NETMASK INTERFACE 3280 LOCAL_ADDRESS 3281 3282Adding routes to IPv6 subnets: 3283 3284Linux 'route add -A inet6' NETWORK_ADDRESS'/'PREFIXLENGTH INTERFACE 3285Linux iproute2 'ip route add' NETWORK_ADDRESS'/'PREFIXLENGTH 'dev' INTERFACE 3286FreeBSD 'route add -inet6' NETWORK_ADDRESS'/'PREFIXLENGTH LOCAL_ADDRESS 3287OpenBSD 'route add -inet6' NETWORK_ADDRESS LOCAL_ADDRESS '-prefixlen' PREFIXLENGTH 3288NetBSD 'route add -inet6' NETWORK_ADDRESS LOCAL_ADDRESS '-prefixlen' PREFIXLENGTH 3289Solaris 'route add -inet6' NETWORK_ADDRESS'/'PREFIXLENGTH LOCAL_ADDRESS '-interface' 3290Darwin (MacOS/X) ? 3291Windows 'netsh interface ipv6 add route' NETWORK ADDRESS/PREFIXLENGTH INTERFACE 3292 3293 3294File: tinc.info, Node: Automatically starting tinc, Prev: Routes, Up: Platform specific information 3295 32969.3 Automatically starting tinc 3297=============================== 3298 3299* Menu: 3300 3301* Linux:: 3302* Windows:: 3303* Other platforms:: 3304 3305 3306File: tinc.info, Node: Linux, Next: Windows, Up: Automatically starting tinc 3307 33089.3.1 Linux 3309----------- 3310 3311There are many Linux distributions, and historically, many of them had 3312their own way of starting programs at boot time. Today, a number of 3313major Linux distributions have chosen to use systemd as their init 3314system. Tinc ships with systemd service files that allow you to start 3315and stop tinc using systemd. There are two service files: 3316'tinc.service' is used to globally enable or disable all tinc daemons 3317managed by systemd, and 'tinc@NETNAME.service' is used to enable or 3318disable specific tinc daemons. So if one has created a tinc network 3319with netname 'foo', then you have to run the following two commands to 3320ensure it is started at boot time: 3321 3322 systemctl enable tinc 3323 systemctl enable tinc@foo 3324 3325To start the tinc daemon immediately if it wasn't already running, use 3326the following command: 3327 3328 systemctl start tinc@foo 3329 3330You can also use 'systemctl start tinc', this will start all tinc 3331daemons that are enabled. You can stop and disable tinc networks in the 3332same way. 3333 3334If your system is not using systemd, then you have to look up your 3335distribution's way of starting tinc at boot time. 3336 3337 3338File: tinc.info, Node: Windows, Next: Other platforms, Prev: Linux, Up: Automatically starting tinc 3339 33409.3.2 Windows 3341------------- 3342 3343On Windows, if tinc is started with the 'tinc start' command without 3344using the '-D' or '--no-detach' option, it will automatically register 3345itself as a service that is started at boot time. When tinc is stopped 3346using the 'tinc stop' command, it will also automatically unregister 3347itself. Once tinc is registered as a service, it is also possible to 3348stop and start tinc using the Windows Services Manager. 3349 3350 3351File: tinc.info, Node: Other platforms, Prev: Windows, Up: Automatically starting tinc 3352 33539.3.3 Other platforms 3354--------------------- 3355 3356On platforms other than the ones mentioned in the earlier sections, you 3357have to look up your platform's way of starting programs at boot time. 3358 3359 3360File: tinc.info, Node: About us, Next: Concept Index, Prev: Platform specific information, Up: Top 3361 336210 About us 3363*********** 3364 3365* Menu: 3366 3367* Contact information:: 3368* Authors:: 3369 3370 3371File: tinc.info, Node: Contact information, Next: Authors, Up: About us 3372 337310.1 Contact information 3374======================== 3375 3376Tinc's website is at <https://www.tinc-vpn.org/>, this server is located 3377in the Netherlands. 3378 3379We have an IRC channel on the FreeNode and OFTC IRC networks. Connect 3380to irc.freenode.net (https://freenode.net/) or irc.oftc.net 3381(https://www.oftc.net/) and join channel #tinc. 3382 3383 3384File: tinc.info, Node: Authors, Prev: Contact information, Up: About us 3385 338610.2 Authors 3387============ 3388 3389Ivo Timmermans (zarq) 3390Guus Sliepen (guus) (<guus@tinc-vpn.org>) 3391 3392We have received a lot of valuable input from users. With their help, 3393tinc has become the flexible and robust tool that it is today. We have 3394composed a list of contributions, in the file called 'THANKS' in the 3395source distribution. 3396 3397 3398File: tinc.info, Node: Concept Index, Prev: About us, Up: Top 3399 3400Concept Index 3401************* 3402 3403[index] 3404* Menu: 3405 3406* ACK: Legacy authentication protocol. 3407 (line 6) 3408* add: tinc commands. (line 22) 3409* Address: Host configuration variables. 3410 (line 6) 3411* AddressFamily: Main configuration variables. 3412 (line 6) 3413* ADD_EDGE: The meta-protocol. (line 22) 3414* ADD_SUBNET: The meta-protocol. (line 22) 3415* ANS_KEY: The meta-protocol. (line 63) 3416* AutoConnect: Main configuration variables. 3417 (line 12) 3418* batch: tinc runtime options. 3419 (line 18) 3420* binary package: Building and installing tinc. 3421 (line 9) 3422* BindToAddress: Main configuration variables. 3423 (line 16) 3424* BindToInterface: Main configuration variables. 3425 (line 23) 3426* Broadcast: Main configuration variables. 3427 (line 33) 3428* BroadcastSubnet: Main configuration variables. 3429 (line 53) 3430* Cabal: Security. (line 6) 3431* CHALLENGE: Legacy authentication protocol. 3432 (line 6) 3433* CHAL_REPLY: Legacy authentication protocol. 3434 (line 6) 3435* CIDR notation: Host configuration variables. 3436 (line 101) 3437* Cipher: Host configuration variables. 3438 (line 14) 3439* ClampMSS: Host configuration variables. 3440 (line 22) 3441* client: How connections work. 3442 (line 12) 3443* command line: Runtime options. (line 9) 3444* command line interface: Controlling tinc. (line 6) 3445* Compression: Host configuration variables. 3446 (line 28) 3447* connection: The connection. (line 6) 3448* ConnectTo: Main configuration variables. 3449 (line 65) 3450* daemon: Running tinc. (line 11) 3451* data-protocol: The meta-connection. (line 18) 3452* debug: tinc commands. (line 127) 3453* debug level: Runtime options. (line 17) 3454* debug levels: Debug levels. (line 6) 3455* DecrementTTL: Main configuration variables. 3456 (line 76) 3457* del: tinc commands. (line 27) 3458* DEL_EDGE: The meta-protocol. (line 46) 3459* DEL_SUBNET: The meta-protocol. (line 46) 3460* Device: Main configuration variables. 3461 (line 85) 3462* DEVICE: Scripts. (line 71) 3463* device files: Device files. (line 6) 3464* DeviceStandby: Main configuration variables. 3465 (line 92) 3466* DeviceType: Main configuration variables. 3467 (line 99) 3468* Digest: Host configuration variables. 3469 (line 33) 3470* DirectOnly: Main configuration variables. 3471 (line 177) 3472* disconnect: tinc commands. (line 142) 3473* dummy: Main configuration variables. 3474 (line 106) 3475* dump: tinc commands. (line 95) 3476* Ed25519PrivateKeyFile: Main configuration variables. 3477 (line 184) 3478* edit: tinc commands. (line 32) 3479* encapsulating: The UDP tunnel. (line 30) 3480* encryption: Encryption of network packets. 3481 (line 6) 3482* environment variables: Scripts. (line 59) 3483* example: Example configuration. 3484 (line 6) 3485* exchange: tinc commands. (line 48) 3486* exchange-all: tinc commands. (line 51) 3487* exec: Main configuration variables. 3488 (line 376) 3489* ExperimentalProtocol: Main configuration variables. 3490 (line 188) 3491* export: tinc commands. (line 36) 3492* export-all: tinc commands. (line 40) 3493* fd: Main configuration variables. 3494 (line 129) 3495* Forwarding: Main configuration variables. 3496 (line 195) 3497* frame type: The UDP tunnel. (line 6) 3498* fsck: tinc commands. (line 160) 3499* FWMark: Main configuration variables. 3500 (line 217) 3501* generate-ed25519-keys: tinc commands. (line 86) 3502* generate-keys: tinc commands. (line 81) 3503* generate-rsa-keys: tinc commands. (line 89) 3504* get: tinc commands. (line 11) 3505* graph: tinc commands. (line 108) 3506* Hostnames: Main configuration variables. 3507 (line 223) 3508* http: Main configuration variables. 3509 (line 373) 3510* hub: Main configuration variables. 3511 (line 291) 3512* ID: Legacy authentication protocol. 3513 (line 6) 3514* Ifconfig: Invitation file format. 3515 (line 36) 3516* import: tinc commands. (line 43) 3517* IndirectData: Host configuration variables. 3518 (line 40) 3519* info: tinc commands. (line 120) 3520* init: tinc commands. (line 6) 3521* Interface: Main configuration variables. 3522 (line 234) 3523* INTERFACE: Scripts. (line 74) 3524* InvitationExpire: Main configuration variables. 3525 (line 296) 3526* INVITATION_FILE: Scripts. (line 97) 3527* INVITATION_URL: Scripts. (line 101) 3528* invite: tinc commands. (line 54) 3529* IRC: Contact information. (line 9) 3530* join: tinc commands. (line 59) 3531* KeyExpire: Main configuration variables. 3532 (line 299) 3533* KEY_CHANGED: The meta-protocol. (line 63) 3534* legacy authentication protocol: Legacy authentication protocol. 3535 (line 6) 3536* libcurses: libcurses. (line 6) 3537* libraries: Libraries. (line 6) 3538* libreadline: libreadline. (line 6) 3539* LibreSSL: LibreSSL/OpenSSL. (line 6) 3540* license: LibreSSL/OpenSSL. (line 38) 3541* ListenAddress: Main configuration variables. 3542 (line 242) 3543* LocalDiscovery: Main configuration variables. 3544 (line 254) 3545* log: tinc commands. (line 130) 3546* LogLevel: Main configuration variables. 3547 (line 265) 3548* LZO: LZO. (line 6) 3549* MACExpire: Main configuration variables. 3550 (line 305) 3551* MACLength: Host configuration variables. 3552 (line 45) 3553* MaxConnectionBurst: Main configuration variables. 3554 (line 310) 3555* meta-protocol: The meta-connection. (line 18) 3556* META_KEY: Legacy authentication protocol. 3557 (line 6) 3558* Mode: Main configuration variables. 3559 (line 269) 3560* MTUInfoInterval: Host configuration variables. 3561 (line 60) 3562* multicast: Main configuration variables. 3563 (line 118) 3564* multiple networks: Multiple networks. (line 6) 3565* Name: Main configuration variables. 3566 (line 316) 3567* NAME: Scripts. (line 68) 3568* netmask: Network interfaces. (line 40) 3569* netname: Multiple networks. (line 6) 3570* NETNAME: Scripts. (line 65) 3571* NETNAME <1>: tinc environment variables. 3572 (line 6) 3573* network: tinc commands. (line 156) 3574* Network Administrators Guide: Configuration introduction. 3575 (line 15) 3576* NODE: Scripts. (line 78) 3577* OpenSSL: LibreSSL/OpenSSL. (line 6) 3578* options: Runtime options. (line 9) 3579* pcap: tinc commands. (line 150) 3580* PEM format: Host configuration variables. 3581 (line 77) 3582* pid: tinc commands. (line 78) 3583* PING: The meta-protocol. (line 88) 3584* PingInterval: Main configuration variables. 3585 (line 327) 3586* PingTimeout: Main configuration variables. 3587 (line 331) 3588* platforms: Supported platforms. (line 6) 3589* PMTU: Host configuration variables. 3590 (line 52) 3591* PMTUDiscovery: Host configuration variables. 3592 (line 55) 3593* PONG: The meta-protocol. (line 88) 3594* Port: Host configuration variables. 3595 (line 65) 3596* port numbers: Other files. (line 17) 3597* PriorityInheritance: Main configuration variables. 3598 (line 337) 3599* private: Virtual Private Networks. 3600 (line 10) 3601* PrivateKey: Main configuration variables. 3602 (line 342) 3603* PrivateKeyFile: Main configuration variables. 3604 (line 348) 3605* ProcessPriority: Main configuration variables. 3606 (line 353) 3607* Proxy: Main configuration variables. 3608 (line 358) 3609* PublicKey: Host configuration variables. 3610 (line 69) 3611* PublicKeyFile: Host configuration variables. 3612 (line 72) 3613* purge: tinc commands. (line 124) 3614* raw_socket: Main configuration variables. 3615 (line 111) 3616* release: Supported platforms. (line 13) 3617* reload: tinc commands. (line 73) 3618* REMOTEADDRESS: Scripts. (line 83) 3619* REMOTEPORT: Scripts. (line 86) 3620* ReplayWindow: Main configuration variables. 3621 (line 381) 3622* requirements: Libraries. (line 6) 3623* REQ_KEY: The meta-protocol. (line 63) 3624* restart: tinc commands. (line 70) 3625* retry: tinc commands. (line 135) 3626* Route: Invitation file format. 3627 (line 52) 3628* router: Main configuration variables. 3629 (line 272) 3630* runtime options: Runtime options. (line 9) 3631* scalability: tinc. (line 19) 3632* scripts: Scripts. (line 6) 3633* server: How connections work. 3634 (line 12) 3635* set: tinc commands. (line 16) 3636* shell: Controlling tinc. (line 11) 3637* sign: tinc commands. (line 172) 3638* signals: Signals. (line 6) 3639* socks4: Main configuration variables. 3640 (line 362) 3641* socks5: Main configuration variables. 3642 (line 367) 3643* SPTPS: Simple Peer-to-Peer Security. 3644 (line 6) 3645* start: tinc commands. (line 64) 3646* stop: tinc commands. (line 67) 3647* StrictSubnets: Main configuration variables. 3648 (line 392) 3649* Subnet: Host configuration variables. 3650 (line 84) 3651* SUBNET: Scripts. (line 90) 3652* SVPN: Security. (line 11) 3653* switch: Main configuration variables. 3654 (line 280) 3655* systemd: Linux. (line 6) 3656* TCP: The meta-connection. (line 10) 3657* TCPonly: Host configuration variables. 3658 (line 113) 3659* tinc: Introduction. (line 6) 3660* TINC: Security. (line 6) 3661* tinc-down: Scripts. (line 29) 3662* tinc-up: Scripts. (line 19) 3663* tinc-up <1>: Network interfaces. (line 19) 3664* tincd: tinc. (line 14) 3665* top: tinc commands. (line 145) 3666* top <1>: tinc top. (line 6) 3667* traditional VPNs: tinc. (line 19) 3668* tunifhead: Main configuration variables. 3669 (line 161) 3670* TunnelServer: Main configuration variables. 3671 (line 399) 3672* tunnohead: Main configuration variables. 3673 (line 155) 3674* UDP: The UDP tunnel. (line 30) 3675* UDP <1>: Encryption of network packets. 3676 (line 11) 3677* UDPDiscoveryInterval: Main configuration variables. 3678 (line 419) 3679* UDPDiscoveryKeepaliveInterval: Main configuration variables. 3680 (line 413) 3681* UDPDiscoveryTimeout: Main configuration variables. 3682 (line 423) 3683* UDPDiscovey: Main configuration variables. 3684 (line 406) 3685* UDPInfoInterval: Main configuration variables. 3686 (line 428) 3687* UDPRcvBuf: Main configuration variables. 3688 (line 432) 3689* UDPSndBuf: Main configuration variables. 3690 (line 438) 3691* UML: Main configuration variables. 3692 (line 136) 3693* Universal tun/tap: Configuration of Linux kernels. 3694 (line 6) 3695* UPnP: Main configuration variables. 3696 (line 444) 3697* UPnPDiscoverWait: Main configuration variables. 3698 (line 455) 3699* UPnPRefreshPeriod: Main configuration variables. 3700 (line 459) 3701* utun: Main configuration variables. 3702 (line 168) 3703* VDE: Main configuration variables. 3704 (line 142) 3705* verify: tinc commands. (line 177) 3706* virtual: Virtual Private Networks. 3707 (line 18) 3708* virtual network device: The UDP tunnel. (line 6) 3709* VPN: Virtual Private Networks. 3710 (line 6) 3711* vpnd: tinc. (line 6) 3712* website: Contact information. (line 6) 3713* Weight: Host configuration variables. 3714 (line 120) 3715* WEIGHT: Scripts. (line 93) 3716* zlib: zlib. (line 6) 3717 3718 3719 3720Tag Table: 3721Node: Top821 3722Node: Introduction1157 3723Node: Virtual Private Networks1961 3724Node: tinc3673 3725Node: Supported platforms5186 3726Node: Preparations5839 3727Node: Configuring the kernel6095 3728Node: Configuration of Linux kernels6504 3729Node: Configuration of FreeBSD kernels7353 3730Node: Configuration of OpenBSD kernels7818 3731Node: Configuration of NetBSD kernels8175 3732Node: Configuration of Solaris kernels8577 3733Node: Configuration of Darwin (MacOS/X) kernels9239 3734Node: Configuration of Windows10052 3735Node: Libraries10591 3736Node: LibreSSL/OpenSSL11048 3737Node: zlib13576 3738Node: LZO14597 3739Node: libcurses15590 3740Node: libreadline16503 3741Node: Installation17443 3742Node: Building and installing tinc18347 3743Node: Darwin (MacOS/X) build environment18964 3744Node: MinGW (Windows) build environment19522 3745Node: System files20110 3746Node: Device files20375 3747Node: Other files20788 3748Node: Configuration21399 3749Node: Configuration introduction21686 3750Node: Multiple networks23209 3751Node: How connections work24627 3752Node: Configuration files26891 3753Node: Main configuration variables28562 3754Node: Host configuration variables50200 3755Node: Scripts56272 3756Node: How to configure60259 3757Node: Network interfaces64190 3758Node: Example configuration66590 3759Node: Running tinc71682 3760Node: Runtime options72269 3761Node: Signals75596 3762Node: Debug levels76445 3763Node: Solving problems77381 3764Node: Error messages78807 3765Node: Sending bug reports83127 3766Node: Controlling tinc84074 3767Node: tinc runtime options84810 3768Node: tinc environment variables85646 3769Node: tinc commands85975 3770Node: tinc examples92837 3771Node: tinc top93397 3772Node: Invitations94981 3773Node: How invitations work95644 3774Node: Invitation file format97937 3775Node: Writing an invitation-created script100950 3776Node: Technical information102013 3777Node: The connection102243 3778Node: The UDP tunnel102555 3779Node: The meta-connection105591 3780Node: The meta-protocol107049 3781Node: Security112032 3782Node: Legacy authentication protocol113369 3783Node: Simple Peer-to-Peer Security117986 3784Node: Encryption of network packets123631 3785Node: Security issues126269 3786Node: Platform specific information128861 3787Node: Interface configuration129121 3788Node: Routes131391 3789Node: Automatically starting tinc133338 3790Node: Linux133561 3791Node: Windows134773 3792Node: Other platforms135317 3793Node: About us135599 3794Node: Contact information135776 3795Node: Authors136179 3796Node: Concept Index136583 3797 3798End Tag Table 3799 3800 3801Local Variables: 3802coding: utf-8 3803End: 3804