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