Purge through the control socket

[tinc] / doc / tinc.texi

diff --git a/doc/tinc.texi b/doc/tinc.texi
index 7bea5eb..e953472 100644 (file)
--- 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.
 
 
 This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
 

-Copyright @copyright{} 1998-2004 Ivo Timmermans
-<ivo@@tinc-vpn.org>, Guus Sliepen <guus@@tinc-vpn.org> and
+Copyright @copyright{} 1998-2006 Ivo Timmermans,
+Guus Sliepen <guus@@tinc-vpn.org> and

 Wessel Dankers <wsl@@tinc-vpn.org>.
 
 $Id$
 Wessel Dankers <wsl@@tinc-vpn.org>.
 
 $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.
 
 @cindex copyright
 This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
 

-Copyright @copyright{} 1998-2004 Ivo Timmermans
-<ivo@@tinc-vpn.org>, Guus Sliepen <guus@@tinc-vpn.org> and
+Copyright @copyright{} 1998-2007 Ivo Timmermans,
+Guus Sliepen <guus@@tinc-vpn.org> and

 Wessel Dankers <wsl@@tinc-vpn.org>.
 
 $Id$
 Wessel Dankers <wsl@@tinc-vpn.org>.
 
 $Id$


@@ -71,6 +71,7 @@ permission notice identical to this one.
 * Installation::
 * Configuration::
 * Running tinc::
 * Installation::
 * Configuration::
 * Running tinc::

+* Controlling tinc::

 * Technical information::
 * Platform specific information::
 * About us::
 * 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::
 * OpenSSL::
 * zlib::
 * lzo::

+* libevent::

 @end menu
 
 
 @end menu
 
 


@@ -501,6 +503,27 @@ make sure you build development and runtime libraries (which is the
 default).
 
 
 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
 @c
 @c
 @c


@@ -841,15 +864,6 @@ variable.
 
 This option may not work on all platforms.
 
 
 This option may not work on all platforms.
 

-@cindex BlockingTCP
-@item BlockingTCP = <yes|no> (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.
 @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
 
 @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
 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 = <yes|no> (no) [experimental]
 
 @cindex PriorityInheritance
 @item PriorityInheritance = <yes|no> (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
 @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
 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
 @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
 directory.
 
 @cindex PEM format


@@ -1100,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}/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
 @end table
 
 @cindex environment variables


@@ -1129,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.
 @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
 
 @cindex REMOTEADDRESS
 @item REMOTEADDRESS


@@ -1138,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.
 @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
 
 
 @end table
 
 


@@ -1184,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
 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.
 @end example
 
 Tinc will generate a public and a private key and ask you where to put them.


@@ -1413,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
 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},
 @end example
 
 The private key is stored in @file{@value{sysconfdir}/tinc/company/rsa_key.priv},


@@ -1479,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.
 
 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 -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.
 
 @item -L, --mlock
 Lock tinc into main memory.


@@ -1502,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}.
 
 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 --bypass-security
 Disables encryption and authentication.
 Only useful for debugging.


@@ -1543,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.
 
 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 ==================================================================
 @end table
 
 @c ==================================================================


@@ -1746,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
 
 @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
 @c ==================================================================
 @node    Technical information
 @chapter Technical information