diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 59 | ||||
| -rw-r--r-- | doc/anyrtpproxy.8.txt | 150 | ||||
| -rw-r--r-- | doc/anytun-config.8 | 219 | ||||
| -rw-r--r-- | doc/anytun-config.8.txt | 173 | ||||
| -rw-r--r-- | doc/anytun-controld.8 | 127 | ||||
| -rw-r--r-- | doc/anytun-controld.8.txt | 110 | ||||
| -rw-r--r-- | doc/anytun-showtables.8 | 73 | ||||
| -rw-r--r-- | doc/anytun-showtables.8.txt | 71 | ||||
| -rw-r--r-- | doc/anytun.8 | 487 | ||||
| -rw-r--r-- | doc/anytun.8.txt | 373 |
10 files changed, 1842 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..4f8d8e8 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,59 @@ +## +## anytun +## +## The secure anycast tunneling protocol (satp) defines a protocol used +## for communication between any combination of unicast and anycast +## tunnel endpoints. It has less protocol overhead than IPSec in Tunnel +## mode and allows tunneling of every ETHER TYPE protocol (e.g. +## ethernet, ip, arp ...). satp directly includes cryptography and +## message authentication based on the methodes used by SRTP. It is +## intended to deliver a generic, scaleable and secure solution for +## tunneling and relaying of packets of any protocol. +## +## +## Copyright (C) 2007-2009 Othmar Gsenger, Erwin Nindl, +## Christian Pointner <satp@wirdorange.org> +## +## This file is part of Anytun. +## +## Anytun 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. +## +## Anytun is distributed in the hope that it will be useful, +## but WITHOUT ANY WARRANTY; without even the implied warranty of +## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +## GNU General Public License for more details. +## +## You should have received a copy of the GNU General Public License +## along with anytun. If not, see <http://www.gnu.org/licenses/>. +## + +VERSION=$(shell cat ../version) + +MANPAGES := anytun.8 anytun-controld.8 anytun-config.8 anytun-showtables.8 #anyrtpproxy.8 +XML := $(MANPAGES:%.8=%.8.xml) + +.PHONY: clean realclean + +all: manpage + +define create-manpage + a2x -f manpage $(1) + @ sed -i -e 's/\[FIXME: source\]/anytun ${VERSION}/' $(2) + @ sed -i -e 's/\[FIXME: manual\]/$(2:.8=) user manual/' $(2) + @ sed -i -e 's/^\($(subst -,\\-,$(2:.8=))\)$$/\\fB\1\\fR/' $(2) + @ sed -i -e 's/^ \[ \([^ ]*\)/ [ \\fB\1\\fR/' $(2) +endef + +%.8: %.8.txt + $(call create-manpage,$<,$@) + +manpage: $(MANPAGES) + +clean: + rm -f $(XML) + +realclean: + rm -f $(MANPAGES) diff --git a/doc/anyrtpproxy.8.txt b/doc/anyrtpproxy.8.txt new file mode 100644 index 0000000..a92d2e6 --- /dev/null +++ b/doc/anyrtpproxy.8.txt @@ -0,0 +1,150 @@ +anyrtpproxy(8) +============== + +NAME +---- +anyrtpproxy - anycast rtpproxy + +SYNOPSIS +-------- + +.... +anyrtpproxy + [ -h|--help ] + [ -D|--nodaemonize ] + [ -C|--chroot ] + [ -u|--username <username> ] + [ -H|--chroot-dir <directory> ] + [ -P|--write-pid <filename> ] + [ -i|--interface <ip-address> ] + [ -s|--control <hostname|ip>[:<port>] ] + [ -p|--port-range <start> <end> ] + [ -n|--nat ] + [ -o|--no-nat-once ] + [ -S|--sync-port port> ] + [ -M|--sync-hosts <hostname|ip>:<port>[,<hostname|ip>:<port>[...]] ] +.... + + +DESCRIPTION +----------- + +*anyrtpproxy* is a rtpproxy which can be used in combination with anycast. It uses +the same control protocol than rtpproxy though it can be controled through the nathelper +plugin of openser. *anyrtpproxy* uses the same synchronisation protocol than *Anytun* +to sync the session information among all anycast instances. + + +OPTIONS +------- + +*-D, --nodaemonize*:: + This option instructs *anyrtpproxy* to run in the foreground + instead of becoming a daemon. + +*-C, --chroot*:: + chroot and drop privileges + +*-u, --username <username>*:: + if chroot change to this user + +*-H, --chroot-dir <directory>*:: + chroot to this directory + +*-P, --write-pid <filename>*:: + write pid to this file + +*-i, --interface <ip address>*:: + The local interface to listen on for RTP packets + +*-s, --control <hostname|ip>[:<port>]*:: + The local address and port to listen on for control messages from openser + +*-p, --port-range <start> <end>*:: + A pool of ports which should be used by *anyrtpproxy* to relay RTP packets. + The range may not overlap between the anycast instances + +*-n, --nat*:: + Allow to learn the remote address and port in order to handle clients behind nat. + This option should only be enabled if the source is authenticated (i.e. through + *anytun*) + +*-o, --no-nat-once*:: + Disable learning of remote address and port in case the first packet does not + come from the client which is specified by openser during configuration. Invoking + this parameter increases the security level of the system but in case of nat needs + a working nat transversal such as stun. + +*-S, --sync-port <port>*:: + local unicast(sync) port to bind to + + This port is used by anycast hosts to synchronize information about tunnel + endpoints. No payload data is transmitted via this port. + + 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. + +*-M, --sync-hosts <hostname|ip>:<port>,[<hostname|ip>:<port>[...]]*:: + remote hosts to sync with + + Here, one has to specify all unicast IP addresses of all + other anycast hosts that comprise the anycast tunnel endpoint. + +EXAMPLES +-------- + +Anycast Setup with 3 instances: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On the host with unicast hostname unicast1.anycast.anytun.org and anycast +hostname anycast.anytun.org: +-------------------------------------------------------------------------------------- +# anyrtpproxy -i anycast.anytun.org -p 20000 25000 -S 2342 \ + -M unicast2.anycast.anytun.org:2342,unicast3.anycast.anytun.org:2342 +-------------------------------------------------------------------------------------- + +On the host with unicast hostname unicast2.anycast.anytun.org and anycast +hostname anycast.anytun.org: +-------------------------------------------------------------------------------------- +# anyrtpproxy -i anycast.anytun.org -p 25000 30000 -S 2342 \ + -M unicast1.anycast.anytun.org:2342,unicast3.anycast.anytun.org:2342 +-------------------------------------------------------------------------------------- + +On the host with unicast hostname unicast3.anycast.anytun.org and anycast +hostname anycast.anytun.org: +-------------------------------------------------------------------------------------- +# anyrtpproxy -i anycast.anytun.org -p 30000 35000 -S 2342 \ + -M unicast1.anycast.anytun.org:2342,unicast2.anycast.anytun.org:2342 +-------------------------------------------------------------------------------------- + + +BUGS +---- +Most likely there are some bugs in *anyrtpproxy*. If you find a bug, please let +the developers know at satp@anytun.org. Of course, patches are preferred. + +SEE ALSO +-------- +anytun(8) + +AUTHORS +------- + +Othmar Gsenger <otti@anytun.org> +Erwin Nindl <nine@anytun.org> +Christian Pointner <equinox@anytun.org> + + +RESOURCES +--------- + +Main web site: http://www.anytun.org/ + + +COPYING +------- + +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. + diff --git a/doc/anytun-config.8 b/doc/anytun-config.8 new file mode 100644 index 0000000..317aa54 --- /dev/null +++ b/doc/anytun-config.8 @@ -0,0 +1,219 @@ +'\" t +.\" Title: anytun-config +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.1 <http://docbook.sf.net/> +.\" Date: 12/22/2009 +.\" Manual: anytun-config user manual +.\" Source: anytun trunk +.\" Language: English +.\" +.TH "ANYTUN\-CONFIG" "8" "12/22/2009" "anytun trunk" "anytun-config user manual" +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +anytun-config \- anycast tunneling configuration utility +.SH "SYNOPSIS" +.sp +.nf +\fBanytun\-config\fR + [ \fB\-h|\-\-help\fR ] + [ \fB\-L|\-\-log\fR <target>:<level>[,<param1>[,<param2>[\&.\&.]]] + [ \fB\-r|\-\-remote\-host\fR <hostname|ip> ] + [ \fB\-o|\-\-remote\-port\fR <port> ] + [ \fB\-4|\-\-ipv4\-only\fR ] + [ \fB\-6|\-\-ipv6\-only\fR ] + [ \fB\-R|\-\-route\fR <net>/<prefix length> ] + [ \fB\-m|\-\-mux\fR <mux\-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> ] +.fi +.SH "DESCRIPTION" +.sp +\fBanytun\-config\fR writes routing/connection table entries, that can be read by \fBanytun\-controld\fR\&. +.SH "OPTIONS" +.PP +\fB\-L, \-\-log <target>:<level>[,<param1>[,<param2>[\&.\&.]]]\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 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\&. + +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 +\fBsyslog:3,anytun\-config,daemon\fR +is added\&. + +The following targets are supported: +.PP +\fBsyslog\fR +.RS 4 +log to syslog daemon, parameters <level>[,<logname>[,<facility>]] +.RE +.PP +\fBfile\fR +.RS 4 +log to file, parameters <level>[,<path>] +.RE +.PP +\fBstdout\fR +.RS 4 +log to standard output, parameters <level> +.RE +.PP +\fBstderr\fR +.RS 4 +log to standard error, parameters <level> +.RE +.RE +.PP +\fB\-r, \-\-remote\-host <hostname|ip>\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 <port>\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\&. +.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\-R, \-\-route <net>/<prefix length>\fR +.RS 4 +add a route to connection\&. This can be invoked several times\&. +.RE +.PP +\fB\-m, \-\-mux <mux\-id>\fR +.RS 4 +the multiplex id to use\&. default: 0 +.RE +.PP +\fB\-w, \-\-window\-size <window size>\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\' 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 <kd\-prf type>\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 +\fBnull\fR +.RS 4 +no random function, keys and salt are set to 0\&.\&.00 +.RE +.PP +\fBaes\-ctr\fR +.RS 4 +AES in counter mode with 128 Bits, default value +.RE +.PP +\fBaes\-ctr\-128\fR +.RS 4 +AES in counter mode with 128 Bits +.RE +.PP +\fBaes\-ctr\-192\fR +.RS 4 +AES in counter mode with 192 Bits +.RE +.PP +\fBaes\-ctr\-256\fR +.RS 4 +AES in counter mode with 256 Bits +.RE +.RE +.PP +\fB\-e, \-\-role <role>\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 +\fBleft\fR +and +\fBright\fR\&. You may also use +\fBalice\fR +or +\fBserver\fR +as a replacement for +\fBleft\fR +and +\fBbob\fR +or +\fBclient\fR +as a replacement for +\fBright\fR\&. By default +\fBleft\fR +is used\&. +.RE +.PP +\fB\-E, \-\-passphrase <pass phrase>\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 <master key>\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 <master salt>\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 +.SH "EXAMPLES" +.sp +Add a client with Connection ID (Mux) 12 and add 2 Routes to this client +.sp +.if n \{\ +.RS 4 +.\} +.nf +# anytun\-config \-w 0 \-m 12 \-K 0123456789ABCDEFFEDCBA9876543210 \-A 0123456789ABCDDCBA9876543210 \e + \-R 192\&.0\&.2\&.0/24 \-R 192\&.168\&.1\&.1/32 \-e server >> routingtable +.fi +.if n \{\ +.RE +.\} +.SH "BUGS" +.sp +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\&. +.SH "SEE ALSO" +.sp +anytun(8), anytun\-controld(8), anytun\-showtables(8) +.SH "AUTHORS" +.sp +Othmar Gsenger <otti@anytun\&.org> Erwin Nindl <nine@anytun\&.org> Christian Pointner <equinox@anytun\&.org> +.SH "RESOURCES" +.sp +Main web site: http://www\&.anytun\&.org/ +.SH "COPYING" +.sp +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\&. diff --git a/doc/anytun-config.8.txt b/doc/anytun-config.8.txt new file mode 100644 index 0000000..6a80b4d --- /dev/null +++ b/doc/anytun-config.8.txt @@ -0,0 +1,173 @@ +anytun-config(8) +================ + +NAME +---- +anytun-config - anycast tunneling configuration utility + +SYNOPSIS +-------- + +.... +anytun-config + [ -h|--help ] + [ -L|--log <target>:<level>[,<param1>[,<param2>[..]]] + [ -r|--remote-host <hostname|ip> ] + [ -o|--remote-port <port> ] + [ -4|--ipv4-only ] + [ -6|--ipv6-only ] + [ -R|--route <net>/<prefix length> ] + [ -m|--mux <mux-id> ] + [ -w|--window-size <window size> ] + [ -k|--kd-prf <kd-prf type> ] + [ -e|--role <role> ] + [ -E|--passphrase <pass phrase> ] + [ -K|--key <master key> ] + [ -A|--salt <master salt> ] +.... + +DESCRIPTION +----------- + +*anytun-config* writes routing/connection table entries, that can be read by *anytun-controld*. + +OPTIONS +------- + +*-L, --log <target>:<level>[,<param1>[,<param2>[..]]]*:: + 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. + + 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 *syslog:3,anytun-config,daemon* is added. + + The following targets are supported: + + *syslog*;; log to syslog daemon, parameters <level>[,<logname>[,<facility>]] + *file*;; log to file, parameters <level>[,<path>] + *stdout*;; log to standard output, parameters <level> + *stderr*;; log to standard error, parameters <level> + +*-r, --remote-host <hostname|ip>*:: + 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. + +*-o, --remote-port <port>*:: + 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. + +*-4, --ipv4-only*:: + Resolv to IPv4 addresses only. The default is to resolv both + IPv4 and IPv6 addresses. + +*-6, --ipv6-only*:: + Resolv to IPv6 addresses only. The default is to resolv both + IPv4 and IPv6 addresses. + +*-R, --route <net>/<prefix length>*:: + add a route to connection. This can be invoked several times. + +*-m, --mux <mux-id>*:: + the multiplex id to use. default: 0 + +*-w, --window-size <window size>*:: + seqence window size + + 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. + +*-k, --kd--prf <kd-prf type>*:: + key derivation pseudo random function + + The pseudo random function which is used for calculating the + session keys and session salt. + + Possible values: + + *null*;; no random function, keys and salt are set to 0..00 + *aes-ctr*;; AES in counter mode with 128 Bits, default value + *aes-ctr-128*;; AES in counter mode with 128 Bits + *aes-ctr-192*;; AES in counter mode with 192 Bits + *aes-ctr-256*;; AES in counter mode with 256 Bits + +*-e, --role <role>*:: + 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 *left* and *right*. You may also use + *alice* or *server* as a replacement for *left* and *bob* or *client* as + a replacement for *right*. By default *left* is used. + +*-E, --passphrase <pass phrase>*:: + 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 *--key* and *--salt*. + +*-K, --key <master key>*:: + 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). + +*-A, --salt <master salt>*:: + master salt to use for key derivation + + Master salt in hexadecimal notation, e.g. + 01a2b3c4d5e6f708a9b0cadbecfd, with a mandatory length + of 28 characters (14 bytes). + + +EXAMPLES +-------- + +Add a client with Connection ID (Mux) 12 and add 2 Routes to this client + +------------------------------------------------------------------------------------------------ +# anytun-config -w 0 -m 12 -K 0123456789ABCDEFFEDCBA9876543210 -A 0123456789ABCDDCBA9876543210 \ + -R 192.0.2.0/24 -R 192.168.1.1/32 -e server >> routingtable +------------------------------------------------------------------------------------------------ + +BUGS +---- +Most likely there are some bugs in *Anytun*. If you find a bug, please let +the developers know at satp@anytun.org. Of course, patches are preferred. + +SEE ALSO +-------- +anytun(8), anytun-controld(8), anytun-showtables(8) + +AUTHORS +------- + +Othmar Gsenger <otti@anytun.org> +Erwin Nindl <nine@anytun.org> +Christian Pointner <equinox@anytun.org> + + +RESOURCES +--------- + +Main web site: http://www.anytun.org/ + + +COPYING +------- + +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. diff --git a/doc/anytun-controld.8 b/doc/anytun-controld.8 new file mode 100644 index 0000000..7503857 --- /dev/null +++ b/doc/anytun-controld.8 @@ -0,0 +1,127 @@ +'\" t +.\" Title: anytun-controld +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.1 <http://docbook.sf.net/> +.\" Date: 12/22/2009 +.\" Manual: anytun-controld user manual +.\" Source: anytun trunk +.\" Language: English +.\" +.TH "ANYTUN\-CONTROLD" "8" "12/22/2009" "anytun trunk" "anytun-controld user manual" +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +anytun-controld \- anycast tunneling control daemon +.SH "SYNOPSIS" +.sp +.nf +\fBanytun\-controld\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\-f|\-\-file\fR <path> ] + [ \fB\-X|\-\-control\-host\fR < <host>[:port>] | :<port> > ] +.fi +.SH "DESCRIPTION" +.sp +\fBanytun\-controld\fR configures the multi\-connection support for \fBAnytun\fR\&. It reads a connection/routing table and outputs it via a tcp socket to all connected \fBAnytun\fR servers\&. When the control daemon is restarted with a new connection/routing table all \fBAnytun\fR servers automatically load the new configuration\&. Please make sure to protect that information as it contains the connection keys\&. +.SH "OPTIONS" +.PP +\fB\-D, \-\-nodaemonize\fR +.RS 4 +This option instructs +\fBanytun\-controld\fR +to run in foreground instead of becoming a daemon which is the default\&. +.RE +.PP +\fB\-u, \-\-username <username>\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 <groupname>\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 <path>\fR +.RS 4 +Instruct +\fBanytun\-controld\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 +\fBanytun\-controld\fR +to write it\(cqs pid to this file\&. The default is to not create a pid file\&. +.RE +.PP +\fB\-L, \-\-log <target>:<level>[,<param1>[,<param2>[\&.\&.]]]\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 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\&. + +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 +\fBsyslog:3,anytun\-controld,daemon\fR +is added\&. + +The following targets are supported: +.PP +\fBsyslog\fR +.RS 4 +log to syslog daemon, parameters <level>[,<logname>[,<facility>]] +.RE +.PP +\fBfile\fR +.RS 4 +log to file, parameters <level>[,<path>] +.RE +.PP +\fBstdout\fR +.RS 4 +log to standard output, parameters <level> +.RE +.PP +\fBstderr\fR +.RS 4 +log to standard error, parameters <level> +.RE +.RE +.PP +\fB\-f, \-\-file <path>\fR +.RS 4 +The path to the file which holds the sync information\&. +.RE +.PP +\fB\-X, \-\-control\-host <hostname|ip>[:<port>]\fR +.RS 4 +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 seperate the address from the port, eg\&.: [::1]:1234\&. If you want to use the default port [ and ] can be omitted\&. +.RE +.SH "BUGS" +.sp +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\&. +.SH "SEE ALSO" +.sp +anytun(8), anytun\-config(8), anytun\-showtables(8) +.SH "AUTHORS" +.sp +Othmar Gsenger <otti@anytun\&.org> Erwin Nindl <nine@anytun\&.org> Christian Pointner <equinox@anytun\&.org> +.SH "RESOURCES" +.sp +Main web site: http://www\&.anytun\&.org/ +.SH "COPYING" +.sp +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\&. diff --git a/doc/anytun-controld.8.txt b/doc/anytun-controld.8.txt new file mode 100644 index 0000000..0d3e0b8 --- /dev/null +++ b/doc/anytun-controld.8.txt @@ -0,0 +1,110 @@ +anytun-controld(8) +================== + +NAME +---- +anytun-controld - anycast tunneling control daemon + +SYNOPSIS +-------- + +.... +anytun-controld + [ -h|--help ] + [ -D|--nodaemonize ] + [ -u|--username <username> ] + [ -g|--groupname <groupname> ] + [ -C|--chroot <path> ] + [ -P|--write-pid <filename> ] + [ -L|--log <target>:<level>[,<param1>[,<param2>[..]]] ] + [ -f|--file <path> ] + [ -X|--control-host < <host>[:port>] | :<port> > ] +.... + +DESCRIPTION +----------- + +*anytun-controld* configures the multi-connection support for *Anytun*. It reads a connection/routing table and outputs it via a tcp socket to all connected *Anytun* servers. When the control daemon is restarted with a new connection/routing table all *Anytun* servers automatically load the new configuration. Please make sure to protect that information as it contains the connection keys. + +OPTIONS +------- + +*-D, --nodaemonize*:: + This option instructs *anytun-controld* to run in foreground + instead of becoming a daemon which is the default. + +*-u, --username <username>*:: + run as this user. If no group is specified (*-g*) the default group of + the user is used. The default is to not drop privileges. + +*-g, --groupname <groupname>*:: + run as this group. If no username is specified (*-u*) this gets ignored. + The default is to not drop privileges. + +*-C, --chroot <path>*:: + Instruct *anytun-controld* to run in a chroot jail. The default is + to not run in chroot. + +*-P, --write-pid <filename>*:: + Instruct *anytun-controld* to write it's pid to this file. The default is + to not create a pid file. + +*-L, --log <target>:<level>[,<param1>[,<param2>[..]]]*:: + 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. + + 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 *syslog:3,anytun-controld,daemon* is added. + + The following targets are supported: + + *syslog*;; log to syslog daemon, parameters <level>[,<logname>[,<facility>]] + *file*;; log to file, parameters <level>[,<path>] + *stdout*;; log to standard output, parameters <level> + *stderr*;; log to standard error, parameters <level> + +*-f, --file <path>*:: + The path to the file which holds the sync information. + +*-X, --control-host <hostname|ip>[:<port>]*:: + 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 seperate the address + from the port, eg.: [::1]:1234. If you want to use the default port + [ and ] can be omitted. + + +BUGS +---- +Most likely there are some bugs in *Anytun*. If you find a bug, please let +the developers know at satp@anytun.org. Of course, patches are preferred. + +SEE ALSO +-------- +anytun(8), anytun-config(8), anytun-showtables(8) + +AUTHORS +------- + +Othmar Gsenger <otti@anytun.org> +Erwin Nindl <nine@anytun.org> +Christian Pointner <equinox@anytun.org> + + +RESOURCES +--------- + +Main web site: http://www.anytun.org/ + + +COPYING +------- + +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. + diff --git a/doc/anytun-showtables.8 b/doc/anytun-showtables.8 new file mode 100644 index 0000000..a1230e4 --- /dev/null +++ b/doc/anytun-showtables.8 @@ -0,0 +1,73 @@ +'\" t +.\" Title: anytun-showtables +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.1 <http://docbook.sf.net/> +.\" Date: 12/22/2009 +.\" Manual: anytun-showtables user manual +.\" Source: anytun trunk +.\" Language: English +.\" +.TH "ANYTUN\-SHOWTABLES" "8" "12/22/2009" "anytun trunk" "anytun-showtables user manual" +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +anytun-showtables \- anycast tunneling routing table visualization utility +.SH "SYNOPSIS" +.sp +.nf +\fBanytun\-showtables\fR +.fi +.SH "DESCRIPTION" +.sp +\fBanytun\-showtables\fR displays routing and connection tables used by \fBAnytun\fR\&. It can be used to display a saved routing/connection table used by \fBanytun\-controld\fR or to connect to a the sync port of \fBAnytun\fR\&. +.SH "OPTIONS" +.sp +This Tool does not take any options\&. It takes the sync information from the standard input and prints the routing table to the standard output\&. +.SH "EXAMPLES" +.sp +Print routing table stored in local file +.sp +.if n \{\ +.RS 4 +.\} +.nf +# perl \-ne \'chomp; print\' < routingtable | \&./anytun\-showtables +.fi +.if n \{\ +.RE +.\} +.sp +Print current routing table and watch changes +.sp +.if n \{\ +.RS 4 +.\} +.nf +# nc unicast1\&.anycast\&.anytun\&.org 23 | \&./anytun\-showtables +.fi +.if n \{\ +.RE +.\} +.SH "BUGS" +.sp +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\&. +.SH "SEE ALSO" +.sp +anytun(8), anytun\-controld(8), anytun\-config(8) +.SH "AUTHORS" +.sp +Othmar Gsenger <otti@anytun\&.org> Erwin Nindl <nine@anytun\&.org> Christian Pointner <equinox@anytun\&.org> +.SH "RESOURCES" +.sp +Main web site: http://www\&.anytun\&.org/ +.SH "COPYING" +.sp +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\&. diff --git a/doc/anytun-showtables.8.txt b/doc/anytun-showtables.8.txt new file mode 100644 index 0000000..3a1fa8d --- /dev/null +++ b/doc/anytun-showtables.8.txt @@ -0,0 +1,71 @@ +anytun-showtables(8) +==================== + +NAME +---- +anytun-showtables - anycast tunneling routing table visualization utility + +SYNOPSIS +-------- + +.... +anytun-showtables +.... + +DESCRIPTION +----------- + +*anytun-showtables* displays routing and connection tables used by *Anytun*. It can be used to display a saved routing/connection table used by *anytun-controld* or to connect to a the sync port of *Anytun*. + +OPTIONS +------- + +This Tool does not take any options. It takes the sync information from +the standard input and prints the routing table to the standard output. + +EXAMPLES +-------- + +Print routing table stored in local file + +----------------------------------------------------------------------------------- +# perl -ne 'chomp; print' < routingtable | ./anytun-showtables +----------------------------------------------------------------------------------- + +Print current routing table and watch changes + +----------------------------------------------------------------------------------- +# nc unicast1.anycast.anytun.org 23 | ./anytun-showtables +----------------------------------------------------------------------------------- + +BUGS +---- +Most likely there are some bugs in *Anytun*. If you find a bug, please let +the developers know at satp@anytun.org. Of course, patches are preferred. + +SEE ALSO +-------- +anytun(8), anytun-controld(8), anytun-config(8) + +AUTHORS +------- + +Othmar Gsenger <otti@anytun.org> +Erwin Nindl <nine@anytun.org> +Christian Pointner <equinox@anytun.org> + + +RESOURCES +--------- + +Main web site: http://www.anytun.org/ + + +COPYING +------- + +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. diff --git a/doc/anytun.8 b/doc/anytun.8 new file mode 100644 index 0000000..f739978 --- /dev/null +++ b/doc/anytun.8 @@ -0,0 +1,487 @@ +'\" t +.\" Title: anytun +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.1 <http://docbook.sf.net/> +.\" Date: 12/22/2009 +.\" Manual: anytun user manual +.\" Source: anytun trunk +.\" Language: English +.\" +.TH "ANYTUN" "8" "12/22/2009" "anytun trunk" "anytun user manual" +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +anytun \- anycast tunneling daemon +.SH "SYNOPSIS" +.sp +.nf +\fBanytun\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\-i|\-\-interface\fR <ip\-address> ] + [ \fB\-p|\-\-port\fR <port> ] + [ \fB\-r|\-\-remote\-host\fR <hostname|ip> ] + [ \fB\-o|\-\-remote\-port\fR <port> ] + [ \fB\-4|\-\-ipv4\-only\fR ] + [ \fB\-6|\-\-ipv6\-only\fR ] + [ \fB\-I|\-\-sync\-interface\fR <ip\-address> ] + [ \fB\-S|\-\-sync\-port\fR port> ] + [ \fB\-M|\-\-sync\-hosts\fR <hostname|ip>[:<port>][,<hostname|ip>[:<port>][\&.\&.\&.]] ] + [ \fB\-X|\-\-control\-host\fR <hostname|ip>[:<port>] + [ \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\-R|\-\-route\fR <net>/<prefix length> ] + [ \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 +\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\&. +.SH "OPTIONS" +.sp +\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: +.PP +\fB\-D, \-\-nodaemonize\fR +.RS 4 +This option instructs +\fBAnytun\fR +to run in foreground instead of becoming a daemon which is the default\&. +.RE +.PP +\fB\-u, \-\-username <username>\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 <groupname>\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 <path>\fR +.RS 4 +Instruct +\fBAnytun\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 +\fBAnytun\fR +to write it\(cqs pid to this file\&. The default is to not create a pid file\&. +.RE +.PP +\fB\-L, \-\-log <target>:<level>[,<param1>[,<param2>[\&.\&.]]]\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 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\&. + +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 +\fBsyslog:3,anytun,daemon\fR +is added\&. + +The following targets are supported: +.PP +\fBsyslog\fR +.RS 4 +log to syslog daemon, parameters <level>[,<logname>[,<facility>]] +.RE +.PP +\fBfile\fR +.RS 4 +log to file, parameters <level>[,<path>] +.RE +.PP +\fBstdout\fR +.RS 4 +log to standard output, parameters <level> +.RE +.PP +\fBstderr\fR +.RS 4 +log to standard error, parameters <level> +.RE +.RE +.PP +\fB\-i, \-\-interface <ip address>\fR +.RS 4 +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\&. +.RE +.PP +\fB\-p, \-\-port <port>\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\&. If a tunnel endpoint consists of multiple anycast hosts, all hosts have to use the same port\&. default: 4444 +.RE +.PP +\fB\-r, \-\-remote\-host <hostname|ip>\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 <port>\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\&. +.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\-I, \-\-sync\-interface <ip\-address>\fR +.RS 4 +local unicast(sync) ip address to bind to + +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 +\fB\-\-sync\-port\fR\&. +.RE +.PP +\fB\-S, \-\-sync\-port <port>\fR +.RS 4 +local unicast(sync) port to bind to + +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\&. + +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\&. +.RE +.PP +\fB\-M, \-\-sync\-hosts <hostname|ip>[:<port>],[<hostname|ip>[:<port>][\&...]]\fR +.RS 4 +remote hosts to sync with + +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 seperate the address from the port, eg\&.: [::1]:1234\&. If you want to use the default port [ and ] can be omitted\&. +.RE +.PP +\fB\-X, \-\-control\-host <hostname|ip>[:<port>]\fR +.RS 4 +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 seperate the address from the port, eg\&.: [::1]:1234\&. If you want to use the default port [ and ] can be omitted\&. +.RE +.PP +\fB\-d, \-\-dev <name>\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 <tun|tap>\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 <local>/<prefix>\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 +\fB<local>\fR +.RS 4 +the local IP address for the tun/tap device +.RE +.PP +\fB<prefix>\fR +.RS 4 +the prefix length of the network +.RE +.RE +.PP +\fB\-x, \-\-post\-up\-script <script>\fR +.RS 4 +This option instructs +\fBAnytun\fR +to run this script after the interface is created\&. By default no script will be executed\&. +.RE +.PP +\fB\-R, \-\-route <net>/<prefix length>\fR +.RS 4 +add a route to connection\&. This can be invoked several times\&. +.RE +.PP +\fB\-m, \-\-mux <mux\-id>\fR +.RS 4 +the multiplex id to use\&. default: 0 +.RE +.PP +\fB\-s, \-\-sender\-id <sender id>\fR +.RS 4 +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 +.RE +.PP +\fB\-w, \-\-window\-size <window size>\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\' 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 <kd\-prf type>\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 +\fBnull\fR +.RS 4 +no random function, keys and salt are set to 0\&.\&.00 +.RE +.PP +\fBaes\-ctr\fR +.RS 4 +AES in counter mode with 128 Bits, default value +.RE +.PP +\fBaes\-ctr\-128\fR +.RS 4 +AES in counter mode with 128 Bits +.RE +.PP +\fBaes\-ctr\-192\fR +.RS 4 +AES in counter mode with 192 Bits +.RE +.PP +\fBaes\-ctr\-256\fR +.RS 4 +AES in counter mode with 256 Bits +.RE +.RE +.PP +\fB\-e, \-\-role <role>\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 +\fBleft\fR +and +\fBright\fR\&. You may also use +\fBalice\fR +or +\fBserver\fR +as a replacement for +\fBleft\fR +and +\fBbob\fR +or +\fBclient\fR +as a replacement for +\fBright\fR\&. By default +\fBleft\fR +is used\&. +.RE +.PP +\fB\-E, \-\-passphrase <pass phrase>\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 <master key>\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 <master salt>\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 <cipher type>\fR +.RS 4 +payload encryption algorithm + +Encryption algorithm used for encrypting the payload + +Possible values: +.PP +\fBnull\fR +.RS 4 +no encryption +.RE +.PP +\fBaes\-ctr\fR +.RS 4 +AES in counter mode with 128 Bits, default value +.RE +.PP +\fBaes\-ctr\-128\fR +.RS 4 +AES in counter mode with 128 Bits +.RE +.PP +\fBaes\-ctr\-192\fR +.RS 4 +AES in counter mode with 192 Bits +.RE +.PP +\fBaes\-ctr\-256\fR +.RS 4 +AES in counter mode with 256 Bits +.RE +.RE +.PP +\fB\-a, \-\-auth\-algo <algo type>\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 +\fBnull\fR +.RS 4 +no message authentication +.RE +.PP +\fBsha1\fR +.RS 4 +HMAC\-SHA1, default value +.RE +.RE +.PP +\fB\-b, \-\-auth\-tag\-length <length>\fR +.RS 4 +The number of bytes to use for the auth tag\&. This value defaults to 10 bytes unless the +\fBnull\fR +auth algo is used in which case it defaults to 0\&. +.RE +.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 +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 +.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 +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 +.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 +anytun \-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 +On the host with unicast hostname unicast1\&.anycast\&.anytun\&.org and anycast hostname anycast\&.anytun\&.org: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# anytun \-i anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.1/30 \-a null \-c null \-w 0 \-e server \e + \-S 2342 \-M unicast2\&.anycast\&.anytun\&.org:2342,unicast3\&.anycast\&.anytun\&.org:2342 +.fi +.if n \{\ +.RE +.\} +.sp +On the host with unicast hostname unicast2\&.anycast\&.anytun\&.org and anycast hostname anycast\&.anytun\&.org: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# anytun \-i anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.1/30 \-a null \-c null \-w 0 \-e server \e + \-S 2342 \-M unicast1\&.anycast\&.anytun\&.org:2342,unicast3\&.anycast\&.anytun\&.org:2342 +.fi +.if n \{\ +.RE +.\} +.sp +On the host with unicast hostname unicast3\&.anycast\&.anytun\&.org and anycast hostname anycast\&.anytun\&.org: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# anytun \-i anycast\&.anytun\&.org \-d anytun0 \-t tun \-n 192\&.0\&.2\&.1/30 \-a null \-c null \-w 0 \-e server \e + \-S 2342 \-M unicast1\&.anycast\&.anytun\&.org:2342,unicast2\&.anycast\&.anytun\&.org:2342 +.fi +.if n \{\ +.RE +.\} +.sp +For more sophisticated examples (like multiple unicast endpoints to one anycast tunnel endpoint) please consult the man page of anytun\-config(8)\&. +.RE +.SH "BUGS" +.sp +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\&. +.SH "SEE ALSO" +.sp +anytun\-config(8), anytun\-controld(8), anytun\-showtables(8) +.SH "AUTHORS" +.sp +Othmar Gsenger <otti@anytun\&.org> Erwin Nindl <nine@anytun\&.org> Christian Pointner <equinox@anytun\&.org> +.SH "RESOURCES" +.sp +Main web site: http://www\&.anytun\&.org/ +.SH "COPYING" +.sp +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\&. diff --git a/doc/anytun.8.txt b/doc/anytun.8.txt new file mode 100644 index 0000000..377bb2d --- /dev/null +++ b/doc/anytun.8.txt @@ -0,0 +1,373 @@ +anytun(8) +========= + +NAME +---- +anytun - anycast tunneling daemon + +SYNOPSIS +-------- + +.... +anytun + [ -h|--help ] + [ -D|--nodaemonize ] + [ -u|--username <username> ] + [ -g|--groupname <groupname> ] + [ -C|--chroot <path> ] + [ -P|--write-pid <filename> ] + [ -L|--log <target>:<level>[,<param1>[,<param2>[..]]] ] + [ -i|--interface <ip-address> ] + [ -p|--port <port> ] + [ -r|--remote-host <hostname|ip> ] + [ -o|--remote-port <port> ] + [ -4|--ipv4-only ] + [ -6|--ipv6-only ] + [ -I|--sync-interface <ip-address> ] + [ -S|--sync-port port> ] + [ -M|--sync-hosts <hostname|ip>[:<port>][,<hostname|ip>[:<port>][...]] ] + [ -X|--control-host <hostname|ip>[:<port>] + [ -d|--dev <name> ] + [ -t|--type <tun|tap> ] + [ -n|--ifconfig <local>/<prefix> ] + [ -x|--post-up-script <script> ] + [ -R|--route <net>/<prefix length> ] + [ -m|--mux <mux-id> ] + [ -s|--sender-id <sender id> ] + [ -w|--window-size <window size> ] + [ -k|--kd-prf <kd-prf type> ] + [ -e|--role <role> ] + [ -E|--passphrase <pass phrase> ] + [ -K|--key <master key> ] + [ -A|--salt <master salt> ] + [ -c|--cipher <cipher type> ] + [ -a|--auth-algo <algo type> ] + [ -b|--auth-tag-length <length> ] +.... + +DESCRIPTION +----------- + +*Anytun* 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. + +OPTIONS +------- + +*Anytun* 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: + +*-D, --nodaemonize*:: + This option instructs *Anytun* to run in foreground + instead of becoming a daemon which is the default. + +*-u, --username <username>*:: + run as this user. If no group is specified (*-g*) the default group of + the user is used. The default is to not drop privileges. + +*-g, --groupname <groupname>*:: + run as this group. If no username is specified (*-u*) this gets ignored. + The default is to not drop privileges. + +*-C, --chroot <path>*:: + Instruct *Anytun* to run in a chroot jail. The default is + to not run in chroot. + +*-P, --write-pid <filename>*:: + Instruct *Anytun* to write it's pid to this file. The default is + to not create a pid file. + +*-L, --log <target>:<level>[,<param1>[,<param2>[..]]]*:: + 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. + + 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 *syslog:3,anytun,daemon* is added. + + The following targets are supported: + + *syslog*;; log to syslog daemon, parameters <level>[,<logname>[,<facility>]] + *file*;; log to file, parameters <level>[,<path>] + *stdout*;; log to standard output, parameters <level> + *stderr*;; log to standard error, parameters <level> + +*-i, --interface <ip address>*:: + 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. + +*-p, --port <port>*:: + 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 + +*-r, --remote-host <hostname|ip>*:: + 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. + +*-o, --remote-port <port>*:: + 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. + +*-4, --ipv4-only*:: + Resolv to IPv4 addresses only. The default is to resolv both + IPv4 and IPv6 addresses. + +*-6, --ipv6-only*:: + Resolv to IPv6 addresses only. The default is to resolv both + IPv4 and IPv6 addresses. + +*-I, --sync-interface <ip-address>*:: + local unicast(sync) ip address to bind to + + 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 *--sync-port*. + +*-S, --sync-port <port>*:: + local unicast(sync) port to bind to + + 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. + + 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. + +*-M, --sync-hosts <hostname|ip>[:<port>],[<hostname|ip>[:<port>][...]]*:: + remote hosts to sync with + + 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 seperate the address + from the port, eg.: [::1]:1234. If you want to use the default port + [ and ] can be omitted. + +*-X, --control-host <hostname|ip>[:<port>]*:: + 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 seperate the address + from the port, eg.: [::1]:1234. If you want to use the default port + [ and ] can be omitted. + +*-d, --dev <name>*:: + 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. + +*-t, --type <tun|tap>*:: + device type + + Type of the tunnels to create. Use tap for Ethernet + tunnels, tun for IP tunnels. + +*-n, --ifconfig <local>/<prefix>*:: + The local IP address and prefix length. The remote tunnel endpoint + has to use a different IP address in the same subnet. + + *<local>*;; the local IP address for the tun/tap device + *<prefix>*;; the prefix length of the network + +*-x, --post-up-script <script>*:: + This option instructs *Anytun* to run this script after the interface + is created. By default no script will be executed. + +*-R, --route <net>/<prefix length>*:: + add a route to connection. This can be invoked several times. + +*-m, --mux <mux-id>*:: + the multiplex id to use. default: 0 + +*-s, --sender-id <sender id>*:: + 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 + +*-w, --window-size <window size>*:: + seqence window size + + 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. + +*-k, --kd--prf <kd-prf type>*:: + key derivation pseudo random function + + The pseudo random function which is used for calculating the + session keys and session salt. + + Possible values: + + *null*;; no random function, keys and salt are set to 0..00 + *aes-ctr*;; AES in counter mode with 128 Bits, default value + *aes-ctr-128*;; AES in counter mode with 128 Bits + *aes-ctr-192*;; AES in counter mode with 192 Bits + *aes-ctr-256*;; AES in counter mode with 256 Bits + +*-e, --role <role>*:: + 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 *left* and *right*. You may also use + *alice* or *server* as a replacement for *left* and *bob* or *client* as + a replacement for *right*. By default *left* is used. + +*-E, --passphrase <pass phrase>*:: + 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 *--key* and *--salt*. + +*-K, --key <master key>*:: + 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). + +*-A, --salt <master salt>*:: + master salt to use for key derivation + + Master salt in hexadecimal notation, e.g. + 01a2b3c4d5e6f708a9b0cadbecfd, with a mandatory length + of 28 characters (14 bytes). + +*-c, --cipher <cipher type>*:: + payload encryption algorithm + + Encryption algorithm used for encrypting the payload + + Possible values: + + *null*;; no encryption + *aes-ctr*;; AES in counter mode with 128 Bits, default value + *aes-ctr-128*;; AES in counter mode with 128 Bits + *aes-ctr-192*;; AES in counter mode with 192 Bits + *aes-ctr-256*;; AES in counter mode with 256 Bits + +*-a, --auth-algo <algo type>*:: + 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 *--auth-tag-length* for more info. + + Possible values: + + *null*;; no message authentication + *sha1*;; HMAC-SHA1, default value + +*-b, --auth-tag-length <length>*:: + The number of bytes to use for the auth tag. This value defaults to 10 bytes + unless the *null* auth algo is used in which case it defaults to 0. + + +EXAMPLES +-------- + +P2P Setup between two unicast enpoints: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Host A: +^^^^^^^ + +anytun -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 + +Host B: +^^^^^^^ +anytun -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 + + +One unicast and one anycast tunnel endpoint: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Unicast tunnel endpoint: +^^^^^^^^^^^^^^^^^^^^^^^^ + +anytun -r anycast.anytun.org -d anytun0 -t tun -n 192.0.2.2/30 -a null -c null -w 0 -e client + +Anycast tunnel endpoints: +^^^^^^^^^^^^^^^^^^^^^^^^^ + +On the host with unicast hostname unicast1.anycast.anytun.org and anycast +hostname anycast.anytun.org: +------------------------------------------------------------------------------------------------- +# anytun -i anycast.anytun.org -d anytun0 -t tun -n 192.0.2.1/30 -a null -c null -w 0 -e server \ + -S 2342 -M unicast2.anycast.anytun.org:2342,unicast3.anycast.anytun.org:2342 +------------------------------------------------------------------------------------------------- + +On the host with unicast hostname unicast2.anycast.anytun.org and anycast +hostname anycast.anytun.org: +------------------------------------------------------------------------------------------------- +# anytun -i anycast.anytun.org -d anytun0 -t tun -n 192.0.2.1/30 -a null -c null -w 0 -e server \ + -S 2342 -M unicast1.anycast.anytun.org:2342,unicast3.anycast.anytun.org:2342 +------------------------------------------------------------------------------------------------- + +On the host with unicast hostname unicast3.anycast.anytun.org and anycast +hostname anycast.anytun.org: +------------------------------------------------------------------------------------------------- +# anytun -i anycast.anytun.org -d anytun0 -t tun -n 192.0.2.1/30 -a null -c null -w 0 -e server \ + -S 2342 -M unicast1.anycast.anytun.org:2342,unicast2.anycast.anytun.org:2342 +------------------------------------------------------------------------------------------------- + +For more sophisticated examples (like multiple unicast endpoints to one +anycast tunnel endpoint) please consult the man page of anytun-config(8). + + +BUGS +---- +Most likely there are some bugs in *Anytun*. If you find a bug, please let +the developers know at satp@anytun.org. Of course, patches are preferred. + +SEE ALSO +-------- +anytun-config(8), anytun-controld(8), anytun-showtables(8) + +AUTHORS +------- + +Othmar Gsenger <otti@anytun.org> +Erwin Nindl <nine@anytun.org> +Christian Pointner <equinox@anytun.org> + + +RESOURCES +--------- + +Main web site: http://www.anytun.org/ + + +COPYING +------- + +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. |