j3d1/tinc
1
0
Fork 0
Code Issues 1 Pull requests Releases Wiki Activity

Synchronise HEAD with CABAL branch.

Browse source
This commit is contained in:
Guus Sliepen 2003-08-24 20:38:31 +00:00
parent efa5148bc7
commit 013a2e159e
173 changed files with 12252 additions and 28046 deletions
Download patch file Download diff file Expand all files Collapse all files

365
doc/CONNECTIVITY
View file

@ -1,7 +1,7 @@
This document describes how nodes in a VPN find and connect to eachother and
maintain a stable network.
Copyright 2001-2002 Guus Sliepen <guus@sliepen.warande.net>
Copyright 2001-2002 Guus Sliepen <guus@sliepen.eu.org>
Permission is granted to make and distribute verbatim copies of
this documentation provided the copyright notice and this
@ -12,343 +12,34 @@ maintain a stable network.
provided that the entire resulting derived work is distributed
under the terms of a permission notice identical to this one.
$Id: CONNECTIVITY,v 1.2 2002/04/12 08:25:01 guus Exp $
$Id: CONNECTIVITY,v 1.3 2003/08/24 20:38:18 guus Exp $
1. Problem
1. Synchronisation
==================
Each tinc daemon has zero or more connections to other tinc daemons. It will
try to keep its own information synchronised with the other tinc daemons. If
one of its peers sends information, the tinc daemon will check if it is new
information. If so, it will update its own information and forward the new
information to all the other peers.
This scheme will make sure that after a short amount of time all tinc daemons
share the same information. It will also almost completely prevent information
from looping, because "new" information that is already known is ignored and
not forwarded any further. However, since information can also be deleted
there's the possibility of a looping sequence of add/delete messages. This is
resolved by additionaly adding a unique identifier to each broadcasted message.
Messages are dropped if the same message with that identifier has already been
seen.
2. Routing
==========
We have a set of nodes (A, B, C, ...) that are part of the same VPN. They need
to connect to eachother and form a single graph that satisfies the tree
property.
Every node tells its peers to which other peers it is connected. This way
every node will eventually know every connection every node has on the VPN.
Each node will use graph algorithms to determine if other nodes are reachable or not and
what the best route is to other nodes.
There is the possibility that loops are formed, the offending connections must
be eliminated.
Suppose we start with two smaller graphs that want to form a single larger
graph. Both graphs consist of three nodes:
A-----B-----C
D-----E-----F
It is very well possible that A wants to connect to D, and F wants to connect
to C, both at the same time. The following loop will occur:
A-----B-----C
| ^
| |
v |
D-----E-----F
The situation described here is totally symmetric, there is no preference to
one connection over the other. The problem of resolving the loop, maintaining
consistency and stability is therefore not a trivial one.
What happens when A---D and C---F are connected to eachother? They exchange
lists of known hosts. A knows of B and C, and D knows of E and F. The protocol
defines ADD_HOST messages, from now on we will say that "node X sends and
ADD_HOST(Y) to Z".
There are two possible scenarios: either both A---D and C---F finish
authentication at the same time, or A---D finishes first, so that ADD_HOST
messages will reach C and F before they finish authentication.
1.1 A---D finishes first
------------------------
After A---D authentication finishes the following actions are taken:
1 A sends ADD_HOST(B) to D
A sends ADD_HOST(C) to D
D sends ADD_HOST(E) to A
D sends ADD_HOST(F) to A
2 A sends ADD_HOST(D) to B
A receives ADD_HOST(E) from D:
A sends ADD_HOST(E) to B
A receives ADD_HOST(F) from D:
A sends ADD_HOST(F) to B
D sends ADD_HOST(A) to E
D receives ADD_HOST(B) from A:
D sends ADD_HOST(B) to E
D receives ADD_HOST(C) from A:
D sends ADD_HOST(C) to E
3 B receives ADD_HOST(D) from A,
B sends ADD_HOST(D) to C
B receives ADD_HOST(E) from A:
B sends ADD_HOST(E) to C
B receives ADD_HOST(F) from A:
B sends ADD_HOST(F) to C
E receives ADD_HOST(A) from D:
E sends ADD_HOST(A) to F
E receives ADD_HOST(B) from D:
E sends ADD_HOST(B) to F
E receives ADD_HOST(C) from D:
E sends ADD_HOST(C) to F
4 C receives ADD_HOST(D) from B.
C receives ADD_HOST(E) from B.
C receives ADD_HOST(F) from B.
F receives ADD_HOST(A) from E.
F receives ADD_HOST(B) from E.
F receives ADD_HOST(C) from E.
Then C---F authentication finishes, the following actions are taken:
1 C notes that F is already known:
Connection is closed.
F notes that C is already known:
Connection is closed.
1.2 Both A---D and C---F finish at the same time.
-------------------------------------------------
1 A sends ADD_HOST(B) to D
A sends ADD_HOST(C) to D
D sends ADD_HOST(E) to A
D sends ADD_HOST(F) to A
C sends ADD_HOST(A) to F
C sends ADD_HOST(B) to F
F sends ADD_HOST(D) to C
F sends ADD_HOST(E) to C
2 A sends ADD_HOST(D) to B
A receives ADD_HOST(E) from D:
A sends ADD_HOST(E) to B
A receives ADD_HOST(F) from D:
A sends ADD_HOST(F) to B
D sends ADD_HOST(A) to E
D receives ADD_HOST(B) from A:
D sends ADD_HOST(B) to E
D receives ADD_HOST(C) from A:
D sends ADD_HOST(C) to E
C sends ADD_HOST(F) to B
C receives ADD_HOST(D) from F:
A sends ADD_HOST(D) to B
C receives ADD_HOST(E) from F:
A sends ADD_HOST(E) to B
F sends ADD_HOSTS(C) to E
F receives ADD_HOST(A) from C:
D sends ADD_HOST(A) to E
F receives ADD_HOST(B) from C:
D sends ADD_HOST(B) to E
3 B receives ADD_HOST(D) from A,
B sends ADD_HOST(D) to C
B receives ADD_HOST(E) from A:
B sends ADD_HOST(E) to C
B receives ADD_HOST(F) from A:
B sends ADD_HOST(F) to C
E receives ADD_HOST(A) from D:
E sends ADD_HOST(A) to F
E receives ADD_HOST(B) from D:
E sends ADD_HOST(B) to F
E receives ADD_HOST(C) from D:
E sends ADD_HOST(C) to F
B receives ADD_HOST(F) from C, and notes that is is already known:
<insert solution here>
B receives ADD_HOST(D) from C, and notes that is is already known:
<insert solution here>
B receives ADD_HOST(E) from C, and notes that is is already known:
<insert solution here>
E receives ADD_HOST(C) from F, and notes that is is already known:
<insert solution here>
E receives ADD_HOST(A) from F, and notes that is is already known:
<insert solution here>
E receives ADD_HOST(B) from F, and notes that is is already known:
<insert solution here>
4 A receives ADD_HOST(D) from B, and notes that it is already known:
<insert solution here>
A receives ADD_HOST(E) from B, and notes that it is already known:
<insert solution here>
A receives ADD_HOST(F) from B, and notes that it is already known:
<insert solution here>
F receives ADD_HOST(A) from E, and notes that it is already known:
<insert solution here>
F receives ADD_HOST(B) from E, and notes that it is already known:
<insert solution here>
F receives ADD_HOST(B) from E, and notes that it is already known:
<insert solution here>
...
1.2.1 Augmenting ADD_HOST
-------------------------
A solution would be to augment ADD_HOST with an extra parameter, the nexthop of
the added host:
3 B receives ADD_HOST(D,A) from A,
B sends ADD_HOST(D,A) to C
B receives ADD_HOST(E,D) from A:
B sends ADD_HOST(E,D) to C
B receives ADD_HOST(F,E) from A:
B sends ADD_HOST(F,E) to C
E receives ADD_HOST(A,D) from D:
E sends ADD_HOST(A,D) to F
E receives ADD_HOST(B,A) from D:
E sends ADD_HOST(B,A) to F
E receives ADD_HOST(C,B) from D:
E sends ADD_HOST(C,B) to F
B receives ADD_HOST(F,C) from C, and notes that F is already known:
<insert solution here>
B receives ADD_HOST(D,E) from C, and notes that D is already known:
<insert solution here>
B receives ADD_HOST(E,F) from C, and notes that E is already known:
<insert solution here>
E receives ADD_HOST(C,F) from F, and notes that C is already known:
<insert solution here>
E receives ADD_HOST(A,B) from F, and notes that A is already known:
<insert solution here>
E receives ADD_HOST(B,C) from F, and notes that B is already known:
<insert solution here>
So, B and E have to make a choice. Which ADD_HOST is going to win? Fortunately,
since the ADD_HOST messages are augmented, they have an extra piece of
information they can use to decide in a deterministic way which one is going to
win. For example, B got ADD_HOST(F,E) and ADD_HOST(F,C). Since "E" > "C", it
could let ADD_HOST(F,E) win.
B receives ADD_HOST(F,C) from C, and notes that F is already known:
since "C" < "E", B ignores ADD_HOST(F,E)
B sends ADD_HOST(F,C) to A
...
E receives ADD_HOST(C,F) from F, and notes that C is already known:
since "F" > "B", E removes the ADD_HOST(C,B) in favour of the new one
E sends ADD_HOST(C,F) to D
4 A receives ADD_HOST(F,E) from B, and notes that F is already known:
since "E" < "D", A ignores ADD_HOST(F,D).
...
D receives ADD_HOST(C,F) from E, and notes that C is already known:
since "F" > "B", D removes the ADD_HOST(C,B),
closes the connection with C, in favour of the new one.
Ok, time to forget this crap.
1.2.2
-----
The problem with the current ADD/DEL_HOST technique is that each host only
knows the general direction in which to send packets for the other hosts. It
really doesn't know much about the true topology of the network, only about
it's direct neighbours. With so little information each host cannot make a
certain decision which it knows for sure all the others will decide too.
Let's do something totally different. Instead of notifying every host of the
addition of a new host, which is represented by a vertex in a graph, lets send
out notifications of new connections, which are the edges in a graph. This is
rather cheap, since our graphs are (almost) spanning trees, there is
approximately one edge for each vertex in the graph, so we don't need to send
more messages. Furthermore, an edge is characterized by two vertices, so we
only send a fixed amount of extra information. The size/complexity of the
problem therefore does not increase much.
What is the advantage of notifying each vertex of new edges instead of new
vertices? Well, all the vertices now know exactly which connections are made
between each host. This was not known with the former schemes.
Ok back to our problem:
A-----B-----C
D-----E-----F
Edges are undirected, and are characterised by the vertices it connects, sorted
alphabetically, so the edges in the two graphs are:
(A,B), (B,C), (D,E) and (E,F).
So again we have that A wants to connect to D, and F wants to connect to C,
both at the same time. The following loop will occur:
A-----B-----C
| ^
| |
v |
D-----E-----F
Instead of sending ADD_HOSTs, lets assume the hosts send ADD_EDGEs. So, after
making the connections:
1 A sends ADD_EDGE(A,D) to B
A sends ADD_EDGE(A,B) to D
A sends ADD_EDGE(B,C) to D
D sends ADD_EDGE(A,D) to E
D sends ADD_EDGE(D,E) to A
D sends ADD_EDGE(E,F) to A
C sends ADD_EDGE(C,F) to B
C sends ADD_EDGE(A,B) to F
C sends ADD_EDGE(B,C) to F
F sends ADD_EDGE(C,F) to E
F sends ADD_EDGE(D,E) to C
F sends ADD_EDGE(E,F) to C
2 B receives ADD_EDGE(A,D) from A:
B sends ADD_EDGE(A,D) to C
B receives ADD_EDGE(D,E) from A:
B sends ADD_EDGE(D,E) to C
B receives ADD_EDGE(E,F) from A:
B sends ADD_EDGE(E,F) to C
...
B receives ADD_EDGE(C,F) from C, notes that both C and F are already known,
but that the edge (C,F) was not known, so a loop has been created:
<resolve loop here>
Ok, how to resolve the loop? Remeber, we want to do that in such a way that it
is consistent with the way all the other hosts resolve the loop. Here is the
things B does when it notices that a loop is going to be formed:
B performs a Breadth First Search from the first element of the list of all
known hosts sorted alfabetically, in this case A, and thereby finds a
spanning tree. (This might later be changed into a minimum spanning tree
alhorithm, but the key point here is that all hosts do this with exactly the
same starting parameters.) All known edges that are not in the spanning tree
are marked inactive.
An edge marked inactive does not mean anything, unless this edge is connected
to B itself. In that case, B will stop sending messages over that edge. B might
consider closing this edge, but this is not really needed. Keeping it means no
DEL_EDGE has to be sent for it, and if another edge is removed (which will
quite certainly split the graph if it's a spanning tree), this edge might be
reactivated, without the need of sending a new ADD_EDGE for it. On the other
hand, we mustn't keep to many inactive edges, because we want to keep the
number of known edges linear to the number of hosts (otherwise the size of the
problem will grow quadratically).
So, since B didn't deactivate one of it's own edges, it forwards the
ADD_EDGE(C,F) to A, which also does a BFS, and so on, until it reaches F. F of
course also does a BFS, notes that is is one of it's own edges. It deactivates
the edge (C,F), and consequently will not forward the ADD_EDGE(C,F) to C
anymore. In the mean time, C got messages from B which will make C do the same.
Ok, suppose a DEL_EDGE was sent, and it means an inactive edge has to be
reactivated. The vertices connected by that edge must exchange their entire
knowledge of edges again, because in the mean time other messages could have
been sent, which were not properly forwarded. Take this example:
X C-----D
| | |
| | |
v | |
A-----B- - -E
The edge (B,E) is inactive. X is trying to make a new connection with A. A
sends an ADD_EDGE(A,X) to B, which forwards it to C. At that time, the
connection between C and D goes down, so C sends a DEL_EDGE(C,D) to B, and D
sends a DEL_EDGE(C,D) to E. If we just allow (B,E) to be reactivated again
without anything else, then E and D will never have received the ADD_EDGE(A,X).
So, B and E have to exchange edges again, and propagate them to the hosts they
already know.
Because all nodes share the same information, using a deterministic algorithm
each node will calculate the same minimum spanning tree for the entire VPN.
The MST will be used to send broadcast VPN packets.

23
doc/GNUmakefile
View file

@ -1,23 +0,0 @@
# Having a separate GNUmakefile lets me use features of GNU make
# to generate the man pages.
# This makefile is used only if you run GNU Make.
# It is necessary if you want to build targets usually of interest
# only to the maintainer.
have-Makefile := $(shell test -f Makefile && echo yes)
# If the user runs GNU make but has not yet run ./configure,
# give them a diagnostic.
ifeq ($(have-Makefile),yes)
include Makefile
include $(srcdir)/Makefile.maint
else
all:
@echo There seems to be no Makefile in this directory.
@echo "You must run ./configure before running \`make'."
@exit 1
endif

175
doc/HOWTO
View file

@ -1,175 +0,0 @@
==============
The TINC HOWTO
==============
Wessel Dankers
wsl@nl.linux.org
Introduction
------------
Tinc is a system to create a virtual ethernet network on top of an existing
infrastructure. This infrastructure can be anything from modem lines to
gigabit ethernet networks, as long as they talk IP. Once you install and
configure tinc, your host will get an extra IP address, just like it would
when you stick an extra ethernet card into it. Using this IP address, it can
communicate with all hosts in its virtual network using strong encryption.
If you install Tinc on a router (and pick your numbers correctly) you can
have the router forward all packets. This way you can---instead of
connecting hosts---connect entire sites together! Now you need only one
outgoing network connection for both internet and intranet.
Architecture
------------
When a few Tinc daemons are running they will try to seek contact with
eachother. A daemon is all the time connected to a few other daemons,
but if traffic is required with a daemon it doesn't know yet, it will
instantly contact it and exchange keys. These so-called meta-connections
are made over TCP, using encryption of course.
When actual traffic has to be sent, a daemon checks his connection list to
see if the addressee is known (and makes contact with it if neccessary).
All packets are then sent using UDP to the other host, just like in a real
network. If a packet gets lost, the connection layer of Linux will resend
the packet, just like it would over a normal network.
Once in a while the daemons will renegotiate keys so that even if a cracker
breaks one, it'll be of limited use.
Getting Tinc
------------
Before you fetch the latest tarball, you might want to check if there's a
package for your Linux distribution. One of the main authors is a Debian
Developer, so you can expect the Debian packages to be very up to date.
The official website for Tinc can be found at http://tinc.nl.linux.org/.
There you can find Debian packages, RPM's and of course... the tarball!
Since we run Doohickey Linux Pro 1.0, for which no package exists (or
indeed the distribution itself) we shall compile the package ourselves.
Building
--------
The Tinc source adheres to so many standards it makes you head spin.
Even the debug messages have been localized! Amazing. Tinc also comes
with a configuration script. If you like to see what is there to
configure run ./configure --help | more. If you don't have time for such
nonsense:
./configure --sysconfdir=/etc
This will see if your system is nice enough to run tinc on, and will
create some Makefiles and other stuff which will together build tinc.
make
make install
The first will do the actual build, the second copies all files into place.
The kernel
----------
Next you will have to configure the kernel to support the tap device.
It is important that you run a recent kernel, but anything after 2.2.16
will do. You have to enable both the netlink device AND the ethertap
device (in that order). Enable them as modules!
Compile, install =) You don't even have to reboot.
Picking your numbers
--------------------
The first thing we should do is pick network numbers. Tinc has a very
peculiar taste for network numbers, which is caused by the way it routes
traffic. However, it turns out to be really handy if you want to use
your tinc host as a router for a site.
The numbers have to be in a range that is not yet in use in your existing,
real network! In this example we will use numbers from the 192.168.0/16
range. This is standard CIDR notation for all IP addresses from 192.168.0.0
to 192.168.255.255. The /16 means that the first 16 bits form the network
part.
It is common practice for Tinc networks to use private (RFC 1918) addresses.
This is not necessary, but it would be a waste to use official addresses
for a private network!
In the example we will connect three machines: f00f, fdiv and hlt. We will
give each an address, but not just that, also a slice of our address space
to play with.
Host Real address Tinc network
---------------------------------------------------
f00f 126.202.37.20 192.168.1.1/24
fdiv 126.202.37.81 192.168.2.1/24
hlt 103.22.1.218 192.168.3.1/24
It is very important that none of the Tinc netmasks overlap! Note how the
192.168.0/16 network covers the entire address space of the three hosts.
We will refer to the 192.168.0/16 network as the `umbrella' from now on.
As you can see we can fit 256 hosts into this umbrella this way, which is
also the practical maximum for tinc. Let's name our VPN 'fubar'.
The configuration file
----------------------
Let's create a configuration file for f00f. We have to put it in
/etc/tinc/fubar because that's how we named our VPN.
MyOwnVPNIP = 192.168.1.1/24
VpnMask = 255.255.0.0
ConnectTo = 126.202.37.81
ConnectTo = 103.22.1.218
TapDevice = /dev/tap0
The first two lines tell Tinc about the numbers we have chosen above.
Using the ConnectTo lines, the daemon will seek contact with the rest of
the umbrella. It's possible to configure any number of ConnectTo lines,
you can even omit them so that it just sits and waits until someone else
contacts it. Until someone does, the poor daemon won't be able to send
any data because it doesn't know where everybody is.
The TapDevice is where the tinc daemon will interface with the kernel.
The passphrases
---------------
We will have to generate keys for ourselves, and get a key from everybody
we want to ConnectTo. All of these go into a directory named
/etc/tinc/fubar/passphrases. PROTECT THIS DIRECTORY!
mkdir -m 700 /etc/tinc/fubar/passphrases
To generate our own key:
genauth 1024 >/etc/tinc/fubar/passphrases/local
You should then proceed to give this key to anyone who wants to ConnectTo
you. DO THIS IN A SECURE MANNER! Anyone who has this number can do icky
things to the umbrella network! Encrypt it using PGP, GPG or another
program using asymmetric keys. Read it over the phone (without anyone
listening of course). Send it by snailmail. Write the key down and bring
it to your partners personally!
If you get any keys from your partners, store them under their network
number. For example, the key we get from fdiv's network administrator
will be stored in /etc/tinc/fubar/passphrases/192.168.2.0 (note the 0).
Running the daemon
------------------
If you use a package manager to install Tinc, the startup scripts use a file
called /etc/tinc/nets.boot to see which umbrella's exist. It has a line
per VPN, and lines starting with a # are ignored. Ours will contain:
# Example VPN from the HOWTO
fubar
In Debian, /etc/init.d/tinc start will start the daemons.
If you use Doohickey Linux just like we do, you'll have to edit the systems
startup scripts by hand. It should contain something along the lines of:
insmod ethertap -s --name=tap0 unit=0
ifconfig tap0 hw ether fe:fd:c0:a8:01:01
ifconfig tap0 192.168.1.1 netmask 255.255.0.0 broadcast 192.168.255.255 -arp
There are two things to note here! First, the MAC address of the ethertap
device is very important. It must start with fe:fd, and end in the
hexadecimal representation of the VPN IP number.
Second, the netmask of the tap device is set to that of the umbrella!
--
$Id: HOWTO,v 1.6 2002/04/12 08:25:01 guus Exp $

23
doc/Makefile.am
View file

@ -1,20 +1,12 @@
## Process this file with automake to get Makefile.in
SUBDIRS = es
info_TEXINFOS = tinc.texi
dyn_MANS =
man_aux = $(dyn_MANS:.8=.x)
man_MANS = tincd.8 tinc.conf.5
man_MANS = tincd.8 tinc.conf.5 $(dyn_MANS)
EXTRA_DIST = tincinclude.texi.in tincd.8.in tinc.conf.5.in sample-config.tar.gz
PERL = @PERL@
HELP2MAN = help2man
MAINTAINERCLEANFILES = $(dyn_MANS)
EXTRA_DIST = $(man_MANS) $(HELP2MAN) $(man_aux) \
Makefile.maint GNUmakefile Makefile.summ sample-config.tar.gz
CLEANFILES = *.html
# Use `ginstall' in the definition of man_MANS to avoid
# confusion with the `install' target. The install rule transforms `ginstall'
@ -23,3 +15,12 @@ transform = s/ginstall/install/; @program_transform_name@
# For additional rules usually of interest only to the maintainer,
# see GNUmakefile and Makefile.maint.
sample-config.tar.gz: sample-config
GZIP=$(GZIP_ENV) $(AMTAR) chozf sample-config.tar.gz sample-config
texi2html: tinc.texi
texi2html -split=chapter tinc.texi
%.html: $(man_MANS)
w3mman2html $< > $@

