chiark / gitweb /
manpage improvements
authorian <ian>
Sun, 29 Jun 2003 21:12:38 +0000 (21:12 +0000)
committerian <ian>
Sun, 29 Jun 2003 21:12:38 +0000 (21:12 +0000)
INSTALL
debian/changelog
userv.1
uservd.8 [new file with mode: 0644]

diff --git a/INSTALL b/INSTALL
index 97bb5db..46d3bdc 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -72,68 +72,9 @@ For debugging version (./configure --enable-debug):
 * initgroups(3) must use setgroups(2) and dynamic
   linking must allow overriding setgroups(2) for initgroups(3);
 
-DAEMON INVOCATION:
-
-The daemon can be invoked with no arguments, in which case it will not
-fork or detach itself.  This is suitable for running from init and
-similar arrangements.
-
-With -daemon it will attempt to detach itself from the controlling
-terminal and fork/exit so that control returns at startup.
-
-In both cases diagnostics which prevent correct startup will appear on
-stderr.
-
-SYSLOG MESSAGES:
-
-The daemon issues diagnostics of various kinds to syslog, usually with
-facility LOG_DAEMON (though this can be changed in daemon.h if you want).
-The syslog levels used are:
- debug - verbose messages about the activity of the userv daemon.
- info - two log message about the nature and outcome of each request.
- notice - messages about the status of the daemon, including the
-          startup message and the hourly socket check messages.
- warning - if the uservd exits because it believes that it no longer
-          controls the rendezvous socket (ie, its socket has become
-          orphaned), this level will receive messages indicating why
-          the daemon believes this and notifying of its shutdown.
- err - a believed-recoverable error condition was detected by the
-       userv server in itself, the client or the operating system
-       (this includes resource shortages). The uservd will try to
-       continue.
- crit - the uservd detected a non-recoverable error condition
-        after startup and will exit.
- alert - not used.
- emerg - not used.
-
-The service configuration language has the facility to direct error
-and warning messages to syslog.  The default facility and level is
-user.err, but the author of the configuration file(s) can override
-this.
-
-DAEMON EXIT STATUS:
-
-The daemon's exit code will reflect how well things went:
-
- 0 - The daemon was asked to detach itself from the controlling
-     terminal and this appears to have been done successfully.
- 1* - The daemon got a SIGTERM or SIGINT and shut itself down.
- 2* - The daemon believes that it was no longer the uservd and so has
-      exited to clean itself up.
- 3 - uservd was started with incorrect arguments.
- 4 - A system call failure or other environmental problem occurred
-     during startup.
- 5* - There was a non-recoverable error after startup; the uservd had
-      to exit.
- 6 - The daemon was asked to detach itself, but its detaching child
-     died for some unexpected reason.
-
- SIGABRT/SIGIOT* - an unexpected internal error, usually caused by a
-   bug in uservd.  This can also occur if an attempt to block signals
-   using sigprocmask fails.
-
-Outcomes marked * are not possible if the daemon is asked to detach
-itself - these exit statuses will be reaped by init instead.
+EXIT STATUS CODES
+
+For information about uservd's exit status, see uservd(8).
 
 The daemon's per-request children will note the success level of its
 request in its exit status.  This will not usually be logged unless it
index f9d429e..999cd3b 100644 (file)
@@ -20,7 +20,8 @@ userv (1.0.2) unstable; urgency=low
   * Specification's usage notes section improved.
   * --help and --version behaviour made to conform to GNU standards.
   * We do ship m4 and flex output now, so say so.
