\input texinfo @c -*-texinfo-*-
-@c $Id$
@c %**start of header
@setfilename tinc.info
@settitle tinc Manual
This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
-Copyright @copyright{} 1998-2008 Ivo Timmermans,
+Copyright @copyright{} 1998-2009 Ivo Timmermans,
Guus Sliepen <guus@@tinc-vpn.org> and
Wessel Dankers <wsl@@tinc-vpn.org>.
-$Id$
-
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.
@cindex copyright
This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
-Copyright @copyright{} 1998-2006 Ivo Timmermans,
+Copyright @copyright{} 1998-2009 Ivo Timmermans,
Guus Sliepen <guus@@tinc-vpn.org> and
Wessel Dankers <wsl@@tinc-vpn.org>.
-$Id$
-
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.
* Installation::
* Configuration::
* Running tinc::
+* Controlling tinc::
* Technical information::
* Platform specific information::
* About us::
@subsection Configuration of Darwin (MacOS/X) kernels
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/},
+Tinc supports either the driver from @uref{http://tuntaposx.sourceforge.net/},
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.
* OpenSSL::
* zlib::
* lzo::
+* libevent::
@end menu
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
@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
or PrivateKeyFile
specified in the configuration file.
+@cindex ProcessPriority
+@item ProcessPriority = <low|normal|high>
+When this option is used the priority of the tincd process will be adjusted.
+Increasing the priority may help to reduce latency and packet loss on the VPN.
+
@cindex TunnelServer
@item TunnelServer = <yes|no> (no) [experimental]
When this option is enabled tinc will no longer forward information between other tinc daemons,
@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
connection with that host.
@cindex Subnet
-@item Subnet = <@var{address}[/@var{prefixlength}]>
+@item Subnet = <@var{address}[/@var{prefixlength}[#@var{weight}]]>
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,
/22. This conforms to standard CIDR notation as described in
@uref{ftp://ftp.isi.edu/in-notes/rfc1519.txt, RFC1519}
+A Subnet can be given a weight to indicate its priority over identical Subnets
+owned by different nodes. The default weight is 10. Lower values indicate
+higher priority. Packets will be sent to the node with the highest priority,
+unless that node is not reachable, in which case the node with the next highest
+priority will be tried, and so on.
+
@cindex TCPonly
@item TCPonly = <yes|no> (no)
If this variable is set to yes, then the packets are tunnelled over a
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.
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},
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.
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.
+@item -R, --chroot
+Change process root directory to the directory where the config file is
+located (@file{@value{sysconfdir}/tinc/@var{netname}/} as determined by
+-n/--net option or as given by -c/--config option), for added security.
+The chroot is performed after all the initialization is done, after
+writing pid files and opening network sockets.
+
+Note that this option alone does not do any good without -U/--user, below.
+
+Note also that tinc can't run scripts anymore (such as tinc-down or host-up),
+unless it's setup to be runnable inside chroot environment.
+
+@item -U, --user=@var{user}
+Switch to the given @var{user} after initialization, at the same time as
+chroot is performed (see --chroot above). With this option tinc drops
+privileges, for added security.
+
@item --help
Display a short reminder of these runtime options and terminate.
@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 ==================================================================
@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.
+
+@item debug @var{level}
+Sets debug level to @var{level}.
+
+@item retry
+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.
+
+@end table
+
+
@c ==================================================================
@node Technical information
@chapter Technical information
@section Authors
@table @asis
-@item Ivo Timmermans (zarq) (@email{ivo@@tinc-vpn.org})
+@item Ivo Timmermans (zarq)
@item Guus Sliepen (guus) (@email{guus@@tinc-vpn.org})
@end table