INSTALL

   1 INSTALLATION INSTRUCTIONS:
   2
   3    $ ./configure
   4    $ make
   5    # make install
   6
   7 This will not install the documentation, which is shipped as
   8 pre-prepared HTML and PostScript as well as debiandoc-sgml source.
   9 Put that (spec.html/ and spec.ps) where you will.
  10
  11 SYSTEM REQUIREMENTS:
  12
  13 Programs:
  14
  15 * md5sum (Colin Plumb's or the GNU version)
  16 * GNU m4
  17 * GNU make
  18 * GNU flex
  19 * GCC is preferred but other compilers ought to work (though
  20   no portability testing has yet been done).  ANSI C only.
  21   ints must be at least 32 bits.
  22 * A sensible /bin/cat which notices write errors (ie not
  23   SunOS4, BSD 4.3, or many others.)
  24
  25 C Library:
  26
  27 * [v]snprintf - a real version, not just [v]sprintf with a wrapper
  28   that throws the argument away.
  29 * strsignal;
  30 * fnmatch;
  31 * BSD syslog(3);
  32 * strtoul;
  33 * memcpy, memset, memcpy;
  34 * realloc(0,size) must work and be equivalent to malloc(size).
  35 * free(0) must work and do nothing
  36 * <stdarg.h> (not varargs) and v[sf][n]printf.
  37
  38 System interfaces:
  39
  40 * setreuid(2), getreuid(2), getgroups(2), initgroups(3), with
  41   the ability for root to (a) swap euid and ruid and
  42   (b) give away all privilege by calling setreuid(ruid,ruid)
  43   twice.
  44 * wait3 and waitpid, <wait.h> with WNOHANG, WIFSIGNALED,
  45   WIFEXITEED, WTERMSIG, WEXITSTATUS and WCOREDUMP.
  46 * gid_t, uid_t, pid_t.
  47 * Unix-domain (AF_UNIX) stream sockets, for use with:
  48   * BSD sockets - socket(), bind(), listen(), accept(), connect();
  49   * socketpair(2);
  50 * lstat(2) (though stat(2) will be safe on systems without symlinks,
  51   if you say -Dlstat=stat).
  52 * Pipes:
  53   * creating using pipe(2) and mkfifo(2);
  54   * proper interaction between open(O_RDWR), open(O_RDONLY),
  55     open(O_WRONLY), close(), dup2, EPIPE, SIGPIPE, &c.
  56     (ie, opening pipes with O_RDWR never blocks; EPIPE happens
  57     if you write with no readers; EOF happens if you read with
  58     no buffered data and writers);
  59 * POSIX signal handling - sigaction(2), sigprocmask(2), sigsuspend(2);
  60 * POSIX sessions - setsid(2) (for -daemon flag).
  61
  62 To format the documentation:
  63
  64 * debiandoc-sgml, and hence sp (aka nsgmls) and sgmlspm.
  65 * For PostScript output, Lout and possibly psutils.
  66
  67 For debugging version (./configure --enable-debug):
  68
  69 * initgroups(3) must use setgroups(2) and dynamic
  70   linking must allow overriding setgroups(2) for initgroups(3);
  71
  72 DAEMON INVOCATION:
  73
  74 The daemon can be invoked with no arguments, in which case it will not
  75 fork or detach itself.  This is suitable for running from init and
  76 similar arrangements.
  77
  78 With -daemon it will attempt to detach itself from the controlling
  79 terminal and fork/exit so that control returns at startup.
  80
  81 In both cases diagnostics which prevent correct startup will appear on
  82 stderr.
  83
  84 SYSLOG MESSAGES:
  85
  86 The daemon issues diagnostics of various kinds to syslog, usually with
  87 facility LOG_DAEMON (though this can be changed in daemon.h if you want).
  88 The syslog levels used are:
  89  debug - verbose messages about the activity of the userv daemon.
  90  info - two log message about the nature and outcome of each request.
  91  notice - messages about the status of the daemon, including the
  92           startup message and the hourly socket check messages.
  93  warning - if the uservd exits because it believes that it no longer
  94            controls the rendezvous socket (ie, its socket has become
  95            orphaned), this level will receive messages indicating why
  96            the daemon believes this and notifying of its shutdown.
  97  err - a believed-recoverable error condition was detected by the
  98        userv server in itself, the client or the operating system
  99        (this includes resource shortages). The uservd will try to
 100        continue.
 101  crit - the uservd detected a non-recoverable error condition
 102         after startup and will exit.
 103  alert - not used.
 104  emerg - not used.
 105
 106 The service configuration language has the facility to direct error
 107 and warning messages to syslog.  The default facility and level is
 108 user.err, but the author of the configuration file(s) can override
 109 this.
 110
 111 DAEMON EXIT STATUS:
 112
 113 The daemon's exit code will reflect how well things went:
 114
 115  0 - The daemon was asked to detach itself from the controlling
 116      terminal and this appears to have been done successfully.
 117  1* - The daemon got a SIGTERM or SIGINT and shut itself down.
 118  2* - The daemon believes that it was no longer the uservd and so has
 119       exited to clean itself up.
 120  3 - uservd was started with incorrect arguments.
 121  4 - A system call failure or other environmental problem occurred
 122      during startup.
 123  5* - There was a non-recoverable error after startup; the uservd had
 124       to exit.
 125  6 - The daemon was asked to detach itself, but its detaching child
 126      died for some unexpected reason.
 127
 128  SIGABRT/SIGIOT* - an unexpected internal error, usually caused by a
 129    bug in uservd.  This can also occur if an attempt to block signals
 130    using sigprocmask fails.
 131
 132 Outcomes marked * are not possible if the daemon is asked to detach
 133 itself - these exit statuses will be reaped by init instead.
 134
 135 The daemon's per-request children will note the success level of its
 136 request in its exit status.  This will not usually be logged unless it
 137 is higher than those listed below; they are presented here for
 138 completeness and as programming documentation.
 139
 140  2 - The connection was just an internal version check.
 141
 142  4 - The client requested that the service be disconnected.  This
 143      includes normal termination, which is achieved by having the
 144      server tell the client that the service has completed and waiting
 145      for the client to tell it to disconnect.
 146
 147  8 - The client closed its end of the socket when this would not
 148      usually have been expected, causing an EPIPE or unexpected EOF in
 149      the server.  This is not an error condition - it can happen, for
 150      example, if the client receives a fatal signal of some kind from
 151      its execution environment (eg its controlling terminal).
 152
 153  12 - The service failed onm the service side in an expected and
 154       controlled manner, for example because it was rejected in the
 155       configuration files.
 156
 157  16 - A fatal system call failure or other general error occurred,
 158       which ought not to have happened at all, barring system resource
 159       shortages.
 160
 161  20 - The client sent invalid data to the server, after the client
 162       dropped all its system privilege.  On some systems this can be
 163       caused by a malicious calling user.
 164
 165  SIGABRT/SIGIOT - The client sent invalid data to the server before it
 166    dropped all its system privileges, or some other unexpected
 167    internal error occurred.  This can also occur if an attempt to
 168    block signals using sigprocmask fails.
 169
 170  0-3,5-7,9-11,13-15,17-19 are not currently used.
 171
 172 REENTRANCY IN THE LIBC:
 173
 174 We assume, both in the client and server, that it is safe to use one
 175 stdio stream in a signal handler which interrupts use of a _different_
 176 stdio stream in another.  We make sure using setvbuf that we have
 177 pre-allocated buffers so that stdio doesn't need to use malloc() when
 178 we actually read or write.  stdio had better not do anything else
 179 weird.
 180
 181 Furthermore, we assume that it is safe to use syslog in a signal
 182 handler which has interrupted a stdio operation (but we don't require
 183 that it be safe to invoke when the signal has interrupted a call to
 184 malloc, unless stdio makes gratuitous mallocs).  openlog will already
 185 have been called (but syslog will not necessarily have been called).
 186
 187 We assume that strerror is completely reentrant.
 188
 189 PROBLEMS
 190
 191 * `function declaration isn't a prototype'
 192
 193   One some systems (at least some versions of NetBSD, for example),
 194   the SIG_IGN and SIG_DFL macros contain function declarations (as part
 195   of a typecast, presumably) which are not prototypes.  The warning
 196   options that are used by default if the configure script detects that
 197   you're using a good GCC then cause the compilation to fail.  You must
 198   use
 199     make CFLAGS=-O2
 200   instead of just `make', thus suppressing warnings.
 201
 202   The bug is actually in your system header files, for not specifying
 203   the number and types of arguments to signal handler functions when
 204   they cast in the SIG_IGN and SIG_DFL macros.