38
doc/Makefile.maint
View file

@ -1,38 +0,0 @@
# This -*- Makefile -*- uses features of GNU make.
# It is included via GNUmakefile.
# The following one line summaries were extracted from the
# original man pages using this bit of sh code:
# for i in *.1; do echo "$i: "|tr -d '\012'; \
# grep -A1 SH.NAME $i|sed '/SH NAME/d;s/^[^ ][^ ]* .- //'; done
include Makefile.summ
HELP2MAN-run = $(PERL) -w -- $(srcdir)/$(HELP2MAN)
# Depend on configure.in to get version number changes.
$(dyn_MANS): $(top_srcdir)/configure.in
# Depend on the source file containing the --help text.
# Filter out irregular cases.
regular-men = $(filter-out $(irregular-men),$(dyn_MANS))
$(regular-men): %.8: $(top_srcdir)/src/%.c
executable = $(patsubst %/install,%/ginstall, ../src/$(basename $@))
$(dyn_MANS): %.8: %.x $(HELP2MAN)
@if test -f $(executable); then \
echo "Updating man page $@"; \
rm -f $@-t $@; \
$(HELP2MAN-run) \
--name="$($(basename $@)-summary)" \
--include=$(basename $@).x \
$(executable) > $@-t; \
chmod -w $@-t; \
mv $@-t $@; \
else \
echo "WARNING: The man page $@ cannot be updated yet."; \
echo " Retry once the corresponding executable is built."; \
fi
sample-config.tar.gz:
GZIP=$(GZIP_ENV) $(AMTAR) chozf sample-config.tar.gz sample-config

