README
~~~~~~
daemon - turns other processes into daemons

DESCRIPTION
~~~~~~~~~~~
Daemon turns other processes into daemons. There are many tasks that need to
be performed to correctly set up a daemon process. This can be tedious.
Daemon performs these tasks for other processes. This is useful for writing
daemons in languages other than C, C++ or Perl (e.g. /bin/sh, Java).

If you want to write daemons in languages that can link against C functions
(e.g. C, C++), see libslack which contains the core functionality of daemon.

DETAILS
~~~~~~~
Daemon turns other processes into daemons. There are many tasks that need to
be performed to correctly set up a daemon process. This can be tedious.
Daemon performs these tasks for other processes.

The preparatory tasks that daemon performs for other processes are:

o Disable core file generation to prevent security holes in daemons run by
  root (unless the --core option is supplied).

o If daemon was not invoked by init(8) or inetd(8):

  o Background the process to lose process group leadership.

  o Start a new process session.

  o Under SVR4, background the process again to lose process session
    leadership. This prevents the process from ever gaining a controlling
    terminal. This only happens when SVR4 is defined and
    NO_EXTRA_SVR4_FORK is not defined when libslack is compiled.

o Change to the root directory so as not to hamper umounts.

o Clear the umask to enable explicit file creation modes.

o Close all open file descriptors. If daemon was invoked by inetd(8)
  stdin, stdout and stderr are left open since they are open to a
  socket.

o Open stdin, stdout and stderr to /dev/null in case something
  requires them to be open. Of course, this is not done if daemon was
  invoked by inetd(8).

o If the --name option is supplied, create and lock a file containing the
  process id of the daemon process. The presence of this locked file
  prevents two instances of a daemon with the same name from running at the
  same time.

If the --user option is supplied, daemon changes the user id (and possibly
the group id). Only root can use this option.

Daemon then spawns the client command specified on its command line and
waits for it to terminate. If the --syslog option is supplied, the client's
standard output and error are captured by daemon and sent to the syslog
destination specified in the --syslog option.

When the client terminates, daemon respawns it if the --respawn option is
supplied and the client terminated successfully after at least 600 seconds.
Otherwise daemon terminates.

If daemon receives a SIGTERM signal, it propagates the signal to the client
and then terminates.

Note: For security reasons, never install I<daemon> with setuid or setgid
privileges. It is unnecessary. If you do, I<daemon> will revert to the real
user and group for safety before doing anything else.

INSTALL
~~~~~~~
Currently this is only known to work on Linux Redhat 6.x/7.x and Solaris 2.6.
Compiling on Solaris 2.6 requires running conf/solaris-cc (If you have the
Sun WorkShop C compiler) or conf/solaris-gcc (If you have gcc) in the source
directory. It is ready to compile on Linux as distributed so it is not
necessary to run conf/linux. There isn't a real configure script yet so you
will no doubt encounter problems on other systems. An ANSI C and POSIX
environment will help greatly.

If your system doesn't have snprintf(3), GNU getopt_long(3), vsscanf(3),
strcasecmp(3), strncasecmp(3), strlcpy(3) or strlcat(3), uncomment the
relevant lines in the libslack/macros.mk file to include them in libslack.

