Fix quoted strings. Oops.

[userv.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index 8c5db28545b190e7ddf019230875dcf3fcccf802..4b5d665b4eb0d98b2c0483474666ee1fc3d16bcd 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -47,12 +47,17 @@ System interfaces:
 * Unix-domain (AF_UNIX) stream sockets, for use with:
   * BSD sockets - socket(), bind(), listen(), accept(), connect();
   * socketpair(2);
 * Unix-domain (AF_UNIX) stream sockets, for use with:
   * BSD sockets - socket(), bind(), listen(), accept(), connect();
   * socketpair(2);

-* lstat(2) (though stat(2) will be safe on systems without symlinks).
+* lstat(2) (though stat(2) will be safe on systems without symlinks,
+  if you say -Dlstat=stat).

 * Pipes:
   * creating using pipe(2) and mkfifo(2);
   * proper interaction between open(O_RDWR), open(O_RDONLY),
 * Pipes:
   * creating using pipe(2) and mkfifo(2);
   * proper interaction between open(O_RDWR), open(O_RDONLY),

-    open(O_WRONLY), close(), dup2, EPIPE, SIGPIPE, &c.;
+    open(O_WRONLY), close(), dup2, EPIPE, SIGPIPE, &c.
+    (ie, opening pipes with O_RDWR never blocks; EPIPE happens
+    if you write with no readers; EOF happens if you read with
+    no buffered data and writers);

 * POSIX signal handling - sigaction(2), sigprocmask(2), sigsuspend(2);
 * POSIX signal handling - sigaction(2), sigprocmask(2), sigsuspend(2);

+* POSIX sessions - setsid(2) (for -daemon flag).

 
 To format the documentation:
 
 
 To format the documentation:
 


@@ -64,6 +69,106 @@ 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.
+
+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
+is higher than those listed below; they are presented here for
+completeness and as programming documentation.
+
+ 2 - The connection was just an internal version check.
+
+ 4 - The client requested that the service be disconnected.  This
+     includes normal termination, which is achieved by having the
+     server tell the client that the service has completed and waiting
+     for the client to tell it to disconnect.
+
+ 8 - The client closed its end of the socket when this would not
+     usually have been expected, causing an EPIPE or unexpected EOF in
+     the server.  This is not an error condition - it can happen, for
+     example, if the client receives a fatal signal of some kind from
+     its execution environment (eg its controlling terminal).
+
+ 12 - The service failed onm the service side in an expected and
+      controlled manner, for example because it was rejected in the
+      configuration files.
+
+ 16 - A fatal system call failure or other general error occurred,
+      which ought not to have happened at all, barring system resource
+      shortages.
+
+ 20 - The client sent invalid data to the server, after the client
+      dropped all its system privilege.  On some systems this can be
+      caused by a malicious calling user.
+
+ SIGABRT/SIGIOT - The client sent invalid data to the server before it
+   dropped all its system privileges, or some other unexpected
+   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.
+

 REENTRANCY IN THE LIBC:
 
 We assume, both in the client and server, that it is safe to use one
 REENTRANCY IN THE LIBC:
 
 We assume, both in the client and server, that it is safe to use one


@@ -80,3 +185,20 @@ malloc, unless stdio makes gratuitous mallocs).  openlog will already
 have been called (but syslog will not necessarily have been called).
 
 We assume that strerror is completely reentrant.
 have been called (but syslog will not necessarily have been called).
 
 We assume that strerror is completely reentrant.

+
+PROBLEMS
+
+* `function declaration isn't a prototype'
+
+  One some systems (at least some versions of NetBSD, for example),
+  the SIG_IGN and SIG_DFL macros contain function declarations (as part
+  of a typecast, presumably) which are not prototypes.  The warning
+  options that are used by default if the configure script detects that
+  you're using a good GCC then cause the compilation to fail.  You must
+  use
+    make CFLAGS=-O2
+  instead of just `make', thus suppressing warnings.
+
+  The bug is actually in your system header files, for not specifying
+  the number and types of arguments to signal handler functions when
+  they cast in the SIG_IGN and SIG_DFL macros.