[tinc] / doc / tinc.conf.5
1 .Dd 2002-02-06
3 .\" Manual page created by:
4 .\" Ivo Timmermans <itimmermans@bigfoot.com>
5 .\" Guus Sliepen <guus@sliepen.warande.net>
6 .Sh NAME
7 .Nm tinc.conf
8 .Nd tinc daemon configuration
10 The files in the
11 .Pa /etc/tinc/
12 directory contain runtime and security information for the tinc daemon.
14 It is perfectly ok for you to run more than one tinc daemon.
15 However, in its default form,
16 you will soon notice that you can't use two different configuration files without the
17 .Fl c
18 option.
19 .Pp
20 We have thought of another way of dealing with this: network names.
21 This means that you call
22 .Nm
23 with the
24 .Fl n
25 option, which will assign a name to this daemon.
26 .Pp
27 The effect of this is that the daemon will set its configuration root to
28 .Pa /etc/tinc/ Ns Ar NETNAME Ns Pa / ,
29 where 
31 is your argument to the
32 .Fl n
33 option.
34 You'll notice that messages appear in syslog as coming from
35 .Nm tincd. Ns Ar NETNAME .
36 .Pp
37 However, it is not strictly necessary that you call tinc with the
38 .Fl n
39 option.
40 In this case, the network name would just be empty,
41 and it will be used as such.
42 .Nm tinc
43 now looks for files in
44 .Pa /etc/tinc/ ,
45 instead of 
46 .Pa /etc/tinc/ Ns Ar NETNAME Ns Pa / ;
47 the configuration file should be
48 .Pa /etc/tinc/tinc.conf ,
49 and the host configuration files are now expected to be in
50 .Pa /etc/tinc/hosts/ .
51 .Pp
52 But it is highly recommended that you use this feature of
53 .Nm tinc ,
54 because it will be so much clearer whom your daemon talks to.
55 Hence, we will assume that you use it.
56 .Sh NAMES
57 Each tinc daemon should have a name that is unique in the network which it will be part of.
58 The name will be used by other tinc daemons for identification.
59 The name has to be declared in the
60 .Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /tinc.conf
61 file.
62 .Pp
63 To make things easy,
64 choose something that will give unique and easy to remember names to your tinc daemon(s).
65 You could try things like hostnames, owner surnames or location names.
67 You should use 
68 .Ic tincd -K
69 to generate public/private keypairs.
70 It will generate two keys.
71 The private key should be stored in a separate file
72 .Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /rsa_key.priv
73 \-\- where 
75 stands for the network (see 
77 above.
78 The public key should be stored in the host configuration file
79 .Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /hosts/ Ns Va NAME
80 \-\- where
81 .Va NAME
82 stands for the name of the local tinc daemon (see
83 .Sx NAMES ) .
85 The server configuration of the daemon is done in the file
86 .Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /tinc.conf .
87 This file consists of comments (lines started with a
88 .Li # )
89 or assignments in the form of:
90 .Pp
91 .Va Variable Li = Ar Value .
92 .Pp
93 The variable names are case insensitive, and any spaces, tabs,
94 newlines and carriage returns are ignored.
95 Note: it is not required that you put in the 
96 .Li =
97 sign, but doing so improves readability.
98 If you leave it out, remember to replace it with at least one space character.
99 .Pp
100 Here are all valid variables, listed in alphabetical order.
101 The default value is given between parentheses.
102 .Bl -tag -width indent
103 .It Va AddressFamily Li = ipv4 | ipv6 | any Po ipv4 Pc Bq experimental
104 This option affects the address family of listening and outgoing sockets.
105 If
106 .Qq any
107 is selected, then depending on the operating system both IPv4 and IPv6 or just
108 IPv6 listening sockets will be created.
109 .It Va BindToInterface Li = Ar interface Bq experimental
110 If your computer has more than one network interface,
111 .Nm tinc
112 will by default listen on all of them for incoming connections.
113 It is possible to bind only to a single interface with this variable.
114 .Pp
115 This option may not work on all platforms.
116 .It Va ConnectTo Li = Ar name
117 Specifies which other tinc daemon to connect to on startup.
118 Multiple
119 .Va ConnectTo
120 variables may be specified,
121 in which case outgoing connections to each specified tinc daemon are made.
122 The names should be known to this tinc daemon
123 (i.e., there should be a host configuration file for the name on the
124 .Va ConnectTo
125 line).
126 .Pp
127 If you don't specify a host with
128 .Va ConnectTo ,
129 .Nm tinc
130 won't try to connect to other daemons at all,
131 and will instead just listen for incoming connections.
132 .It Va Device Li = Ar device Po /dev/tap0 or /dev/misc/net/tun Pc
133 The virtual network device to use.
134 .Nm tinc
135 will automatically detect what kind of device it is.
136 Note that you can only use one device per daemon.
137 The info pages of the tinc package contain more information
138 about configuring the virtual network device.
139 .It Va Hostnames Li = yes | no Pq no
140 This option selects whether IP addresses (both real and on the VPN) should
141 be resolved. Since DNS lookups are blocking, it might affect tinc's
142 efficiency, even stopping the daemon for a few seconds every time it does
143 a lookup if your DNS server is not responding.
144 .Pp
145 This does not affect resolving hostnames to IP addresses from the
146 host configuration files.
147 .It Va Interface Li = Ar interface
148 Defines the name of the interface corresponding to the virtual network device.
149 Depending on the operating system and the type of device this may or may not actually set the name.
150 Currently this option only affects the Linux tun/tap device.
151 .It Va KeyExpire Li = Ar period Pq 3600
152 This option controls the period the encryption keys used to encrypt the data are valid.
153 It is common practice to change keys at regular intervals to make it even harder for crackers,
154 even though it is thought to be nearly impossible to crack a single key.
155 .It Va MACExpire Li = Ar period Pq 600
156 This option controls the amount of time MAC addresses are kept before they are removed.
157 This only has effect when
158 .Va Mode
159 is set to
160 .Qq switch .
161 .It Va MaxTimeout Li = Ar period Pq 900
162 This is the maximum delay before trying to reconnect to other tinc daemons.
163 .It Va Mode Li = router | switch | hub Pq router
164 This option selects the way packets are routed to other daemons.
165 .Bl -tag -width indent
166 .It router
167 In this mode
168 .Va Subnet
169 variables in the host configuration files will be used to form a routing table.
170 Only unicast packets of routable protocols (IPv4 and IPv6) are supported in this mode.
171 .It switch
172 In this mode the MAC addresses of the packets on the VPN will be used to
173 dynamically create a routing table just like an Ethernet switch does.
174 Unicast, multicast and broadcast packets of every protocol that runs over Ethernet are supported in this mode
175 at the cost of frequent broadcast ARP requests and routing table updates.
176 .It hub
177 This mode is almost the same as the switch mode, but instead
178 every packet will be broadcast to the other daemons
179 while no routing table is managed.
180 .El
181 .It Va Name Li = Ar name Bq required
182 This is the name which identifies this tinc daemon.
183 It must be unique for the virtual private network this daemon will connect to.
184 .It Va PingTimeout Li = Ar period Pq 60
185 The number of seconds of inactivity that
186 .Nm tinc
187 will wait before sending a probe to the other end.
188 If that other end doesn't answer within that same amount of time,
189 the connection is terminated,
190 and the others will be notified of this.
191 .It Va PriorityInheritance Li = yes | no Po no Pc Bq experimental
192 When this option is enabled the value of the TOS field of tunneled IPv4 packets
193 will be inherited by the UDP packets that are sent out.
194 .It Va PrivateKey Li = Ar key Bq obsolete
195 The private RSA key of this tinc daemon.
196 It will allow this tinc daemon to authenticate itself to other daemons.
197 .It Va PrivateKeyFile Li = Ar filename Bq recommended
198 The file in which the private RSA key of this tinc daemon resides.
199 Note that there must be exactly one of
200 .Va PrivateKey
201 or
202 .Va PrivateKeyFile
203 specified in the configuration file.
204 .El
206 The host configuration files contain all information needed
207 to establish a connection to those hosts.
208 A host configuration file is also required for the local tinc daemon,
209 it will use it to read in it's listen port, public key and subnets.
210 .Pp
211 The idea is that these files are portable.
212 You can safely mail your own host configuration file to someone else.
213 That other person can then copy it to his own hosts directory,
214 and now his tinc daemon will be able to connect to your tinc daemon.
215 Since host configuration files only contain public keys,
216 no secrets are revealed by sending out this information.
217 .Bl -tag -width indent
218 .It Va Address Li = Ar address Bq recommended
219 The IP address or hostname of this tinc daemon on the real network.
220 This wil only be used when trying to make an outgoing connection to this tinc daemon.
221 Multiple
222 .Va Address
223 variables can be specified, in which case each address will be tried until a working
224 connection has been established.
225 .It Va Cipher Li = Ar cipher Pq blowfish
226 The symmetric cipher algorithm used to encrypt UDP packets.
227 Any cipher supported by OpenSSL is recognised.
228 Furthermore, specifying
229 .Qq none
230 will turn off packet encryption.
231 .It Va Compression Li = Ar level Pq 0
232 This option sets the level of compression used for UDP packets.
233 Possible values are 0 (off), 1 (fast) and any integer up to 9 (best).
234 .It Va Digest Li = Ar digest Pq sha1
235 The digest algorithm used to authenticate UDP packets.
236 Any digest supported by OpenSSL is recognised.
237 Furthermore, specifying
238 .Qq none
239 will turn off packet authentication.
240 .It Va IndirectData Li = yes | no Pq no
241 This option specifies whether other tinc daemons besides the one you specified with
242 .Va ConnectTo
243 can make a direct connection to you.
244 This is especially useful if you are behind a firewall
245 and it is impossible to make a connection from the outside to your tinc daemon.
246 Otherwise, it is best to leave this option out or set it to no.
247 .It Va MACLength Li = Ar length Pq 4
248 The length of the message authentication code used to authenticate UDP packets.
249 Can be anything from
250 .Qq 0
251 up to the length of the digest produced by the digest algorithm.
252 .It Va Port Li = Ar port Pq 655
253 The port number on which this tinc daemon is listening for incoming connections.
254 .It Va PublicKey Li = Ar key Bq obsolete
255 The public RSA key of this tinc daemon.
256 It will be used to cryptographically verify it's identity and to set up a secure connection.
257 .It Va PublicKeyFile Li = Ar filename Bq obsolete
258 The file in which the public RSA key of this tinc daemon resides.
259 .Pp
260 From version 1.0pre4 on
261 .Nm tinc
262 will store the public key directly into the host configuration file in PEM format,
263 the above two options then are not necessary.
264 Either the PEM format is used, or exactly one of the above two options must be specified
265 in each host configuration file,
266 if you want to be able to establish a connection with that host.
267 .It Va Subnet Li = Ar address Ns Op Li / Ns Ar masklength
268 The subnet which this tinc daemon will serve.
269 .Nm tinc
270 tries to look up which other daemon it should send a packet to by searching the appropriate subnet.
271 If the packet matches a subnet,
272 it will be sent to the daemon who has this subnet in his host configuration file.
273 Multiple
274 .Va Subnet
275 variables can be specified.
276 .Pp
277 Subnets can either be single MAC, IPv4 or IPv6 addresses,
278 in which case a subnet consisting of only that single address is assumed,
279 or they can be a IPv4 or IPv6 network address with a masklength.
280 Shorthand notations are not supported.
281 For example, IPv4 subnets must be in a form like,
282 where is the network address and 24 is the number of bits set in the netmask.
283 Note that subnets like are invalid!
284 Read a networking HOWTO/FAQ/guide if you don't understand this.
285 IPv6 subnets are notated like fec0:0:0:1:0:0:0:0/64.
286 MAC addresses are notated like 0:1a:2b:3c:4d:5e.
287 .It Va TCPOnly Li = yes | no Pq no
288 If this variable is set to yes,
289 then the packets are tunnelled over the TCP connection instead of a UDP connection.
290 This is especially useful for those who want to run a tinc daemon
291 from behind a masquerading firewall,
292 or if UDP packet routing is disabled somehow.
293 This is experimental code, try this at your own risk.
294 It may not work at all.
295 Setting this options also implicitly sets IndirectData.
296 .El
297 .Sh FILES
298 .Bl -tag -width indent
299 .It Pa /etc/tinc/
300 The top directory for configuration files.
301 .It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /tinc.conf
302 The default name of the server configuration file for net
303 .Ar NETNAME .
304 .It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /hosts/
305 Host configuration files are kept in this directory.
306 .It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /tinc-up
307 If an executable file with this name exists,
308 it will be executed right after the tinc daemon has connected to the virtual network device.
309 It can be used to set up the corresponding network interface.
310 .Pp
311 The environment variable
312 .Ev $NETNAME
313 will be passed to the executable.
314 If specified with the
315 .Va Interface
316 configuration variable,
317 or if the virtual network device is a Linux tun/tap device,
318 the environment variable
320 will be set to the name of the network interface.
321 .It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /tinc-down
322 If an executable file with this name exists,
323 it will be executed right before the tinc daemon is going to close
324 its connection to the virtual network device.
325 The same environment variables will be passed as mentioned above.
326 .El
327 .Sh SEE ALSO
328 .Xr tincd 8 ,
329 .Pa http://tinc.nl.linux.org/ ,
330 .Pa http://www.linuxdoc.org/LDP/nag2/ .
331 .Pp
332 The full documentation for
333 .Nm tinc
334 is maintained as a Texinfo manual.
335 If the info and tinc programs are properly installed at your site, the command
336 .Ic info tinc
337 should give you access to the complete manual.
338 .Pp
339 .Nm tinc
341 This is free software, and you are welcome to redistribute it under certain conditions;
342 see the file COPYING for details.