2
doc/Makefile.summ
View file

@ -1,2 +0,0 @@
# -*- makefile -*-
tincd-summary = tinc VPN daemon

4
doc/NETWORKING
View file

@ -1,7 +1,7 @@
This is the network infrastructure documentation for tinc, a Virtual Private
Network daemon.
Copyright 2001-2002 Guus Sliepen <guus@sliepen.warande.net>
Copyright 2001-2002 Guus Sliepen <guus@sliepen.eu.org>
Permission is granted to make and distribute verbatim copies of
this documentation provided the copyright notice and this
@ -12,7 +12,7 @@ Network daemon.
provided that the entire resulting derived work is distributed
under the terms of a permission notice identical to this one.
$Id: NETWORKING,v 1.2 2002/04/12 08:25:01 guus Exp $
$Id: NETWORKING,v 1.3 2003/08/24 20:38:18 guus Exp $
1. Packet flow
==============

86
doc/PROTOCOL
View file

@ -1,7 +1,7 @@
This is the protocol documentation for tinc, a Virtual Private Network daemon.
Copyright 2000-2002 Guus Sliepen <guus@sliepen.warande.net>,
2000-2002 Ivo Timmmermans <itimmermans@bigfoot.com>
Copyright 2000-2002 Guus Sliepen <guus@sliepen.eu.org>,
2000-2002 Ivo Timmmermans <ivo@o2w.nl>
Permission is granted to make and distribute verbatim copies of
this documentation provided the copyright notice and this
@ -12,7 +12,7 @@ This is the protocol documentation for tinc, a Virtual Private Network daemon.
provided that the entire resulting derived work is distributed
under the terms of a permission notice identical to this one.
$Id: PROTOCOL,v 1.2 2002/04/12 08:25:01 guus Exp $
$Id: PROTOCOL,v 1.3 2003/08/24 20:38:18 guus Exp $
1. Protocols used in tinc
@ -69,24 +69,62 @@ synchronised.
daemon message
--------------------------------------------------------------------------
origin ADD_EDGE node1 12.23.34.45 655 node2 21.32.43.54 655 222 0
| | | \___________________/ | +-> options
| | | | +----> weight
| | | +----------------> see below
| | +--> UDP port
| +----------> real address
+------------------> name of node on one side of the edge
origin ADD_EDGE node1 node2 21.32.43.54 655 222 0
| | | | | +-> options
| | | | +----> weight
| | | +--------> UDP port of node2
| | +----------------> real address of node2
| +-------------------------> name of destination node
+-------------------------------> name of source node
origin ADD_SUBNET node 192.168.1.0/24
| | +--> prefixlength
| +--------> IPv4 network address
| +--------> network address
+------------------> owner of this subnet
--------------------------------------------------------------------------
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.
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
------------------------------------------------------------------
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.
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
--------------------------------------------------------------------------
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
@ -97,33 +135,17 @@ act as a proxy and forward its copy back to the requestor.
daemon message
--------------------------------------------------------------------------
daemon REQ_KEY origin destination
| +--> name of the tinc daemon it wants the key from
+----------> name of the daemon that wants the key
daemon ANS_KEY origin destination 4ae0b0a82d6e0078 91 64 4
| | \______________/ | | +--> MAC length
| | | | +-----> digest algorithm
| | | +--------> cipher algorithm
| | +--> 128 bits key
| +--> name of the daemon that wants the key
+----------> name of the daemon that uses this key
daemon KEY_CHANGED origin
+--> daemon that has changed it's packet key
origin PING
dest. PONG
--------------------------------------------------------------------------
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.
daemon message
--------------------------------------------------------------------------
origin PING
dest. PONG
--------------------------------------------------------------------------
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 everything that is sent over the meta connection by
tinc.

