chiark / gitweb /
Complete the manual.
authormdw <mdw>
Thu, 22 Feb 2001 09:08:38 +0000 (09:08 +0000)
committermdw <mdw>
Thu, 22 Feb 2001 09:08:38 +0000 (09:08 +0000)
doc/tripectl.1

index 877a467..12e0c2c 100644 (file)
@@ -1,4 +1,21 @@
 .\" -*-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
@@ -20,9 +37,11 @@ Options:
        \&
 .RB [ \-s ]
 .RB [ \-d
-.IR directory ]
+.IR dir ]
 .RB [ \-a
 .IR socket ]
+.RB [ \-P
+.IR pidfile ]
 .br
        \&
 .RB [ \-p
@@ -30,3 +49,196 @@ Options:
 .RB [ \-S
 .IB arg , arg ,\fR...]
 .SH DESCRIPTION
+The
+.B tripectl
+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@nsict.org>