-  * Some groff warnings in userv(1) fixed.
+  * Some groff warnings in userv(1), and source version fixed.
+  * New userv(8) manpage.  (Debian: Closes: #33777.)
 
   Debian:
   * Priority changed to optional as per override file.
diff --git a/userv.1 b/userv.1
index 70553a0..e4f3fd9 100644 (file)
--- a/userv.1
+++ b/userv.1
@@ -3,7 +3,7 @@
 .\" copyright section, below.
 .Dd November 3, 1999
 .Dt USERV 1
-.Os "userv 1.0.0"
+.Os "userv"
 .Sh NAME
 .Nm userv
 .Nd request user services
diff --git a/uservd.8 b/uservd.8
new file mode 100644 (file)
index 0000000..581be28
--- /dev/null
+++ b/uservd.8
@@ -0,0 +1,145 @@
+.\"
+.\" This manpage is copyright, like the rest of userv, - see the
+.\" copyright section, below.
+.Dd November 3, 1999
+.Dt USERVD 8
+.Os "userv"
+.Sh NAME
+.Nm uservd
+.Nd supply user services
+.Sh SYNOPSIS
+.Nm userv
+.Op Fl daemon
+.Sh DESCRIPTION
+.Nm uservd
+is the daemon called by
+.Nm userv
+to have a task performed under different userid while
+maintaining limited trust between caller and callee.
+.Sh OPTIONS
+There is one optional argument:
+.Bl -tag -width Fl
+.It Fl daemon
+Requests that the program daemonise.  If this flag is supplied,
+.Nm uservd
+will fork and completely detach from the controlling terminal.
+If this option is not supplied,
+.Nm uservd
+will remain in its starting process group and continue to use the
+supplied stderr stream for any runtime system messages; this is useful
+for running
+.Nm uservd
+as a child of
+.Nm init Ns .
+Errors
+detected by
+.Nm uservd
+itself will be reported via
+.Nm syslog
+in either case.
+.El
+.Sh SYSLOG MESSAGES:
+.Nm uservd
+issues diagnostics of various kinds to syslog, with facility
+.Nm LOG_DAEMON Ns .
+The syslog levels used are:
+.Bl -tag -width Nm
+.It Nm debug
+Verbose messages about the activity of the userv daemon.
+.It Nm info
+Two log messages about the nature and outcome of each request.
+.It Nm notice
+Messages about the status of the daemon, including the
+startup message and the hourly socket check messages.
+.It Nm warning
+If the uservd exits because it believes that it no longer controls the
+rendezvous socket (ie, its socket has become orphaned), this level
+will receive messages indicating why the daemon believes this and
+notifying of its shutdown.
+.It Nm err
+A believed-recoverable error condition was detected by the userv
+server in itself, the client or the operating system (this includes
+resource shortages). The uservd will try to continue.
+.It Nm crit
+The uservd detected a non-recoverable error condition after startup
+and will exit.
+.It Nm alert
+not used.
+.It Nm emerg
+not used.
+.El
+.Pp
+The service configuration language has the facility to direct error
+and warning messages to syslog.  The default facility and level is
+.Nm user.err Ns ,
+but the author of the configuration file(s) can override this.
+.Sh EXIT STATUS
+The daemon's exit code will reflect how well things went:
+.Bl -tag -width Nm
+.It Nm 0
+The daemon was asked to detach itself from the controlling
+terminal and this appears to have been done successfully.
+.It Nm 1*
+The daemon got a SIGTERM or SIGINT and shut itself down.
+.It Nm 2*
+The daemon believed that it was no longer the uservd and so exited to
+clean up.
+.It Nm 3
+uservd was started with incorrect arguments.
+.It Nm 4
+A system call failure or other environmental problem occurred
+during startup.
+.It Nm 5*
+There was a non-recoverable error after startup; the uservd had
+to exit.
+.It Nm 6
+The daemon was asked to detach itself, but its detaching child
+died for some unexpected reason.
+.It Nm SIGABRT/SIGIOT*
+An unexpected internal error, usually caused by a bug in uservd.  This
+can also occur if an attempt to block signals using sigprocmask fails.
+.El
+.Pp
+Outcomes marked * are not possible if the daemon is asked to detach
+itself - these exit statuses will be reaped by init instead and so
+will not usually be logged anywhere.
+.Pp
+The daemon's per-request children will report the success or otherwise
+of its request in their exit status.  These are not usually be logged
+unless they indicate a serious problem.
+.Sh ENVIRONMENT
+All of the environment variables passed to
+.Nm uservd
+will be inherited by services as part of the default environment.
+(If the
+.Nm set-environment
+configuration directive is used, then other system configuration files
+can modify the environment.  Consult the specification.)
+.Sh SEE ALSO
+.Xr userv 1
+.Xr init 8
+.Rs
+.%T "User service daemon and client specification"
+.%A Ian Jackson
+.Re
+.Sh COPYRIGHT
+GNU userv, including this manpage, is Copyright (C)1996-2001,2003 Ian
+Jackson, except that the
+.Xr userv 1
+manpage is Copyright (C)2000 Ben Harris.
+.Pp
+GNU userv is licensed under the terms of the GNU General Public
+Licence, version 2 or (at your option) any later version, and it comes
+with NO WARRANTY, not even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+for details.
+.Pp
+You should have received a copy of the GNU General Public License
+along with userv, if not, write to the Free Software Foundation, 59
+Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+.Sh HISTORY
+.Nm
+was initially written in 1996 by Ian Jackson.  It became
+.Tn GNU
+.Nm
+in 1999, and version 1.0 was released in 2000.