2038 lines
75 KiB
Text
2038 lines
75 KiB
Text
\input texinfo @c -*-texinfo-*-
|
|
@c $Id: tinc.texi,v 1.8.4.40 2003/07/30 09:22:29 guus Exp $
|
|
@c %**start of header
|
|
@setfilename tinc.info
|
|
@settitle tinc Manual
|
|
@setchapternewpage odd
|
|
@c %**end of header
|
|
|
|
@ifinfo
|
|
@dircategory Networking tools
|
|
@direntry
|
|
* tinc: (tinc). The tinc Manual.
|
|
@end direntry
|
|
|
|
This is the info manual for tinc, a Virtual Private Network daemon.
|
|
|
|
Copyright @copyright{} 1998-2003 Ivo Timmermans
|
|
<ivo@@o2w.nl>, Guus Sliepen <guus@@sliepen.eu.org> and
|
|
Wessel Dankers <wsl@@nl.linux.org>.
|
|
|
|
$Id: tinc.texi,v 1.8.4.40 2003/07/30 09:22:29 guus Exp $
|
|
|
|
Permission is granted to make and distribute verbatim copies of this
|
|
manual provided the copyright notice and this permission notice are
|
|
preserved on all copies.
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the
|
|
entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
|
|
@end ifinfo
|
|
|
|
@titlepage
|
|
@title tinc Manual
|
|
@subtitle Setting up a Virtual Private Network with tinc
|
|
@author Ivo Timmermans and Guus Sliepen
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@cindex copyright
|
|
Copyright @copyright{} 1998-2003 Ivo Timmermans
|
|
<ivo@@o2w.nl>, Guus Sliepen <guus@@sliepen.eu.org> and
|
|
Wessel Dankers <wsl@@nl.linux.org>.
|
|
|
|
$Id: tinc.texi,v 1.8.4.40 2003/07/30 09:22:29 guus Exp $
|
|
|
|
Permission is granted to make and distribute verbatim copies of this
|
|
manual provided the copyright notice and this permission notice are
|
|
preserved on all copies.
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the
|
|
entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
|
|
@end titlepage
|
|
|
|
@c ==================================================================
|
|
@node Top, Introduction, (dir), (dir)
|
|
|
|
@menu
|
|
* Introduction:: Introduction
|
|
* Preparations::
|
|
* Installation::
|
|
* Configuration::
|
|
* Running tinc::
|
|
* Technical information::
|
|
* About us::
|
|
* Concept Index:: All used terms explained
|
|
@end menu
|
|
|
|
|
|
@contents
|
|
|
|
@c ==================================================================
|
|
@node Introduction, Preparations, Top, Top
|
|
@chapter Introduction
|
|
|
|
@cindex tinc
|
|
tinc is a Virtual Private Network (VPN) daemon that uses tunneling and
|
|
encryption to create a secure private network between hosts on the
|
|
Internet.
|
|
|
|
Because the tunnel appears to the IP level network code as a normal
|
|
network device, there is no need to adapt any existing software.
|
|
The encrypted tunnels allows VPN sites to share information with each other
|
|
over the Internet without exposing any information to others.
|
|
|
|
This document is the manual for tinc. Included are chapters on how to
|
|
configure your computer to use tinc, as well as the configuration
|
|
process of tinc itself.
|
|
|
|
@menu
|
|
* VPNs:: Virtual Private Networks in general
|
|
* tinc:: about tinc
|
|
* Supported platforms::
|
|
@end menu
|
|
|
|
@c ==================================================================
|
|
@node VPNs, tinc, Introduction, Introduction
|
|
@section Virtual Private Networks
|
|
|
|
@cindex VPN
|
|
A Virtual Private Network or VPN is a network that can only be accessed
|
|
by a few elected computers that participate. This goal is achievable in
|
|
more than just one way.
|
|
|
|
@cindex private
|
|
Private networks can consist of a single stand-alone Ethernet LAN. Or
|
|
even two computers hooked up using a null-modem cable. In these cases,
|
|
it is
|
|
obvious that the network is @emph{private}, no one can access it from the
|
|
outside. But if your computers are linked to the Internet, the network
|
|
is not private anymore, unless one uses firewalls to block all private
|
|
traffic. But then, there is no way to send private data to trusted
|
|
computers on the other end of the Internet.
|
|
|
|
@cindex virtual
|
|
This problem can be solved by using @emph{virtual} networks. Virtual
|
|
networks can live on top of other networks, but they use encapsulation to
|
|
keep using their private address space so they do not interfere with
|
|
the Internet. Mostly, virtual networks appear like a singe LAN, even though
|
|
they can span the entire world. But virtual networks can't be secured
|
|
by using firewalls, because the traffic that flows through it has to go
|
|
through the Internet, where other people can look at it.
|
|
|
|
As is the case with either type of VPN, anybody could eavesdrop. Or
|
|
worse, alter data. Hence it's probably advisable to encrypt the data
|
|
that flows over the network.
|
|
|
|
When one introduces encryption, we can form a true VPN. Other people may
|
|
see encrypted traffic, but if they don't know how to decipher it (they
|
|
need to know the key for that), they cannot read the information that flows
|
|
through the VPN. This is what tinc was made for.
|
|
|
|
|
|
@c ==================================================================
|
|
@node tinc, Supported platforms, VPNs, Introduction
|
|
@section tinc
|
|
|
|
@cindex vpnd
|
|
I really don't quite remember what got us started, but it must have been
|
|
Guus' idea. He wrote a simple implementation (about 50 lines of C) that
|
|
used the ethertap device that Linux knows of since somewhere
|
|
about kernel 2.1.60. It didn't work immediately and he improved it a
|
|
bit. At this stage, the project was still simply called @samp{vpnd}.
|
|
|
|
Since then, a lot has changed---to say the least.
|
|
|
|
@cindex tincd
|
|
tinc now supports encryption, it consists of a single daemon (tincd) for
|
|
both the receiving and sending end, it has become largely
|
|
runtime-configurable---in short, it has become a full-fledged
|
|
professional package.
|
|
|
|
@cindex Traditional VPNs
|
|
@cindex scalability
|
|
tinc also allows more than two sites to connect to eachother and form a single VPN.
|
|
Traditionally VPNs are created by making tunnels, which only have two endpoints.
|
|
Larger VPNs with more sites are created by adding more tunnels.
|
|
tinc takes another approach: only endpoints are specified,
|
|
the software itself will take care of creating the tunnels.
|
|
This allows for easier configuration and improved scalability.
|
|
|
|
A lot can---and will be---changed. We have a number of things that we would like to
|
|
see in the future releases of tinc. Not everything will be available in
|
|
the near future. Our first objective is to make tinc work perfectly as
|
|
it stands, and then add more advanced features.
|
|
|
|
Meanwhile, we're always open-minded towards new ideas. And we're
|
|
available too.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Supported platforms, , tinc, Introduction
|
|
@section Supported platforms
|
|
|
|
@cindex platforms
|
|
tinc has been verified to work under Linux, FreeBSD, OpenBSD, NetBSD, MacOS/X (Darwin), Solaris, and Windows (in a Cygwin environment),
|
|
with various hardware architectures. These are some of the platforms
|
|
that are supported by the universal tun/tap device driver or other virtual network device drivers.
|
|
Without such a driver, tinc will most
|
|
likely compile and run, but it will not be able to send or receive data
|
|
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}.
|
|
|
|
|
|
@c ==================================================================
|
|
@subsection Linux
|
|
|
|
@cindex Linux
|
|
tinc was first written for Linux running on an intel x86 processor, so
|
|
this is the best supported platform. The protocol however, and actually
|
|
anything about tinc, has been rewritten to support random byte ordering
|
|
and arbitrary word length. So in theory it should run on other
|
|
processors that Linux runs on. It has already been verified to run on
|
|
alpha and sparc processors as well.
|
|
|
|
tinc uses the ethertap device or the universal tun/tap driver. The former is provided in the standard kernel
|
|
from version 2.1.60 up to 2.3.x, but has been replaced in favour of the tun/tap driver in kernel versions 2.4.0 and later.
|
|
|
|
|
|
@c ==================================================================
|
|
@subsection FreeBSD
|
|
|
|
@cindex FreeBSD
|
|
tinc on FreeBSD relies on the universal tun/tap driver for its data
|
|
acquisition from the kernel. Therefore, tinc will work on the same platforms
|
|
as this driver. These are: FreeBSD 3.x, 4.x, 5.x.
|
|
|
|
|
|
@c ==================================================================
|
|
@subsection OpenBSD
|
|
|
|
@cindex OpenBSD
|
|
tinc on OpenBSD relies on the tun driver for its data
|
|
acquisition from the kernel. It has been verified to work under at least OpenBSD 2.9.
|
|
|
|
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
|
|
|
|
@cindex Solaris
|
|
tinc on Solaris relies on the universal tun/tap driver for its data
|
|
acquisition from the kernel. Therefore, tinc will work on the same platforms
|
|
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 ==================================================================
|
|
@subsection Cygwin (Windows)
|
|
|
|
@cindex Cygwin
|
|
@cindex Windows
|
|
tinc on Windows, in a Cygwin environment, relies on the CIPE driver for its data
|
|
acquisition from the kernel. This driver is not part of Windows but can be
|
|
downloaded from @uref{http://cipe-win32.sourceforge.net/}.
|
|
|
|
@c ==================================================================
|
|
@subsection MinGW (Windows)
|
|
|
|
@cindex MinGW
|
|
@cindex Windows
|
|
tinc on Windows, compiled using MinGW, relies on the CIPE driver for its data
|
|
acquisition from the kernel. This driver is not part of Windows but can be
|
|
downloaded from @uref{http://cipe-win32.sourceforge.net/}.
|
|
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@c
|
|
@c
|
|
@c
|
|
@c Preparing your system
|
|
@c
|
|
@c
|
|
@c
|
|
@c
|
|
@c
|
|
|
|
@c ==================================================================
|
|
@node Preparations, Installation, Introduction, Top
|
|
@chapter Preparations
|
|
|
|
This chapter contains information on how to prepare your system to
|
|
support tinc.
|
|
|
|
@menu
|
|
* Configuring the kernel::
|
|
* Libraries::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuring the kernel, Libraries, Preparations, Preparations
|
|
@section Configuring the kernel
|
|
|
|
@cindex RedHat
|
|
@cindex Debian
|
|
@cindex netlink_dev
|
|
@cindex tun
|
|
@cindex ethertap
|
|
If you are running Linux, chances are good that your kernel already supports
|
|
all the devices that tinc needs for proper operation. For example, the
|
|
standard kernel from Redhat Linux already has support for ethertap and netlink
|
|
compiled in. Debian users can use the modconf utility to select the modules.
|
|
If your Linux distribution supports this method of selecting devices, look out
|
|
for something called `ethertap', and `netlink_dev' if it is using a kernel
|
|
version prior to 2.4.0. In that case you will need both these devices. If you
|
|
are using kernel 2.4.0 or later, you need to select `tun'.
|
|
|
|
@cindex Kernel-HOWTO
|
|
If you can install these devices in a similar manner, you may skip this section.
|
|
Otherwise, you will have to recompile the kernel in order to turn on the required features.
|
|
If you are unfamiliar with the process of configuring and compiling a new kernel,
|
|
you should read the @uref{http://howto.linuxberg.com/LDP/HOWTO/Kernel-HOWTO.html, Kernel HOWTO} first.
|
|
|
|
@menu
|
|
* Configuration of Linux kernels 2.1.60 up to 2.4.0::
|
|
* 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::
|
|
* Configuration of Cygwin (Windows)::
|
|
* Configuration of MinGW (Windows)::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuration of Linux kernels 2.1.60 up to 2.4.0, Configuration of Linux kernels 2.4.0 and higher, Configuring the kernel, Configuring the kernel
|
|
@subsection Configuration of Linux kernels 2.1.60 up to 2.4.0
|
|
|
|
Here are the options you have to turn on when configuring a new kernel:
|
|
|
|
@example
|
|
Code maturity level options
|
|
[*] Prompt for development and/or incomplete code/drivers
|
|
Networking options
|
|
[*] Kernel/User netlink socket
|
|
<M> Netlink device emulation
|
|
Network device support
|
|
<M> Ethertap network tap
|
|
@end example
|
|
|
|
If you want to run more than one instance of tinc or other programs that use
|
|
the ethertap, you have to compile the ethertap driver as a module, otherwise
|
|
you can also choose to compile it directly into the kernel.
|
|
|
|
If you decide to build any of these as dynamic kernel modules, it's a good idea
|
|
to add these lines to @file{/etc/modules.conf}:
|
|
|
|
@example
|
|
alias char-major-36 netlink_dev
|
|
alias tap0 ethertap
|
|
options tap0 -o tap0 unit=0
|
|
alias tap1 ethertap
|
|
options tap1 -o tap1 unit=1
|
|
...
|
|
alias tap@emph{N} ethertap
|
|
options tap@emph{N} -o tap@emph{N} unit=@emph{N}
|
|
@end example
|
|
|
|
Add as much alias/options lines as necessary.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuration of Linux kernels 2.4.0 and higher, Configuration of FreeBSD kernels, Configuration of Linux kernels 2.1.60 up to 2.4.0, Configuring the kernel
|
|
@subsection Configuration of Linux kernels 2.4.0 and higher
|
|
|
|
Here are the options you have to turn on when configuring a new kernel:
|
|
|
|
@example
|
|
Code maturity level options
|
|
[*] Prompt for development and/or incomplete code/drivers
|
|
Network device support
|
|
<M> Universal tun/tap device driver support
|
|
@end example
|
|
|
|
It's not necessary to compile this driver as a module, even if you are going to
|
|
run more than one instance of tinc.
|
|
|
|
If you have an early 2.4 kernel, you can choose both the tun/tap driver and the
|
|
`Ethertap network tap' device. This latter is marked obsolete, and chances are
|
|
that it won't even function correctly anymore. Make sure you select the
|
|
universal tun/tap driver.
|
|
|
|
If you decide to build the tun/tap driver as a kernel module, add these lines
|
|
to @file{/etc/modules.conf}:
|
|
|
|
@example
|
|
alias char-major-10-200 tun
|
|
@end example
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuration of FreeBSD kernels, Configuration of OpenBSD kernels, Configuration of Linux kernels 2.4.0 and higher, Configuring the kernel
|
|
@subsection Configuration of FreeBSD kernels
|
|
|
|
For FreeBSD version 4.1 and higher, the tap driver is included in the default kernel configuration, for earlier
|
|
systems (4.0 and earlier), you need to install the universal tun/tap driver
|
|
yourself.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuration of OpenBSD kernels, Configuration of NetBSD kernels, Configuration of FreeBSD kernels, Configuring the kernel
|
|
@subsection Configuration of OpenBSD kernels
|
|
|
|
For OpenBSD version 2.9 and higher,
|
|
the tun driver is included in the default kernel configuration.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuration of NetBSD kernels, Configuration of Solaris kernels, Configuration of OpenBSD kernels, Configuring the kernel
|
|
@subsection Configuration of NetBSD kernels
|
|
|
|
For NetBSD version 1.5.2 and higher,
|
|
the tun driver is included in the default kernel configuration.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuration of Solaris kernels, Configuration of Darwin (MacOS/X) kernels, Configuration of NetBSD kernels, Configuring the kernel
|
|
@subsection Configuration of Solaris kernels
|
|
|
|
For Solaris 8 (SunOS 5.8) and higher,
|
|
the tun driver is included in the default kernel configuration.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuration of Darwin (MacOS/X) kernels, Configuration of Cygwin (Windows), 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 Configuration of Cygwin (Windows), Configuration of MinGW (Windows), Configuration of Darwin (MacOS/X) kernels, Configuring the kernel
|
|
@subsection Configuration of Cygwin (Windows)
|
|
|
|
You will need to install the CIPE driver, you can download it from
|
|
@uref{http://cipe-win32.sourceforge.net}. Configure the CIPE network device in
|
|
the same way as you would do from the tinc-up script.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuration of MinGW (Windows), , Configuration of Cygwin (Windows), Configuring the kernel
|
|
@subsection Configuration of MinGW (Windows)
|
|
|
|
You will need to install the CIPE driver, you can download it from
|
|
@uref{http://cipe-win32.sourceforge.net}. Configure the CIPE network device in
|
|
the same way as you would do from the tinc-up script.
|
|
|
|
|
|
@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,
|
|
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
|
|
|
|
|
|
@c ==================================================================
|
|
@node OpenSSL, zlib, Libraries, Libraries
|
|
@subsection OpenSSL
|
|
|
|
@cindex OpenSSL
|
|
For all cryptography-related functions, tinc uses the functions provided
|
|
by the OpenSSL library.
|
|
|
|
If this library is not installed, you wil get an error when configuring
|
|
tinc for build. Support for running tinc without having OpenSSL
|
|
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 OpenSSL manually, you can get the source code
|
|
from @url{http://www.openssl.org/}. 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).
|
|
|
|
If you installed the OpenSSL libraries from source, it may be necessary
|
|
to let configure know where they are, by passing configure one of the
|
|
--with-openssl-* parameters.
|
|
|
|
@example
|
|
--with-openssl=DIR OpenSSL library and headers prefix
|
|
--with-openssl-include=DIR OpenSSL headers directory
|
|
(Default is OPENSSL_DIR/include)
|
|
--with-openssl-lib=DIR OpenSSL library directory
|
|
(Default is OPENSSL_DIR/lib)
|
|
@end example
|
|
|
|
|
|
@subsubheading License
|
|
|
|
@cindex license
|
|
Since the license under which OpenSSL is distributed is not directly
|
|
compatible with the terms of the GNU GPL
|
|
@uref{http://www.openssl.org/support/faq.html#LEGAL2}, therefore we
|
|
include an addition to the GPL (see also the file COPYING.README):
|
|
|
|
@quotation
|
|
This program is released under the GPL with the additional exemption
|
|
that compiling, linking, and/or using OpenSSL is allowed. You may
|
|
provide binary packages linked to the OpenSSL libraries, provided that
|
|
all other requirements of the GPL are met.
|
|
@end quotation
|
|
|
|
|
|
@c ==================================================================
|
|
@node zlib, lzo, OpenSSL, Libraries
|
|
@subsection zlib
|
|
|
|
@cindex zlib
|
|
For the optional compression of UDP packets, tinc uses the functions provided
|
|
by the zlib library.
|
|
|
|
If this library is not installed, you wil get an error when configuring
|
|
tinc for build. Support for running tinc without having zlib
|
|
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 zlib manually, you can get the source code
|
|
from @url{http://www.gzip.org/zlib/}. 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 ==================================================================
|
|
@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
|
|
@c Installing tinc
|
|
@c
|
|
@c
|
|
@c
|
|
@c
|
|
|
|
@c ==================================================================
|
|
@node Installation, Configuration, Preparations, Top
|
|
@chapter Installation
|
|
|
|
If you use Debian, you may want to install one of the
|
|
precompiled packages for your system. These packages are equipped with
|
|
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, 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'.
|
|
More detailed instructions are in the file @file{INSTALL}, which is
|
|
included in the source distribution.
|
|
|
|
@menu
|
|
* Building and installing tinc::
|
|
* System files::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Building and installing tinc, System files, Installation, Installation
|
|
@section Building and installing tinc
|
|
|
|
Detailed instructions on configuring the source, building tinc and installing tinc
|
|
can be found in the file called @file{INSTALL}.
|
|
|
|
@cindex binary package
|
|
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::
|
|
* Cygwin (Windows) build environment::
|
|
* MinGW (Windows) build environment::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Darwin (MacOS/X) build environment, Cygwin (Windows) 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 Cygwin (Windows) build environment, MinGW (Windows) build environment, Darwin (MacOS/X) build environment, Building and installing tinc
|
|
@subsection Cygwin (Windows) build environment
|
|
|
|
If Cygwin hasn't already been installed, install it directly from
|
|
@uref{http://www.cygwin.com/}.
|
|
|
|
When tinc is compiled in a Cygwin environment, it can only be run in this environment,
|
|
but all programs, including those started outside the Cygwin environment, will be able to use the VPN.
|
|
It will also support all features.
|
|
|
|
@c ==================================================================
|
|
@node MinGW (Windows) build environment, , Cygwin (Windows) build environment, Building and installing tinc
|
|
@subsection MinGW (Windows) build environment
|
|
|
|
You will need to install the MinGW environment from @uref{http://www.mingw.org}.
|
|
|
|
When tinc is compiled using MinGW it runs natively under Windows,
|
|
it is not necessary to keep MinGW installed.
|
|
However, when compiled using MinGW, tinc will not be able to start
|
|
scripts or be able to receive signals.
|
|
|
|
|
|
@c ==================================================================
|
|
@node System files, , Building and installing tinc, Installation
|
|
@section System files
|
|
|
|
Before you can run tinc, you must make sure you have all the needed
|
|
files on your system.
|
|
|
|
@menu
|
|
* Device files::
|
|
* Other files::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Device files, Other files, System files, System files
|
|
@subsection Device files
|
|
|
|
@cindex device files
|
|
First, you'll need the special device file(s) that form the interface
|
|
between the kernel and the daemon.
|
|
|
|
The permissions for these files have to be such that only the super user
|
|
may read/write to this file. You'd want this, because otherwise
|
|
eavesdropping would become a bit too easy. This does, however, imply
|
|
that you'd have to run tincd as root.
|
|
|
|
If you use Linux and have a kernel version prior to 2.4.0, you have to make the
|
|
ethertap devices:
|
|
|
|
@example
|
|
mknod -m 600 /dev/tap0 c 36 16
|
|
mknod -m 600 /dev/tap1 c 36 17
|
|
...
|
|
mknod -m 600 /dev/tap@emph{N} c 36 @emph{N+16}
|
|
@end example
|
|
|
|
There is a maximum of 16 ethertap devices.
|
|
|
|
If you use the universal tun/tap driver, you have to create the
|
|
following device file (unless it already exist):
|
|
|
|
@example
|
|
mknod -m 600 /dev/tun c 10 200
|
|
@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/net/tun}.
|
|
|
|
Unlike the ethertap device, you do not need multiple device files if
|
|
you are planning to run multiple tinc daemons.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Other files, , Device files, System files
|
|
@subsection Other files
|
|
|
|
@subsubheading @file{/etc/networks}
|
|
|
|
You may add a line to @file{/etc/networks} so that your VPN will get a
|
|
symbolic name. For example:
|
|
|
|
@example
|
|
myvpn 10.0.0.0
|
|
@end example
|
|
|
|
@subsubheading @file{/etc/services}
|
|
|
|
@cindex port numbers
|
|
You may add this line to @file{/etc/services}. The effect is that you
|
|
may supply a @samp{tinc} as a valid port number to some programs. The
|
|
number 655 is registered with the IANA.
|
|
|
|
@example
|
|
tinc 655/tcp TINC
|
|
tinc 655/udp TINC
|
|
# Ivo Timmermans <ivo@@o2w.nl>
|
|
@end example
|
|
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@c
|
|
@c Configuring tinc
|
|
@c
|
|
@c
|
|
@c
|
|
@c
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuration, Running tinc, Installation, Top
|
|
@chapter Configuration
|
|
|
|
@menu
|
|
* Configuration introduction::
|
|
* Multiple networks::
|
|
* How connections work::
|
|
* Configuration files::
|
|
* Generating keypairs::
|
|
* Network interfaces::
|
|
* Example configuration::
|
|
@end menu
|
|
|
|
@c ==================================================================
|
|
@node Configuration introduction, Multiple networks, Configuration, Configuration
|
|
@section Configuration introduction
|
|
|
|
@cindex Network Administrators Guide
|
|
Before actually starting to configure tinc and editing files,
|
|
make sure you have read this entire section so you know what to expect.
|
|
Then, make it clear to yourself how you want to organize your VPN:
|
|
What are the nodes (computers running tinc)?
|
|
What IP addresses/subnets do they have?
|
|
What is the network mask of the entire VPN?
|
|
Do you need special firewall rules?
|
|
Do you have to set up masquerading or forwarding rules?
|
|
These questions can only be answered by yourself,
|
|
you will not find the answers in this documentation.
|
|
Make sure you have an adequate understanding of networks in general.
|
|
A good resource on networking is the
|
|
@uref{http://www.linuxdoc.org/LDP/nag2/, Linux Network Administrators Guide}.
|
|
|
|
If you have everything clearly pictured in your mind,
|
|
proceed in the following order:
|
|
First, generate the configuration files (@file{tinc.conf}, your host configuration file, @file{tinc-up} and perhaps @file{tinc-down}).
|
|
Then generate the keypairs.
|
|
Finally, distribute the host configuration files.
|
|
These steps are described in the subsections below.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Multiple networks, How connections work, Configuration introduction, Configuration
|
|
@section Multiple networks
|
|
|
|
@cindex multiple networks
|
|
@cindex netname
|
|
In order to allow you to run more than one tinc daemon on one computer,
|
|
for instance if your computer is part of more than one VPN,
|
|
you can assign a ``netname'' to your VPN.
|
|
It is not required if you only run one tinc daemon,
|
|
it doesn't even have to be the same on all the sites of your VPN,
|
|
but it is recommended that you choose one anyway.
|
|
|
|
We will asume you use a netname throughout this document.
|
|
This means that you call tincd with the -n argument,
|
|
which will assign a netname to this daemon.
|
|
|
|
The effect of this is that the daemon will set its configuration
|
|
``root'' to /etc/tinc/netname/, where netname is your argument to the -n
|
|
option. You'll notice that it appears in syslog as ``tinc.netname''.
|
|
|
|
However, it is not strictly necessary that you call tinc with the -n
|
|
option. In this case, the network name would just be empty, and it will
|
|
be used as such. tinc now looks for files in /etc/tinc/, instead of
|
|
/etc/tinc/netname/; the configuration file should be /etc/tinc/tinc.conf,
|
|
and the host configuration files are now expected to be in /etc/tinc/hosts/.
|
|
|
|
But it is highly recommended that you use this feature of tinc, because
|
|
it will be so much clearer whom your daemon talks to. Hence, we will
|
|
assume that you use it.
|
|
|
|
|
|
@c ==================================================================
|
|
@node How connections work, Configuration files, Multiple networks, Configuration
|
|
@section How connections work
|
|
|
|
When tinc starts up, it parses the command-line options and then
|
|
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,
|
|
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 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 each other however.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuration files, Generating keypairs, How connections work, Configuration
|
|
@section Configuration files
|
|
|
|
The actual configuration of the daemon is done in the file
|
|
@file{/etc/tinc/netname/tinc.conf} and at least one other file in the directory
|
|
@file{/etc/tinc/netname/hosts/}.
|
|
|
|
These file consists of comments (lines started with a #) or assignments
|
|
in the form of
|
|
|
|
@example
|
|
Variable = Value.
|
|
@end example
|
|
|
|
The variable names are case insensitive, and any spaces, tabs, newlines
|
|
and carriage returns are ignored. Note: it is not required that you put
|
|
in the `=' sign, but doing so improves readability. If you leave it
|
|
out, remember to replace it with at least one space character.
|
|
|
|
In this section all valid variables are listed in alphabetical order.
|
|
The default value is given between parentheses,
|
|
other comments are between square brackets and
|
|
required directives are given in @strong{bold}.
|
|
|
|
@menu
|
|
* Main configuration variables::
|
|
* Host configuration variables::
|
|
* How to configure::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Main configuration variables, Host configuration variables, Configuration files, Configuration files
|
|
@subsection Main configuration variables
|
|
|
|
@table @asis
|
|
@cindex AddressFamily
|
|
@item AddressFamily = <ipv4|ipv6|any> (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 = <address> [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 = <interface> [experimental]
|
|
If you have more than one network interface in your computer, tinc will
|
|
by default listen on all of them for incoming connections. It is
|
|
possible to bind tinc to a single interface like eth0 or ppp0 with this
|
|
variable.
|
|
|
|
This option may not work on all platforms.
|
|
|
|
@cindex ConnectTo
|
|
@item @strong{ConnectTo = <name>}
|
|
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,
|
|
tinc won't try to connect to other daemons at all,
|
|
and will instead just listen for incoming connections.
|
|
|
|
@cindex Device
|
|
@item @strong{Device = <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}.
|
|
|
|
@cindex Hostnames
|
|
@item Hostnames = <yes|no> (no)
|
|
This option selects whether IP addresses (both real and on the VPN)
|
|
should be resolved. Since DNS lookups are blocking, it might affect
|
|
tinc's efficiency, even stopping the daemon for a few seconds everytime
|
|
it does a lookup if your DNS server is not responding.
|
|
|
|
This does not affect resolving hostnames to IP addresses from the
|
|
configuration file.
|
|
|
|
@cindex Interface
|
|
@item Interface = <interface>
|
|
Defines the name of the interface corresponding to the virtual network device.
|
|
Depending on the operating system and the type of device this may or may not actually set the name of the interface
|
|
or choose the device corresponding to this interface.
|
|
|
|
@cindex Mode
|
|
@item Mode = <router|switch|hub> (router)
|
|
This option selects the way packets are routed to other daemons.
|
|
|
|
@table @asis
|
|
@cindex router
|
|
@item router
|
|
In this mode Subnet
|
|
variables in the host configuration files will be used to form a routing table.
|
|
Only unicast packets of routable protocols (IPv4 and IPv6) are supported in this mode.
|
|
|
|
This is the default mode, and unless you really know you need another mode, don't change it.
|
|
|
|
@cindex switch
|
|
@item switch
|
|
In this mode the MAC addresses of the packets on the VPN will be used to
|
|
dynamically create a routing table just like an Ethernet switch does.
|
|
Unicast, multicast and broadcast packets of every protocol that runs over Ethernet are supported in this mode
|
|
at the cost of frequent broadcast ARP requests and routing table updates.
|
|
|
|
This mode is primarily useful if you want to bridge Ethernet segments.
|
|
|
|
@cindex hub
|
|
@item hub
|
|
This mode is almost the same as the switch mode, but instead
|
|
every packet will be broadcast to the other daemons
|
|
while no routing table is managed.
|
|
@end table
|
|
|
|
@cindex KeyExpire
|
|
@item KeyExpire = <seconds> (3600)
|
|
This option controls the time the encryption keys used to encrypt the data
|
|
are valid. It is common practice to change keys at regular intervals to
|
|
make it even harder for crackers, even though it is thought to be nearly
|
|
impossible to crack a single key.
|
|
|
|
@cindex MACExpire
|
|
@item MACExpire = <seconds> (600)
|
|
This option controls the amount of time MAC addresses are kept before they are removed.
|
|
This only has effect when Mode is set to "switch".
|
|
|
|
@cindex Name
|
|
@item @strong{Name = <name>}
|
|
This is a symbolic name for this connection. It can be anything
|
|
|
|
@cindex PingTimeout
|
|
@item PingTimeout = <seconds> (60)
|
|
The number of seconds of inactivity that tinc will wait before sending a
|
|
probe to the other end. If that other end doesn't answer within that
|
|
same amount of seconds, the connection is terminated, and the others
|
|
will be notified of this.
|
|
|
|
@cindex PriorityInheritance
|
|
@item PriorityInheritance = <yes|no> (no) [experimental]
|
|
When this option is enabled the value of the TOS field of tunneled IPv4 packets
|
|
will be inherited by the UDP packets that are sent out.
|
|
|
|
@cindex PrivateKey
|
|
@item PrivateKey = <key> [obsolete]
|
|
This is the RSA private key for tinc. However, for safety reasons it is
|
|
advised to store private keys of any kind in separate files. This prevents
|
|
accidental eavesdropping if you are editting the configuration file.
|
|
|
|
@cindex PrivateKeyFile
|
|
@item @strong{PrivateKeyFile = <path>} [recommended]
|
|
This is the full path name of the RSA private key file that was
|
|
generated by ``tincd --generate-keys''. It must be a full path, not a
|
|
relative directory.
|
|
|
|
Note that there must be exactly one of PrivateKey
|
|
or PrivateKeyFile
|
|
specified in the configuration file.
|
|
|
|
@end table
|
|
|
|
|
|
@c ==================================================================
|
|
@node Host configuration variables, How to configure, Main configuration variables, Configuration files
|
|
@subsection Host configuration variables
|
|
|
|
@table @asis
|
|
@cindex Address
|
|
@item @strong{Address = <IP address|hostname>} [recommended]
|
|
This variable is only required if you want to connect to this host. It
|
|
must resolve to the external IP address where the host can be reached,
|
|
not the one that is internal to the VPN.
|
|
|
|
@cindex Cipher
|
|
@item Cipher = <cipher> (blowfish)
|
|
The symmetric cipher algorithm used to encrypt UDP packets.
|
|
Any cipher supported by OpenSSL is recognized.
|
|
|
|
@cindex Compression
|
|
@item Compression = <level> (0)
|
|
This option sets the level of compression used for UDP packets.
|
|
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 = <digest> (sha1)
|
|
The digest algorithm used to authenticate UDP packets.
|
|
Any digest supported by OpenSSL is recognized.
|
|
Furthermore, specifying "none" will turn off packet authentication.
|
|
|
|
@cindex IndirectData
|
|
@item IndirectData = <yes|no> (no)
|
|
This option specifies whether other tinc daemons besides the one you
|
|
specified with ConnectTo can make a direct connection to you. This is
|
|
especially useful if you are behind a firewall and it is impossible to
|
|
make a connection from the outside to your tinc daemon. Otherwise, it
|
|
is best to leave this option out or set it to no.
|
|
|
|
@cindex MACLength
|
|
@item MACLength = <length> (4)
|
|
The length of the message authentication code used to authenticate UDP packets.
|
|
Can be anything from 0
|
|
up to the length of the digest produced by the digest algorithm.
|
|
|
|
@cindex Port
|
|
@item Port = <port> (655)
|
|
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 = <key> [obsolete]
|
|
This is the RSA public key for this host.
|
|
|
|
@cindex PublicKeyFile
|
|
@item PublicKeyFile = <path> [obsolete]
|
|
This is the full path name of the RSA public key file that was generated
|
|
by ``tincd --generate-keys''. It must be a full path, not a relative
|
|
directory.
|
|
|
|
@cindex PEM format
|
|
From version 1.0pre4 on tinc will store the public key directly into the
|
|
host configuration file in PEM format, the above two options then are not
|
|
necessary. Either the PEM format is used, or exactly
|
|
@strong{one of the above two options} must be specified
|
|
in each host configuration file, if you want to be able to establish a
|
|
connection with that host.
|
|
|
|
@cindex Subnet
|
|
@item Subnet = <address[/prefixlength]>
|
|
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,
|
|
it will be sent to the daemon who has this subnet in his host configuration file.
|
|
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 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.
|
|
Note that subnets like 192.168.1.1/24 are invalid!
|
|
Read a networking HOWTO/FAQ/guide if you don't understand this.
|
|
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
|
|
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}
|
|
|
|
@cindex TCPonly
|
|
@item TCPonly = <yes|no> (no) [experimental]
|
|
If this variable is set to yes, then the packets are tunnelled over a
|
|
TCP connection instead of a UDP connection. This is especially useful
|
|
for those who want to run a tinc daemon from behind a masquerading
|
|
firewall, or if UDP packet routing is disabled somehow.
|
|
Setting this options also implicitly sets IndirectData.
|
|
@end table
|
|
|
|
|
|
@c ==================================================================
|
|
@node How to configure, , Host configuration variables, Configuration files
|
|
@subsection How to configure
|
|
|
|
@subsubheading Step 1. Creating the main configuration file
|
|
|
|
The main configuration file will be called @file{/etc/tinc/netname/tinc.conf}.
|
|
Adapt the following example to create a basic configuration file:
|
|
|
|
@example
|
|
Name = @emph{yourname}
|
|
Device = @emph{/dev/tap0}
|
|
PrivateKeyFile = /etc/tinc/@emph{netname}/rsa_key.priv
|
|
@end example
|
|
|
|
Then, if you know to which other tinc daemon(s) yours is going to connect,
|
|
add `ConnectTo' values.
|
|
|
|
@subsubheading Step 2. Creating your host configuration file
|
|
|
|
If you added a line containing `Name = yourname' in the main configuarion file,
|
|
you will need to create a host configuration file @file{/etc/tinc/netname/hosts/yourname}.
|
|
Adapt the following example to create a host configuration file:
|
|
|
|
@example
|
|
Address = @emph{your.real.hostname.org}
|
|
Subnet = @emph{192.168.1.0/24}
|
|
@end example
|
|
|
|
You can also use an IP address instead of a hostname.
|
|
The `Subnet' specifies the address range that is local for @emph{your part of the VPN only}.
|
|
If you have multiple address ranges you can specify more than one `Subnet'.
|
|
You might also need to add a `Port' if you want your tinc daemon to run on a different port number than the default (655).
|
|
|
|
|
|
@c ==================================================================
|
|
@node Generating keypairs, Network interfaces, Configuration files, Configuration
|
|
@section Generating keypairs
|
|
|
|
@cindex key generation
|
|
Now that you have already created the main configuration file and your host configuration file,
|
|
you can easily create a public/private keypair by entering the following command:
|
|
|
|
@example
|
|
tincd -n @emph{netname} -K
|
|
@end example
|
|
|
|
tinc will generate a public and a private key and ask you where to put them.
|
|
Just press enter to accept the defaults.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Network interfaces, Example configuration, Generating keypairs, Configuration
|
|
@section Network interfaces
|
|
|
|
Before tinc can start transmitting data over the tunnel, it must
|
|
set up the virtual network interface.
|
|
|
|
First, decide which IP addresses you want to have associated with these
|
|
devices, and what network mask they must have.
|
|
|
|
tinc will open a virtual network device (@file{/dev/tun}, @file{/dev/tap0} or similar),
|
|
which will also create a network interface called something like `tun0', `tap0', or,
|
|
if you are using the Linux tun/tap driver, the network interface will by default have the same name as the netname.
|
|
|
|
@cindex tinc-up
|
|
You can configure the network interface by putting ordinary ifconfig, route, and other commands
|
|
to a script named @file{/etc/tinc/netname/tinc-up}. When tinc starts, this script
|
|
will be executed. When tinc exits, it will execute the script named
|
|
@file{/etc/tinc/netname/tinc-down}, but normally you don't need to create that script.
|
|
|
|
An example @file{tinc-up} script:
|
|
|
|
@example
|
|
#!/bin/sh
|
|
ifconfig $INTERFACE 192.168.1.1 netmask 255.255.0.0
|
|
@end example
|
|
|
|
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.
|
|
@cindex netmask
|
|
The netmask is the mask of the @emph{entire} VPN network, not just your
|
|
own subnet.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Example configuration, , Network interfaces, Configuration
|
|
@section Example configuration
|
|
|
|
|
|
@cindex example
|
|
Imagine the following situation. Branch A of our example `company' wants to connect
|
|
three branch offices in B, C and D using the Internet. All four offices
|
|
have a 24/7 connection to the Internet.
|
|
|
|
A is going to serve as the center of the network. B and C will connect
|
|
to A, and D will connect to C. Each office will be assigned their own IP
|
|
network, 10.x.0.0.
|
|
|
|
@example
|
|
A: net 10.1.0.0 mask 255.255.0.0 gateway 10.1.54.1 internet IP 1.2.3.4
|
|
B: net 10.2.0.0 mask 255.255.0.0 gateway 10.2.1.12 internet IP 2.3.4.5
|
|
C: net 10.3.0.0 mask 255.255.0.0 gateway 10.3.69.254 internet IP 3.4.5.6
|
|
D: net 10.4.0.0 mask 255.255.0.0 gateway 10.4.3.32 internet IP 4.5.6.7
|
|
@end example
|
|
|
|
``gateway'' is the VPN IP address of the machine that is running the
|
|
tincd. ``internet IP'' is the IP address of the firewall, which does not
|
|
need to run tincd, but it must do a port forwarding of TCP&UDP on port
|
|
655 (unless otherwise configured).
|
|
|
|
In this example, it is assumed that eth0 is the interface that points to
|
|
the inner (physical) LAN of the office, although this could also be the
|
|
same as the interface that leads to the Internet. The configuration of
|
|
the real interface is also shown as a comment, to give you an idea of
|
|
how these example host is set up. All branches use the netname `company'
|
|
for this particular VPN.
|
|
|
|
@subsubheading For Branch A
|
|
|
|
@emph{BranchA} would be configured like this:
|
|
|
|
In @file{/etc/tinc/company/tinc-up}:
|
|
|
|
@example
|
|
# Real interface of internal network:
|
|
# ifconfig eth0 10.1.54.1 netmask 255.255.0.0 broadcast 10.1.255.255
|
|
|
|
ifconfig $INTERFACE 10.1.54.1 netmask 255.0.0.0
|
|
@end example
|
|
|
|
and in @file{/etc/tinc/company/tinc.conf}:
|
|
|
|
@example
|
|
Name = BranchA
|
|
PrivateKeyFile = /etc/tinc/company/rsa_key.priv
|
|
Device = /dev/tap0
|
|
@end example
|
|
|
|
On all hosts, /etc/tinc/company/hosts/BranchA contains:
|
|
|
|
@example
|
|
Subnet = 10.1.0.0/16
|
|
Address = 1.2.3.4
|
|
|
|
-----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
|
|
|
|
In @file{/etc/tinc/company/tinc-up}:
|
|
|
|
@example
|
|
# Real interface of internal network:
|
|
# ifconfig eth0 10.2.43.8 netmask 255.255.0.0 broadcast 10.2.255.255
|
|
|
|
ifconfig $INTERFACE 10.2.1.12 netmask 255.0.0.0
|
|
@end example
|
|
|
|
and in @file{/etc/tinc/company/tinc.conf}:
|
|
|
|
@example
|
|
Name = BranchB
|
|
ConnectTo = BranchA
|
|
PrivateKeyFile = /etc/tinc/company/rsa_key.priv
|
|
@end example
|
|
|
|
Note here that the internal address (on eth0) doesn't have to be the
|
|
same as on the tap0 device. Also, ConnectTo is given so that no-one can
|
|
connect to this node.
|
|
|
|
On all hosts, in @file{/etc/tinc/company/hosts/BranchB}:
|
|
|
|
@example
|
|
Subnet = 10.2.0.0/16
|
|
Address = 2.3.4.5
|
|
|
|
-----BEGIN RSA PUBLIC KEY-----
|
|
...
|
|
-----END RSA PUBLIC KEY-----
|
|
@end example
|
|
|
|
|
|
@subsubheading For Branch C
|
|
|
|
In @file{/etc/tinc/company/tinc-up}:
|
|
|
|
@example
|
|
# Real interface of internal network:
|
|
# ifconfig eth0 10.3.69.254 netmask 255.255.0.0 broadcast 10.3.255.255
|
|
|
|
ifconfig $INTERFACE 10.3.69.254 netmask 255.0.0.0
|
|
@end example
|
|
|
|
and in @file{/etc/tinc/company/tinc.conf}:
|
|
|
|
@example
|
|
Name = BranchC
|
|
ConnectTo = BranchA
|
|
Device = /dev/tap1
|
|
@end example
|
|
|
|
C already has another daemon that runs on port 655, so they have to
|
|
reserve another port for tinc. It knows the portnumber it has to listen on
|
|
from it's own host configuration file.
|
|
|
|
On all hosts, in @file{/etc/tinc/company/hosts/BranchC}:
|
|
|
|
@example
|
|
Address = 3.4.5.6
|
|
Subnet = 10.3.0.0/16
|
|
Port = 2000
|
|
|
|
-----BEGIN RSA PUBLIC KEY-----
|
|
...
|
|
-----END RSA PUBLIC KEY-----
|
|
@end example
|
|
|
|
|
|
@subsubheading For Branch D
|
|
|
|
In @file{/etc/tinc/company/tinc-up}:
|
|
|
|
@example
|
|
# Real interface of internal network:
|
|
# ifconfig eth0 10.4.3.32 netmask 255.255.0.0 broadcast 10.4.255.255
|
|
|
|
ifconfig $INTERFACE 10.4.3.32 netmask 255.0.0.0
|
|
@end example
|
|
|
|
and in @file{/etc/tinc/company/tinc.conf}:
|
|
|
|
@example
|
|
Name = BranchD
|
|
ConnectTo = BranchC
|
|
Device = /dev/net/tun
|
|
PrivateKeyFile = /etc/tinc/company/rsa_key.priv
|
|
@end example
|
|
|
|
D will be connecting to C, which has a tincd running for this network on
|
|
port 2000. It knows the port number from the host configuration file.
|
|
Also note that since D uses the tun/tap driver, the network interface
|
|
will not be called `tun' or `tap0' or something like that, but will
|
|
have the same name as netname.
|
|
|
|
On all hosts, in @file{/etc/tinc/company/hosts/BranchD}:
|
|
|
|
@example
|
|
Subnet = 10.4.0.0/16
|
|
Address = 4.5.6.7
|
|
|
|
-----BEGIN RSA PUBLIC KEY-----
|
|
...
|
|
-----END RSA PUBLIC KEY-----
|
|
@end example
|
|
|
|
@subsubheading Key files
|
|
|
|
A, B, C and D all have generated a public/private keypair with the following command:
|
|
|
|
@example
|
|
tincd -n company -K
|
|
@end example
|
|
|
|
The private key is stored in @file{/etc/tinc/company/rsa_key.priv},
|
|
the public key is put into the host configuration file in the @file{/etc/tinc/company/hosts/} directory.
|
|
During key generation, tinc automatically guesses the right filenames based on the -n option and
|
|
the Name directive in the @file{tinc.conf} file (if it is available).
|
|
|
|
@subsubheading Starting
|
|
|
|
After each branch has finished configuration and they have distributed
|
|
the host configuration files amongst them, they can start their tinc daemons.
|
|
They don't necessarily have to wait for the other branches to have started
|
|
their daemons, tinc will try connecting until they are available.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Running tinc, Technical information, Configuration, Top
|
|
@chapter Running tinc
|
|
|
|
If everything else is done, you can start tinc by typing the following command:
|
|
|
|
@example
|
|
tincd -n @emph{netname}
|
|
@end example
|
|
|
|
@cindex daemon
|
|
tinc will detach from the terminal and continue to run in the background like a good daemon.
|
|
If there are any problems however you can try to increase the debug level
|
|
and look in the syslog to find out what the problems are.
|
|
|
|
@menu
|
|
* Runtime options::
|
|
* Error messages::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Runtime options, Error messages, , Running tinc
|
|
@section Runtime options
|
|
|
|
Besides the settings in the configuration file, tinc also accepts some
|
|
command line options.
|
|
|
|
@cindex command line
|
|
@cindex runtime options
|
|
@cindex options
|
|
@c from the manpage
|
|
@table @samp
|
|
@item -c, --config=PATH
|
|
Read configuration options from the directory PATH. The default is
|
|
@file{/etc/tinc/netname/}.
|
|
|
|
@item -D, --no-detach
|
|
Don't fork and detach.
|
|
This will also disable the automatic restart mechanism for fatal errors.
|
|
|
|
@cindex debug level
|
|
@item -d, --debug=LEVEL
|
|
Set debug level to LEVEL. The higher the debug level, the more gets
|
|
logged. Everything goes via syslog.
|
|
|
|
@item -k, --kill[=SIGNAL]
|
|
Attempt to kill a running tincd (optionally with the specified SIGNAL instead of SIGTERM) and exit.
|
|
Use it in conjunction with the -n option to make sure you kill the right tinc daemon.
|
|
|
|
@item -n, --net=NETNAME
|
|
Connect to net NETNAME. @xref{Multiple networks}.
|
|
|
|
@item -K, --generate-keys[=BITS]
|
|
Generate public/private keypair of BITS length. If BITS is not specified,
|
|
1024 is the default. tinc will ask where you want to store the files,
|
|
but will default to the configuration directory (you can use the -c or -n option
|
|
in combination with -K). After that, tinc will quit.
|
|
|
|
@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 --logfile[=FILE]
|
|
Write log entries to a file instead of to the system logging facility.
|
|
If FILE is omitted, the default is /var/log/tinc.NETNAME.log.
|
|
|
|
@item --pidfile=FILE
|
|
Write PID to FILE instead of /var/run/tinc.NETNAME.pid.
|
|
|
|
@item --bypass-security
|
|
Disables encryption and authentication.
|
|
Only useful for debugging.
|
|
|
|
@item --help
|
|
Display a short reminder of these runtime options and terminate.
|
|
|
|
@item --version
|
|
Output version information and exit.
|
|
|
|
@end table
|
|
|
|
|
|
@c ==================================================================
|
|
@node Error messages, , Runtime options, Running tinc
|
|
@section Error messages
|
|
|
|
What follows is a list of the most common error messages you can see
|
|
when configuring tinc. Most of these messages are visible in the syslog
|
|
only, so keep an eye on it!
|
|
|
|
@table @strong
|
|
@item Could not open /dev/tap0: No such device
|
|
|
|
@itemize
|
|
@item You forgot to `modprobe netlink_dev' or `modprobe ethertap'.
|
|
@item You forgot to compile `Netlink device emulation' in the kernel.
|
|
@end itemize
|
|
|
|
@item Can't write to /dev/net/tun: No such device
|
|
|
|
@itemize
|
|
@item You forgot to `modprobe tun'.
|
|
@item You forgot to compile `Universal TUN/TAP driver' in the kernel.
|
|
@end itemize
|
|
|
|
@item Packet with destination 1.2.3.4 is looping back to us!
|
|
|
|
@itemize
|
|
@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 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!
|
|
@item Chances are that a `Subnet = ...' line in the host configuration file of this tinc daemon is wrong.
|
|
Change it to a subnet that is accepted locally by another interface,
|
|
or if that is not the case, try changing the prefix length into /32.
|
|
@end itemize
|
|
|
|
@item Network doesn't work, syslog shows only packets of length 46
|
|
|
|
@item Network address and prefix length do not match!
|
|
|
|
@itemize
|
|
@item The Subnet field must contain a @emph{network} address.
|
|
@item If you only want to use one IP address, set the netmask to /32.
|
|
@end itemize
|
|
|
|
@item This is a bug: net.c:253: 24: Some error
|
|
|
|
@itemize
|
|
@item This is something that should not have happened.
|
|
Please report this, and tell us exactly what went wrong before you got
|
|
this message. In normal operation, these errors should not occur.
|
|
@end itemize
|
|
|
|
@item Error reading RSA key file `rsa_key.priv': No such file or directory
|
|
|
|
@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).
|
|
@end itemize
|
|
|
|
@end table
|
|
|
|
@c ==================================================================
|
|
@node Technical information, About us, Running tinc, Top
|
|
@chapter Technical information
|
|
|
|
|
|
@menu
|
|
* The connection::
|
|
* The meta-protocol::
|
|
* Security::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node The connection, The meta-protocol, Technical information, Technical information
|
|
@section The connection
|
|
|
|
@cindex connection
|
|
tinc is a daemon that takes VPN data and transmit that to another host
|
|
computer over the existing Internet infrastructure.
|
|
|
|
@menu
|
|
* The UDP tunnel::
|
|
* The meta-connection::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node The UDP tunnel, The meta-connection, The connection, The connection
|
|
@subsection The UDP tunnel
|
|
|
|
@cindex virtual network device
|
|
@cindex frame type
|
|
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.
|
|
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 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,
|
|
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
|
|
When that is done, time has come to actually transport the
|
|
packet to the destination computer. We do this by sending the packet
|
|
over an UDP connection to the destination host. This is called
|
|
@emph{encapsulating}, the VPN packet (though now encrypted) is
|
|
encapsulated in another IP datagram.
|
|
|
|
When the destination receives this packet, the same thing happens, only
|
|
in reverse. So it checks the message authentication code, decrypts the contents of the UDP datagram,
|
|
checks the sequence number
|
|
and writes the decrypted information to its own virtual network device.
|
|
|
|
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 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.
|
|
|
|
@cindex TCP
|
|
TCP is a better alternative, because it already contains protection
|
|
against information being lost, unlike UDP.
|
|
|
|
So we establish two connections. One for the encrypted VPN data, and one
|
|
for other information, the meta-data. Hence, we call the second
|
|
connection the meta-connection. We can now be sure that the
|
|
meta-information doesn't get lost on the way to another computer.
|
|
|
|
@cindex data-protocol
|
|
@cindex meta-protocol
|
|
Like with any communication, we must have a protocol, so that everybody
|
|
knows what everything stands for, and how she should react. Because we
|
|
have two connections, we also have two protocols. The protocol used for
|
|
the UDP data is the ``data-protocol,'' the other one is the
|
|
``meta-protocol.''
|
|
|
|
The reason we don't use TCP for both protocols is that UDP is much
|
|
better for encapsulation, even while it is less reliable. The real
|
|
problem is that when TCP would be used to encapsulate a TCP stream
|
|
that's on the private network, for every packet sent there would be
|
|
three ACKs sent instead of just one. Furthermore, if there would be
|
|
a timeout, both TCP streams would sense the timeout, and both would
|
|
start re-sending packets.
|
|
|
|
|
|
@c ==================================================================
|
|
@node The meta-protocol, Security, The connection, Technical information
|
|
@section The meta-protocol
|
|
|
|
The meta protocol is used to tie all tinc daemons together, and
|
|
exchange information about which tinc daemon serves which virtual
|
|
subnet.
|
|
|
|
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 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
|
|
successful authentication, the server and the client will exchange all the
|
|
information about other tinc daemons and subnets they know of, so that both
|
|
sides (and all the other tinc daemons behind them) have their information
|
|
synchronised.
|
|
|
|
@cindex ADD_EDGE
|
|
@cindex ADD_SUBNET
|
|
@example
|
|
daemon message
|
|
--------------------------------------------------------------------------
|
|
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
|
|
| | +--> 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.
|
|
|
|
@cindex PING
|
|
@cindex PONG
|
|
@example
|
|
daemon message
|
|
--------------------------------------------------------------------------
|
|
origin PING
|
|
dest. PONG
|
|
--------------------------------------------------------------------------
|
|
@end example
|
|
|
|
There is also a mechanism to check if hosts are still alive. Since network
|
|
failures or a crash can cause a daemon to be killed without properly
|
|
shutting down the TCP connection, this is necessary to keep an up to date
|
|
connection list. PINGs are sent at regular intervals, except when there
|
|
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.
|
|
|
|
This basically covers what is sent over the meta connection by
|
|
tinc.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Security, , The meta-protocol, Technical information
|
|
@section About tinc's encryption and other security-related issues.
|
|
|
|
@cindex TINC
|
|
@cindex Cabal
|
|
tinc got its name from ``TINC,'' short for @emph{There Is No Cabal}; the
|
|
alleged Cabal was/is an organisation that was said to keep an eye on the
|
|
entire Internet. As this is exactly what you @emph{don't} want, we named
|
|
the tinc project after TINC.
|
|
|
|
@cindex SVPN
|
|
But in order to be ``immune'' to eavesdropping, you'll have to encrypt
|
|
your data. Because tinc is a @emph{Secure} VPN (SVPN) daemon, it does
|
|
exactly that: encrypt.
|
|
tinc by default uses blowfish encryption with 128 bit keys in CBC mode, 32 bit
|
|
sequence numbers and 4 byte long message authentication codes to make sure
|
|
eavesdroppers cannot get and cannot change any information at all from the
|
|
packets they can intercept. The encryption algorithm and message authentication
|
|
algorithm can be changed in the configuration. The length of the message
|
|
authentication codes is also adjustable. The length of the key for the
|
|
encryption algorithm is always the default length used by OpenSSL.
|
|
|
|
@menu
|
|
* Authentication protocol::
|
|
* Encryption of network packets::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Authentication protocol, Encryption of network packets, Security, Security
|
|
@subsection Authentication protocol
|
|
|
|
@cindex authentication
|
|
A new scheme for authentication in tinc has been devised, which offers some
|
|
improvements over the protocol used in 1.0pre2 and 1.0pre3. Explanation is
|
|
below.
|
|
|
|
@cindex ID
|
|
@cindex META_KEY
|
|
@cindex CHALLENGE
|
|
@cindex CHAL_REPLY
|
|
@cindex ACK
|
|
@example
|
|
daemon message
|
|
--------------------------------------------------------------------------
|
|
client <attempts connection>
|
|
|
|
server <accepts connection>
|
|
|
|
client ID client 12
|
|
| +---> version
|
|
+-------> name of tinc daemon
|
|
|
|
server ID server 12
|
|
| +---> version
|
|
+-------> name of tinc daemon
|
|
|
|
client META_KEY 5f0823a93e35b69e...7086ec7866ce582b
|
|
\_________________________________/
|
|
+-> RSAKEYLEN bits totally random string S1,
|
|
encrypted with server's public RSA key
|
|
|
|
server META_KEY 6ab9c1640388f8f0...45d1a07f8a672630
|
|
\_________________________________/
|
|
+-> RSAKEYLEN bits totally random string S2,
|
|
encrypted with client's public RSA key
|
|
|
|
From now on:
|
|
- the client will symmetrically encrypt outgoing traffic using S1
|
|
- the server will symmetrically encrypt outgoing traffic using S2
|
|
|
|
client CHALLENGE da02add1817c1920989ba6ae2a49cecbda0
|
|
\_________________________________/
|
|
+-> CHALLEN bits totally random string H1
|
|
|
|
server CHALLENGE 57fb4b2ccd70d6bb35a64c142f47e61d57f
|
|
\_________________________________/
|
|
+-> CHALLEN bits totally random string H2
|
|
|
|
client CHAL_REPLY 816a86
|
|
+-> 160 bits SHA1 of H2
|
|
|
|
server CHAL_REPLY 928ffe
|
|
+-> 160 bits SHA1 of H1
|
|
|
|
After the correct challenge replies are received, both ends have proved
|
|
their identity. Further information is exchanged.
|
|
|
|
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
|
|
|
|
This new scheme has several improvements, both in efficiency and security.
|
|
|
|
First of all, the server sends exactly the same kind of messages over the wire
|
|
as the client. The previous versions of tinc first authenticated the client,
|
|
and then the server. This scheme even allows both sides to send their messages
|
|
simultaneously, there is no need to wait for the other to send something first.
|
|
This means that any calculations that need to be done upon sending or receiving
|
|
a message can also be done in parallel. This is especially important when doing
|
|
RSA encryption/decryption. Given that these calculations are the main part of
|
|
the CPU time spent for the authentication, speed is improved by a factor 2.
|
|
|
|
Second, only one RSA encrypted message is sent instead of two. This reduces the
|
|
amount of information attackers can see (and thus use for a cryptographic
|
|
attack). It also improves speed by a factor two, making the total speedup a
|
|
factor 4.
|
|
|
|
Third, and most important:
|
|
The symmetric cipher keys are exchanged first, the challenge is done
|
|
afterwards. In the previous authentication scheme, because a man-in-the-middle
|
|
could pass the challenge/chal_reply phase (by just copying the messages between
|
|
the two real tinc daemons), but no information was exchanged that was really
|
|
needed to read the rest of the messages, the challenge/chal_reply phase was of
|
|
no real use. The man-in-the-middle was only stopped by the fact that only after
|
|
the ACK messages were encrypted with the symmetric cipher. Potentially, it
|
|
could even send it's own symmetric key to the server (if it knew the server's
|
|
public key) and read some of the metadata the server would send it (it was
|
|
impossible for the mitm to read actual network packets though). The new scheme
|
|
however prevents this.
|
|
|
|
This new scheme makes sure that first of all, symmetric keys are exchanged. The
|
|
rest of the messages are then encrypted with the symmetric cipher. Then, each
|
|
side can only read received messages if they have their private key. The
|
|
challenge is there to let the other side know that the private key is really
|
|
known, because a challenge reply can only be sent back if the challenge is
|
|
decrypted correctly, and that can only be done with knowledge of the private
|
|
key.
|
|
|
|
Fourth: the first thing that is send via the symmetric cipher encrypted
|
|
connection is a totally random string, so that there is no known plaintext (for
|
|
an attacker) in the beginning of the encrypted stream.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Encryption of network packets, , Authentication protocol, Security
|
|
@subsection Encryption of network packet
|
|
@cindex encryption
|
|
|
|
A data packet can only be sent if the encryption key is known to both
|
|
parties, and the connection is activated. If the encryption key is not
|
|
known, a request is sent to the destination using the meta connection
|
|
to retrieve it. The packet is stored in a queue while waiting for the
|
|
key to arrive.
|
|
|
|
@cindex UDP
|
|
The UDP packet containing the network packet from the VPN has the following layout:
|
|
|
|
@example
|
|
... | IP header | UDP header | seqno | VPN packet | MAC | UDP trailer
|
|
\___________________/\_____/
|
|
| |
|
|
V +---> digest algorithm
|
|
Encrypted with symmetric cipher
|
|
@end example
|
|
|
|
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
|
|
the MACLength configuration variable.
|
|
|
|
@c ==================================================================
|
|
@node About us, Concept Index, Technical information, Top
|
|
@chapter About us
|
|
|
|
|
|
@menu
|
|
* Contact Information::
|
|
* Authors::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Contact Information, Authors, About us, About us
|
|
@section Contact information
|
|
|
|
@cindex website
|
|
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 FreeNode and OFTC IRC networks. Connect to
|
|
@uref{http://www.freenode.net/, irc.freenode.net}
|
|
or
|
|
@uref{http://www.oftc.net/, irc.oftc.net}
|
|
and join channel #tinc.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Authors, , Contact Information, About us
|
|
@section Authors
|
|
|
|
@table @asis
|
|
@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,
|
|
tinc has become the flexible and robust tool that it is today. We have
|
|
composed a list of contributions, in the file called @file{THANKS} in
|
|
the source distribution.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Concept Index, , About us, Top
|
|
@c node-name, next, previous, up
|
|
@unnumbered Concept Index
|
|
|
|
@c ==================================================================
|
|
@printindex cp
|
|
|
|
|
|
@c ==================================================================
|
|
@contents
|
|
@bye
|