<hr>
<h2>
-<a name="s-standards">6.1 Standard services and directory management</a>
+<a name="s-examples">6.1 Examples</a>
+</h2>
+
+<p>
+The companion package, <code>userv-utils</code>, contains a selection of
+example services, some of which are useful tools in their own right.
+See the <code>README</code> in its top-level directory for details.
+</p>
+
+<hr>
+
+<h2>
+<a name="s-standards">6.2 Standard services and directory management</a>
</h2>
<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>
<p>
<code>userv</code> 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) <samp>~/.userv/.servdata/<var>service</var></samp>, where
-<var>service</var> is the service name or application in question.
+(created by them) <samp>~/.userv/<var>service</var></samp>, where <var>service</var>
+is the service name or application in question.
+</p>
+
+<p>
+If desired, a dot-directory inside <samp>~/.userv</samp> 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>
<p>
-The use of a dot-directory inside <samp>~/.userv</samp> 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.)
+However, <code>userv</code> 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.
</p>
<hr>
<h2>
-<a name="s-reducepriv">6.2 Reducing the number of absolutely privileged subsystems</a>
+<a name="s-reducepriv">6.3 Reducing the number of absolutely privileged subsystems</a>
</h2>
<p>
</p>
<p>
-Using <code>userv</code> many of these subsystems no longer need any unusual
-privilege.
+If they were to use <code>userv</code>, many of these subsystems would no
+longer need any unusual privilege.
</p>
<p>
<code>cron</code> and <code>at</code>, <code>lpr</code> and the system's mail transfer
agent (<code>sendmail</code>, <code>smail</code>, <code>exim</code> or the like) all
-fall into this category.
+fall into this category, though <code>userv</code>-based versions of these
+programs are not currently available.
</p>
<hr>
<h2>
-<a name="s-noexcess">6.3 Do not give away excessive privilege to <code>userv</code>-using facilities</a>
+<a name="s-noexcess">6.4 Do not give away excessive privilege to <code>userv</code>-using facilities</a>
</h2>
<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.
</p>
<hr>
<h2>
-<a name="s-notreally">6.4 <code>userv</code> is not a replacement for <code>really</code> and <code>sudo</code></a>
+<a name="s-notreally">6.5 <code>userv</code> can often replace <code>sudo</code>, but not <code>really</code></a>
</h2>
<p>
<code>userv</code> 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>
+
+<p>
+However, its use when restricted to running particular programs in
+particular ways is very similar to many common uses of
+<code>sudo</code><a href="footnotes.html#2" name="fr2">[2]</a>. <code>userv</code> is
+generally much better than restricted <code>sudo</code>, 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 <code>sudo</code>, have not been designed to run in a
+partially hostile environment. <code>userv</code> allows these programs to
+be run in a safer environment and should be used instead.
+</p>
+
+<hr>
+
+<h2>
+<a name="s-stdinerr">6.6 Error handling and input streams (eg stdin)</a>
+</h2>
+
+<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 <code>userv</code> and not to the same object as was presented by
+the caller.
+</p>
+
+<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>
<p>
-Its facilities for restricting activities to running certain programs
-may at first glance seem to provide similar functionality to
-<code>sudo</code><a href="footnotes.html#2" name="fr2">[2]</a>. However, the
-separation mentioned above is a problem here too, particular for
-interaction - it can be hard for a <code>userv</code> service program to
-interact with its real caller or the user in question.
+For example, consider a <code>userv</code> 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.
</p>
<hr>
<h2>
-<a name="s-nogeneral">6.5 Don't give access to general-purpose utilities</a>
+<a name="s-nogeneral">6.7 Don't give access to general-purpose utilities</a>
</h2>
<p>
~ian / userv.git / blobdiff