+.\"
+.\" 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.
~ian / userv.git / commitdiff