server/admin: Fix tokenization of statistics output.

[tripe] / doc / tripectl.1

.\" -*-nroff-*-
.de VS
.sp 1
.RS
.nf
.ft B
..
.de VE
.ft R
.fi
.RE
.sp 1
..
.ie t \{\
.  if \n(.g \{\
.    fam P
.  \}
.\}
.TH tripectl 1 "19 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.SH NAME
tripectl \- simple client for TrIPE
.SH SYNOPSIS
.B tripectl
.RB [ \-w ]
.RB [ \-\fIoptions ]
.RI [ command
.RI [ args ]...]
.br
.B tripectl
.RB [ \-Dl ]
.RB [ \-f
.IR file ]
.RB [ \-\fIoptions ]
.PP
Options:
.br
	\&
.RB [ \-s ]
.RB [ \-d
.IR dir ]
.RB [ \-a
.IR socket ]
.RB [ \-P
.IR pidfile ]
.br
	\&
.RB [ \-p
.IR program ]
.RB [ \-S
.IB arg , arg ,\fR...]
.SH DESCRIPTION
The
.B tripectl
program is a simple client which can be used, either interactively or
from a script, to send commands to and read status information from a
running
.BR tripe (8)
server.  It can also be used to start
.BR tripe (8),
passing appropriate arguments and capturing logging information.
.SS "Command-line options"
.TP
.B "\-h, \-\-help"
Writes a brief description of the command-line options available to
standard output and exits with status 0.
.TP
.B "\-v, \-\-version"
Writes tripe's version number to standard output and exits with status
0.
.TP
.B "\-u, \-\-usage"
Writes a brief usage summary to standard output and exits with status 0.
.TP
.B "\-D, \-\-daemon"
Makes
.B tripectl
disassociate from the terminal and become a background process after
connecting to the server.
.TP
.BI "\-d, \-\-directory=" dir
Make
.I dir
the current directory, before doing anything else.  Note that all the
other filenames (e.g., the log output file) are relative to this
directory.  The default directory, if this option is not specified, is
taken from the environment variable
.BR TRIPEDIR ;
if that's not defined either, a default default of
.BR /var/lib/tripe
is used.
.TP
.BI "\-a, \-\-admin=" socket
If connecting to a running server, connect to the socket named
.IR socket ;
if running a new server, instruct it to listen for admin
connections on
.IR socket .
.TP
.BI "\-P, \-\-pidfile=" pidfile
Write
.BR tripectl 's
process-id to
.I pidfile
(relative to
.IR dir ).
If the
.B \-D
and
.B \-f
options are given, a default of
.IB dir /tripectl.pid
is used if you don't give a
.B \-P
option.
.TP
.B "\-s, \-\-spawn"
Start a new server: don't connect to an existing one.  Starting a
.BR tripe (8)
server in this manner is a good way to ensure that no log messages are
lost.  The
.BR \-l ,
.B \-f
and
.B \-D
options are particularly useful in conjunction with
.BR \-s .
.TP
.BI "\-p, \-\-spawn\-path=" path
Implies
.BR \-s ;
runs the program named by
.I path
rather than the default
.BR tripe .
If
.I path
is actually an unqualified filename, the program to run is found using
the
.B PATH
environment variable in the usual way.
.TP
.BI "\-S, \-\-spawn\-args=" arg , arg ,\fR...
Implies
.BR \-s ;
passes the comma-separated
.IR arg s
to the
.B tripe
server on its command line.  Arguments added using this option are added
.I after
any passed automatically by
.B tripectl
(e.g., 
.BR \-a ).
.TP
.B "\-l, \-\-syslog"
Send warnings and trace messages to the
.BR syslog (8)
service.  Messages are logged using the
.B daemon
facility.  Warnings are logged with severity
.BR warning ;
trace messages are logged with severity
.BR debug .
.TP
.BI "\-f, \-\-logfile=" file
Write warnings and trace messages to
.IR file .
On receipt of a
.B SIGHUP
signal,
.B tripectl
will close its log file and reopen a new one with the same name.  This
is useful when you rotate logs.
.TP
.B "\-w, \-\-warnings"
Write warnings to standard error even when running noninteractively.
.SS "Interactive use"
With no arguments,
.B tripectl
will connect to a running server and await commands from its standard
input.  The commands are submitted to the server unchanged, and the
results written to standard output.  It will quit when it receives a
fatal signal or an end-of-file indication from the server.
.SS "Use from scripts"
If arguments are given to
.BR tripectl ,
they are concatenated with spaces between and submitted to the server
after connection.  Any
.B INFO
responses returned by the server are written to standard output (without
the
.B INFO
on the front).  A
.B FAIL
response causes the error message to be written to standard error, and
the client to exit with a nonzero return code.  An
.B OK
response causes the client to exit with a zero return code.  Unless the
.B \-w
command-line option was given, any
.B WARN
responses are discarded; if
.B \-w
.I was
given,
.B WARN
responses are written to standard error.  In all cases,
.B TRACE
responses are ignored.
.SS "Starting the tripe server"
If any of the options
.BR \-s ,
.B \-p 
or
.B \-S
are given,
.B tripectl
will start a new
.B tripe
server, rather than connecting to an existing one.  This is most useful
if you want to collect logging information from the server, and want to
avoid losing any.  For example, the command
.VS
tripectl -Ds -f tripe.log
.VE
starts up a new server in the default directory, and captures all of its
logging output (i.e.,
.B WARN
and
.B TRACE
messages) in the file
.BR tripe.log .
It stores its process-id in
.BR tripectl.pid .
.PP
It's possible to communicate interactively with a newly-started server,
or to give it a command and quit, but this is seldom useful.
.SH "SEE ALSO"
.BR tripe\-admin (5),
.BR tripe (8).
.PP
.IR "The Trivial IP Encryption Protocol" ,
.IR "The Wrestlers Protocol" .
.SH "AUTHOR"
Mark Wooding, <mdw@distorted.org.uk>