chiark - git - mdw - tripe/blob - client/tripectl.1.in

   1 .\" -*-nroff-*-
   2 .\".
   3 .\" Manual for the administration client
   4 .\"
   5 .\" (c) 2008 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of Trivial IP Encryption (TrIPE).
  11 .\"
  12 .\" TrIPE is free software; you can redistribute it and/or modify
  13 .\" it under the terms of the GNU General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or
  15 .\" (at your option) any later version.
  16 .\"
  17 .\" TrIPE is distributed in the hope that it will be useful,
  18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 .\" GNU General Public License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU General Public License
  23 .\" along with TrIPE; if not, write to the Free Software Foundation,
  24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  25 .
  26 .\"--------------------------------------------------------------------------
  27 .so ../defs.man.in \" @@@PRE@@@
  28 .
  29 .\"--------------------------------------------------------------------------
  30 .TH tripectl 1 "19 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  31 .
  32 .\"--------------------------------------------------------------------------
  33 .SH "NAME"
  34 .
  35 tripectl \- simple client for TrIPE
  36 .
  37 .\"--------------------------------------------------------------------------
  38 .SH "SYNOPSIS"
  39 .
  40 .B tripectl
  41 .RB [ \-w ]
  42 .RB [ \-\fIoptions ]
  43 .RI [ command
  44 .RI [ args ]...]
  45 .br
  46 .B tripectl
  47 .RB [ \-Dl ]
  48 .RB [ \-f
  49 .IR file ]
  50 .RB [ \-\fIoptions ]
  51 .PP
  52 Options:
  53 .br
  54         \&
  55 .RB [ \-s ]
  56 .RB [ \-d
  57 .IR dir ]
  58 .RB [ \-a
  59 .IR socket ]
  60 .RB [ \-P
  61 .IR pidfile ]
  62 .br
  63         \&
  64 .RB [ \-p
  65 .IR path ]
  66 .RB [ \-S
  67 .IB arg , arg ,\fR...]
  68 .
  69 .\"--------------------------------------------------------------------------
  70 .SH "DESCRIPTION"
  71 .
  72 The
  73 .B tripectl
  74 program is a simple client which can be used, either interactively or
  75 from a script, to send commands to and read status information from a
  76 running
  77 .BR tripe (8)
  78 server.  It can also be used to start
  79 .BR tripe (8),
  80 passing appropriate arguments and capturing logging information.
  81 .SS "Command-line options"
  82 .TP
  83 .B "\-h, \-\-help"
  84 Writes a brief description of the command-line options available to
  85 standard output and exits with status 0.
  86 .TP
  87 .B "\-v, \-\-version"
  88 Writes tripe's version number to standard output and exits with status
  89 0.
  90 .TP
  91 .B "\-u, \-\-usage"
  92 Writes a brief usage summary to standard output and exits with status 0.
  93 .TP
  94 .B "\-D, \-\-daemon"
  95 Makes
  96 .B tripectl
  97 disassociate from the terminal and become a background process after
  98 connecting to the server.
  99 .TP
 100 .BI "\-d, \-\-directory=" dir
 101 Make
 102 .I dir
 103 the current directory, before doing anything else.  Note that all the
 104 other filenames (e.g., the log output file) are relative to this
 105 directory.  The default directory, if this option is not specified, is
 106 taken from the environment variable
 107 .BR TRIPEDIR ;
 108 if that's not defined either, a default default of
 109 .B "*(/c"
 110 is used.
 111 .TP
 112 .BI "\-a, \-\-admin-socket=" socket
 113 If connecting to a running server, connect to the socket named
 114 .IR socket ;
 115 if running a new server, instruct it to listen for admin
 116 connections on
 117 .IR socket .
 118 The default socket, if this option is not specified, is taken from the
 119 environment variable
 120 .BR TRIPESOCK ;
 121 if that's not defined either, a default default of
 122 .B "*(/s/tripesock"
 123 is used.
 124 .TP
 125 .BI "\-P, \-\-pidfile=" pidfile
 126 Write
 127 .BR tripectl 's
 128 process-id to
 129 .I pidfile
 130 (relative to
 131 .IR dir ).
 132 If the
 133 .B \-D
 134 and
 135 .B \-f
 136 options are given, a default of
 137 .IB dir /tripectl.pid
 138 is used if you don't give a
 139 .B \-P
 140 option.
 141 .TP
 142 .B "\-s, \-\-spawn"
 143 Start a new server: don't connect to an existing one.  Starting a
 144 .BR tripe (8)
 145 server in this manner is a good way to ensure that no log messages are
 146 lost.  The
 147 .BR \-l ,
 148 .B \-f
 149 and
 150 .B \-D
 151 options are particularly useful in conjunction with
 152 .BR \-s .
 153 .TP
 154 .BI "\-p, \-\-spawn\-path=" path
 155 Implies
 156 .BR \-s ;
 157 runs the program named by
 158 .I path
 159 rather than the default
 160 .BR tripe .
 161 If
 162 .I path
 163 is actually an unqualified filename, the program to run is found using
 164 the
 165 .B PATH
 166 environment variable in the usual way.
 167 .TP
 168 .BI "\-S, \-\-spawn\-args=" arg , arg ,\fR...
 169 Implies
 170 .BR \-s ;
 171 passes the comma-separated
 172 .IR arg s
 173 to the
 174 .B tripe
 175 server on its command line.  Arguments added using this option are added
 176 .I after
 177 any passed automatically by
 178 .B tripectl
 179 (e.g.,
 180 .BR \-a ).
 181 .TP
 182 .B "\-l, \-\-syslog"
 183 Send warnings and trace messages to the
 184 .BR syslog (8)
 185 service.  Messages are logged using the
 186 .B daemon
 187 facility.  Warnings are logged with severity
 188 .BR warning ;
 189 trace messages are logged with severity
 190 .BR debug .
 191 .TP
 192 .BI "\-f, \-\-logfile=" file
 193 Write warnings and trace messages to
 194 .IR file .
 195 On receipt of a
 196 .B SIGHUP
 197 signal,
 198 .B tripectl
 199 will close its log file and reopen a new one with the same name.  This
 200 is useful when you rotate logs.
 201 .TP
 202 .B "\-w, \-\-warnings"
 203 Write warnings to standard error even when running noninteractively.
 204 .SS "Interactive use"
 205 With no arguments,
 206 .B tripectl
 207 will connect to a running server and await commands from its standard
 208 input.  The commands are submitted to the server unchanged, and the
 209 results written to standard output.  It will quit when it receives a
 210 fatal signal or an end-of-file indication from the server.
 211 .SS "Use from scripts"
 212 If arguments are given to
 213 .BR tripectl ,
 214 they are quoted if necessary to protect spaces and other special
 215 characters, concatenated with spaces between, and submitted to the
 216 server after connection.  Any
 217 .B INFO
 218 responses returned by the server are written to standard output (without
 219 the
 220 .B INFO
 221 on the front).  A
 222 .B FAIL
 223 response causes the error message to be written to standard error, and
 224 the client to exit with a nonzero return code.  An
 225 .B OK
 226 response causes the client to exit with a zero return code.  Unless the
 227 .B \-w
 228 command-line option was given, any
 229 .B WARN
 230 responses are discarded; if
 231 .B \-w
 232 .I was
 233 given,
 234 .B WARN
 235 responses are written to standard error.  In all cases,
 236 .B TRACE
 237 responses are ignored.
 238 .SS "Starting the tripe server"
 239 If any of the options
 240 .BR \-s ,
 241 .B \-p
 242 or
 243 .B \-S
 244 are given,
 245 .B tripectl
 246 will start a new
 247 .B tripe
 248 server, rather than connecting to an existing one.
 249 .PP
 250 The command line for the new server is
 251 .IP
 252 .I path
 253 .B \-F
 254 .B \-d.\&
 255 .B \-a
 256 .I socket
 257 .I dash-S-options
 258 .PP
 259 where
 260 .I dash-S-options
 261 is the concatenation of the arguments of
 262 .B \-S
 263 options, split at commas.
 264 .PP
 265 Starting a
 266 .B tripe
 267 server through
 268 .B tripectl
 269 is most useful if you want to collect logging information from the
 270 server, and want to avoid losing any.  For example, the command
 271 .VS
 272 tripectl -Ds -f tripe.log
 273 .VE
 274 starts up a new server in the default directory, and captures all of its
 275 logging output (i.e.,
 276 .B WARN
 277 and
 278 .B TRACE
 279 messages) in the file
 280 .BR tripe.log .
 281 It stores its process-id in
 282 .BR tripectl.pid .
 283 .PP
 284 It's possible to communicate interactively with a newly-started server,
 285 or to give it a command and quit, but this is seldom useful.
 286 .
 287 .\"--------------------------------------------------------------------------
 288 .SH "SEE ALSO"
 289 .
 290 .BR tripe\-admin (5),
 291 .BR tripe (8).
 292 .PP
 293 .IR "The Trivial IP Encryption Protocol" ,
 294 .IR "The Wrestlers Protocol" .
 295 .
 296 .\"--------------------------------------------------------------------------
 297 .SH "AUTHOR"
 298 .
 299 Mark Wooding, <mdw@distorted.org.uk>
 300 .
 301 .\"----- That's all, folks --------------------------------------------------