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 make
  18 * GCC is preferred but other compilers ought to work (though
  19   no portability testing has yet been done).  ANSI C only.
  20   ints must be at least 32 bits.
  21 * A sensible `cat' which notices write errors (ie not SunOS4, BSD 4.3,
  22   or many others.  GNU textutils has one.  NB that this `cat' is used
  23   at runtime and must be first on the system default PATH, so probably
  24   in /bin.)
  25 * GNU m4   } if you don't want to change those bits of source
  26 * GNU flex }  you can do without these
  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 EXIT STATUS CODES
  76
  77 For information about uservd's exit status, see uservd(8).
  78
  79 The daemon's per-request children will note the success level of its
  80 request in its exit status.  This will not usually be logged unless it
  81 is higher than those listed below; they are presented here for
  82 completeness and as programming documentation.
  83
  84  2 - The connection was just an internal version check.
  85
  86  4 - The client requested that the service be disconnected.  This
  87      includes normal termination, which is achieved by having the
  88      server tell the client that the service has completed and waiting
  89      for the client to tell it to disconnect.
  90
  91  8 - The client closed its end of the socket when this would not
  92      usually have been expected, causing an EPIPE or unexpected EOF in
  93      the server.  This is not an error condition - it can happen, for
  94      example, if the client receives a fatal signal of some kind from
  95      its execution environment (eg its controlling terminal).
  96
  97  10 - The per-request child wishes the server to check whether it is
  98       still the uservd.
  99
 100  12 - The service failed onm the service side in an expected and
 101       controlled manner, for example because it was rejected in the
 102       configuration files.
 103
 104  16 - A fatal system call failure or other general error occurred,
 105       which ought not to have happened at all, barring system resource
 106       shortages.
 107
 108  20 - The client sent invalid data to the server, after the client
 109       dropped all its system privilege.  On some systems this can be
 110       caused by a malicious calling user.
 111
 112  SIGABRT/SIGIOT - The client sent invalid data to the server before it
 113    dropped all its system privileges, or some other unexpected
 114    internal error occurred.  This can also occur if an attempt to
 115    block signals using sigprocmask fails.
 116
 117  0-3,5-7,9,11,13-15,17-19 are not currently used by normal children.
 118
 119 REENTRANCY IN THE LIBC:
 120
 121 We assume, both in the client and server, that it is safe to use one
 122 stdio stream in a signal handler which interrupts use of a _different_
 123 stdio stream in another.  We make sure using setvbuf that we have
 124 pre-allocated buffers so that stdio doesn't need to use malloc() when
 125 we actually read or write.  stdio had better not do anything else
 126 weird.
 127
 128 Furthermore, we assume that it is safe to use syslog in a signal
 129 handler which has interrupted a stdio operation (but we don't require
 130 that it be safe to invoke when the signal has interrupted a call to
 131 malloc, unless stdio makes gratuitous mallocs).  openlog will already
 132 have been called (but syslog will not necessarily have been called).
 133
 134 We assume that strerror is completely reentrant.
 135
 136 PROBLEMS
 137
 138 * `function declaration isn't a prototype'
 139
 140   One some systems (at least some versions of NetBSD, for example),
 141   the SIG_IGN and SIG_DFL macros contain function declarations (as part
 142   of a typecast, presumably) which are not prototypes.  The warning
 143   options that are used by default if the configure script detects that
 144   you're using a good GCC then cause the compilation to fail.  You must
 145   use
 146     make CFLAGS=-O2
 147   instead of just `make', thus suppressing warnings.
 148
 149   The bug is actually in your system header files, for not specifying
 150   the number and types of arguments to signal handler functions when
 151   they cast in the SIG_IGN and SIG_DFL macros.
 152
 153 DEBUGGING VERSION
 154
 155 If you run configure with --enable-debug, a debugging version will be
 156 built.  This will look in the current directory (the build directory)
 157 for the base of various things, including the IPC area (which you must
 158 therefore construct yourself).  The debugging version will produce
 159 extra output at various points.  It will not attempt to call
 160 setgroups(), instead just checking that the groups list is right, so
 161 it will work non-setuid if the daemon is invoked as the service user.
 162 The daemon won't fork for each request; instead, it will handle a
 163 single request and exit.
 164
 165 There may be other changes.  Consult the code for details.  Making the
 166 debugging version of the client or daemon setuid root is probably a
 167 bad idea.  They may not work if they are run as different users.
 168
 169
 170 COPYRIGHT
 171
 172 This file, INSTALL, contains installation instructions and other
 173 details for userv.
 174
 175 userv is
 176 Copyright (C)1996-2000 Ian Jackson <ian@davenant.greenend.org.uk>.
 177 Copyright (C)2000      Ben Harris <bjh21@cam.ac.uk>
 178
 179 userv is free software; you can redistribute it and/or modify it under
 180 the terms of the GNU General Public License as published by the Free
 181 Software Foundation; either version 2 of the License, or (at your
 182 option) any later version.
 183
 184 This program is distributed in the hope that it will be useful, but
 185 WITHOUT ANY WARRANTY; without even the implied warranty of
 186 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 187 General Public License for more details.
 188
 189 You should have received a copy of the GNU General Public License
 190 along with userv as the file COPYING; if not, email me at the address
 191 above or write to the Free Software Foundation, 59 Temple Place -
 192 Suite 330, Boston, MA 02111-1307, USA.