1 |
.Dd 2002-04-09 |
2 |
.Dt TINC.CONF 5 |
3 |
.\" Manual page created by: |
4 |
.\" Ivo Timmermans <ivo@o2w.nl> |
5 |
.\" Guus Sliepen <guus@sliepen.eu.org> |
6 |
.Sh NAME |
7 |
.Nm tinc.conf |
8 |
.Nd tinc daemon configuration |
9 |
.Sh DESCRIPTION |
10 |
The files in the |
11 |
.Pa /etc/tinc/ |
12 |
directory contain runtime and security information for the tinc daemon. |
13 |
.Sh NETWORKS |
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 |
30 |
.Ar NETNAME |
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. |
66 |
.Sh PUBLIC/PRIVATE KEYS |
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 |
74 |
.Ar NETNAME |
75 |
stands for the network (see |
76 |
.Sx NETWORKS ) |
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 ) . |
84 |
.Sh SERVER CONFIGURATION |
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/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 |
205 |
.Sh HOST CONFIGURATION FILES |
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 prefixlength |
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 prefixlength. |
280 |
Shorthand notations are not supported. |
281 |
For example, IPv4 subnets must be in a form like 192.168.1.0/24, |
282 |
where 192.168.1.0 is the network address and 24 is the number of bits set in the netmask. |
283 |
Note that subnets like 192.168.1.1/24 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 |
Setting this options also implicitly sets IndirectData. |
294 |
.El |
295 |
.Sh FILES |
296 |
.Bl -tag -width indent |
297 |
.It Pa /etc/tinc/ |
298 |
The top directory for configuration files. |
299 |
.It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /tinc.conf |
300 |
The default name of the server configuration file for net |
301 |
.Ar NETNAME . |
302 |
.It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /hosts/ |
303 |
Host configuration files are kept in this directory. |
304 |
.It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /tinc-up |
305 |
If an executable file with this name exists, |
306 |
it will be executed right after the tinc daemon has connected to the virtual network device. |
307 |
It can be used to set up the corresponding network interface. |
308 |
.Pp |
309 |
The environment variable |
310 |
.Ev $NETNAME |
311 |
will be passed to the executable. |
312 |
If specified with the |
313 |
.Va Interface |
314 |
configuration variable, |
315 |
or if the virtual network device is a Linux tun/tap device, |
316 |
the environment variable |
317 |
.Ev $INTERFACE |
318 |
will be set to the name of the network interface. |
319 |
.It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /tinc-down |
320 |
If an executable file with this name exists, |
321 |
it will be executed right before the tinc daemon is going to close |
322 |
its connection to the virtual network device. |
323 |
The same environment variables will be passed as mentioned above. |
324 |
.El |
325 |
.Sh SEE ALSO |
326 |
.Xr tincd 8 , |
327 |
.Pa http://tinc.nl.linux.org/ , |
328 |
.Pa http://www.linuxdoc.org/LDP/nag2/ . |
329 |
.Pp |
330 |
The full documentation for |
331 |
.Nm tinc |
332 |
is maintained as a Texinfo manual. |
333 |
If the info and tinc programs are properly installed at your site, the command |
334 |
.Ic info tinc |
335 |
should give you access to the complete manual. |
336 |
.Pp |
337 |
.Nm tinc |
338 |
comes with ABSOLUTELY NO WARRANTY. |
339 |
This is free software, and you are welcome to redistribute it under certain conditions; |
340 |
see the file COPYING for details. |