1178 lines
37 KiB
Text
1178 lines
37 KiB
Text
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename tinc.info
|
|
@settitle tinc Manual
|
|
@setchapternewpage odd
|
|
@c %**end of header
|
|
|
|
@ifinfo
|
|
|
|
This is the info manual for tinc, a Virtual Private Network daemon.
|
|
|
|
Copyright 1998 Ivo Timmermans <itimmermans@@bigfoot.com>
|
|
|
|
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 <itimmermans@@bigfoot.com>
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 1998 Ivo Timmermans <itimmermans@@bigfoot.com>
|
|
|
|
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
|
|
* Configuring a Linux system:: Before compiling tinc
|
|
* Installing tinc::
|
|
* Configuring tinc::
|
|
* Running tinc::
|
|
* Technical information::
|
|
* About us::
|
|
* Concept Index:: All used terms explained
|
|
@end menu
|
|
|
|
@c ==================================================================
|
|
@node Introduction, Configuring a Linux system, Top, Top
|
|
@chapter Introduction
|
|
|
|
@c straight from the www page
|
|
|
|
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.
|
|
|
|
This tunneling 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
|
|
@end menu
|
|
|
|
@c ==================================================================
|
|
@node VPNs, tinc, Introduction, Introduction
|
|
@section Virtual Private Networks
|
|
|
|
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
|
|
For instance, a VPN can consist of a single stand-alone ethernet LAN. Or
|
|
even two computers hooked up using a null-modem cable@footnote{Though
|
|
discuss-able, I think it qualifies as a VPN.}. In these cases, it is
|
|
obvious that the network is @emph{private}. But there is another type
|
|
of VPN, the type tinc was made for.
|
|
|
|
@cindex virtual
|
|
tinc uses normal IP datagrams to encapsulate data that goes over the VPN
|
|
network link. In this case it's also clear that the network is
|
|
@emph{virtual}, because no direct network link has to exist between to
|
|
participants.
|
|
|
|
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.
|
|
|
|
|
|
@c ==================================================================
|
|
@node tinc, , VPNs, Introduction
|
|
@section tinc
|
|
|
|
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 @emph{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.
|
|
|
|
A lot can---and will be---changed. I have a few things that I'd 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 Configuring a Linux system, Installing tinc, Introduction, Top
|
|
@chapter Configuring a Linux system
|
|
|
|
This chapter contains information on how a Linux system is configured
|
|
for the use of tinc.
|
|
|
|
@menu
|
|
* Configuring the kernel::
|
|
* Files Needed::
|
|
* Setting up the devices::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuring the kernel, Files Needed, Configuring a Linux system, Configuring a Linux system
|
|
@section Configuring the kernel
|
|
|
|
Since this particular implementation only runs on 2.1 or higher Linux
|
|
kernels, you should grab one (2.2 is current at this time). A 2.0 port
|
|
is not really possible, unless someone tells me someone ported the
|
|
ethertap and netlink devices back to 2.0.
|
|
|
|
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. Do that now!
|
|
|
|
Here are the options you have to turn on/off when configuring a new
|
|
kernel.
|
|
|
|
@example
|
|
Code maturity level options
|
|
[*] Prompt for development and/or incomplete code/drivers
|
|
Networking options
|
|
[*] Kernel/User netlink socket
|
|
<*> Netlink device emulation
|
|
Network device support
|
|
<*> Ethertap network tap
|
|
@end example
|
|
|
|
Any other options not mentioned here are not relevant to tinc. 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 tap0 ethertap
|
|
alias char-major-36 netlink_dev
|
|
@end example
|
|
|
|
Finally, after having set up other options, build the kernel and boot
|
|
it. Unfortunately it's not possible to insert these modules in a running
|
|
kernel.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Files Needed, Setting up the devices, Configuring the kernel, Configuring a Linux system
|
|
@section Files Needed
|
|
|
|
@subsubheading Device files
|
|
|
|
First, you'll need the special device file(s) that form the interface
|
|
between the kernel and the daemon.
|
|
|
|
@example
|
|
mknod -m 600 /dev/tap0 c 36 16
|
|
chown 0.0 /dev/tap0
|
|
@end example
|
|
|
|
The permissions now will 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 want to, you may also create more device files, which would be
|
|
numbered 0...15, with minor device numbers 16...31. They all should be
|
|
owned by root and have permission 600.
|
|
|
|
|
|
@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}
|
|
|
|
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 <itimmermans@@bigfoot.com>
|
|
@end example
|
|
|
|
|
|
@c ==================================================================
|
|
@node Setting up the devices, , Files Needed, Configuring a Linux system
|
|
@section Setting up the devices
|
|
|
|
Before you can start transmitting data over the tinc tunnel, you must
|
|
set up the ethertap network devices.
|
|
|
|
First, decide which IP addresses you want to have associated with these
|
|
devices, and what network mask they must have. You also need these
|
|
numbers when you are going to configure tinc itself. @xref{Configuring
|
|
tinc}.
|
|
|
|
It doesn't matter much which part you do first, setting up the network
|
|
devices or configure tinc. But they both have to be done before you try
|
|
to start a tincd.
|
|
|
|
The actual setup of the ethertap device is quite simple, just repeat
|
|
after me:
|
|
|
|
@example
|
|
ifconfig tap@emph{n} hw ether fe:fd:@emph{xx}:@emph{xx}:@emph{xx}:@emph{xx}
|
|
@end example
|
|
|
|
The @emph{n} here is the number of the ethertap device you want to
|
|
use. It should be the same @emph{n} as the one you use for
|
|
@file{/dev/tap@emph{n}}. The @emph{xx}s are four hexadecimal numbers
|
|
(0--ff). With previous versions of tincd, it didn't matter what they
|
|
were. But newer kernels require properly set up ethernet addresses.
|
|
In fact, the old behavior was wrong. It is required that the @emph{xx}s
|
|
match MyOwnVPNIP.
|
|
|
|
@example
|
|
ifconfig tap@emph{n} @emph{IP} netmask @emph{mask}
|
|
@end example
|
|
|
|
This will activate the device with an IP address @emph{IP} with network
|
|
mask @emph{mask}.
|
|
|
|
|
|
|
|
@c ==================================================================
|
|
@node Installing tinc, Configuring tinc, Configuring a Linux system, Top
|
|
@chapter Installing tinc
|
|
|
|
First download it. This is the
|
|
@uref{http://tinc.nl.linux.org/download.html, download
|
|
page}, which has the checksums of these files listed; you may wish to
|
|
check these with md5sum before continuing.
|
|
|
|
tinc comes in a handy 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.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuring tinc, Running tinc, Installing tinc, Top
|
|
@chapter Configuring tinc
|
|
|
|
@menu
|
|
* Multiple networks::
|
|
* How connections work::
|
|
* Configuration file::
|
|
* Example::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Multiple networks, How connections work, Configuring tinc, Configuring tinc
|
|
@section Multiple networks
|
|
|
|
@c from the manpage
|
|
|
|
It is perfectly OK for you to run more than one tinc daemon.
|
|
However, in its default form, you will soon notice that you can't use
|
|
two different configuration files without the -c option.
|
|
|
|
We have thought of another way of dealing with this: network names. This
|
|
means that you call tincd with the -n argument, which will assign a name
|
|
to this daemon.
|
|
|
|
The effect of this is that the daemon will set its configuration
|
|
``root'' to /etc/tinc/nn/, where nn is your argument to the -n
|
|
option. You'll notice that it appears in syslog as ``tincd.nn''.
|
|
|
|
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/nn/; the configuration file should be /etc/tinc/tincd.conf,
|
|
and the passphrases are now expected to be in /etc/tinc/passphrases/.
|
|
|
|
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 file, Multiple networks, Configuring tinc
|
|
@section How connections work
|
|
|
|
Before going on, first a bit on how tinc sees connections.
|
|
|
|
When tinc starts up, it reads in the configuration file and parses the
|
|
command-line options. If it sees a `ConnectTo' value in the file, it
|
|
will try to connect to it, on the given port. If this fails, tinc exits.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Configuration file, Example, How connections work, Configuring tinc
|
|
@section Configuration file
|
|
|
|
The actual configuration of the daemon is done in the file
|
|
@file{/etc/tinc/nn/tincd.conf}.
|
|
|
|
This 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.
|
|
|
|
@menu
|
|
* Variables::
|
|
@end menu
|
|
|
|
@c ==================================================================
|
|
@node Variables, , Configuration file, Configuration file
|
|
@subsection Variables
|
|
|
|
Here are all valid variables, listed in alphabetical order:
|
|
|
|
@c straight from the manpage
|
|
@table @asis
|
|
@item AllowConnect = (yes|no)
|
|
If set to yes, anyone may try to connect to you. If you set this to no,
|
|
no incoming connections will be accepted. This does not affect the
|
|
outgoing connections.
|
|
|
|
@item ConnectPort = port
|
|
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) or hexadecimal (prefixed with 0x). port is the port
|
|
number for both the UDP and the TCP (meta) connections.
|
|
|
|
@item ConnectTo = (IP address|hostname)
|
|
Specifies which host to connect to on startup. If the ConnectPort
|
|
variable is omitted, then tinc will try to connect to port 655.
|
|
|
|
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. Only the initiator of a
|
|
tinc VPN should need this.
|
|
|
|
@item ListenPort = port
|
|
Listen on local port port. The computer connecting to this daemon should
|
|
use this number as the argument for his ConnectPort. Again, the
|
|
default is 655.
|
|
|
|
@item MyOwnVPNIP = local address[/maskbits]
|
|
The local address is the number that the daemon will propagate to
|
|
other daemons on the network when it is identifying itself. Hence this
|
|
will be the file name of the passphrase file that the other end expects
|
|
to find the passphrase in.
|
|
|
|
The local address is the IP address of the tap device, not the real IP
|
|
address of the host running tincd. Due to changes in recent kernels, it
|
|
is also necessary that you make the ethernet (also known as MAC) address
|
|
equal to the IP address (see the example).
|
|
|
|
maskbits is the number of bits set to 1 in the netmask part.
|
|
|
|
@item MyVirtualIP = local address[/maskbits]
|
|
This is an alias for MyOwnVPNIP.
|
|
|
|
@item Passphrases = directory
|
|
The directory where tinc will look for passphrases when someone tries to
|
|
connect. Please see the manpage for genauth(8) for more information
|
|
about passphrases as used by tinc.
|
|
|
|
@item PingTimeout = number
|
|
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.
|
|
|
|
@item TapDevice = device
|
|
The ethertap device to use. Note that you can only use one device per
|
|
daemon. The info pages of the tinc package contain more information
|
|
about configuring an ethertap device for Linux.
|
|
|
|
@end table
|
|
|
|
|
|
@c ==================================================================
|
|
@node Example, , Configuration file, Configuring tinc
|
|
@section Example
|
|
|
|
Imagine the following situation. An A-based 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 LAN of the office. This could be the same as the interface
|
|
that leads to the internet.
|
|
|
|
@subsubheading For A
|
|
|
|
@emph{A} would be configured like this:
|
|
|
|
@example
|
|
ifconfig tap0 hw ether fe:fd:0a:01:36:01
|
|
ifconfig tap0 10.1.54.1 netmask 255.0.0.0
|
|
ifconfig eth0 10.1.54.1 netmask 255.255.0.0 broadcast 10.1.255.255
|
|
@end example
|
|
|
|
and in /etc/tinc/tincd.conf:
|
|
|
|
@example
|
|
TapDevice = /dev/tap0
|
|
MyVirtualIP = 10.1.54.1/16
|
|
@end example
|
|
|
|
@subsubheading For B
|
|
|
|
@example
|
|
ifconfig tap0 hw ether fe:fd:0a:02:01:0c
|
|
ifconfig tap0 10.2.1.12 netmask 255.0.0.0
|
|
ifconfig eth0 10.2.43.8 netmask 255.255.0.0 broadcast 10.2.255.255
|
|
@end example
|
|
|
|
and in /etc/tinc/tincd.conf:
|
|
|
|
@example
|
|
TapDevice = /dev/tap0
|
|
MyVirtualIP = 10.2.1.12/16
|
|
ConnectTo = 1.2.3.4
|
|
AllowConnect = no
|
|
@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.
|
|
|
|
@subsubheading For C
|
|
|
|
@example
|
|
ifconfig tap0 hw ether fe:fd:0a:03:45:fe
|
|
ifconfig tap0 10.3.69.254 netmask 255.0.0.0
|
|
ifconfig eth0 10.3.69.254 netmask 255.255.0.0 broadcast 10.3.255.255
|
|
@end example
|
|
|
|
and in /etc/tinc/A/tincd.conf:
|
|
|
|
@example
|
|
MyVirtualIP = 10.3.69.254/16
|
|
ConnectTo = 1.2.3.4
|
|
ListenPort = 2000
|
|
@end example
|
|
|
|
C already has another daemon that runs on port 655, so they have to
|
|
reserve another port for tinc. They also use the netname to distinguish
|
|
between the two. tinc is started with `tincd -n A'.
|
|
|
|
@subsubheading For D
|
|
|
|
@example
|
|
ifconfig tap0 hw ether fe:fd:0a:04:03:20
|
|
ifconfig tap0 10.4.3.32 netmask 255.0.0.0
|
|
ifconfig tap0 10.4.3.32 netmask 255.255.0.0 broadcast 10.4.255.255
|
|
@end example
|
|
|
|
and in /etc/tinc/tincd.conf:
|
|
|
|
@example
|
|
MyVirtualIP = 10.4.3.32/16
|
|
ConnectTo = 3.4.5.6
|
|
ConnectPort = 2000
|
|
AllowConnect = no
|
|
@end example
|
|
|
|
D will be connecting to C, which has a tincd running for this network on
|
|
port 2000. Hence they need to put in a ConnectPort.
|
|
|
|
@subsubheading Authentication
|
|
|
|
A, B, C and D all generate a passphrase with genauth 2048, the output is
|
|
stored in /etc/tinc/passphrases/local, except for C, where it should be
|
|
/etc/tinc/A/passphrases/local.
|
|
|
|
A stores a copy of B's passphrase in /etc/tinc/passphrases/10.2.0.0
|
|
|
|
A stores a copy of C's passphrase in /etc/tinc/passphrases/10.3.0.0
|
|
|
|
B stores a copy of A's passphrase in /etc/tinc/passphrases/10.1.0.0
|
|
|
|
C stores a copy of A's passphrase in /etc/tinc/A/passphrases/10.1.0.0
|
|
|
|
C stores a copy of D's passphrase in /etc/tinc/A/passphrases/10.4.0.0
|
|
|
|
D stores a copy of C's passphrase in /etc/tinc/passphrases/10.3.0.0
|
|
|
|
@subsubheading Starting
|
|
|
|
A has to start their tincd first. Then come B and C, where C has to
|
|
provide the option `-n A', because they have more than one tinc
|
|
network. Finally, D's tincd is started.
|
|
|
|
|
|
|
|
@c ==================================================================
|
|
@node Running tinc, Technical information, Configuring tinc, Top
|
|
@chapter Running tinc
|
|
|
|
Running tinc isn't just as easy as typing `tincd' and hoping everything
|
|
will just work out the way you wanted. Instead, the use of tinc is a
|
|
project that involves trust relations and more than one computer.
|
|
|
|
@menu
|
|
* Managing keys::
|
|
* Runtime options::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Managing keys, Runtime options, Running tinc, Running tinc
|
|
@section Managing keys
|
|
|
|
Before attempting to start tinc, you have to create passphrases. When
|
|
tinc tries to make a connection, it exchanges some sensitive
|
|
data. Before doing so, it likes to know if the other end is
|
|
trustworthy.
|
|
|
|
To do this, both ends must have some knowledge about the other. In the
|
|
case of tinc this is the authentication passphrase.
|
|
|
|
This passphrase is a number, which is chosen at random. This number is
|
|
then sent to the other computers which want to talk to us directly. To
|
|
avoid breaking security, this should be done over a known secure channel
|
|
(such as ssh or similar).
|
|
|
|
All passphrases are stored in the passphrases directory, which is
|
|
normally /etc/tinc/nn/passphrases/, but it may be changed using the
|
|
`Passphrases' option in the config file.
|
|
|
|
To generate a passphrase, run `genauth'. genauth takes one argument,
|
|
which is the length of the passphrase in bits. The length of the
|
|
passphrase should be in the range 1024--2048 for a key length of 128
|
|
bits. genauth creates a random number of the specified length, and puts
|
|
it to stdout.
|
|
|
|
Every computer that wants to participate in the VPN should do this, and
|
|
store the output in the passphrases directory, in the file @file{local}.
|
|
|
|
When every computer has his own local key, it should copy it to the
|
|
computer that it wants to talk to directly. (i.e. the one it connects to
|
|
during startup.) This should be done via a secure channel, because it is
|
|
sensitive information. If this is not done securely, someone might break
|
|
in on you later on.
|
|
|
|
Those non-local passphrase files must have the name of the VPN IP
|
|
address that they will advertise to you. For instance, if a computer
|
|
tells us it likes to be 10.1.1.3 with netmask 255.255.0.0, the file
|
|
should still be called 10.1.1.3, and not 10.1.0.0.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Runtime options, , Managing keys, Running tinc
|
|
@section Runtime options
|
|
|
|
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.
|
|
|
|
@c from the manpage
|
|
@table @asis
|
|
@item -c, --config=FILE
|
|
Read configuration options from FILE. The default is
|
|
@file{/etc/tinc/nn/tincd.conf}.
|
|
|
|
@item -d
|
|
Increase debug level. The higher it gets, the more gets
|
|
logged. Everything goes via syslog.
|
|
|
|
0 is the default, only some basic information connection attempts get
|
|
logged. Setting it to 1 will log a bit more, still not very
|
|
disturbing. With two -d's tincd will log protocol information, which can
|
|
get pretty noisy. Three or more -d's will output every single packet
|
|
that goes out or comes in, which probably generates more data than the
|
|
packets themselves.
|
|
|
|
@item -k, --kill
|
|
Attempt to kill a running tincd and exit. A TERM signal (15) gets sent
|
|
to the daemon that his its PID in /var/run/tincd.nn.pid.
|
|
|
|
Because it kills only one tincd, you should use -n here if you use it
|
|
normally.
|
|
|
|
@item -n, --net=NETNAME
|
|
Connect to net NETNAME. @xref{Multiple networks}.
|
|
|
|
@item -t, --timeout=TIMEOUT
|
|
Seconds to wait before giving a timeout. Should not be set too low,
|
|
because every time tincd senses a timeout, it disconnects and reconnects
|
|
again, which will cause unnecessary network traffic and log messages.
|
|
|
|
@item --help
|
|
Display a short reminder of these runtime options and terminate.
|
|
|
|
@item --version
|
|
Output version information and exit.
|
|
|
|
@end table
|
|
|
|
|
|
@c ==================================================================
|
|
@node Technical information, About us, Running tinc, Top
|
|
@chapter Technical information
|
|
|
|
|
|
@c ==================================================================
|
|
@menu
|
|
* The Connection::
|
|
* Security::
|
|
* The Protocol::
|
|
@end menu
|
|
|
|
@node The Connection, Security, Technical information, Technical information
|
|
@section The basic philosophy of the way tinc works
|
|
@cindex Connection
|
|
|
|
tinc is a daemon that takes VPN data and transmit that to another host
|
|
computer over the existing Internet infrastructure.
|
|
|
|
@menu
|
|
* Protocol Preview::
|
|
* The Meta-connection::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Protocol Preview, The Meta-connection, The Connection, The Connection
|
|
@subsection A preview of the way the tinc works
|
|
|
|
@cindex ethertap
|
|
@cindex frame type
|
|
The data itself is read from a character device file, the so-called
|
|
@emph{ethertap} 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.
|
|
|
|
So when tinc reads an ethernet frame from the device, it determines its
|
|
type. Right now, tinc can only handle Internet Protocol version 4 (IPv4)
|
|
frames. Plans to support other protocols are being made. When tinc knows
|
|
which type of frame it has read, it can also read the source and
|
|
destination address from it.
|
|
|
|
Now it is time that the frame gets encrypted. Currently the only
|
|
encryption algorithm available is blowfish.
|
|
|
|
@cindex encapsulating
|
|
When the encryption is ready, 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 does a decrypt on the contents of the UDP datagram,
|
|
and it writes the decrypted information to its own ethertap device.
|
|
|
|
|
|
@c ==================================================================
|
|
@node The Meta-connection, , Protocol Preview, 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 encryption information to somebody.
|
|
|
|
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, an how he 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.''
|
|
|
|
|
|
@c ==================================================================
|
|
@node Security, The Protocol, The Connection, 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 organization 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.
|
|
|
|
This chapter is a mixture of ideas, reasoning and explanation, please
|
|
don't take it too serious.
|
|
|
|
@menu
|
|
* Key Management::
|
|
* Authentication::
|
|
* Protection::
|
|
@end menu
|
|
|
|
|
|
@c ==================================================================
|
|
@node Key Management, Authentication, Security, Security
|
|
@subsection Key Management
|
|
@c FIXME: recheck
|
|
|
|
@cindex Diffie-Hellman
|
|
You can't just send a private encryption key to your peer, because
|
|
somebody else might already be listening to you. So you'll have to
|
|
negotiate over a shared but secret key. One way to do this is by using
|
|
the ``Diffie-Hellman key exchange'' protocol
|
|
(@uref{http://www.rsa.com/rsalabs/faq/html/3-6-1.html}). The idea is as
|
|
follows.
|
|
|
|
You have two participants A and B that want to agree over a shared
|
|
secret encryption key. Both parties have some large prime number p and a
|
|
generator g. These numbers may be known to the outside world, and hence
|
|
may be included in the source distribution.
|
|
|
|
@cindex secret key
|
|
Both parties then generate a secret key. A generates a, and computes g^a
|
|
mod p. This is then sent to B; while B computes g^b mod p, and transmits
|
|
this to A, b being generated by B. Both a and b must be smaller than
|
|
p-1.
|
|
|
|
These private keys are generated upon startup, and they are not changed
|
|
while the connection exists. A possible feature in the future is to
|
|
dynamically change the keys, every hour for example.
|
|
|
|
Both parties then calculate g^ab mod p = k. k is the new, shared, but
|
|
still secret key.
|
|
|
|
To obtain a key k of a sufficient length (128 bits in our vpnd), p
|
|
should be 2^129-1 or more.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Authentication, Protection, Key Management, Security
|
|
@subsection Authentication
|
|
@c FIXME: recheck
|
|
|
|
@cindex man-in-the-middle attack
|
|
Because the Diffie-Hellman protocol is in itself vulnerable to the
|
|
``man-in-the-middle attack,'' we should introduce an authentication
|
|
system.
|
|
|
|
We will let A transmit a passphrase that is also known to B encrypted
|
|
with g^a, before A sends this to B. This way, B can check whether A is
|
|
really A or just someone else.
|
|
|
|
@cindex passphrase
|
|
This passphrase should be 2304 bits for a symmetric encryption
|
|
system. But since an asymmetric system is more secure, we could do with
|
|
2048 bits. This only holds if the passphrase is very random.
|
|
|
|
These passphrases could be stored in a file that is non-readable by
|
|
anyone else but root; e.g. @file{/etc/vpn/passphrases}.
|
|
|
|
The only thing that needs to be taken care of is how A announces its
|
|
passphrase to B.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Protection, , Authentication, Security
|
|
@subsection Protecting your data
|
|
|
|
Now we have securely hidden our data. But a malicious cracker may still
|
|
bother you by randomly altering the encrypted data he intercepts.
|
|
|
|
|
|
@c ==================================================================
|
|
@node The Protocol, , Security, Technical information
|
|
@section Detailed protocol specifications
|
|
|
|
|
|
|
|
@menu
|
|
* Data protocol::
|
|
* Meta protocol::
|
|
@end menu
|
|
|
|
@c ==================================================================
|
|
@node Data protocol, Meta protocol, The Protocol, The Protocol
|
|
@subsection The data protocol
|
|
|
|
The data that is sent through the UDP connection is formatted as follows:
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0-1 | The length of this packet, including all leading fields
|
|
2-5 | The destination IP address
|
|
6-... | The encrypted data
|
|
|
|
@end example
|
|
|
|
The method that was used to encrypt the data should be made known via
|
|
the meta-protocol, during early identification stages.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Meta protocol, , Data protocol, The Protocol
|
|
@subsection The Meta protocol
|
|
|
|
This protocol consists of separate packets of information, that are
|
|
generally formatted thusly:
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0 | The request ID
|
|
1-... | (Optional: arguments)
|
|
|
|
@end example
|
|
|
|
What follows is a listing of possible request IDs.
|
|
|
|
@table @samp
|
|
@item ACK
|
|
Acknowledge. This generally means that the authentication has been
|
|
accepted by the remote computer. Takes no arguments.
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0 | `1'
|
|
|
|
@end example
|
|
|
|
@item AUTH_S_INIT
|
|
@itemx AUTH_C_INIT
|
|
Obsolete. Use @samp{BASIC_INFO}.
|
|
|
|
@item AUTH_S_SPP
|
|
@itemx AUTH_C_SPP
|
|
Obsolete. Use @samp{PASSPHRASE}.
|
|
|
|
@item AUTH_S_SKEY
|
|
@itemx AUTH_C_SKEY
|
|
Obsolete. Use @samp{PUBLIC_KEY}, @samp{REQ_KEY} and @samp{ANS_KEY}.
|
|
|
|
@item AUTH_S_SACK
|
|
@itemx AUTH_C_RACK
|
|
Obsolete. Use @samp{ACK}.
|
|
|
|
@item TERMREQ
|
|
A request to terminate this connection, for whatever reason.
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0 | `30'
|
|
1-4 | The VPN IP address of the host that has exited
|
|
|
|
@end example
|
|
|
|
|
|
@item PINGTIMEOUT
|
|
Terminate connection, but the reason must be a ping timeout.
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0 | `31'
|
|
1-4 | The VPN IP address of the host that has exited
|
|
|
|
@end example
|
|
|
|
|
|
@item PING
|
|
Send probe to the other end, if he hasn't returned a @samp{PONG} within
|
|
10 seconds, the connection is considered to be dead and will be
|
|
terminated, we should try to notify the other by sending a
|
|
@samp{PINGTIMEOUT} packet.
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0 | `40'
|
|
|
|
@end example
|
|
|
|
|
|
@item PONG
|
|
See explanation for @samp{PING}
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0 | `41'
|
|
|
|
@end example
|
|
|
|
|
|
@item ADD_HOST
|
|
Send an @samp{ADD_HOST} packet if you want to propagate all your current
|
|
connections to a new computer on a network. If we get this request, we
|
|
must forward it to everyone that hasn't got it yet.
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0 | `60'
|
|
1-4 | The real IP address of the new host
|
|
5-8 | The VPN IP address of the new host
|
|
9-12 | The VPN netmask
|
|
13-14 | The port number that the new host listens on
|
|
|
|
@end example
|
|
|
|
|
|
@item BASIC_INFO
|
|
This packet will contain all necessary basic information about
|
|
ourselves, such as the port we listen on and our desired VPN IP address.
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0 | `61'
|
|
1 | The protocol version.
|
|
| This chapter describes version 4.
|
|
2-3 | The port number that the new host listens on
|
|
4-7 | The VPN IP address of the new host
|
|
8-11 | The VPN netmask
|
|
|
|
@end example
|
|
|
|
|
|
@item PASSPHRASE
|
|
Send an encrypted passphrase. Should be encrypted with our
|
|
@strong{public} key, and it must reach us before a @samp{PUBLIC_KEY}
|
|
request.
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0 | `62'
|
|
1-2 | The length of the encrypted passphrase
|
|
3-... | The encrypted passphrase
|
|
|
|
@end example
|
|
|
|
|
|
@item PUBLIC_KEY
|
|
This is only used during authentication of a new connection, later on we
|
|
may use @samp{REQ_KEY} and @samp{ANS_KEY}.
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0 | `63'
|
|
1-2 | The length of the key
|
|
3-... | The public key, given in base-36
|
|
|
|
@end example
|
|
|
|
|
|
@item HOLD
|
|
@itemx RESUME
|
|
Unused.
|
|
|
|
@item CALCULATE
|
|
@itemx CALC_RES
|
|
@itemx ALMOST_KEY
|
|
Never been in use.
|
|
|
|
@item REQ_KEY
|
|
Request a public key from someone and return it to the sender of this
|
|
request using a @samp{ANS_KEY} packet. If we get such request, we must
|
|
forward it to the connection that leads to the destination.
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0 | `160'
|
|
1-4 | The source VPN IP address
|
|
5-8 | The destination VPN IP address
|
|
9-14 | `0'
|
|
|
|
@end example
|
|
|
|
|
|
@item ANS_KEY
|
|
Answer to a @samp{REQ_KEY} request, forward it to the destination if it
|
|
is not meant for us.
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0 | `161'
|
|
1-4 | The source VPN IP address
|
|
5-8 | The destination VPN IP address
|
|
9-12 | The expiration date/time in seconds
|
|
13-14 | The key length
|
|
15-... | The public key in base-36
|
|
|
|
@end example
|
|
|
|
|
|
@item KEY_CHANGED
|
|
The source computer wants to tell that it has regenerated its private
|
|
and public keys, so anything going there must be encrypted with a new
|
|
shared key.
|
|
|
|
@example
|
|
|
|
bytes | Contents
|
|
----------------------
|
|
0 | `162'
|
|
1-4 | The source VPN IP address
|
|
|
|
@end example
|
|
|
|
|
|
@end table
|
|
|
|
|
|
@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
|
|
|
|
tinc's main page is at @url{http://tinc.nl.linux.org/},
|
|
this server is located in the Netherlands.
|
|
|
|
We have an IRC channel on the Open Projects IRC network. Connect to
|
|
@uref{http://openprojects.nu/services/irc.html, irc.openprojects.net},
|
|
and join channel #tinc.
|
|
|
|
|
|
@c ==================================================================
|
|
@node Authors, , Contact Information, About us
|
|
@section Authors
|
|
|
|
@table @asis
|
|
@item Ivo Timmermans (zarq) (@email{itimmermans@@bigfoot.com})
|
|
Main coder/hacker and maintainer of the package.
|
|
|
|
@item Guus Sliepen (guus)
|
|
Originator of it all, co-author.
|
|
|
|
@item Wessel Dankers (Ubiq)
|
|
General obfuscater of the code.
|
|
|
|
@end table
|
|
|
|
Thank you's to: Dekan, Emphyrio, vDong
|
|
|
|
Greetings to: braque, Fluor, giggles, macro, smoke, tribbel
|
|
|
|
|
|
@c ==================================================================
|
|
@node Concept Index, , About us, Top
|
|
@c node-name, next, previous, up
|
|
@unnumbered Concept Index
|
|
|
|
@c ==================================================================
|
|
@printindex cp
|
|
|
|
|
|
@c ==================================================================
|
|
@contents
|
|
@bye
|
|
|