X-Git-Url: https://tinc-vpn.org/git/browse?a=blobdiff_plain;f=doc%2Ftinc.texi;h=e9534728fdff9d1ae7c42542645dcdcb8df1a352;hb=1065879c8c6e8cdf8d3755024241f31eaabd4138;hp=c31885dfd7ffe4619fab33d92ef6d2a256a0b870;hpb=2369b0ab09a008c519cd4307b634fd294c66014e;p=tinc diff --git a/doc/tinc.texi b/doc/tinc.texi index c31885df..e9534728 100644 --- a/doc/tinc.texi +++ b/doc/tinc.texi @@ -16,8 +16,8 @@ This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon. -Copyright @copyright{} 1998-2004 Ivo Timmermans -, Guus Sliepen and +Copyright @copyright{} 1998-2006 Ivo Timmermans, +Guus Sliepen and Wessel Dankers . $Id$ @@ -43,8 +43,8 @@ permission notice identical to this one. @cindex copyright This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon. -Copyright @copyright{} 1998-2004 Ivo Timmermans -, Guus Sliepen and +Copyright @copyright{} 1998-2007 Ivo Timmermans, +Guus Sliepen and Wessel Dankers . $Id$ @@ -71,6 +71,7 @@ permission notice identical to this one. * Installation:: * Configuration:: * Running tinc:: +* Controlling tinc:: * Technical information:: * Platform specific information:: * About us:: @@ -194,84 +195,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. -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. - -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 may 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). - -@c ================================================================== -@subsection Darwin (MacOS/X) - -@cindex Darwin -@cindex MacOS/X -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. - -@c ================================================================== -@subsection Windows - -@cindex Windows -Tinc on Windows relies on the TAP-Win32 driver (as shipped by OpenVPN) for its data acquisition from the kernel. -This driver is not part of Windows but can be downloaded from @uref{http://openvpn.sourceforge.net/}. - - @c @c @c @@ -302,26 +225,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 +241,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 +281,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 +313,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 +323,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 +335,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,18 +353,17 @@ 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 @@ -478,6 +390,7 @@ having them installed, configure will give you an error message, and stop. * OpenSSL:: * zlib:: * lzo:: +* libevent:: @end menu @@ -590,6 +503,27 @@ make sure you build development and runtime libraries (which is the default). +@c ================================================================== +@node libevent +@subsection libevent + +@cindex libevent +For the main event loop, tinc uses the libevent library. + +If this library is not installed, you wil get an error when configuring +tinc for build. + +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 libevent manually, you can get the source code +from @url{http://monkey.org/~provos/libevent/}. 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 @@ -930,15 +864,6 @@ 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. @@ -1022,12 +947,16 @@ This only has effect when Mode is set to "switch". @item Name = <@var{name}> [required] This is a symbolic name for this connection. It can be anything -@cindex PingTimeout -@item PingTimeout = <@var{seconds}> (60) +@cindex PingInterval +@item PingInterval = <@var{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. +probe to the other end. + +@cindex PingTimeout +@item PingTimeout = <@var{seconds}> (5) +The number of seconds to wait for a response to pings or to allow meta +connections to block. If the other end doesn't respond within this time, +the connection is terminated, and the others will be notified of this. @cindex PriorityInheritance @item PriorityInheritance = (no) [experimental] @@ -1043,7 +972,7 @@ accidental eavesdropping if you are editting the configuration file. @cindex PrivateKeyFile @item PrivateKeyFile = <@var{path}> (@file{@value{sysconfdir}/tinc/@var{netname}/rsa_key.priv}) This is the full path name of the RSA private key file that was -generated by @samp{tincd --generate-keys}. It must be a full path, not a +generated by @samp{tincctl generate-keys}. It must be a full path, not a relative directory. Note that there must be exactly one of PrivateKey @@ -1115,7 +1044,7 @@ This is the RSA public key for this host. @cindex PublicKeyFile @item PublicKeyFile = <@var{path}> [obsolete] This is the full path name of the RSA public key file that was generated -by @samp{tincd --generate-keys}. It must be a full path, not a relative +by @samp{tincctl generate-keys}. It must be a full path, not a relative directory. @cindex PEM format @@ -1189,6 +1118,19 @@ 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}/host-up +This script is started when any host becomes reachable. + +@item @value{sysconfdir}/tinc/@var{netname}/host-down +This script is started when any 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 @@ -1218,6 +1160,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 @@ -1227,6 +1170,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 @@ -1273,7 +1221,7 @@ Now that you have already created the main configuration file and your host conf you can easily create a public/private keypair by entering the following command: @example -tincd -n @var{netname} -K +tincctl -n @var{netname} generate-keys @end example Tinc will generate a public and a private key and ask you where to put them. @@ -1502,7 +1450,7 @@ Address = 4.5.6.7 A, B, C and D all have generated a public/private keypair with the following command: @example -tincd -n company -K +tincctl -n company generate-keys @end example The private key is stored in @file{@value{sysconfdir}/tinc/company/rsa_key.priv}, @@ -1568,20 +1516,12 @@ This will also disable the automatic restart mechanism for fatal errors. Set debug level to @var{level}. The higher the debug level, the more gets logged. Everything goes via syslog. -@item -k, --kill[=@var{signal}] -Attempt to kill a running tincd (optionally with the specified @var{signal} instead of SIGTERM) and exit. -Use it in conjunction with the -n option to make sure you kill the right tinc daemon. -Under native Windows the optional argument is ignored, -the service will always be stopped and removed. - @item -n, --net=@var{netname} Use configuration for net @var{netname}. @xref{Multiple networks}. -@item -K, --generate-keys[=@var{bits}] -Generate public/private keypair of @var{bits} length. If @var{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 --controlsocket=@var{filename} +Open control socket at @var{filename}. If unspecified, the default is +@file{@value{localstatedir}/run/tinc.@var{netname}.control}. @item -L, --mlock Lock tinc into main memory. @@ -1591,9 +1531,6 @@ This will prevent sensitive data like shared private keys to be written to the s Write log entries to a file instead of to the system logging facility. If @var{file} is omitted, the default is @file{@value{localstatedir}/log/tinc.@var{netname}.log}. -@item --pidfile=@var{file} -Write PID to @var{file} instead of @file{@value{localstatedir}/run/tinc.@var{netname}.pid}. - @item --bypass-security Disables encryption and authentication. Only useful for debugging. @@ -1632,15 +1569,6 @@ New outgoing connections specified in @file{tinc.conf} will be made. 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 ================================================================== @@ -1835,6 +1763,100 @@ Be sure to include the following information in your bugreport: @item The output of any command that fails to work as it should (like ping or traceroute). @end itemize +@c ================================================================== +@node Controlling tinc +@chapter Controlling tinc + +You can control and inspect a running @samp{tincd} through the @samp{tincctl} +command. A quick example: + +@example +tincctl -n @var{netname} reload +@end example + +@menu +* tincctl runtime options:: +* tincctl commands:: +@end menu + + +@c ================================================================== +@node tincctl runtime options +@section tincctl runtime options + +@c from the manpage +@table @option +@item -c, --config=@var{path} +Read configuration options from the directory @var{path}. The default is +@file{@value{sysconfdir}/tinc/@var{netname}/}. + +@item -n, --net=@var{netname} +Use configuration for net @var{netname}. @xref{Multiple networks}. + +@item --controlsocket=@var{filename} +Open control socket at @var{filename}. If unspecified, the default is +@file{@value{localstatedir}/run/tinc.@var{netname}.control}. + +@item --help +Display a short reminder of runtime options and commands, then terminate. + +@item --version +Output version information and exit. + +@end table + + +@c ================================================================== +@node tincctl commands +@section tincctl commands + +@c from the manpage +@table @code + +@item start +Start @samp{tincd}. + +@item stop +Stop @samp{tincd}. + +@item restart +Restart @samp{tincd}. + +@item reload +Partially rereads configuration files. Connections to hosts whose host +config files are removed are closed. New outgoing connections specified +in @file{tinc.conf} will be made. + +@item pid +Shows the PID of the currently running @samp{tincd}. + +@item generate-keys [@var{bits}] +Generate public/private keypair of @var{bits} length. If @var{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). + +@item dump nodes +Dump a list of all known nodes in the VPN. + +@item dump edges +Dump a list of all known connections in the VPN. + +@item dump subnets +Dump a list of all known subnets in the VPN. + +@item dump connections +Dump a list of all meta connections with ourself. + +@item dump graph +Dump a graph of the VPN in dotty format. + +@item purge +Purges all information remembered about unreachable nodes. + +@end table + + @c ================================================================== @node Technical information @chapter Technical information