X-Git-Url: https://tinc-vpn.org/git/browse?a=blobdiff_plain;f=doc%2Ftinc.texi;h=e9534728fdff9d1ae7c42542645dcdcb8df1a352;hb=1065879c8c6e8cdf8d3755024241f31eaabd4138;hp=e02b6a24bdd822615aab1e40bc168d7f164ff341;hpb=df3220a1549f992cbf4a9b6e67c1e67b69896c7d;p=tinc diff --git a/doc/tinc.texi b/doc/tinc.texi index e02b6a24..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-2005 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-2005 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:: @@ -389,6 +390,7 @@ having them installed, configure will give you an error message, and stop. * OpenSSL:: * zlib:: * lzo:: +* libevent:: @end menu @@ -501,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 @@ -841,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. @@ -933,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] @@ -954,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 @@ -1026,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 @@ -1101,6 +1119,12 @@ 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. @@ -1197,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. @@ -1426,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}, @@ -1492,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. @@ -1515,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. @@ -1556,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 ================================================================== @@ -1759,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