<book>
<title>User service daemon and client specification
<author>Ian Jackson <email>ian@davenant.greenend.org.uk
-<version>0.64.1</version>
+<version>1.1.2~~iwj1</version>
<abstract>
This is a specification for a Unix system facility to allow one
between them.
<copyright>
-<prgn/userv/ is Copyright 1996-1999 Ian Jackson.
+<prgn/userv/ is
+Copyright 1996-2017 Ian Jackson;
+Copyright 2000 Ben Harris;
+Copyright 2016-2017 Peter Benie.
<p>
<prgn/userv/ is free software; you can redistribute it and/or modify
line. The portion of a line following a hash character <tt/#/ is
taken as a comment and ignored. Each directive consists of a series
of tokens separated by linear whitespace (spaces and tabs); tokens may
-be words consisting of non-space characters (except backslash), or,
-where a string is required, a string in double quotes. Double-quoted
-strings may contain the following backslash escapes:
+be words consisting of non-space characters, or, where a string is
+required, a string in double quotes. Double-quoted strings may
+contain the following backslash escapes:
<taglist compact>
<tag/<tt/\n//<item>newline
current directory (usually the service user's home directory).
Pathnames starting with the two characters <tt>~/</> are taken to be
relative to the service user's home directory.
-<p>
-
-Logical lines may be continued by putting a backslash <tt/\/ at the
-end of a line; this counts as part of linear whitespace.
<sect id="directives">Configuration file directives
<p>
<p>
A translation will be applied to values before they are used to
-construct a filename, so that the lookup cannot access dotfiles,
-backup files, files in other directories and the like: each slash will
-be replaced with a colon followed by a hyphen <tt>:-</>, and all
-characters which are not lowercase alphanumerics, hyphens or
-underscores will have a colon prepended (so that colons are doubled).
-A parameter value which is the empty string will be replaced with
+construct a filename, so that the lookup cannot access dotfiles or
+files in other directories: values starting with full stops will have
+a colon prepended (making <tt/:./), colons will be doubled, and each
+slash will be replaced with a colon followed by a hyphen <tt>:-</>. A
+parameter value which is the empty string will be replaced with
<tt/:empty/ (note that this is different from a parameter not having
any values).
+<p>
+(In older versions of userv, a different translation was applied:
+See <tt>https://bugs.debian.org/837391</tt>. The old translation
+can be requested (for subsequent directives) with
+<tt/include-lookup-quote-old/, which is undone by
+<tt/include-lookup-quote-new/ and <tt/reset/.)
+
<tag/<tt/include-directory <var/directory///
<item>
Read configuration from all files in directory <var/directory/ which
<item>
Causes an error whose message includes the descriptive string
<var/text/. <var/text/ may consist of several tokens with intervening
-linear whitespace. Each set of linear whitespace will appear in the
-message as a single space. The usual meaning of double-quoted strings
+whitespace. The whitespace will be included in the message as found
+in the configuration file: all the characters until the end of the
+line will be included verbatim, unless they are part of a
+double-quoted string, in which case the usual meaning of the string
(i.e., after backslash escape processing) will be used. Comments and
linear whitespace at the end of the line (or just before the comment)
-will still be ignored. Apart from those cases, each token's text will
-be included verbatim.
+will still be ignored.
<tag/<tt/message <var/text ...///
<item>
</taglist>
-<tag/<tt/errors-push/ <var/filename//
+<tag/<tt/errors-push//
<tag/<tt/srorre//
<item>
Stacks the error handling behaviour currently in effect. Any changes
<chapt id="notes">Applications and notes on use
<p>
+<sect id="examples">Examples
+<p>
+
+The companion package, <prgn/userv-utils/, contains a selection of
+example services, some of which are useful tools in their own right.
+See the <prgn/README/ in its top-level directory for details.
+
<sect id="standards">Standard services and directory management
<p>
In later versions of this specification standard service names and
interfaces for common services such as mail delivery and WWW CGI
-scripts will be specified.
+scripts may be specified.
<p>
<prgn/userv/-using applications and system services which hide
<prgn/userv/ behind wrapper scripts may need to store information in
the user's filespace to preserve the correct placement of the security
perimiters. Such applications should usually do so in a directory
-(created by them) <tt>~/.userv/.servdata/<var/service/</>, where
-<var/service/ is the service name or application in question.
+(created by them) <tt>~/.userv/<var/service/</>, where <var/service/
+is the service name or application in question.
<p>
-The use of a dot-directory inside <tt>~/.userv</> will hopefully avoid
-the user becoming confused by finding parts of a semi-privileged
-application's internal state in their filespace, and or discourage
-them from fiddling with and thus corrupting it. (Note that such
-applications should of course not rely for their global integrity on
-the integrity of the data on the user's side of the security
-boundary.)
+If desired, a dot-directory inside <tt>~/.userv</> may be used to
+avoid the user becoming confused by finding parts of a semi-privileged
+application's internal state in their filespace, and/or discourage
+them from fiddling with and thus corrupting it.
+<p>
+
+However, <prgn/userv/ applications should of course not rely for their
+global integrity and security on the integrity of the data on the
+user's side of the security boundary.
<sect id="reducepriv">Reducing the number of absolutely privileged subsystems
<p>
trusted with the security of the system.
<p>
-Using <prgn/userv/ many of these subsystems no longer need any unusual
-privilege.
-<p>
+If they were to use <prgn/userv/, many of these subsystems would no
+longer need any unusual privilege. <p>
<prgn/cron/ and <prgn/at/, <prgn/lpr/ and the system's mail transfer
agent (<prgn/sendmail/, <prgn/smail/, <prgn/exim/ or the like) all
-fall into this category.
+fall into this category, though <prgn/userv/-based versions of these
+programs are not currently available.
<sect id="noexcess">Do not give away excessive privilege to <prgn/userv/-using facilities
<p>
It is debatable whether the user-controlled state should be kept in
the user's filespace (in dotfiles, say) or kept in a separate area set
aside for the purpose; however, using the user's home directory (and
-probably creating a separate subdirectory of it as a dotfile to
-contain many subsystems' state) has fewer implications for the rest of
-the system and makes it entirely clear where the security boundaries
-lie.
+possibly creating a separate subdirectory of it as a dotfile to
+contain subsystem state) has fewer implications for the rest of the
+system and makes it entirely clear where the security boundaries lie.
-<sect id="notreally"><prgn/userv/ is not a replacement for <prgn/really/ and <prgn/sudo/
+<sect id="notreally"><prgn/userv/ can often replace <prgn/sudo/, but not <prgn/really/
<p>
<prgn/userv/ is not intended as a general-purpose system
administration tool with which system administrators can execute
-privileged programs when they need to. It is unsuitable for this
-purpose precisely because it enforces a strong separation between the
-calling and the called program, which is undesirable in this context.
+arbitrary programs like text editors as root (or other system users)
+when they need to. It is unsuitable for this purpose precisely
+because it enforces a strong separation between the calling and the
+called program, which is undesirable in this context.
<p>
-Its facilities for restricting activities to running certain programs
-may at first glance seem to provide similar functionality to
+However, its use when restricted to running particular programs in
+particular ways is very similar to many common uses of
<prgn/sudo/<footnote><prgn/sudo/ is a program which allows users to
execute certain programs as root, according to configuration files
-specified by the system administrator.</footnote>. However, the
-separation mentioned above is a problem here too, particular for
-interaction - it can be hard for a <prgn/userv/ service program to
-interact with its real caller or the user in question.
+specified by the system administrator.</footnote>. <prgn/userv/ is
+generally much better than restricted <prgn/sudo/, because it protects
+the called program much more strongly from bad environmental
+conditions set up by the caller. Most programs that one might want to
+run via restricted <prgn/sudo/, have not been designed to run in a
+partially hostile environment. <prgn/userv/ allows these programs to
+be run in a safer environment and should be used instead.
+
+<sect id="stdinerr">Error handling and input streams (eg stdin)
+<p>
+
+When the service program is reading from a file descriptor connected
+to the calling side, the fd that the service program refers to a pipe
+set up by <prgn/userv/ and not to the same object as was presented by
+the caller.
+<p>
+
+Therefore if there is some kind of error it is possible for the
+service-side fd to give premature end of file. If it is important to
+tell whether all of the intended data has been received by the service
+program, the datastream must contain an explicit end-of-file
+indication of some kind.
+<p>
+
+For example, consider a <prgn/userv/ service for submitting a mail
+message, where message is supplied on the service's stdin. However,
+if the calling process is interrupted before it has written all of the
+message, the service program will get EOF on the message data. In a
+naive arrangement this would cause a half-complete message to be
+sent. To prevent this, it is necessary to adopt some kind of explicit
+end indication; for example, the end of the message could be signalled
+by a dot on a line by itself, and dots doubled, as in SMTP. Then the
+service program would know when the entire message had been received,
+and could avoid queueing incomplete messages.
<sect id="nogeneral">Don't give access to general-purpose utilities
<p>
~ian / userv.git / blobdiff