path: root/doc/uanytun.8

'\" t
.\"     Title: uanytun
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 01/04/2017
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "UANYTUN" "8" "01/04/2017" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
uanytun \- micro anycast tunneling daemon
.SH "SYNOPSIS"
.sp
.nf
\fBuanytun\fR
  [ \fB\-h|\-\-help\fR ]
  [ \fB\-D|\-\-nodaemonize\fR ]
  [ \fB\-u|\-\-username\fR <username> ]
  [ \fB\-g|\-\-groupname\fR <groupname> ]
  [ \fB\-C|\-\-chroot\fR <path> ]
  [ \fB\-P|\-\-write\-pid\fR <filename> ]
  [ \fB\-L|\-\-log\fR <target>:<level>[,<param1>[,<param2>[\&.\&.]]] ]
  [ \fB\-U|\-\-debug\fR ]
  [ \fB\-i|\-\-interface\fR <ip\-address> ]
  [ \fB\-p|\-\-port\fR <port>[:<port>] ]
  [ \fB\-Y|\-\-rail\-mode\fR ]
  [ \fB\-r|\-\-remote\-host\fR <hostname|ip> ]
  [ \fB\-o|\-\-remote\-port\fR <port>[:<port>] ]
  [ \fB\-4|\-\-ipv4\-only\fR ]
  [ \fB\-6|\-\-ipv6\-only\fR ]
  [ \fB\-d|\-\-dev\fR <name> ]
  [ \fB\-t|\-\-type\fR <tun|tap> ]
  [ \fB\-n|\-\-ifconfig\fR <local>/<prefix> ]
  [ \fB\-x|\-\-post\-up\-script\fR <script> ]
  [ \fB\-m|\-\-mux\fR <mux\-id> ]
  [ \fB\-s|\-\-sender\-id\fR <sender id> ]
  [ \fB\-w|\-\-window\-size\fR <window size> ]
  [ \fB\-k|\-\-kd\-prf\fR <kd\-prf type> ]
  [ \fB\-e|\-\-role\fR <role> ]
  [ \fB\-E|\-\-passphrase\fR <pass phrase> ]
  [ \fB\-K|\-\-key\fR <master key> ]
  [ \fB\-A|\-\-salt\fR <master salt> ]
  [ \fB\-c|\-\-cipher\fR <cipher type> ]
  [ \fB\-a|\-\-auth\-algo\fR <algo type> ]
  [ \fB\-b|\-\-auth\-tag\-length\fR <length> ]