22
doc/SECURITY2
View file

@ -1,6 +1,6 @@
This is the security documentation for tinc, a Virtual Private Network daemon.
Copyright 2001-2002 Guus Sliepen <guus@sliepen.warande.net>,
Copyright 2001-2002 Guus Sliepen <guus@sliepen.eu.org>,
2001-2002 Wessel Dankers <wsl@nl.linux.org>
Permission is granted to make and distribute verbatim copies of
@ -12,7 +12,7 @@ This is the security documentation for tinc, a Virtual Private Network daemon.
provided that the entire resulting derived work is distributed
under the terms of a permission notice identical to this one.
$Id: SECURITY2,v 1.2 2002/04/12 08:25:01 guus Exp $
$Id: SECURITY2,v 1.3 2003/08/24 20:38:18 guus Exp $
Proposed new authentication scheme
----------------------------------
@ -66,17 +66,15 @@ server CHAL_REPLY 928ffe
After the correct challenge replies are recieved, both ends have proved
their identity. Further information is exchanged.
client ACK 655 12.23.34.45 123 0
| | | +-> options
| | +----> estimated weight
| +------------> IP address of server as seen by client
+--------------------> UDP port of client
client ACK 655 123 0
| | +-> options
| +----> estimated weight
+--------> listening port of client
server ACK 655 21.32.43.54 321 0
| | | +-> options
| | +----> estimated weight
| +------------> IP address of client as seen by server
+--------------------> UDP port of server
server ACK 655 321 0
| | +-> options
| +----> estimated weight
+--------> listening port of server
--------------------------------------------------------------------------
This new scheme has several improvements, both in efficiency and security.

1
doc/es/.cvsignore
View file

@ -1 +0,0 @@
Makefile Makefile.in

3
doc/es/Makefile.am
View file

@ -1,3 +0,0 @@
## Process this file with automake to get Makefile.in
# Nothing to see here, go away!

375
doc/help2man
View file

