chiark / gitweb /
Fix quoted strings. Oops.
[userv.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index d7211b6..4b5d665 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -32,6 +32,7 @@ C Library:
 * strtoul;
 * memcpy, memset, memcpy;
 * realloc(0,size) must work and be equivalent to malloc(size).
+* free(0) must work and do nothing
 * <stdarg.h> (not varargs) and v[sf][n]printf.
 
 System interfaces:
@@ -46,12 +47,17 @@ System interfaces:
 * 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),
-    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 sessions - setsid(2) (for -daemon flag).
 
 To format the documentation:
 
@@ -63,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);
 
+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
@@ -79,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.
+
+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.