draft initd status support

[userv.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index 3fe90525d356feeb0f13211556cbcd460e79dcc1..46d3bdc47ea18c289e063ecf80517244c140fb09 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -14,9 +14,7 @@ Programs:
 
 * md5sum (GNU textutils; alternatively, Colin Plumb's, as shipped with
           Debian in the `dpkg' package) - used during build only
 
 * md5sum (GNU textutils; alternatively, Colin Plumb's, as shipped with
           Debian in the `dpkg' package) - used during build only

-* GNU m4 [fixme: should ship the output]

 * GNU make
 * GNU make

-* GNU flex [fixme: should ship the output]

 * GCC is preferred but other compilers ought to work (though
   no portability testing has yet been done).  ANSI C only.
   ints must be at least 32 bits.
 * GCC is preferred but other compilers ought to work (though
   no portability testing has yet been done).  ANSI C only.
   ints must be at least 32 bits.


@@ -24,6 +22,8 @@ Programs:
   or many others.  GNU textutils has one.  NB that this `cat' is used
   at runtime and must be first on the system default PATH, so probably
   in /bin.)
   or many others.  GNU textutils has one.  NB that this `cat' is used
   at runtime and must be first on the system default PATH, so probably
   in /bin.)

+* GNU m4   } if you don't want to change those bits of source
+* GNU flex }  you can do without these

 
 C Library:
 
 
 C Library:
 


@@ -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);
 
 * 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
 
 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


@@ -153,6 +94,9 @@ completeness and as programming documentation.
      example, if the client receives a fatal signal of some kind from
      its execution environment (eg its controlling terminal).
 
      example, if the client receives a fatal signal of some kind from
      its execution environment (eg its controlling terminal).
 

+ 10 - The per-request child wishes the server to check whether it is
+      still the uservd.
+

  12 - The service failed onm the service side in an expected and
       controlled manner, for example because it was rejected in the
       configuration files.
  12 - The service failed onm the service side in an expected and
       controlled manner, for example because it was rejected in the
       configuration files.


@@ -170,7 +114,7 @@ completeness and as programming documentation.
    internal error occurred.  This can also occur if an attempt to
    block signals using sigprocmask fails.
 
    internal error occurred.  This can also occur if an attempt to
    block signals using sigprocmask fails.
 

- 0-3,5-7,9-11,13-15,17-19 are not currently used.
+ 0-3,5-7,9,11,13-15,17-19 are not currently used by normal children.

 
 REENTRANCY IN THE LIBC:
 
 
 REENTRANCY IN THE LIBC:
 


@@ -221,3 +165,28 @@ single request and exit.
 There may be other changes.  Consult the code for details.  Making the
 debugging version of the client or daemon setuid root is probably a
 bad idea.  They may not work if they are run as different users.
 There may be other changes.  Consult the code for details.  Making the
 debugging version of the client or daemon setuid root is probably a
 bad idea.  They may not work if they are run as different users.

+
+
+COPYRIGHT
+
+This file, INSTALL, contains installation instructions and other
+details for userv.
+
+userv is
+Copyright (C)1996-2000 Ian Jackson <ian@davenant.greenend.org.uk>.
+Copyright (C)2000      Ben Harris <bjh21@cam.ac.uk>
+
+userv is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free
+Software Foundation; either version 2 of the License, or (at your
+option) any later version.
+
+This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with userv as the file COPYING; if not, email me at the address
+above or write to the Free Software Foundation, 59 Temple Place -
+Suite 330, Boston, MA 02111-1307, USA.