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