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