.fi
.SH "DESCRIPTION"
.sp
\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\&.
.SH "OPTIONS"
.sp
\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:
.PP
\fB\-D, \-\-nodaemonize\fR
.RS 4
This option instructs
\fBuAnytun\fR
to run in foreground instead of becoming a daemon which is the default\&.
.RE
.PP
\fB\-u, \-\-username \fR\fB\fI<username>\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-g, \-\-groupname \fR\fB\fI<groupname>\fR\fR
.RS 4
run as this group\&. If no username is specified (\fB\-u\fR) this gets ignored\&. The default is to not drop privileges\&.
.RE
.PP
\fB\-C, \-\-chroot \fR\fB\fI<path>\fR\fR
.RS 4
Instruct
\fBuAnytun\fR
to run in a chroot jail\&. The default is to not run in chroot\&.
.RE
.PP
\fB\-P, \-\-write\-pid <filename>\fR
.RS 4
Instruct
\fBuAnytun\fR
to write it\(cqs pid to this file\&. The default is to not create a pid file\&.
.RE
.PP
\fB\-L, \-\-log \fR\fB\fI<target>:<level>[,<param1>[,<param2>[\&.\&.]]]\fR\fR
.RS 4
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 has its own log level which is a number between 0 and 5\&. Where 0 means disabling log and 5 means debug messages are enabled\&.

The file target can be used more than once with different levels\&. If no target is provided at the command line a single target with the config
\fIsyslog:3,uanytun,daemon\fR
is added\&.

The following targets are supported:
.PP
\fIsyslog\fR
.RS 4
log to syslog daemon, parameters <level>[,<logname>[,<facility>]]
.RE
.PP
\fIfile\fR
.RS 4
log to file, parameters <level>[,<path>]
.RE
.PP
\fIstdout\fR
.RS 4
log to standard output, parameters <level>
.RE
.PP
\fIstderr\fR
.RS 4
log to standard error, parameters <level>
.RE
.RE
.PP
\fB\-U, \-\-debug\fR
.RS 4
This option instructs
\fBuAnytun\fR
to run in debug mode\&. It implicits
\fB\-D\fR
(don\(cqt daemonize) and adds a log target with the configuration
\fIstdout:5\fR
(logging with maximum level)\&. In future releases there might be additional output when this option is supplied\&.
.RE
.PP
\fB\-i, \-\-interface \fR\fB\fI<ip address>\fR\fR
.RS 4
This IP address is used as the sender address for outgoing packets\&. The default is to not use a special interface and just bind on all interfaces\&.
.RE
.PP
\fB\-p, \-\-port \fR\fB\fI<port>[:<port>]\fR\fR
.RS 4
The local UDP port that is used to send and receive the payload data\&. The two tunnel endpoints can use different ports\&. The default port is 4444\&. In
\fBRAIL\fR
mode you must specify a port range\&. See section
\fBRAIL\fR
below to find out what this is\&.
.RE
.PP
\fB\-Y, \-\-rail\-mode\fR
.RS 4
This option instructs
\fBuAnytun\fR
to run in RAIL mode\&. See section
\fBRAIL\fR
below to find out what this is\&.
.RE
.PP
\fB\-r, \-\-remote\-host \fR\fB\fI<hostname|ip>\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-o, \-\-remote\-port \fR\fB\fI<port>[:<port>]\fR\fR
.RS 4
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\&. When RAIL mode is enabled the port range must be of the same length as the range defined with
\fB\-p, \-\-port\fR\&. See section
\fBRAIL\fR
below for more information about this mode\&.
.RE
.PP
\fB\-4, \-\-ipv4\-only\fR
.RS 4
Resolv to IPv4 addresses only\&. The default is to resolv both IPv4 and IPv6 addresses\&.
.RE
.PP
\fB\-6, \-\-ipv6\-only\fR
.RS 4
Resolv to IPv6 addresses only\&. The default is to resolv both IPv4 and IPv6 addresses\&.
.RE
.PP
\fB\-d, \-\-dev \fR\fB\fI<name>\fR\fR
.RS 4
device name

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\&.
.RE
.PP
\fB\-t, \-\-type \fR\fB\fI<tun|tap>\fR\fR
.RS 4
device type

Type of the tunnels to create\&. Use tap for Ethernet tunnels, tun for IP tunnels\&.
.RE
.PP
\fB\-n, \-\-ifconfig \fR\fB\fI<local>/<prefix>\fR\fR
.RS 4
The local IP address and prefix length\&. The remote tunnel endpoint has to use a different IP address in the same subnet\&.
.PP
\fI<local>\fR
.RS 4
the local IP address for the tun/tap device
.RE
.PP
\fI<prefix>\fR
.RS 4
the prefix length of the network
.RE
.RE
.PP
\fB\-x, \-\-post\-up\-script \fR\fB\fI<script>\fR\fR
.RS 4
This option instructs
\fBuAnytun\fR
to run this script after the interface is created\&. By default no script will be executed\&.
.RE
.PP
\fB\-m, \-\-mux \fR\fB\fI<mux\-id>\fR\fR
.RS 4
the multiplex id to use\&. default: 0
.RE
.PP
\fB\-s, \-\-sender\-id \fR\fB\fI<sender id>\fR\fR
.RS 4
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
\fBuAnytun\fR
does not support synchronisation it can\(cqt be used as an anycast endpoint therefore this option is quite useless but implemented for compatibility reasons\&. default: 0
.RE
.PP
\fB\-w, \-\-window\-size \fR\fB\fI<window size>\fR\fR
.RS 4
seqence window size

Sometimes, packets arrive out of order on the receiver side\&. This option defines the size of a list of received packets\*(Aq 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\&.
.RE
.PP
\fB\-k, \-\-kd\(emprf \fR\fB\fI<kd\-prf type>\fR\fR
.RS 4
key derivation pseudo random function

The pseudo random function which is used for calculating the session keys and session salt\&.

Possible values:
.PP
\fInull\fR
.RS 4
no random function, keys and salt are set to 0\&.\&.00
.RE
.PP
\fIaes\-ctr\fR
.RS 4
AES in counter mode with 128 Bits, default value
.RE
.PP
\fIaes\-ctr\-128\fR
.RS 4
AES in counter mode with 128 Bits
.RE
.PP
\fIaes\-ctr\-192\fR
.RS 4
AES in counter mode with 192 Bits
.RE
.PP
\fIaes\-ctr\-256\fR
.RS 4
AES in counter mode with 256 Bits
.RE
.RE
.PP
\fB\-e, \-\-role \fR\fB\fI<role>\fR\fR
.RS 4
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
\fIleft\fR
and
\fIright\fR\&. You may also use
\fIalice\fR
or
\fIserver\fR
as a replacement for
\fIleft\fR
and
\fIbob\fR
or
\fIclient\fR
as a replacement for
\fIright\fR\&. By default
\fIleft\fR
is used\&.
.RE
.PP
\fB\-E, \-\-passphrase \fR\fB\fI<pass phrase>\fR\fR
.RS 4
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
\fB\-\-key\fR
and
\fB\-\-salt\fR\&.
.RE
.PP
\fB\-K, \-\-key \fR\fB\fI<master key>\fR\fR
.RS 4
master key to use for key derivation

Master key in hexadecimal notation, e\&.g\&. 01a2b3c4d5e6f708a9b0cadbecfd0fa1, with a mandatory length of 32, 48 or 64 characters (128, 192 or 256 bits)\&.
.RE
.PP
\fB\-A, \-\-salt \fR\fB\fI<master salt>\fR\fR
.RS 4
master salt to use for key derivation

Master salt in hexadecimal notation, e\&.g\&. 01a2b3c4d5e6f708a9b0cadbecfd, with a mandatory length of 28 characters (14 bytes)\&.
.RE
.PP
\fB\-c, \-\-cipher \fR\fB\fI<cipher type>\fR\fR
.RS 4
payload encryption algorithm

Encryption algorithm used for encrypting the payload

Possible values:
.PP
\fInull\fR
.RS 4
no encryption
.RE
.PP
\fIaes\-ctr\fR
.RS 4
AES in counter mode with 128 Bits, default value
.RE
.PP
\fIaes\-ctr\-128\fR
.RS 4
AES in counter mode with 128 Bits
.RE
.PP
\fIaes\-ctr\-192\fR
.RS 4
AES in counter mode with 192 Bits
.RE
.PP
\fIaes\-ctr\-256\fR
.RS 4
AES in counter mode with 256 Bits
.RE
.RE
.PP
\fB\-a, \-\-auth\-algo \fR\fB\fI<algo type>\fR\fR
.RS 4
message authentication algorithm

This option sets the message authentication algorithm\&.

If HMAC\-SHA1 is used, the packet length is increased\&. The additional bytes contain the authentication data\&. see
\fB\-\-auth\-tag\-length\fR
for more info\&.

Possible values:
.PP
\fInull\fR
.RS 4
no message authentication
.RE
.PP
\fIsha1\fR
.RS 4
HMAC\-SHA1, default value
.RE
.RE
.PP
\fB\-b, \-\-auth\-tag\-length \fR\fB\fI<length>\fR\fR
.RS 4
The number of bytes to use for the auth tag\&. This value defaults to 10 bytes unless the
\fInull\fR
auth algo is used in which case it defaults to 0\&.
.RE
.SH "RAIL"
.sp
\fBRAIL\fR stands for Redundant Array of Inexpensive Links\&. Like RAID spreads the blocks of a disk volume over multiple physical disks, \fBRAIL\fR will spread the UDP packets over multiple physical links\&. More precisly for each packet \fBuAnytun\fR reads, from the TUN/TAP device, it will send out multiple UDP packets\&. All of those to the same host but with different destination ports\&. Using policy\-based routing mechanisms these packets can now be seperated and sent out on several interfaces\&. The server\-side will then pick the first of the packets that arrive and discards all others\&. For this to work the size of the sequence window (\fB\-w\fR) must not be set to 0\&. As soon as the server\-side learns the remote endpoints of all or some of the links it will as well send multiple UDP packets for each payload packet\&.
.SH "EXAMPLES"
.SS "P2P Setup between two unicast enpoints:"
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBHost A:\fR
.RS 4
.sp
uanytun \-r hostb\&.example\&.com \-t tun \-n 192\&.168\&.123\&.1/30 \-c aes\-ctr\-256 \-k aes\-ctr\-256 \-E have_a_very_safe_and_productive_day \-e left
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBHost B:\fR
.RS 4
.sp
uanytun \-r hosta\&.example\&.com \-t tun \-n 192\&.168\&.123\&.2/30 \-c aes\-ctr\-256 \-k aes\-ctr\-256 \-E have_a_very_safe_and_productive_day \-e right
.RE
.SS "One unicast and one anycast tunnel endpoint:"
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBUnicast tunnel endpoint:\fR
.RS 4
.sp
uanytun \-r anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.2/30 \-a null \-c null \-w 0 \-e client
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAnycast tunnel endpoints:\fR
.RS 4
.sp
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\&.
.RE
.SS "Rail Setup for 3 links:"
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBClient:\fR
.RS 4
.sp
uanytun \-t tun \-n 192\&.168\&.42\&.2/30 \-c aes\-ctr\-256 \-k aes\-ctr\-256 \-E rail_MODE_is_VERY_cool \-e client \-w 64 \-Y \-p 1233:1235 \-r rail\&.example\&.com \-o 4440:4442
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBServer:\fR
.RS 4
.sp
uanytun \-t tun \-n 192\&.168\&.42\&.1/30 \-c aes\-ctr\-256 \-k aes\-ctr\-256 \-E rail_MODE_is_VERY_cool \-e server \-w 64 \-Y \-p 4440:4442
.RE
.SH "BUGS"
.sp
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\&.
.SH "AUTHORS"
.sp
Christian Pointner <equinox@anytun\&.org>
.SH "RESOURCES"
.sp
Main web site: http://www\&.anytun\&.org/
.SH "COPYING"
.sp
Copyright (C) 2008\-2017 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\&.