chiark - git - mdw - tripe/blob - doc/tripectl.1.in

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