debian/uanytun.8

   1 '\" t
   2 .\"     Title: uanytun
   3 .\"    Author: [see the "AUTHORS" section]
   4 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
   5 .\"      Date: 12/14/2009
   6 .\"    Manual: uanytun user manual
   7 .\"    Source: uanytun 0.3.2
   8 .\"  Language: English
   9 .\"
  10 .TH "UANYTUN" "8" "12/14/2009" "uanytun 0.3.2" "uanytun 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 uanytun \- micro anycast tunneling daemon
  23 .SH "SYNOPSIS"
  24 .sp
  25 .nf
  26 \fBuanytun\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\-i|\-\-interface\fR <ip\-address> ]
  35   [ \fB\-p|\-\-port\fR <port> ]
  36   [ \fB\-r|\-\-remote\-host\fR <hostname|ip> ]
  37   [ \fB\-o|\-\-remote\-port\fR <port> ]
  38   [ \fB\-4|\-\-ipv4\-only\fR ]
  39   [ \fB\-6|\-\-ipv6\-only\fR ]
  40   [ \fB\-d|\-\-dev\fR <name> ]
  41   [ \fB\-t|\-\-type\fR <tun|tap> ]
  42   [ \fB\-n|\-\-ifconfig\fR <local>/<prefix> ]
  43   [ \fB\-x|\-\-post\-up\-script\fR <script> ]
  44   [ \fB\-m|\-\-mux\fR <mux\-id> ]
  45   [ \fB\-s|\-\-sender\-id\fR <sender id> ]
  46   [ \fB\-w|\-\-window\-size\fR <window size> ]
  47   [ \fB\-k|\-\-kd\-prf\fR <kd\-prf type> ]
  48   [ \fB\-e|\-\-role\fR <role> ]
  49   [ \fB\-E|\-\-passphrase\fR <pass phrase> ]
  50   [ \fB\-K|\-\-key\fR <master key> ]
  51   [ \fB\-A|\-\-salt\fR <master salt> ]
  52   [ \fB\-c|\-\-cipher\fR <cipher type> ]
  53   [ \fB\-a|\-\-auth\-algo\fR <algo type> ]
  54   [ \fB\-b|\-\-auth\-tag\-length\fR <length> ]
  55 .fi
  56 .SH "DESCRIPTION"
  57 .sp
  58 \fBuAnytun\fR is a tiny 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 enables the setup of tunnels between an arbitrary combination of anycast, unicast and multicast hosts\&. Unlike Anytun which is a full featured implementation uAnytun has no support for multiple connections or synchronisation\&. It is a small single threaded implementation intended to act as a client on small platforms\&.
  59 .SH "OPTIONS"
  60 .sp
  61 \fBuAnytun\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:
  62 .PP
  63 \fB\-D, \-\-nodaemonize\fR
  64 .RS 4
  65 This option instructs
  66 \fBuAnytun\fR
  67 to run in foreground instead of becoming a daemon which is the default\&.
  68 .RE
  69 .PP
  70 \fB\-u, \-\-username <username>\fR
  71 .RS 4
  72 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\&.
  73 .RE
  74 .PP
  75 \fB\-g, \-\-groupname <groupname>\fR
  76 .RS 4
  77 run as this group\&. If no username is specified (\fB\-u\fR) this gets ignored\&. The default is to not drop privileges\&.
  78 .RE
  79 .PP
  80 \fB\-C, \-\-chroot <path>\fR
  81 .RS 4
  82 Instruct
  83 \fBuAnytun\fR
  84 to run in a chroot jail\&. The default is to not run in chroot\&.
  85 .RE
  86 .PP
  87 \fB\-P, \-\-write\-pid <filename>\fR
  88 .RS 4
  89 Instruct
  90 \fBuAnytun\fR
  91 to write it\(cqs pid to this file\&. The default is to not create a pid file\&.
  92 .RE
  93 .PP
  94 \fB\-L, \-\-log <target>:<level>[,<param1>[,<param2>[\&.\&.]]]\fR
  95 .RS 4
  96 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\&.
  97
  98 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
  99 \fBsyslog:3,uanytun,daemon\fR
 100 is added\&.
 101
 102 The following targets are supported:
 103 .PP
 104 \fBsyslog\fR
 105 .RS 4
 106 log to syslog daemon, parameters <level>[,<logname>[,<facility>]]
 107 .RE
 108 .PP
 109 \fBfile\fR
 110 .RS 4
 111 log to file, parameters <level>[,<path>]
 112 .RE
 113 .PP
 114 \fBstdout\fR
 115 .RS 4
 116 log to standard output, parameters <level>
 117 .RE
 118 .PP
 119 \fBstderr\fR
 120 .RS 4
 121 log to standard error, parameters <level>
 122 .RE
 123 .RE
 124 .PP
 125 \fB\-i, \-\-interface <ip address>\fR
 126 .RS 4
 127 This IP address is used as the sender address for outgoing packets\&. The default is to not use a special inteface and just bind on all interfaces\&.
 128 .RE
 129 .PP
 130 \fB\-p, \-\-port <port>\fR
 131 .RS 4
 132 The local UDP port that is used to send and receive the payload data\&. The two tunnel endpoints can use different ports\&. default: 4444
 133 .RE
 134 .PP
 135 \fB\-r, \-\-remote\-host <hostname|ip>\fR
 136 .RS 4
 137 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\&.
 138 .RE
 139 .PP
 140 \fB\-o, \-\-remote\-port <port>\fR
 141 .RS 4
 142 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\&.
 143 .RE
 144 .PP
 145 \fB\-4, \-\-ipv4\-only\fR
 146 .RS 4
 147 Resolv to IPv4 addresses only\&. The default is to resolv both IPv4 and IPv6 addresses\&.
 148 .RE
 149 .PP
 150 \fB\-6, \-\-ipv6\-only\fR
 151 .RS 4
 152 Resolv to IPv6 addresses only\&. The default is to resolv both IPv4 and IPv6 addresses\&.
 153 .RE
 154 .PP
 155 \fB\-d, \-\-dev <name>\fR
 156 .RS 4
 157 device name
 158
 159 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\&.
 160 .RE
 161 .PP
 162 \fB\-t, \-\-type <tun|tap>\fR
 163 .RS 4
 164 device type
 165
 166 Type of the tunnels to create\&. Use tap for Ethernet tunnels, tun for IP tunnels\&.
 167 .RE
 168 .PP
 169 \fB\-n, \-\-ifconfig <local>/<prefix>\fR
 170 .RS 4
 171 The local IP address and prefix length\&. The remote tunnel endpoint has to use a different IP address in the same subnet\&.
 172 .PP
 173 \fB<local>\fR
 174 .RS 4
 175 the local IP address for the tun/tap device
 176 .RE
 177 .PP
 178 \fB<prefix>\fR
 179 .RS 4
 180 the prefix length of the network
 181 .RE
 182 .RE
 183 .PP
 184 \fB\-x, \-\-post\-up\-script <script>\fR
 185 .RS 4
 186 This option instructs
 187 \fBuAnytun\fR
 188 to run this script after the interface is created\&. By default no script will be executed\&.
 189 .RE
 190 .PP
 191 \fB\-m, \-\-mux <mux\-id>\fR
 192 .RS 4
 193 the multiplex id to use\&. default: 0
 194 .RE
 195 .PP
 196 \fB\-s, \-\-sender\-id <sender id>\fR
 197 .RS 4
 198 Each anycast tunnel endpoint needs a unique sender id (1, 2, 3, \&...)\&. It is needed to distinguish the senders in case of replay attacks\&. As
 199 \fBuAnytun\fR
 200 does not support synchronisation it can\(cqt be used as an anycast endpoint therefore this option is quite useless but implemented for compability reasons\&. default: 0
 201 .RE
 202 .PP
 203 \fB\-w, \-\-window\-size <window size>\fR
 204 .RS 4
 205 seqence window size
 206
 207 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\&.
 208 .RE
 209 .PP
 210 \fB\-k, \-\-kd\(emprf <kd\-prf type>\fR
 211 .RS 4
 212 key derivation pseudo random function
 213
 214 The pseudo random function which is used for calculating the session keys and session salt\&.
 215
 216 Possible values:
 217 .PP
 218 \fBnull\fR
 219 .RS 4
 220 no random function, keys and salt are set to 0\&.\&.00
 221 .RE
 222 .PP
 223 \fBaes\-ctr\fR
 224 .RS 4
 225 AES in counter mode with 128 Bits, default value
 226 .RE
 227 .PP
 228 \fBaes\-ctr\-128\fR
 229 .RS 4
 230 AES in counter mode with 128 Bits
 231 .RE
 232 .PP
 233 \fBaes\-ctr\-192\fR
 234 .RS 4
 235 AES in counter mode with 192 Bits
 236 .RE
 237 .PP
 238 \fBaes\-ctr\-256\fR
 239 .RS 4
 240 AES in counter mode with 256 Bits
 241 .RE
 242 .RE
 243 .PP
 244 \fB\-e, \-\-role <role>\fR
 245 .RS 4
 246 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
 247 \fBleft\fR
 248 and
 249 \fBright\fR\&. You may also use
 250 \fBalice\fR
 251 or
 252 \fBserver\fR
 253 as a replacement for
 254 \fBleft\fR
 255 and
 256 \fBbob\fR
 257 or
 258 \fBclient\fR
 259 as a replacement for
 260 \fBright\fR\&. By default
 261 \fBleft\fR
 262 is used\&.
 263 .RE
 264 .PP
 265 \fB\-E, \-\-passphrase <pass phrase>\fR
 266 .RS 4
 267 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
 268 \fB\-\-key\fR
 269 and
 270 \fB\-\-salt\fR\&.
 271 .RE
 272 .PP
 273 \fB\-K, \-\-key <master key>\fR
 274 .RS 4
 275 master key to use for key derivation
 276
 277 Master key in hexadecimal notation, e\&.g\&. 01a2b3c4d5e6f708a9b0cadbecfd0fa1, with a mandatory length of 32, 48 or 64 characters (128, 192 or 256 bits)\&.
 278 .RE
 279 .PP
 280 \fB\-A, \-\-salt <master salt>\fR
 281 .RS 4
 282 master salt to use for key derivation
 283
 284 Master salt in hexadecimal notation, e\&.g\&. 01a2b3c4d5e6f708a9b0cadbecfd, with a mandatory length of 28 characters (14 bytes)\&.
 285 .RE
 286 .PP
 287 \fB\-c, \-\-cipher <cipher type>\fR
 288 .RS 4
 289 payload encryption algorithm
 290
 291 Encryption algorithm used for encrypting the payload
 292
 293 Possible values:
 294 .PP
 295 \fBnull\fR
 296 .RS 4
 297 no encryption
 298 .RE
 299 .PP
 300 \fBaes\-ctr\fR
 301 .RS 4
 302 AES in counter mode with 128 Bits, default value
 303 .RE
 304 .PP
 305 \fBaes\-ctr\-128\fR
 306 .RS 4
 307 AES in counter mode with 128 Bits
 308 .RE
 309 .PP
 310 \fBaes\-ctr\-192\fR
 311 .RS 4
 312 AES in counter mode with 192 Bits
 313 .RE
 314 .PP
 315 \fBaes\-ctr\-256\fR
 316 .RS 4
 317 AES in counter mode with 256 Bits
 318 .RE
 319 .RE
 320 .PP
 321 \fB\-a, \-\-auth\-algo <algo type>\fR
 322 .RS 4
 323 message authentication algorithm
 324
 325 This option sets the message authentication algorithm\&.
 326
 327 If HMAC\-SHA1 is used, the packet length is increased\&. The additional bytes contain the authentication data\&. see
 328 \fB\-\-auth\-tag\-length\fR
 329 for more info\&.
 330
 331 Possible values:
 332 .PP
 333 \fBnull\fR
 334 .RS 4
 335 no message authentication
 336 .RE
 337 .PP
 338 \fBsha1\fR
 339 .RS 4
 340 HMAC\-SHA1, default value
 341 .RE
 342 .RE
 343 .PP
 344 \fB\-b, \-\-auth\-tag\-length <length>\fR
 345 .RS 4
 346 The number of bytes to use for the auth tag\&. This value defaults to 10 bytes unless the
 347 \fBnull\fR
 348 auth algo is used in which case it defaults to 0\&.
 349 .RE
 350 .SH "EXAMPLES"
 351 .SS "P2P Setup between two unicast enpoints:"
 352 .sp
 353 .it 1 an-trap
 354 .nr an-no-space-flag 1
 355 .nr an-break-flag 1
 356 .br
 357 .ps +1
 358 \fBHost A:\fR
 359 .RS 4
 360 .sp
 361 uanytun \-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
 362 .RE
 363 .sp
 364 .it 1 an-trap
 365 .nr an-no-space-flag 1
 366 .nr an-break-flag 1
 367 .br
 368 .ps +1
 369 \fBHost B:\fR
 370 .RS 4
 371 .sp
 372 uanytun \-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
 373 .RE
 374 .SS "One unicast and one anycast tunnel endpoint:"
 375 .sp
 376 .it 1 an-trap
 377 .nr an-no-space-flag 1
 378 .nr an-break-flag 1
 379 .br
 380 .ps +1
 381 \fBUnicast tunnel endpoint:\fR
 382 .RS 4
 383 .sp
 384 uanytun \-r anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.2/30 \-a null \-c null \-w 0 \-e client
 385 .RE
 386 .sp
 387 .it 1 an-trap
 388 .nr an-no-space-flag 1
 389 .nr an-break-flag 1
 390 .br
 391 .ps +1
 392 \fBAnycast tunnel endpoints:\fR
 393 .RS 4
 394 .sp
 395 As \fBuAnytun\fR can\(cqt work as an anycast endpoint it can\(cqt be used for this purpose\&. You have to use \fBAnytun\fR for that job\&.
 396 .RE
 397 .SH "BUGS"
 398 .sp
 399 Most likely there are some bugs in \fBuAnytun\fR\&. If you find a bug, please let the developers know at uanytun@anytun\&.org\&. Of course, patches are preferred\&.
 400 .SH "AUTHORS"
 401 .sp
 402 Christian Pointner <equinox@anytun\&.org>
 403 .SH "RESOURCES"
 404 .sp
 405 Main web site: http://www\&.anytun\&.org/
 406 .SH "COPYING"
 407 .sp
 408 Copyright (C) 2008\-2009 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\&.