uservd.8

   1 .\"
   2 .\" This manpage is copyright, like the rest of userv, - see the
   3 .\" copyright section, below.
   4 .Dd November 3, 1999
   5 .Dt USERVD 8
   6 .Os "userv"
   7 .Sh NAME
   8 .Nm uservd
   9 .Nd supply user services
  10 .Sh SYNOPSIS
  11 .Nm userv
  12 .Op Fl daemon
  13 .Sh DESCRIPTION
  14 .Nm uservd
  15 is the daemon called by
  16 .Nm userv
  17 to have a task performed under different userid while
  18 maintaining limited trust between caller and callee.
  19 .Sh OPTIONS
  20 There is one optional argument:
  21 .Bl -tag -width Fl
  22 .It Fl daemon
  23 Requests that the program daemonise.  If this flag is supplied,
  24 .Nm uservd
  25 will fork and completely detach from the controlling terminal.
  26 If this option is not supplied,
  27 .Nm uservd
  28 will remain in its starting process group and continue to use the
  29 supplied stderr stream for any runtime system messages; this is useful
  30 for running
  31 .Nm uservd
  32 as a child of
  33 .Nm init Ns .
  34 Errors
  35 detected by
  36 .Nm uservd
  37 itself will be reported via
  38 .Nm syslog
  39 in either case.
  40 .El
  41 .Sh SYSLOG MESSAGES:
  42 .Nm uservd
  43 issues diagnostics of various kinds to syslog, with facility
  44 .Nm LOG_DAEMON Ns .
  45 The syslog levels used are:
  46 .Bl -tag -width Nm
  47 .It Nm debug
  48 Verbose messages about the activity of the userv daemon.
  49 .It Nm info
  50 Two log messages about the nature and outcome of each request.
  51 .It Nm notice
  52 Messages about the status of the daemon, including the
  53 startup message and the hourly socket check messages.
  54 .It Nm warning
  55 If the uservd exits because it believes that it no longer controls the
  56 rendezvous socket (ie, its socket has become orphaned), this level
  57 will receive messages indicating why the daemon believes this and
  58 notifying of its shutdown.
  59 .It Nm err
  60 A believed-recoverable error condition was detected by the userv
  61 server in itself, the client or the operating system (this includes
  62 resource shortages). The uservd will try to continue.
  63 .It Nm crit
  64 The uservd detected a non-recoverable error condition after startup
  65 and will exit.
  66 .It Nm alert
  67 not used.
  68 .It Nm emerg
  69 not used.
  70 .El
  71 .Pp
  72 The service configuration language has the facility to direct error
  73 and warning messages to syslog.  The default facility and level is
  74 .Nm user.err Ns ,
  75 but the author of the configuration file(s) can override this.
  76 .Sh EXIT STATUS
  77 The daemon's exit code will reflect how well things went:
  78 .Bl -tag -width Nm
  79 .It Nm 0
  80 The daemon was asked to detach itself from the controlling
  81 terminal and this appears to have been done successfully.
  82 .It Nm 1*
  83 The daemon got a SIGTERM or SIGINT and shut itself down.
  84 .It Nm 2*
  85 The daemon believed that it was no longer the uservd and so exited to
  86 clean up.
  87 .It Nm 3
  88 uservd was started with incorrect arguments.
  89 .It Nm 4
  90 A system call failure or other environmental problem occurred
  91 during startup.
  92 .It Nm 5*
  93 There was a non-recoverable error after startup; the uservd had
  94 to exit.
  95 .It Nm 6
  96 The daemon was asked to detach itself, but its detaching child
  97 died for some unexpected reason.
  98 .It Nm SIGABRT/SIGIOT*
  99 An unexpected internal error, usually caused by a bug in uservd.  This
 100 can also occur if an attempt to block signals using sigprocmask fails.
 101 .El
 102 .Pp
 103 Outcomes marked * are not possible if the daemon is asked to detach
 104 itself - these exit statuses will be reaped by init instead and so
 105 will not usually be logged anywhere.
 106 .Pp
 107 The daemon's per-request children will report the success or otherwise
 108 of its request in their exit status.  These are not usually be logged
 109 unless they indicate a serious problem.
 110 .Sh ENVIRONMENT
 111 All of the environment variables passed to
 112 .Nm uservd
 113 will be inherited by services as part of the default environment.
 114 (If the
 115 .Nm set-environment
 116 configuration directive is used, then other system configuration files
 117 can modify the environment.  Consult the specification.)
 118 .Sh SEE ALSO
 119 .Xr userv 1
 120 .Xr init 8
 121 .Rs
 122 .%T "User service daemon and client specification"
 123 .%A Ian Jackson
 124 .Re
 125 .Sh COPYRIGHT
 126 GNU userv is Copyright 1996-2017 Ian Jackson; Copyright 2000 Ben
 127 Harris; and Copyright 2016-2017 Peter Benie.
 128 .Pp
 129 .Pp
 130 GNU userv is licensed under the terms of the GNU General Public
 131 Licence, version 2 or (at your option) any later version, and it comes
 132 with NO WARRANTY, not even the implied warranty of MERCHANTABILITY or
 133 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 134 for details.
 135 .Pp
 136 You should have received a copy of the GNU General Public License
 137 along with userv, if not, write to the Free Software Foundation, 59
 138 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 139 .Sh HISTORY
 140 .Nm
 141 was initially written in 1996 by Ian Jackson.  It became
 142 .Tn GNU
 143 .Nm
 144 in 1999, and version 1.0 was released in 2000.