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