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