+@c ==================================================================
+@node Controlling tinc
+@chapter Controlling tinc
+
+You can control and inspect a running tincd through the tincctl
+command. A quick example:
+
+@example
+tincctl -n @var{netname} reload
+@end example
+
+@menu
+* tincctl runtime options::
+* tincctl environment variables::
+* tincctl commands::
+* tincctl examples::
+* tincctl top::
+@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 --pidfile=@var{filename}
+Use the cookie from @var{filename} to authenticate with a running tinc daemon.
+If unspecified, the default is
+@file{@value{localstatedir}/run/tinc.@var{netname}.pid}.
+
+@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 environment variables
+@section tincctl environment variables
+
+@table @env
+@cindex NETNAME
+@item NETNAME
+If no netname is specified on the command line with the @option{-n} option,
+the value of this environment variable is used.
+@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.
+
+@item disconnect @var{node}
+Closes the meta connection with the given @var{node}.
+
+@item top
+If tincctl is compiled with libcurses support, this will display live traffic statistics for all the known nodes,
+similar to the UNIX top command.
+See below for more information.
+
+@item pcap
+Dump VPN traffic going through the local tinc node in pcap-savefile format to standard output,
+from where it can be redirected to a file or piped through a program that can parse it directly,
+such as tcpdump.
+
+@end table
+
+@c ==================================================================
+@node tincctl examples
+@section tincctl examples
+
+Examples of some commands:
+
+@example
+tincctl -n vpn dump graph | circo -Txlib
+tincctl -n vpn pcap | tcpdump -r -
+tincctl -n vpn top
+@end example
+
+@c ==================================================================
+@node tincctl top
+@section tincctl top
+
+The top command connects to a running tinc daemon and repeatedly queries its per-node traffic counters.
+It displays a list of all the known nodes in the left-most column,
+and the amount of bytes and packets read from and sent to each node in the other columns.
+By default, the information is updated every second.
+The behaviour of the top command can be changed using the following keys:
+
+@table @key
+
+@item s
+Change the interval between updates.
+After pressing the @key{s} key, enter the desired interval in seconds, followed by enter.
+Fractional seconds are honored.
+Intervals lower than 0.1 seconds are not allowed.
+
+@item c
+Toggle between displaying current traffic rates (in packets and bytes per second)
+and cummulative traffic (total packets and bytes since the tinc daemon started).
+
+@item n
+Sort the list of nodes by name.
+
+@item i
+Sort the list of nodes by incoming amount of bytes.
+
+@item I
+Sort the list of nodes by incoming amount of packets.
+
+@item o
+Sort the list of nodes by outgoing amount of bytes.
+
+@item O
+Sort the list of nodes by outgoing amount of packets.
+
+@item t
+Sort the list of nodes by sum of incoming and outgoing amount of bytes.
+
+@item T
+Sort the list of nodes by sum of incoming and outgoing amount of packets.
+
+@item b
+Show amount of traffic in bytes.
+
+@item k
+Show amount of traffic in kilobytes.
+
+@item M
+Show amount of traffic in megabytes.
+
+@item G
+Show amount of traffic in gigabytes.
+
+@item q
+Quit.
+
+@end table
+
+