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