Imported Upstream version 0.3.6
[debian/uanytun.git] / doc / uanytun.8.txt
1 uanytun(8)
2 ==========
3
4 NAME
5 ----
6
7 uanytun - micro anycast tunneling daemon
8
9
10 SYNOPSIS
11 --------
12
13 ....
14 uanytun
15   [ -h|--help ]
16   [ -D|--nodaemonize ]
17   [ -u|--username <username> ]
18   [ -g|--groupname <groupname> ]
19   [ -C|--chroot <path> ]
20   [ -P|--write-pid <filename> ]
21   [ -L|--log <target>:<level>[,<param1>[,<param2>[..]]] ]
22   [ -U|--debug ]
23   [ -i|--interface <ip-address> ]
24   [ -p|--port <port> ]
25   [ -r|--remote-host <hostname|ip> ]
26   [ -o|--remote-port <port> ]
27   [ -4|--ipv4-only ]
28   [ -6|--ipv6-only ]
29   [ -d|--dev <name> ]
30   [ -t|--type <tun|tap> ]
31   [ -n|--ifconfig <local>/<prefix> ]
32   [ -x|--post-up-script <script> ]
33   [ -m|--mux <mux-id> ]
34   [ -s|--sender-id <sender id> ]
35   [ -w|--window-size <window size> ]
36   [ -k|--kd-prf <kd-prf type> ]
37   [ -e|--role <role> ]
38   [ -E|--passphrase <pass phrase> ]
39   [ -K|--key <master key> ]
40   [ -A|--salt <master salt> ]
41   [ -c|--cipher <cipher type> ]
42   [ -a|--auth-algo <algo type> ]
43   [ -b|--auth-tag-length <length> ]
44 ....
45
46
47 DESCRIPTION
48 -----------
49
50 *uAnytun* is a tiny implementation of the Secure Anycast Tunneling Protocol
51 (SATP). It provides a complete VPN solution similar to OpenVPN or
52 IPsec in tunnel mode. The main difference is that anycast enables the
53 setup of tunnels between an arbitrary combination of anycast, unicast
54 and multicast hosts. Unlike Anytun which is a full featured implementation
55 uAnytun has no support for multiple connections or synchronisation. It is a
56 small single threaded implementation intended to act as a client on small
57 platforms.
58
59
60 OPTIONS
61 -------
62
63 *uAnytun* has been designed as a peer to peer application, so there is
64 no difference between client and server. The following options can be
65 passed to the daemon:
66
67 *-D, --nodaemonize*::
68    This option instructs *uAnytun* to run in foreground
69    instead of becoming a daemon which is the default.
70
71 *-u, --username '<username>'*::
72    run as this user. If no group is specified (*-g*) the default group of
73    the user is used. The default is to not drop privileges.
74
75 *-g, --groupname '<groupname>'*::
76    run as this group. If no username is specified (*-u*) this gets ignored.
77    The default is to not drop privileges.
78
79 *-C, --chroot '<path>'*::
80    Instruct *uAnytun* to run in a chroot jail. The default is
81    to not run in chroot.
82
83 *-P, --write-pid <filename>*::
84    Instruct *uAnytun* to write it's pid to this file. The default is
85    to not create a pid file.
86
87 *-L, --log '<target>:<level>[,<param1>[,<param2>[..]]]'*::
88    add log target to logging system. This can be invoked several times
89    in order to log to different targets at the same time. Every target
90    has its own log level which is a number between 0 and 5. Where 0 means
91    disabling log and 5 means debug messages are enabled. +
92    The file target can be used more than once with different levels.
93    If no target is provided at the command line a single target with the
94    config 'syslog:3,uanytun,daemon' is added. +
95    The following targets are supported:
96
97    'syslog';; log to syslog daemon, parameters <level>[,<logname>[,<facility>]]
98    'file';; log to file, parameters <level>[,<path>]
99    'stdout';; log to standard output, parameters <level>
100    'stderr';; log to standard error, parameters <level>
101
102 *-U, --debug*::
103    This option instructs *uAnytun* to run in debug mode. It implicits *-D*
104    (don't daemonize) and adds a log target with the configuration
105    'stdout:5' (logging with maximum level). In future releases there might
106    be additional output when this option is supplied.
107
108 *-i, --interface '<ip address>'*::
109    This IP address is used as the sender address for outgoing
110    packets. The default is to not use a special inteface and just
111    bind on all interfaces.
112
113 *-p, --port '<port>'*::
114    The local UDP port that is used to send and receive the
115    payload data. The two tunnel endpoints can use different
116    ports. default: 4444
117
118 *-r, --remote-host '<hostname|ip>'*::
119    This option can be used to specify the remote tunnel
120    endpoint. In case of anycast tunnel endpoints, the
121    anycast IP address has to be used. If you do not specify
122    an address, it is automatically determined after receiving
123    the first data packet.
124
125 *-o, --remote-port '<port>'*::
126    The UDP port used for payload data by the remote host
127    (specified with -p on the remote host). If you do not specify
128    a port, it is automatically determined after receiving
129    the first data packet.
130
131 *-4, --ipv4-only*::
132    Resolv to IPv4 addresses only. The default is to resolv both
133    IPv4 and IPv6 addresses.
134
135 *-6, --ipv6-only*::
136    Resolv to IPv6 addresses only. The default is to resolv both
137    IPv4 and IPv6 addresses.
138
139 *-d, --dev '<name>'*::
140    device name +
141    By default, tapN is used for Ethernet tunnel interfaces,
142    and tunN for IP tunnels, respectively. This option can
143    be used to manually override these defaults.
144
145 *-t, --type '<tun|tap>'*::
146    device type +
147    Type of the tunnels to create. Use tap for Ethernet
148    tunnels, tun for IP tunnels.
149
150 *-n, --ifconfig '<local>/<prefix>'*::
151    The local IP address and prefix length. The remote tunnel endpoint
152    has to use a different IP address in the same subnet.
153
154    '<local>';; the local IP address for the tun/tap device
155    '<prefix>';; the prefix length of the network
156
157 *-x, --post-up-script '<script>'*::
158    This option instructs *uAnytun* to run this script after the interface
159    is created. By default no script will be executed.
160
161 *-m, --mux '<mux-id>'*::
162    the multiplex id to use. default: 0
163
164 *-s, --sender-id '<sender id>'*::
165    Each anycast tunnel endpoint needs a unique sender id
166    (1, 2, 3, ...). It is needed to distinguish the senders
167    in case of replay attacks. As *uAnytun* does not support
168    synchronisation it can't be used as an anycast endpoint therefore
169    this option is quite useless but implemented for compatibility
170    reasons. default: 0
171
172 *-w, --window-size '<window size>'*::
173    seqence window size +
174    Sometimes, packets arrive out of order on the receiver
175    side. This option defines the size of a list of received
176    packets' sequence numbers. If, according to this list,
177    a received packet has been previously received or has
178    been transmitted in the past, and is therefore not in
179    the list anymore, this is interpreted as a replay attack
180    and the packet is dropped. A value of 0 deactivates this
181    list and, as a consequence, the replay protection employed
182    by filtering packets according to their secuence number.
183    By default the sequence window is disabled and therefore a
184    window size of 0 is used.
185
186 *-k, --kd--prf '<kd-prf type>'*::
187    key derivation pseudo random function +
188    The pseudo random function which is used for calculating the
189    session keys and session salt. +
190    Possible values:
191
192    'null';; no random function, keys and salt are set to 0..00
193    'aes-ctr';; AES in counter mode with 128 Bits, default value
194    'aes-ctr-128';; AES in counter mode with 128 Bits
195    'aes-ctr-192';; AES in counter mode with 192 Bits
196    'aes-ctr-256';; AES in counter mode with 256 Bits
197
198 *-e, --role '<role>'*::
199    SATP uses different session keys for inbound and outbound traffic. The
200    role parameter is used to determine which keys to use for outbound or
201    inbound packets. On both sides of a vpn connection different roles have
202    to be used. Possible values are 'left' and 'right'. You may also use
203    'alice' or 'server' as a replacement for 'left' and 'bob' or 'client' as
204    a replacement for 'right'. By default 'left' is used.
205
206 *-E, --passphrase '<pass phrase>'*::
207    This passphrase is used to generate the master key and master salt.
208    For the master key the last n bits of the SHA256 digest of the
209    passphrase (where n is the length of the master key in bits) is used.
210    The master salt gets generated with the SHA1 digest.
211    You may force a specific key and or salt by using *--key* and *--salt*.
212
213 *-K, --key '<master key>'*::
214    master key to use for key derivation +
215    Master key in hexadecimal notation, e.g.
216    01a2b3c4d5e6f708a9b0cadbecfd0fa1, with a mandatory length
217    of 32, 48 or 64 characters (128, 192 or 256 bits).
218
219 *-A, --salt '<master salt>'*::
220    master salt to use for key derivation +
221    Master salt in hexadecimal notation, e.g.
222    01a2b3c4d5e6f708a9b0cadbecfd, with a mandatory length
223    of 28 characters (14 bytes).
224
225 *-c, --cipher '<cipher type>'*::
226    payload encryption algorithm +
227    Encryption algorithm used for encrypting the payload +
228    Possible values:
229
230    'null';; no encryption
231    'aes-ctr';; AES in counter mode with 128 Bits, default value
232    'aes-ctr-128';; AES in counter mode with 128 Bits
233    'aes-ctr-192';; AES in counter mode with 192 Bits
234    'aes-ctr-256';; AES in counter mode with 256 Bits
235
236 *-a, --auth-algo '<algo type>'*::
237    message authentication algorithm +
238    This option sets the message authentication algorithm. +
239    If HMAC-SHA1 is used, the packet length is increased. The additional bytes
240    contain the authentication data. see *--auth-tag-length* for more info. +
241    Possible values:
242
243    'null';; no message authentication
244    'sha1';; HMAC-SHA1, default value
245
246 *-b, --auth-tag-length '<length>'*::
247    The number of bytes to use for the auth tag. This value defaults to 10 bytes
248    unless the 'null' auth algo is used in which case it defaults to 0.
249
250
251 EXAMPLES
252 --------
253
254 P2P Setup between two unicast enpoints:
255 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
256
257 Host A:
258 ^^^^^^^
259
260 uanytun -r hostb.example.com -t tun -n 192.168.123.1/30 -c aes-ctr-256 -k aes-ctr-256
261         -E have_a_very_safe_and_productive_day -e left
262
263 Host B:
264 ^^^^^^^
265 uanytun -r hosta.example.com -t tun -n 192.168.123.2/30 -c aes-ctr-256 -k aes-ctr-256
266         -E have_a_very_safe_and_productive_day -e right
267
268
269 One unicast and one anycast tunnel endpoint:
270 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
271
272 Unicast tunnel endpoint:
273 ^^^^^^^^^^^^^^^^^^^^^^^^
274
275 uanytun -r anycast.anytun.org -d anytun0 -t tun -n 192.0.2.2/30 -a null -c null -w 0 -e client
276
277 Anycast tunnel endpoints:
278 ^^^^^^^^^^^^^^^^^^^^^^^^^
279 As *uAnytun* can't work as an anycast endpoint it can't be used for this purpose. You
280 have to use *Anytun* for that job.
281
282
283 BUGS
284 ----
285
286 Most likely there are some bugs in *uAnytun*. If you find a bug, please let
287 the developers know at uanytun@anytun.org. Of course, patches are preferred.
288
289
290 AUTHORS
291 -------
292
293 Christian Pointner <equinox@anytun.org>
294
295
296 RESOURCES
297 ---------
298
299 Main web site: http://www.anytun.org/
300
301
302 COPYING
303 -------
304
305 Copyright \(C) 2008-2014 Christian Pointner. This  program is  free
306 software: you can redistribute it and/or modify it under the terms
307 of the GNU General Public License as published by the Free Software
308 Foundation, either version 3 of the License, or any later version.