chiark - git - mdw - tripe/blob - doc/tripectl.1

   1 .\" -*-nroff-*-
   2 .de VS
   3 .sp 1
   4 .RS
   5 .nf
   6 .ft B
   7 ..
   8 .de VE
   9 .ft R
  10 .fi
  11 .RE
  12 .sp 1
  13 ..
  14 .ie t \{\
  15 .  if \n(.g \{\
  16 .    fam P
  17 .  \}
  18 .\}
  19 .TH tripectl 1 "19 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  20 .SH NAME
  21 tripectl \- simple client for TrIPE
  22 .SH SYNOPSIS
  23 .B tripectl
  24 .RB [ \-w ]
  25 .RB [ \-\fIoptions ]
  26 .RI [ command
  27 .RI [ args ]...]
  28 .br
  29 .B tripectl
  30 .RB [ \-Dl ]
  31 .RB [ \-f
  32 .IR file ]
  33 .RB [ \-\fIoptions ]
  34 .PP
  35 Options:
  36 .br
  37         \&
  38 .RB [ \-s ]
  39 .RB [ \-d
  40 .IR dir ]
  41 .RB [ \-a
  42 .IR socket ]
  43 .RB [ \-P
  44 .IR pidfile ]
  45 .br
  46         \&
  47 .RB [ \-p
  48 .IR program ]
  49 .RB [ \-S
  50 .IB arg , arg ,\fR...]
  51 .SH DESCRIPTION
  52 The
  53 .B tripectl
  54 is a simple client which can be used, either interactively or from a
  55 script, to send commands to and read status information from a running
  56 .BR tripe (8)
  57 server.  It can also be used to start
  58 .BR tripe (8),
  59 passing appropriate arguments and capturing logging information.
  60 .SS "Command-line options"
  61 .TP
  62 .B "\-h, \-\-help"
  63 Writes a brief description of the command-line options available to
  64 standard output and exits with status 0.
  65 .TP
  66 .B "\-v, \-\-version"
  67 Writes tripe's version number to standard output and exits with status
  68 0.
  69 .TP
  70 .B "\-u, \-\-usage"
  71 Writes a brief usage summary to standard output and exits with status 0.
  72 .TP
  73 .B "\-D, \-\-daemon"
  74 Makes
  75 .B tripectl
  76 disassociate from the terminal and become a background process after
  77 connecting to the server.
  78 .TP
  79 .BI "\-d, \-\-directory=" dir
  80 Make
  81 .I dir
  82 the current directory, before doing anything else.  Note that all the
  83 other filenames (e.g., the log output file) are relative to this
  84 directory.  The default directory, if this option is not specified, is
  85 taken from the environment variable
  86 .BR TRIPEDIR ;
  87 if that's not defined either, a default default of
  88 .BR /var/lib/tripe
  89 is used.
  90 .TP
  91 .BI "\-a, \-\-admin=" socket
  92 If connecting to a running server, connect to the socket named
  93 .IR socket ; if running a new server, instruct it to listen for admin
  94 connections on
  95 .IR socket .
  96 .TP
  97 .BI "\-P, \-\-pidfile=" pidfile
  98 Write
  99 .BR tripectl 's
 100 process-id to
 101 .I pidfile
 102 (relative to
 103 .IR dir ).
 104 If the
 105 .B \-D
 106 and
 107 .B \-f
 108 options are given, a default of
 109 .IB dir /tripectl.pid
 110 is used if you don't give a
 111 .B \-P
 112 option.
 113 .TP
 114 .B "\-s, \-\-spawn"
 115 Start a new server: don't connect to an existing one.  Starting a
 116 .BR tripe (8)
 117 server in this manner is a good way to ensure that no log messages are
 118 lost.  The
 119 .BR \-l ,
 120 .B \-f
 121 and
 122 .B \-D
 123 options are particularly useful in conjunction with
 124 .BR \-s .
 125 .TP
 126 .BI "\-p, \-\-spawn\-path=" path
 127 Implies
 128 .BR \-s ;
 129 runs the program named by
 130 .I path
 131 rather than the default
 132 .BR tripe .
 133 If
 134 .I path
 135 is actually an unqualified filename, the program to run is found using
 136 the
 137 .B PATH
 138 environment variable in the usual way.
 139 .TP
 140 .BI "\-S, \-\-spawn\-args=" arg , arg ,\fR...
 141 Implies
 142 .BR \-s ;
 143 passes the comma-separated
 144 .IR arg s
 145 to the
 146 .B tripe
 147 server on its command line.  Arguments added using this option are added
 148 .I after
 149 any passed automatically by
 150 .B tripectl
 151 (e.g.,
 152 .BR \-a ).
 153 .TP
 154 .B "\-l, \-\-syslog"
 155 Send warnings and trace messages to the
 156 .BR syslog (8)
 157 service.  Messages are logged using the
 158 .B daemon
 159 facility.  Warnings are logged with severity
 160 .BR warning ;
 161 trace messages are logged with severity
 162 .BR debug .
 163 .TP
 164 .BI "\-f, \-\-logfile=" file
 165 Write warnings and trace messages to
 166 .IR file .
 167 On receipt of a
 168 .B SIGHUP
 169 signal,
 170 .B tripectl
 171 will close its log file and reopen a new one with the same name.  This
 172 is useful when you rotate logs.
 173 .TP
 174 .B "\-w, \-\-warnings"
 175 Write warnings to standard error even when running noninteractively.
 176 .SS "Interactive use"
 177 With no arguments,
 178 .B tripectl
 179 will connect to a running server and await commands from its standard
 180 input.  The commands are submitted to the server unchanged, and the
 181 results written to standard output.  It will quit when it receives a
 182 fatal signal or an end-of-file indication from the server.
 183 .SS "Use from scripts"
 184 If arguments are given to
 185 .BR tripectl ,
 186 they are concatenated with spaces between and submitted to the server
 187 after connection.  Any
 188 .B INFO
 189 responses returned by the server are written to standard output (without
 190 the
 191 .B INFO
 192 on the front).  A
 193 .B FAIL
 194 response causes the error message to be written to standard error, and
 195 the client to exit with a nonzero return code.  An
 196 .B OK
 197 response causes the client to exit with a zero return code.  Unless the
 198 .B \-w
 199 command-line option was given, any
 200 .B WARN
 201 responses are discarded; if
 202 .B \-w
 203 .I was
 204 given,
 205 .B WARN
 206 responses are written to standard error.  In all cases,
 207 .B TRACE
 208 responses are ignored.
 209 .SS "Starting the tripe server"
 210 If any of the options
 211 .BR \-s ,
 212 .B \-p
 213 or
 214 .B \-S
 215 are given,
 216 .B tripectl
 217 will start a new
 218 .B tripe
 219 server, rather than connecting to an existing one.  This is most useful
 220 if you want to collect logging information from the server, and want to
 221 avoid losing any.  For example, the command
 222 .VS
 223 tripectl -Ds -f tripe.log
 224 .VE
 225 starts up a new server in the default directory, and captures all of its
 226 logging output (i.e.,
 227 .B WARN
 228 and
 229 .B TRACE
 230 messages) in the file
 231 .BR tripe.log .
 232 It stores its process-id in
 233 .BR tripectl.pid .
 234 .PP
 235 It's possible to communicate interactively with a newly-started server,
 236 or to give it a command and quit, but this is seldom useful.
 237 .SH "SEE ALSO"
 238 .BR tripe\-admin (5),
 239 .BR tripe (8).
 240 .PP
 241 .IR "The Trivial IP Encryption Protocol" ,
 242 .IR "The Wrestlers Protocol" .
 243 .SH "AUTHOR"
 244 Mark Wooding, <mdw@nsict.org>