src/man/anytun.8.txt

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