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