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 ../common/defs.man \" @@@PRE@@@
  28 .
  29 .\"--------------------------------------------------------------------------
  30 .TH tripectl 1tripe "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 [ \-W
  43 .IR things ]
  44 .RB [ \-\fIoptions ]
  45 .RI [ command
  46 .RI [ args ]...]
  47 .br
  48 .B tripectl
  49 .RB [ \-Dlt ]
  50 .RB [ \-f
  51 .IR file ]
  52 .RB [ \-\fIoptions ]
  53 .PP
  54 Options:
  55 .br
  56         \&
  57 .RB [ \-s ]
  58 .RB [ \-d
  59 .IR dir ]
  60 .RB [ \-a
  61 .IR socket ]
  62 .RB [ \-P
  63 .IR pidfile ]
  64 .br
  65         \&
  66 .RB [ \-p
  67 .IR path ]
  68 .RB [ \-U
  69 .IR user ]
  70 .RB [ \-G
  71 .IR group ]
  72 .RB [ \-S
  73 .IB arg , arg ,\fR...]
  74 .
  75 .\"--------------------------------------------------------------------------
  76 .SH "DESCRIPTION"
  77 .
  78 The
  79 .B tripectl
  80 program is a simple client which can be used, either interactively or
  81 from a script, to send commands to and read status information from a
  82 running
  83 .BR tripe (8)
  84 server.  It can also be used to start
  85 .BR tripe (8),
  86 passing appropriate arguments and capturing logging information.
  87 .SS "Command-line options"
  88 .TP
  89 .B "\-h, \-\-help"
  90 Writes a brief description of the command-line options available to
  91 standard output and exits with status 0.
  92 .TP
  93 .B "\-v, \-\-version"
  94 Writes tripe's version number to standard output and exits with status
  95 0.
  96 .TP
  97 .B "\-u, \-\-usage"
  98 Writes a brief usage summary to standard output and exits with status 0.
  99 .TP
 100 .B "\-D, \-\-daemon"
 101 Makes
 102 .B tripectl
 103 disassociate from the terminal and become a background process after
 104 connecting to the server.
 105 .TP
 106 .BI "\-d, \-\-directory=" dir
 107 Make
 108 .I dir
 109 the current directory, before doing anything else.  Note that all the
 110 other filenames (e.g., the log output file) are relative to this
 111 directory.  The default directory, if this option is not specified, is
 112 taken from the environment variable
 113 .BR TRIPEDIR ;
 114 if that's not defined either, a default default of
 115 .B "\*(/c"
 116 is used.
 117 .TP
 118 .BI "\-a, \-\-admin-socket=" socket
 119 If connecting to a running server, connect to the socket named
 120 .IR socket ;
 121 if running a new server, instruct it to listen for admin
 122 connections on
 123 .IR socket .
 124 The default socket, if this option is not specified, is taken from the
 125 environment variable
 126 .BR TRIPESOCK ;
 127 if that's not defined either, a default default of
 128 .B "\*(/s/tripesock"
 129 is used.
 130 .TP
 131 .BI "\-P, \-\-pidfile=" pidfile
 132 Write
 133 .BR tripectl 's
 134 process-id to
 135 .I pidfile
 136 (relative to
 137 .IR dir ).
 138 If the
 139 .B \-D
 140 and
 141 .B \-f
 142 options are given, a default of
 143 .IB dir /tripectl.pid
 144 is used if you don't give a
 145 .B \-P
 146 option.
 147 .TP
 148 .B "\-s, \-\-spawn"
 149 Start a new server: don't connect to an existing one.  Starting a
 150 .BR tripe (8)
 151 server in this manner is a good way to ensure that no log messages are
 152 lost.  The
 153 .BR \-l ,
 154 .B \-f
 155 and
 156 .B \-D
 157 options are particularly useful in conjunction with
 158 .BR \-s .
 159 .TP
 160 .BI "\-p, \-\-spawn\-path=" path
 161 Implies
 162 .BR \-s ;
 163 runs the program named by
 164 .I path
 165 rather than the default
 166 .BR tripe .
 167 If
 168 .I path
 169 is actually an unqualified filename, the program to run is found using
 170 the
 171 .B PATH
 172 environment variable in the usual way.
 173 .TP
 174 .BI "\-S, \-\-spawn\-args=" arg , arg ,\fR...
 175 Implies
 176 .BR \-s ;
 177 passes the comma-separated
 178 .IR arg s
 179 to the
 180 .B tripe
 181 server on its command line.  Arguments added using this option are added
 182 .I after
 183 any passed automatically by
 184 .B tripectl
 185 (e.g.,
 186 .BR \-a ).
 187 .TP
 188 .BI "\-U, \-\-setuid=" user
 189 Set uid to that of
 190 .I user
 191 (either a user name or integer uid) after initialization.  Also set gid
 192 to
 193 .IR user 's
 194 primary group, unless overridden by a
 195 .B \-G
 196 option.  If a new
 197 .BR tripe (8)
 198 server is going to be spawned then it is also passed corresponding
 199 .B \-U
 200 and
 201 .B \-G
 202 options.
 203 .TP
 204 .BI "\-G, \-\-setgid=" group
 205 If the current effective uid is zero (i.e., the daemon was invoked as
 206 .BR root )
 207 then set gid to that of
 208 .I group
 209 (either a group name or integer gid) after initialization.  If a new
 210 .BR tripe (8)
 211 server is going to be spawned then it is also passed a corresponding
 212 .B \-G
 213 option.
 214 .TP
 215 .B "\-l, \-\-syslog"
 216 Send warnings and trace messages to the
 217 .BR syslog (8)
 218 service.  Messages are logged using the
 219 .B daemon
 220 facility.  Warnings are logged with severity
 221 .BR warning ;
 222 trace messages are logged with severity
 223 .BR debug .
 224 .TP
 225 .BI "\-f, \-\-logfile=" file
 226 Write warnings and trace messages to
 227 .IR file .
 228 The
 229 .I file
 230 may be
 231 .RB ` \- '
 232 to request output to stdout, or
 233 .RB ` ! '
 234 to request output to stderr.  If a proper filename is given (rather than
 235 one of these special tokens), then on receipt of a
 236 .B SIGHUP
 237 signal,
 238 .B tripectl
 239 will close its log file and reopen a new one with the same name; this is
 240 useful when you rotate logs.
 241 .TP
 242 .B "\-t, \-\-no-timestamp"
 243 When logging to a file (with
 244 .BR \-f ),
 245 don't prefix log items with a timestamp.  This is useful when the log
 246 output is being captured by some process which will add its own
 247 timestamps anyway.
 248 .TP
 249 .B "\-w, \-\-warnings"
 250 Write warnings to standard error even when running noninteractively.
 251 .TP
 252 .BI "\-W, \-\-watch=" things
 253 When running as a client, arrange to receive asynchronous messages as
 254 described by
 255 .IR things ,
 256 which should be a trace list suitable for passing to the server's
 257 .B WATCH
 258 command: see
 259 .BR tripe-admin (5)
 260 for more details.  This overrides the
 261 .B \-w
 262 flag in noninteractive use.
 263 .SS "Interactive use"
 264 With no arguments,
 265 .B tripectl
 266 will connect to a running server and await commands from its standard
 267 input.  The commands are submitted to the server unchanged, and the
 268 results written to standard output.  It will quit when it receives a
 269 fatal signal or an end-of-file indication from the server.
 270 .SS "Use from scripts"
 271 If arguments are given to
 272 .BR tripectl ,
 273 they are quoted if necessary to protect spaces and other special
 274 characters, concatenated with spaces between, and submitted to the
 275 server after connection.  Any
 276 .B INFO
 277 responses returned by the server are written to standard output (without
 278 the
 279 .B INFO
 280 on the front).  A
 281 .B FAIL
 282 response causes the error message to be written to standard error, and
 283 the client to exit with a nonzero return code.  An
 284 .B OK
 285 response causes the client to exit with a zero return code.  Unless the
 286 .B \-w
 287 command-line option was given, any
 288 .B WARN
 289 responses are discarded; if
 290 .B \-w
 291 .I was
 292 given,
 293 .B WARN
 294 responses are written to standard error.  In all cases,
 295 .B TRACE
 296 responses are ignored.
 297 .SS "Starting the tripe server"
 298 If any of the options
 299 .BR \-s ,
 300 .B \-p
 301 or
 302 .B \-S
 303 are given,
 304 .B tripectl
 305 will start a new
 306 .B tripe
 307 server, rather than connecting to an existing one.
 308 .PP
 309 The command line for the new server is
 310 .IP
 311 .I path
 312 .B \-F
 313 .B \-d.\&
 314 .B \-a
 315 .I socket
 316 .I dash-S-options
 317 .PP
 318 where
 319 .I dash-S-options
 320 is the concatenation of the arguments of
 321 .B \-S
 322 options, split at commas.
 323 .PP
 324 Starting a
 325 .B tripe
 326 server through
 327 .B tripectl
 328 is most useful if you want to collect logging information from the
 329 server, and want to avoid losing any.  For example, the command
 330 .VS
 331 tripectl -Ds -f tripe.log
 332 .VE
 333 starts up a new server in the default directory, and captures all of its
 334 logging output (i.e.,
 335 .B WARN
 336 and
 337 .B TRACE
 338 messages) in the file
 339 .BR tripe.log .
 340 It stores its process-id in
 341 .BR tripectl.pid .
 342 .PP
 343 It's possible to communicate interactively with a newly-started server,
 344 or to give it a command and quit, but this is seldom useful.
 345 .
 346 .\"--------------------------------------------------------------------------
 347 .SH "SEE ALSO"
 348 .
 349 .BR tripe\-admin (5),
 350 .BR tripe (8).
 351 .PP
 352 .IR "The Trivial IP Encryption Protocol" ,
 353 .IR "The Wrestlers Protocol" .
 354 .
 355 .\"--------------------------------------------------------------------------
 356 .SH "AUTHOR"
 357 .
 358 Mark Wooding, <mdw@distorted.org.uk>
 359 .
 360 .\"----- That's all, folks --------------------------------------------------