@ -1,375 +0,0 @@
#!/usr/bin/perl -w
# Generate a short man page from --help and --version output.
# Copyright © 1997, 98 Free Software Foundation, Inc.
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software Foundation,
# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
# Written by Brendan O'Dea <bod@compusol.com.au>
use 5.004;
use strict;
use Getopt::Long;
use POSIX qw(strftime setlocale LC_TIME);
my $this_program = 'help2man';
my $this_version = '1.006';
my $version_info = <<EOT;
$this_program $this_version
Copyright (C) 1997, 98 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Written by Brendan O'Dea <bod\@compusol.com.au>
EOT
my $help_info = <<EOT;
`$this_program' generates a man page out of `--help' and `--version' output.
Usage: $this_program [OPTION]... EXECUTABLE
--name=STRING use `STRING' as the description for the NAME paragraph
--include=FILE include material from `FILE'
--opt-include=FILE include material from `FILE' if it exists
--output=FILE send output to `FILE'
--no-info suppress pointer to Texinfo manual
--help print this help, then exit
--version print $this_program program version number, then exit
EXECUTABLE should accept `--help' and `version' options.
EOT
my ($include, $opt_name, $opt_include, $opt_output, $opt_no_info);
# Parse options.
GetOptions (
'name=s' => \$opt_name,
'include=s' => \$include,
'opt-include=s' => \$opt_include,
'output=s' => \$opt_output,
'no-info' => \$opt_no_info,
help => sub { print $help_info; exit },
version => sub { print $version_info; exit },
) or die $help_info;
die $help_info unless @ARGV == 1;
my %include = ();
my @include = (); # to retain order
# Process include file (if given). Format is:
#
# [section name]
# verbatim text
if ($include or $opt_include)
{
if (open INC, $include || $opt_include)
{
my $sect;
while (<INC>)
{
if (/^\[([^]]+)\]/)
{
$sect = uc $1;
$sect =~ s/^\s+//;
$sect =~ s/\s+$//;
next;
}
# Silently ignore anything before the first
# section--allows for comments and revision info.
next unless $sect;
push @include, $sect unless $include{$sect};
$include{$sect} ||= '';
$include{$sect} .= $_;
}
close INC;
die "$this_program: no valid information found in `$include'\n"
unless %include;
# Compress trailing blank lines.
for (keys %include)
{
$include{$_} =~ s/\n+$//;
$include{$_} .= "\n" unless /^NAME$/;
}
}
else
{
die "$this_program: can't open `$include' ($!)\n" if $include;
}
}
# Turn off localisation of executable's ouput.
@ENV{qw(LANGUAGE LANG LC_ALL)} = ('C') x 3;
# Turn off localisation of date (for strftime)
setlocale LC_TIME, 'C';
# Grab help and version paragraphs from executable
my @help = split /\n\n+/, `$ARGV[0] --help 2>/dev/null`
or die "$this_program: can't get `--help' info from $ARGV[0]\n";
my @version = split /\n\n+/, `$ARGV[0] --version 2>/dev/null`
or die "$this_program: can't get `--version' info from $ARGV[0]\n";
my $date = strftime "%B %Y", localtime;
my $program = $ARGV[0]; $program =~ s!.*/!!;
my $package = $program;
my $version;
if ($opt_output)
{
unlink $opt_output
or die "$this_program: can't unlink $opt_output ($!)\n"
if -e $opt_output;
open STDOUT, ">$opt_output"
or die "$this_program: can't create $opt_output ($!)\n";
}
# The first line of the --version information is assumed to be in one
# of the following formats:
#
# <version>
# <program> <version>
# GNU <program> <version>
# <program> (GNU <package>) <version>
# <program> - GNU <package> <version>
#
# and seperated from any copyright/author details by a blank line.
$_ = shift @version;
if (/^(\S+)\s+\((GNU\s+[^)]+)\)\s+(.*)/ or
/^(\S+)\s+-\s*(GNU\s+\S+)\s+(.*)/)
{
$program = $1;
$package = $2;
$version = $3;
}
elsif (/^(GNU\s+)?(\S+)\s+(.*)/)
{
$program = $2;
$package = $1 ? "$1$2" : $2;
$version = $3;
}
else
{
$version = $_;
}
$program =~ s!.*/!!;
# no info for `info' itself
$opt_no_info = 1 if $program eq 'info';
# --name overrides --include contents
$include{NAME} = "$program \\- $opt_name" if $opt_name;
# Default (useless) NAME paragraph
$include{NAME} ||= "$program \\- manual page for $program $version";
# Man pages traditionally have the page title in caps.
my $PROGRAM = uc $program;
# Header.
print <<EOT;
.\" DO NOT MODIFY THIS FILE! It was generated by $this_program $this_version.
.TH $PROGRAM 1 "$date" "$package $version" "FSF"
.SH NAME
$include{NAME}
EOT
my $accumulate = 1;
my @description = ();
sub convert_option;
# Output converted --help information.
for (@help)
{
chomp;
if (s/^Usage:\s+\S+\s+(.*)\n?//)
{
# Turn the usage clause into a synopsis.
my $synopsis = '';
do {
my $syn = $1;
$syn =~ s/(([][]|\.\.+)+)/\\fR$1\\fI/g;
$syn =~ s/^/\\fI/ unless $syn =~ s/^\\fR//;
$syn .= '\fR';
$syn =~ s/\\fI(\s*)\\fR/$1/g;
$synopsis .= ".br\n" unless $accumulate;
$synopsis .= ".B $program\n";
$synopsis .= "$syn\n";
$accumulate = 0;
} while s/^(?:Usage|\s*or):\s+\S+\s+(.*)\n?//;
# Include file overrides SYNOPSIS.
print ".SH SYNOPSIS\n", $include{SYNOPSIS} || $synopsis;
# Dump any accumulated description text.
print ".SH DESCRIPTION\n";
print @description;
# Add additional description text from include file.
if ($include{DESCRIPTION})
{
print ".PP\n" unless $include{DESCRIPTION} =~ /^\..P/;
print $include{DESCRIPTION};
}
next unless $_;
}
# Accumulate text if the synopsis has not been produced yet.
if ($accumulate)
{
push @description, ".PP\n" if @description;
push @description, "$_\n";
next;
}
# Catch start of options.
if (/^Options:/)
{
print qq(.SH OPTIONS\n);
s/Options://;
}
# Catch bug report text.
if (/^Report bugs |^Email bug reports to /)
{
print qq(.SH "REPORTING BUGS"\n$_\n);
next;
}
# Special case for tar 1.12: --label=NAME\nPATTERN.
s{(\n[ \t]*)(-V,[ \t]+--label=NAME.*)\n[ \t]+PATTERN[ \t]+}
{$1$2$1\\&...=PATTERN };
# Convert options.
s/(\s)(-[][\w=-]+|\\&\S+)/$1 . convert_option $2/ge;
# Option subsections have second line indented.
print qq(.SS "$1"\n) if s/^(\S.*)\n(\s)/$2/;
# Lines indented more than about 10 spaces may be assumed to be
# continuations of the previous line.
s/\n {10,}/ /g;
# Lines following dotted (*) or numbered points may also be
# continued if indented to the same level as the text following
# the point.
1 while s{((?:^|\n)(\s+)(?:[1-9][.)]|\*)(\s+)(?:[^\n]+))\n\2 \3(\S)}
{$1 $4}g;
# Indented paragraph.
if (/^\s/)
{
for (split /\n/)
{
s/^\s+//;
s/([^,])\s+/$1\n/;
print ".TP\n$_\n" if $_;
}
}
# Anything else.
else
{
print ".PP\n$_\n";
}
}
# Print any include items other than the ones we have already dealt
# with.
for (@include)
{
print qq(.SH "$_"\n$include{$_})
unless /^(NAME|SYNOPSIS|DESCRIPTION|SEE ALSO)$/;
}
# Refer to the real documentation.
if ($include{'SEE ALSO'} or !$opt_no_info)
{
print qq(.SH "SEE ALSO"\n);
print $include{'SEE ALSO'}, ".PP\n" if $include{'SEE ALSO'};
print <<EOT unless $opt_no_info;
The full documentation for
.B $program
is maintained as a Texinfo manual. If the
.B info
and
.B $program
programs are properly installed at your site, the command
.IP
.B info $program
.PP
should give you access to the complete manual.
EOT
}
# Output converted --version information.
for (@version)
{
chomp;
# Join hyphenated lines.
s/([A-Za-z])-\n */$1/g;
# Convert copyright symbol or (c) to nroff character.
s/Copyright\s+(?:\xa9|\([Cc]\))/Copyright \\(co/g;
# Insert appropriate headings for copyright and author.
if (/^Copyright\s\\/) { print ".SH COPYRIGHT\n" }
elsif (/^Written\s+by/) { print ".SH AUTHOR\n" }
else { print ".PP\n"; }
# Insert line breaks before additional copyright messages and the
# disclaimer.
s/(.)\n(Copyright\s|This is free software)/$1\n.br\n$2/g;
print "$_\n";
}
exit;
# Convert option dashes to \- to stop nroff from hyphenating 'em, and
# embolden. Option arguments get italicised.
sub convert_option
{
my $option = '\fB' . shift;
$option =~ s/-/\\-/g;
unless ($option =~ s/\[=(.*)\]$/\\fR[=\\fI$1\\fR]/)
{
$option =~ s/=(.)/\\fR=\\fI$1/;
$option =~ s/ (.)/ \\fI$1/;
$option .= '\fR';
}
$option;
}

10
doc/sample-config/tinc-up
View file

@ -2,14 +2,10 @@
# This file sets up the tap device.
# It gives you the freedom to do anything you want with it.
# Use the correct name for the tap device:
# For the Linux tun/tap device $INTERFACE is set to the right name,
# but for ethertap and FreeBSD this is tap0, tap1, tap2 etcetera,
# for Solaris and OpenBSD it is tun0, tun1, etcetera.
# Set hardware ethernet address (required!)
ifconfig $INTERFACE hw ether fe:fd:0:0:0:0
# The environment variable $INTERFACE is set to the right name
# on most platforms, but if it doesn't work try to set it manually.
# Give it the right ip and netmask. Remember, the subnet of the
# tap device must be larger than that of the individual Subnets
# as defined in the host configuration file!
ifconfig $INTERFACE 192.168.1.1 netmask 255.255.0.0 -arp
ifconfig $INTERFACE 192.168.1.1 netmask 255.255.0.0

9
doc/sample-config/tinc.conf
View file

@ -15,11 +15,8 @@ Name = alpha
# May be used multiple times for redundance.
ConnectTo = beta
# The tap device tinc will use. Required.
# The tap device tinc will use.
# Default is /dev/tap0 for ethertap or FreeBSD,
# /dev/tun0 for Solaris and OpenBSD,
# and /dev/misc/net/tun for Linux tun/tap device.
Device = /dev/misc/net/tun
# The file in which the private key for this host is stored. Required.
PrivateKeyFile = /etc/tinc/example/rsa_key.priv
# and /dev/net/tun for Linux tun/tap device.
Device = /dev/net/tun

5484
doc/texinfo.tex
View file

File diff suppressed because it is too large Load diff

196
doc/tinc.conf.5
View file

@ -1,196 +0,0 @@
.TH TINC 5 "May 2000" "tinc version 1.0" "FSF"
.SH NAME
tincd.conf \- tinc daemon configuration
.SH "DESCRIPTION"
The files in the \fI/etc/tinc\fR directory contain runtime and
security information for the \fBtinc\fR(8) daemon.
.PP
.SH "NETWORKS"
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 \fI-c\fR option.
We have thought of another way of dealing with this: network
names. This means that you call \fBtincd\fR with the \fI-n\fR argument,
which will assign a name to this daemon.
The effect of this is that the daemon will set its configuration
``root'' to \fI/etc/tinc/\fBnn\fI/\fR, where \fBnn\fR is your argument
to the \fI-n\fR option. You'll notice that it appears in syslog as
``tincd.\fBnn\fR''.
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 \fI/etc/tinc/\fR,
instead of \fI/etc/tinc/\fBnn\fI/\fR; the configuration file should be
\fI/etc/tinc/tincd.conf\fR, and the passphrases are now expected to be
in \fI/etc/tinc/passphrases/\fR.
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.
.PP
.SH "PASSPHRASES"
You should use the \fBgenauth\fR(8) program to generate passphrases.
with, it accepts a single parameter, which is the number of bits the
passphrase should be. Its output should be stored in
\fI/etc/tinc/\fBnn\fI/passphrases/local\fR \-\- where \fBnn\fR stands
for the network (See under \fBNETWORKS\fR) above.
Please see the manpage for \fBgenauth\fR to learn more about setting
up an authentication scheme.
.PP
.SH "CONFIGURATION"
The actual configuration of the daemon is done in the file
\fI/etc/tinc/\fBnn\fI/tincd.conf\fR.
This file consists of comments (lines started with a \fB#\fR) or
assignments in the form of
.PP
.Vb 1
\& \fIVariable \fB= \fIValue\fR.
.Ve
.PP
The variable names are case insensitive, and any spaces, tabs,
newlines and carriage returns are ignored. \fINote\fR: it is not
required that you put in the \fB=\fR sign, but doing so improves
readability. If you leave it out, remember to replace it with at least
one space character.
.PP
.SH "VARIABLES"
.PP
Here are all valid variables, listed in alphabetical order. The default
value, required or optional is given between parentheses.
.TP
\fBConnectPort\fR = <\fIport\fR> (655)
Connect to the upstream host (given with the \fBConnectTo\fR directive) on
port \fIport\fR. port may be given in decimal (default), octal (when preceded
by a single zero) or hexadecimal (prefixed with 0x). \fIport\fR is the port
number for both the UDP and the TCP (meta) connections.
.TP
\fBConnectTo\fR = <\fIIP address|hostname\fR> (optional)
Specifies which host to connect to on startup. Multiple \fBConnectTo\fR variables
may be specified, if connecting to the first one fails then tinc will try
the next one, and so on. It is possible to specify hostnames for dynamic IP
addresses (like those given on dyndns.org), tinc will not cache the resolved
IP address.
If you don't specify a host with \fBConnectTo\fR, regardless of whether a
value for \fBConnectPort\fR is given, tinc won't connect at all, and will
instead just listen for incoming connections.
.TP
\fBHostnames\fR = <\fIyes|no\fR> (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.
.TP
\fBIndirectData\fR = <\fIyes|no\fR> (no)
This option specifies whether other tinc daemons besides the one you
specified with \fBConnectTo\fR 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.
.TP
\fBInterface\fR = <\fIdevice\fR> (optional)
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.
.TP
\fBInterfaceIP\fR = <\fIlocal address\fR> (optional)
If your computer has more than one IP address on a single interface (for example
if you are running virtual hosts), tinc will by default listen on all of them for
incoming connections. It is possible to bind tinc to a single IP address with
this variable. It is still possible to listen on several interfaces at the same
time though, if they share the same IP address.
.TP
\fBKeyExpire\fR = <\fIseconds\fR> (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.
.TP
\fBListenPort\fR = <\fIport\fR> (655)
Listen on local port \fIport\fR. The computer connecting to this daemon should
use this number as the argument for his \fBConnectPort\fR.
.TP
\fBMyOwnVPNIP\fR = <\fIlocal address[/maskbits]\fR> (required)
The \fIlocal address\fR 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).
\fImaskbits\fR is the number of bits set to 1 in the netmask part.
.TP
\fBMyVirtualIP\fR = <\fIlocal address[/maskbits]>
This is an alias for \fBMyOwnVPNIP\fR.
.TP
\fBPassphrases\fR = <\fIdirectory\fR> (/etc/tinc/NETNAME/passphrases)
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.
.TP
\fBPingTimeout\fR = <\fIseconds\fR> (5)
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.
.TP
\fBTapDevice\fR = <\fIdevice\fR> (/dev/tap0)
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.
.TP
\fBTCPonly\fR = <\fIyes|no\fR> (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. This is experimental code,
try this at your own risk.
.TP
\fBVpnMask\fR = <\fImask\fR> (optional)
The mask that defines the scope of the entire VPN. This option is not used
by the tinc daemon itself, but can be used by startup scripts to configure
the ethertap devices correctly.
.PP
.SH "FILES"
.TP
\fI/etc/tinc/\fR
The top directory for configuration files.
.TP
\fI/etc/tinc/\fBnn\fI/tincd.conf\fR
The default name of the configuration file for net
\fBnn\fR.
.TP
\fI/etc/tinc/\fBnn\fI/passphrases/\fR
Passphrases are kept in this directory. (See the section
\fBPASSPHRASES\fR above).
.PP
.SH "SEE ALSO"
\fBtincd\fR(8), \fBgenauth\fR(8)
.TP
\fBhttp://tinc.nl.linux.org/\fR
.PP
The full documentation for
.B tinc
is maintained as a Texinfo manual. If the
.B info
and
.B tinc
programs are properly installed at your site, the command
.IP
.B info tinc
.PP
should give you access to the complete manual.
.PP
tinc comes with ABSOLUTELY NO WARRANTY. This is free software,
and you are welcome to redistribute it under certain conditions;
see the file COPYING for details.

399
doc/tinc.conf.5.in Normal file
View file

@ -0,0 +1,399 @@
.Dd 2002-04-09
.Dt TINC.CONF 5
.\" Manual page created by:
.\" Ivo Timmermans <ivo@o2w.nl>
.\" Guus Sliepen <guus@sliepen.eu.org>
.Sh NAME
.Nm tinc.conf
.Nd tinc daemon configuration
.Sh DESCRIPTION
The files in the
.Pa @sysconfdir@/tinc/
directory contain runtime and security information for the tinc daemon.
.Sh NETWORKS
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
.Fl c
option.
.Pp
We have thought of another way of dealing with this: network names.
This means that you call
.Nm
with the
.Fl n
option, which will assign a name to this daemon.
.Pp
The effect of this is that the daemon will set its configuration root to
.Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa / ,
where
.Ar NETNAME
is your argument to the
.Fl n
option.
You'll notice that messages appear in syslog as coming from
.Nm tincd. Ns Ar NETNAME .
.Pp
However, it is not strictly necessary that you call tinc with the
.Fl n
option.
In this case, the network name would just be empty,
and it will be used as such.
.Nm tinc
now looks for files in
.Pa @sysconfdir@/tinc/ ,
instead of
.Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa / ;
the configuration file should be
.Pa @sysconfdir@/tinc/tinc.conf ,
and the host configuration files are now expected to be in
.Pa @sysconfdir@/tinc/hosts/ .
.Pp
But it is highly recommended that you use this feature of
.Nm tinc ,
because it will be so much clearer whom your daemon talks to.
Hence, we will assume that you use it.
.Sh NAMES
Each tinc daemon should have a name that is unique in the network which it will be part of.
The name will be used by other tinc daemons for identification.
The name has to be declared in the
.Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa /tinc.conf
file.
.Pp
To make things easy,
choose something that will give unique and easy to remember names to your tinc daemon(s).
You could try things like hostnames, owner surnames or location names.
.Sh PUBLIC/PRIVATE KEYS
You should use
.Ic tincd -K
to generate public/private keypairs.
It will generate two keys.
The private key should be stored in a separate file
.Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa /rsa_key.priv
\-\- where
.Ar NETNAME
stands for the network (see
.Sx NETWORKS )
above.
The public key should be stored in the host configuration file
.Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa /hosts/ Ns Va NAME
\-\- where
.Va NAME
stands for the name of the local tinc daemon (see
.Sx NAMES ) .
.Sh SERVER CONFIGURATION
The server configuration of the daemon is done in the file
.Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa /tinc.conf .
This file consists of comments (lines started with a
.Li # )
or assignments in the form of:
.Pp
.Va Variable Li = Ar Value .
.Pp
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
.Li =
sign, but doing so improves readability.
If you leave it out, remember to replace it with at least one space character.
.Pp
Here are all valid variables, listed in alphabetical order.
The default value is given between parentheses.
.Bl -tag -width indent
.It Va AddressFamily Li = ipv4 | ipv6 | any Pq any
This option affects the address family of listening and outgoing sockets.
If
.Qq any
is selected, then depending on the operating system both IPv4 and IPv6 or just
IPv6 listening sockets will be created.
.It Va BindToAddress Li = Ar address Bq experimental
If your computer has more than one IPv4 or IPv6 address,
.Nm 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.
.Pp
This option may not work on all platforms.
.It Va BindToInterface Li = Ar interface Bq experimental
If your computer has more than one network interface,
.Nm tinc
will by default listen on all of them for incoming connections.
It is possible to bind only to a single interface with this variable.
.Pp
This option may not work on all platforms.
.It Va ConnectTo Li = Ar name
Specifies which other tinc daemon to connect to on startup.
Multiple
.Va 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
.Va ConnectTo
line).
.Pp
If you don't specify a host with
.Va ConnectTo ,
.Nm tinc
won't try to connect to other daemons at all,
and will instead just listen for incoming connections.
.It Va Device Li = Ar device Po Pa /dev/tap0 , Pa /dev/net/tun No or other depending on platform Pc
The virtual network device to use.
.Nm tinc
will automatically detect what kind of device it is.
Note that you can only use one device per daemon.
Under Windows, use
.Va Interface
instead of
.Va Device .
The info pages of the tinc package contain more information
about configuring the virtual network device.
.It Va Hostnames Li = yes | no Pq 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 every time it does
a lookup if your DNS server is not responding.
.Pp
This does not affect resolving hostnames to IP addresses from the
host configuration files.
.It Va Interface Li = Ar 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.
Under Windows, this variable is used to select which network interface will be used.
If you specified a
.Va Device ,
this variable is almost always already correctly set.
.It Va KeyExpire Li = Ar seconds Pq 3600
This option controls the period 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.
.It Va MACExpire Li = Ar seconds Pq 600
This option controls the amount of time MAC addresses are kept before they are removed.
This only has effect when
.Va Mode
is set to
.Qq switch .
.It Va MaxTimeout Li = Ar seconds Pq 900
This is the maximum delay before trying to reconnect to other tinc daemons.
.It Va Mode Li = router | switch | hub Pq router
This option selects the way packets are routed to other daemons.
.Bl -tag -width indent
.It router
In this mode
.Va 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.
.Pp
This is the default mode, and unless you really know you need another mode, don't change it.
.It 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.
.Pp
This mode is primarily useful if you want to bridge Ethernet segments.
.It 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.
.El
.It Va Name Li = Ar name Bq required
This is the name which identifies this tinc daemon.
It must be unique for the virtual private network this daemon will connect to.
.It Va PingTimeout Li = Ar seconds Pq 60
The number of seconds of inactivity that
.Nm tinc
will wait before sending a probe to the other end.
If that other end doesn't answer within that same amount of time,
the connection is terminated,
and the others will be notified of this.
.It Va PriorityInheritance Li = yes | no Po no Pc Bq 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.
.It Va PrivateKey Li = Ar key Bq obsolete
The private RSA key of this tinc daemon.
It will allow this tinc daemon to authenticate itself to other daemons.
.It Va PrivateKeyFile Li = Ar filename Po Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa /rsa_key.priv Pc
The file in which the private RSA key of this tinc daemon resides.
Note that there must be exactly one of
.Va PrivateKey
or
.Va PrivateKeyFile
specified in the configuration file.
.El
.Sh HOST CONFIGURATION FILES
The host configuration files contain all information needed
to establish a connection to those hosts.
A host configuration file is also required for the local tinc daemon,
it will use it to read in it's listen port, public key and subnets.
.Pp
The idea is that these files are portable.
You can safely mail your own host configuration file to someone else.
That other person can then copy it to his own hosts directory,
and now his tinc daemon will be able to connect to your tinc daemon.
Since host configuration files only contain public keys,
no secrets are revealed by sending out this information.
.Bl -tag -width indent
.It Va Address Li = Ar address Bq recommended
The IP address or hostname of this tinc daemon on the real network.
This wil only be used when trying to make an outgoing connection to this tinc daemon.
Multiple
.Va Address
variables can be specified, in which case each address will be tried until a working
connection has been established.
.It Va Cipher Li = Ar cipher Pq blowfish
The symmetric cipher algorithm used to encrypt UDP packets.
Any cipher supported by OpenSSL is recognised.
Furthermore, specifying
.Qq none
will turn off packet encryption.
.It Va Compression Li = Ar level Pq 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).
.It Va Digest Li = Ar digest Pq sha1
The digest algorithm used to authenticate UDP packets.
Any digest supported by OpenSSL is recognised.
Furthermore, specifying
.Qq none
will turn off packet authentication.
.It Va IndirectData Li = yes | no Pq no
This option specifies whether other tinc daemons besides the one you specified with
.Va 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.
.It Va MACLength Li = Ar length Pq 4
The length of the message authentication code used to authenticate UDP packets.
Can be anything from
.Qq 0
up to the length of the digest produced by the digest algorithm.
.It Va Port Li = Ar port Pq 655
The port number on which this tinc daemon is listening for incoming connections.
.It Va PublicKey Li = Ar key Bq obsolete
The public RSA key of this tinc daemon.
It will be used to cryptographically verify it's identity and to set up a secure connection.
.It Va PublicKeyFile Li = Ar filename Bq obsolete
The file in which the public RSA key of this tinc daemon resides.
.Pp
From version 1.0pre4 on
.Nm 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 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.
.It Va Subnet Li = Ar address Ns Op Li / Ns Ar prefixlength
The subnet which this tinc daemon will serve.
.Nm tinc
tries to look up which other daemon it should send a packet to by searching the appropriate subnet.
If the packet matches a subnet,
it will be sent to the daemon who has this subnet in his host configuration file.
Multiple
.Va Subnet
variables can be specified.
.Pp
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.
.It Va TCPOnly Li = yes | no Pq no
If this variable is set to yes,
then the packets are tunnelled over the 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.
.El
.Sh SCRIPTS
Apart from reading the server and host configuration files,
tinc can also run scripts at certain moments.
On Windows (not Cygwin), the scripts should have the extension
.Pa .bat .
.Bl -tag -width indent
.It Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa /tinc-up
This is the most important script.
If it is present it will be executed right after the tinc daemon has been started and has connected to the virtual network device.
It should be used to set up the corresponding network interface,
but can also be used to start other things.
Under Windows you can use the Network Connections control panel instead of creating this script.
.It Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa /tinc-down
This script is started right before the tinc daemon quits.
.It Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa /hosts/ Ns Ar HOST Ns Pa -up
This script is started when the tinc daemon with name
.Ar HOST
becomes reachable.
.It Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa /hosts/ Ns Ar HOST Ns Pa -down
This script is started when the tinc daemon with name
.Ar HOST
becomes unreachable.
.El
.Pp
The scripts are started without command line arguments, but can make use of certain environment variables.
Under UNIX like operating systems the names of environment variables must be preceded by a
.Li $
in scripts.
Under Windows, in
.Pa .bat
files, they have to be put between
.Li %
signs.
.Bl -tag -width indent
.It Ev NETNAME
If a netname was specified, this environment variable contains it.
.It Ev NAME
Contains the name of this tinc daemon.
.It Ev DEVICE
Contains the name of the virtual network device that tinc uses.
.It Ev INTERFACE
Contains the name of the virtual network interface that tinc uses.
This should be used for commands like
.Pa ifconfig .
.It Ev NODE
When a host becomes (un)reachable, this is set to its name.
.It Ev REMOTEADDRESS
When a host becomes (un)reachable, this is set to its real address.
.It Ev REMOTEPORT
When a host becomes (un)reachable, this is set to the port number it uses for communication with other tinc daemons.
.El
.Sh FILES
The most important files are:
.Bl -tag -width indent
.It Pa @sysconfdir@/tinc/
The top directory for configuration files.
.It Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa /tinc.conf
The default name of the server configuration file for net
.Ar NETNAME .
.It Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa /hosts/
Host configuration files are kept in this directory.
.It Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa /tinc-up
If an executable file with this name exists,
it will be executed right after the tinc daemon has connected to the virtual network device.
It can be used to set up the corresponding network interface.
.It Pa @sysconfdir@/tinc/ Ns Ar NETNAME Ns Pa /tinc-down
If an executable file with this name exists,
it will be executed right before the tinc daemon is going to close
its connection to the virtual network device.
.El
.Sh SEE ALSO
.Xr tincd 8 ,
.Pa http://tinc.nl.linux.org/ ,
.Pa http://www.linuxdoc.org/LDP/nag2/ .
.Pp
The full documentation for
.Nm tinc
is maintained as a Texinfo manual.
If the info and tinc programs are properly installed at your site, the command
.Ic info tinc
should give you access to the complete manual.
.Pp
.Nm tinc
comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it under certain conditions;
see the file COPYING for details.

2173
doc/tinc.texi
View file

File diff suppressed because it is too large Load diff

113
doc/tincd.8 → doc/tincd.8.in
View file

@ -1,22 +1,25 @@
.Dd 2002-03-25
.Dt TINCD 8
.\" Manual page created by:
.\" Ivo Timmermans <itimmermans@bigfoot.com>
.\" Guus Sliepen <guus@sliepen.warande.net>
.\" Ivo Timmermans <ivo@o2w.nl>
.\" Guus Sliepen <guus@sliepen.eu.org>
.Sh NAME
.Nm tincd
.Nd tinc VPN daemon
.Sh SYNOPSIS
.Nm
.Op Fl cdDkKn
.Op Fl -bypass-security
.Op Fl cdDkKnL
.Op Fl -config Ns = Ns Ar DIR
.Op Fl -debug Ns = Ns Ar LEVEL
.Op Fl -generate-keys Ns Op = Ns Ar BITS
.Op Fl -help
.Op Fl -kill Ns = Ns Ar SIGNAL
.Op Fl -net Ns = Ns Ar NETNAME
.Op Fl -no-detach
.Op Fl -debug Ns Op = Ns Ar LEVEL
.Op Fl -kill Ns Op = Ns Ar SIGNAL
.Op Fl -net Ns = Ns Ar NETNAME
.Op Fl -generate-keys Ns Op = Ns Ar BITS
.Op Fl -mlock
.Op Fl -logfile Ns Op = Ns Ar FILE
.Op Fl -pidfile Ns = Ns Ar FILE
.Op Fl -bypass-security
.Op Fl -help
.Op Fl -version
.Sh DESCRIPTION
This is the daemon of tinc, a secure virtual private network (VPN) project.
@ -31,37 +34,59 @@ If that succeeds,
it will detach from the controlling terminal and continue in the background,
accepting and setting up connections to other tinc daemons
that are part of the virtual private network.
Under Windows (not Cygwin) tinc will install itself as a service,
which will be restarted automatically after reboots.
.Sh OPTIONS
.Bl -tag -width indent
.It Fl -bypass-security
Disables encryption and authentication.
Only useful for debugging.
.It Fl c, -config Ns = Ns Ar DIR
Read configuration options from
.Ar DIR .
Read configuration files from
.Ar DIR
instead of
.Pa @sysconfdir@/tinc/ .
.It Fl D, -no-detach
Don't fork and detach.
This will also disable the automatic restart mechanism for fatal errors.
If not mentioned otherwise, this will show log messages on the standard error output.
.It Fl d, -debug Ns Op = Ns Ar LEVEL
Increase debug level or set it to
.Ar LEVEL
(see below).
.It Fl K, -generate-keys Ns Op = Ns Ar BITS
Generate public/private RSA keypair and exit.
If
.Ar BITS
is omitted, the default length will be 1024 bits.
.It Fl -help
Display short list of options.
.It Fl k, -kill Ns Op = Ns Ar SIGNAL
Attempt to kill a running
.Nm
(optionally with the specified
.Ar SIGNAL
instead of SIGTERM) and exit.
Under Windows (not Cygwin) the optional argument is ignored,
the service will always be stopped and removed.
.It Fl n, -net Ns = Ns Ar NETNAME
Connect to net
.Ar NETNAME .
.It Fl D, -no-detach
Don't fork and detach.
This will also disable the automatic restart mechanism for fatal errors.
.It Fl K, -generate-keys Ns Op = Ns Ar BITS
Generate public/private RSA keypair and exit.
If
.Ar BITS
is omitted, the default length will be 1024 bits.
.It Fl 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.
.It Fl -logfile Ns Op = Ns Ar FILE
Write log entries to a file instead of to the system logging facility.
If
.Ar FILE
is omitted, the default is
.Pa @localstatedir@/log/tinc. Ns Ar NETNAME Ns Pa .log.
.It Fl -pidfile Ns = Ns Ar FILE
Write PID to
.Ar FILE
instead of
.Pa @localstatedir@/run/tinc. Ns Ar NETNAME Ns Pa .pid.
Under Windows this option will be ignored.
.It Fl -bypass-security
Disables encryption and authentication of the meta protocol.
Only useful for debugging.
.It Fl -help
Display short list of options.
.It Fl -version
Output version information and exit.
.El
@ -80,7 +105,11 @@ and if
didn't succeed to connect to an uplink the first time after it started,
it defaults to the maximum time of 15 minutes.
.It HUP
Closes all connections, rereads the configuration file and restarts the daemon.
Partially rereads configuration files.
Connections to hosts whose host config file are removed are closed.
New outgoing connections specified in
.Pa tinc.conf
will be made.
.It INT
Temporarily increases debug level to 5.
Send this signal again to revert to the original level.
@ -105,7 +134,7 @@ It will also any serious error.
.It 1
This will log all connections that are made with other tinc daemons.
.It 2
This will log status and error messages from other tinc daemons.
This will log status and error messages from scripts and other tinc daemons.
.It 3
This will log all requests that are exchanged with other tinc daemons. These include
authentication, key exchange and connection list updates.
@ -116,29 +145,11 @@ This will log all network traffic over the virtual private network.
.El
.Sh FILES
.Bl -tag -width indent
.It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /tinc.conf
The configuration file for
.Nm .
.It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /tinc-up
Script which is executed as soon as the virtual network device has been allocated.
Purpose is to further configure that device.
.It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /tinc-down
Script which is executed when
.Nm
exits.
Purpose is to cleanly shut down the virtual network device before it will be deallocated.
.It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /hosts/*
The directory containing the host configuration files
used to authenticate other tinc daemons.
.It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /hosts/ Ns Ar NAME Ns Pa -up
Script which is executed as soon as host
.Ar NAME
becomes reachable.
.It Pa /etc/tinc/ Ns Ar NETNAME Ns Pa /hosts/ Ns Ar NAME Ns Pa -down
Script which is executed as soon as host
.Ar NAME
becomes unreachable.
.It Pa /var/run/tinc. Ns Ar NETNAME Ns Pa .pid
.It Pa @sysconfdir@/tinc/
Directory containing the configuration files tinc uses.
For more information, see
.Xr tinc.conf 5 .
.It Pa @localstatedir@/run/tinc. Ns Ar NETNAME Ns Pa .pid
The PID of the currently running
.Nm
is stored in this file.
@ -168,7 +179,7 @@ tinc comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it under certain conditions;
see the file COPYING for details.
.Sh AUTHORS
.An "Ivo Timmermans" Aq itimmermans@bigfoot.com
.An "Guus Sliepen" Aq guus@sliepen.warande.net
.An "Ivo Timmermans" Aq ivo@o2w.nl
.An "Guus Sliepen" Aq guus@sliepen.eu.org
.Pp
And thanks to many others for their contributions to tinc!

4
doc/tincinclude.texi.in Normal file
View file

@ -0,0 +1,4 @@
@set VERSION @VERSION@
@set PACKAGE @PACKAGE@
@set sysconfdir @sysconfdir@
@set localstatedir @localstatedir@