Use logging.h instead of syslog.h
[tinc] / doc / HOWTO
1                                 ==============
2                                 The TINC HOWTO
3                                 ==============
4
5                                 Wessel Dankers
6                                wsl@nl.linux.org
7 \f
8 Introduction
9 ------------
10 Tinc is a system to create a virtual ethernet network on top of an existing
11 infrastructure. This infrastructure can be anything from modem lines to
12 gigabit ethernet networks, as long as they talk IP. Once you install and
13 configure tinc, your host will get an extra IP address, just like it would
14 when you stick an extra ethernet card into it. Using this IP address, it can
15 communicate with all hosts in its virtual network using strong encryption.
16
17 If you install Tinc on a router (and pick your numbers correctly) you can
18 have the router forward all packets. This way you can---instead of
19 connecting hosts---connect entire sites together! Now you need only one
20 outgoing network connection for both internet and intranet.
21 \f
22 Architecture
23 ------------
24 When a few Tinc daemons are running they will try to seek contact with
25 eachother. A daemon is all the time connected to a few other daemons,
26 but if traffic is required with a daemon it doesn't know yet, it will
27 instantly contact it and exchange keys. These so-called meta-connections
28 are made over TCP, using encryption of course.
29
30 When actual traffic has to be sent, a daemon checks his connection list to
31 see if the addressee is known (and makes contact with it if neccessary).
32 All packets are then sent using UDP to the other host, just like in a real
33 network. If a packet gets lost, the connection layer of Linux will resend
34 the packet, just like it would over a normal network.
35
36 Once in a while the daemons will renegotiate keys so that even if a cracker
37 breaks one, it'll be of limited use.
38 \f
39 Getting Tinc
40 ------------
41 Before you fetch the latest tarball, you might want to check if there's a
42 package for your Linux distribution. One of the main authors is a Debian
43 Developer, so you can expect the Debian packages to be very up to date.
44
45 The official website for Tinc can be found at http://tinc.nl.linux.org/.
46 There you can find Debian packages, RPM's and of course... the tarball!
47 Since we run Doohickey Linux Pro 1.0, for which no package exists (or
48 indeed the distribution itself) we shall compile the package ourselves.
49 \f
50 Building
51 --------
52 The Tinc source adheres to so many standards it makes you head spin.
53 Even the debug messages have been localized! Amazing. Tinc also comes
54 with a configuration script. If you like to see what is there to
55 configure run ./configure --help | more. If you don't have time for such
56 nonsense:
57
58         ./configure --sysconfdir=/etc
59
60 This will see if your system is nice enough to run tinc on, and will
61 create some Makefiles and other stuff which will together build tinc.
62
63         make
64         make install
65
66 The first will do the actual build, the second copies all files into place.
67 \f
68 The kernel
69 ----------
70 Next you will have to configure the kernel to support the tap device.
71 It is important that you run a recent kernel, but anything after 2.2.16
72 will do. You have to enable both the netlink device AND the ethertap
73 device (in that order). Enable them as modules!
74 Compile, install =) You don't even have to reboot.
75 \f
76 Picking your numbers
77 --------------------
78 The first thing we should do is pick network numbers. Tinc has a very
79 peculiar taste for network numbers, which is caused by the way it routes
80 traffic. However, it turns out to be really handy if you want to use
81 your tinc host as a router for a site.
82
83 The numbers have to be in a range that is not yet in use in your existing,
84 real network! In this example we will use numbers from the 192.168.0/16
85 range. This is standard CIDR notation for all IP addresses from 192.168.0.0
86 to 192.168.255.255. The /16 means that the first 16 bits form the network
87 part.
88
89 It is common practice for Tinc networks to use private (RFC 1918) addresses.
90 This is not necessary, but it would be a waste to use official addresses
91 for a private network!
92
93 In the example we will connect three machines: f00f, fdiv and hlt. We will
94 give each an address, but not just that, also a slice of our address space
95 to play with.
96
97       Host          Real address           Tinc network
98       ---------------------------------------------------
99       f00f          126.202.37.20          192.168.1.1/24
100       fdiv          126.202.37.81          192.168.2.1/24
101       hlt           103.22.1.218           192.168.3.1/24
102
103 It is very important that none of the Tinc netmasks overlap! Note how the
104 192.168.0/16 network covers the entire address space of the three hosts.
105 We will refer to the 192.168.0/16 network as the `umbrella' from now on.
106 As you can see we can fit 256 hosts into this umbrella this way, which is
107 also the practical maximum for tinc. Let's name our VPN 'fubar'.
108 \f
109 The configuration file
110 ----------------------
111 Let's create a configuration file for f00f. We have to put it in
112 /etc/tinc/fubar because that's how we named our VPN.
113
114         MyOwnVPNIP = 192.168.1.1/24
115         VpnMask    = 255.255.0.0
116         ConnectTo  = 126.202.37.81
117         ConnectTo  = 103.22.1.218
118         TapDevice  = /dev/tap0
119
120 The first two lines tell Tinc about the numbers we have chosen above.
121 Using the ConnectTo lines, the daemon will seek contact with the rest of
122 the umbrella. It's possible to configure any number of ConnectTo lines,
123 you can even omit them so that it just sits and waits until someone else
124 contacts it. Until someone does, the poor daemon won't be able to send
125 any data because it doesn't know where everybody is.
126 The TapDevice is where the tinc daemon will interface with the kernel.
127 \f
128 The passphrases
129 ---------------
130 We will have to generate keys for ourselves, and get a key from everybody
131 we want to ConnectTo. All of these go into a directory named
132 /etc/tinc/fubar/passphrases. PROTECT THIS DIRECTORY!
133
134         mkdir -m 700 /etc/tinc/fubar/passphrases
135
136 To generate our own key:
137
138         genauth 1024 >/etc/tinc/fubar/passphrases/local
139
140 You should then proceed to give this key to anyone who wants to ConnectTo
141 you. DO THIS IN A SECURE MANNER! Anyone who has this number can do icky
142 things to the umbrella network! Encrypt it using PGP, GPG or another
143 program using asymmetric keys. Read it over the phone (without anyone
144 listening of course). Send it by snailmail. Write the key down and bring
145 it to your partners personally!
146
147 If you get any keys from your partners, store them under their network
148 number. For example, the key we get from fdiv's network administrator
149 will be stored in /etc/tinc/fubar/passphrases/192.168.2.0 (note the 0).
150 \f
151 Running the daemon
152 ------------------
153 If you use a package manager to install Tinc, the startup scripts use a file
154 called /etc/tinc/nets.boot to see which umbrella's exist. It has a line
155 per VPN, and lines starting with a # are ignored. Ours will contain:
156
157         # Example VPN from the HOWTO
158         fubar
159
160 In Debian, /etc/init.d/tinc start will start the daemons.
161
162 If you use Doohickey Linux just like we do, you'll have to edit the systems
163 startup scripts by hand. It should contain something along the lines of:
164
165         insmod ethertap -s --name=tap0 unit=0
166         ifconfig tap0 hw ether fe:fd:c0:a8:01:01
167         ifconfig tap0 192.168.1.1 netmask 255.255.0.0 broadcast 192.168.255.255 -arp
168
169 There are two things to note here! First, the MAC address of the ethertap
170 device is very important. It must start with fe:fd, and end in the
171 hexadecimal representation of the VPN IP number.
172 Second, the netmask of the tap device is set to that of the umbrella!
173
174 --
175 $Id: HOWTO,v 1.6 2002/04/12 08:25:01 guus Exp $