From e8deda0b23463599a7533e82cf038a01062956a7 Mon Sep 17 00:00:00 2001 From: Guus Sliepen Date: Sat, 25 Jun 2011 14:52:47 +0200 Subject: [PATCH] Update manpages and info manual. --- doc/tinc.texi | 103 +++++++++++++++++++++++++++++++++++++++++++---- doc/tincctl.8.in | 91 ++++++++++++++++++++++++++++++++++------- doc/tincd.8.in | 13 +++--- 3 files changed, 181 insertions(+), 26 deletions(-) diff --git a/doc/tinc.texi b/doc/tinc.texi index 7878db56..c5956d9a 100644 --- a/doc/tinc.texi +++ b/doc/tinc.texi @@ -1581,9 +1581,10 @@ This will let tinc read all configuration files from Specifying . for @var{netname} is the same as not specifying any @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 --controlcookie=@var{filename} +Store a cookie in @var{filename} which allows tincctl to authenticate. +If unspecified, the default is +@file{@value{localstatedir}/run/tinc.@var{netname}.cookie}. @item -L, --mlock Lock tinc into main memory. @@ -1837,7 +1838,7 @@ Be sure to include the following information in your bugreport: @node Controlling tinc @chapter Controlling tinc -You can control and inspect a running @samp{tincd} through the @samp{tincctl} +You can control and inspect a running tincd through the tincctl command. A quick example: @example @@ -1847,6 +1848,8 @@ tincctl -n @var{netname} reload @menu * tincctl runtime options:: * tincctl commands:: +* tincctl examples:: +* tincctl top:: @end menu @@ -1863,9 +1866,10 @@ Read configuration options from the directory @var{path}. The default is @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 --controlcookie=@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}.cookie}. @item --help Display a short reminder of runtime options and commands, then terminate. @@ -1934,6 +1938,91 @@ 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, ESC +Quit. + @end table diff --git a/doc/tincctl.8.in b/doc/tincctl.8.in index 493adfd0..6b550ae8 100644 --- a/doc/tincctl.8.in +++ b/doc/tincctl.8.in @@ -1,4 +1,4 @@ -.Dd 2007-07-20 +.Dd 2011-06-25 .Dt TINCCTL 8 .\" Manual page created by: .\" Scott Lamb @@ -10,7 +10,7 @@ .Op Fl cn .Op Fl -config Ns = Ns Ar DIR .Op Fl -net Ns = Ns Ar NETNAME -.Op Fl -controlsocket Ns = Ns Ar FILENAME +.Op Fl -controlcookie Ns = Ns Ar FILENAME .Op Fl -help .Op Fl -version .Ar COMMAND @@ -26,11 +26,12 @@ to alter and inspect the running VPN's state. .It Fl n, -net Ns = Ns Ar NETNAME Communicate with tincd(8) connected with .Ar NETNAME . -.It Fl -controlsocket Ns = Ns Ar FILENAME -Open control socket at -.Ar FILENAME . +.It Fl -controlcookie Ns = Ns Ar FILENAME +Use the cookie from +.Ar FILENAME +to authenticate with a running tinc daemon. If unspecified, the default is -.Pa @localstatedir@/run/tinc. Ns Ar NETNAME Ns Pa .control. +.Pa @localstatedir@/run/tinc. Ns Ar NETNAME Ns Pa .cookie. .It Fl -help Display short list of options. .It Fl -version @@ -93,21 +94,83 @@ and if .Xr tincd 8 didn't succeed to connect to an uplink the first time after it started, it defaults to the maximum time of 15 minutes. -.It reload -Partially rereads configuration files. -Connections to hosts whose host config files are removed are closed. -New outgoing connections specified in -.Pa tinc.conf -will be made. +.It disconnect Ar NODE +Closes the meta connection with the given +.Ar NODE . +.It top +If +.Nm +is compiled with libcurses support, this will display live traffic statistics +for all the known nodes, similar to the UNIX +.Xr top 1 +command. +See below for more information. +.It pcap +Dump VPN traffic going through the local tinc node in +.Xr pcap-savefile 5 +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 +.Xr tcpdump 8 . +.El +.Sh EXAMPLES +Examples of some commands: +.Bd -literal -offset indent +tincctl -n vpn dump graph | circo -Txlib +tincctl -n vpn pcap | tcpdump -r - +tincctl -n vpn top +.Ed +.Sh 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: +.Bl -tag +.It Ic s +Change the interval between updates. +After pressing the +.Ic s +key, enter the desired interval in seconds, followed by enter. +Fractional seconds are honored. +Intervals lower than 0.1 seconds are not allowed. +.It Ic 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). +.It Ic n +Sort the list of nodes by name. +.It Ic i +Sort the list of nodes by incoming amount of bytes. +.It Ic I +Sort the list of nodes by incoming amount of packets. +.It Ic o +Sort the list of nodes by outgoing amount of bytes. +.It Ic O +Sort the list of nodes by outgoing amount of packets. +.It Ic t +Sort the list of nodes by sum of incoming and outgoing amount of bytes. +.It Ic T +Sort the list of nodes by sum of incoming and outgoing amount of packets. +.It Ic b +Show amount of traffic in bytes. +.It Ic k +Show amount of traffic in kilobytes. +.It Ic M +Show amount of traffic in megabytes. +.It Ic G +Show amount of traffic in gigabytes. +.It Ic q , ESC +Quit. .El .Sh BUGS -The "start" and "restart" commands are not yet implemented. -.Pp If you find any bugs, report them to tinc@tinc-vpn.org. .Sh SEE ALSO .Xr tincd 8 , .Xr tinc.conf 5 , .Xr dotty 1 , +.Xr pcap-savefile 7 , +.Xr tcpdump 8 , +.Xr top 1 , .Pa http://www.tinc-vpn.org/ , .Pa http://www.cabal.org/ . .Pp diff --git a/doc/tincd.8.in b/doc/tincd.8.in index 0e790e03..bb560256 100644 --- a/doc/tincd.8.in +++ b/doc/tincd.8.in @@ -1,4 +1,4 @@ -.Dd 2011-01-02 +.Dd 2011-06-25 .Dt TINCD 8 .\" Manual page created by: .\" Ivo Timmermans @@ -70,13 +70,16 @@ If .Ar FILE is omitted, the default is .Pa @localstatedir@/log/tinc. Ns Ar NETNAME Ns Pa .log. -.It Fl -controlsocket Ns = Ns Ar FILENAME -Open control socket at -.Ar FILENAME . +.It Fl -controlcookie Ns = Ns Ar FILENAME +Store a cookie in +.Ar FILENAME +which allows +.Xr tincctl 8 +to authenticate. If .Ar FILE is omitted, the default is -.Pa @localstatedir@/run/tinc. Ns Ar NETNAME Ns Pa .control. +.Pa @localstatedir@/run/tinc. Ns Ar NETNAME Ns Pa .cookie. .It Fl -bypass-security Disables encryption and authentication of the meta protocol. Only useful for debugging. -- 2.39.5