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 (GNU textutils; alternatively, Colin Plumb's, as shipped with
  16           Debian in the `dpkg' package) - used during build only
  17 * GNU m4 [fixme: should ship the output]
  18 * GNU make
  19 * GNU flex [fixme: should ship the output]
  20 * GCC is preferred but other compilers ought to work (though
  21   no portability testing has yet been done).  ANSI C only.
  22   ints must be at least 32 bits.
  23 * A sensible `cat' which notices write errors (ie not SunOS4, BSD 4.3,
  24   or many others.  GNU textutils has one.  NB that this `cat' is used
  25   at runtime and must be first on the system default PATH, so probably
  26   in /bin.)
  27
  28 C Library:
  29
  30 * [v]snprintf - a real version, not just [v]sprintf with a wrapper
  31   that throws the argument away.
  32 * strsignal;
  33 * fnmatch;
  34 * BSD syslog(3);
  35 * strtoul;
  36 * memcpy, memset, memcpy;
  37 * realloc(0,size) must work and be equivalent to malloc(size).
  38 * free(0) must work and do nothing
  39 * <stdarg.h> (not varargs) and v[sf][n]printf.
  40
  41 System interfaces:
  42
  43 * setreuid(2), getreuid(2), getgroups(2), initgroups(3), with
  44   the ability for root to (a) swap euid and ruid and
  45   (b) give away all privilege by calling setreuid(ruid,ruid)
  46   twice.
  47 * wait3 and waitpid, <wait.h> with WNOHANG, WIFSIGNALED,
  48   WIFEXITEED, WTERMSIG, WEXITSTATUS and WCOREDUMP.
  49 * gid_t, uid_t, pid_t.
  50 * Unix-domain (AF_UNIX) stream sockets, for use with:
  51   * BSD sockets - socket(), bind(), listen(), accept(), connect();
  52   * socketpair(2);
  53 * lstat(2) (though stat(2) will be safe on systems without symlinks,
  54   if you say -Dlstat=stat).
  55 * Pipes:
  56   * creating using pipe(2) and mkfifo(2);
  57   * proper interaction between open(O_RDWR), open(O_RDONLY),
  58     open(O_WRONLY), close(), dup2, EPIPE, SIGPIPE, &c.
  59     (ie, opening pipes with O_RDWR never blocks; EPIPE happens
  60     if you write with no readers; EOF happens if you read with
  61     no buffered data and writers);
  62 * POSIX signal handling - sigaction(2), sigprocmask(2), sigsuspend(2);
  63 * POSIX sessions - setsid(2) (for -daemon flag).
  64
  65 To format the documentation:
  66
  67 * debiandoc-sgml, and hence sp (aka nsgmls) and sgmlspm.
  68 * For PostScript output, Lout and possibly psutils.
  69
  70 For debugging version (./configure --enable-debug):
  71
  72 * initgroups(3) must use setgroups(2) and dynamic
  73   linking must allow overriding setgroups(2) for initgroups(3);
  74
  75 DAEMON INVOCATION:
  76
  77 The daemon can be invoked with no arguments, in which case it will not
  78 fork or detach itself.  This is suitable for running from init and
  79 similar arrangements.
  80
  81 With -daemon it will attempt to detach itself from the controlling
  82 terminal and fork/exit so that control returns at startup.
  83
  84 In both cases diagnostics which prevent correct startup will appear on
  85 stderr.
  86
  87 SYSLOG MESSAGES:
  88
  89 The daemon issues diagnostics of various kinds to syslog, usually with
  90 facility LOG_DAEMON (though this can be changed in daemon.h if you want).
  91 The syslog levels used are:
  92  debug - verbose messages about the activity of the userv daemon.
  93  info - two log message about the nature and outcome of each request.
  94  notice - messages about the status of the daemon, including the
  95           startup message and the hourly socket check messages.
  96  warning - if the uservd exits because it believes that it no longer
  97            controls the rendezvous socket (ie, its socket has become
  98            orphaned), this level will receive messages indicating why
  99            the daemon believes this and notifying of its shutdown.
 100  err - a believed-recoverable error condition was detected by the
 101        userv server in itself, the client or the operating system
 102        (this includes resource shortages). The uservd will try to
 103        continue.
 104  crit - the uservd detected a non-recoverable error condition
 105         after startup and will exit.
 106  alert - not used.
 107  emerg - not used.
 108
 109 The service configuration language has the facility to direct error
 110 and warning messages to syslog.  The default facility and level is
 111 user.err, but the author of the configuration file(s) can override
 112 this.
 113
 114 DAEMON EXIT STATUS:
 115
 116 The daemon's exit code will reflect how well things went:
 117
 118  0 - The daemon was asked to detach itself from the controlling
 119      terminal and this appears to have been done successfully.
 120  1* - The daemon got a SIGTERM or SIGINT and shut itself down.
 121  2* - The daemon believes that it was no longer the uservd and so has
 122       exited to clean itself up.
 123  3 - uservd was started with incorrect arguments.
 124  4 - A system call failure or other environmental problem occurred
 125      during startup.
 126  5* - There was a non-recoverable error after startup; the uservd had
 127       to exit.
 128  6 - The daemon was asked to detach itself, but its detaching child
 129      died for some unexpected reason.
 130
 131  SIGABRT/SIGIOT* - an unexpected internal error, usually caused by a
 132    bug in uservd.  This can also occur if an attempt to block signals
 133    using sigprocmask fails.
 134
 135 Outcomes marked * are not possible if the daemon is asked to detach
 136 itself - these exit statuses will be reaped by init instead.
 137
 138 The daemon's per-request children will note the success level of its
 139 request in its exit status.  This will not usually be logged unless it
 140 is higher than those listed below; they are presented here for
 141 completeness and as programming documentation.
 142
 143  2 - The connection was just an internal version check.
 144
 145  4 - The client requested that the service be disconnected.  This
 146      includes normal termination, which is achieved by having the
 147      server tell the client that the service has completed and waiting
 148      for the client to tell it to disconnect.
 149
 150  8 - The client closed its end of the socket when this would not
 151      usually have been expected, causing an EPIPE or unexpected EOF in
 152      the server.  This is not an error condition - it can happen, for
 153      example, if the client receives a fatal signal of some kind from
 154      its execution environment (eg its controlling terminal).
 155
 156  10 - The per-request child wishes the server to check whether it is
 157       still the uservd.
 158
 159  12 - The service failed onm the service side in an expected and
 160       controlled manner, for example because it was rejected in the
 161       configuration files.
 162
 163  16 - A fatal system call failure or other general error occurred,
 164       which ought not to have happened at all, barring system resource
 165       shortages.
 166
 167  20 - The client sent invalid data to the server, after the client
 168       dropped all its system privilege.  On some systems this can be
 169       caused by a malicious calling user.
 170
 171  SIGABRT/SIGIOT - The client sent invalid data to the server before it
 172    dropped all its system privileges, or some other unexpected
 173    internal error occurred.  This can also occur if an attempt to
 174    block signals using sigprocmask fails.
 175
 176  0-3,5-7,9,11,13-15,17-19 are not currently used by normal children.
 177
 178 REENTRANCY IN THE LIBC:
 179
 180 We assume, both in the client and server, that it is safe to use one
 181 stdio stream in a signal handler which interrupts use of a _different_
 182 stdio stream in another.  We make sure using setvbuf that we have
 183 pre-allocated buffers so that stdio doesn't need to use malloc() when
 184 we actually read or write.  stdio had better not do anything else
 185 weird.
 186
 187 Furthermore, we assume that it is safe to use syslog in a signal
 188 handler which has interrupted a stdio operation (but we don't require
 189 that it be safe to invoke when the signal has interrupted a call to
 190 malloc, unless stdio makes gratuitous mallocs).  openlog will already
 191 have been called (but syslog will not necessarily have been called).
 192
 193 We assume that strerror is completely reentrant.
 194
 195 PROBLEMS
 196
 197 * `function declaration isn't a prototype'
 198
 199   One some systems (at least some versions of NetBSD, for example),
 200   the SIG_IGN and SIG_DFL macros contain function declarations (as part
 201   of a typecast, presumably) which are not prototypes.  The warning
 202   options that are used by default if the configure script detects that
 203   you're using a good GCC then cause the compilation to fail.  You must
 204   use
 205     make CFLAGS=-O2
 206   instead of just `make', thus suppressing warnings.
 207
 208   The bug is actually in your system header files, for not specifying
 209   the number and types of arguments to signal handler functions when
 210   they cast in the SIG_IGN and SIG_DFL macros.
 211
 212 DEBUGGING VERSION
 213
 214 If you run configure with --enable-debug, a debugging version will be
 215 built.  This will look in the current directory (the build directory)
 216 for the base of various things, including the IPC area (which you must
 217 therefore construct yourself).  The debugging version will produce
 218 extra output at various points.  It will not attempt to call
 219 setgroups(), instead just checking that the groups list is right, so
 220 it will work non-setuid if the daemon is invoked as the service user.
 221 The daemon won't fork for each request; instead, it will handle a
 222 single request and exit.
 223
 224 There may be other changes.  Consult the code for details.  Making the
 225 debugging version of the client or daemon setuid root is probably a
 226 bad idea.  They may not work if they are run as different users.
 227
 228
 229 COPYRIGHT
 230
 231 This file, INSTALL, contains installation instructions and other
 232 details for userv.
 233
 234 userv is
 235 Copyright (C)1996-2000 Ian Jackson <ian@davenant.greenend.org.uk>.
 236 Copyright (C)2000      Ben Harris <bjh21@cam.ac.uk>
 237
 238 userv is free software; you can redistribute it and/or modify it under
 239 the terms of the GNU General Public License as published by the Free
 240 Software Foundation; either version 2 of the License, or (at your
 241 option) any later version.
 242
 243 This program is distributed in the hope that it will be useful, but
 244 WITHOUT ANY WARRANTY; without even the implied warranty of
 245 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 246 General Public License for more details.
 247
 248 You should have received a copy of the GNU General Public License
 249 along with userv as the file COPYING; if not, email me at the address
 250 above or write to the Free Software Foundation, 59 Temple Place -
 251 Suite 330, Boston, MA 02111-1307, USA.