1 |
pcg |
1.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. |