Release new version 0.3.4-2
[anytun.git] / doc / anytun.8
1 '\" t
2 .\"     Title: anytun
3 .\"    Author: [see the "AUTHORS" section]
4 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
5 .\"      Date: 12/30/2011
6 .\"    Manual: \ \&
7 .\"    Source: \ \&
8 .\"  Language: English
9 .\"
10 .TH "ANYTUN" "8" "12/30/2011" "\ \&" "\ \&"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el       .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 anytun \- anycast tunneling daemon
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 \fBanytun\fR
36   [ \fB\-h|\-\-help\fR ]
37   [ \fB\-D|\-\-nodaemonize\fR ]
38   [ \fB\-u|\-\-username\fR <username> ]
39   [ \fB\-g|\-\-groupname\fR <groupname> ]
40   [ \fB\-C|\-\-chroot\fR <path> ]
41   [ \fB\-P|\-\-write\-pid\fR <filename> ]
42   [ \fB\-L|\-\-log\fR <target>:<level>[,<param1>[,<param2>[\&.\&.]]] ]
43   [ \fB\-U|\-\-debug\fR ]
44   [ \fB\-i|\-\-interface\fR <ip\-address> ]
45   [ \fB\-p|\-\-port\fR <port> ]
46   [ \fB\-r|\-\-remote\-host\fR <hostname|ip> ]
47   [ \fB\-o|\-\-remote\-port\fR <port> ]
48   [ \fB\-4|\-\-ipv4\-only\fR ]
49   [ \fB\-6|\-\-ipv6\-only\fR ]
50   [ \fB\-I|\-\-sync\-interface\fR <ip\-address> ]
51   [ \fB\-S|\-\-sync\-port\fR port> ]
52   [ \fB\-M|\-\-sync\-hosts\fR <hostname|ip>[:<port>][,<hostname|ip>[:<port>][\&.\&.\&.]] ]
53   [ \fB\-X|\-\-control\-host\fR <hostname|ip>[:<port>]
54   [ \fB\-d|\-\-dev\fR <name> ]
55   [ \fB\-t|\-\-type\fR <tun|tap> ]
56   [ \fB\-n|\-\-ifconfig\fR <local>/<prefix> ]
57   [ \fB\-x|\-\-post\-up\-script\fR <script> ]
58   [ \fB\-R|\-\-route\fR <net>/<prefix length> ]
59   [ \fB\-m|\-\-mux\fR <mux\-id> ]
60   [ \fB\-s|\-\-sender\-id\fR <sender id> ]
61   [ \fB\-w|\-\-window\-size\fR <window size> ]
62   [ \fB\-k|\-\-kd\-prf\fR <kd\-prf type> ]
63   [ \fB\-e|\-\-role\fR <role> ]
64   [ \fB\-E|\-\-passphrase\fR <pass phrase> ]
65   [ \fB\-K|\-\-key\fR <master key> ]
66   [ \fB\-A|\-\-salt\fR <master salt> ]
67   [ \fB\-c|\-\-cipher\fR <cipher type> ]
68   [ \fB\-a|\-\-auth\-algo\fR <algo type> ]
69   [ \fB\-b|\-\-auth\-tag\-length\fR <length> ]
70 .fi
71 .SH "DESCRIPTION"
72 .sp
73 \fBAnytun\fR is an implementation of the Secure Anycast Tunneling Protocol (SATP)\&. It provides a complete VPN solution similar to OpenVPN or IPsec in tunnel mode\&. The main difference is that anycast allows a setup of tunnels between an arbitrary combination of anycast, unicast and multicast hosts\&.
74 .SH "OPTIONS"
75 .sp
76 \fBAnytun\fR has been designed as a peer to peer application, so there is no difference between client and server\&. The following options can be passed to the daemon:
77 .PP
78 \fB\-D, \-\-nodaemonize\fR
79 .RS 4
80 This option instructs
81 \fBAnytun\fR
82 to run in foreground instead of becoming a daemon which is the default\&.
83 .RE
84 .PP
85 \fB\-u, \-\-username \fR\fB\fI<username>\fR\fR
86 .RS 4
87 run as this user\&. If no group is specified (\fB\-g\fR) the default group of the user is used\&. The default is to not drop privileges\&.
88 .RE
89 .PP
90 \fB\-g, \-\-groupname \fR\fB\fI<groupname>\fR\fR
91 .RS 4
92 run as this group\&. If no username is specified (\fB\-u\fR) this gets ignored\&. The default is to not drop privileges\&.
93 .RE
94 .PP
95 \fB\-C, \-\-chroot \fR\fB\fI<path>\fR\fR
96 .RS 4
97 Instruct
98 \fBAnytun\fR
99 to run in a chroot jail\&. The default is to not run in chroot\&.
100 .RE
101 .PP
102 \fB\-P, \-\-write\-pid \fR\fB\fI<filename>\fR\fR
103 .RS 4
104 Instruct
105 \fBAnytun\fR
106 to write it\(cqs pid to this file\&. The default is to not create a pid file\&.
107 .RE
108 .PP
109 \fB\-L, \-\-log \fR\fB\fI<target>:<level>[,<param1>[,<param2>[\&.\&.]]]\fR\fR
110 .RS 4
111 add log target to logging system\&. This can be invoked several times in order to log to different targets at the same time\&. Every target hast its own log level which is a number between 0 and 5\&. Where 0 means disabling log and 5 means debug messages are enabled\&.
112
113 The file target can be used more the once with different levels\&. If no target is provided at the command line a single target with the config
114 \fIsyslog:3,anytun,daemon\fR
115 is added\&.
116
117 The following targets are supported:
118 .PP
119 \fIsyslog\fR
120 .RS 4
121 log to syslog daemon, parameters <level>[,<logname>[,<facility>]]
122 .RE
123 .PP
124 \fIfile\fR
125 .RS 4
126 log to file, parameters <level>[,<path>]
127 .RE
128 .PP
129 \fIstdout\fR
130 .RS 4
131 log to standard output, parameters <level>
132 .RE
133 .PP
134 \fIstderr\fR
135 .RS 4
136 log to standard error, parameters <level>
137 .RE
138 .RE
139 .PP
140 \fB\-U, \-\-debug\fR
141 .RS 4
142 This option instructs
143 \fBAnytun\fR
144 to run in debug mode\&. It implicits
145 \fB\-D\fR
146 (don\(cqt daemonize) and adds a log target with the configuration
147 \fIstdout:5\fR
148 (logging with maximum level)\&. In future releases there might be additional output when this option is supplied\&.
149 .RE
150 .PP
151 \fB\-i, \-\-interface \fR\fB\fI<ip address>\fR\fR
152 .RS 4
153 This IP address is used as the sender address for outgoing packets\&. In case of anycast tunnel endpoints, the anycast IP has to be used\&. In case of unicast endpoints, the address is usually derived correctly from the routing table\&. The default is to not use a special inteface and just bind on all interfaces\&.
154 .RE
155 .PP
156 \fB\-p, \-\-port \fR\fB\fI<port>\fR\fR
157 .RS 4
158 The local UDP port that is used to send and receive the payload data\&. The two tunnel endpoints can use different ports\&. If a tunnel endpoint consists of multiple anycast hosts, all hosts have to use the same port\&. default: 4444
159 .RE
160 .PP
161 \fB\-r, \-\-remote\-host \fR\fB\fI<hostname|ip>\fR\fR
162 .RS 4
163 This option can be used to specify the remote tunnel endpoint\&. In case of anycast tunnel endpoints, the anycast IP address has to be used\&. If you do not specify an address, it is automatically determined after receiving the first data packet\&.
164 .RE
165 .PP
166 \fB\-o, \-\-remote\-port \fR\fB\fI<port>\fR\fR
167 .RS 4
168 The UDP port used for payload data by the remote host (specified with \-p on the remote host)\&. If you do not specify a port, it is automatically determined after receiving the first data packet\&.
169 .RE
170 .PP
171 \fB\-4, \-\-ipv4\-only\fR
172 .RS 4
173 Resolv to IPv4 addresses only\&. The default is to resolv both IPv4 and IPv6 addresses\&.
174 .RE
175 .PP
176 \fB\-6, \-\-ipv6\-only\fR
177 .RS 4
178 Resolv to IPv6 addresses only\&. The default is to resolv both IPv4 and IPv6 addresses\&.
179 .RE
180 .PP
181 \fB\-I, \-\-sync\-interface \fR\fB\fI<ip\-address>\fR\fR
182 .RS 4
183 local unicast(sync) ip address to bind to
184
185 This option is only needed for tunnel endpoints consisting of multiple anycast hosts\&. The unicast IP address of the anycast host can be used here\&. This is needed for communication with the other anycast hosts\&. The default is to not use a special inteface and just bind on all interfaces\&. However this is only the case if synchronisation is active see
186 \fB\-\-sync\-port\fR\&.
187 .RE
188 .PP
189 \fB\-S, \-\-sync\-port \fR\fB\fI<port>\fR\fR
190 .RS 4
191 local unicast(sync) port to bind to
192
193 This option is only needed for tunnel endpoints consisting of multiple anycast hosts\&. This port is used by anycast hosts to synchronize information about tunnel endpoints\&. No payload data is transmitted via this port\&. By default the synchronisation is disabled an therefore the port is kept empty\&.
194
195 It is possible to obtain a list of active connections by telnetting into this port\&. This port is read\-only and unprotected by default\&. It is advised to protect this port using firewall rules and, eventually, IPsec\&.
196 .RE
197 .PP
198 \fB\-M, \-\-sync\-hosts \fR\fB\fI<hostname|ip>[:<port>],[<hostname|ip>[:<port>][\&...]]\fR\fR
199 .RS 4
200 remote hosts to sync with
201
202 This option is only needed for tunnel endpoints consisting of multiple anycast hosts\&. Here, one has to specify all unicast IP addresses of all other anycast hosts that comprise the anycast tunnel endpoint\&. By default synchronisation is disabled and therefore this is empty\&. Mind that the port can be omitted in which case port 2323 is used\&. If you want to specify an ipv6 address and a port you have to use [ and ] to separate the address from the port, eg\&.: [::1]:1234\&. If you want to use the default port [ and ] can be omitted\&.
203 .RE
204 .PP
205 \fB\-X, \-\-control\-host \fR\fB\fI<hostname|ip>[:<port>]\fR\fR
206 .RS 4
207 fetch the config from this host\&. The default is not to use a control host and therefore this is empty\&. Mind that the port can be omitted in which case port 2323 is used\&. If you want to specify an ipv6 address and a port you have to use [ and ] to separate the address from the port, eg\&.: [::1]:1234\&. If you want to use the default port [ and ] can be omitted\&.
208 .RE
209 .PP
210 \fB\-d, \-\-dev \fR\fB\fI<name>\fR\fR
211 .RS 4
212 device name
213
214 By default, tapN is used for Ethernet tunnel interfaces, and tunN for IP tunnels, respectively\&. This option can be used to manually override these defaults\&.
215 .RE
216 .PP
217 \fB\-t, \-\-type \fR\fB\fI<tun|tap>\fR\fR
218 .RS 4
219 device type
220
221 Type of the tunnels to create\&. Use tap for Ethernet tunnels, tun for IP tunnels\&.
222 .RE
223 .PP
224 \fB\-n, \-\-ifconfig \fR\fB\fI<local>/<prefix>\fR\fR
225 .RS 4
226 The local IP address and prefix length\&. The remote tunnel endpoint has to use a different IP address in the same subnet\&.
227 .PP
228 \fI<local>\fR
229 .RS 4
230 the local IP address for the tun/tap device
231 .RE
232 .PP
233 \fI<prefix>\fR
234 .RS 4
235 the prefix length of the network
236 .RE
237 .RE
238 .PP
239 \fB\-x, \-\-post\-up\-script \fR\fB\fI<script>\fR\fR
240 .RS 4
241 This option instructs
242 \fBAnytun\fR
243 to run this script after the interface is created\&. By default no script will be executed\&.
244 .RE
245 .PP
246 \fB\-R, \-\-route \fR\fB\fI<net>/<prefix length>\fR\fR
247 .RS 4
248 add a route to connection\&. This can be invoked several times\&.
249 .RE
250 .PP
251 \fB\-m, \-\-mux \fR\fB\fI<mux\-id>\fR\fR
252 .RS 4
253 the multiplex id to use\&. default: 0
254 .RE
255 .PP
256 \fB\-s, \-\-sender\-id \fR\fB\fI<sender id>\fR\fR
257 .RS 4
258 Each anycast tunnel endpoint needs a uniqe sender id (1, 2, 3, \&...)\&. It is needed to distinguish the senders in case of replay attacks\&. This option can be ignored on unicast endpoints\&. default: 0
259 .RE
260 .PP
261 \fB\-w, \-\-window\-size \fR\fB\fI<window size>\fR\fR
262 .RS 4
263 seqence window size
264
265 Sometimes, packets arrive out of order on the receiver side\&. This option defines the size of a list of received packets\*(Aq sequence numbers\&. If, according to this list, a received packet has been previously received or has been transmitted in the past, and is therefore not in the list anymore, this is interpreted as a replay attack and the packet is dropped\&. A value of 0 deactivates this list and, as a consequence, the replay protection employed by filtering packets according to their secuence number\&. By default the sequence window is disabled and therefore a window size of 0 is used\&.
266 .RE
267 .PP
268 \fB\-k, \-\-kd\(emprf \fR\fB\fI<kd\-prf type>\fR\fR
269 .RS 4
270 key derivation pseudo random function
271
272 The pseudo random function which is used for calculating the session keys and session salt\&.
273
274 Possible values:
275 .PP
276 \fInull\fR
277 .RS 4
278 no random function, keys and salt are set to 0\&.\&.00
279 .RE
280 .PP
281 \fIaes\-ctr\fR
282 .RS 4
283 AES in counter mode with 128 Bits, default value
284 .RE
285 .PP
286 \fIaes\-ctr\-128\fR
287 .RS 4
288 AES in counter mode with 128 Bits
289 .RE
290 .PP
291 \fIaes\-ctr\-192\fR
292 .RS 4
293 AES in counter mode with 192 Bits
294 .RE
295 .PP
296 \fIaes\-ctr\-256\fR
297 .RS 4
298 AES in counter mode with 256 Bits
299 .RE
300 .RE
301 .PP
302 \fB\-e, \-\-role \fR\fB\fI<role>\fR\fR
303 .RS 4
304 SATP uses different session keys for inbound and outbound traffic\&. The role parameter is used to determine which keys to use for outbound or inbound packets\&. On both sides of a vpn connection different roles have to be used\&. Possible values are
305 \fIleft\fR
306 and
307 \fIright\fR\&. You may also use
308 \fIalice\fR
309 or
310 \fIserver\fR
311 as a replacement for
312 \fIleft\fR
313 and
314 \fIbob\fR
315 or
316 \fIclient\fR
317 as a replacement for
318 \fIright\fR\&. By default
319 \fIleft\fR
320 is used\&.
321 .RE
322 .PP
323 \fB\-E, \-\-passphrase \fR\fB\fI<passphrase>\fR\fR
324 .RS 4
325 This passphrase is used to generate the master key and master salt\&. For the master key the last n bits of the SHA256 digest of the passphrase (where n is the length of the master key in bits) is used\&. The master salt gets generated with the SHA1 digest\&. You may force a specific key and or salt by using
326 \fB\-\-key\fR
327 and
328 \fB\-\-salt\fR\&.
329 .RE
330 .PP
331 \fB\-K, \-\-key \fR\fB\fI<master key>\fR\fR
332 .RS 4
333 master key to use for key derivation
334
335 Master key in hexadecimal notation, e\&.g\&. 01a2b3c4d5e6f708a9b0cadbecfd0fa1, with a mandatory length of 32, 48 or 64 characters (128, 192 or 256 bits)\&.
336 .RE
337 .PP
338 \fB\-A, \-\-salt \fR\fB\fI<master salt>\fR\fR
339 .RS 4
340 master salt to use for key derivation
341
342 Master salt in hexadecimal notation, e\&.g\&. 01a2b3c4d5e6f708a9b0cadbecfd, with a mandatory length of 28 characters (14 bytes)\&.
343 .RE
344 .PP
345 \fB\-c, \-\-cipher \fR\fB\fI<cipher type>\fR\fR
346 .RS 4
347 payload encryption algorithm
348
349 Encryption algorithm used for encrypting the payload
350
351 Possible values:
352 .PP
353 \fInull\fR
354 .RS 4
355 no encryption
356 .RE
357 .PP
358 \fIaes\-ctr\fR
359 .RS 4
360 AES in counter mode with 128 Bits, default value
361 .RE
362 .PP
363 \fIaes\-ctr\-128\fR
364 .RS 4
365 AES in counter mode with 128 Bits
366 .RE
367 .PP
368 \fIaes\-ctr\-192\fR
369 .RS 4
370 AES in counter mode with 192 Bits
371 .RE
372 .PP
373 \fIaes\-ctr\-256\fR
374 .RS 4
375 AES in counter mode with 256 Bits
376 .RE
377 .RE
378 .PP
379 \fB\-a, \-\-auth\-algo \fR\fB\fI<algo type>\fR\fR
380 .RS 4
381 message authentication algorithm
382
383 This option sets the message authentication algorithm\&.
384
385 If HMAC\-SHA1 is used, the packet length is increased\&. The additional bytes contain the authentication data\&. see
386 \fB\-\-auth\-tag\-length\fR
387 for more info\&.
388
389 Possible values:
390 .PP
391 \fInull\fR
392 .RS 4
393 no message authentication
394 .RE
395 .PP
396 \fIsha1\fR
397 .RS 4
398 HMAC\-SHA1, default value
399 .RE
400 .RE
401 .PP
402 \fB\-b, \-\-auth\-tag\-length \fR\fB\fI<length>\fR\fR
403 .RS 4
404 The number of bytes to use for the auth tag\&. This value defaults to 10 bytes unless the
405 \fInull\fR
406 auth algo is used in which case it defaults to 0\&.
407 .RE
408 .SH "EXAMPLES"
409 .SS "P2P Setup between two unicast enpoints:"
410 .sp
411 .it 1 an-trap
412 .nr an-no-space-flag 1
413 .nr an-break-flag 1
414 .br
415 .ps +1
416 \fBHost A:\fR
417 .RS 4
418 .sp
419 anytun \-r hostb\&.example\&.com \-t tun \-n 192\&.168\&.123\&.1/30 \-c aes\-ctr\-256 \-k aes\-ctr\-256 \e \-E have_a_very_safe_and_productive_day \-e left
420 .RE
421 .sp
422 .it 1 an-trap
423 .nr an-no-space-flag 1
424 .nr an-break-flag 1
425 .br
426 .ps +1
427 \fBHost B:\fR
428 .RS 4
429 .sp
430 anytun \-r hosta\&.example\&.com \-t tun \-n 192\&.168\&.123\&.2/30 \-c aes\-ctr\-256 \-k aes\-ctr\-256 \e \-E have_a_very_safe_and_productive_day \-e right
431 .RE
432 .SS "One unicast and one anycast tunnel endpoint:"
433 .sp
434 .it 1 an-trap
435 .nr an-no-space-flag 1
436 .nr an-break-flag 1
437 .br
438 .ps +1
439 \fBUnicast tunnel endpoint:\fR
440 .RS 4
441 .sp
442 anytun \-r anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.2/30 \-a null \-c null \-w 0 \-e client
443 .RE
444 .sp
445 .it 1 an-trap
446 .nr an-no-space-flag 1
447 .nr an-break-flag 1
448 .br
449 .ps +1
450 \fBAnycast tunnel endpoints:\fR
451 .RS 4
452 .sp
453 On the host with unicast hostname unicast1\&.anycast\&.anytun\&.org and anycast hostname anycast\&.anytun\&.org:
454 .sp
455 .if n \{\
456 .RS 4
457 .\}
458 .nf
459 # anytun \-i anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.1/30 \-a null \-c null \-w 0 \-e server \e
460          \-S 2342 \-M unicast2\&.anycast\&.anytun\&.org:2342,unicast3\&.anycast\&.anytun\&.org:2342
461 .fi
462 .if n \{\
463 .RE
464 .\}
465 .sp
466 On the host with unicast hostname unicast2\&.anycast\&.anytun\&.org and anycast hostname anycast\&.anytun\&.org:
467 .sp
468 .if n \{\
469 .RS 4
470 .\}
471 .nf
472 # anytun \-i anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.1/30 \-a null \-c null \-w 0 \-e server \e
473          \-S 2342 \-M unicast1\&.anycast\&.anytun\&.org:2342,unicast3\&.anycast\&.anytun\&.org:2342
474 .fi
475 .if n \{\
476 .RE
477 .\}
478 .sp
479 On the host with unicast hostname unicast3\&.anycast\&.anytun\&.org and anycast hostname anycast\&.anytun\&.org:
480 .sp
481 .if n \{\
482 .RS 4
483 .\}
484 .nf
485 # anytun \-i anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.1/30 \-a null \-c null \-w 0 \-e server \e
486          \-S 2342 \-M unicast1\&.anycast\&.anytun\&.org:2342,unicast2\&.anycast\&.anytun\&.org:2342
487 .fi
488 .if n \{\
489 .RE
490 .\}
491 .sp
492 For more sophisticated examples (like multiple unicast endpoints to one anycast tunnel endpoint) please consult the man page of anytun\-config(8)\&.
493 .RE
494 .SH "BUGS"
495 .sp
496 Most likely there are some bugs in \fBAnytun\fR\&. If you find a bug, please let the developers know at satp@anytun\&.org\&. Of course, patches are preferred\&.
497 .SH "SEE ALSO"
498 .sp
499 anytun\-config(8), anytun\-controld(8), anytun\-showtables(8)
500 .SH "AUTHORS"
501 .sp
502 Othmar Gsenger <otti@anytun\&.org> Erwin Nindl <nine@anytun\&.org> Christian Pointner <equinox@anytun\&.org>
503 .SH "RESOURCES"
504 .sp
505 Main web site: http://www\&.anytun\&.org/
506 .SH "COPYING"
507 .sp
508 Copyright (C) 2007\-2009 Othmar Gsenger, Erwin Nindl and Christian Pointner\&. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version\&.