X-Git-Url: https://www.tinc-vpn.org/git/browse?p=tinc;a=blobdiff_plain;f=doc%2Ftinc.texi;h=5015ac4a9f963c296fa98a053b78f033642e71d3;hp=726655d337be8e6d6c105debfcbcb361a407542d;hb=5db596c6844169f1eb5f804b72abe99d067aaa5a;hpb=efd29fde85481e080a676f2ba780a528a90a9925 diff --git a/doc/tinc.texi b/doc/tinc.texi index 726655d3..5015ac4a 100644 --- a/doc/tinc.texi +++ b/doc/tinc.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@c $Id: tinc.texi,v 1.8.4.27 2002/03/27 15:26:29 guus Exp $ +@c $Id: tinc.texi,v 1.8.4.38 2003/07/12 17:41:45 guus Exp $ @c %**start of header @setfilename tinc.info @settitle tinc Manual @@ -14,11 +14,11 @@ This is the info manual for tinc, a Virtual Private Network daemon. -Copyright @copyright{} 1998-2002 Ivo Timmermans -, Guus Sliepen and +Copyright @copyright{} 1998-2003 Ivo Timmermans +, Guus Sliepen and Wessel Dankers . -$Id: tinc.texi,v 1.8.4.27 2002/03/27 15:26:29 guus Exp $ +$Id: tinc.texi,v 1.8.4.38 2003/07/12 17:41:45 guus Exp $ Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -39,11 +39,11 @@ permission notice identical to this one. @page @vskip 0pt plus 1filll @cindex copyright -Copyright @copyright{} 1998-2002 Ivo Timmermans -, Guus Sliepen and +Copyright @copyright{} 1998-2003 Ivo Timmermans +, Guus Sliepen and Wessel Dankers . -$Id: tinc.texi,v 1.8.4.27 2002/03/27 15:26:29 guus Exp $ +$Id: tinc.texi,v 1.8.4.38 2003/07/12 17:41:45 guus Exp $ Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -187,7 +187,7 @@ packets. @cindex release For an up to date list of supported platforms, please check the list on our website: -@uref{http://tinc.nl.linux.org/platforms.html}. +@uref{http://tinc.nl.linux.org/platforms}. @c ================================================================== @@ -224,6 +224,19 @@ acquisition from the kernel. It has been verified to work under at least OpenBSD Tunneling IPv6 packets may not work on OpenBSD. +@c ================================================================== +@subsection Solaris + +@c ================================================================== +@subsection NetBSD + +@cindex NetBSD +tinc on NetBSD relies on the tun driver for its data +acquisition from the kernel. It has been verified to work under at least NetBSD 1.5.2. + +Tunneling IPv6 does not work on OpenBSD. + + @c ================================================================== @subsection Solaris @@ -234,6 +247,17 @@ as this driver. These are: Solaris 8 (SunOS 5.8). IPv6 packets cannot be tunneled on Solaris. +@c ================================================================== +@subsection Darwin (MacOS/X) + +@cindex Darwin +@cindex MacOS/X +tinc on Darwin relies on the tunnel driver for its data +acquisition from the kernel. This driver is not part of Darwin but can be +downloaded from @uref{http://chrisp.de/en/projects/tunnel.html}. + +IPv6 packets cannot be tunneled on Darwin. + @c @c @@ -290,7 +314,9 @@ you should read the @uref{http://howto.linuxberg.com/LDP/HOWTO/Kernel-HOWTO.html * Configuration of Linux kernels 2.4.0 and higher:: * Configuration of FreeBSD kernels:: * Configuration of OpenBSD kernels:: +* Configuration of NetBSD kernels:: * Configuration of Solaris kernels:: +* Configuration of Darwin (MacOS/X) kernels:: @end menu @@ -374,7 +400,7 @@ Unfortunately somebody still has to write the text. @c ================================================================== -@node Configuration of OpenBSD kernels, Configuration of Solaris kernels, Configuration of FreeBSD kernels, Configuring the kernel +@node Configuration of OpenBSD kernels, Configuration of NetBSD kernels, Configuration of FreeBSD kernels, Configuring the kernel @subsection Configuration of OpenBSD kernels This section will contain information on how to configure your OpenBSD @@ -385,7 +411,18 @@ Unfortunately somebody still has to write the text. @c ================================================================== -@node Configuration of Solaris kernels, , Configuration of OpenBSD kernels, Configuring the kernel +@node Configuration of NetBSD kernels, Configuration of Solaris kernels, Configuration of OpenBSD kernels, Configuring the kernel +@subsection Configuration of NetBSD kernels + +This section will contain information on how to configure your NetBSD +kernel to support the tun device. For 1.5.2 systems, +this is included in the default kernel configuration. + +Unfortunately somebody still has to write the text. + + +@c ================================================================== +@node Configuration of Solaris kernels, Configuration of Darwin (MacOS/X) kernels, Configuration of NetBSD kernels, Configuring the kernel @subsection Configuration of Solaris kernels This section will contain information on how to configure your Solaris @@ -395,19 +432,37 @@ this is included in the default kernel configuration. Unfortunately somebody still has to write the text. +@c ================================================================== +@node Configuration of Darwin (MacOS/X) kernels, , Configuration of Solaris kernels, Configuring the kernel +@subsection Configuration of Darwin (MacOS/X) kernels + +Darwin does not come with a tunnel driver. You must download it at +@uref{http://chrisp.de/en/projects/tunnel.html}. If compiling the source fails, +try the binary module. The tunnel driver must be loaded before starting tinc +with the following command: + +@example +kmodload tunnel +@end example + +Once loaded, the tunnel driver will automatically create @file{/dev/tun0}..@file{/dev/tun3} +and the corresponding network interfaces. + + @c ================================================================== @node Libraries, , Configuring the kernel, Preparations @section Libraries @cindex requirements @cindex libraries -Before you can configure or build tinc, you need to have the OpenSSL -library installed on your system. If you try to configure tinc without -having installed it, configure will give you an error message, and stop. +Before you can configure or build tinc, you need to have the OpenSSL, +zlib and lzo libraries installed on your system. If you try to configure tinc without +having them installed, configure will give you an error message, and stop. @menu * OpenSSL:: * zlib:: +* lzo:: @end menu @@ -463,7 +518,7 @@ all other requirements of the GPL are met. @c ================================================================== -@node zlib, , OpenSSL, Libraries +@node zlib, lzo, OpenSSL, Libraries @subsection zlib @cindex zlib @@ -485,6 +540,28 @@ make sure you build development and runtime libraries (which is the default). +@c ================================================================== +@node lzo, , zlib, Libraries +@subsection lzo + +@cindex lzo +Another form of compression is offered using the lzo library. + +If this library is not installed, you wil get an error when configuring +tinc for build. Support for running tinc without having lzo +installed @emph{may} be added in the future. + +You can use your operating system's package manager to install this if +available. Make sure you install the development AND runtime versions +of this package. + +If you have to install lzo manually, you can get the source code +from @url{http://www.oberhumer.com/opensource/lzo/}. Instructions on how to configure, +build and install this package are included within the package. Please +make sure you build development and runtime libraries (which is the +default). + + @c @c @c @@ -505,13 +582,13 @@ system startup scripts and sample configurations. If you cannot use one of the precompiled packages, or you want to compile tinc for yourself, you can use the source. The source is distributed under the GNU General Public License (GPL). Download the source from the -@uref{http://tinc.nl.linux.org/download.html, download page}, which has +@uref{http://tinc.nl.linux.org/download, download page}, which has the checksums of these files listed; you may wish to check these with md5sum before continuing. tinc comes in a convenient autoconf/automake package, which you can just treat the same as any other package. Which is just untar it, type -`configure' and then `make'. +`./configure' and then `make'. More detailed instructions are in the file @file{INSTALL}, which is included in the source distribution. @@ -533,6 +610,22 @@ If you happen to have a binary package for tinc for your distribution, you can use the package management tools of that distribution to install tinc. The documentation that comes along with your distribution will tell you how to do that. +@menu +* Darwin (MacOS/X) build environment:: +@end menu + + +@c ================================================================== +@node Darwin (MacOS/X) build environment, , , Building and installing tinc +@subsection Darwin (MacOS/X) build environment + +In order to build tinc on Darwin, you need to install the MacOS/X Developer Tools +from @uref{http://developer.apple.com/tools/macosxtools.html} and +a recent version of Fink from @uref{http://fink.sourceforge.net/}. + +After installation use fink to download and install the following packages: +autoconf25, automake, dlcompat, m4, openssl, zlib and lzo. + @c ================================================================== @node System files, , Building and installing tinc, Installation @@ -565,12 +658,9 @@ ethertap devices: @example mknod -m 600 /dev/tap0 c 36 16 -chown 0.0 /dev/tap0 mknod -m 600 /dev/tap1 c 36 17 -chown 0.0 /dev/tap0 ... mknod -m 600 /dev/tap@emph{N} c 36 @emph{N+16} -chown 0.0 /dev/tap@emph{N} @end example There is a maximum of 16 ethertap devices. @@ -580,12 +670,11 @@ following device file (unless it already exist): @example mknod -m 600 /dev/tun c 10 200 -chown 0.0 /dev/tun @end example If you use Linux, and you run the new 2.4 kernel using the devfs filesystem, then the tun/tap device will probably be automatically generated as -@file{/dev/misc/net/tun}. +@file{/dev/net/tun}. Unlike the ethertap device, you do not need multiple device files if you are planning to run multiple tinc daemons. @@ -614,7 +703,7 @@ number 655 is registered with the IANA. @example tinc 655/tcp TINC tinc 655/udp TINC -# Ivo Timmermans +# Ivo Timmermans @end example @@ -707,9 +796,9 @@ assume that you use it. @section How connections work When tinc starts up, it parses the command-line options and then -reads in the configuration file. -If it sees a `ConnectTo' value pointing to another tinc daemon in the file, -it will try to connect to that other one. +reads in the configuration file tinc.conf. +If it sees one or more `ConnectTo' values pointing to other tinc daemons in that file, +it will try to connect to those other daemons. Whether this succeeds or not and whether `ConnectTo' is specified or not, tinc will listen for incoming connection from other deamons. If you did specify a `ConnectTo' value and the other side is not responding, @@ -717,14 +806,14 @@ tinc will keep retrying. This means that once started, tinc will stay running until you tell it to stop, and failures to connect to other tinc daemons will not stop your tinc daemon for trying again later. -This means you don't have to intervene if there are any network problems. +This means you don't have to intervene if there are temporary network problems. @cindex client @cindex server There is no real distinction between a server and a client in tinc. If you wish, you can view a tinc daemon without a `ConnectTo' value as a server, and one which does specify such a value as a client. -It does not matter if two tinc daemons have a `ConnectTo' value pointing to eachother however. +It does not matter if two tinc daemons have a `ConnectTo' value pointing to each other however. @c ================================================================== @@ -765,11 +854,19 @@ required directives are given in @strong{bold}. @table @asis @cindex AddressFamily -@item AddressFamily = (ipv4) [experimental] +@item AddressFamily = (any) This option affects the address family of listening and outgoing sockets. If "any" is selected, then depending on the operating system both IPv4 and IPv6 or just IPv6 listening sockets will be created. +@cindex BindToAddress +@item BindToAddress =
[experimental] +If your computer has more than one IPv4 or IPv6 address, tinc +will by default listen on all of them for incoming connections. +It is possible to bind only to a single address with this variable. + +This option may not work on all platforms. + @cindex BindToInterface @item BindToInterface = [experimental] If you have more than one network interface in your computer, tinc will @@ -781,18 +878,18 @@ This option may not work on all platforms. @cindex ConnectTo @item @strong{ConnectTo = } -Specifies which host to connect to on startup. Multiple ConnectTo -variables may be specified, if connecting to the first one fails then -tinc will try the next one, and so on. It is possible to specify -hostnames for dynamic IP addresses (like those given on dyndns.org), -tinc will not cache the resolved IP address. +Specifies which other tinc daemon to connect to on startup. +Multiple ConnectTo variables may be specified, +in which case outgoing connections to each specified tinc daemon are made. +The names should be known to this tinc daemon +(i.e., there should be a host configuration file for the name on the ConnectTo line). -If you don't specify a host with ConnectTo, regardless of whether a -value for ConnectPort is given, tinc won't connect at all, and will -instead just listen for incoming connections. +If you don't specify a host with ConnectTo, +tinc won't try to connect to other daemons at all, +and will instead just listen for incoming connections. @cindex Device -@item @strong{Device = } (/dev/tap0 or /dev/misc/net/tun) +@item @strong{Device = } (/dev/tap0 or /dev/net/tun) The virtual network device to use. Note that you can only use one device per daemon. See also @ref{Device files}. @@ -903,7 +1000,8 @@ Any cipher supported by OpenSSL is recognized. @cindex Compression @item Compression = (0) This option sets the level of compression used for UDP packets. -Possible values are 0 (off), 1 (fast) and any integer up to 9 (best). +Possible values are 0 (off), 1 (fast zlib) and any integer up to 9 (best zlib), +10 (fast lzo) and 11 (best lzo). @cindex Digest @item Digest = (sha1) @@ -927,10 +1025,8 @@ up to the length of the digest produced by the digest algorithm. @cindex Port @item Port = (655) -Connect to the upstream host (given with the ConnectTo directive) on -port port. port may be given in decimal (default), octal (when preceded -by a single zero) o hexadecimal (prefixed with 0x). port is the port -number for both the UDP and the TCP (meta) connections. +This is the port this tinc daemon listens on. +You can use decimal portnumbers or symbolic names (as listed in /etc/services). @cindex PublicKey @item PublicKey = [obsolete] @@ -951,7 +1047,7 @@ in each host configuration file, if you want to be able to establish a connection with that host. @cindex Subnet -@item Subnet = +@item Subnet = The subnet which this tinc daemon will serve. tinc tries to look up which other daemon it should send a packet to by searching the appropiate subnet. If the packet matches a subnet, @@ -960,7 +1056,7 @@ Multiple subnet lines can be specified for each daemon. Subnets can either be single MAC, IPv4 or IPv6 addresses, in which case a subnet consisting of only that single address is assumed, -or they can be a IPv4 or IPv6 network address with a masklength. +or they can be a IPv4 or IPv6 network address with a prefixlength. Shorthand notations are not supported. For example, IPv4 subnets must be in a form like 192.168.1.0/24, where 192.168.1.0 is the network address and 24 is the number of bits set in the netmask. @@ -970,7 +1066,7 @@ IPv6 subnets are notated like fec0:0:0:1:0:0:0:0/64. MAC addresses are notated like 0:1a:2b:3c:4d:5e. @cindex CIDR notation -masklength is the number of bits set to 1 in the netmask part; for +prefixlength is the number of bits set to 1 in the netmask part; for example: netmask 255.255.255.0 would become /24, 255.255.252.0 becomes /22. This conforms to standard CIDR notation as described in @uref{ftp://ftp.isi.edu/in-notes/rfc1519.txt, RFC1519} @@ -1060,24 +1156,10 @@ An example @file{tinc-up} script: @example #!/bin/sh -ifconfig $INTERFACE hw ether fe:fd:0:0:0:0 ifconfig $INTERFACE 192.168.1.1 netmask 255.255.0.0 -ifconfig $INTERFACE -arp @end example -@cindex MAC address -@cindex hardware address -The first line sets up the MAC address of the network interface. -Due to the nature of how Ethernet and tinc work, it has to be set to fe:fd:0:0:0:0 -for tinc to work in it's normal mode. -If you configured tinc to work in `switch' or `hub' mode, the hardware address should instead -be set to a unique address instead of fe:fd:0:0:0:0. - -You can use the environment variable $INTERFACE to get the name of the interface. -However, this might not be reliable. If in doubt, use the name of the interface explicitly. - -@cindex ifconfig -The next line gives the interface an IP address and a netmask. +This script gives the interface an IP address and a netmask. The kernel will also automatically add a route to this interface, so normally you don't need to add route commands to the @file{tinc-up} script. The kernel will also bring the interface up after this command. @@ -1085,11 +1167,6 @@ The kernel will also bring the interface up after this command. The netmask is the mask of the @emph{entire} VPN network, not just your own subnet. -@cindex arp -The last line tells the kernel not to use ARP on that interface. -Again this has to do with how Ethernet and tinc work. -Use this option only if you are running tinc under Linux and are using tinc's normal routing mode. - @c ================================================================== @node Example configuration, , Network interfaces, Configuration @@ -1134,16 +1211,14 @@ In @file{/etc/tinc/company/tinc-up}: # Real interface of internal network: # ifconfig eth0 10.1.54.1 netmask 255.255.0.0 broadcast 10.1.255.255 -ifconfig tap0 hw ether fe:fd:0:0:0:0 -ifconfig tap0 10.1.54.1 netmask 255.0.0.0 -ifconfig tap0 -arp +ifconfig $INTERFACE 10.1.54.1 netmask 255.0.0.0 @end example and in @file{/etc/tinc/company/tinc.conf}: @example Name = BranchA -PrivateKey = /etc/tinc/company/rsa_key.priv +PrivateKeyFile = /etc/tinc/company/rsa_key.priv Device = /dev/tap0 @end example @@ -1153,16 +1228,16 @@ On all hosts, /etc/tinc/company/hosts/BranchA contains: Subnet = 10.1.0.0/16 Address = 1.2.3.4 -Note that the IP addresses of eth0 and tap0 are the same. -This is quite possible, if you make sure that the netmasks of the interfaces are different. -It is in fact recommended to give give both real internal network interfaces and tap interfaces the same IP address, -since that will make things a lot easier to remember and set up. - -----BEGIN RSA PUBLIC KEY----- ... -----END RSA PUBLIC KEY----- @end example +Note that the IP addresses of eth0 and tap0 are the same. +This is quite possible, if you make sure that the netmasks of the interfaces are different. +It is in fact recommended to give give both real internal network interfaces and tap interfaces the same IP address, +since that will make things a lot easier to remember and set up. + @subsubheading For Branch B @@ -1172,9 +1247,7 @@ In @file{/etc/tinc/company/tinc-up}: # Real interface of internal network: # ifconfig eth0 10.2.43.8 netmask 255.255.0.0 broadcast 10.2.255.255 -ifconfig tap0 hw ether fe:fd:0:0:0:0 -ifconfig tap0 10.2.1.12 netmask 255.0.0.0 -ifconfig tap0 -arp +ifconfig $INTERFACE 10.2.1.12 netmask 255.0.0.0 @end example and in @file{/etc/tinc/company/tinc.conf}: @@ -1182,7 +1255,7 @@ and in @file{/etc/tinc/company/tinc.conf}: @example Name = BranchB ConnectTo = BranchA -PrivateKey = /etc/tinc/company/rsa_key.priv +PrivateKeyFile = /etc/tinc/company/rsa_key.priv @end example Note here that the internal address (on eth0) doesn't have to be the @@ -1209,9 +1282,7 @@ In @file{/etc/tinc/company/tinc-up}: # Real interface of internal network: # ifconfig eth0 10.3.69.254 netmask 255.255.0.0 broadcast 10.3.255.255 -ifconfig tap1 hw ether fe:fd:0:0:0:0 -ifconfig tap1 10.3.69.254 netmask 255.0.0.0 -ifconfig tap1 -arp +ifconfig $INTERFACE 10.3.69.254 netmask 255.0.0.0 @end example and in @file{/etc/tinc/company/tinc.conf}: @@ -1247,9 +1318,7 @@ In @file{/etc/tinc/company/tinc-up}: # Real interface of internal network: # ifconfig eth0 10.4.3.32 netmask 255.255.0.0 broadcast 10.4.255.255 -ifconfig company hw ether fe:fd:0:0:0:0 -ifconfig company 10.4.3.32 netmask 255.0.0.0 -ifconfig company -arp +ifconfig $INTERFACE 10.4.3.32 netmask 255.0.0.0 @end example and in @file{/etc/tinc/company/tinc.conf}: @@ -1257,7 +1326,7 @@ and in @file{/etc/tinc/company/tinc.conf}: @example Name = BranchD ConnectTo = BranchC -Device = /dev/misc/net/tun +Device = /dev/net/tun PrivateKeyFile = /etc/tinc/company/rsa_key.priv @end example @@ -1327,9 +1396,6 @@ and look in the syslog to find out what the problems are. Besides the settings in the configuration file, tinc also accepts some command line options. -This list is a longer version of that in the manpage. The latter is -generated automatically, so may be more up-to-date. - @cindex command line @cindex runtime options @cindex options @@ -1368,6 +1434,10 @@ Connect to net NETNAME. @xref{Multiple networks}. Don't fork and detach. This will also disable the automatic restart mechanism for fatal errors. +@item -L, --mlock +Lock tinc into main memory. +This will prevent sensitive data like shared private keys to be written to the system swap files/partitions. + @item --version Output version information and exit. @@ -1390,7 +1460,7 @@ only, so keep an eye on it! @item You forgot to compile `Netlink device emulation' in the kernel. @end itemize -@item Can't write to /dev/misc/net/tun: No such device +@item Can't write to /dev/net/tun: No such device @itemize @item You forgot to `modprobe tun'. @@ -1403,8 +1473,8 @@ only, so keep an eye on it! @item Something is not configured right. Packets are being sent out to the virtual network device, but according to the Subnet directives in your host configuration file, those packets should go to your own host. Most common mistake is that -you have a Subnet line in your host configuration file with a netmask which is -just as large as the netmask of the virtual network interface. The latter should in almost all +you have a Subnet line in your host configuration file with a prefix length which is +just as large as the prefix of the virtual network interface. The latter should in almost all cases be larger. Rethink your configuration. Note that you will only see this message if you specified a debug level of 5 or higher! @@ -1415,16 +1485,7 @@ or if that is not the case, try changing the prefix length into /32. @item Network doesn't work, syslog shows only packets of length 46 -@cindex arp -@example -Jan 1 12:00:00 host tinc.net[1234]: Read packet of length 46 from tap device -Jan 1 12:00:00 host tinc.net[1234]: Trying to look up 0.0.192.168 in connection list failed! -@end example -@itemize -@item Add the `ifconfig $INTERFACE -arp' to tinc-up. -@end itemize - -@item Network address and subnet mask do not match! +@item Network address and prefix length do not match! @itemize @item The Subnet field must contain a @emph{network} address. @@ -1444,9 +1505,7 @@ this message. In normal operation, these errors should not occur. @itemize @item You must specify the complete pathname. Specifying a relative path does not make sense here. tinc changes its -directory to / when starting (to avoid keeping a mount point busy); and -even if we built in a default directory to look for these files, the key -files are bound to be in a different directory. +directory to / when starting (to avoid keeping a mount point busy). @end itemize @end table @@ -1486,22 +1545,25 @@ computer over the existing Internet infrastructure. The data itself is read from a character device file, the so-called @emph{virtual network device}. This device is associated with a network interface. Any data sent to this interface can be read from the device, -and any data written to the device gets sent from the interface. Data to -and from the device is formatted as if it were a normal Ethernet card, -so a frame is preceded by two MAC addresses and a @emph{frame type} -field. +and any data written to the device gets sent from the interface. +There are two possible types of virtual network devices: +`tun' style, which are point-to-point devices which can only handle IPv4 and/or IPv6 packets, +and `tap' style, which are Ethernet devices and handle complete Ethernet frames. So when tinc reads an Ethernet frame from the device, it determines its type. When tinc is in it's default routing mode, it can handle IPv4 and IPv6 -packets. Depending on the Subnet lines, it will send the packets off to their destination. +packets. Depending on the Subnet lines, it will send the packets off to their destination IP address. In the `switch' and `hub' mode, tinc will use broadcasts and MAC address discovery to deduce the destination of the packets. Since the latter modes only depend on the link layer information, any protocol that runs over Ethernet is supported (for instance IPX and Appletalk). +However, only `tap' style devices provide this information. -After the destination has been determined, a sequence number will be added to the packet. -The packet will then be encrypted and a message authentication -code will be appended. +After the destination has been determined, +the packet will be compressed (optionally), +a sequence number will be added to the packet, +the packet will then be encrypted +and a message authentication code will be appended. @cindex encapsulating @cindex UDP @@ -1516,20 +1578,27 @@ in reverse. So it checks the message authentication code, decrypts the contents checks the sequence number and writes the decrypted information to its own virtual network device. -To let the kernel on the receiving end accept the packet, the destination MAC -address must match that of the virtual network interface. -If tinc is in it's default routing mode, ARP does not work, so the correct destination MAC cannot be set -by the sending daemons. -tinc solves this by always overwriting the -destination MAC address with fe:fd:0:0:0:0. That is also the reason why you must -set the MAC address of your tap interface to that address. +If the virtual network device is a `tun' device (a point-to-point tunnel), +there is no problem for the kernel to accept a packet. +However, if it is a `tap' device (this is the only available type on FreeBSD), +the destination MAC address must match that of the virtual network interface. +If tinc is in it's default routing mode, ARP does not work, so the correct destination MAC +can not be known by the sending host. +tinc solves this by letting the receiving end detect the MAC address of its own virtual network interface +and overwriting the destination MAC address of the received packet. + +In switch or hub modes ARP does work so the sender already knows the correct destination MAC address. +In those modes every interface should have a unique MAC address, so make sure they are not the same. +Because switch and hub modes rely on MAC addresses to function correctly, +these modes cannot be used on the following operating systems which don't have a `tap' style virtual network device: +OpenBSD, NetBSD, Darwin and Solaris. @c ================================================================== @node The meta-connection, , The UDP tunnel, The connection @subsection The meta-connection -Having only an UDP connection available is not enough. Though suitable +Having only a UDP connection available is not enough. Though suitable for transmitting data, we want to be able to reliably send other information, such as routing and session key information to somebody. @@ -1571,7 +1640,8 @@ The meta protocol consists of requests that can be sent to the other side. Each request has a unique number and several parameters. All requests are represented in the standard ASCII character set. It is possible to use tools such as telnet or netcat to connect to a tinc -daemon and to read and write requests by hand, provided that one +daemon started with the --bypass-security option +and to read and write requests by hand, provided that one understands the numeric codes sent. The authentication scheme is described in @ref{Authentication protocol}. After a @@ -1585,54 +1655,86 @@ synchronised. @example daemon message -------------------------------------------------------------------------- -origin ADD_EDGE node1 12.23.34.45 655 node2 21.32.43.54 655 222 0 - | | | \___________________/ | +-> options - | | | | +----> weight - | | | +----------------> see below - | | +--> UDP port - | +----------> real address - +------------------> name of node on one side of the edge +origin ADD_EDGE node1 node2 21.32.43.54 655 222 0 + | | | | | +-> options + | | | | +----> weight + | | | +--------> UDP port of node2 + | | +----------------> real address of node2 + | +-------------------------> name of destination node + +-------------------------------> name of source node origin ADD_SUBNET node 192.168.1.0/24 - | | +--> masklength - | +--------> IPv4 network address + | | +--> prefixlength + | +--------> network address +------------------> owner of this subnet -------------------------------------------------------------------------- @end example +The ADD_EDGE messages are to inform other tinc daemons that a connection between +two nodes exist. The address of the destination node is available so that +VPN packets can be sent directly to that node. + +The ADD_SUBNET messages inform other tinc daemons that certain subnets belong +to certain nodes. tinc will use it to determine to which node a VPN packet has +to be sent. + @cindex DEL_EDGE +@cindex DEL_SUBNET +@example +message +------------------------------------------------------------------ +DEL_EDGE node1 node2 + | +----> name of destination node + +----------> name of source node + +DEL_SUBNET node 192.168.1.0/24 + | | +--> prefixlength + | +--------> network address + +------------------> owner of this subnet +------------------------------------------------------------------ +@end example + In case a connection between two daemons is closed or broken, DEL_EDGE messages are sent to inform the other daemons of that fact. Each daemon will calculate a new route to the the daemons, or mark them unreachable if there isn't any. +@cindex REQ_KEY +@cindex ANS_KEY +@cindex KEY_CHANGED +@example +message +------------------------------------------------------------------ +REQ_KEY origin destination + | +--> name of the tinc daemon it wants the key from + +----------> name of the daemon that wants the key + +ANS_KEY origin destination 4ae0b0a82d6e0078 91 64 4 + | | \______________/ | | +--> MAC length + | | | | +-----> digest algorithm + | | | +--------> cipher algorithm + | | +--> 128 bits key + | +--> name of the daemon that wants the key + +----------> name of the daemon that uses this key + +KEY_CHANGED origin + +--> daemon that has changed it's packet key +-------------------------------------------------------------------------- +@end example + The keys used to encrypt VPN packets are not sent out directly. This is because it would generate a lot of traffic on VPNs with many daemons, and chances are that not every tinc daemon will ever send a packet to every other daemon. Instead, if a daemon needs a key it sends a request for it via the meta connection of the nearest hop in the direction of the -destination. If any hop on the way has already learned the key, it will -act as a proxy and forward its copy back to the requester. +destination. -@cindex REQ_KEY -@cindex ANS_KEY -@cindex KEY_CHANGED +@cindex PING +@cindex PONG @example daemon message -------------------------------------------------------------------------- -daemon REQ_KEY origin destination - | +--> name of the tinc daemon it wants the key from - +----------> name of the daemon that wants the key - -daemon ANS_KEY origin destination 4ae0b0a82d6e0078 91 64 4 - | | \______________/ | | +--> MAC length - | | | | +-----> digest algorithm - | | | +--------> cipher algorithm - | | +--> 128 bits key - | +--> name of the daemon that wants the key - +----------> name of the daemon that uses this key - -daemon KEY_CHANGED origin - +--> daemon that has changed it's packet key +origin PING +dest. PONG -------------------------------------------------------------------------- @end example @@ -1644,16 +1746,6 @@ is also some other traffic. A little bit of salt (random data) is added with each PING and PONG message, to make sure that long sequences of PING/PONG messages without any other traffic won't result in known plaintext. -@cindex PING -@cindex PONG -@example -daemon message --------------------------------------------------------------------------- -origin PING -dest. PONG --------------------------------------------------------------------------- -@end example - This basically covers what is sent over the meta connection by tinc. @@ -1747,17 +1839,15 @@ server CHAL_REPLY 928ffe After the correct challenge replies are received, both ends have proved their identity. Further information is exchanged. -client ACK 655 12.23.34.45 123 0 - | | | +-> options - | | +----> estimated weight - | +------------> IP address of server as seen by client - +--------------------> UDP port of client - -server ACK 655 21.32.43.54 321 0 - | | | +-> options - | | +----> estimated weight - | +------------> IP address of client as seen by server - +--------------------> UDP port of server +client ACK 655 123 0 + | | +-> options + | +----> estimated weight + +--------> listening port of client + +server ACK 655 321 0 + | | +-> options + | +----> estimated weight + +--------> listening port of server -------------------------------------------------------------------------- @end example @@ -1825,8 +1915,8 @@ The UDP packet containing the network packet from the VPN has the following layo Encrypted with symmetric cipher @end example -So, the entire VPN packet is encrypted using a symmetric cipher. A 32 bits -sequence number is added in front of the actual VPN packet, to act as a unique +So, the entire VPN packet is encrypted using a symmetric cipher, including a 32 bits +sequence number that is added in front of the actual VPN packet, to act as a unique IV for each packet and to prevent replay attacks. A message authentication code is added to the UDP packet to prevent alteration of packets. By default the first 4 bytes of the digest are used for this, but this can be changed using @@ -1852,8 +1942,8 @@ tinc's website is at @url{http://tinc.nl.linux.org/}, this server is located in the Netherlands. @cindex IRC -We have an IRC channel on the Open Projects IRC network. Connect to -@uref{http://openprojects.nu/services/irc.html, irc.openprojects.net}, +We have an IRC channel on the FreeNode IRC network. Connect to +@uref{http://www.freenode.net/, irc.freenode.net} and join channel #tinc. @@ -1862,15 +1952,8 @@ and join channel #tinc. @section Authors @table @asis -@item Ivo Timmermans (zarq) (@email{itimmermans@@bigfoot.com}) -Main coder/hacker and maintainer of the package. - -@item Guus Sliepen (guus) (@email{guus@@sliepen.warande.net}) -Originator of it all, co-author. - -@item Wessel Dankers (Ubiq) (@email{wsl@@nl.linux.org}) -For the name `tinc' and various suggestions. - +@item Ivo Timmermans (zarq) (@email{ivo@@o2w.nl}) +@item Guus Sliepen (guus) (@email{guus@@sliepen.eu.org}) @end table We have received a lot of valuable input from users. With their help,