16229e53afb08052a51cf5e05158dcce1dc19e1c
[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 @ifinfo
9 @direntry
10 * tinc: (tinc).              The tinc Manual.
11 @end direntry
12
13 This is the info manual for tinc, a Virtual Private Network daemon.
14
15 Copyright @copyright{} 1998,199,2000 Ivo Timmermans
16 <itimmermans@@bigfoot.com>, Guus Sliepen <guus@@sliepen.warande.net> and
17 Wessel Dankers <wsl@@nl.linux.org>.
18
19
20 Permission is granted to make and distribute verbatim copies of this
21 manual provided the copyright notice and this permission notice are
22 preserved on all copies.
23
24 Permission is granted to copy and distribute modified versions of this
25 manual under the conditions for verbatim copying, provided that the
26 entire resulting derived work is distributed under the terms of a
27 permission notice identical to this one.
28
29 @end ifinfo
30
31 @titlepage
32 @title tinc Manual
33 @subtitle Setting up a Virtual Private Network with tinc
34 @author Ivo Timmermans and Guus Sliepen
35
36 @page
37 @vskip 0pt plus 1filll
38 @cindex copyright
39 Copyright @copyright{} 1998,1999,2000 Ivo Timmermans
40 <itimmermans@@bigfoot.com>, Guus Sliepen <guus@@sliepen.warande.net> and
41 Wessel Dankers <wsl@@nl.linux.org>.
42
43 Permission is granted to make and distribute verbatim copies of this
44 manual provided the copyright notice and this permission notice are
45 preserved on all copies.
46
47 Permission is granted to copy and distribute modified versions of this
48 manual under the conditions for verbatim copying, provided that the
49 entire resulting derived work is distributed under the terms of a
50 permission notice identical to this one.
51
52 @end titlepage
53
54 @c ==================================================================
55 @node Top, Introduction, (dir), (dir)
56
57 @menu
58 * Introduction::                Introduction
59 * Installing tinc - preparations::  
60 * Installing tinc - installation::  
61 * Configuring tinc::            
62 * Running tinc::                
63 * Technical information::       
64 * About us::                    
65 * Concept Index::               All used terms explained
66 @end menu
67
68
69 @contents
70
71 @c ==================================================================
72 @node    Introduction, Installing tinc - preparations, Top, Top
73 @chapter Introduction
74
75 @cindex tinc
76 tinc is a Virtual Private Network (VPN) daemon that uses tunneling and
77 encryption to create a secure private network between hosts on the
78 Internet.
79
80 Because the tunnel appears to the IP level network code as a normal
81 network device, there is no need to adapt any existing software.
82
83 This tunneling allows VPN sites to share information with each other
84 over the Internet without exposing any information to others.
85
86 This document is the manual for tinc. Included are chapters on how to
87 configure your computer to use tinc, as well as the configuration
88 process of tinc itself.
89
90 @menu
91 * VPNs::                        Virtual Private Networks in general
92 * tinc::                        about tinc
93 * Supported platforms::         
94 @end menu
95
96 @c ==================================================================
97 @node    VPNs, tinc, Introduction, Introduction
98 @section Virtual Private Networks
99
100 @cindex VPN
101 A Virtual Private Network or VPN is a network that can only be accessed
102 by a few elected computers that participate. This goal is achievable in
103 more than just one way.
104
105 @cindex private
106 Private networks can consist of a single stand-alone ethernet LAN. Or
107 even two computers hooked up using a null-modem cable. In these cases,
108 it is
109 obvious that the network is @emph{private}, no one can access it from the
110 outside. But if your computers are linked to the internet, the network
111 is not private anymore, unless one uses firewalls to block all private
112 traffic. But then, there is no way to send private data to trusted
113 computers on the other end of the internet.
114
115 @cindex virtual
116 This problem can be solved by using @emph{virtual} networks. Virtual
117 networks can live on top of other networks, but do not interfere with
118 each other. Mostly, virtual networks appear like a singe LAN, even though
119 they can span the entire world. But virtual networks can't be secured
120 by using firewalls, because the traffic that flows through it has to go
121 through the internet, where other people can look at it.
122
123 When one introduces encryption, we can form a true VPN. Other people may
124 see encrypted traffic, but if they don't know how to decipher it (they
125 need to know the key for that), they cannot read the information that flows
126 through the VPN. This is what tinc was made for.
127
128 @cindex virtual
129 tinc uses normal IP datagrams to encapsulate data that goes over the VPN
130 network link. In this case it's also clear that the network is
131 @emph{virtual}, because no direct network link has to exist between to
132 participants.
133
134 As is the case with either type of VPN, anybody could eavesdrop. Or
135 worse, alter data. Hence it's probably advisable to encrypt the data
136 that flows over the network.
137
138
139 @c ==================================================================
140 @node    tinc, Supported platforms, VPNs, Introduction
141 @section tinc
142
143 @cindex vpnd
144 @cindex ethertap
145 I really don't quite remember what got us started, but it must have been
146 Guus' idea. He wrote a simple implementation (about 50 lines of C) that
147 used the @emph{ethertap} device that Linux knows of since somewhere
148 about kernel 2.1.60. It didn't work immediately and he improved it a
149 bit. At this stage, the project was still simply called @samp{vpnd}.
150
151 Since then, a lot has changed---to say the least.
152
153 @cindex tincd
154 tinc now supports encryption, it consists of a single daemon (tincd) for
155 both the receiving and sending end, it has become largely
156 runtime-configurable---in short, it has become a full-fledged
157 professional package.
158
159 A lot can---and will be---changed. I have a few things that I'd like to
160 see in the future releases of tinc. Not everything will be available in
161 the near future. Our first objective is to make tinc work perfectly as
162 it stands, and then add more advanced features.
163
164 Meanwhile, we're always open-minded towards new ideas. And we're
165 available too.
166
167
168 @c ==================================================================
169 @node    Supported platforms,  , tinc, Introduction
170 @section Supported platforms
171
172 tinc works on Linux, FreeBSD and Solaris.  These are the three platforms
173 that are supported by the universial TUN/TAP device driver, so if
174 support for other operating systems is added to this driver, perhaps
175 tinc will run on them as well.  Without this driver, tinc will most
176 likely compile and run, but it will not be able to send or receive data
177 packets.
178
179 @c ==================================================================
180 @subsection Linux
181
182 tinc was first written for Linux running on an intel x86 processor, so
183 this is the best supported platform.  The protocol however, and actually
184 anything about tinc, has been rewritten to support random byte ordering
185 and arbitrary word length.  So in theory it should run on other
186 processors that Linux runs on.  Take care however, we haven't been able
187 to really test it yet.  If you want to run tinc on another platform than
188 x86, and want to tell us how it went, please do so.
189
190 tinc uses the ethertap device that is provided in the standard kernel
191 since version 2.1.60, so anything above that (2.2.x, 2.3.x, and the
192 2.4.0-testx (which is current at the time of this writing) kernel
193 versions) is able to support tinc.
194
195
196 @c ==================================================================
197 @subsection FreeBSD
198
199 tinc on FreeBSD relies on the universial TUN/TAP driver for its data
200 acquisition from the kernel.  Therefore, tinc suports the same platforms
201 as this driver.  These are: FreeBSD 3.x, 4.x, 5.x.
202
203
204 @c ==================================================================
205 @subsection Solaris
206
207 tinc on Solaris relies on the universial TUN/TAP driver for its data
208 acquisition from the kernel.  Therefore, tinc suports the same platforms
209 as this driver.  These are: Solaris, 2.1.x.
210
211
212 @c
213 @c
214 @c
215 @c
216 @c
217 @c
218 @c       Preparing your system
219 @c
220 @c
221 @c
222 @c
223 @c
224
225 @c ==================================================================
226 @node    Installing tinc - preparations, Installing tinc - installation, Introduction, Top
227 @chapter Installing tinc: preparations
228
229 This chapter contains information on how to prepare your system to
230 support tinc.
231
232 @menu
233 * Configuring the kernel::      
234 * Libraries::                   
235 @end menu
236
237
238 @c ==================================================================
239 @node    Configuring the kernel, Libraries, Installing tinc - preparations, Installing tinc - preparations
240 @section Configuring the kernel
241
242 If you are running Linux, chances are good that your kernel already
243 supports all the devices that tinc needs for proper operation.  For
244 example, the standard kernel from Redhat Linux already has support for
245 ethertap and netlink compiled in.  Debian users can use the modconf
246 utility to select the modules.  If your Linux distribution supports this
247 method of selecting devices, look out for something called `ethertap',
248 and `netlink_dev'.  You need both these devices.
249
250 If you can install these devices in a similar manner, you may skip this
251 section.
252
253 @menu
254 * Configuration of the Linux kernel::  
255 * Configuration of the FreeBSD kernel::  
256 * Configuration of the Solaris kernel::  
257 @end menu
258
259
260 @c ==================================================================
261 @node       Configuration of the Linux kernel, Configuration of the FreeBSD kernel, Configuring the kernel, Configuring the kernel
262 @subsection Configuring the Linux kernel
263
264 Since this particular implementation only runs on 2.1 or higher Linux
265 kernels, you should grab one (2.2 is current at this time). A 2.0 port
266 is not really possible, unless someone tells me someone ported the
267 ethertap and netlink devices back to 2.0.
268
269 If you are unfamiliar with the process of configuring and compiling a
270 new kernel, you should read the
271 @uref{http://howto.linuxberg.com/LDP/HOWTO/Kernel-HOWTO.html, Kernel
272 HOWTO} first. Do that now!
273
274 Here are the options you have to turn on when configuring a new
275 kernel.
276
277 For kernel 2.2.x:
278
279 @example
280 Code maturity level options
281 [*] Prompt for development and/or incomplete code/drivers
282 Networking options
283 [*] Kernel/User netlink socket
284 <*> Netlink device emulation
285 Network device support
286 <*> Ethertap network tap
287 @end example
288
289 For kernel 2.3.x and 2.4.x:
290
291 @example
292 Code maturity level options
293 [*] Prompt for development and/or incomplete code/drivers
294 Networking options
295 [*] Kernel/User netlink socket
296 <*> Netlink device emulation
297 Network device support
298 <*> Universal TUN/TAP device driver support
299 @end example
300
301
302 Any other options not mentioned here are not relevant to tinc. If you
303 decide to build any of these as dynamic kernel modules, it's a good idea
304 to add these lines to @file{/etc/modules.conf}.
305
306 @example
307 alias tap0 ethertap
308 alias char-major-36 netlink_dev
309 @end example
310
311 If you have a 2.4 kernel, you can also choose to use the `Ethertap
312 network tap' device.  This is marked obsolete, because the universal
313 TUN/TAP driver is a newer implementation that is supposed to be used in
314 favor of ethertap.  For tinc, it doesn't really matter which one you
315 choose; based on the device file name, tinc will make the right choice
316 about what protocol to use.
317
318 Finally, after having set up other options, build the kernel and boot
319 it.  Unfortunately it's not possible to insert these modules in a
320 running kernel.
321
322
323 @c ==================================================================
324 @node       Configuration of the FreeBSD kernel, Configuration of the Solaris kernel, Configuration of the Linux kernel, Configuring the kernel
325 @subsection Configuring the FreeBSD kernel
326
327 This section will contain information on how to configure your FreeBSD
328 kernel to support the universal TUN/TAP device.  For 5.0 and 4.1
329 systems, this is included in the kernel configuration, for earlier
330 systems (4.0 and 3.x), you need to install the universal TUN/TAP driver
331 yourself.
332
333 Unfortunately somebody still has to write the text.
334
335
336 @c ==================================================================
337 @node       Configuration of the Solaris kernel,  , Configuration of the FreeBSD kernel, Configuring the kernel
338 @subsection Configuring the Solaris kernel
339
340 This section will contain information on how to configure your Solaris
341 kernel to support the universal TUN/TAP device.  You need to install
342 this driver yourself.
343
344 Unfortunately somebody still has to write the text.
345
346
347 @c ==================================================================
348 @node    Libraries,  , Configuring the kernel, Installing tinc - preparations
349 @section Libraries
350
351 @cindex requirements
352 Before you can configure or build tinc, you need to have the OpenSSL
353 library installed on your system.  If you try to configure tinc without
354 having installed it, configure will give you an error message, and stop.
355
356 @menu
357 * OpenSSL::                     
358 @end menu
359
360
361 @c ==================================================================
362 @node       OpenSSL,  , Libraries, Libraries
363 @subsection OpenSSL
364
365 @cindex OpenSSL
366 For all cryptography-related functions, tinc uses the functions provided
367 by the OpenSSL library.  We recommend using version 0.9.5 or 0.9.6 of
368 this library.  Other versions may also work, but we can guarantee
369 nothing.
370
371 If this library is not installed, you wil get an error when configuring
372 tinc for build.  Support for running tinc without having OpenSSL
373 installed @emph{may} be added in the future.
374
375 You can use your operating system's package manager to install this if
376 available.  Make sure you install the development AND runtime versions
377 of this package.
378
379 If you have to install OpenSSL manually, you can get the source code
380 from @url{http://www.openssl.org/}.  Instructions on how to configure,
381 build and install this package are included within the package.  Please
382 make sure you build development and runtime libraries (which is the
383 default).
384
385
386 @c
387 @c
388 @c
389 @c      Installing tinc
390 @c
391 @c
392 @c
393 @c
394
395 @c ==================================================================
396 @node    Installing tinc - installation, Configuring tinc, Installing tinc - preparations, Top
397 @chapter Installing tinc: installation
398
399 If you use Redhat or Debian, you may want to install one of the
400 precompiled packages for your system.  These packages are equipped with
401 system startup scripts and sample configurations.
402
403 If you don't run either of these systems, or you want to compile tinc
404 for yourself, you can use the source.  The source is distributed under
405 the GNU General Public License (GPL).  Download the source from the
406 @uref{http://tinc.nl.linux.org/download.html, download page}, which has
407 the checksums of these files listed; you may wish to check these with
408 md5sum before continuing.
409
410 tinc comes in a handy autoconf/automake package, which you can just
411 treat the same as any other package. Which is just untar it, type
412 `configure' and then `make'.
413
414 More detailed instructions are in the file @file{INSTALL}, which is
415 included in the source distribution.
416
417 @menu
418 * Building tinc::               
419 * System files::                
420 * Interfaces::                  
421 @end menu
422
423
424 @c ==================================================================
425 @node    Building tinc, System files, Installing tinc - installation, Installing tinc - installation
426 @section Building tinc
427
428 Detailed instructions on configuring the source and building tinc can be
429 found in the file called @file{INSTALL}.
430
431
432 @c ==================================================================
433 @node    System files, Interfaces, Building tinc, Installing tinc - installation
434 @section System files
435
436 Before you can run tinc, you 
437
438 @menu
439 * Device files::                
440 * Other files::                 
441 @end menu
442
443
444 @c ==================================================================
445 @node       Device files, Other files, System files, System files
446 @subsection Device files
447
448 First, you'll need the special device file(s) that form the interface
449 between the kernel and the daemon.
450
451 The permissions for these files have to be such that only the super user
452 may read/write to this file.  You'd want this, because otherwise
453 eavesdropping would become a bit too easy.  This does, however, imply
454 that you'd have to run tincd as root.
455
456 If you use the universal TUN/TAP driver, you have to create the
457 following device files (unless they already exist):
458
459 @example
460 mknod -m 600 /dev/... c .. ..
461 chown 0.0 /dev/...
462 @end example
463
464 If you want to have more devices, the device numbers will be .. .. ...
465
466 If you use Linux, and you run the new 2.4 kernel using the devfs
467 filesystem, then the tap device will be automatically generated as
468 @file{/dev/netlink/tap0}.
469
470 If you use Linux and have kernel 2.2.x, you have to make the ethertap
471 devices:
472
473 @example
474 mknod -m 600 /dev/tap0 c 36 16
475 chown 0.0 /dev/tap0
476 @end example
477
478 Any further ethertap devices have minor device number 16 through 31.
479
480
481 @c ==================================================================
482 @node       Other files,  , Device files, System files
483 @subsection Other files
484
485 @subsubheading @file{/etc/networks}
486
487 You may add a line to @file{/etc/networks} so that your VPN will get a
488 symbolic name. For example:
489
490 @example
491 myvpn 10.0.0.0
492 @end example
493
494 This has nothing to do with the MyVPNIP configuration variable that will be
495 discussed later, it is only to make the output of the route command more
496 legible.
497
498 @subsubheading @file{/etc/services}
499
500 You may add this line to @file{/etc/services}. The effect is that you
501 may supply a @samp{tinc} as a valid port number to some programs. The
502 number 655 is registered with the IANA.
503
504 @example
505 tinc            655/tcp    TINC
506 tinc            655/udp    TINC
507 #                          Ivo Timmermans <itimmermans@@bigfoot.com>
508 @end example
509
510
511 @c ==================================================================
512 @node    Interfaces,  , System files, Installing tinc - installation
513 @section Interfaces
514
515 Before you can start transmitting data over the tinc tunnel, you must
516 set up the ethertap network devices.
517
518 First, decide which IP addresses you want to have associated with these
519 devices, and what network mask they must have.  You also need these
520 numbers when you are going to configure tinc itself.  @xref{Configuring
521 tinc}.
522
523 It doesn't matter much which part you do first, setting up the network
524 devices or configure tinc. But they both have to be done before you try
525 to start a tincd.
526
527 The actual setup of the ethertap device is quite simple, just repeat
528 after me:
529
530 @example
531 ifconfig tap@emph{n} hw ether fe:fd:@emph{xx}:@emph{xx}:@emph{xx}:@emph{xx}
532 @end example
533
534 The @emph{n} here is the number of the ethertap device you want to use.
535 It should be the same @emph{n} as the one you use for
536 @file{/dev/tap@emph{n}}.  The @emph{xx}s are four hexadecimal numbers
537 (0--ff). With previous versions of tincd, it didn't matter what they
538 were.  But newer kernels require properly set up ethernet addresses.  In
539 fact, the old behavior was wrong.  It is required that the @emph{xx}s
540 match the numbers of the IP address you will give to the tap device and
541 to the MyOwnVPNIP configuration (which will be discussed later).
542
543 @cindex MAC address
544 @cindex hardware address
545 @strong{Tip}: for finding out what the MAC address of the tap interface
546 should be, you can use the following command:
547
548 @example
549 $ printf 'fe:fd:%02x:%02x:%02x:%02x' 10 1 54 1
550 fe:fd:0a:01:36:01
551 @end example
552
553 @cindex ifconfig
554 To activate the device, you have to assign an IP address to it.  To set
555 an IP address @emph{IP} with network mask @emph{mask}, do the following:
556
557 @example
558 ifconfig tap@emph{n} @emph{xx}.@emph{xx}.@emph{xx}.@emph{xx} netmask @emph{mask}
559 @end example
560
561 @cindex netmask
562 The netmask is the mask of the @emph{entire} VPN network, not just your
563 own subnet.  It is the same netmask you will have to specify with the
564 VpnMask configuration variable.
565
566
567 @c
568 @c
569 @c
570 @c
571 @c         Configuring tinc
572 @c
573 @c
574 @c
575 @c
576
577
578 @c ==================================================================
579 @node    Configuring tinc, Running tinc, Installing tinc - installation, Top
580 @chapter Configuring tinc
581
582 @menu
583 * Multiple networks::           
584 * How connections work::        
585 * Configuration file::          
586 * Example::                     
587 @end menu
588
589 @c ==================================================================
590 @node    Multiple networks, How connections work, Configuring tinc, Configuring tinc
591 @section Multiple networks
592
593 @c from the manpage
594
595 It is perfectly OK for you to run more than one tinc daemon.
596 However, in its default form, you will soon notice that you can't use
597 two different configuration files without the -c option.
598
599 We have thought of another way of dealing with this: network names. This
600 means that you call tincd with the -n argument, which will assign a name
601 to this daemon.
602
603 The effect of this is that the daemon will set its configuration
604 ``root'' to /etc/tinc/nn/, where nn is your argument to the -n
605 option. You'll notice that it appears in syslog as ``tinc.nn''.
606
607 However, it is not strictly necessary that you call tinc with the -n
608 option. In this case, the network name would just be empty, and it will
609 be used as such. tinc now looks for files in /etc/tinc/, instead of
610 /etc/tinc/nn/; the configuration file should be /etc/tinc/tinc.conf,
611 and the passphrases are now expected to be in /etc/tinc/passphrases/.
612
613 But it is highly recommended that you use this feature of tinc, because
614 it will be so much clearer whom your daemon talks to. Hence, we will
615 assume that you use it.
616
617
618 @c ==================================================================
619 @node    How connections work, Configuration file, Multiple networks, Configuring tinc
620 @section How connections work
621
622 Before going on, first a bit on how tinc sees connections.
623
624 When tinc starts up, it reads in the configuration file and parses the
625 command-line options. If it sees a `ConnectTo' value in the file, it
626 will try to connect to it, on the given port. If this fails, tinc exits.
627
628
629 @c ==================================================================
630 @node    Configuration file, Example, How connections work, Configuring tinc
631 @section Configuration file
632
633 The actual configuration of the daemon is done in the file
634 @file{/etc/tinc/nn/tinc.conf}.
635
636 This file consists of comments (lines started with a #) or assignments
637 in the form of
638
639 @example
640 Variable = Value.
641 @end example
642
643 The variable names are case insensitive, and any spaces, tabs, newlines
644 and carriage returns are ignored. Note: it is not required that you put
645 in the `=' sign, but doing so improves readability.  If you leave it
646 out, remember to replace it with at least one space character.
647
648 @menu
649 * Variables::                   
650 @end menu
651
652 @c ==================================================================
653 @node    Variables,  , Configuration file, Configuration file
654 @subsection Variables
655
656 Here are all valid variables, listed in alphabetical order. The default
657 value, required or optional is given between parentheses.
658
659 @c straight from the manpage
660 @table @asis
661 @item ConnectPort = <port> (655)
662 Connect to the upstream host (given with the ConnectTo directive) on
663 port port. port may be given in decimal (default), octal (when preceded
664 by a single zero) or hexadecimal (prefixed with 0x).  port is the port
665 number for both the UDP and the TCP (meta) connections.
666
667 @item ConnectTo = <IP address|hostname> (optional)
668 Specifies which host to connect to on startup. Multiple ConnectTo variables
669 may be specified, if connecting to the first one fails then tinc will try
670 the next one, and so on. It is possible to specify hostnames for dynamic IP
671 addresses (like those given on dyndns.org), tinc will not cache the resolved
672 IP address.
673
674 If you don't specify a host with ConnectTo, regardless of whether a
675 value for ConnectPort is given, tinc won't connect at all, and will
676 instead just listen for incoming connections.
677
678 @item Hostnames = <yes|no> (no)
679 This option selects whether IP addresses (both real and on the VPN) should
680 be resolved. Since DNS lookups are blocking, it might affect tinc's
681 efficiency, even stopping the daemon for a few seconds everytime it does
682 a lookup if your DNS server is not responding.
683
684 This does not affect resolving hostnames to IP addresses from the configuration
685 file.
686
687 @item IndirectData = <yes|no> (no)
688 This option specifies whether other tinc daemons besides the one you
689 specified with ConnectTo can make a direct connection to you. This is
690 especially useful if you are behind a firewall and it is impossible
691 to make a connection from the outside to your tinc daemon. Otherwise,
692 it is best to leave this option out or set it to no.
693
694 @item Interface = <device> (optional)
695 If you have more than one network interface in your computer, tinc will by
696 default listen on all of them for incoming connections. It is possible to
697 bind tinc to a single interface like eth0 or ppp0 with this variable.
698
699 @item InterfaceIP = <local address> (optional)
700 If your computer has more than one IP address on a single interface (for example
701 if you are running virtual hosts), tinc will by default listen on all of them for
702 incoming connections. It is possible to bind tinc to a single IP address with
703 this variable. It is still possible to listen on several interfaces at the same
704 time though, if they share the same IP address.
705
706 @item KeyExpire = <seconds> (3600)
707 This option controls the time the encryption keys used to encrypt the data
708 are valid. It is common practice to change keys at regular intervals to
709 make it even harder for crackers, even though it is thought to be nearly
710 impossible to crack a single key.
711
712 @item ListenPort = <port> (655)
713 Listen on local port port. The computer connecting to this daemon should
714 use this number as the argument for his ConnectPort.
715
716 @item MyOwnVPNIP = <local address[/maskbits]> (required)
717 The local address is the number that the daemon will propagate to
718 other daemons on the network when it is identifying itself. Hence this
719 will be the file name of the passphrase file that the other end expects
720 to find the passphrase in.
721
722 The local address is the IP address of the tap device, not the real IP
723 address of the host running tincd. Due to changes in recent kernels, it
724 is also necessary that you make the ethernet (also known as MAC) address
725 equal to the IP address (see the example).
726
727 maskbits is the number of bits set to 1 in the netmask part.
728
729 @item MyVirtualIP = <local address[/maskbits]>
730 This is an alias for MyOwnVPNIP.
731
732 @item Passphrases = <directory> (/etc/tinc/NETNAME/passphrases)
733 The directory where tinc will look for passphrases when someone tries to
734 connect. Please see the manpage for genauth(8) for more information
735 about passphrases as used by tinc.
736
737 @item PingTimeout = <seconds> (5)
738 The number of seconds of inactivity that tinc will wait before sending a
739 probe to the other end. If that other end doesn't answer within that
740 same amount of seconds, the connection is terminated, and the others
741 will be notified of this.
742
743 @item TapDevice = <device> (/dev/tap0)
744 The ethertap device to use. Note that you can only use one device per
745 daemon. The info pages of the tinc package contain more information
746 about configuring an ethertap device for Linux.
747
748 @item TCPonly = <yes|no> (no, experimental)
749 If this variable is set to yes, then the packets are tunnelled over a TCP
750 connection instead of a UDP connection. This is especially useful for those
751 who want to run a tinc daemon from behind a masquerading firewall, or if
752 UDP packet routing is disabled somehow. This is experimental code,
753 try this at your own risk.
754
755 @item VpnMask = <mask> (optional)
756 The mask that defines the scope of the entire VPN. This option is not used
757 by the tinc daemon itself, but can be used by startup scripts to configure
758 the ethertap devices correctly.
759 @end table
760
761
762
763 @c ==================================================================
764 @node    Example,  , Configuration file, Configuring tinc
765 @section Example
766
767
768 Imagine the following situation. An A-based company wants to connect
769 three branch offices in B, C and D using the internet. All four offices
770 have a 24/7 connection to the internet.
771
772 A is going to serve as the center of the network. B and C will connect
773 to A, and D will connect to C. Each office will be assigned their own IP
774 network, 10.x.0.0.
775
776 @example
777 A: net 10.1.0.0 mask 255.255.0.0 gateway 10.1.54.1 internet IP 1.2.3.4
778 B: net 10.2.0.0 mask 255.255.0.0 gateway 10.2.1.12 internet IP 2.3.4.5
779 C: net 10.3.0.0 mask 255.255.0.0 gateway 10.3.69.254 internet IP 3.4.5.6
780 D: net 10.4.0.0 mask 255.255.0.0 gateway 10.4.3.32 internet IP 4.5.6.7
781 @end example
782
783 ``gateway'' is the VPN IP address of the machine that is running the
784 tincd. ``internet IP'' is the IP address of the firewall, which does not
785 need to run tincd, but it must do a port forwarding of TCP&UDP on port
786 655 (unless otherwise configured).
787
788 In this example, it is assumed that eth0 is the interface that points to
789 the inner LAN of the office, although this could also be the same as the
790 interface that leads to the internet. The configuration of the real
791 interface is also shown as a comment, to give you an idea of how these
792 example host is set up.
793
794 @subsubheading For A
795
796 @emph{A} would be configured like this:
797
798 @example
799 #ifconfig eth0 10.1.54.1 netmask 255.255.0.0 broadcast 10.1.255.255
800 ifconfig tap0 hw ether fe:fd:0a:01:36:01
801 ifconfig tap0 10.1.54.1 netmask 255.0.0.0
802 @end example
803
804 and in /etc/tinc/tinc.conf:
805
806 @example
807 TapDevice = /dev/tap0
808 MyVirtualIP = 10.1.54.1/16
809 VpnMask = 255.0.0.0
810 @end example
811
812 @subsubheading For B
813
814 @example
815 #ifconfig eth0 10.2.43.8 netmask 255.255.0.0 broadcast 10.2.255.255
816 ifconfig tap0 hw ether fe:fd:0a:02:01:0c
817 ifconfig tap0 10.2.1.12 netmask 255.0.0.0
818 @end example
819
820 and in /etc/tinc/tinc.conf:
821
822 @example
823 TapDevice = /dev/tap0
824 MyVirtualIP = 10.2.1.12/16
825 ConnectTo = 1.2.3.4
826 VpnMask = 255.0.0.0
827 @end example
828
829 Note here that the internal address (on eth0) doesn't have to be the
830 same as on the tap0 device. Also, ConnectTo is given so that no-one can
831 connect to this node.
832
833 @subsubheading For C
834
835 @example
836 #ifconfig eth0 10.3.69.254 netmask 255.255.0.0 broadcast 10.3.255.255
837 ifconfig tap0 hw ether fe:fd:0a:03:45:fe
838 ifconfig tap0 10.3.69.254 netmask 255.0.0.0
839 @end example
840
841 and in /etc/tinc/A/tinc.conf:
842
843 @example
844 MyVirtualIP = 10.3.69.254/16
845 TapDevice = /dev/tap1
846 ConnectTo = 1.2.3.4
847 ListenPort = 2000
848 VpnMask = 255.0.0.0
849 @end example
850
851 C already has another daemon that runs on port 655, so they have to
852 reserve another port for tinc. It can connect to other tinc daemons on
853 the regular port though, so no ConnectPort variable is needed.
854 They also use the netname to distinguish
855 between the two. tinc is started with `tincd -n A'.
856
857 @subsubheading For D
858
859 @example
860 #ifconfig tap0 10.4.3.32 netmask 255.255.0.0 broadcast 10.4.255.255
861 ifconfig tap0 hw ether fe:fd:0a:04:03:20
862 ifconfig tap0 10.4.3.32 netmask 255.0.0.0
863 @end example
864
865 and in /etc/tinc/tinc.conf:
866
867 @example
868 MyVirtualIP = 10.4.3.32/16
869 ConnectTo = 3.4.5.6
870 ConnectPort = 2000
871 VpnMask=255.0.0.0
872 @end example
873
874 D will be connecting to C, which has a tincd running for this network on
875 port 2000. Hence they need to put in a ConnectPort, but it doesn't need
876 to have a different ListenPort.
877
878 @subsubheading Authentication
879
880 A, B, C and D all generate a passphrase with genauth 2048, the output is
881 stored in /etc/tinc/passphrases/local, except for C, where it should be
882 /etc/tinc/A/passphrases/local.
883
884 A stores a copy of B's passphrase in /etc/tinc/passphrases/10.2.1.12
885
886 A stores a copy of C's passphrase in /etc/tinc/passphrases/10.3.69.254
887
888 B stores a copy of A's passphrase in /etc/tinc/passphrases/10.1.54.1
889
890 C stores a copy of A's passphrase in /etc/tinc/A/passphrases/10.1.54.1
891
892 C stores a copy of D's passphrase in /etc/tinc/A/passphrases/10.4.3.32
893
894 D stores a copy of C's passphrase in /etc/tinc/passphrases/10.3.69.254
895
896 @subsubheading Starting
897
898 A has to start their tincd first. Then come B and C, where C has to
899 provide the option `-n A', because they have more than one tinc
900 network. Finally, D's tincd is started.
901
902
903
904 @c ==================================================================
905 @node    Running tinc, Technical information, Configuring tinc, Top
906 @chapter Running tinc
907
908 Running tinc isn't just as easy as typing `tincd' and hoping everything
909 will just work out the way you wanted. Instead, the use of tinc is a
910 project that involves trust relations and more than one computer.
911
912 @menu
913 * Managing keys::               
914 * Runtime options::             
915 @end menu
916
917
918 @c ==================================================================
919 @node    Managing keys, Runtime options, Running tinc, Running tinc
920 @section Managing keys
921
922 Before attempting to start tinc, you have to create passphrases. When
923 tinc tries to make a connection, it exchanges some sensitive
924 data. Before doing so, it likes to know if the other end is
925 trustworthy.
926
927 To do this, both ends must have some knowledge about the other. In the
928 case of tinc this is the authentication passphrase.
929
930 This passphrase is a number, which is chosen at random. This number is
931 then sent to the other computers which want to talk to us directly. To
932 avoid breaking security, this should be done over a known secure channel
933 (such as ssh or similar).
934
935 All passphrases are stored in the passphrases directory, which is
936 normally /etc/tinc/nn/passphrases/, but it may be changed using the
937 `Passphrases' option in the config file.
938
939 To generate a passphrase, run `genauth'. genauth takes one argument,
940 which is the length of the passphrase in bits. The length of the
941 passphrase should be in the range 1024--2048 for a key length of 128
942 bits. genauth creates a random number of the specified length, and puts
943 it to stdout.
944
945 Every computer that wants to participate in the VPN should do this, and
946 store the output in the passphrases directory, in the file @file{local}.
947
948 When every computer has his own local key, it should copy it to the
949 computer that it wants to talk to directly. (i.e. the one it connects to
950 during startup.) This should be done via a secure channel, because it is
951 sensitive information. If this is not done securely, someone might break
952 in on you later on.
953
954 Those non-local passphrase files must have the name of the VPN IP
955 address that they will advertise to you. For instance, if a computer
956 tells us it likes to be 10.1.1.3 with netmask 255.255.0.0, the file
957 should still be called 10.1.1.3, and not 10.1.0.0.
958
959
960 @c ==================================================================
961 @node    Runtime options,  , Managing keys, Running tinc
962 @section Runtime options
963
964 Besides the settings in the configuration file, tinc also accepts some
965 command line options.
966
967 This list is a longer version of that in the manpage. The latter is
968 generated automatically, so may be more up-to-date.
969
970 @c from the manpage
971 @table @asis
972 @item -c, --config=FILE
973 Read configuration options from FILE. The default is
974 @file{/etc/tinc/nn/tinc.conf}.
975
976 @item -d
977 Increase debug level. The higher it gets, the more gets
978 logged. Everything goes via syslog.
979
980 0 is the default, only some basic information connection attempts get
981 logged. Setting it to 1 will log a bit more, still not very
982 disturbing. With two -d's tincd will log protocol information, which can
983 get pretty noisy. Three or more -d's will output every single packet
984 that goes out or comes in, which probably generates more data than the
985 packets themselves.
986
987 @item -k, --kill
988 Attempt to kill a running tincd and exit. A TERM signal (15) gets sent
989 to the daemon that his its PID in /var/run/tinc.nn.pid.
990
991 Because it kills only one tincd, you should use -n here if you use it
992 normally.
993
994 @item -n, --net=NETNAME
995 Connect to net NETNAME. @xref{Multiple networks}.
996
997 @item -t, --timeout=TIMEOUT
998 Seconds to wait before giving a timeout. Should not be set too low,
999 because every time tincd senses a timeout, it disconnects and reconnects
1000 again, which will cause unnecessary network traffic and log messages.
1001
1002 @item --help
1003 Display a short reminder of these runtime options and terminate.
1004
1005 @item --version
1006 Output version information and exit.
1007
1008 @end table
1009
1010
1011 @c ==================================================================
1012 @node    Technical information, About us, Running tinc, Top
1013 @chapter Technical information
1014
1015
1016 @c ==================================================================
1017 @menu
1018 * The Connection::              
1019 * Security::                    
1020 @end menu
1021
1022 @node    The Connection, Security, Technical information, Technical information
1023 @section The basic philosophy of the way tinc works
1024 @cindex Connection
1025
1026 tinc is a daemon that takes VPN data and transmit that to another host
1027 computer over the existing Internet infrastructure.
1028
1029 @menu
1030 * Protocol Preview::            
1031 * The Meta-connection::         
1032 @end menu
1033
1034
1035 @c ==================================================================
1036 @node    Protocol Preview, The Meta-connection, The Connection, The Connection
1037 @subsection A preview of the way the tinc works
1038
1039 @cindex ethertap
1040 @cindex frame type
1041 The data itself is read from a character device file, the so-called
1042 @emph{ethertap} device. This device is associated with a network
1043 interface. Any data sent to this interface can be read from the device,
1044 and any data written to the device gets sent from the interface. Data to
1045 and from the device is formatted as if it were a normal ethernet card,
1046 so a frame is preceded by two MAC addresses and a @emph{frame type}
1047 field.
1048
1049 So when tinc reads an ethernet frame from the device, it determines its
1050 type. Right now, tinc can only handle Internet Protocol version 4 (IPv4)
1051 frames. Plans to support other protocols are being made. When tinc knows
1052 which type of frame it has read, it can also read the source and
1053 destination address from it.
1054
1055 Now it is time that the frame gets encrypted. Currently the only
1056 encryption algorithm available is blowfish.
1057
1058 @cindex encapsulating
1059 When the encryption is ready, time has come to actually transport the
1060 packet to the destination computer. We do this by sending the packet
1061 over an UDP connection to the destination host. This is called
1062 @emph{encapsulating}, the VPN packet (though now encrypted) is
1063 encapsulated in another IP datagram.
1064
1065 When the destination receives this packet, the same thing happens, only
1066 in reverse. So it does a decrypt on the contents of the UDP datagram,
1067 and it writes the decrypted information to its own ethertap device.
1068
1069
1070 @c ==================================================================
1071 @node    The Meta-connection,  , Protocol Preview, The Connection
1072 @subsection The meta-connection
1073
1074 Having only an UDP connection available is not enough. Though suitable
1075 for transmitting data, we want to be able to reliably send other
1076 information, such as routing and encryption information to somebody.
1077
1078 TCP is a better alternative, because it already contains protection
1079 against information being lost, unlike UDP.
1080
1081 So we establish two connections. One for the encrypted VPN data, and one
1082 for other information, the meta-data. Hence, we call the second
1083 connection the meta-connection. We can now be sure that the
1084 meta-information doesn't get lost on the way to another computer.
1085
1086 @cindex data-protocol
1087 @cindex meta-protocol
1088 Like with any communication, we must have a protocol, so that everybody
1089 knows what everything stands for, an how he should react. Because we
1090 have two connections, we also have two protocols. The protocol used for
1091 the UDP data is the ``data-protocol,'' the other one is the
1092 ``meta-protocol.''
1093
1094 The reason we don't use TCP for both protocols is that UDP is much
1095 better for encapsulation, even while it is less reliable. The real
1096 problem is that when TCP would be used to encapsulate a TCP stream
1097 that's on the private network, for every packet sent there would be
1098 three ACK's sent instead of just one. Furthermore, if there would be
1099 a timeout, both TCP streams would sense the timeout, and both would
1100 start resending packets.
1101
1102 @c ==================================================================
1103 @node    Security,  , The Connection, Technical information
1104 @section About tinc's encryption and other security-related issues.
1105
1106 @cindex tinc
1107 @cindex Cabal
1108 tinc got its name from ``TINC,'' short for @emph{There Is No Cabal}; the
1109 alleged Cabal was/is an organization that was said to keep an eye on the
1110 entire Internet. As this is exactly what you @emph{don't} want, we named
1111 the tinc project after TINC.
1112
1113 @cindex SVPN
1114 But in order to be ``immune'' to eavesdropping, you'll have to encrypt
1115 your data. Because tinc is a @emph{Secure} VPN (SVPN) daemon, it does
1116 exactly that: encrypt.
1117
1118 This chapter is a mixture of ideas, reasoning and explanation, please
1119 don't take it too serious.
1120
1121 @menu
1122 * Key Types::                   
1123 * Key Management::              
1124 * Authentication::              
1125 * Protection::                  
1126 @end menu
1127
1128 @c ==================================================================
1129 @node    Key Types, Key Management, Security, Security
1130 @subsection Key Types
1131 @c FIXME: check if I'm not talking nonsense
1132
1133 There are several types of encryption keys. Tinc uses two of them,
1134 symmetric private keypairs and public/private keypairs.
1135
1136 Public/private keypairs are used in public key cryptography. It enables
1137 someone to send out a public key with which other people can encrypt their
1138 data. The encrypted data now can only be decrypted by the person who has
1139 the private key that matches the public key. So, a public key only allows
1140 @emph{other} people to send encrypted messages to you. This is very useful
1141 in setting up private communications channels. Just send out your public key
1142 and other people can talk to you in a secure way. But how can you know
1143 the other person is who he says he is?
1144
1145 For authentication itself tinc uses symmetric private keypairs, referred
1146 to as a passphrase. The identity of each tinc daemon is defined by it's
1147 passphrase (like you can be identified by your social security number).
1148 Every tinc daemon that is allowed to connect to you has a copy of your
1149 passphrase (hence symmetrical).
1150
1151 It would also be possible to use public/private keypairs for authentication,
1152 so that you could shout out your public key and don't need to keep it
1153 secret (like the passphrase you would have to send to someone else). Also,
1154 no one else has to know a private key from you.
1155 Both forms have their pros and cons, and at the moment tinc just uses passphrases
1156 (which are computationaly more efficient and perhaps in some way more
1157 secure).
1158
1159 @c ==================================================================
1160 @node    Key Management, Authentication, Key Types, Security
1161 @subsection Key Management
1162 @c FIXME change for the current protocol
1163
1164 @cindex Diffie-Hellman
1165 You can't just send a private encryption key to your peer, because
1166 somebody else might already be listening to you. So you'll have to
1167 negotiate over a shared but secret key. One way to do this is by using
1168 the ``Diffie-Hellman key exchange'' protocol
1169 (@uref{http://www.rsa.com/rsalabs/faq/html/3-6-1.html}). The idea is as
1170 follows.
1171
1172 You have two participants A and B that want to agree over a shared
1173 secret encryption key. Both parties have some large prime number p and a
1174 generator g. These numbers may be known to the outside world, and hence
1175 may be included in the source distribution.
1176
1177 @cindex secret key
1178 Both parties then generate a secret key. A generates a, and computes g^a
1179 mod p. This is then sent to B; while B computes g^b mod p, and transmits
1180 this to A, b being generated by B. Both a and b must be smaller than
1181 p-1.
1182
1183 Both parties then calculate g^ab mod p = k. k is the new, shared, but
1184 still secret key.
1185
1186 To obtain a key k of a sufficient length (128 bits in our vpnd), p
1187 should be 2^129-1 or more.
1188
1189
1190 @c ==================================================================
1191 @node    Authentication, Protection, Key Management, Security
1192 @subsection Authentication
1193 @c FIXME: recheck
1194
1195 @cindex man-in-the-middle attack
1196 Because the Diffie-Hellman protocol is in itself vulnerable to the
1197 ``man-in-the-middle attack,'' we should introduce an authentication
1198 system.
1199
1200 We will let A transmit a passphrase that is also known to B encrypted
1201 with g^a, before A sends this to B. This way, B can check whether A is
1202 really A or just someone else.
1203 B will never receive the real passphrase though, because it was
1204 encrypted using public/private keypairs. This way there is no way an
1205 imposter could steal A's passphrase.
1206
1207 @cindex passphrase
1208 @c ehrmz... but we only use 1024 bits passphrases ourselves? [guus]
1209 This passphrase should be 2304 bits for a symmetric encryption
1210 system. But since an asymmetric system is more secure, we could do with
1211 2048 bits. This only holds if the passphrase is very random. 
1212
1213 These passphrases could be stored in a file that is non-readable by
1214 anyone else but root; e.g. @file{/etc/tinc/passphrases} with UID 0
1215 and permissions mode 700.
1216
1217 The only thing that needs to be taken care of is how A can securely send
1218 a copy of it's passphrase to B if B doesn't have it yet. This could be
1219 done via mail with PGP, but you should be really convinced of the
1220 identity of the person who owns the email address you are sending this to.
1221 Swapping floppy disks in real life might be the best way to do this!
1222
1223
1224 @c ==================================================================
1225 @node    Protection,  , Authentication, Security
1226 @subsection Protecting your data
1227
1228 Now we have securely hidden our data. But a malicious cracker may still
1229 bother you by randomly altering the encrypted data he intercepts.
1230
1231 @c FIXME what the hell is this all about? remove? IT
1232
1233 @c ==================================================================
1234 @node    About us, Concept Index, Technical information, Top
1235 @chapter About us
1236
1237
1238 @menu
1239 * Contact Information::         
1240 * Authors::                     
1241 @end menu
1242
1243
1244 @c ==================================================================
1245 @node    Contact Information, Authors, About us, About us
1246 @section Contact information
1247
1248 tinc's main page is at @url{http://tinc.nl.linux.org/},
1249 this server is located in the Netherlands.
1250
1251 We have an IRC channel on the Open Projects IRC network. Connect to
1252 @uref{http://openprojects.nu/services/irc.html, irc.openprojects.net},
1253 and join channel #tinc.
1254
1255
1256 @c ==================================================================
1257 @node    Authors,  , Contact Information, About us
1258 @section Authors
1259
1260 @table @asis
1261 @item Ivo Timmermans (zarq) (@email{itimmermans@@bigfoot.com})
1262 Main coder/hacker and maintainer of the package.
1263
1264 @item Guus Sliepen (guus)
1265 Originator of it all, co-author.
1266
1267 @item Wessel Dankers (Ubiq)
1268 General obfuscater of the code.
1269
1270 @end table
1271
1272 Thank you's to: Dekan, Emphyrio, vDong
1273
1274 Greetings to: braque, Fluor, giggles, macro, smoke, tribbel
1275
1276
1277 @c ==================================================================
1278 @node    Concept Index,  , About us, Top
1279 @c        node-name,    next, previous,        up
1280 @unnumbered Concept Index
1281
1282 @c ==================================================================
1283 @printindex cp
1284
1285
1286 @c ==================================================================
1287 @contents
1288 @bye
1289