Imported Upstream version 0.3.6
[debian/uanytun.git] / doc / uanytun.8
1 '\" t
2 .\"     Title: uanytun
3 .\"    Author: [see the "AUTHORS" section]
4 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
5 .\"      Date: 01/04/2017
6 .\"    Manual: \ \&
7 .\"    Source: \ \&
8 .\"  Language: English
9 .\"
10 .TH "UANYTUN" "8" "01/04/2017" "\ \&" "\ \&"
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 uanytun \- micro anycast tunneling daemon
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 \fBuanytun\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\-d|\-\-dev\fR <name> ]
51   [ \fB\-t|\-\-type\fR <tun|tap> ]
52   [ \fB\-n|\-\-ifconfig\fR <local>/<prefix> ]
53   [ \fB\-x|\-\-post\-up\-script\fR <script> ]
54   [ \fB\-m|\-\-mux\fR <mux\-id> ]
55   [ \fB\-s|\-\-sender\-id\fR <sender id> ]
56   [ \fB\-w|\-\-window\-size\fR <window size> ]
57   [ \fB\-k|\-\-kd\-prf\fR <kd\-prf type> ]
58   [ \fB\-e|\-\-role\fR <role> ]
59   [ \fB\-E|\-\-passphrase\fR <pass phrase> ]
60   [ \fB\-K|\-\-key\fR <master key> ]
61   [ \fB\-A|\-\-salt\fR <master salt> ]
62   [ \fB\-c|\-\-cipher\fR <cipher type> ]
63   [ \fB\-a|\-\-auth\-algo\fR <algo type> ]
64   [ \fB\-b|\-\-auth\-tag\-length\fR <length> ]
65 .fi
66 .SH "DESCRIPTION"
67 .sp
68 \fBuAnytun\fR is a tiny 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 enables the setup of tunnels between an arbitrary combination of anycast, unicast and multicast hosts\&. Unlike Anytun which is a full featured implementation uAnytun has no support for multiple connections or synchronisation\&. It is a small single threaded implementation intended to act as a client on small platforms\&.
69 .SH "OPTIONS"
70 .sp
71 \fBuAnytun\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:
72 .PP
73 \fB\-D, \-\-nodaemonize\fR
74 .RS 4
75 This option instructs
76 \fBuAnytun\fR
77 to run in foreground instead of becoming a daemon which is the default\&.
78 .RE
79 .PP
80 \fB\-u, \-\-username \fR\fB\fI<username>\fR\fR
81 .RS 4
82 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\&.
83 .RE
84 .PP
85 \fB\-g, \-\-groupname \fR\fB\fI<groupname>\fR\fR
86 .RS 4
87 run as this group\&. If no username is specified (\fB\-u\fR) this gets ignored\&. The default is to not drop privileges\&.
88 .RE
89 .PP
90 \fB\-C, \-\-chroot \fR\fB\fI<path>\fR\fR
91 .RS 4
92 Instruct
93 \fBuAnytun\fR
94 to run in a chroot jail\&. The default is to not run in chroot\&.
95 .RE
96 .PP
97 \fB\-P, \-\-write\-pid <filename>\fR
98 .RS 4
99 Instruct
100 \fBuAnytun\fR
101 to write it\(cqs pid to this file\&. The default is to not create a pid file\&.
102 .RE
103 .PP
104 \fB\-L, \-\-log \fR\fB\fI<target>:<level>[,<param1>[,<param2>[\&.\&.]]]\fR\fR
105 .RS 4
106 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 has its own log level which is a number between 0 and 5\&. Where 0 means disabling log and 5 means debug messages are enabled\&.
107
108 The file target can be used more than once with different levels\&. If no target is provided at the command line a single target with the config
109 \fIsyslog:3,uanytun,daemon\fR
110 is added\&.
111
112 The following targets are supported:
113 .PP
114 \fIsyslog\fR
115 .RS 4
116 log to syslog daemon, parameters <level>[,<logname>[,<facility>]]
117 .RE
118 .PP
119 \fIfile\fR
120 .RS 4
121 log to file, parameters <level>[,<path>]
122 .RE
123 .PP
124 \fIstdout\fR
125 .RS 4
126 log to standard output, parameters <level>
127 .RE
128 .PP
129 \fIstderr\fR
130 .RS 4
131 log to standard error, parameters <level>
132 .RE
133 .RE
134 .PP
135 \fB\-U, \-\-debug\fR
136 .RS 4
137 This option instructs
138 \fBuAnytun\fR
139 to run in debug mode\&. It implicits
140 \fB\-D\fR
141 (don\(cqt daemonize) and adds a log target with the configuration
142 \fIstdout:5\fR
143 (logging with maximum level)\&. In future releases there might be additional output when this option is supplied\&.
144 .RE
145 .PP
146 \fB\-i, \-\-interface \fR\fB\fI<ip address>\fR\fR
147 .RS 4
148 This IP address is used as the sender address for outgoing packets\&. The default is to not use a special inteface and just bind on all interfaces\&.
149 .RE
150 .PP
151 \fB\-p, \-\-port \fR\fB\fI<port>\fR\fR
152 .RS 4
153 The local UDP port that is used to send and receive the payload data\&. The two tunnel endpoints can use different ports\&. default: 4444
154 .RE
155 .PP
156 \fB\-r, \-\-remote\-host \fR\fB\fI<hostname|ip>\fR\fR
157 .RS 4
158 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\&.
159 .RE
160 .PP
161 \fB\-o, \-\-remote\-port \fR\fB\fI<port>\fR\fR
162 .RS 4
163 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\&.
164 .RE
165 .PP
166 \fB\-4, \-\-ipv4\-only\fR
167 .RS 4
168 Resolv to IPv4 addresses only\&. The default is to resolv both IPv4 and IPv6 addresses\&.
169 .RE
170 .PP
171 \fB\-6, \-\-ipv6\-only\fR
172 .RS 4
173 Resolv to IPv6 addresses only\&. The default is to resolv both IPv4 and IPv6 addresses\&.
174 .RE
175 .PP
176 \fB\-d, \-\-dev \fR\fB\fI<name>\fR\fR
177 .RS 4
178 device name
179
180 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\&.
181 .RE
182 .PP
183 \fB\-t, \-\-type \fR\fB\fI<tun|tap>\fR\fR
184 .RS 4
185 device type
186
187 Type of the tunnels to create\&. Use tap for Ethernet tunnels, tun for IP tunnels\&.
188 .RE
189 .PP
190 \fB\-n, \-\-ifconfig \fR\fB\fI<local>/<prefix>\fR\fR
191 .RS 4
192 The local IP address and prefix length\&. The remote tunnel endpoint has to use a different IP address in the same subnet\&.
193 .PP
194 \fI<local>\fR
195 .RS 4
196 the local IP address for the tun/tap device
197 .RE
198 .PP
199 \fI<prefix>\fR
200 .RS 4
201 the prefix length of the network
202 .RE
203 .RE
204 .PP
205 \fB\-x, \-\-post\-up\-script \fR\fB\fI<script>\fR\fR
206 .RS 4
207 This option instructs
208 \fBuAnytun\fR
209 to run this script after the interface is created\&. By default no script will be executed\&.
210 .RE
211 .PP
212 \fB\-m, \-\-mux \fR\fB\fI<mux\-id>\fR\fR
213 .RS 4
214 the multiplex id to use\&. default: 0
215 .RE
216 .PP
217 \fB\-s, \-\-sender\-id \fR\fB\fI<sender id>\fR\fR
218 .RS 4
219 Each anycast tunnel endpoint needs a unique sender id (1, 2, 3, \&...)\&. It is needed to distinguish the senders in case of replay attacks\&. As
220 \fBuAnytun\fR
221 does not support synchronisation it can\(cqt be used as an anycast endpoint therefore this option is quite useless but implemented for compatibility reasons\&. default: 0
222 .RE
223 .PP
224 \fB\-w, \-\-window\-size \fR\fB\fI<window size>\fR\fR
225 .RS 4
226 seqence window size
227
228 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\&.
229 .RE
230 .PP
231 \fB\-k, \-\-kd\(emprf \fR\fB\fI<kd\-prf type>\fR\fR
232 .RS 4
233 key derivation pseudo random function
234
235 The pseudo random function which is used for calculating the session keys and session salt\&.
236
237 Possible values:
238 .PP
239 \fInull\fR
240 .RS 4
241 no random function, keys and salt are set to 0\&.\&.00
242 .RE
243 .PP
244 \fIaes\-ctr\fR
245 .RS 4
246 AES in counter mode with 128 Bits, default value
247 .RE
248 .PP
249 \fIaes\-ctr\-128\fR
250 .RS 4
251 AES in counter mode with 128 Bits
252 .RE
253 .PP
254 \fIaes\-ctr\-192\fR
255 .RS 4
256 AES in counter mode with 192 Bits
257 .RE
258 .PP
259 \fIaes\-ctr\-256\fR
260 .RS 4
261 AES in counter mode with 256 Bits
262 .RE
263 .RE
264 .PP
265 \fB\-e, \-\-role \fR\fB\fI<role>\fR\fR
266 .RS 4
267 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
268 \fIleft\fR
269 and
270 \fIright\fR\&. You may also use
271 \fIalice\fR
272 or
273 \fIserver\fR
274 as a replacement for
275 \fIleft\fR
276 and
277 \fIbob\fR
278 or
279 \fIclient\fR
280 as a replacement for
281 \fIright\fR\&. By default
282 \fIleft\fR
283 is used\&.
284 .RE
285 .PP
286 \fB\-E, \-\-passphrase \fR\fB\fI<pass phrase>\fR\fR
287 .RS 4
288 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
289 \fB\-\-key\fR
290 and
291 \fB\-\-salt\fR\&.
292 .RE
293 .PP
294 \fB\-K, \-\-key \fR\fB\fI<master key>\fR\fR
295 .RS 4
296 master key to use for key derivation
297
298 Master key in hexadecimal notation, e\&.g\&. 01a2b3c4d5e6f708a9b0cadbecfd0fa1, with a mandatory length of 32, 48 or 64 characters (128, 192 or 256 bits)\&.
299 .RE
300 .PP
301 \fB\-A, \-\-salt \fR\fB\fI<master salt>\fR\fR
302 .RS 4
303 master salt to use for key derivation
304
305 Master salt in hexadecimal notation, e\&.g\&. 01a2b3c4d5e6f708a9b0cadbecfd, with a mandatory length of 28 characters (14 bytes)\&.
306 .RE
307 .PP
308 \fB\-c, \-\-cipher \fR\fB\fI<cipher type>\fR\fR
309 .RS 4
310 payload encryption algorithm
311
312 Encryption algorithm used for encrypting the payload
313
314 Possible values:
315 .PP
316 \fInull\fR
317 .RS 4
318 no encryption
319 .RE
320 .PP
321 \fIaes\-ctr\fR
322 .RS 4
323 AES in counter mode with 128 Bits, default value
324 .RE
325 .PP
326 \fIaes\-ctr\-128\fR
327 .RS 4
328 AES in counter mode with 128 Bits
329 .RE
330 .PP
331 \fIaes\-ctr\-192\fR
332 .RS 4
333 AES in counter mode with 192 Bits
334 .RE
335 .PP
336 \fIaes\-ctr\-256\fR
337 .RS 4
338 AES in counter mode with 256 Bits
339 .RE
340 .RE
341 .PP
342 \fB\-a, \-\-auth\-algo \fR\fB\fI<algo type>\fR\fR
343 .RS 4
344 message authentication algorithm
345
346 This option sets the message authentication algorithm\&.
347
348 If HMAC\-SHA1 is used, the packet length is increased\&. The additional bytes contain the authentication data\&. see
349 \fB\-\-auth\-tag\-length\fR
350 for more info\&.
351
352 Possible values:
353 .PP
354 \fInull\fR
355 .RS 4
356 no message authentication
357 .RE
358 .PP
359 \fIsha1\fR
360 .RS 4
361 HMAC\-SHA1, default value
362 .RE
363 .RE
364 .PP
365 \fB\-b, \-\-auth\-tag\-length \fR\fB\fI<length>\fR\fR
366 .RS 4
367 The number of bytes to use for the auth tag\&. This value defaults to 10 bytes unless the
368 \fInull\fR
369 auth algo is used in which case it defaults to 0\&.
370 .RE
371 .SH "EXAMPLES"
372 .SS "P2P Setup between two unicast enpoints:"
373 .sp
374 .it 1 an-trap
375 .nr an-no-space-flag 1
376 .nr an-break-flag 1
377 .br
378 .ps +1
379 \fBHost A:\fR
380 .RS 4
381 .sp
382 uanytun \-r hostb\&.example\&.com \-t tun \-n 192\&.168\&.123\&.1/30 \-c aes\-ctr\-256 \-k aes\-ctr\-256 \-E have_a_very_safe_and_productive_day \-e left
383 .RE
384 .sp
385 .it 1 an-trap
386 .nr an-no-space-flag 1
387 .nr an-break-flag 1
388 .br
389 .ps +1
390 \fBHost B:\fR
391 .RS 4
392 .sp
393 uanytun \-r hosta\&.example\&.com \-t tun \-n 192\&.168\&.123\&.2/30 \-c aes\-ctr\-256 \-k aes\-ctr\-256 \-E have_a_very_safe_and_productive_day \-e right
394 .RE
395 .SS "One unicast and one anycast tunnel endpoint:"
396 .sp
397 .it 1 an-trap
398 .nr an-no-space-flag 1
399 .nr an-break-flag 1
400 .br
401 .ps +1
402 \fBUnicast tunnel endpoint:\fR
403 .RS 4
404 .sp
405 uanytun \-r anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.2/30 \-a null \-c null \-w 0 \-e client
406 .RE
407 .sp
408 .it 1 an-trap
409 .nr an-no-space-flag 1
410 .nr an-break-flag 1
411 .br
412 .ps +1
413 \fBAnycast tunnel endpoints:\fR
414 .RS 4
415 .sp
416 As \fBuAnytun\fR can\(cqt work as an anycast endpoint it can\(cqt be used for this purpose\&. You have to use \fBAnytun\fR for that job\&.
417 .RE
418 .SH "BUGS"
419 .sp
420 Most likely there are some bugs in \fBuAnytun\fR\&. If you find a bug, please let the developers know at uanytun@anytun\&.org\&. Of course, patches are preferred\&.
421 .SH "AUTHORS"
422 .sp
423 Christian Pointner <equinox@anytun\&.org>
424 .SH "RESOURCES"
425 .sp
426 Main web site: http://www\&.anytun\&.org/
427 .SH "COPYING"
428 .sp
429 Copyright (C) 2008\-2014 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\&.