X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=userv.git;a=blobdiff_plain;f=INSTALL;h=4b5d665b4eb0d98b2c0483474666ee1fc3d16bcd;hp=8c5db28545b190e7ddf019230875dcf3fcccf802;hb=7bc3c582a0a80d34d2c9c86ed9a588b3983e0db1;hpb=464d71c37246e556de9ec05f7b97af834a5224ee diff --git a/INSTALL b/INSTALL index 8c5db28..4b5d665 100644 --- 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); -* 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: @@ -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); +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 @@ -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. + +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.