If your system doesn't have POSIX 1003.2 compliant regex functions, either:
install the GNU implementation, ftp://ftp.gnu.org/gnu/regex/regex-0.12.tar.gz
[290K] (doesn't support internationalisation); or install Henry Spencer's
implementation, ftp://ftp.zoo.toronto.edu/pub/regex.shar [157K].

If you really, really, really don't want the regular expression functions,
uncomment REGEX_MISSING in libslack/macros.mk to enable the rest of the
str module to be compiled.

If you have a linux-2.2.x system, you must have LinuxThreads-0.8 or
LinuxThreads-0.9 and the latest corresponding version of glibc.
If you have a linux-2.4.x system, you must have at least glibc-2.2.1
and glibc-linuxthreads-2.2.1. They are available from
http://ftp.gnu.org/pub/gnu/glibc/. Older versions can be used but
they are buggy and I don't want to hear about it.

First, uninstall any previous version:

        cd daemon-0.3
		make uninstall

To build and test:

        tar xzf daemon-0.4.tar.gz
        cd daemon-0.4
        conf/<your-system>   # if applicable (i.e. solaris-gcc, solaris-cc)
        make
        make test            # note: compiling the tests can take ages

To install just the daemon program and its manpage (in /usr/local by default):

        make install-daemon

To install just libslack and its manpages (into /usr/local by default):

        make install-slack

To install both (into /usr/local by default):

        make install

To install into somewhere other than /usr/local:

        make PREFIX=/opt/daemon install

To uninstall:

        make uninstall

For more details:

        make help

The manpage for daemon is daemon(1). There is one manpage for each module in
libslack (as well as one for each function). The module manpages are
daemon(3), err(3), fio(3), hsort(3), lim(3), list(3), map(3), mem(3),
msg(3), net(3), prog(3), prop(3), sig(3), str(3) and thread(3). If
necessary, the manpages getopt(3), snprintf(3) and vsscanf(3) are created as
well.

BINARY PACKAGES
~~~~~~~~~~~~~~~
To install from the RPM binary package (into /usr by default):

        rpm -i daemon-0.4-1.i386.rpm

To install from the RPM binary package into somewhere other than /usr:

        rpm --prefix=/usr/local -i daemon-0.4-1.i386.rpm

To install from the (relocatable) Debian binary package (into /usr):

        dpkg -i daemon_0.4_i386.deb

To install from the (relocatable) Solaris binary package (into /opt/daemon):

        gunzip daemon-0.4.sun4u.pkg.gz
        pkgadd -d daemon-0.4.sun4u.pkg

REQUIREMENTS
~~~~~~~~~~~~
Requires perl to run the scripts in the conf directory.
Repuires perl to install per-function manpage links.
Requires an ANSI C compiler like gcc to compile the source.
Requires pod2man (comes with perl) to make the manpages.
Requires pod2html (comes with perl) to make the html manpages.
Requires POSIX 1003.2 compliant regex functions. See INSTALL.
Requires libpthread. See INSTALL.

COPYING
~~~~~~~
daemon - turns other processes into daemons
Copyright (C) 1999-2001 raf <raf@raf.org>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
    or visit http://www.gnu.org/copyleft/gpl.html

libslack - A UNIX/C library of general utilities for programmers with slack
Copyright (C) 1999-2001 raf <raf@raf.org>

    This library is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
    or visit http://www.gnu.org/copyleft/gpl.html

$OpenBSD: strlcpy.c,v 1.4 1999/05/01 18:56:41 millert Exp $
$OpenBSD: strlcat.c,v 1.5 2001/01/13 16:17:24 millert Exp $
Copyright (c) 1998 Todd C. Miller <Todd.Miller@courtesan.com>
All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
    1. Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
    2. Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
    3. The name of the author may not be used to endorse or promote products
       derived from this software without specific prior written permission.
    
    THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
    INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
    AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
    THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
    ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

HISTORY
~~~~~~~
0.1
    - Initial version

0.2
    - Decoupled core file prevention from daemon_init()
      into its own function, daemon_prevent_core()
    - Decoupled signal handling from daemon_init()
    - Cached daemon_started_by_init() and daemon_started_by_inetd() results
    - Fixed bug when formatting --help message
    - Added some modules to libprog: conf, list, hsort, map, prop
    - Added timestamps to msg_out_file()
    - Included source to GNU getopt_long_only() (if neccessary)
    - Added hdr.h to allow non-ANSI compilers to parse libprog's headers
    - Moved libprog to a subdirectory using a "Whole Project" Makefile
    - Converted "Whole Project" Makefile into "Scalable" Makefiles
    - Added verbosity functions to libprog(prog)
    - Added -core option to allow core file generation
    - Added -respawn option to allow client respawn if death not too sudden
    - Added -syslog option to redirect client stdout and stderr to syslog
    - Added -log option to specify where daemon stdout and stderr are sent
    - Fixed bug when constructing data for GNU getopt_long_only()
    - Fixed bugs in the options table for libprog(prog)
    - Changed help message format: separated option chunks by a blank line
    - Fixed bug when obtaining names associated with syslog constants
    - Added -Config option and /etc/daemon.conf handling
    - Added pathetic conf/linux and conf/solaris scripts
    - Revert to real uid/gid if not same as effective uid/gid for safety
    - Added manpages

0.3
    - Started using GNU getopt_long() instead of getopt_long_only()
    - Started ignoring /etc/daemon.conf if group or world writable
    - Added -DSVR4 in conf/solaris (doh!)
    - Added conditional compilation of debug functions
    - Added assert macro that calls dump()
    - Completed the daemon(1) manpage (common options weren't documented)
    - Fixed bug: SIG_IGN, SIG_DFL and nasty signals weren't treated specially
    - Made lists grow/shrink exponentially rather than linearly
    - Made maps grow as needed and use arbitrary hash functions and key types
    - Added multi-dimensional array allocator to the mem module
    - Added net module: clients/servers, expect/send, pack/unpack, mail
    - Added internal iterators and some more functions to list and map
    - Added examples sections to some libprog manpages
    - Added --user option
    - Added str module: decent strings + tr, regex, regsub, fmt, trim, lc, uc ...
    - Added vsscanf(3) implementation for systems that don't have it (e.g. solaris)
    - Renamed libprog to libslack (thanks, fred!)
    - Added socks.h
    - Added daemon_revoke_privileges(), daemon_file_is_safe() to daemon module
    - Moved revocation of setuid/setgid privileges to start for greater safety
    - Fixed bug: wasn't unlinking pidfile when client died of natural causes
    - Fixed bug: wasn't processing config file correctly
    - Included daemon(1) tests in distribution (not automatic, though)

0.4
    - Fixed memory usage bugs
    - Added daemon demo directory (previously, the incomplete "test" directory)
    - Changed net server/client functions to use service name else port number
    - Fixed security bug: daemon_file_is_safe() wasn't following symlinks (doh!)
    - Changed -d and -v options to take optional arguments (both default to 1)
    - Renamed daemon_file_is_safe() to daemon_path_is_safe()
    - Added daemon_absolute_path() to daemon module
    - Added memory pool functions to mem module
    - Fixed bug: optional option arguments were handled in dodgy C
    - Made supplied snprintf() POSIX compliant (was using getpagesize())
    - Removed conf module (Added daemon_parse_config() to daemon module)
    - Removed net_chat(), rfc822_localtime(), rfc822_gmtime() (not useful enough)
    - Added secure memory/pool functions to mem module
    - Fixed Makefile bug: $(CCFLAGS) for daemon and libslack weren't separate
    - Added fgetline() to fifo module (reads a line with any line ending)
    - Added str_fgetline() to str module (like fgetline but handles any length)
    - Renamed fifo module to fio
    - Fixed Makefile bug: wasn't uninstalling everything properly
    - Changed net_send() to take a timeout argument like next_expect() does
    - Added strlcpy(), strlcat(), strcasecmp() and strncasecmp() to str module
    - Changed debug levels used by daemon(1) from 8 and 9 to 1 and 2
    - Renamed conf/solaris to solaris-gcc and added solaris-cc for sun workshop
    - Fixed bug: -n and -u options together failed to unlink pidfiles
    - Fixed security bug: wasn't clearing supplementary groups with -u option
    - Added support for root and user pidfiles in separate directories
    - Added make rpm rpm-daemon rpm-slack (with Edward Avis epa98@doc.ic.ac.uk)
    - Added installation of manpages for each function (link to module manpage)
    - Added libslack(3) overview manpage
    - Added list_break(), map_break()
    - Renamed assert() to check() for obvious reasons
    - Renamed re funcs in str module: s/regex/regexpr/g
    - Added thread module and made everything MT-Safe or MT-Disciplined
    - Added relative index/range semantics to string functions
    - Added make deb deb-daemon deb-slack (debian binary packages)
    - Added make pkg pkg-daemon pkg-slack (solaris binary packages)
    - Added setsockopt(SO_REUSEADDR) for net servers
    - Changed net server/client API to allow optional setsockopt(RCVBUF/SNDBUF)
    - Added REFERENCES section to README file
    - Stopped net_expect/net_send from interfering with SIGALRM/alarm/setitimer
    - Added read_timeout(), write_timeout() and rw_timeout() to fio module
    - Changed net_read() and net_write() to take a timeout argument
    - Added '?' field size specifier to unpack() (for packet length fields)
    - Added libslack-config administration utility
    - Renamed sockaddr typedef to sockaddr_t
    - Changed net_client to take a timeout parameter
    - Fixed fd leak in error handling code in net server/client functions
    - Fixed bug: str_regsub() didn't handle empty string matches at all
    - Changed str_regexpr_split() to take cflags and eflags arguments
    - Changed all *_destroy macros to functions that take address of pointer
    - Changed mem_resize macro so client must explicitly provide address of mem
    - Changed all *_destroy_t typedefs to *_release_t
    - Added make [un]install-{daemon|slack}-html (not part of make [un]install)
    - Temporarily removed snprintf module (not MT-Safe, not essential)
    - Merged lognames module into msg module
    - Merged opt module into prog module
    - Renamed _* functions in err module to *f (not ANSI compliant)
    - Removed MANIFEST

TODO
~~~~
    - MT signal handling
    - Decouple memory type and strategy from List/Map/String code into mem
    - Add pty/coproc to fio module
    - Add agent module (select/poll + hashed/hierarchical timing wheels)
    - Add debian source package creation
    - Use autoconf and libtool (when API is stable, then add *-devel packages)
    - Generate sub library packages (at least: daemon, str, net, agent)

REFERENCES
~~~~~~~~~~
Advanced Programming in the UNIX Environment
W. Richard Stevens
Addison-Wesley Professional Computing Series, 1992

UNIX Network Programming
W. Richard Stevens
Prentice Hall Software Series, 1990

UNIX System V Network Programming
Stephen A. Rago
Addison-Wesley Professional Computing Series, 1993

The Practice of Programming
Brian W. Kernighan and Rob Pike,
Addison-Wesley Professional Computing Series, 1999

Multithreaded Programming with Pthreads
Bil Lewis and Daniel J. Berg
Sun Microsystem Press/Prentice Hall, 1998

Effective TCP/IP Programming
Jon C. Snader
Addison-Wesley, 2000

Design Patterns - Elements of Reusable Object-Oriented Software
Erich Gamma, Richard Helm, Ralph Johnson and John Vlissides
Addison-Wesley Professional Computing Series, 1995

The Standard C Library
P. J. Plauger
Prentice Hall, 1992

The Discipline and Method Architecture for Reusable Libraries
Kiem-Phong Vo
Software - Practice & Experience, v.30, pp.107-128, 2000
http://www.research.att.com/sw/tools/sfio/dm-spe.ps

strlcpy and strlcat--Consistent, Safe, String Copy and Concatenation
Todd C. Miller and Theo De Raadt
Proceedings of the FREENIX Track: 1999 USENIX Annual Technical Conference
http://www.usenix.org/events/usenix99/millert.html

The Perl manpages
Larry Wall

Practical UNIX and Internet Security
Simson Garfinkel and Gene Spafford
O'Reilly, 1996

Interconnections - Bridges, Routers, Switches and Internetworking Protocols
Radia Perlman
Addison-Wesley Professional Computing Series, 2000

MT-Disciplined
raf, http://raf.org/papers/mtdisc.html

Scalable Makefiles
raf, http://raf.org/papers/scalable-makefiles.html

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
URL: http://libslack.org/daemon/
Date: 20010215
Author: raf <raf@raf.org>
