X-Git-Url: https://tinc-vpn.org/git/browse?p=tinc;a=blobdiff_plain;f=doc%2Ftinc.texi;h=5bd4c6c2a4524ee4025f69b6afd8048572811fdd;hp=a178849eaf82bc0983add1965c019ec577c9030c;hb=54a30e30ad41d7c0e73fcc4e6ff23c3e85af75c4;hpb=7926a156e5b118d06295228e57de0cc9de0433b4 diff --git a/doc/tinc.texi b/doc/tinc.texi index a178849e..5bd4c6c2 100644 --- a/doc/tinc.texi +++ b/doc/tinc.texi @@ -194,84 +194,6 @@ For an up to date list of supported platforms, please check the list on our website: @uref{http://www.tinc-vpn.org/platforms}. - -@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. - -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. It has been verified to work under 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 ================================================================== -@subsection Windows - -@cindex Windows -Tinc on Windows, in a Cygwin environment, relies on the CIPE driver or the TAP-Win32 driver for its data -acquisition from the kernel. This driver is not part of Windows but can be -downloaded from @uref{http://cipe-win32.sourceforge.net/}. - - @c @c @c @@ -302,26 +224,6 @@ support tinc. @node Configuring the kernel @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:: @@ -338,7 +240,10 @@ you should read the @uref{http://howto.linuxberg.com/LDP/HOWTO/Kernel-HOWTO.html @node Configuration of Linux kernels 2.1.60 up to 2.4.0 @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: +@cindex ethertap +For kernels up to 2.4.0, you need a kernel that supports the ethertap device. +Most distributions come with kernels that already support this. +If not, here are the options you have to turn on when configuring a new kernel: @example Code maturity level options @@ -375,6 +280,9 @@ Add as much alias/options lines as necessary. @node Configuration of Linux kernels 2.4.0 and higher @subsection Configuration of Linux kernels 2.4.0 and higher +@cindex Universal tun/tap +For kernels 2.4.0 and higher, you need a kernel that supports the Universal tun/tap device. +Most distributions come with kernels that already support this. Here are the options you have to turn on when configuring a new kernel: @example @@ -404,9 +312,8 @@ alias char-major-10-200 tun @node Configuration of FreeBSD kernels @subsection Configuration of FreeBSD kernels -For FreeBSD version 4.1 and higher, the tap driver is included in the default kernel configuration, for earlier -systems (4.0 and earlier), you need to install the universal tun/tap driver -yourself. +For FreeBSD version 4.1 and higher, tun and tap drivers are included in the default kernel configuration. +Using tap devices is recommended. @c ================================================================== @@ -415,6 +322,9 @@ yourself. For OpenBSD version 2.9 and higher, the tun driver is included in the default kernel configuration. +There is also a kernel patch from @uref{http://diehard.n-r-g.com/stuff/openbsd/} +which adds a tap device to OpenBSD. +This should work with tinc. @c ================================================================== @@ -424,6 +334,8 @@ the tun driver is included in the default kernel configuration. For NetBSD version 1.5.2 and higher, the tun driver is included in the default kernel configuration. +Tunneling IPv6 may not work on NetBSD's tun device. + @c ================================================================== @node Configuration of Solaris kernels @@ -440,28 +352,27 @@ If the @file{net/if_tun.h} header file is missing, install it from the source pa @node Configuration of Darwin (MacOS/X) kernels @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: +Tinc on Darwin relies on a tunnel driver for its data acquisition from the kernel. +Tinc supports either the driver from @uref{http://www-user.rhrk.uni-kl.de/~nissler/tuntap/}, +which supports both tun and tap style devices, +and also the driver from from @uref{http://chrisp.de/en/projects/tunnel.html}. +The former driver is recommended. +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 Configuration of Windows @subsection Configuration of Windows -You will need to install the CIPE-Win32 driver or the TAP-Win32 driver, it -doesn't matter which one. You can download the CIPE driver from -@uref{http://cipe-win32.sourceforge.net}. Using the Network Connections -control panel, configure the CIPE-Win32 or TAP-Win32 network interface in the same way as you would -do from the tinc-up script as explained in the rest of the documentation. +You will need to install the latest TAP-Win32 driver from OpenVPN. +You can download it from @uref{http://openvpn.sourceforge.net}. +Using the Network Connections control panel, +configure the TAP-Win32 network interface in the same way as you would do from the tinc-up script, +as explained in the rest of the documentation. @c ================================================================== @@ -930,6 +841,15 @@ variable. This option may not work on all platforms. +@cindex BlockingTCP +@item BlockingTCP = (no) [experimental] +This options selects whether TCP connections, when established, should use blocking writes. +When turned off, tinc will never block when a TCP connection becomes congested, +but will have to terminate that connection instead. +If turned on, tinc will not terminate connections but will block, +thereby unable to process data to/from other connections. +Turn this option on if you also use TCPOnly and tinc terminates connections frequently. + @cindex ConnectTo @item ConnectTo = <@var{name}> Specifies which other tinc daemon to connect to on startup. @@ -1041,6 +961,12 @@ Note that there must be exactly one of PrivateKey or PrivateKeyFile specified in the configuration file. +@cindex TunnelServer +@item TunnelServer = (no) [experimental] +When this option is enabled tinc will no longer forward information between other tinc daemons, +and will only allow nodes and subnets on the VPN which are present in the +@file{@value{sysconfdir}/tinc/@var{netname}/hosts/} directory. + @end table @@ -1131,7 +1057,7 @@ 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 -prefixlength 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} @@ -1174,6 +1100,13 @@ This script is started when the tinc daemon with name @var{host} becomes reachab @item @value{sysconfdir}/tinc/@var{netname}/hosts/@var{host}-down This script is started when the tinc daemon with name @var{host} becomes unreachable. + +@item @value{sysconfdir}/tinc/@var{netname}/subnet-up +This script is started when a Subnet becomes reachable. +The Subnet and the node it belongs to are passed in environment variables. + +@item @value{sysconfdir}/tinc/@var{netname}/subnet-down +This script is started when a Subnet becomes unreachable. @end table @cindex environment variables @@ -1203,6 +1136,7 @@ This should be used for commands like ifconfig. @cindex NODE @item NODE When a host becomes (un)reachable, this is set to its name. +If a subnet becomes (un)reachable, this is set to the owner of that subnet. @cindex REMOTEADDRESS @item REMOTEADDRESS @@ -1212,6 +1146,11 @@ When a host becomes (un)reachable, this is set to its real address. @item REMOTEPORT When a host becomes (un)reachable, this is set to the port number it uses for communication with other tinc daemons. + +@cindex SUBNET +@item SUBNET +When a subnet becomes (un)reachable, this is set to the subnet. + @end table @@ -1356,7 +1295,6 @@ and in @file{@value{sysconfdir}/tinc/company/tinc.conf}: @example Name = BranchA -PrivateKeyFile = @value{sysconfdir}/tinc/company/rsa_key.priv Device = /dev/tap0 @end example @@ -1393,7 +1331,6 @@ and in @file{@value{sysconfdir}/tinc/company/tinc.conf}: @example Name = BranchB ConnectTo = BranchA -PrivateKeyFile = @value{sysconfdir}/tinc/company/rsa_key.priv @end example Note here that the internal address (on eth0) doesn't have to be the @@ -1465,7 +1402,6 @@ and in @file{@value{sysconfdir}/tinc/company/tinc.conf}: Name = BranchD ConnectTo = BranchC Device = /dev/net/tun -PrivateKeyFile = @value{sysconfdir}/tinc/company/rsa_key.priv @end example D will be connecting to C, which has a tincd running for this network on @@ -1523,6 +1459,8 @@ and look in the syslog to find out what the problems are. @menu * Runtime options:: +* Signals:: +* Debug levels:: * Solving problems:: * Error messages:: * Sending bug reports:: @@ -1592,6 +1530,77 @@ Output version information and exit. @end table +@c ================================================================== +@node Signals +@section Signals + +@cindex signals +You can also send the following signals to a running tincd process: + +@c from the manpage +@table @samp + +@item ALRM +Forces tinc to try to connect to all uplinks immediately. +Usually tinc attempts to do this itself, +but increases the time it waits between the attempts each time it failed, +and if tinc didn't succeed to connect to an uplink the first time after it started, +it defaults to the maximum time of 15 minutes. + +@item HUP +Partially rereads configuration files. +Connections to hosts whose host config file are removed are closed. +New outgoing connections specified in @file{tinc.conf} will be made. + +@item INT +Temporarily increases debug level to 5. +Send this signal again to revert to the original level. + +@item USR1 +Dumps the connection list to syslog. + +@item USR2 +Dumps virtual network device statistics, all known nodes, edges and subnets to syslog. + +@item WINCH +Purges all information remembered about unreachable nodes. + +@end table + +@c ================================================================== +@node Debug levels +@section Debug levels + +@cindex debug levels +The tinc daemon can send a lot of messages to the syslog. +The higher the debug level, the more messages it will log. +Each level inherits all messages of the previous level: + +@c from the manpage +@table @samp + +@item 0 +This will log a message indicating tinc has started along with a version number. +It will also log any serious error. + +@item 1 +This will log all connections that are made with other tinc daemons. + +@item 2 +This will log status and error messages from scripts and other tinc daemons. + +@item 3 +This will log all requests that are exchanged with other tinc daemons. These include +authentication, key exchange and connection list updates. + +@item 4 +This will log a copy of everything received on the meta socket. + +@item 5 +This will log all network traffic over the virtual private network. + +@end table + @c ================================================================== @node Solving problems @section Solving problems @@ -1893,21 +1902,21 @@ synchronised. @cindex ADD_EDGE @cindex ADD_SUBNET @example -daemon message --------------------------------------------------------------------------- -origin ADD_EDGE node1 node2 21.32.43.54 655 222 0 - | | | | | +-> options - | | | | +----> weight - | | | +--------> UDP port of node2 - | | +----------------> real address of node2 - | +-------------------------> name of destination node - +-------------------------------> name of source node - -origin ADD_SUBNET node 192.168.1.0/24 - | | +--> prefixlength - | +--------> network address - +------------------> owner of this subnet --------------------------------------------------------------------------- +message +------------------------------------------------------------------ +ADD_EDGE node1 node2 21.32.43.54 655 222 0 + | | | | | +-> options + | | | | +----> weight + | | | +--------> UDP port of node2 + | | +----------------> real address of node2 + | +-------------------------> name of destination node + +-------------------------------> name of source node + +ADD_SUBNET node 192.168.1.0/24 + | | +--> prefixlength + | +--------> network address + +------------------> owner of this subnet +------------------------------------------------------------------ @end example The ADD_EDGE messages are to inform other tinc daemons that a connection between @@ -1924,7 +1933,7 @@ to be sent. message ------------------------------------------------------------------ DEL_EDGE node1 node2 - | +----> name of destination node + | +----> name of destination node +----------> name of source node DEL_SUBNET node 192.168.1.0/24 @@ -1958,7 +1967,7 @@ ANS_KEY origin destination 4ae0b0a82d6e0078 91 64 4 KEY_CHANGED origin +--> daemon that has changed it's packet key --------------------------------------------------------------------------- +------------------------------------------------------------------ @end example The keys used to encrypt VPN packets are not sent out directly. This is @@ -1972,10 +1981,10 @@ destination. @cindex PONG @example daemon message --------------------------------------------------------------------------- +------------------------------------------------------------------ origin PING dest. PONG --------------------------------------------------------------------------- +------------------------------------------------------------------ @end example There is also a mechanism to check if hosts are still alive. Since network @@ -2247,7 +2256,9 @@ For IPv6 addresses: @item NetBSD @tab @code{ifconfig} @var{interface} @code{inet6} @var{address} @code{prefixlen} @var{prefixlength} @item Solaris -@tab @code{ifconfig} @var{interface} @code{inet6 addif} @var{address}@code{/}@var{prefixlength} +@tab @code{ifconfig} @var{interface} @code{inet6 plumb up} +@item +@tab @code{ifconfig} @var{interface} @code{inet6 addif} @var{address} @var{address} @item Darwin (MacOS/X) @tab @code{ifconfig} @var{interface} @code{inet6} @var{address} @code{prefixlen} @var{prefixlength} @item Windows @@ -2280,9 +2291,11 @@ Adding routes to IPv4 subnets: @item NetBSD @tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @var{local_address} @item Solaris +@tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @var{local_address} @code{-interface} @item Darwin (MacOS/X) @tab @code{route add} @var{network_address}@code{/}@var{prefixlength} @var{local_address} @item Windows +@tab @code{netsh routing ip add persistentroute} @var{network_address} @var{netmask} @var{interface} @var{local_address} @end multitable Adding routes to IPv6 subnets: @@ -2292,10 +2305,16 @@ Adding routes to IPv6 subnets: @tab @code{route add -A inet6} @var{network_address}@code{/}@var{prefixlength} @var{interface} @item Linux iproute2 @tab @code{ip route add} @var{network_address}@code{/}@var{prefixlength} @code{dev} @var{interface} +@item FreeBSD +@tab @code{route add -inet6} @var{network_address}@code{/}@var{prefixlength} @var{local_address} @item OpenBSD +@tab @code{route add -inet6} @var{network_address} @var{local_address} @code{-prefixlen} @var{prefixlength} @item NetBSD +@tab @code{route add -inet6} @var{network_address} @var{local_address} @code{-prefixlen} @var{prefixlength} @item Solaris +@tab @code{route add -inet6} @var{network_address}@code{/}@var{prefixlength} @var{local_address} @code{-interface} @item Darwin (MacOS/X) +@tab ? @item Windows @tab @code{netsh interface ipv6 add route} @var{network address}/@var{prefixlength} @var{interface} @end multitable