README
~~~~~~
This contains the source code to daemon and libslack.

daemon - turns other processes into daemons

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).

libslack - A UNIX/C library of general utilities for programmers with slack

Libslack contains many modules of general utility (including the ability to
become a daemon) in a separately linkable form. This can be useful for
writing daemons in languages that can link against C functions (e.g. C, C++).
Libslack also contains many other general utility functions. See the
documentation for details.

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.

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.0 and Solaris 2.6.
Compiling on Solaris 2.6 requires running conf/solaris 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 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) or vsscanf(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
library to be compiled.

To build and test:

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

To install just the daemon program and its manpage:

        make install-daemon

To install just libslack and its manpages:

        make install-slack

To install both:

        make install

For more details:

        make help

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

REQUIREMENTS
~~~~~~~~~~~~
Requires perl to run the scripts in the conf directory.
Requires 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 perl and GNU tar to make the distribution.
Requires POSIX 1003.2 compliant regex functions. See INSTALL.

COPYING
~~~~~~~
daemon - turns other processes into daemons
Copyright (C) 1999, 2000 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, 2000 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

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)

TODO
~~~~
    - Add modules: tty/pty, timo, thr
    - Add pool, gc(?) to mem module
    - Use autoconf
    - Use libtool

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