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