doc/anytun.8

   1 '\" t
   2 .\"     Title: anytun
   3 .\"    Author: [see the "AUTHORS" section]
   4 .\" Generator: DocBook XSL Stylesheets v1.75.1 <http://docbook.sf.net/>
   5 .\"      Date: 02/16/2010
   6 .\"    Manual: anytun user manual
   7 .\"    Source: anytun 0.3.3
   8 .\"  Language: English
   9 .\"
  10 .TH "ANYTUN" "8" "02/16/2010" "anytun 0.3.3" "anytun user manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * set default formatting
  13 .\" -----------------------------------------------------------------
  14 .\" disable hyphenation
  15 .nh
  16 .\" disable justification (adjust text to left margin only)
  17 .ad l
  18 .\" -----------------------------------------------------------------
  19 .\" * MAIN CONTENT STARTS HERE *
  20 .\" -----------------------------------------------------------------
  21 .SH "NAME"
  22 anytun \- anycast tunneling daemon
  23 .SH "SYNOPSIS"
  24 .sp
  25 .nf
  26 \fBanytun\fR
  27   [ \fB\-h|\-\-help\fR ]
  28   [ \fB\-D|\-\-nodaemonize\fR ]
  29   [ \fB\-u|\-\-username\fR <username> ]
  30   [ \fB\-g|\-\-groupname\fR <groupname> ]
  31   [ \fB\-C|\-\-chroot\fR <path> ]
  32   [ \fB\-P|\-\-write\-pid\fR <filename> ]
  33   [ \fB\-L|\-\-log\fR <target>:<level>[,<param1>[,<param2>[\&.\&.]]] ]
  34   [ \fB\-U|\-\-debug\fR ]
  35   [ \fB\-i|\-\-interface\fR <ip\-address> ]
  36   [ \fB\-p|\-\-port\fR <port> ]
  37   [ \fB\-r|\-\-remote\-host\fR <hostname|ip> ]
  38   [ \fB\-o|\-\-remote\-port\fR <port> ]
  39   [ \fB\-4|\-\-ipv4\-only\fR ]
  40   [ \fB\-6|\-\-ipv6\-only\fR ]
  41   [ \fB\-I|\-\-sync\-interface\fR <ip\-address> ]
  42   [ \fB\-S|\-\-sync\-port\fR port> ]
  43   [ \fB\-M|\-\-sync\-hosts\fR <hostname|ip>[:<port>][,<hostname|ip>[:<port>][\&.\&.\&.]] ]
  44   [ \fB\-X|\-\-control\-host\fR <hostname|ip>[:<port>]
  45   [ \fB\-d|\-\-dev\fR <name> ]
  46   [ \fB\-t|\-\-type\fR <tun|tap> ]
  47   [ \fB\-n|\-\-ifconfig\fR <local>/<prefix> ]
  48   [ \fB\-x|\-\-post\-up\-script\fR <script> ]
  49   [ \fB\-R|\-\-route\fR <net>/<prefix length> ]
  50   [ \fB\-m|\-\-mux\fR <mux\-id> ]
  51   [ \fB\-s|\-\-sender\-id\fR <sender id> ]
  52   [ \fB\-w|\-\-window\-size\fR <window size> ]
  53   [ \fB\-k|\-\-kd\-prf\fR <kd\-prf type> ]
  54   [ \fB\-e|\-\-role\fR <role> ]
  55   [ \fB\-E|\-\-passphrase\fR <pass phrase> ]
  56   [ \fB\-K|\-\-key\fR <master key> ]
  57   [ \fB\-A|\-\-salt\fR <master salt> ]
  58   [ \fB\-c|\-\-cipher\fR <cipher type> ]
  59   [ \fB\-a|\-\-auth\-algo\fR <algo type> ]
  60   [ \fB\-b|\-\-auth\-tag\-length\fR <length> ]
  61 .fi
  62 .SH "DESCRIPTION"
  63 .sp
  64 \fBAnytun\fR is an 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 allows a setup of tunnels between an arbitrary combination of anycast, unicast and multicast hosts\&.
  65 .SH "OPTIONS"
  66 .sp
  67 \fBAnytun\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:
  68 .PP
  69 \fB\-D, \-\-nodaemonize\fR
  70 .RS 4
  71 This option instructs
  72 \fBAnytun\fR
  73 to run in foreground instead of becoming a daemon which is the default\&.
  74 .RE
  75 .PP
  76 \fB\-u, \-\-username \fR\fB\fI<username>\fR\fR
  77 .RS 4
  78 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\&.
  79 .RE
  80 .PP
  81 \fB\-g, \-\-groupname \fR\fB\fI<groupname>\fR\fR
  82 .RS 4
  83 run as this group\&. If no username is specified (\fB\-u\fR) this gets ignored\&. The default is to not drop privileges\&.
  84 .RE
  85 .PP
  86 \fB\-C, \-\-chroot \fR\fB\fI<path>\fR\fR
  87 .RS 4
  88 Instruct
  89 \fBAnytun\fR
  90 to run in a chroot jail\&. The default is to not run in chroot\&.
  91 .RE
  92 .PP
  93 \fB\-P, \-\-write\-pid \fR\fB\fI<filename>\fR\fR
  94 .RS 4
  95 Instruct
  96 \fBAnytun\fR
  97 to write it\(cqs pid to this file\&. The default is to not create a pid file\&.
  98 .RE
  99 .PP
 100 \fB\-L, \-\-log \fR\fB\fI<target>:<level>[,<param1>[,<param2>[\&.\&.]]]\fR\fR
 101 .RS 4
 102 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 hast its own log level which is a number between 0 and 5\&. Where 0 means disabling log and 5 means debug messages are enabled\&.
 103
 104 The file target can be used more the once with different levels\&. If no target is provided at the command line a single target with the config
 105 \fIsyslog:3,anytun,daemon\fR
 106 is added\&.
 107
 108 The following targets are supported:
 109 .PP
 110 \fIsyslog\fR
 111 .RS 4
 112 log to syslog daemon, parameters <level>[,<logname>[,<facility>]]
 113 .RE
 114 .PP
 115 \fIfile\fR
 116 .RS 4
 117 log to file, parameters <level>[,<path>]
 118 .RE
 119 .PP
 120 \fIstdout\fR
 121 .RS 4
 122 log to standard output, parameters <level>
 123 .RE
 124 .PP
 125 \fIstderr\fR
 126 .RS 4
 127 log to standard error, parameters <level>
 128 .RE
 129 .RE
 130 .PP
 131 \fB\-U, \-\-debug\fR
 132 .RS 4
 133 This option instructs
 134 \fBAnytun\fR
 135 to run in debug mode\&. It implicits
 136 \fB\-D\fR
 137 (don\(cqt daemonize) and adds a log target with the configuration
 138 \fIstdout:5\fR
 139 (logging with maximum level)\&. In future releases there might be additional output when this option is supplied\&.
 140 .RE
 141 .PP
 142 \fB\-i, \-\-interface \fR\fB\fI<ip address>\fR\fR
 143 .RS 4
 144 This IP address is used as the sender address for outgoing packets\&. In case of anycast tunnel endpoints, the anycast IP has to be used\&. In case of unicast endpoints, the address is usually derived correctly from the routing table\&. The default is to not use a special inteface and just bind on all interfaces\&.
 145 .RE
 146 .PP
 147 \fB\-p, \-\-port \fR\fB\fI<port>\fR\fR
 148 .RS 4
 149 The local UDP port that is used to send and receive the payload data\&. The two tunnel endpoints can use different ports\&. If a tunnel endpoint consists of multiple anycast hosts, all hosts have to use the same port\&. default: 4444
 150 .RE
 151 .PP
 152 \fB\-r, \-\-remote\-host \fR\fB\fI<hostname|ip>\fR\fR
 153 .RS 4
 154 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\&.
 155 .RE
 156 .PP
 157 \fB\-o, \-\-remote\-port \fR\fB\fI<port>\fR\fR
 158 .RS 4
 159 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\&.
 160 .RE
 161 .PP
 162 \fB\-4, \-\-ipv4\-only\fR
 163 .RS 4
 164 Resolv to IPv4 addresses only\&. The default is to resolv both IPv4 and IPv6 addresses\&.
 165 .RE
 166 .PP
 167 \fB\-6, \-\-ipv6\-only\fR
 168 .RS 4
 169 Resolv to IPv6 addresses only\&. The default is to resolv both IPv4 and IPv6 addresses\&.
 170 .RE
 171 .PP
 172 \fB\-I, \-\-sync\-interface \fR\fB\fI<ip\-address>\fR\fR
 173 .RS 4
 174 local unicast(sync) ip address to bind to
 175
 176 This option is only needed for tunnel endpoints consisting of multiple anycast hosts\&. The unicast IP address of the anycast host can be used here\&. This is needed for communication with the other anycast hosts\&. The default is to not use a special inteface and just bind on all interfaces\&. However this is only the case if synchronisation is active see
 177 \fB\-\-sync\-port\fR\&.
 178 .RE
 179 .PP
 180 \fB\-S, \-\-sync\-port \fR\fB\fI<port>\fR\fR
 181 .RS 4
 182 local unicast(sync) port to bind to
 183
 184 This option is only needed for tunnel endpoints consisting of multiple anycast hosts\&. This port is used by anycast hosts to synchronize information about tunnel endpoints\&. No payload data is transmitted via this port\&. By default the synchronisation is disabled an therefore the port is kept empty\&.
 185
 186 It is possible to obtain a list of active connections by telnetting into this port\&. This port is read\-only and unprotected by default\&. It is advised to protect this port using firewall rules and, eventually, IPsec\&.
 187 .RE
 188 .PP
 189 \fB\-M, \-\-sync\-hosts \fR\fB\fI<hostname|ip>[:<port>],[<hostname|ip>[:<port>][\&...]]\fR\fR
 190 .RS 4
 191 remote hosts to sync with
 192
 193 This option is only needed for tunnel endpoints consisting of multiple anycast hosts\&. Here, one has to specify all unicast IP addresses of all other anycast hosts that comprise the anycast tunnel endpoint\&. By default synchronisation is disabled and therefore this is empty\&. Mind that the port can be omitted in which case port 2323 is used\&. If you want to specify an ipv6 address and a port you have to use [ and ] to separate the address from the port, eg\&.: [::1]:1234\&. If you want to use the default port [ and ] can be omitted\&.
 194 .RE
 195 .PP
 196 \fB\-X, \-\-control\-host \fR\fB\fI<hostname|ip>[:<port>]\fR\fR
 197 .RS 4
 198 fetch the config from this host\&. The default is not to use a control host and therefore this is empty\&. Mind that the port can be omitted in which case port 2323 is used\&. If you want to specify an ipv6 address and a port you have to use [ and ] to separate the address from the port, eg\&.: [::1]:1234\&. If you want to use the default port [ and ] can be omitted\&.
 199 .RE
 200 .PP
 201 \fB\-d, \-\-dev \fR\fB\fI<name>\fR\fR
 202 .RS 4
 203 device name
 204
 205 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\&.
 206 .RE
 207 .PP
 208 \fB\-t, \-\-type \fR\fB\fI<tun|tap>\fR\fR
 209 .RS 4
 210 device type
 211
 212 Type of the tunnels to create\&. Use tap for Ethernet tunnels, tun for IP tunnels\&.
 213 .RE
 214 .PP
 215 \fB\-n, \-\-ifconfig \fR\fB\fI<local>/<prefix>\fR\fR
 216 .RS 4
 217 The local IP address and prefix length\&. The remote tunnel endpoint has to use a different IP address in the same subnet\&.
 218 .PP
 219 \fI<local>\fR
 220 .RS 4
 221 the local IP address for the tun/tap device
 222 .RE
 223 .PP
 224 \fI<prefix>\fR
 225 .RS 4
 226 the prefix length of the network
 227 .RE
 228 .RE
 229 .PP
 230 \fB\-x, \-\-post\-up\-script \fR\fB\fI<script>\fR\fR
 231 .RS 4
 232 This option instructs
 233 \fBAnytun\fR
 234 to run this script after the interface is created\&. By default no script will be executed\&.
 235 .RE
 236 .PP
 237 \fB\-R, \-\-route \fR\fB\fI<net>/<prefix length>\fR\fR
 238 .RS 4
 239 add a route to connection\&. This can be invoked several times\&.
 240 .RE
 241 .PP
 242 \fB\-m, \-\-mux \fR\fB\fI<mux\-id>\fR\fR
 243 .RS 4
 244 the multiplex id to use\&. default: 0
 245 .RE
 246 .PP
 247 \fB\-s, \-\-sender\-id \fR\fB\fI<sender id>\fR\fR
 248 .RS 4
 249 Each anycast tunnel endpoint needs a uniqe sender id (1, 2, 3, \&...)\&. It is needed to distinguish the senders in case of replay attacks\&. This option can be ignored on unicast endpoints\&. default: 0
 250 .RE
 251 .PP
 252 \fB\-w, \-\-window\-size \fR\fB\fI<window size>\fR\fR
 253 .RS 4
 254 seqence window size
 255
 256 Sometimes, packets arrive out of order on the receiver side\&. This option defines the size of a list of received packets\' 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\&.
 257 .RE
 258 .PP
 259 \fB\-k, \-\-kd\(emprf \fR\fB\fI<kd\-prf type>\fR\fR
 260 .RS 4
 261 key derivation pseudo random function
 262
 263 The pseudo random function which is used for calculating the session keys and session salt\&.
 264
 265 Possible values:
 266 .PP
 267 \fInull\fR
 268 .RS 4
 269 no random function, keys and salt are set to 0\&.\&.00
 270 .RE
 271 .PP
 272 \fIaes\-ctr\fR
 273 .RS 4
 274 AES in counter mode with 128 Bits, default value
 275 .RE
 276 .PP
 277 \fIaes\-ctr\-128\fR
 278 .RS 4
 279 AES in counter mode with 128 Bits
 280 .RE
 281 .PP
 282 \fIaes\-ctr\-192\fR
 283 .RS 4
 284 AES in counter mode with 192 Bits
 285 .RE
 286 .PP
 287 \fIaes\-ctr\-256\fR
 288 .RS 4
 289 AES in counter mode with 256 Bits
 290 .RE
 291 .RE
 292 .PP
 293 \fB\-e, \-\-role \fR\fB\fI<role>\fR\fR
 294 .RS 4
 295 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
 296 \fIleft\fR
 297 and
 298 \fIright\fR\&. You may also use
 299 \fIalice\fR
 300 or
 301 \fIserver\fR
 302 as a replacement for
 303 \fIleft\fR
 304 and
 305 \fIbob\fR
 306 or
 307 \fIclient\fR
 308 as a replacement for
 309 \fIright\fR\&. By default
 310 \fIleft\fR
 311 is used\&.
 312 .RE
 313 .PP
 314 \fB\-E, \-\-passphrase \fR\fB\fI<passphrase>\fR\fR
 315 .RS 4
 316 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
 317 \fB\-\-key\fR
 318 and
 319 \fB\-\-salt\fR\&.
 320 .RE
 321 .PP
 322 \fB\-K, \-\-key \fR\fB\fI<master key>\fR\fR
 323 .RS 4
 324 master key to use for key derivation
 325
 326 Master key in hexadecimal notation, e\&.g\&. 01a2b3c4d5e6f708a9b0cadbecfd0fa1, with a mandatory length of 32, 48 or 64 characters (128, 192 or 256 bits)\&.
 327 .RE
 328 .PP
 329 \fB\-A, \-\-salt \fR\fB\fI<master salt>\fR\fR
 330 .RS 4
 331 master salt to use for key derivation
 332
 333 Master salt in hexadecimal notation, e\&.g\&. 01a2b3c4d5e6f708a9b0cadbecfd, with a mandatory length of 28 characters (14 bytes)\&.
 334 .RE
 335 .PP
 336 \fB\-c, \-\-cipher \fR\fB\fI<cipher type>\fR\fR
 337 .RS 4
 338 payload encryption algorithm
 339
 340 Encryption algorithm used for encrypting the payload
 341
 342 Possible values:
 343 .PP
 344 \fInull\fR
 345 .RS 4
 346 no encryption
 347 .RE
 348 .PP
 349 \fIaes\-ctr\fR
 350 .RS 4
 351 AES in counter mode with 128 Bits, default value
 352 .RE
 353 .PP
 354 \fIaes\-ctr\-128\fR
 355 .RS 4
 356 AES in counter mode with 128 Bits
 357 .RE
 358 .PP
 359 \fIaes\-ctr\-192\fR
 360 .RS 4
 361 AES in counter mode with 192 Bits
 362 .RE
 363 .PP
 364 \fIaes\-ctr\-256\fR
 365 .RS 4
 366 AES in counter mode with 256 Bits
 367 .RE
 368 .RE
 369 .PP
 370 \fB\-a, \-\-auth\-algo \fR\fB\fI<algo type>\fR\fR
 371 .RS 4
 372 message authentication algorithm
 373
 374 This option sets the message authentication algorithm\&.
 375
 376 If HMAC\-SHA1 is used, the packet length is increased\&. The additional bytes contain the authentication data\&. see
 377 \fB\-\-auth\-tag\-length\fR
 378 for more info\&.
 379
 380 Possible values:
 381 .PP
 382 \fInull\fR
 383 .RS 4
 384 no message authentication
 385 .RE
 386 .PP
 387 \fIsha1\fR
 388 .RS 4
 389 HMAC\-SHA1, default value
 390 .RE
 391 .RE
 392 .PP
 393 \fB\-b, \-\-auth\-tag\-length \fR\fB\fI<length>\fR\fR
 394 .RS 4
 395 The number of bytes to use for the auth tag\&. This value defaults to 10 bytes unless the
 396 \fInull\fR
 397 auth algo is used in which case it defaults to 0\&.
 398 .RE
 399 .SH "EXAMPLES"
 400 .SS "P2P Setup between two unicast enpoints:"
 401 .sp
 402 .it 1 an-trap
 403 .nr an-no-space-flag 1
 404 .nr an-break-flag 1
 405 .br
 406 .ps +1
 407 \fBHost A:\fR
 408 .RS 4
 409 .sp
 410 anytun \-r hostb\&.example\&.com \-t tun \-n 192\&.168\&.123\&.1/30 \-c aes\-ctr\-256 \-k aes\-ctr\-256 \e \-E have_a_very_safe_and_productive_day \-e left
 411 .RE
 412 .sp
 413 .it 1 an-trap
 414 .nr an-no-space-flag 1
 415 .nr an-break-flag 1
 416 .br
 417 .ps +1
 418 \fBHost B:\fR
 419 .RS 4
 420 .sp
 421 anytun \-r hosta\&.example\&.com \-t tun \-n 192\&.168\&.123\&.2/30 \-c aes\-ctr\-256 \-k aes\-ctr\-256 \e \-E have_a_very_safe_and_productive_day \-e right
 422 .RE
 423 .SS "One unicast and one anycast tunnel endpoint:"
 424 .sp
 425 .it 1 an-trap
 426 .nr an-no-space-flag 1
 427 .nr an-break-flag 1
 428 .br
 429 .ps +1
 430 \fBUnicast tunnel endpoint:\fR
 431 .RS 4
 432 .sp
 433 anytun \-r anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.2/30 \-a null \-c null \-w 0 \-e client
 434 .RE
 435 .sp
 436 .it 1 an-trap
 437 .nr an-no-space-flag 1
 438 .nr an-break-flag 1
 439 .br
 440 .ps +1
 441 \fBAnycast tunnel endpoints:\fR
 442 .RS 4
 443 .sp
 444 On the host with unicast hostname unicast1\&.anycast\&.anytun\&.org and anycast hostname anycast\&.anytun\&.org:
 445 .sp
 446 .if n \{\
 447 .RS 4
 448 .\}
 449 .nf
 450 # anytun \-i anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.1/30 \-a null \-c null \-w 0 \-e server \e
 451          \-S 2342 \-M unicast2\&.anycast\&.anytun\&.org:2342,unicast3\&.anycast\&.anytun\&.org:2342
 452 .fi
 453 .if n \{\
 454 .RE
 455 .\}
 456 .sp
 457 On the host with unicast hostname unicast2\&.anycast\&.anytun\&.org and anycast hostname anycast\&.anytun\&.org:
 458 .sp
 459 .if n \{\
 460 .RS 4
 461 .\}
 462 .nf
 463 # anytun \-i anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.1/30 \-a null \-c null \-w 0 \-e server \e
 464          \-S 2342 \-M unicast1\&.anycast\&.anytun\&.org:2342,unicast3\&.anycast\&.anytun\&.org:2342
 465 .fi
 466 .if n \{\
 467 .RE
 468 .\}
 469 .sp
 470 On the host with unicast hostname unicast3\&.anycast\&.anytun\&.org and anycast hostname anycast\&.anytun\&.org:
 471 .sp
 472 .if n \{\
 473 .RS 4
 474 .\}
 475 .nf
 476 # anytun \-i anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.1/30 \-a null \-c null \-w 0 \-e server \e
 477          \-S 2342 \-M unicast1\&.anycast\&.anytun\&.org:2342,unicast2\&.anycast\&.anytun\&.org:2342
 478 .fi
 479 .if n \{\
 480 .RE
 481 .\}
 482 .sp
 483 For more sophisticated examples (like multiple unicast endpoints to one anycast tunnel endpoint) please consult the man page of anytun\-config(8)\&.
 484 .RE
 485 .SH "BUGS"
 486 .sp
 487 Most likely there are some bugs in \fBAnytun\fR\&. If you find a bug, please let the developers know at satp@anytun\&.org\&. Of course, patches are preferred\&.
 488 .SH "SEE ALSO"
 489 .sp
 490 anytun\-config(8), anytun\-controld(8), anytun\-showtables(8)
 491 .SH "AUTHORS"
 492 .sp
 493 Othmar Gsenger <otti@anytun\&.org> Erwin Nindl <nine@anytun\&.org> Christian Pointner <equinox@anytun\&.org>
 494 .SH "RESOURCES"
 495 .sp
 496 Main web site: http://www\&.anytun\&.org/
 497 .SH "COPYING"
 498 .sp
 499 Copyright (C) 2007\-2009 Othmar Gsenger, Erwin Nindl and 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\&.