\input texinfo @c -*-texinfo-*-
-@c $Id: tinc.texi,v 1.8.4.22 2002/03/01 13:38:02 guus Exp $
+@c $Id: tinc.texi,v 1.8.4.29 2002/06/12 13:45:23 guus Exp $
@c %**start of header
@setfilename tinc.info
@settitle tinc Manual
<itimmermans@@bigfoot.com>, Guus Sliepen <guus@@sliepen.warande.net> and
Wessel Dankers <wsl@@nl.linux.org>.
-$Id: tinc.texi,v 1.8.4.22 2002/03/01 13:38:02 guus Exp $
+$Id: tinc.texi,v 1.8.4.29 2002/06/12 13:45:23 guus Exp $
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
<itimmermans@@bigfoot.com>, Guus Sliepen <guus@@sliepen.warande.net> and
Wessel Dankers <wsl@@nl.linux.org>.
-$Id: tinc.texi,v 1.8.4.22 2002/03/01 13:38:02 guus Exp $
+$Id: tinc.texi,v 1.8.4.29 2002/06/12 13:45:23 guus Exp $
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
tinc on OpenBSD relies on the tun driver for its data
acquisition from the kernel. It has been verified to work under at least OpenBSD 2.9.
+Tunneling IPv6 packets may not work on OpenBSD.
+
+
+@c ==================================================================
+@subsection Solaris
+
+@c ==================================================================
+@subsection NetBSD
+
+@cindex NetBSD
+tinc on NetBSD relies on the tun driver for its data
+acquisition from the kernel. It has been verified to work under at least NetBSD 1.5.2.
+
+Tunneling IPv6 does not work on OpenBSD.
+
@c ==================================================================
@subsection Solaris
@cindex Solaris
tinc on Solaris relies on the universal tun/tap driver for its data
acquisition from the kernel. Therefore, tinc will work on the same platforms
-as this driver. These are: Solaris, 2.1.x.
+as this driver. These are: Solaris 8 (SunOS 5.8).
+
+IPv6 packets cannot be tunneled on Solaris.
+
+@c ==================================================================
+@subsection Darwin (MacOS/X)
+
+@cindex Darwin
+@cindex MacOS/X
+tinc on Darwin relies on the tunnel driver for its data
+acquisition from the kernel. This driver is not part of Darwin but can be
+downloaded from @uref{http://chrisp.de/en/projects/tunnel.html}.
+
+IPv6 packets cannot be tunneled on Darwin.
@c
* Configuration of Linux kernels 2.4.0 and higher::
* Configuration of FreeBSD kernels::
* Configuration of OpenBSD kernels::
+* Configuration of NetBSD kernels::
* Configuration of Solaris kernels::
+* Configuration of Darwin (MacOS/X) kernels::
@end menu
@c ==================================================================
-@node Configuration of OpenBSD kernels, Configuration of Solaris kernels, Configuration of FreeBSD kernels, Configuring the kernel
+@node Configuration of OpenBSD kernels, Configuration of NetBSD kernels, Configuration of FreeBSD kernels, Configuring the kernel
@subsection Configuration of OpenBSD kernels
This section will contain information on how to configure your OpenBSD
@c ==================================================================
-@node Configuration of Solaris kernels, , Configuration of OpenBSD kernels, Configuring the kernel
+@node Configuration of NetBSD kernels, Configuration of Solaris kernels, Configuration of OpenBSD kernels, Configuring the kernel
+@subsection Configuration of NetBSD kernels
+
+This section will contain information on how to configure your NetBSD
+kernel to support the tun device. For 1.5.2 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 Darwin (MacOS/X) kernels, Configuration of NetBSD 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.
+kernel to support the universal tun/tap device. For Solaris 8 (SunOS 5.8),
+this is included in the default kernel configuration.
Unfortunately somebody still has to write the text.
+@c ==================================================================
+@node Configuration of Darwin (MacOS/X) kernels, , Configuration of Solaris kernels, Configuring the kernel
+@subsection Configuration of Darwin (MacOS/X) kernels
+
+Darwin does not come with a tunnel driver. You must download it at
+@uref{http://chrisp.de/en/projects/tunnel.html}. If compiling the source fails,
+try the binary module. The tunnel driver must be loaded before starting tinc
+with the following command:
+
+@example
+kmodload tunnel
+@end example
+
+Once loaded, the tunnel driver will automatically create @file{/dev/tun0}..@file{/dev/tun3}
+and the corresponding network interfaces.
+
+
@c ==================================================================
@node Libraries, , Configuring the kernel, Preparations
@section Libraries
@menu
* OpenSSL::
+* zlib::
@end menu
@c ==================================================================
-@node OpenSSL, , Libraries, Libraries
+@node OpenSSL, zlib, Libraries, Libraries
@subsection OpenSSL
@cindex OpenSSL
@end quotation
+@c ==================================================================
+@node zlib, , OpenSSL, Libraries
+@subsection zlib
+
+@cindex zlib
+For the optional compression of UDP packets, tinc uses the functions provided
+by the zlib library.
+
+If this library is not installed, you wil get an error when configuring
+tinc for build. Support for running tinc without having zlib
+installed @emph{may} be added in the future.
+
+You can use your operating system's package manager to install this if
+available. Make sure you install the development AND runtime versions
+of this package.
+
+If you have to install zlib manually, you can get the source code
+from @url{http://www.gzip.org/zlib/}. Instructions on how to configure,
+build and install this package are included within the package. Please
+make sure you build development and runtime libraries (which is the
+default).
+
+
@c
@c
@c
you can use the package management tools of that distribution to install tinc.
The documentation that comes along with your distribution will tell you how to do that.
+@menu
+* Darwin (MacOS/X) build environment::
+@end menu
+
+
+@c ==================================================================
+@node Darwin (MacOS/X) build environment, , , Building and installing tinc
+@subsection Darwin (MacOS/X) build environment
+
+In order to build tinc on Darwin, you need to install the MacOS/X Developer Tools
+from @uref{http://developer.apple.com/tools/macosxtools.html} and
+a recent version of Fink from @uref{http://fink.sourceforge.net/}.
+
+After installation use fink to download and install the following packages:
+autoconf25, automake, dlcompat, m4, openssl and zlib.
+
@c ==================================================================
@node System files, , Building and installing tinc, Installation
If "any" is selected, then depending on the operating system
both IPv4 and IPv6 or just IPv6 listening sockets will be created.
-Mixing IPv4 and IPv6 may not work as desired.
-It's best to choose one address family
-and use that for all tinc daemons on the VPN.
-
@cindex BindToInterface
@item BindToInterface = <interface> [experimental]
If you have more than one network interface in your computer, tinc will
This option may not work on all platforms.
-@cindex BindToIP
-@item BindToIP = <address> [experimental]
-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
@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
+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.
@cindex hub
@item hub
-In this mode every packet will be broadcast to the other daemons.
+This mode is almost the same as the switch mode, but instead
+every packet will be broadcast to the other daemons
+while no routing table is managed.
@end table
@cindex KeyExpire
make it even harder for crackers, even though it is thought to be nearly
impossible to crack a single key.
+@cindex MACExpire
+@item MACExpire = <seconds> (600)
+This option controls the amount of time MAC addresses are kept before they are removed.
+This only has effect when Mode is set to "switch".
+
@cindex Name
@item @strong{Name = <name>}
This is a symbolic name for this connection. It can be anything
Furthermore, specifying "none" will turn off packet authentication.
@cindex IndirectData
-@item IndirectData = <yes|no> (no) [experimental]
+@item IndirectData = <yes|no> (no)
This option specifies whether other tinc daemons besides the one you
specified with ConnectTo can make a direct connection to you. This is
especially useful if you are behind a firewall and it is impossible to
connection with that host.
@cindex Subnet
-@item Subnet = <address[/masklength]>
+@item Subnet = <address[/prefixlength]>
The subnet which this tinc daemon will serve.
tinc tries to look up which other daemon it should send a packet to by searching the appropiate subnet.
If the packet matches a subnet,
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.
+or they can be a IPv4 or IPv6 network address with a prefixlength.
+Shorthand notations are not supported.
For example, IPv4 subnets must be in a form like 192.168.1.0/24,
where 192.168.1.0 is the network address and 24 is the number of bits set in the netmask.
Note that subnets like 192.168.1.1/24 are invalid!
+Read a networking HOWTO/FAQ/guide if you don't understand this.
+IPv6 subnets are notated like fec0:0:0:1:0:0:0:0/64.
+MAC addresses are notated like 0:1a:2b:3c:4d:5e.
@cindex CIDR notation
-masklength is the number of bits set to 1 in the netmask part; for
+prefixlength is the number of bits set to 1 in the netmask part; for
example: netmask 255.255.255.0 would become /24, 255.255.252.0 becomes
/22. This conforms to standard CIDR notation as described in
@uref{ftp://ftp.isi.edu/in-notes/rfc1519.txt, RFC1519}
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.
+firewall, or if UDP packet routing is disabled somehow.
Setting this options also implicitly sets IndirectData.
@end table
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.
+However, this might not be reliable. If in doubt, use the name of the interface explicitly.
@cindex ifconfig
The next line gives the interface an IP address and a netmask.
# 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 hw ether fe:fd:0:0:0:0
ifconfig company 10.4.3.32 netmask 255.0.0.0
ifconfig company -arp
@end example
@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}.
+@item -k, --kill[=SIGNAL]
+Attempt to kill a running tincd (optionally with the specified SIGNAL instead of SIGTERM) and exit.
Use it in conjunction with the -n option to make sure you kill the right tinc daemon.
@item -n, --net=NETNAME
@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
+you have a Subnet line in your host configuration file with a prefix length which is
+just as large as the prefix of the virtual network interface. The latter should in almost all
cases be larger. Rethink your configuration.
Note that you will only see this message if you specified a debug
level of 5 or higher!
@item Add the `ifconfig $INTERFACE -arp' to tinc-up.
@end itemize
-@item Network address and subnet mask do not match!
+@item Network address and prefix length do not match!
@itemize
@item The Subnet field must contain a @emph{network} address.
+------------------> name of node on one side of the edge
origin ADD_SUBNET node 192.168.1.0/24
- | | +--> masklength
+ | | +--> prefixlength
| +--------> IPv4 network address
+------------------> owner of this subnet
--------------------------------------------------------------------------
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.
+tinc by default uses blowfish encryption with 128 bit keys in CBC mode, 32 bit
+sequence numbers and 4 byte long message authentication codes to make sure
+eavesdroppers cannot get and cannot change any information at all from the
+packets they can intercept. The encryption algorithm and message authentication
+algorithm can be changed in the configuration. The length of the message
+authentication codes is also adjustable. The length of the key for the
+encryption algorithm is always the default length used by OpenSSL.
@menu
* Authentication protocol::
projects / tinc / blobdiff