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.