spec.html/ch-client.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2
   3 <html>
   4
   5 <head>
   6
   7 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
   8
   9 <title>User service daemon and client specification - Client program usage</title>
  10
  11 </head>
  12
  13 <body>
  14
  15 <a name="ch-client"></a>
  16 <hr>
  17
  18 [ <a href="ch-intro.html">previous</a> ]
  19 [ <a href="index.html#contents">Contents</a> ]
  20 [ <a href="ch-intro.html">1</a> ]
  21 [ 2 ]
  22 [ <a href="ch-envir.html">3</a> ]
  23 [ <a href="ch-config.html">4</a> ]
  24 [ <a href="ch-ipass.html">5</a> ]
  25 [ <a href="ch-notes.html">6</a> ]
  26 [ <a href="ch-envir.html">next</a> ]
  27
  28 <hr>
  29
  30 <h1>
  31 User service daemon and client specification
  32 <br>Chapter 2 - Client program usage
  33 </h1>
  34
  35
  36 <pre>
  37      userv <var>options</var> [--] <var>service-user</var> <var>service-name</var> [<var>argument</var> ...]
  38      userv <var>options</var> -B|--builtin [--] <var>builtin-service</var> [<var>info-argument</var> ...]
  39 </pre>
  40
  41 <hr>
  42
  43
  44 <p>
  45 <var>service-user</var> specifies which user is to provide the service.  The
  46 user may be a login name or a numeric uid, or <samp>-</samp> to indicate that
  47 the service user is to be the same as the calling user.
  48
  49 <p>
  50 The service name is interpreted by the userv[<a href="footnotes.html#f1"
  51 name="fr1">1</a>] daemon on behalf of the service user.  It will often be the
  52 name of a program.
  53
  54 <hr>
  55
  56 <a name="s2.1"></a>
  57 <h2>2.1 Options</h2>
  58
  59 <p>
  60 Single-letter options may be combined as is usual with Unix programs, and the
  61 value for such an option may appear in the same argument or in the next.
  62 <dl>
  63 <dt><samp>-B</samp></dt>
  64 <dt><samp>--builtin</samp></dt>
  65 <dd>
  66 Requests that a builtin service be provided.  This is equivalent to using the
  67 <code>--override</code> option to specify a string consisting of
  68 <code>execute-builtin</code> followed by the <var>builtin-service</var>
  69 requested, and requesting a service user of <samp>-</samp> (indicating the
  70 calling user).
  71
  72 <p>
  73 If the builtin service being requested requires a <var>service-argument</var>
  74 then this must be supplied to the client in the same argument as the
  75 <var>builtin-service</var>.  See <a
  76 href="ch-config.html#s-dirs-execution">Directives for changing execution
  77 settings, Section 4.2.4</a> for details of the builtin services available, and
  78 <a href="ch-client.html#s-optoverride">Security-overriding options, Section
  79 2.2</a> for details of the <code>--override</code> options.
  80
  81 <p>
  82 The actual service name passed will be the <var>builtin-service</var>; note
  83 that this actual service name (as opposed to the override data) and the
  84 <var>info-argument</var>s supplied will be ignored by most builtin services;
  85 the override mechanism and <code>execute-builtin</code> will be used to ensure
  86 that the right builtin service is called with the right
  87 <var>service-argument</var>s.
  88 </dd>
  89 </dl>
  90 <dl>
  91 <dt><samp>--file <var>fd</var>[<var>modifiers</var>]=<var>filename</var></samp></dt>
  92 <dd>
  93 Requests that data be copied in and out of the service using pipes.  For each
  94 file or descriptor this will be done by creating a pipe, one end of which is
  95 passed to the service program and the other end of which is passed to a copy of
  96 <code>cat</code> invoked by the client; the other file descriptor passed to
  97 <code>cat</code> will be one inherited by the client program from the caller or
  98 one opened by the client program on behalf of the caller.
  99
 100 <p>
 101 The descriptor in the service program that should be connected must be
 102 specified as <var>fd</var>, either as a decimal number or as one of the strings
 103 <samp>stdin</samp>, <samp>stdout</samp> or <samp>stderr</samp>.  The next
 104 argument is a filename which will be opened by the client with the privileges
 105 of the calling user.
 106
 107 <p>
 108 <var>modifiers</var> is used to specify whether the file or descriptor is to be
 109 read from or written to.  It consists of a series of words separated by commas.
 110 A comma may separate the <var>modifiers</var> from the <var>fd</var> and is
 111 required if <var>fd</var> is not numeric.
 112
 113 <p>
 114 The modifier words are:
 115 <dl>
 116 <dt><samp>read</samp></dt>
 117 <dd>
 118 <samp>O_RDONLY</samp>: Allow reading and not writing.  May not be used with
 119 <samp>write</samp> or things that imply it.
 120 </dd>
 121 <dt><samp>write</samp></dt>
 122 <dd>
 123 <samp>O_WRONLY</samp>: Allow writing and not reading.  <em>Doesn't truncate or
 124 create</em> without <samp>truncate</samp> or <samp>create</samp>.
 125 <samp>write</samp> or things that imply it may not be used with
 126 <samp>read</samp>.
 127 </dd>
 128 <dt><samp>overwrite</samp></dt>
 129 <dd>
 130 Equivalent to <samp>write,create,truncate</samp>.
 131 </dd>
 132 <dt><samp>create</samp></dt>
 133 <dt><samp>creat</samp></dt>
 134 <dd>
 135 <samp>O_CREAT</samp>: Creates the file if necessary.  Implies
 136 <samp>write</samp>.
 137 </dd>
 138 <dt><samp>exclusive</samp></dt>
 139 <dt><samp>excl</samp></dt>
 140 <dd>
 141 <samp>O_EXCL</samp>: Fails if the file already exists.  Implies
 142 <samp>write</samp> and <samp>create</samp>.  May not be used with
 143 <samp>truncate</samp>.
 144 </dd>
 145 <dt><samp>truncate</samp></dt>
 146 <dt><samp>trunc</samp></dt>
 147 <dd>
 148 <samp>O_TRUNC</samp>: Truncate any existing file.  Implies <samp>write</samp>.
 149 May not be used with <samp>exclusive</samp>.
 150 </dd>
 151 <dt><samp>append</samp></dt>
 152 <dd>
 153 <samp>O_APPEND</samp>: All writes will append to the file.  Implies
 154 <samp>write</samp> (but not <samp>create</samp>).
 155 </dd>
 156 <dt><samp>sync</samp></dt>
 157 <dd>
 158 <samp>O_SYNC</samp>: Do writes synchronously.  Implies <samp>write</samp>.
 159 </dd>
 160 <dt><samp>wait</samp></dt>
 161 <dt><samp>nowait</samp></dt>
 162 <dt><samp>close</samp></dt>
 163 <dd>
 164 These modifiers control the behaviour of the client, with respect to the pipes
 165 carrying data to and from the service, when the service terminates.  See below.
 166 </dd>
 167 <dt><samp>fd</samp></dt>
 168 <dd>
 169 The <var>filename</var> is not a filename but a numeric file descriptor.  One
 170 or both of <samp>read</samp> and <samp>write</samp> must be specified, and no
 171 other words are allowed.  The <var>filename</var> may also be
 172 <samp>stdin</samp>, <samp>stdout</samp> or <samp>stderr</samp> for file
 173 descriptor 0, 1 or 2 respectively.
 174 </dd>
 175 </dl>
 176
 177 <p>
 178 If no <var>modifiers</var> which imply <samp>read</samp> or <samp>write</samp>
 179 are used it is as if <samp>write</samp> had been specified, except that if the
 180 filedescriptor 0 of the service is being opened (either specified numerically
 181 or with <samp>stdin</samp>) it is as if <samp>overwrite</samp> had been
 182 specified (or <samp>write</samp> if only <samp>fd</samp> was specified).
 183
 184 <p>
 185 The client will also use <samp>O_NOCTTY</samp> when opening files specified by
 186 the caller, to avoid changing its controlling terminal.
 187
 188 <p>
 189 By default stdin, stdout and stderr of the service will be connected to the
 190 corresponding descriptors on the client.  Diagnostics from the client and
 191 daemon will also appear on stderr.
 192
 193 <p>
 194 If <samp>wait</samp> is specified, the client will wait for the pipe to be
 195 closed, and only exit after this has happened.  This means that either the
 196 receiving end of the pipe connection was closed while data was still available
 197 at the sending end, or that the end of file was reached on the reading file
 198 descriptor.  Errors encountered reading or writing in the client at this stage
 199 will be considered a system error and cause the client to exit with status 255,
 200 but will not cause disconnection at the service side since the service has
 201 already exited.
 202
 203 <p>
 204 If <samp>close</samp> is specified the client will immediately close the pipe
 205 connection by killing the relevant copy of <code>cat</code>.  If the service
 206 uses the descriptor it will get <code>SIGPIPE</code> (or <code>EPIPE</code>)
 207 for a writing descriptor or end of file for a reading one; the descriptor
 208 opened by or passed to the client will also be closed.
 209
 210 <p>
 211 If <samp>nowait</samp> is specified then the client will not wait and the
 212 connection will remain open after the client terminates.  Data may continue to
 213 be passed between the inheritors of the relevant descriptor on the service side
 214 and the corresponding file or descriptor on the client side until either side
 215 closes their descriptor.  This should not usually be specified for stderr (or
 216 stdout if <samp>--signals stdout</samp> is used) since diagnostics from the
 217 service side may arrive after the client has exited and be confused with
 218 expected output.
 219
 220 <p>
 221 The default is <samp>wait</samp> for writing file descriptors and
 222 <samp>close</samp> for reading ones.
 223 </dd>
 224 </dl>
 225 <dl>
 226 <dt><samp>-w<var>fd</var>=<var>action</var></samp></dt>
 227 <dt><samp>--fdwait<var>fd</var>=<var>action</var></samp></dt>
 228 <dd>
 229 Sets the action on termination of the service for the specified file
 230 descriptor; <var>action</var> must be <samp>wait</samp>, <samp>nowait</samp> or
 231 <samp>close</samp> as described above.  The file descriptor must be specified
 232 as open when this option is encountered; this option is overridden by any later
 233 <code>--file</code> or <code>--fdwait</code> option - even by a
 234 <code>--file</code> which does not specify an action on termination (in this
 235 case the default will be used, as described above).
 236 </dd>
 237 </dl>
 238 <dl>
 239 <dt><samp>-D<var>name</var>=<var>value</var></samp></dt>
 240 <dt><samp>--defvar <var>name</var>=<var>value</var></samp></dt>
 241 <dd>
 242 Set a user-defined variable <var>name</var> to <var>value</var>.  These
 243 user-defined variables are made available in the configuration language as the
 244 parameters <samp>u-<var>name</var></samp> and are passed to the service in
 245 environment variables <samp>USERV_U_<var>name</var></samp>.  <var>name</var>
 246 may contain only alphanumerics and underscores, and must start with a letter.
 247 If several definitions are given for the same <var>name</var> then only the
 248 last is effective.
 249 </dd>
 250 </dl>
 251 <dl>
 252 <dt><samp>-t <var>seconds</var></samp></dt>
 253 <dt><samp>--timeout <var>seconds</var></samp></dt>
 254 <dd>
 255 Time out the service if it takes longer than <var>seconds</var> seconds (a
 256 positive integer, in decimal).  Timeout will produce a diagnostic on stderr and
 257 an exit status of 255.  If <var>seconds</var> is zero then no timeout will be
 258 implemented (this is the default).
 259 </dd>
 260 </dl>
 261 <dl>
 262 <dt><samp>--signals</samp> <var>method</var></dt>
 263 <dd>
 264 Affects the handling of the exit status when the service terminates due to a
 265 signal.  (The client will always finish by calling <code>_exit</code>, so that
 266 only numbers from 0 to 255 can be returned and not the full range of numbers
 267 and signal indications which can be returned by the <code>wait</code> family of
 268 system calls.)
 269
 270 <p>
 271 The <var>method</var> may be one of the following:
 272 <dl>
 273 <dt><var>status</var></dt>
 274 <dd>
 275 The client's exit status will be <var>status</var>.  This will not be
 276 distinguishable from the service really having exited with code
 277 <var>status</var>.  This method is the default, with a <var>status</var> of
 278 254.
 279 </dd>
 280 <dt><samp>number</samp></dt>
 281 <dt><samp>number-nocore</samp></dt>
 282 <dd>
 283 The client's exit status will be the number of the signal which caused the
 284 termination of the service.  If <samp>number</samp> is used rather than
 285 <samp>number-nocore</samp> then 128 will be added if the service dumped core.
 286 <samp>number</samp> is very like the exit code mangling done by the Bourne
 287 shell.
 288 </dd>
 289 <dt><samp>highbit</samp></dt>
 290 <dd>
 291 The client's exit status will be the number of the signal with 128 added.  If
 292 the service exits normally with an exit code of greater than 127 then 127 will
 293 be returned.
 294 </dd>
 295 <dt><samp>stdout</samp></dt>
 296 <dd>
 297 The service's numeric wait status as two decimal numbers (high byte first) and
 298 a textual description of its meaning will be printed to the client's standard
 299 output.  It will be preceded by a newline and followed by an extra newline, and
 300 the numbers are separated from each other and from the textual description by
 301 single spaces.  The exit status of the client will be zero, unless a system
 302 error occurs in which case no exit status and description will be printed to
 303 stdout, and an error message will be printed to stderr as usual.
 304 </dd>
 305 </dl>
 306
 307 <p>
 308 Problems such as client usage errors, the service not being found or permission
 309 being denied or failure of a system call are system errors.  An error message
 310 describing the problem will be printed on the client's stderr, and the client's
 311 exit status will be 255.  If the client dies due to a signal this should be
 312 treated as a serious system error.
 313 </dd>
 314 </dl>
 315 <dl>
 316 <dt><samp>-H</samp></dt>
 317 <dt><samp>--hidecwd</samp></dt>
 318 <dd>
 319 Prevents the calling process's current directory name from being passed to the
 320 service; the null string will be passed instead.
 321 </dd>
 322 </dl>
 323 <dl>
 324 <dt><samp>-P</samp></dt>
 325 <dt><samp>--sigpipe</samp></dt>
 326 <dd>
 327 If the service program is terminated due to a <code>SIGPIPE</code> the exit
 328 status of the client will be zero, even if it would have been something else
 329 according to the exit status method specified.  This option has no effect on
 330 the code and description printed if the exit status method <samp>stdout</samp>
 331 is in use.
 332 </dd>
 333 </dl>
 334 <dl>
 335 <dt><samp>-h</samp></dt>
 336 <dt><samp>--help</samp></dt>
 337 <dt><samp>--copyright</samp></dt>
 338 <dd>
 339 <samp>-h</samp> or <samp>--help</samp> prints the client's usage message;
 340 <samp>--copyright</samp> prints the copyright and lack of warranty notice.
 341 </dd>
 342 </dl>
 343
 344 <hr>
 345
 346 <a name="s-optoverride"></a>
 347 <h2>2.2 Security-overriding options</h2>
 348
 349 <p>
 350 There are also some options which are available for debugging and to allow the
 351 system administrator to override a user's policy.  These options are available
 352 only if the client is called by root or if the calling user is the same as the
 353 service user.
 354 <dl>
 355 <dt><samp>--override <var>configuration-data</var></samp></dt>
 356 <dt><samp>--override-file <var>filename</var></samp></dt>
 357 <dd>
 358 Do not read the usual configuration files.  Instead, the client sends
 359 <var>configuration-data</var> (followed by a newline) or the contents of
 360 <var>filename</var> (which is opened in the context of the client) to the
 361 daemon and the daemon uses that data instead.  The
 362 <var>configuration-data</var> must all be in one argument.  It will have a
 363 single newline appended so that a single directive can easily be given, but if
 364 more than one directive is required it will have to contain one or more real
 365 newlines.
 366 </dd>
 367 </dl>
 368 <dl>
 369 <dt><samp>--spoof-user <var>user</var></samp></dt>
 370 <dd>
 371 Pretend to the service that it is being called by <var>user</var> (which may be
 372 a username or a uid).  This will also affect the group and supplementary groups
 373 supplied to the service; they will be the standard group and supplementary
 374 groups for <var>user</var>.  The <samp>--spoof-user</samp> option will
 375 <em>not</em> affect which user is chosen if the service user is specified as
 376 just <samp>-</samp>; in this case the service user will be the real calling
 377 user.
 378 </dd>
 379 </dl>
 380
 381 <hr>
 382
 383 [ <a href="ch-intro.html">previous</a> ]
 384 [ <a href="index.html#contents">Contents</a> ]
 385 [ <a href="ch-intro.html">1</a> ]
 386 [ 2 ]
 387 [ <a href="ch-envir.html">3</a> ]
 388 [ <a href="ch-config.html">4</a> ]
 389 [ <a href="ch-ipass.html">5</a> ]
 390 [ <a href="ch-notes.html">6</a> ]
 391 [ <a href="ch-envir.html">next</a> ]
 392
 393 <hr>
 394
 395 <p>
 396 User service daemon and client specification
 397
 398 <address>
 399 1.0.3<br>
 400 Ian Jackson <code><a href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</a></code>
 401 </address>
 402
 403 <hr>
 404
 405 </body>
 406
 407 </html>
 408