From: mdw Date: Thu, 22 Feb 2001 09:08:38 +0000 (+0000) Subject: Complete the manual. X-Git-Tag: 1.0.0pre1~7 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/commitdiff_plain/87154d69af814f4334ea39113df1615122b9a2b2 Complete the manual. --- diff --git a/doc/tripectl.1 b/doc/tripectl.1 index 877a467a..12e0c2cd 100644 --- a/doc/tripectl.1 +++ b/doc/tripectl.1 @@ -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,