<!doctype debiandoc system>
+
<book>
<title>User service daemon and client specification
-<author>Ian Jackson <email>ian@chiark.greenend.org.uk
-<version>draft 0.17
+<author>Ian Jackson <email>ian@davenant.greenend.org.uk
+<version>0.64.1</version>
<abstract>
This is a specification for a Unix system facility to allow one
between them.
<copyright>
-Copyright 1996-1997 Ian Jackson.
+<prgn/userv/ is Copyright 1996-1999 Ian Jackson.
<p>
<prgn/userv/ is free software; you can redistribute it and/or modify
<p>
If no <var/modifiers/ which imply <tt/read/ or <tt/write/ are used it
-is as if <tt/read/ had been specified, except that if the
-filedescriptor 1 or 2 of the service is being opened (either specified
-numerically or with <tt/stdout/ or <tt/stderr/) it is as if
-<tt/overwrite/ had been specified (or <tt/write/ if only <tt/fd/ was
-specified).
+is as if <tt/write/ had been specified, except that if the
+filedescriptor 0 of the service is being opened (either specified
+numerically or with <tt/stdin/) it is as if <tt/overwrite/ had been
+specified (or <tt/write/ if only <tt/fd/ was specified).
<p>
The client will also use <tt/O_NOCTTY/ when opening files specified by
Pretend to the service that it is being called by <var/user/ (which
may be a username or a uid). This will also affect the group and
supplementary groups supplied to the service; they will be the
-standard group and supplementary groups for <var/user/.
+standard group and supplementary groups for <var/user/. The
+<tt/--spoof-user/ option will <em/not/ affect which user is chosen if
+the service user is specified as just <tt/-/; in this case the service
+user will be the real calling user.
</taglist>
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, 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 (except backslash), 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 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
+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
<tt/:empty/ (note that this is different from a parameter not having
any values).
<item>
Causes an error whose message includes the descriptive string
<var/text/. <var/text/ may consist of several tokens with intervening
-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
+linear whitespace. Each set of linear whitespace will appear in the
+message as a single space. The usual meaning of double-quoted strings
(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.
+will still be ignored. Apart from those cases, each token's text will
+be included verbatim.
<tag/<tt/message <var/text ...///
<item>
<tag/<tt/errors-to-syslog/ [<var/facility/ [<var/level/]]/
<item>
Error messages will be delivered using <prgn/syslog/. The default
-<var/facility/ is <tt/daemon/; the default <var/level/ is <tt/error/.
+<var/facility/ is <tt/user/; the default <var/level/ is <tt/error/.
</taglist>
<sect1 id="dirs-control">Control structure directives
Reject the request. <prgn/execute/, <prgn/execute-from-directory/ and
<prgn/execute-from-path/ will change this setting.
-<tag/<tt/execute <var/pathname/ [<var/argument/ ...]//
+<tag/<tt/execute <var/program/ [<var/argument/ ...]//
<item>
-Execute the program <var/pathname/, with the arguments as specified,
+Execute the program <var/program/, with the arguments as specified,
followed by any arguments given to the client if
<prgn/no-suppress-args/ is in effect. It is an error for the
execution to fail when it is attempted (after all the configuration
-has been parsed). If <var/pathname/ does not contain a slash it will
+has been parsed). If <var/program/ does not contain a slash it will
be searched for on the service user's path.
<tag/<tt/execute-from-directory <var/pathname/ [<var/argument/ ...]//
Displays the top-level override configuration (the configuration data,
evaluated by the server, which causes all the other configuration data
to be parsed).
+
+<tag/<tt/help//
+<item>
+Displays a list of the understood builtin service names and arguments.
</taglist>
In the future other builtin services may be defined which do more than
<chapt id="notes">Applications and notes on use
<p>
+<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.
+<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.
+<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.)
+
<sect id="reducepriv">Reducing the number of absolutely privileged subsystems
<p>
~ian / userv.git / blobdiff