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