1 INSTALLATION INSTRUCTIONS:
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.
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]
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
30 * [v]snprintf - a real version, not just [v]sprintf with a wrapper
31 that throws the argument away.
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.
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)
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();
53 * lstat(2) (though stat(2) will be safe on systems without symlinks,
54 if you say -Dlstat=stat).
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).
65 To format the documentation:
67 * debiandoc-sgml, and hence sp (aka nsgmls) and sgmlspm.
68 * For PostScript output, Lout and possibly psutils.
70 For debugging version (./configure --enable-debug):
72 * initgroups(3) must use setgroups(2) and dynamic
73 linking must allow overriding setgroups(2) for initgroups(3);
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
81 With -daemon it will attempt to detach itself from the controlling
82 terminal and fork/exit so that control returns at startup.
84 In both cases diagnostics which prevent correct startup will appear on
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
104 crit - the uservd detected a non-recoverable error condition
105 after startup and will exit.
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
116 The daemon's exit code will reflect how well things went:
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
126 5* - There was a non-recoverable error after startup; the uservd had
128 6 - The daemon was asked to detach itself, but its detaching child
129 died for some unexpected reason.
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.
135 Outcomes marked * are not possible if the daemon is asked to detach
136 itself - these exit statuses will be reaped by init instead.
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.
143 2 - The connection was just an internal version check.
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.
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).
156 12 - The service failed onm the service side in an expected and
157 controlled manner, for example because it was rejected in the
160 16 - A fatal system call failure or other general error occurred,
161 which ought not to have happened at all, barring system resource
164 20 - The client sent invalid data to the server, after the client
165 dropped all its system privilege. On some systems this can be
166 caused by a malicious calling user.
168 SIGABRT/SIGIOT - The client sent invalid data to the server before it
169 dropped all its system privileges, or some other unexpected
170 internal error occurred. This can also occur if an attempt to
171 block signals using sigprocmask fails.
173 0-3,5-7,9-11,13-15,17-19 are not currently used.
175 REENTRANCY IN THE LIBC:
177 We assume, both in the client and server, that it is safe to use one
178 stdio stream in a signal handler which interrupts use of a _different_
179 stdio stream in another. We make sure using setvbuf that we have
180 pre-allocated buffers so that stdio doesn't need to use malloc() when
181 we actually read or write. stdio had better not do anything else
184 Furthermore, we assume that it is safe to use syslog in a signal
185 handler which has interrupted a stdio operation (but we don't require
186 that it be safe to invoke when the signal has interrupted a call to
187 malloc, unless stdio makes gratuitous mallocs). openlog will already
188 have been called (but syslog will not necessarily have been called).
190 We assume that strerror is completely reentrant.
194 * `function declaration isn't a prototype'
196 One some systems (at least some versions of NetBSD, for example),
197 the SIG_IGN and SIG_DFL macros contain function declarations (as part
198 of a typecast, presumably) which are not prototypes. The warning
199 options that are used by default if the configure script detects that
200 you're using a good GCC then cause the compilation to fail. You must
203 instead of just `make', thus suppressing warnings.
205 The bug is actually in your system header files, for not specifying
206 the number and types of arguments to signal handler functions when
207 they cast in the SIG_IGN and SIG_DFL macros.
211 If you run configure with --enable-debug, a debugging version will be
212 built. This will look in the current directory (the build directory)
213 for the base of various things, including the IPC area (which you must
214 therefore construct yourself). The debugging version will produce
215 extra output at various points. It will not attempt to call
216 setgroups(), instead just checking that the groups list is right, so
217 it will work non-setuid if the daemon is invoked as the service user.
218 The daemon won't fork for each request; instead, it will handle a
219 single request and exit.
221 There may be other changes. Consult the code for details. Making the
222 debugging version of the client or daemon setuid root is probably a
223 bad idea. They may not work if they are run as different users.
228 This file, INSTALL, contains installation instructions and other
231 userv is Copyright (C)1996-9 Ian Jackson <ian@davenant.greenend.org.uk>.
233 userv is free software; you can redistribute it and/or modify it under
234 the terms of the GNU General Public License as published by the Free
235 Software Foundation; either version 2 of the License, or (at your
236 option) any later version.
238 This program is distributed in the hope that it will be useful, but
239 WITHOUT ANY WARRANTY; without even the implied warranty of
240 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
241 General Public License for more details.
243 You should have received a copy of the GNU General Public License
244 along with userv as the file COPYING; if not, email me at the address
245 above or write to the Free Software Foundation, 59 Temple Place -
246 Suite 330, Boston, MA 02111-1307, USA.