chiark / gitweb /
mention bug
[userv.git] / spec.sgml.in
1 <!doctype debiandoc system>
2
3 <book>
4 <title>User service daemon and client specification
5 <author>Ian Jackson <email>ian@davenant.greenend.org.uk
6 <version></version>
7
8 <abstract>
9 This is a specification for a Unix system facility to allow one
10 program to invoke another when only limited trust exists
11 between them.
12
13 <copyright>
14 <prgn/userv/ is
15 Copyright 1996-2003,2006 Ian Jackson;
16 Copyright 2000 Ben Harris.
17 <p>
18
19 <prgn/userv/ is free software; you can redistribute it and/or modify
20 it under the terms of the GNU General Public License as published by
21 the Free Software Foundation; either version 2 of the License, or (at
22 your option) any later version.
23 <p>
24
25 This program is distributed in the hope that it will be useful, but
26 <em/without any warranty/; without even the implied warranty of
27 <em/merchantability/ or <em/fitness for a particular purpose/.  See
28 the GNU General Public License for more details.
29 <p>
30
31 You should have received a copy of the GNU General Public License
32 along with <prgn/userv/; if not, write to the Free Software
33 Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
34
35 <toc sect>
36
37 <chapt id="intro">Introduction
38 <p>
39 There is a daemon which invokes user service programs (henceforth
40 `services') in response to requests by callers of a companion client
41 program (henceforth the `client') and according to rules set forth in
42 system-wide and user-specific configuration files.  The companion
43 client program is setuid root, and negotiates with the daemon through
44 an <prgn/AF_UNIX/ socket and associated objects in a system-wide
45 private directory set aside for the purpose.  The user who wishes the
46 service to be performed and calls the client is called the `calling
47 user'; the process which calls the client is called the `calling
48 process'.
49
50 <p>
51 The daemon and the client are responsible for ensuring that
52 information is safely carried across the security boundary between the
53 two users, and that the processes on either side cannot interact with
54 each other in any unexpected ways.
55
56 <chapt id="client">Client program usage
57
58 <p>
59 <example>
60 userv <var/options/ [--] <var/service-user/ <var/service-name/ [<var/argument/ ...]
61 userv <var/options/ -B|--builtin [--] <var/builtin-service/ [<var/info-argument/ ...]
62 </example>
63 <p>
64
65 <var/service-user/ specifies which user is to provide the service.
66 The user may be a login name or a numeric uid, or <tt/-/ to indicate
67 that the service user is to be the same as the calling user.
68 <p>
69
70 The service name is interpreted by the userv<footnote><prgn/userv/ is
71 short for `user services', and is pronounced `you-serve'.</footnote>
72 daemon on behalf of the service user.  It will often be the name of a
73 program.
74
75 <sect>Options
76 <p>
77
78 Single-letter options may be combined as is usual with Unix programs,
79 and the value for such an option may appear in the same argument or in
80 the next.
81
82 <taglist>
83 <tag/<tt/-B//
84 <tag/<tt/--builtin//
85 <item>
86 Requests that a builtin service be provided.  This is equivalent to
87 using the <prgn/--override/ option to specify a string consisting of
88 <prgn/execute-builtin/ followed by the <var/builtin-service/
89 requested, and requesting a service user of <tt/-/ (indicating the
90 calling user).
91 <p>
92
93 If the builtin service being requested requires a
94 <var/service-argument/ then this must be supplied to the client in the
95 same argument as the <var/builtin-service/.  See <ref
96 id="dirs-execution"> for details of the builtin services available,
97 and <ref id="optoverride"> for details of the <prgn/--override/
98 options.
99 <p>
100
101 The actual service name passed will be the <var/builtin-service/; note
102 that this actual service name (as opposed to the override data) and
103 the <var/info-argument/s supplied will be ignored by most builtin
104 services; the override mechanism and <prgn/execute-builtin/ will be
105 used to ensure that the right builtin service is called with the right
106 <var/service-argument/s.
107
108 <tag/<tt/-f<var/fd/[<var/modifiers/]=<var/filename///
109 <tag/<tt/--file <var/fd/[<var/modifiers/]=<var/filename///
110 <item>
111 Requests that data be copied in and out of the service using pipes.
112 For each file or descriptor this will be done by creating a pipe, one
113 end of which is passed to the service program and the other end of
114 which is passed to a copy of <prgn/cat/ invoked by the client; the
115 other file descriptor passed to <prgn/cat/ will be one inherited by
116 the client program from the caller or one opened by the client program
117 on behalf of the caller.
118 <p>
119
120 The descriptor in the service program that should be connected must be
121 specified as <var/fd/, either as a decimal number or as one of the
122 strings <tt/stdin/, <tt/stdout/ or <tt/stderr/.  The next argument is
123 a filename which will be opened by the client with the privileges of
124 the calling user.
125
126 <p>
127 <var/modifiers/ is used to specify whether the file or descriptor is
128 to be read from or written to.  It consists of a series of words
129 separated by commas.  A comma may separate the <var/modifiers/ from
130 the <var/fd/ and is required if <var/fd/ is not numeric.
131
132 <p>
133 The modifier words are:
134 <taglist compact>
135 <tag/<tt/read//
136 <item>
137 <tt/O_RDONLY/: Allow reading and not writing.  May not be used with
138 <tt/write/ or things that imply it.
139
140 <tag/<tt/write//
141 <item>
142 <tt/O_WRONLY/: Allow writing and not reading.  <em/Doesn't truncate or
143 create/ without <tt/truncate/ or <tt/create/.  <tt/write/ or things
144 that imply it may not be used with <tt/read/.
145
146 <tag/<tt/overwrite//
147 <item>
148 Equivalent to <tt/write,create,truncate/.
149
150 <tag/<tt/create//
151 <tag/<tt/creat//
152 <item>
153 <tt/O_CREAT/: Creates the file if necessary.  Implies <tt/write/.
154
155 <tag/<tt/exclusive//
156 <tag/<tt/excl//
157 <item>
158 <tt/O_EXCL/: Fails if the file already exists.  Implies <tt/write/ and
159 <tt/create/.  May not be used with <tt/truncate/.
160
161 <tag/<tt/truncate//
162 <tag/<tt/trunc//
163 <item>
164 <tt/O_TRUNC/: Truncate any existing file.  Implies <tt/write/.
165 May not be used with <tt/exclusive/.
166
167 <tag/<tt/append//
168 <item>
169 <tt/O_APPEND/: All writes will append to the file.  Implies <tt/write/
170 (but not <tt/create/).
171
172 <tag/<tt/sync//
173 <item>
174 <tt/O_SYNC/: Do writes synchronously.  Implies <tt/write/.
175
176 <tag/<tt/wait//
177 <tag/<tt/nowait//
178 <tag/<tt/close//
179 <item>
180
181 These modifiers control the behaviour of the client, with respect to
182 the pipes carrying data to and from the service, when the service
183 terminates.  See below.
184
185 <tag/<tt/fd//
186 <item>
187 The <var/filename/ is not a filename but a numeric file descriptor.
188 One or both of <tt/read/ and <tt/write/ must be specified, and no
189 other words are allowed.  The <var/filename/ may also be <tt/stdin/,
190 <tt/stdout/ or <tt/stderr/ for file descriptor 0, 1 or 2 respectively.
191
192 </taglist>
193 <p>
194
195 If no <var/modifiers/ which imply <tt/read/ or <tt/write/ are used it
196 is as if <tt/write/ had been specified, except that if the
197 filedescriptor 0 of the service is being opened (either specified
198 numerically or with <tt/stdin/) it is as if <tt/overwrite/ had been
199 specified (or <tt/write/ if only <tt/fd/ was specified).
200 <p>
201
202 The client will also use <tt/O_NOCTTY/ when opening files specified by
203 the caller, to avoid changing its controlling terminal.
204 <p>
205
206 By default stdin, stdout and stderr of the service will be connected
207 to the corresponding descriptors on the client.  Diagnostics from
208 the client and daemon will also appear on stderr.
209 <p>
210
211 If <tt/wait/ is specified, the client will wait for the pipe to be
212 closed, and only exit after this has happened.  This means that either
213 the receiving end of the pipe connection was closed while data was
214 still available at the sending end, or that the end of file was
215 reached on the reading file descriptor.  Errors encountered reading or
216 writing in the client at this stage will be considered a system error
217 and cause the client to exit with status 255, but will not cause
218 disconnection at the service side since the service has already
219 exited.
220 <p>
221
222 If <tt/close/ is specified the client will immediately close the pipe
223 connection by killing the relevant copy of <prgn/cat/.  If the service
224 uses the descriptor it will get <prgn/SIGPIPE/ (or <prgn/EPIPE/) for a
225 writing descriptor or end of file for a reading one; the descriptor
226 opened by or passed to the client will also be closed.
227 <p>
228
229 If <tt/nowait/ is specified then the client will not wait and the
230 connection will remain open after the client terminates.  Data may
231 continue to be passed between the inheritors of the relevant
232 descriptor on the service side and the corresponding file or
233 descriptor on the client side until either side closes their
234 descriptor.  This should not usually be specified for stderr (or
235 stdout if <tt/--signals stdout/ is used) since diagnostics from
236 the service side may arrive after the client has exited and be
237 confused with expected output.
238 <p>
239
240 The default is <tt/wait/ for writing file descriptors and <tt/close/
241 for reading ones.
242
243 <tag/<tt/-w<var/fd/=<var/action///
244 <tag/<tt/--fdwait<var/fd/=<var/action///
245 <item>
246 Sets the action on termination of the service for the specified file
247 descriptor; <var/action/ must be <tt/wait/, <tt/nowait/ or <tt/close/
248 as described above.  The file descriptor must be specified as open
249 when this option is encountered; this option is overridden by any
250 later <prgn/--file/ or <prgn/--fdwait/ option - even by a
251 <prgn/--file/ which does not specify an action on termination (in this
252 case the default will be used, as described above).
253
254 <tag/<tt/-D<var/name/=<var/value///
255 <tag/<tt/--defvar <var/name/=<var/value///
256 <item>
257 Set a user-defined variable <var/name/ to <var/value/.  These
258 user-defined variables are made available in the configuration
259 language as the parameters <tt/u-<var/name// and are passed to the
260 service in environment variables <tt/USERV_U_<var/name//.  <var/name/
261 may contain only alphanumerics and underscores, and must start with a
262 letter.  If several definitions are given for the same <var/name/ then
263 only the last is effective.
264
265 <tag/<tt/-t <var/seconds///
266 <tag/<tt/--timeout <var/seconds///
267 <item>
268 Time out the service if it takes longer than <var/seconds/ seconds (a
269 positive integer, in decimal).  Timeout will produce a diagnostic on
270 stderr and an exit status of 255.  If <var/seconds/ is zero then no
271 timeout will be implemented (this is the default).
272
273 <tag/<tt/-S/ <var/method//
274 <tag/<tt/--signals/ <var/method//
275 <item>
276 Affects the handling of the exit status when the service terminates
277 due to a signal.  (The client will always finish by calling
278 <prgn/_exit/, so that only numbers from 0 to 255 can be returned and
279 not the full range of numbers and signal indications which can be
280 returned by the <prgn/wait/ family of system calls.)
281 <p>
282
283 The <var/method/ may be one of the following:
284 <taglist compact>
285 <tag/<var/status/
286 <item>
287 The client's exit status will be <var/status/.  This will not be
288 distinguishable from the service really having exited with code
289 <var/status/.  This method is the default, with a <var/status/ of 254.
290
291 <tag/<tt/number//
292 <tag/<tt/number-nocore//
293 <item>
294 The client's exit status will be the number of the signal which caused
295 the termination of the service.  If <tt/number/ is used rather than
296 <tt/number-nocore/ then 128 will be added if the service dumped core.
297 <tt/number/ is very like the exit code mangling done by the Bourne
298 shell.
299
300 <tag/<tt/highbit//
301 <item>The client's exit status will be the number of the signal with
302 128 added.  If the service exits normally with an exit code of greater
303 than 127 then 127 will be returned.
304
305 <tag/<tt/stdout//
306 <item>
307 The service's numeric wait status as two decimal numbers (high byte
308 first) and a textual description of its meaning will be printed to the
309 client's standard output.  It will be preceded by a newline and
310 followed by an extra newline, and the numbers are separated from each
311 other and from the textual description by single spaces.  The exit
312 status of the client will be zero, unless a system error occurs in
313 which case no exit status and description will be printed to stdout,
314 and an error message will be printed to stderr as usual.
315 </taglist>
316
317 <p>
318 Problems such as client usage errors, the service not being found or
319 permission being denied or failure of a system call are system errors.
320 An error message describing the problem will be printed on the
321 client's stderr, and the client's exit status will be 255.  If the
322 client dies due to a signal this should be treated as a serious system
323 error.
324
325 <tag/<tt/-H//
326 <tag/<tt/--hidecwd//
327 <item>
328 Prevents the calling process's current directory name from being
329 passed to the service; the null string will be passed instead.
330
331 <tag/<tt/-P//
332 <tag/<tt/--sigpipe//
333 <item>
334 If the service program is terminated due to a <prgn/SIGPIPE/ the exit
335 status of the client will be zero, even if it would have been
336 something else according to the exit status method specified.  This
337 option has no effect on the code and description printed if the exit
338 status method <tt/stdout/ is in use.
339
340 <tag/<tt/-h//
341 <tag/<tt/--help//
342 <tag/<tt/--copyright//
343 <item>
344 <tt/-h/ or <tt/--help/ prints the client's usage message;
345 <tt/--copyright/ prints the copyright and lack of warranty notice.
346
347 </taglist>
348
349 <sect id="optoverride">Security-overriding options
350 <p>
351
352 There are also some options which are available for debugging and to
353 allow the system administrator to override a user's policy.  These
354 options are available only if the client is called by root or if the
355 calling user is the same as the service user.
356
357 <taglist>
358
359 <tag/<tt/--override <var/configuration-data///
360 <tag/<tt/--override-file <var/filename///
361 <item>
362 Do not read the usual configuration files.  Instead, the client sends
363 <var/configuration-data/ (followed by a newline) or the contents of
364 <var/filename/ (which is opened in the context of the client) to the
365 daemon and the daemon uses that data instead.  The
366 <var/configuration-data/ must all be in one argument.  It will have a
367 single newline appended so that a single directive can easily be
368 given, but if more than one directive is required it will have to
369 contain one or more real newlines.
370
371 <tag/<tt/--spoof-user <var/user///
372 <item>
373 Pretend to the service that it is being called by <var/user/ (which
374 may be a username or a uid).  This will also affect the group and
375 supplementary groups supplied to the service; they will be the
376 standard group and supplementary groups for <var/user/.  The
377 <tt/--spoof-user/ option will <em/not/ affect which user is chosen if
378 the service user is specified as just <tt/-/; in this case the service
379 user will be the real calling user.
380
381 </taglist>
382
383
384 <chapt id="envir">Execution environment of the service program
385 <p>
386
387 The daemon which is handling the service user side of things will read
388 configuration files to decide what to do.  If it decides to allow the
389 service to be provided it will fork a subprocess to execute the
390 service.
391 <p>
392
393 The service will have no controlling terminal, but it will be a
394 process group leader.
395 <p>
396
397 If the client is killed or times out or a file or descriptor being
398 read or written by the client process gets an error then the service
399 will be disconnected from the client.  The client will return an exit
400 status of 255 and some the service's pipes may be closed at the other
401 end.  The service will become a child of <prgn/init/.  The service may
402 well not notice the disconnection, though writing to a pipe after this
403 may produce a <prgn/SIGPIPE/ and the facility exists to have a
404 <prgn/SIGHUP/ sent to the service on disconnection.
405
406 <sect>File descriptors
407 <p>
408
409 The service program's standard filedescriptors, and possibly other
410 file descriptors, will be connected to pipes or to
411 <prgn>/dev/null</>.  The <prgn/userv/ client/daemon pair will arrange
412 that data is copied between the files or file descriptors specified to
413 to the client by the caller and these these pipes.
414 <p>
415
416 Pipes which may be written to will be closed if a write error occurs
417 on the corresponding client-side file or descriptor, which may result
418 in a <prgn/SIGPIPE/ in the service program; pipes open for reading
419 will get <prgn/EOF/ if the client-side file descriptor gets <prgn/EOF/
420 or an error.
421 <p>
422
423 If the service closes one of its reading file descriptors the writing
424 end of the corresponding pipe will generate a <prgn/SIGPIPE/ when
425 attempts are made by the client/daemon pair to write to it.  This will
426 not be considered an error; rather, the relevant pipe will be
427 discarded and the corresponding file or file descriptor held by the
428 client will be closed.
429 <p>
430
431 Likewise, if one of the file descriptors held by the client for
432 writing by the service is a pipe whose other end is closed by the
433 caller then the client/daemon pair will see an error when trying to
434 copy data provided by the service.  This too will not be considered an
435 error; rather, the pipe correspondong to that descriptor will be
436 closed and any further writes will cause the service to get a
437 <prgn/SIGPIPE/.
438 <p>
439
440 Note that not all write errors or broken pipes on file descriptors may
441 be visible to the service, since buffered data may be discarded by the
442 operating system and there will be a finite interval between the error
443 happening and the service being disconnected from the client or the
444 next write causing a <prgn/SIGPIPE/.
445 <p>
446
447 Read errors on file descriptors (and disconnection) will only be
448 visible to the service and distinguishable from normal end of file if
449 <prgn/disconnect-hup/ is in effect.
450 <p>
451
452 Read and write errors (other than broken pipes, as described above)
453 will always be visible to the caller; they are system errors, and will
454 therefore cause the client to print an error message to stderr and
455 return with an exit status of 255.
456 <p>
457
458 If the main service program process exits while it still has running
459 children any file descriptors held by those children can remain open,
460 depending on the use of <tt/wait/, <tt/nowait/ or <tt/close/ for the
461 relevant file descriptor in the client's arguments.  By default
462 writing filedescriptors remain open and the client will wait for them
463 to be closed at the service end, and reading file descriptors are
464 closed immediately.  These leftover child processes will not get a any
465 <prgn/SIGHUP/ even if a read or write error occurs or the client
466 disconnects before then.
467
468 <sect>Environment
469 <p>
470
471 The service will have some information in environment variables:
472 <taglist compact>
473 <tag/<tt/USERV_USER//
474 <item>
475 The login name of the calling user.  If the <prgn/LOGNAME/ variable is
476 set (or, if that is unset, if the <prgn/USER/ variable is set) in the
477 environment passed to the client by the caller then the password entry
478 for that login name will be looked up; if that password entry's uid is
479 the same as that of the calling process then that login name will be
480 used, otherwise (or if neither <prgn/LOGNAME/ nor <prgn/USER/ is set)
481 the calling process's uid will be looked up to determine their login
482 name (and if this lookup fails then the service will not be invoked).
483
484 <tag/<tt/USERV_UID//
485 <item>
486 The uid of the calling process.
487
488 <tag/<tt/USERV_GID//
489 <item>
490 The gid and supplementary group list of the calling process: first the
491 group in gid and then those in the supplementary group list, in
492 decimal, separated by spaces.
493
494 <tag/<tt/USERV_GROUP//
495 <item>
496 The group names of the calling process, listed in the same way as the
497 ids are in <prgn/USERV_GID/.  If no name can be found for any of the
498 calling process's group(s) then the service will not be invoked.
499
500 <tag/<tt/USERV_CWD//
501 <item>
502 The client's current working directory name (this directory may not be
503 accessible to the service).  If it could not be determined or the
504 <prgn/--hidecwd/ flag was used then this variable will be set to an
505 empty string (this is not considered an error).
506
507 <tag/<tt/USERV_SERVICE//
508 <item>
509 The service name requested by the caller.
510
511 <tag/<tt/USERV_U_<var/name///
512 <item>
513 The value supplied to the client by the caller using -D<var/name/.
514
515 </taglist>
516
517 <prgn/HOME/, <prgn/PATH/, <prgn/SHELL/, <prgn/LOGNAME/ and <prgn/USER/
518 will be set appropriately (according to the details of the service
519 user).
520
521
522 <chapt id="config">Service-side configuration
523 <p>
524
525 Which services may be run by whom and under what conditions is
526 controlled by configuration files.
527 <p>
528
529 The daemon will read these files in order.  Certain directives in the
530 files modify the daemon's execution settings for invoking the service,
531 for example allowing certain file descriptors to be specified by the
532 client or specifying which program to execute to provide the service.
533 <p>
534
535 The <em/last/ instance of each such setting will take effect.  The
536 directives which specify which program to execute will not stop the
537 configuration file from being read; they will be remembered and will
538 only take effect if they are not overridden by a later directive.
539 <p>
540
541 The daemon will first read <tt>/etc/userv/system.default</>.  Then, by
542 default (this behaviour may be modified), it will read a per-user file
543 <tt>~/.userv/rc</>, if it exists and the service user's shell is in
544 <tt>/etc/shells</>.  Finally it will read
545 <tt>/etc/userv/system.override</>.
546 <p>
547
548 When it has read all of these files it will act according to the
549 currently values of of the execution settings.
550
551 <sect>Configuration file syntax
552 <p>
553
554 The configuration file is a series of directives, usually one per
555 line.  The portion of a line following a hash character <tt/#/ is
556 taken as a comment and ignored.  Each directive consists of a series
557 of tokens separated by linear whitespace (spaces and tabs); tokens may
558 be words consisting of non-space characters, or, where a string is
559 required, a string in double quotes.  Double-quoted strings may
560 contain the following backslash escapes:
561
562 <taglist compact>
563 <tag/<tt/\n//<item>newline
564 <tag/<tt/\t//<item>tab
565 <tag/<tt/\r//<item>carriage return
566 <tag/<tt/\<var/OOO///<item>character whose octal code is <var/OOO/
567 <tag/<tt/\x<var/XX///<item>character whose hex code is <var/XX/
568 <tag/<tt/\<var/punctuation///<item>literal punctuation character (eg <tt/\\/, <tt/\"/)
569 <tag/<tt/\<var/newline// (ie, backslash at end of line)/
570 <item>string continues on next line
571 </taglist>
572 <p>
573
574 Relative pathnames in directives are relative to the service program's
575 current directory (usually the service user's home directory).
576 Pathnames starting with the two characters <tt>~/</> are taken to be
577 relative to the service user's home directory.
578
579 <sect id="directives">Configuration file directives
580 <p>
581
582 <sect1 id="dirs-immediate">Immediate directives
583 <p>
584
585 The following directives take effect immediately:
586
587 <taglist>
588 <tag/<tt/cd <var/pathname///
589 <item>
590 Change directory in the service program.  <prgn/cd/ is cumulative.  It
591 is an error if the directory cannot be changed to.
592 <p>
593
594 <prgn/cd/ should not be used between <prgn/execute-from-directory/ and
595 the invocation of the service program, as the test for the
596 availability of the service program would be done with the old current
597 directory and the actual execution with the new (probably causing an
598 error).
599
600 <tag/<tt/eof//
601 <item>
602 Stop reading the configuration file in question, as if end of file had
603 been reached.  Any control constructs (<prgn/if/, <prgn/catch-quit/ or
604 <prgn/errors-push/) which were started in that file will be considered
605 finished.  Parsing will continue in the file which caused the file
606 containing the <prgn/eof/ to be read.
607
608 <tag/<tt/quit//
609 <item>
610 Stop reading configuration files and act immediately on the current
611 settings.  The behaviour of <prgn/quit/ is subject to the
612 <prgn/catch-quit/ control construct.
613
614 <tag/<tt/include <var/filename///
615 <tag/<tt/include-ifexist <var/filename///
616 <item>
617 Read the configuration file <var/filename/, and then return to this
618 file and continue parsing it with the next directive.  It is an error
619 if the file cannot be opened and read, unless <prgn/include-ifexist/
620 is used and the file does not exist, in which case the directive is
621 silently ignored.
622
623 <tag/<tt/include-lookup <var/parameter/ <var/directory///
624 <tag/<tt/include-lookup-all <var/parameter/ <var/directory///
625 <item>
626 Read the configuration file in <var/directory/ whose name is the value
627 of <var/parameter/ (see the description of <prgn/if/, <ref
628 id="dirs-control">).  If <var/parameter/ has several values they will
629 be tried in order; with <prgn/include-lookup/ this search will stop
630 when one is found, but with <prgn/include-lookup-all/ the search will
631 continue and any files appropriate to other values will be read too.
632 <p>
633
634 If none of the parameter's values had a corresponding file then the
635 file <tt/:default/ will be read, if it exists.  If <var/parameter/'s
636 list of values was empty then the file <tt/:none/ will be tried first
637 and read if it exists, otherwise <tt/:default/ will be tried.
638 <p>
639
640 It is not an error for any of the files (including <tt/:default/) not
641 to exist, but it is an error if a file exists and cannot be read or if
642 the directory cannot be accessed.
643
644 <p>
645 A translation will be applied to values before they are used to
646 construct a filename, so that the lookup cannot access dotfiles or
647 files in other directories: values starting with full stops will have
648 a colon prepended (making <tt/:./), colons will be doubled, and each
649 slash will be replaced with a colon followed by a hyphen <tt>:-</>.  A
650 parameter value which is the empty string will be replaced with
651 <tt/:empty/ (note that this is different from a parameter not having
652 any values).
653
654 <tag/<tt/include-directory <var/directory///
655 <item>
656 Read configuration from all files in directory <var/directory/ which
657 are plain files whose names consist only of alphanumerics and hyphens
658 and start with an alphanumeric.  They will be read in lexical order.
659 It is an error for the directory not to exist or for it or any of the
660 files found not to be read successfully, or for anything with an
661 appropriate name not to be a plain file or a symbolic link to a plain
662 file.
663
664 <tag/<tt/error <var/text ...///
665 <item>
666 Causes an error whose message includes the descriptive string
667 <var/text/.  <var/text/ may consist of several tokens with intervening
668 whitespace.  The whitespace will be included in the message as found
669 in the configuration file: all the characters until the end of the
670 line will be included verbatim, unless they are part of a
671 double-quoted string, in which case the usual meaning of the string
672 (i.e., after backslash escape processing) will be used.  Comments and
673 linear whitespace at the end of the line (or just before the comment)
674 will still be ignored.
675
676 <tag/<tt/message <var/text ...///
677 <item>
678 Causes a message including the descriptive string <var/text/ to be
679 delivered as if it were an error message, but does not actually cause
680 an error.
681 </taglist>
682
683 <sect1 id="dirs-delayed">Directives with delayed effect
684 <p>
685
686 The following directives have no immediate effect, but are remembered
687 and have an effect on later processing of the configuration files.
688
689 <taglist>
690 <tag/<tt/user-rcfile <var/filename///
691 <item>
692 Specifies that the file <var/filename/ should be read instead of the
693 user's <tt>~/.userv/rc</>.  This does <em/not/ happen immediately;
694 instead, the setting is remembered and used after the
695 <prgn/system.default/ configuration file has been read.  This
696 directive has no effect in a user's configuration file or in the
697 <prgn/system.override/ file, as the user's configuration file has
698 already been found and read by then and will not be re-read.
699
700 <tag/<tt/errors-to-stderr//
701 <item>
702 Causes error messages to be delivered to the client's stderr.
703
704 <tag/<tt/errors-to-file/ <var/filename//
705 <item>
706 Error messages will be written to <var/filename/, which will be opened
707 in the context of and with the privileges of the service user.
708
709 <tag/<tt/errors-to-syslog/ [<var/facility/ [<var/level/]]/
710 <item>
711 Error messages will be delivered using <prgn/syslog/.  The default
712 <var/facility/ is <tt/user/; the default <var/level/ is <tt/error/.
713 </taglist>
714
715 <sect1 id="dirs-control">Control structure directives
716 <p>
717
718 The following directives are used to create control structures.  If
719 the end of the file is encountered before the end of any control
720 structure which was started inside it then that control structure is
721 considered finished.  This is not an error.
722
723 <taglist>
724 <tag/<tt/if <var/condition///
725 <tag/<tt/elif <var/condition///
726 <tag/<tt/else//
727 <tag/<tt/fi//
728 <item>
729 Lines following <prgn/if/ are interpreted only if the condition is
730 true.  Many conditions are properties of parameter values.  Most
731 parameters have a single string as a value; however, some may yield
732 zero or several strings, in which case the condition is true if it is
733 true of any of the strings individually.  Parameters are described
734 below.
735 <p>
736
737 The conditions are:
738
739 <taglist compact>
740 <tag/<tt/glob <var/parameter/ <var/glob-pattern/ ...//
741 <item>
742 The value of the parameter whose name is given matches one of the glob
743 patterns (anchored at both ends; backslashes can be used to escape
744 metacharacters).
745
746 <tag/<tt/range <var/parameter/ <var/min/ <var/max///
747 <item>
748 The value of the parameter is a nonnegative integer and lies within
749 the range specified.  <var/min/ or <var/max/ may be <tt/$/ to indicate
750 no lower or upper limit, respectively.
751
752 <tag/<tt/grep <var/parameter/ <var/filename///
753 <item>
754 The <var/filename/ refers to a file one of whose lines is the value of
755 the parameter (leading or trailing whitespace on each line and empty
756 lines in the file are ignored).  It is an error for the file not to be
757 opened and read.
758
759 <tag/<tt/! <var/condition///
760 <item>
761 The <var/condition/ is <em/not/ true.
762
763 <tag/Conjunctions: <tt/&amp;/ and <tt/|//
764 <item>
765 <example>
766 ( <var/condition/
767 &amp; <var/condition/
768 &amp; <var/condition/
769 ...
770 )
771 </example>
772 is true if all the listed conditions are true; where <tt/|/ is used it
773 is true if any of them is true.  Newlines must be used to separate one
774 condition from the next, as shown, and the parentheses are mandatory.
775 These conjunctions do not do lazy evaluation.
776 </taglist>
777 <p>
778
779 The parameters are:
780
781 <taglist compact>
782 <tag/<tt/service//
783 <item>
784 The service name specified when the client was called.
785
786 <tag/<tt/calling-user//
787 <item>
788 Two strings: the login name of the calling user (determined as for
789 <prgn/USERV_USER/, above) and the calling uid (represented in
790 decimal).
791
792 <tag/<tt/calling-group//
793 <item>
794 Several strings: the primary and supplementary group names and gids
795 (in decimal) of the calling process.  All the group names come first,
796 and then the gids.  If the first supplementary group is the same as
797 the primary group then it is elided.
798
799 <tag/<tt/calling-user-shell//
800 <item>
801 The calling user's shell, as listed in the password entry for the
802 calling login name (as determined for <prgn/USERV_USER/, above).
803
804 <tag/<tt/service-user//
805 <item>
806 Two strings: the name of the service user (as specified to the client)
807 and their uid (represented in decimal).
808
809 <tag/<tt/service-group//
810 <item>
811 Several strings: the primary and supplementary group names and gids
812 (in decimal) of the service user.
813
814 <tag/<tt/service-user-shell//
815 <item>
816 The service user's shell, as listed in their password entry.
817
818 <tag/<tt/u-<var/name///
819 <item>
820 The value of the user-defined variable <var/name/ passed by the caller
821 using the <prgn/--defvar/ command-line option to the client.  If the
822 variable was not defined then this parameter is an empty list of
823 strings; in this case any condition which tests it will be false, and
824 <tt/include-lookup/ on it will read the <tt/:none/ file, or
825 <tt/:default/ if <tt/:none/ is not found.
826
827 </taglist>
828
829 <tag/<tt/errors-push/ <var/filename//
830 <tag/<tt/srorre//
831 <item>
832 Stacks the error handling behaviour currently in effect.  Any changes
833 to error handling will take effect only between <prgn/errors-push/ and
834 <prgn/srorre/.
835
836 <tag/<tt/catch-quit//
837 <tag/<tt/hctac//
838 <item>
839 Any use of <prgn/quit/ inside <prgn/catch-quit/ will merely cause the
840 parsing to continue at <prgn/hctac/ instead.  Any control constructs
841 started since the <prgn/catch-quit/ will be considered finished if a
842 <prgn/quit/ is found.
843 <p>
844
845 If an error occurs inside <prgn/catch-quit/ the execution settings
846 will be reset (as if by the <prgn/reset/ directive) and parsing will
847 likewise continue at <prgn/hctac/.
848 <p>
849
850 If a lexical or syntax error is detected in the same configuration
851 file as the <prgn/catch-quit/, while looking for the <prgn/hctac/
852 after an error or <prgn/quit/, that new error will not be caught.
853
854 </taglist>
855
856 <sect1 id="dirs-execution">Directives for changing execution settings
857 <p>
858
859 The following directives modify the execution settings; the server
860 will remember the fact that the directive was encountered and act on
861 it only after all the configuration has been parsed.  The <em/last/
862 directive which modifies any particuar setting will take effect.
863
864 <taglist>
865 <tag/<tt/reject//
866 <item>
867 Reject the request.  <prgn/execute/, <prgn/execute-from-directory/ and
868 <prgn/execute-from-path/ will change this setting.
869
870 <tag/<tt/execute <var/program/ [<var/argument/ ...]//
871 <item>
872 Execute the program <var/program/, with the arguments as specified,
873 followed by any arguments given to the client if
874 <prgn/no-suppress-args/ is in effect.  It is an error for the
875 execution to fail when it is attempted (after all the configuration
876 has been parsed).  If <var/program/ does not contain a slash it will
877 be searched for on the service user's path.
878
879 <tag/<tt/execute-from-directory <var/pathname/ [<var/argument/ ...]//
880 <item>
881 Take all the characters after the last slash of the service name
882 specified when the client was called, and execute that program in the
883 directory named by <var/pathname/ as if it had been specified for
884 <var/execute/.  The part of the service name used may contain only
885 alphanumerics and hyphens and must start with an alphanumeric (and it
886 must be non-empty), otherwise it is an error.
887 <p>
888
889 This directive is ignored if the relevant program does not exist in
890 the directory specified; in this case the program to execute is left
891 at its previous setting (or unset, if it was not set before).
892 <p>
893
894 It is an error for the test for the existence of the program to fail
895 other than with a `no such file or directory' indication.  It is also
896 an error for the execution to fail if and when it is attempted (after
897 all the configuration has been parsed).
898
899 <tag/<tt/execute-from-path//
900 <item>
901 <var/service/ is interpreted as a program on the default <prgn/PATH/
902 (or as a pathname of an executable, if it contains a <tt>/</>).  This
903 directive is <em/very dangerous/, and is only provided to make the
904 <prgn/--override/ options effective.  It should not normally be used.
905 It is an error for the execution to fail when it is attempted (after
906 all the configuration has been parsed).
907
908 <tag/<tt/execute-builtin <var/service-name/ <var/service-arguments//
909 <item>
910 Executes the builtin service <var/service-name/.  These builtin
911 services display information about the server and/or the request, and
912 ignore any arguments passed from the service side except possibly to
913 print them as part of their output.  They write their results to their
914 standard output (i.e., wherever file descriptor 1 is directed).  The
915 builtin services are:
916
917 <taglist compact>
918 <tag/<tt/execute//
919 <item>
920 Displays the execution settings, defined variables,
921 arguments, etc. with which the builtin service was invoked.
922
923 <tag/<tt/environment//
924 <item>
925 Displays the environment variable settings with which the builtin
926 service was invoked.
927
928 <tag/<tt/parameter <var/parameter///
929 <item>
930 Displays the values of the service configuration language parameter
931 specified.
932
933 <tag/<tt/version//
934 <item>
935 Displays the version string and compilation details of the uservd
936 server program.
937
938 <tag/<tt/reset//
939 <item>
940 Displays the default reset configuration (evaluated when <prgn/reset/
941 is found in a configuration file, or when an error is caught by
942 <prgn/catch-quit/).
943
944 <tag/<tt/toplevel//
945 <item>
946 Displays the top-level default configuration (the configuration data,
947 evaluated by the server, which calls all the other configuration
948 files).
949
950 <tag/<tt/override//
951 <item>
952 Displays the top-level override configuration (the configuration data,
953 evaluated by the server, which causes all the other configuration data
954 to be parsed).
955
956 <tag/<tt/help//
957 <item>
958 Displays a list of the understood builtin service names and arguments.
959 </taglist>
960
961 In the future other builtin services may be defined which do more than
962 just print information.
963
964 <tag/<tt/set-environment//
965 <tag/<tt/no-set-environment//
966 <item>
967 Runs <tt>/etc/environment</> to set the service user's environment.
968 This adds the overhead of invoking a shell, but doesn't cause any
969 shell (de)mangling of the service's arguments.  This is achieved by
970 invoking
971 <example>
972 .../program arg arg arg ...
973 </example>
974 as
975 <example>
976 /bin/sh -c '. /etc/environment; exec "$@"' - .../program arg arg arg ...
977 </example>
978 <prgn/no-set-environment/ cancels the effect of
979 <prgn/set-environment/.
980
981 <tag/<tt/no-suppress-args//
982 <tag/<tt/suppress-args//
983 <item>
984 Include any arguments given to the client as arguments to the program
985 invoked as a result of an <prgn/execute/,
986 <prgn/execute-from-directory/ or <prgn/execute-from-path/ directive.
987 <prgn/suppress-args/ undoes the effect of <prgn/no-suppress-args/.
988
989 <tag/<tt/require-fd <var/fd-range/ read|write//
990 <item>
991 Insist that the filedescriptor(s) be opened for reading resp. writing.
992 It is an error if any descriptor marked as required when the service
993 is about to be invoked (after the configuration has been parsed) was
994 not specified when the client was invoked.  Each file descriptor has a
995 separate setting, and the last one of <prgn/require-fd/,
996 <prgn/allow-fd/, <prgn/ignore-fd/, <prgn/null-fd/ or <prgn/reject-fd/
997 which affected a particular file descriptor will take effect.
998 <p>
999
1000 <var/fd-range/ may be a single number, two numbers separated by a
1001 hyphen, or one number followed by a hyphen (indicating all descriptors
1002 from that number onwards).  It may also be one of the words
1003 <tt/stdin/, <tt/stdout/ or <tt/stderr/.  Open-ended file descriptor
1004 rangers are allowed only with <prgn/reject-fd/ and <prgn/ignore-fd/,
1005 as otherwise the service program would find itself with a very large
1006 number of file descriptors open.
1007 <p>
1008
1009 When the configuration has been parsed, and before the service is
1010 about to be executed, stderr (fd 2) must be required or allowed
1011 (<prgn/require-fd/ or <prgn/allow-fd/) for writing; this is so that
1012 the error message printed by the server's child process if it cannot
1013 <prgn/exec/ the service program is not lost.
1014
1015 <tag/<tt/allow-fd <var/fd-range/ [read|write]//
1016 <item>
1017 Allow the descriptor(s) to be opened for reading resp. writing, or
1018 either if neither <tt/read/ nor <tt/write/ is specified.  If a
1019 particular descriptor not specified by the client then it will be open
1020 onto <tt>/dev/null</> (for reading, writing, or both, depending on
1021 whether <tt/read/, <tt/write/ or neither was specified).
1022
1023 <tag/<tt/null-fd <var/fd-range/ [read|write]//
1024 <item>
1025 Specify that the descriptor(s) be opened onto <prgn>/dev/null</> for
1026 reading resp. writing, or both if neither <tt/read/ nor <tt/write/
1027 is specified.  Any specification of these file descriptors by the
1028 client will be silently ignored; the client will see its ends of the
1029 descriptors being closed immediately.
1030
1031 <tag/<tt/reject-fd <var/fd-range///
1032 <item>
1033 Do not allow the descriptor(s) to be specified by the client.  It is
1034 an error if any descriptor(s) marked for rejection are specified when
1035 the service is about to be invoked (after the configuration has been
1036 parsed).
1037
1038 <tag/<tt/ignore-fd <var/fd-range///
1039 <item>
1040 Silently ignore any specification by the client of those
1041 descriptor(s).  The pipes corresponding to these descriptors will be
1042 closed just before the service is invoked.
1043
1044 <tag/<tt/disconnect-hup//
1045 <tag/<tt/no-disconnect-hup//
1046 <item>
1047 Causes the service's process group to get a <prgn/SIGHUP/ if the
1048 client disconnects before the main service process terminates.
1049 <prgn/no-disconnect-hup/ cancels <prgn/disconnect-hup/.
1050 <p>
1051
1052 If one of the reading descriptors specified when the client is called
1053 gets a read error, or if the service is disconnected for some other
1054 reason, then the <prgn/SIGHUP/ will be delivered <em/before/ the
1055 writing end(s) of the service's reading pipe(s) are closed, so that
1056 the client can distinguish disconnection from reading EOF on a pipe.
1057
1058 <tag/<tt/reset//
1059 <item>
1060 Resets the execution settings to the default.  This is equivalent to:
1061 <example>
1062 cd ~/
1063 reject
1064 no-set-environment
1065 suppress-args
1066 allow-fd 0 read
1067 allow-fd 1-2 write
1068 reject-fd 3-
1069 disconnect-hup
1070 </example>
1071
1072 </taglist>
1073
1074 If no <prgn/execute/, <prgn/execute-from-path/,
1075 <prgn/execute-from-directory/ or <prgn/builtin/ is interpreted before
1076 all the files are read then the request is rejected.
1077
1078
1079 <sect id="configerrors">Errors in the configuration file
1080 <p>
1081
1082 If a syntax error or other problem occurs when processing a
1083 configuration file then a diagnostic will be issued, to wherever the
1084 error messages are currently being sent (see the <prgn/errors-/ family
1085 of directives, above).
1086 <p>
1087
1088 The error will cause processing of the configuration files to cease at
1089 that point, unless the error was inside a <prgn/catch-quit/ construct.
1090 In this case the settings controlling the program's execution will be
1091 reset to the defaults as if a <prgn/reset/ directive had been issued,
1092 and parsing continues after <prgn/hctac/.
1093
1094
1095 <sect id="defaults">Defaults
1096 <p>
1097
1098 The default configuration processing is as if the daemon were parsing
1099 an overall configuration file whose contents were as follows:
1100
1101 <example>
1102 reset
1103 user-rcfile ~/.userv/rc
1104 errors-to-stderr
1105 include /etc/userv/system.default
1106 if grep service-user-shell /etc/shells
1107    errors-push
1108      catch-quit
1109        include-ifexist <var/file specified by most recent user-rcfile directive/
1110      hctac
1111    srorre
1112 fi
1113 include /etc/userv/system.override
1114 quit
1115 </example>
1116 <p>
1117
1118 If one of the <prgn/--override/ options to the client is used then it
1119 will instead be as if the daemon were parsing an overall configuration
1120 as follows:
1121
1122 <example>
1123 reset
1124 errors-to-stderr
1125 include <var/file containing configuration data sent by client/
1126 quit
1127 </example>
1128
1129
1130 <chapt id="ipass">Information passed through the client/daemon combination
1131 <p>
1132
1133 The information described below is the only information which passes
1134 between the caller and the service.
1135
1136 <list>
1137 <item>
1138 The service name supplied by the caller is available in the
1139 configuration language for deciding whether and which service program
1140 to invoke, in the <prgn/service/ parameter, and is used by the
1141 <prgn/execute-from-directory/ and <prgn/execute-from-path/
1142 configuration directives.  It is usually used to select which service
1143 program to invoke.  It is also passed to the service program in the
1144 <prgn/USERV_SERVICE/ environment variable.
1145
1146 <item>
1147 File descriptors specified by the client and allowed according to the
1148 configuration language will be connected.  Each file descriptor is
1149 opened for reading or writing.  Communication is via pipes, one end of
1150 each pipe being open on the appropriate file descriptor in the service
1151 program (when it is invoked) and the other end being held by the
1152 client process, which will read and write files it opens on behalf of
1153 its caller or file descriptors it is passed by its caller.
1154 <p>
1155
1156 Data may be passed into the service through reading pipes and out of
1157 it through writing pipes.  These pipes can remain open only until the
1158 service and client have terminated, or can be made to stay open after
1159 the client has terminated and (if the service program forks) the main
1160 service process has exited; the behaviour is controlled by options
1161 passed to the client by its caller.
1162 <p>
1163
1164 The caller can arrange that a writing pipe be connected to a pipe or
1165 similar object and cause attempts to write to that descriptor by the
1166 service to generate a <prgn/SIGPIPE/ (or <prgn/EPIPE/ if
1167 <prgn/SIGPIPE/ is caught or ignored) in the service.
1168 <p>
1169
1170 Likewise, the service can close filedescriptors specified for reading,
1171 which will cause the corresponding filedescriptors passed by the
1172 caller to be closed, so that if these are pipes processes which write
1173 to them will receive <prgn/SIGPIPE/ or <prgn/EPIPE/.
1174
1175 <item>
1176 If <prgn/no-suppress-args/ is set then arguments passed to the client
1177 by its caller will be passed on, verbatim, to the service.
1178
1179 <item>
1180 Fatal signals and system call failures experienced by the client will
1181 result in the disconnection of the service from the client and
1182 possibly some of the communication file descriptors described above;
1183 if <prgn/disconnect-hup/ is set then the service will also be sent a
1184 <prgn/SIGHUP/.
1185
1186 <item>
1187 The value of the <prgn/LOGNAME/ (or <prgn/USER/) environment variable
1188 as passed to the client will be used as the login name of the calling
1189 user if the uid of the calling process matches the uid corresponding
1190 to that login name.  Otherwise the calling uid's password entry will
1191 be used to determine the calling user's login name.
1192 <p>
1193
1194 This login name and the calling uid are available in the configuration
1195 language in the <prgn/calling-user/ parameter and are passed to the
1196 service program in environment variables <prgn/USERV_USER/ and
1197 <prgn/USERV_UID/.
1198 <p>
1199
1200 The shell corresponding to that login name (according to the password
1201 entry) is available as in the configuration language's
1202 <prgn/calling-user-shell/ parameter.
1203 <p>
1204
1205 If no relevant password entry can be found then no service will be
1206 invoked.
1207
1208 <item>
1209 The numeric values and textual names for calling gid and supplementary
1210 group list are available in the configuration language in the
1211 <prgn/calling-group/ parameter and are passed to the service in
1212 environment variables.
1213 <p>
1214
1215 If no name can be found for a numeric group to which the calling
1216 process belongs then no service will be invoked.
1217
1218 <item>
1219 The name of the current working directory in which the client was
1220 invoked is passed, if available and not hidden using <prgn/--hidecwd/,
1221 to the service program in the <prgn/USERV_CWD/ variable.  This grants no
1222 special access to that directory unless it is a subdirectory of a
1223 directory which is executable (searchable) but not readable by the
1224 service user.
1225
1226 <item>
1227 Settings specified by the caller using the <tt/--defvar
1228 <var/name/=<var/value// option to the client are available in the
1229 configuration language as the corresponding <tt/u-<var/name//
1230 parameters and are passed to the service program in environment
1231 variables <tt/USERV_U_<var/name//.
1232
1233 <item>
1234 If the calling user is root or the same as the service user then
1235 options may be given to the client which bypass the usual security
1236 features; in this case other information may pass between the caller
1237 and the service.
1238
1239 </list>
1240
1241 <chapt id="notes">Applications and notes on use
1242 <p>
1243
1244 <sect id="examples">Examples
1245 <p>
1246
1247 The companion package, <prgn/userv-utils/, contains a selection of
1248 example services, some of which are useful tools in their own right.
1249 See the <prgn/README/ in its top-level directory for details.
1250
1251 <sect id="standards">Standard services and directory management
1252 <p>
1253
1254 In later versions of this specification standard service names and
1255 interfaces for common services such as mail delivery and WWW CGI
1256 scripts may be specified.
1257 <p>
1258
1259 <prgn/userv/-using applications and system services which hide
1260 <prgn/userv/ behind wrapper scripts may need to store information in
1261 the user's filespace to preserve the correct placement of the security
1262 perimiters.  Such applications should usually do so in a directory
1263 (created by them) <tt>~/.userv/<var/service/</>, where <var/service/
1264 is the service name or application in question.
1265 <p>
1266
1267 If desired, a dot-directory inside <tt>~/.userv</> may be used to
1268 avoid the user becoming confused by finding parts of a semi-privileged
1269 application's internal state in their filespace, and/or discourage
1270 them from fiddling with and thus corrupting it.
1271 <p>
1272
1273 However, <prgn/userv/ applications should of course not rely for their
1274 global integrity and security on the integrity of the data on the
1275 user's side of the security boundary.
1276
1277 <sect id="reducepriv">Reducing the number of absolutely privileged subsystems
1278 <p>
1279
1280 Currently most Unix systems have many components which need to run as
1281 root, even though most of their activity does not strictly require
1282 it.  This gives rise to a large and complex body of code which must be
1283 trusted with the security of the system.
1284 <p>
1285
1286 If they were to use <prgn/userv/, many of these subsystems would no
1287 longer need any unusual privilege.  <p>
1288
1289 <prgn/cron/ and <prgn/at/, <prgn/lpr/ and the system's mail transfer
1290 agent (<prgn/sendmail/, <prgn/smail/, <prgn/exim/ or the like) all
1291 fall into this category, though <prgn/userv/-based versions of these
1292 programs are not currently available.
1293
1294 <sect id="noexcess">Do not give away excessive privilege to <prgn/userv/-using facilities
1295 <p>
1296
1297 There is a danger that people reimplementing the facilities I mention
1298 above using <prgn/userv/ will discard much of the security benefit by
1299 using a naive implementation technique.  This will become clearer with
1300 an example:
1301 <p>
1302
1303 Consider the <prgn/lpr/ program.  In current systems this needs to
1304 have an absolutely privileged component in order to support delayed
1305 printing without copying: when the user queues a file to be printed
1306 the filename is stored in the print queue, rather than a copy of it,
1307 and the printer daemon accesses the file directly when it is ready to
1308 print the job.  In order that the user can print files which are not
1309 world-readable the daemon is given root privilege so that it can open
1310 the file in the context of the user, rather than its own.
1311 <p>
1312
1313 A simple-minded approach to converting this scheme to use <prgn/userv/
1314 might involve giving the printer daemon (the <prgn/lp/ user) the
1315 ability to read the file by allowing them to run <prgn/cat/ (or a
1316 special-purpose file-reading program) as any user.  The <prgn/lpr/
1317 program would use a <prgn/userv/ service to store the filename in the
1318 printer daemon's queues, and the daemon would read the file later when
1319 it felt like it.
1320 <p>
1321
1322 However, this would allow the printer daemon to read any file on the
1323 system, whether or not someone had asked for it to be printed.  Since
1324 many files will contain passwords and other security-critical
1325 information this is nearly as bad as giving the daemon root access in
1326 the first place.  Any security holes in the print server which allow a
1327 user to execute commands as the <prgn/lp/ user will give the user the
1328 ability to read any file on the system.
1329 <p>
1330
1331 Instead, it is necessary to keep a record of which files the daemon
1332 has been asked to print <em/outside/ the control of the print daemon.
1333 This record could be kept by a new root-privileged component, but this
1334 is not necessary: the record of which files a user has asked to be
1335 printed can be kept under the control of the user in question.  The
1336 submission program <prgn/lpr/ will make a record in an area under the
1337 user's control before communicating with the print server, and the
1338 print server would be given the ability to run a special file-reading
1339 program which would only allow files to be read which were listed in
1340 the user's file of things they'd asked to print.
1341 <p>
1342
1343 Now security holes in most of the printing system do not critically
1344 affect the security of the entire system: they only allow the attacker
1345 to read and interfere with print jobs.  Bugs in the programs run by the
1346 print server to read users' files (and to remove entries from the list
1347 of files when it has done with them) will still be serious, but this
1348 program can be quite simple.
1349 <p>
1350
1351 Similar considerations apply to many <prgn/userv/-based versions of
1352 facilities which currently run as root.
1353 <p>
1354
1355 It is debatable whether the user-controlled state should be kept in
1356 the user's filespace (in dotfiles, say) or kept in a separate area set
1357 aside for the purpose; however, using the user's home directory (and
1358 possibly creating a separate subdirectory of it as a dotfile to
1359 contain subsystem state) has fewer implications for the rest of the
1360 system and makes it entirely clear where the security boundaries lie.
1361
1362 <sect id="notreally"><prgn/userv/ can often replace <prgn/sudo/, but not <prgn/really/
1363 <p>
1364
1365 <prgn/userv/ is not intended as a general-purpose system
1366 administration tool with which system administrators can execute
1367 arbitrary programs like text editors as root (or other system users)
1368 when they need to.  It is unsuitable for this purpose precisely
1369 because it enforces a strong separation between the calling and the
1370 called program, which is undesirable in this context.
1371 <p>
1372
1373 However, its use when restricted to running particular programs in
1374 particular ways is very similar to many common uses of
1375 <prgn/sudo/<footnote><prgn/sudo/ is a program which allows users to
1376 execute certain programs as root, according to configuration files
1377 specified by the system administrator.</footnote>.  <prgn/userv/ is
1378 generally much better than restricted <prgn/sudo/, because it protects
1379 the called program much more strongly from bad environmental
1380 conditions set up by the caller.  Most programs that one might want to
1381 run via restricted <prgn/sudo/, have not been designed to run in a
1382 partially hostile environment.  <prgn/userv/ allows these programs to
1383 be run in a safer environment and should be used instead.
1384
1385 <sect id="stdinerr">Error handling and input streams (eg stdin)
1386 <p>
1387
1388 When the service program is reading from a file descriptor connected
1389 to the calling side, the fd that the service program refers to a pipe
1390 set up by <prgn/userv/ and not to the same object as was presented by
1391 the caller.
1392 <p>
1393
1394 Therefore if there is some kind of error it is possible for the
1395 service-side fd to give premature end of file.  If it is important to
1396 tell whether all of the intended data has been received by the service
1397 program, the datastream must contain an explicit end-of-file
1398 indication of some kind.
1399 <p>
1400
1401 For example, consider a <prgn/userv/ service for submitting a mail
1402 message, where message is supplied on the service's stdin.  However,
1403 if the calling process is interrupted before it has written all of the
1404 message, the service program will get EOF on the message data.  In a
1405 naive arrangement this would cause a half-complete message to be
1406 sent.  To prevent this, it is necessary to adopt some kind of explicit
1407 end indication; for example, the end of the message could be signalled
1408 by a dot on a line by itself, and dots doubled, as in SMTP.  Then the
1409 service program would know when the entire message had been received,
1410 and could avoid queueing incomplete messages.
1411
1412 <sect id="nogeneral">Don't give access to general-purpose utilities
1413 <p>
1414
1415 Do not specify general purpose programs like <prgn/mv/ or <prgn/cat/
1416 in <prgn/execute-/ directives without careful thought about their
1417 arguments, and certainly not if <prgn/no-suppress-args/ is specified.
1418 If you do so it will give the caller much more privilige than you
1419 probably intend.
1420 <p>
1421
1422 It is a shame that I have to say this here, but inexperienced
1423 administrators have made similar mistakes with programs like
1424 <prgn/sudo/.
1425
1426 </book>