1TINC.CONF(5) BSD File Formats Manual TINC.CONF(5)
3
5 tinc.conf — tinc daemon configuration
6
9 The files in the /etc/tinc/ directory contain runtime and security infor‐
10 mation for the tinc daemon.
11
14 It is perfectly ok for you to run more than one tinc daemon. However, in
15 its default form, you will soon notice that you can't use two different
16 configuration files without the -c option.
17 We have thought of another way of dealing with this: network names. This
20 means that you call tinc.conf with the -n option, which will assign a
21 name to this daemon.
22 The effect of this is that the daemon will set its configuration root to
25 /etc/tinc/NETNAME/, where NETNAME is your argument to the -n option.
26 You'll notice that messages appear in syslog as coming from
27 tincd.NETNAME.
28 However, it is not strictly necessary that you call tinc with the -n
31 option. In this case, the network name would just be empty, and it will
32 be used as such. tinc now looks for files in /etc/tinc/, instead of
33 /etc/tinc/NETNAME/; the configuration file should be /etc/tinc/tinc.conf,
34 and the host configuration files are now expected to be in
35 /etc/tinc/hosts/.
36 But it is highly recommended that you use this feature of tinc, because
39 it will be so much clearer whom your daemon talks to. Hence, we will
40 assume that you use it.
41
44 Each tinc daemon should have a name that is unique in the network which
45 it will be part of. The name will be used by other tinc daemons for
46 identification. The name has to be declared in the
47 /etc/tinc/NETNAME/tinc.conf file.
48 To make things easy, choose something that will give unique and easy to
51 remember names to your tinc daemon(s). You could try things like host‐
52 names, owner surnames or location names.
53
56 You should use tincd -K to generate public/private keypairs. It will
57 generate two keys. The private key should be stored in a separate file
58 /etc/tinc/NETNAME/rsa_key.priv -- where NETNAME stands for the network
59 (see NETWORKS) above. The public key should be stored in the host con‐
60 figuration file /etc/tinc/NETNAME/hosts/NAME -- where NAME stands for the
61 name of the local tinc daemon (see NAMES).
62
65 The server configuration of the daemon is done in the file
66 /etc/tinc/NETNAME/tinc.conf. This file consists of comments (lines
67 started with a #) or assignments in the form of:
68 Variable = Value.
71 The variable names are case insensitive, and any spaces, tabs, newlines
74 and carriage returns are ignored. Note: it is not required that you put
75 in the = sign, but doing so improves readability. If you leave it out,
76 remember to replace it with at least one space character.
77 The server configuration is complemented with host specific configuration
80 (see the next section). Although all configuration options for the local
81 host listed in this document can also be put in
82 /etc/tinc/NETNAME/tinc.conf, it is recommended to put host specific con‐
83 figuration options in the host configuration file, as this makes it easy
84 to exchange with other nodes.
85 Here are all valid variables, listed in alphabetical order. The default
88 value is given between parentheses.
89 AddressFamily = ipv4 | ipv6 | any (any)
92 This option affects the address family of listening and outgoing
93 sockets. If "any" is selected, then depending on the operating
94 system both IPv4 and IPv6 or just IPv6 listening sockets will be
95 created.
96 BindToAddress = address [experimental]
99 If your computer has more than one IPv4 or IPv6 address, tinc
100 will by default listen on all of them for incoming connections.
101 It is possible to bind only to a single address with this vari‐
102 able.
103 This option may not work on all platforms.
106 BindToInterface = interface [experimental]
109 If your computer has more than one network interface, tinc will
110 by default listen on all of them for incoming connections. It is
111 possible to bind only to a single interface with this variable.
112 This option may not work on all platforms.
115 ConnectTo = name
118 Specifies which other tinc daemon to connect to on startup. Mul‐
119 tiple ConnectTo variables may be specified, in which case outgo‐
120 ing connections to each specified tinc daemon are made. The
121 names should be known to this tinc daemon (i.e., there should be
122 a host configuration file for the name on the ConnectTo line).
123 If you don't specify a host with ConnectTo, tinc won't try to
126 connect to other daemons at all, and will instead just listen for
127 incoming connections.
128 Device = device (/dev/tap0, /dev/net/tun or other depending on platform)
131 The virtual network device to use. tinc will automatically
132 detect what kind of device it is. Note that you can only use one
133 device per daemon. Under Windows, use Interface instead of
134 Device. The info pages of the tinc package contain more informa‐
135 tion about configuring the virtual network device.
136 DeviceType = tun | tunnohead | tunifhead | tap (only supported on BSD
139 platforms)
140 The type of the virtual network device. Tinc will normally auto‐
141 matically select the right type, and this option should not be
142 used. However, in case tinc does not seem to correctly interpret
143 packets received from the virtual network device, using this
144 option might help.
145 tun Set type to tun. Depending on the platform, this can
148 either be with or without an address family header (see
149 below).
150 tunnohead
153 Set type to tun without an address family header. Tinc
154 will expect packets read from the virtual network device
155 to start with an IP header. On some platforms IPv6 pack‐
156 ets cannot be read from or written to the device in this
157 mode.
158 tunifhead
161 Set type to tun with an address family header. Tinc will
162 expect packets read from the virtual network device to
163 start with a four byte header containing the address fam‐
164 ily, followed by an IP header. This mode should support
165 both IPv4 and IPv6 packets.
166 tap Set type to tap. Tinc will expect packets read from the
169 virtual network device to start with an Ethernet header.
170 DirectOnly = yes | no (no) [experimental]
173 When this option is enabled, packets that cannot be sent directly
174 to the destination node, but which would have to be forwarded by
175 an intermediate node, are dropped instead. When combined with
176 the IndirectData option, packets for nodes for which we do not
177 have a meta connection with are also dropped.
178 Forwarding = off | internal | kernel (internal) [experimental]
181 This option selects the way indirect packets are forwarded.
182 off Incoming packets that are not meant for the local node,
185 but which should be forwarded to another node, are
186 dropped.
187 internal
190 Incoming packets that are meant for another node are for‐
191 warded by tinc internally.
192 This is the default mode, and unless you really know you
195 need another forwarding mode, don't change it.
196 kernel Incoming packets are always sent to the TUN/TAP device,
199 even if the packets are not for the local node. This is
200 less efficient, but allows the kernel to apply its rout‐
201 ing and firewall rules on them, and can also help debug‐
202 ging.
203 GraphDumpFile = filename [experimental]
206 If this option is present, tinc will dump the current network
207 graph to the file filename every minute, unless there were no
208 changes to the graph. The file is in a format that can be read
209 by graphviz tools. If filename starts with a pipe symbol |, then
210 the rest of the filename is interpreted as a shell command that
211 is executed, the graph is then sent to stdin.
212 Hostnames = yes | no (no)
215 This option selects whether IP addresses (both real and on the
216 VPN) should be resolved. Since DNS lookups are blocking, it might
217 affect tinc's efficiency, even stopping the daemon for a few sec‐
218 onds every time it does a lookup if your DNS server is not
219 responding.
220 This does not affect resolving hostnames to IP addresses from the
223 host configuration files.
224 IffOneQueue = yes | no (no) [experimental]
227 (Linux only) Set IFF_ONE_QUEUE flag on TUN/TAP devices.
228 Interface = interface
231 Defines the name of the interface corresponding to the virtual
232 network device. Depending on the operating system and the type
233 of device this may or may not actually set the name of the inter‐
234 face. Under Windows, this variable is used to select which net‐
235 work interface will be used. If you specified a Device, this
236 variable is almost always already correctly set.
237 KeyExpire = seconds (3600)
240 This option controls the period the encryption keys used to
241 encrypt the data are valid. It is common practice to change keys
242 at regular intervals to make it even harder for crackers, even
243 though it is thought to be nearly impossible to crack a single
244 key.
245 MACExpire = seconds (600)
248 This option controls the amount of time MAC addresses are kept
249 before they are removed. This only has effect when Mode is set
250 to "switch".
251 MaxTimeout = seconds (900)
254 This is the maximum delay before trying to reconnect to other
255 tinc daemons.
256 Mode = router | switch | hub (router)
259 This option selects the way packets are routed to other daemons.
260 router In this mode Subnet variables in the host configuration
263 files will be used to form a routing table. Only unicast
264 packets of routable protocols (IPv4 and IPv6) are sup‐
265 ported in this mode.
266 This is the default mode, and unless you really know you
269 need another mode, don't change it.
270 switch In this mode the MAC addresses of the packets on the VPN
273 will be used to dynamically create a routing table just
274 like an Ethernet switch does. Unicast, multicast and
275 broadcast packets of every protocol that runs over Ether‐
276 net are supported in this mode at the cost of frequent
277 broadcast ARP requests and routing table updates.
278 This mode is primarily useful if you want to bridge Eth‐
281 ernet segments.
282 hub This mode is almost the same as the switch mode, but
285 instead every packet will be broadcast to the other dae‐
286 mons while no routing table is managed.
287 Name = name [required]
290 This is the name which identifies this tinc daemon. It must be
291 unique for the virtual private network this daemon will connect
292 to.
293 PingInterval = seconds (60)
296 The number of seconds of inactivity that tinc will wait before
297 sending a probe to the other end.
298 PingTimeout = seconds (5)
301 The number of seconds to wait for a response to pings or to allow
302 meta connections to block. If the other end doesn't respond
303 within this time, the connection is terminated, and the others
304 will be notified of this.
305 PriorityInheritance = yes | no (no) [experimental]
308 When this option is enabled the value of the TOS field of tun‐
309 neled IPv4 packets will be inherited by the UDP packets that are
310 sent out.
311 PrivateKey = key [obsolete]
314 The private RSA key of this tinc daemon. It will allow this tinc
315 daemon to authenticate itself to other daemons.
316 PrivateKeyFile = filename (/etc/tinc/NETNAME/rsa_key.priv)
319 The file in which the private RSA key of this tinc daemon
320 resides. Note that there must be exactly one of PrivateKey or
321 PrivateKeyFile specified in the configuration file.
322 ProcessPriority = low | normal | high
325 When this option is used the priority of the tincd process will
326 be adjusted. Increasing the priority may help to reduce latency
327 and packet loss on the VPN.
328 ReplayWindow = bytes (16)
331 This is the size of the replay tracking window for each remote
332 node, in bytes. The window is a bitfield which tracks 1 packet
333 per bit, so for example the default setting of 16 will track up
334 to 128 packets in the window. In high bandwidth scenarios, set‐
335 ting this to a higher value can reduce packet loss from the
336 interaction of replay tracking with underlying real packet loss
337 and/or reordering. Setting this to zero will disable replay
338 tracking completely and pass all traffic, but leaves tinc vulner‐
339 able to replay-based attacks on your traffic.
340 StrictSubnets = yes | no (no) [experimental]
343 When this option is enabled tinc will only use Subnet statements
344 which are present in the host config files in the local
345 /etc/tinc/NETNAME/hosts/ directory.
346 TunnelServer = yes | no (no) [experimental]
349 When this option is enabled tinc will no longer forward informa‐
350 tion between other tinc daemons, and will only allow connections
351 with nodes for which host config files are present in the local
352 /etc/tinc/NETNAME/hosts/ directory. Setting this options also
353 implicitly sets StrictSubnets.
354 UDPRcvBuf = bytes (OS default)
357 Sets the socket receive buffer size for the UDP socket, in bytes.
358 If unset, the default buffer size will be used by the operating
359 system.
360 UDPSndBuf = bytes (OS default)
363 Sets the socket send buffer size for the UDP socket, in bytes.
364 If unset, the default buffer size will be used by the operating
365 system.
366
369 The host configuration files contain all information needed to establish
370 a connection to those hosts. A host configuration file is also required
371 for the local tinc daemon, it will use it to read in it's listen port,
372 public key and subnets.
373 The idea is that these files are portable. You can safely mail your own
376 host configuration file to someone else. That other person can then copy
377 it to his own hosts directory, and now his tinc daemon will be able to
378 connect to your tinc daemon. Since host configuration files only contain
379 public keys, no secrets are revealed by sending out this information.
380 Address = address [port] [recommended]
383 The IP address or hostname of this tinc daemon on the real net‐
384 work. This will only be used when trying to make an outgoing
385 connection to this tinc daemon. Optionally, a port can be speci‐
386 fied to use for this address. Multiple Address variables can be
387 specified, in which case each address will be tried until a work‐
388 ing connection has been established.
389 Cipher = cipher (blowfish)
392 The symmetric cipher algorithm used to encrypt UDP packets. Any
393 cipher supported by OpenSSL is recognised. Furthermore, specify‐
394 ing "none" will turn off packet encryption. It is best to use
395 only those ciphers which support CBC mode.
396 ClampMSS = yes | no (yes)
399 This option specifies whether tinc should clamp the maximum seg‐
400 ment size (MSS) of TCP packets to the path MTU. This helps in
401 situations where ICMP Fragmentation Needed or Packet too Big mes‐
402 sages are dropped by firewalls.
403 Compression = level (0)
406 This option sets the level of compression used for UDP packets.
407 Possible values are 0 (off), 1 (fast zlib) and any integer up to
408 9 (best zlib), 10 (fast lzo) and 11 (best lzo).
409 Digest = digest (sha1)
412 The digest algorithm used to authenticate UDP packets. Any
413 digest supported by OpenSSL is recognised. Furthermore, specify‐
414 ing "none" will turn off packet authentication.
415 IndirectData = yes | no (no)
418 This option specifies whether other tinc daemons besides the one
419 you specified with ConnectTo can make a direct connection to you.
420 This is especially useful if you are behind a firewall and it is
421 impossible to make a connection from the outside to your tinc
422 daemon. Otherwise, it is best to leave this option out or set it
423 to no.
424 MACLength = length (4)
427 The length of the message authentication code used to authenti‐
428 cate UDP packets. Can be anything from "0" up to the length of
429 the digest produced by the digest algorithm.
430 PMTU = mtu (1514)
433 This option controls the initial path MTU to this node.
434 PMTUDiscovery = yes | no (yes)
437 When this option is enabled, tinc will try to discover the path
438 MTU to this node. After the path MTU has been discovered, it
439 will be enforced on the VPN.
440 Port = port (655)
443 The port number on which this tinc daemon is listening for incom‐
444 ing connections, which is used if no port number is specified in
445 an Address statement.
446 PublicKey = key [obsolete]
449 The public RSA key of this tinc daemon. It will be used to cryp‐
450 tographically verify it's identity and to set up a secure connec‐
451 tion.
452 PublicKeyFile = filename [obsolete]
455 The file in which the public RSA key of this tinc daemon resides.
456 From version 1.0pre4 on tinc will store the public key directly
459 into the host configuration file in PEM format, the above two
460 options then are not necessary. Either the PEM format is used,
461 or exactly one of the above two options must be specified in each
462 host configuration file, if you want to be able to establish a
463 connection with that host.
464 Subnet = address[/prefixlength[#weight]]
467 The subnet which this tinc daemon will serve. tinc tries to look
468 up which other daemon it should send a packet to by searching the
469 appropriate subnet. If the packet matches a subnet, it will be
470 sent to the daemon who has this subnet in his host configuration
471 file. Multiple Subnet variables can be specified.
472 Subnets can either be single MAC, IPv4 or IPv6 addresses, in
475 which case a subnet consisting of only that single address is
476 assumed, or they can be a IPv4 or IPv6 network address with a
477 prefixlength. Shorthand notations are not supported. For exam‐
478 ple, IPv4 subnets must be in a form like 192.168.1.0/24, where
479 192.168.1.0 is the network address and 24 is the number of bits
480 set in the netmask. Note that subnets like 192.168.1.1/24 are
481 invalid! Read a networking HOWTO/FAQ/guide if you don't under‐
482 stand this. IPv6 subnets are notated like fec0:0:0:1:0:0:0:0/64.
483 MAC addresses are notated like 0:1a:2b:3c:4d:5e.
484 A Subnet can be given a weight to indicate its priority over
487 identical Subnets owned by different nodes. The default weight
488 is 10. Lower values indicate higher priority. Packets will be
489 sent to the node with the highest priority, unless that node is
490 not reachable, in which case the node with the next highest pri‐
491 ority will be tried, and so on.
492 TCPOnly = yes | no (no [obsolete])
495 If this variable is set to yes, then the packets are tunnelled
496 over the TCP connection instead of a UDP connection. This is
497 especially useful for those who want to run a tinc daemon from
498 behind a masquerading firewall, or if UDP packet routing is dis‐
499 abled somehow. Setting this options also implicitly sets Indi‐
500 rectData.
501 Since version 1.0.10, tinc will automatically detect whether com‐
504 munication via UDP is possible or not.
505
508 Apart from reading the server and host configuration files, tinc can also
509 run scripts at certain moments. Under Windows (not Cygwin), the scripts
510 should have the extension .bat.
511 /etc/tinc/NETNAME/tinc-up
514 This is the most important script. If it is present it will be
515 executed right after the tinc daemon has been started and has
516 connected to the virtual network device. It should be used to
517 set up the corresponding network interface, but can also be used
518 to start other things. Under Windows you can use the Network
519 Connections control panel instead of creating this script.
520 /etc/tinc/NETNAME/tinc-down
523 This script is started right before the tinc daemon quits.
524 /etc/tinc/NETNAME/hosts/HOST-up
527 This script is started when the tinc daemon with name HOST
528 becomes reachable.
529 /etc/tinc/NETNAME/hosts/HOST-down
532 This script is started when the tinc daemon with name HOST
533 becomes unreachable.
534 /etc/tinc/NETNAME/host-up
537 This script is started when any host becomes reachable.
538 /etc/tinc/NETNAME/host-down
541 This script is started when any host becomes unreachable.
542 /etc/tinc/NETNAME/subnet-up
545 This script is started when a Subnet becomes reachable. The Sub‐
546 net and the node it belongs to are passed in environment vari‐
547 ables.
548 /etc/tinc/NETNAME/subnet-down
551 This script is started when a Subnet becomes unreachable.
552 The scripts are started without command line arguments, but can make use
555 of certain environment variables. Under UNIX like operating systems the
556 names of environment variables must be preceded by a $ in scripts. Under
557 Windows, in .bat files, they have to be put between % signs.
558 NETNAME
561 If a netname was specified, this environment variable contains
562 it.
563 NAME Contains the name of this tinc daemon.
566 DEVICE Contains the name of the virtual network device that tinc uses.
569 INTERFACE
572 Contains the name of the virtual network interface that tinc
573 uses. This should be used for commands like ifconfig.
574 NODE When a host becomes (un)reachable, this is set to its name. If a
577 subnet becomes (un)reachable, this is set to the owner of that
578 subnet.
579 REMOTEADDRESS
582 When a host becomes (un)reachable, this is set to its real
583 address.
584 REMOTEPORT
587 When a host becomes (un)reachable, this is set to the port number
588 it uses for communication with other tinc daemons.
589 SUBNET When a subnet becomes (un)reachable, this is set to the subnet.
592 WEIGHT When a subnet becomes (un)reachable, this is set to the subnet
595 weight.
596
599 The most important files are:
600 /etc/tinc/
603 The top directory for configuration files.
604 /etc/tinc/NETNAME/tinc.conf
607 The default name of the server configuration file for net
608 NETNAME.
609 /etc/tinc/NETNAME/hosts/
612 Host configuration files are kept in this directory.
613 /etc/tinc/NETNAME/tinc-up
616 If an executable file with this name exists, it will be executed
617 right after the tinc daemon has connected to the virtual network
618 device. It can be used to set up the corresponding network
619 interface.
620 /etc/tinc/NETNAME/tinc-down
623 If an executable file with this name exists, it will be executed
624 right before the tinc daemon is going to close its connection to
625 the virtual network device.
626
629 tincd(8), http://www.tinc-vpn.org/, http://www.linuxdoc.org/LDP/nag2/.
630 The full documentation for tinc is maintained as a Texinfo manual. If
633 the info and tinc programs are properly installed at your site, the com‐
634 mand info tinc should give you access to the complete manual.
635 tinc comes with ABSOLUTELY NO WARRANTY. This is free software, and you
638 are welcome to redistribute it under certain conditions; see the file
639 COPYING for details.
640 June 22, 2019