forked from gsliepen/tinc
-
Notifications
You must be signed in to change notification settings - Fork 0
/
tinc.texi
3651 lines (2849 loc) · 139 KB
/
tinc.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename tinc.info
@settitle tinc Manual
@setchapternewpage odd
@c %**end of header
@include tincinclude.texi
@ifinfo
@dircategory Networking tools
@direntry
* tinc: (tinc). The tinc Manual.
@end direntry
This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
Copyright @copyright{} 1998-2021 Ivo Timmermans,
Guus Sliepen <guus@@tinc-vpn.org> and
Wessel Dankers <wsl@@tinc-vpn.org>.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
@end ifinfo
@afourpaper
@paragraphindent none
@finalout
@titlepage
@title tinc Manual
@subtitle Setting up a Virtual Private Network with tinc
@author Ivo Timmermans and Guus Sliepen
@page
@vskip 0pt plus 1filll
This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
Copyright @copyright{} 1998-2021 Ivo Timmermans,
Guus Sliepen <guus@@tinc-vpn.org> and
Wessel Dankers <wsl@@tinc-vpn.org>.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
@end titlepage
@ifnottex
@c ==================================================================
@node Top
@top Top
@menu
* Introduction::
* Preparations::
* Installation::
* Configuration::
* Running tinc::
* Controlling tinc::
* Invitations::
* Technical information::
* Platform specific information::
* About us::
* Concept Index:: All used terms explained
@end menu
@end ifnottex
@c ==================================================================
@node Introduction
@chapter Introduction
@cindex tinc
Tinc is a Virtual Private Network (VPN) daemon that uses tunneling and
encryption to create a secure private network between hosts on the
Internet.
Because the tunnel appears to the IP level network code as a normal
network device, there is no need to adapt any existing software.
The encrypted tunnels allows VPN sites to share information with each other
over the Internet without exposing any information to others.
This document is the manual for tinc. Included are chapters on how to
configure your computer to use tinc, as well as the configuration
process of tinc itself.
@menu
* Virtual Private Networks::
* tinc:: About tinc
* Supported platforms::
@end menu
@c ==================================================================
@node Virtual Private Networks
@section Virtual Private Networks
@cindex VPN
A Virtual Private Network or VPN is a network that can only be accessed
by a few elected computers that participate. This goal is achievable in
more than just one way.
@cindex private
Private networks can consist of a single stand-alone Ethernet LAN. Or
even two computers hooked up using a null-modem cable. In these cases,
it is
obvious that the network is @emph{private}, no one can access it from the
outside. But if your computers are linked to the Internet, the network
is not private anymore, unless one uses firewalls to block all private
traffic. But then, there is no way to send private data to trusted
computers on the other end of the Internet.
@cindex virtual
This problem can be solved by using @emph{virtual} networks. Virtual
networks can live on top of other networks, but they use encapsulation to
keep using their private address space so they do not interfere with
the Internet. Mostly, virtual networks appear like a single LAN, even though
they can span the entire world. But virtual networks can't be secured
by using firewalls, because the traffic that flows through it has to go
through the Internet, where other people can look at it.
As is the case with either type of VPN, anybody could eavesdrop. Or
worse, alter data. Hence it's probably advisable to encrypt the data
that flows over the network.
When one introduces encryption, we can form a true VPN. Other people may
see encrypted traffic, but if they don't know how to decipher it (they
need to know the key for that), they cannot read the information that flows
through the VPN. This is what tinc was made for.
@c ==================================================================
@node tinc
@section tinc
@cindex vpnd
I really don't quite remember what got us started, but it must have been
Guus' idea. He wrote a simple implementation (about 50 lines of C) that
used the ethertap device that Linux knows of since somewhere
about kernel 2.1.60. It didn't work immediately and he improved it a
bit. At this stage, the project was still simply called "vpnd".
Since then, a lot has changed---to say the least.
@cindex tincd
Tinc now supports encryption, it consists of a single daemon (tincd) for
both the receiving and sending end, it has become largely
runtime-configurable---in short, it has become a full-fledged
professional package.
@cindex traditional VPNs
@cindex scalability
Tinc also allows more than two sites to connect to each other and form a single VPN.
Traditionally VPNs are created by making tunnels, which only have two endpoints.
Larger VPNs with more sites are created by adding more tunnels.
Tinc takes another approach: only endpoints are specified,
the software itself will take care of creating the tunnels.
This allows for easier configuration and improved scalability.
A lot can---and will be---changed. We have a number of things that we would like to
see in the future releases of tinc. Not everything will be available in
the near future. Our first objective is to make tinc work perfectly as
it stands, and then add more advanced features.
Meanwhile, we're always open-minded towards new ideas. And we're
available too.
@c ==================================================================
@node Supported platforms
@section Supported platforms
@cindex platforms
Tinc has been verified to work under Linux, FreeBSD, OpenBSD, NetBSD, MacOS/X (Darwin), Solaris, and Windows,
with various hardware architectures. These are some of the platforms
that are supported by the universal tun/tap device driver or other virtual network device drivers.
Without such a driver, tinc will most
likely compile and run, but it will not be able to send or receive data
packets.
@cindex release
For an up to date list of supported platforms, please check the list on
our website:
@uref{https://www.tinc-vpn.org/platforms/}.
@c
@c
@c
@c
@c
@c
@c Preparing your system
@c
@c
@c
@c
@c
@c ==================================================================
@node Preparations
@chapter Preparations
This chapter contains information on how to prepare your system to
support tinc.
@menu
* Configuring the kernel::
* Libraries::
@end menu
@c ==================================================================
@node Configuring the kernel
@section Configuring the kernel
@menu
* Configuration of Linux kernels::
* Configuration of FreeBSD kernels::
* Configuration of OpenBSD kernels::
* Configuration of NetBSD kernels::
* Configuration of Solaris kernels::
* Configuration of Darwin (MacOS/X) kernels::
* Configuration of Windows::
@end menu
@c ==================================================================
@node Configuration of Linux kernels
@subsection Configuration of Linux kernels
@cindex Universal tun/tap
For tinc to work, you need a kernel that supports the Universal tun/tap device.
Most distributions come with kernels that already support this.
Here are the options you have to turn on when configuring a new kernel:
@example
Code maturity level options
[*] Prompt for development and/or incomplete code/drivers
Network device support
<M> Universal tun/tap device driver support
@end example
It's not necessary to compile this driver as a module, even if you are going to
run more than one instance of tinc.
If you decide to build the tun/tap driver as a kernel module, add these lines
to @file{/etc/modules.conf}:
@example
alias char-major-10-200 tun
@end example
@c ==================================================================
@node Configuration of FreeBSD kernels
@subsection Configuration of FreeBSD kernels
For FreeBSD version 4.1 and higher, tun and tap drivers are included in the default kernel configuration.
The tap driver can be loaded with @command{kldload if_tap}, or by adding @samp{if_tap_load="YES"} to @file{/boot/loader.conf}.
@c ==================================================================
@node Configuration of OpenBSD kernels
@subsection Configuration of OpenBSD kernels
Recent versions of OpenBSD come with both tun and tap devices enabled in the default kernel configuration.
@c ==================================================================
@node Configuration of NetBSD kernels
@subsection Configuration of NetBSD kernels
For NetBSD version 1.5.2 and higher,
the tun driver is included in the default kernel configuration.
Tunneling IPv6 may not work on NetBSD's tun device.
@c ==================================================================
@node Configuration of Solaris kernels
@subsection Configuration of Solaris kernels
For Solaris 8 (SunOS 5.8) and higher,
the tun driver may or may not be included in the default kernel configuration.
If it isn't, the source can be downloaded from @uref{http:https://vtun.sourceforge.net/tun/}.
For x86 and sparc64 architectures, precompiled versions can be found at @uref{https://www.monkey.org/~dugsong/fragroute/}.
If the @file{net/if_tun.h} header file is missing, install it from the source package.
@c ==================================================================
@node Configuration of Darwin (MacOS/X) kernels
@subsection Configuration of Darwin (MacOS/X) kernels
Tinc on Darwin relies on a tunnel driver for its data acquisition from the kernel.
OS X version 10.6.8 and later have a built-in tun driver called "utun".
Tinc also supports the driver from @uref{http:https://tuntaposx.sourceforge.net/},
which supports both tun and tap style devices,
By default, tinc expects the tuntaposx driver to be installed.
To use the utun driver, set add @samp{Device = utunX} to @file{tinc.conf},
where X is the desired number for the utun interface.
You can also omit the number, in which case the first free number will be chosen.
@c ==================================================================
@node Configuration of Windows
@subsection Configuration of Windows
You will need to install the latest TAP-Win32 driver from OpenVPN.
You can download it from @uref{https://openvpn.net/index.php/open-source/downloads.html}.
Using the Network Connections control panel,
configure the TAP-Win32 network interface in the same way as you would do from the tinc-up script,
as explained in the rest of the documentation.
@c ==================================================================
@node Libraries
@section Libraries
@cindex requirements
@cindex libraries
Before you can configure or build tinc, you need to have the LibreSSL or OpenSSL, zlib,
LZO, curses and readline libraries installed on your system. If you try to
configure tinc without having them installed, configure will give you an error
message, and stop.
@menu
* LibreSSL/OpenSSL::
* zlib::
* LZO::
* LZ4::
* libcurses::
* libreadline::
@end menu
@c ==================================================================
@node LibreSSL/OpenSSL
@subsection LibreSSL/OpenSSL
@cindex LibreSSL
@cindex OpenSSL
For all cryptography-related functions, tinc uses the functions provided
by the LibreSSL or the OpenSSL library.
If this library is not installed, you will get an error when configuring
tinc for build. Support for running tinc with other cryptographic libraries
installed @emph{may} be added in the future.
You can use your operating system's package manager to install this if
available. Make sure you install the development AND runtime versions
of this package.
If your operating system comes neither with LibreSSL or OpenSSL, you have to
install one manually. It is recommended that you get the latest version of
LibreSSL from @url{https://www.libressl.org/}. Instructions on how to
configure, build and install this package are included within the package.
Please make sure you build development and runtime libraries (which is the
default).
If you installed the LibreSSL or OpenSSL libraries from source, it may be necessary
to let configure know where they are, by passing configure one of the
--with-openssl-* parameters. Note that you even have to use --with-openssl-* if you
are using LibreSSL.
@example
--with-openssl=DIR LibreSSL/OpenSSL library and headers prefix
--with-openssl-include=DIR LibreSSL/OpenSSL headers directory
(Default is OPENSSL_DIR/include)
--with-openssl-lib=DIR LibreSSL/OpenSSL library directory
(Default is OPENSSL_DIR/lib)
@end example
@subsubheading License
@cindex license
The complete source code of tinc is covered by the GNU GPL version 2.
Since the license under which OpenSSL is distributed is not directly
compatible with the terms of the GNU GPL
@uref{https://www.openssl.org/support/faq.html#LEGAL2}, we
include an exemption to the GPL (see also the file COPYING.README) to allow
everyone to create a statically or dynamically linked executable:
@quotation
This program is released under the GPL with the additional exemption
that compiling, linking, and/or using OpenSSL is allowed. You may
provide binary packages linked to the OpenSSL libraries, provided that
all other requirements of the GPL are met.
@end quotation
Since the LZO library used by tinc is also covered by the GPL,
we also present the following exemption:
@quotation
Hereby I grant a special exception to the tinc VPN project
(https://www.tinc-vpn.org/) to link the LZO library with the OpenSSL library
(https://www.openssl.org).
Markus F.X.J. Oberhumer
@end quotation
@c ==================================================================
@node zlib
@subsection zlib
@cindex zlib
For the optional compression of UDP packets, tinc uses the functions provided
by the zlib library.
If this library is not installed, you will get an error when running the
configure script. You can either install the zlib library, or disable support
for zlib compression by using the @option{--disable-zlib} option when running the
configure script. Note that if you disable support for zlib, the resulting
binary will not work correctly on VPNs where zlib compression is used.
You can use your operating system's package manager to install this if
available. Make sure you install the development AND runtime versions
of this package.
If you have to install zlib manually, you can get the source code
from @url{https://zlib.net/}. Instructions on how to configure,
build and install this package are included within the package. Please
make sure you build development and runtime libraries (which is the
default).
@c ==================================================================
@node LZO
@subsection LZO
@cindex LZO
Another form of compression is offered using the LZO library.
If this library is not installed, you will get an error when running the
configure script. You can either install the LZO library, or disable support
for LZO compression by using the @option{--disable-lzo} option when running the
configure script. Note that if you disable support for LZO, the resulting
binary will not work correctly on VPNs where LZO compression is used.
You can use your operating system's package manager to install this if
available. Make sure you install the development AND runtime versions
of this package.
If you have to install LZO manually, you can get the source code
from @url{https://www.oberhumer.com/opensource/lzo/}. Instructions on how to configure,
build and install this package are included within the package. Please
make sure you build development and runtime libraries (which is the
default).
@c ==================================================================
@node LZ4
@subsection LZ4
@cindex LZ4
Another form of compression is offered using the LZ4 library.
Tinc has support for the LZ4 compression algorithm as compression level 12.
By default, tinc will try to link to an external LZ4 library. If it is not
found on your system or its version is older than r129, then tinc falls back to
the built-in copy of the library.
You can force the use of the built-in copy by passing `--enable-lz4-builtin`,
or disable it completely with `--disable-lz4-builtin`.
LZ4 support can be completely disabled with `--disable-lz4`. Note that the
resulting binary will not work correctly on VPNs where LZ4 compression is used
by other peers.
@c ==================================================================
@node libcurses
@subsection libcurses
@cindex libcurses
For the @command{tinc top} command, tinc requires a curses library.
If this library is not installed, you will get an error when running the
configure script. You can either install a suitable curses library, or disable
all functionality that depends on a curses library by using the
@option{--disable-curses} option when running the configure script.
There are several curses libraries. It is recommended that you install
"ncurses" (@url{https://invisible-island.net/ncurses/}),
however other curses libraries should also work.
In particular, "PDCurses" (@url{https://pdcurses.sourceforge.io/})
is recommended if you want to compile tinc for Windows.
You can use your operating system's package manager to install this if
available. Make sure you install the development AND runtime versions
of this package.
@c ==================================================================
@node libreadline
@subsection libreadline
@cindex libreadline
For the @command{tinc} command's shell functionality, tinc uses the readline library.
If this library is not installed, you will get an error when running the
configure script. You can either install a suitable readline library, or
disable all functionality that depends on a readline library by using the
@option{--disable-readline} option when running the configure script.
You can use your operating system's package manager to install this if
available. Make sure you install the development AND runtime versions
of this package.
If you have to install libreadline manually, you can get the source code from
@url{https://www.gnu.org/software/readline/}. Instructions on how to configure,
build and install this package are included within the package. Please make
sure you build development and runtime libraries (which is the default).
@c
@c
@c
@c Installing tinc
@c
@c
@c
@c
@c ==================================================================
@node Installation
@chapter Installation
If you use Debian, you may want to install one of the
precompiled packages for your system. These packages are equipped with
system startup scripts and sample configurations.
If you cannot use one of the precompiled packages, or you want to compile tinc
for yourself, you can use the source. The source is distributed under
the GNU General Public License (GPL). Download the source from the
@uref{https://www.tinc-vpn.org/download/, download page}.
Please refer to @file{INSTALL.md} for information on how to build tinc from source.
@menu
* Building and installing tinc::
* System files::
@end menu
@c ==================================================================
@node Building and installing tinc
@section Building and installing tinc
Detailed instructions on configuring the source, building tinc and installing tinc
can be found in the file called @file{INSTALL}.
@cindex binary package
If you happen to have a binary package for tinc for your distribution,
you can use the package management tools of that distribution to install tinc.
The documentation that comes along with your distribution will tell you how to do that.
@menu
* Darwin (MacOS/X) build environment::
* Windows build environment::
@end menu
@c ==================================================================
@node Darwin (MacOS/X) build environment
@subsection Darwin (MacOS/X) build environment
In order to build tinc on Darwin, you need to install Xcode from @uref{https://developer.apple.com/xcode/}.
It might also help to install a recent version of Fink from @uref{http:https://www.finkproject.org/}.
You need to download and install LibreSSL (or OpenSSL) and LZO,
either directly from their websites (see @ref{Libraries}) or using Fink.
@c ==================================================================
@node Windows build environment
@subsection Windows build environment
You will need to install either the native Windows SDK from @uref{https://visualstudio.com},
or the MinGW environment from @uref{https://msys2.org}.
You also need to download and install LibreSSL (or OpenSSL) and LZO.
Whether tinc is compiled using MinGW or the native SDK, it runs natively under Windows,
so it is not necessary to keep either SDK to run the compiled binaries.
When detaching, tinc will install itself as a service,
which will be restarted automatically after reboots.
@c ==================================================================
@node System files
@section System files
Before you can run tinc, you must make sure you have all the needed
files on your system.
@menu
* Device files::
* Other files::
@end menu
@c ==================================================================
@node Device files
@subsection Device files
@cindex device files
Most operating systems nowadays come with the necessary device files by default,
or they have a mechanism to create them on demand.
If you use Linux and do not have udev installed,
you may need to create the following device file if it does not exist:
@example
mknod -m 600 /dev/net/tun c 10 200
@end example
@c ==================================================================
@node Other files
@subsection Other files
@subsubheading @file{/etc/networks}
You may add a line to @file{/etc/networks} so that your VPN will get a
symbolic name. For example:
@example
myvpn 10.0.0.0
@end example
@subsubheading @file{/etc/services}
@cindex port numbers
You may add this line to @file{/etc/services}. The effect is that you
may supply @samp{tinc} as a valid port number to some programs. The
number 655 is registered with the IANA.
@example
tinc 655/tcp TINC
tinc 655/udp TINC
# Ivo Timmermans <ivo@@tinc-vpn.org>
@end example
@c
@c
@c
@c
@c Configuring tinc
@c
@c
@c
@c
@c ==================================================================
@node Configuration
@chapter Configuration
@menu
* Configuration introduction::
* Multiple networks::
* How connections work::
* Configuration files::
* Network interfaces::
* Example configuration::
@end menu
@c ==================================================================
@node Configuration introduction
@section Configuration introduction
Before actually starting to configure tinc and editing files,
make sure you have read this entire section so you know what to expect.
Then, make it clear to yourself how you want to organize your VPN:
What are the nodes (computers running tinc)?
What IP addresses/subnets do they have?
What is the network mask of the entire VPN?
Do you need special firewall rules?
Do you have to set up masquerading or forwarding rules?
Do you want to run tinc in router mode or switch mode?
These questions can only be answered by yourself,
you will not find the answers in this documentation.
Make sure you have an adequate understanding of networks in general.
@cindex Network Administrators Guide
A good resource on networking is the
@uref{https://www.tldp.org/LDP/nag2/, Linux Network Administrators Guide}.
If you have everything clearly pictured in your mind,
proceed in the following order:
First, create the initial configuration files and public/private key pairs using the following command:
@example
tinc -n @var{NETNAME} init @var{NAME}
@end example
Second, use @command{tinc -n @var{NETNAME} add ...} to further configure tinc.
Finally, export your host configuration file using @command{tinc -n @var{NETNAME} export} and send it to those
people or computers you want tinc to connect to.
They should send you their host configuration file back, which you can import using @command{tinc -n @var{NETNAME} import}.
These steps are described in the subsections below.
@c ==================================================================
@node Multiple networks
@section Multiple networks
@cindex multiple networks
@cindex netname
In order to allow you to run more than one tinc daemon on one computer,
for instance if your computer is part of more than one VPN,
you can assign a @var{netname} to your VPN.
It is not required if you only run one tinc daemon,
it doesn't even have to be the same on all the nodes of your VPN,
but it is recommended that you choose one anyway.
We will assume you use a netname throughout this document.
This means that you call tinc with the -n argument,
which will specify the netname.
The effect of this option is that tinc will set its configuration
root to @file{@value{sysconfdir}/tinc/@var{netname}/}, where @var{netname} is your argument to the -n option.
You will also notice that log messages it appears in syslog as coming from @file{tinc.@var{netname}},
and on Linux, unless specified otherwise, the name of the virtual network interface will be the same as the network name.
However, it is not strictly necessary that you call tinc with the -n
option. If you do not use it, the network name will just be empty, and
tinc will look for files in @file{@value{sysconfdir}/tinc/} instead of
@file{@value{sysconfdir}/tinc/@var{netname}/};
the configuration file will then be @file{@value{sysconfdir}/tinc/tinc.conf},
and the host configuration files are expected to be in @file{@value{sysconfdir}/tinc/hosts/}.
@c ==================================================================
@node How connections work
@section How connections work
When tinc starts up, it parses the command-line options and then
reads in the configuration file tinc.conf.
It will then start listening for incoming connection from other daemons,
and will by default also automatically try to connect to known peers.
By default, tinc will try to keep at least 3 working meta-connections alive at all times.
@cindex client
@cindex server
There is no real distinction between a server and a client in tinc.
If you wish, you can view a tinc daemon without a `ConnectTo' statement in tinc.conf and `AutoConnect = no' as a server,
and one which does have one or more `ConnectTo' statements or `Autoconnect = yes' (which is the default) as a client.
It does not matter if two tinc daemons have a `ConnectTo' value pointing to each other however.
Connections specified using `ConnectTo' are so-called meta-connections.
Tinc daemons exchange information about all other daemon they know about via these meta-connections.
After learning about all the daemons in the VPN,
tinc will create other connections as necessary in order to communicate with them.
For example, if there are three daemons named A, B and C, and A has @samp{ConnectTo = B} in its tinc.conf file,
and C has @samp{ConnectTo = B} in its tinc.conf file, then A will learn about C from B,
and will be able to exchange VPN packets with C without the need to have @samp{ConnectTo = C} in its tinc.conf file.
It could be that some daemons are located behind a Network Address Translation (NAT) device, or behind a firewall.
In the above scenario with three daemons, if A and C are behind a NAT,
B will automatically help A and C punch holes through their NAT,
in a way similar to the STUN protocol, so that A and C can still communicate with each other directly.
It is not always possible to do this however, and firewalls might also prevent direct communication.
In that case, VPN packets between A and C will be forwarded by B.
In effect, all nodes in the VPN will be able to talk to each other, as long as
there is a path of meta-connections between them, and whenever possible, two
nodes will communicate with each other directly.
@c ==================================================================
@node Configuration files
@section Configuration files
The actual configuration of the daemon is done in the file
@file{@value{sysconfdir}/tinc/@var{netname}/tinc.conf} and at least one other file in the directory
@file{@value{sysconfdir}/tinc/@var{netname}/hosts/}.
An optional directory @file{@value{sysconfdir}/tinc/@var{netname}/conf.d} can be added from which
any .conf file will be read.
These file consists of comments (lines started with a #) or assignments
in the form of
@example
Variable = Value.
@end example
The variable names are case insensitive, and any spaces, tabs, newlines
and carriage returns are ignored. Note: it is not required that you put
in the `=' sign, but doing so improves readability. If you leave it
out, remember to replace it with at least one space character.
The server configuration is complemented with host specific configuration (see
the next section). Although all host configuration options for the local node
listed in this document can also be put in
@file{@value{sysconfdir}/tinc/@var{netname}/tinc.conf}, it is recommended to
put host specific configuration options in the host configuration file, as this
makes it easy to exchange with other nodes.
You can edit the config file manually, but it is recommended that you use
the tinc command to change configuration variables for you.
In the following two subsections all valid variables are listed in alphabetical order.
The default value is given between parentheses,
other comments are between square brackets.
@menu
* Main configuration variables::
* Host configuration variables::
* Scripts::
* How to configure::
@end menu
@c ==================================================================
@node Main configuration variables
@subsection Main configuration variables
@table @asis
@cindex AddressFamily
@item AddressFamily = <ipv4|ipv6|any> (any)
This option affects the address family of listening and outgoing sockets.
If any is selected, then depending on the operating system
both IPv4 and IPv6 or just IPv6 listening sockets will be created.
@cindex AutoConnect
@item AutoConnect = <yes|no> (yes)
If set to yes, tinc will automatically set up meta connections to other nodes,
without requiring @var{ConnectTo} variables.
@cindex BindToAddress
@item BindToAddress = <@var{address}> [<@var{port}>]
This is the same as ListenAddress, however the address given with the BindToAddress option
will also be used for outgoing connections.
This is useful if your computer has more than one IPv4 or IPv6 address,
and you want tinc to only use a specific one for outgoing packets.
@cindex BindToInterface
@item BindToInterface = <@var{interface}> [experimental]
If you have more than one network interface in your computer, tinc will
by default listen on all of them for incoming connections. It is
possible to bind tinc to a single interface like eth0 or ppp0 with this
variable.
This option may not work on all platforms.
Also, on some platforms it will not actually bind to an interface,
but rather to the address that the interface has at the moment a socket is created.
@cindex Broadcast
@item Broadcast = <no | mst | direct> (mst) [experimental]
This option selects the way broadcast packets are sent to other daemons.
@emph{NOTE: all nodes in a VPN must use the same Broadcast mode, otherwise routing loops can form.}
@table @asis
@item no
Broadcast packets are never sent to other nodes.
@item mst
Broadcast packets are sent and forwarded via the VPN's Minimum Spanning Tree.
This ensures broadcast packets reach all nodes.
@item direct
Broadcast packets are sent directly to all nodes that can be reached directly.
Broadcast packets received from other nodes are never forwarded.
If the IndirectData option is also set, broadcast packets will only be sent to nodes which we have a meta connection to.
@end table
@cindex BroadcastSubnet
@item BroadcastSubnet = @var{address}[/@var{prefixlength}]
Declares a broadcast subnet.
Any packet with a destination address falling into such a subnet will be routed as a broadcast
(provided all nodes have it declared).
This is most useful to declare subnet broadcast addresses (e.g. 10.42.255.255),
otherwise tinc won't know what to do with them.
Note that global broadcast addresses (MAC ff:ff:ff:ff:ff:ff, IPv4 255.255.255.255),
as well as multicast space (IPv4 224.0.0.0/4, IPv6 ff00::/8)
are always considered broadcast addresses and don't need to be declared.
@cindex ConnectTo
@item ConnectTo = <@var{name}>
Specifies which other tinc daemon to connect to on startup.
Multiple ConnectTo variables may be specified,
in which case outgoing connections to each specified tinc daemon are made.
The names should be known to this tinc daemon
(i.e., there should be a host configuration file for the name on the ConnectTo line).
If you don't specify a host with ConnectTo and have disabled AutoConnect,
tinc won't try to connect to other daemons at all,
and will instead just listen for incoming connections.
@cindex DecrementTTL
@item DecrementTTL = <yes | no> (no) [experimental]
When enabled, tinc will decrement the Time To Live field in IPv4 packets, or the Hop Limit field in IPv6 packets,
before forwarding a received packet to the virtual network device or to another node,
and will drop packets that have a TTL value of zero,
in which case it will send an ICMP Time Exceeded packet back.
Do not use this option if you use switch mode and want to use IPv6.
@cindex Device
@item Device = <@var{device}> (@file{/dev/tap0}, @file{/dev/net/tun} or other depending on platform)
The virtual network device to use.
Tinc will automatically detect what kind of device it is.
Note that you can only use one device per daemon.
Under Windows, use @var{Interface} instead of @var{Device}.
Note that you can only use one device per daemon.
See also @ref{Device files}.
@cindex DeviceStandby
@item DeviceStandby = <yes | no> (no)
When disabled, tinc calls @file{tinc-up} on startup, and @file{tinc-down} on shutdown.
When enabled, tinc will only call @file{tinc-up} when at least one node is reachable,
and will call @file{tinc-down} as soon as no nodes are reachable.
On Windows, this also determines when the virtual network interface "cable" is "plugged".
@cindex DeviceType
@item DeviceType = <@var{type}> (platform dependent)
The type of the virtual network device.
Tinc will normally automatically select the right type of tun/tap interface, and this option should not be used.
However, this option can be used to select one of the special interface types, if support for them is compiled in.
@table @asis
@cindex dummy
@item dummy
Use a dummy interface.
No packets are ever read or written to a virtual network device.
Useful for testing, or when setting up a node that only forwards packets for other nodes.
@cindex raw_socket
@item raw_socket
Open a raw socket, and bind it to a pre-existing
@var{Interface} (eth0 by default).
All packets are read from this interface.
Packets received for the local node are written to the raw socket.
However, at least on Linux, the operating system does not process IP packets destined for the local host.
@cindex multicast
@item multicast
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}.
Packets are read from and written to this multicast socket.
This can be used to connect to UML, QEMU or KVM instances listening on the same multicast address.
Do NOT connect multiple tinc daemons to the same multicast address, this will very likely cause routing loops.
Also note that this can cause decrypted VPN packets to be sent out on a real network if misconfigured.
@cindex fd
@item fd
Use a file descriptor, given directly as an integer or passed through a unix domain socket.
On Linux, an abstract socket address can be specified by using @samp{@@} as a prefix.
All packets are read from this interface.
Packets received for the local node are written to it.
@cindex UML
@item uml (not compiled in by default)
Create a UNIX socket with the filename specified by
@var{Device}, or @file{@value{runstatedir}/@var{netname}.umlsocket}
if not specified.
Tinc will wait for a User Mode Linux instance to connect to this socket.
@cindex VDE
@item vde (not compiled in by default)
Uses the libvdeplug library to connect to a Virtual Distributed Ethernet switch,
using the UNIX socket specified by
@var{Device}, or @file{@value{runstatedir}/vde.ctl}
if not specified.
@end table
Also, in case tinc does not seem to correctly interpret packets received from the virtual network device,
it can be used to change the way packets are interpreted:
@table @asis
@item tun (BSD and Linux)
Set type to tun.
Depending on the platform, this can either be with or without an address family header (see below).
@cindex tunnohead
@item tunnohead (BSD)
Set type to tun without an address family header.
Tinc will expect packets read from the virtual network device to start with an IP header.
On some platforms IPv6 packets cannot be read from or written to the device in this mode.
@cindex tunifhead
@item tunifhead (BSD)
Set type to tun with an address family header.