doc/uanytun.8.txt

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