ANNOUNCE: new module: Daemon::Generic

NAME
Daemon::Generic - framework to provide start/stop/reload for a daemon

SYNOPSIS
use Daemon::Generic;

sub gd_run { ... stuff }
sub gd_preconfig { ... stuff }

newdaemon();

DESCRIPTION
Daemon::Generic provides a framework for starting, stopping,
reconfiguring daemon-like programs. The framework provides for standard
commands that work for as init.d files and as apachectl-like commands.

Programs that use Daemon::Generic subclass Daemon::Generic to override
its behavior. Almost everything that Genric::Daemon does can be
overridden as needed.

EXAMPLE USAGE OUTPUT
Unless overriden, the usage output for your program will look something
like this:

Usage: $progname [ -c file ] [ -f ] { start | stop | reload | restart | help | version | check }
-c Specify configuration file (defaults to $configfile)
-f Run in the foreground (don't detach)
start Starts a new $progname if there isn't one running already
stop Stops a running $progname
reload Causes a running $progname to reload it's config file. Starts
a new one if none is running.
restart Stops a running $progname if one is running. Starts a new one.
check Check the configuration file and report the daemon state
help Display this usage info
version Display the version of $progname

CONSTRUCTION
To hand control over to "Daemon::Generic", call "newdaemon()". Control
will be handed back through method calls to functions you define.

Your @ISA will be modified to include "Daemon::Generic" if if it isn't
already there.

These are the arguments to "newdaemon()". Defaults are in (parenthesis).

progname ($0) The name of this program. This will be used for
logging and for naming the PID file.

configfile ("/etc/$progname.conf") The location of the configuration
file for this daemon.

pidbase (/var/run/$progname) We include the configuration file
name as part of the pid file in case there are multiple
instances of this deamon. The pidbase is is the part of
the PID file that does not include the configuration file
name.

pidfile ("$pidbase.$configfile.pid") The location of the process
id file.

foreground (0) Do not detach/daemon and run in the foreground
instead.

debug (0) Turn on debugging.

no_srand (0) Normall srand() is called. If no_srand is set then
srand() won't be called.

options () Additional arguments for Getopt::Long::GetOptions
which is used to parse @ARGV. Alternatively: define
"&gd_more_opt()".

minimum_args (1) Minimum number of @ARGV arguments after flags have
been processed.

maximum_args (1) Maximum number of @ARGV arguments after flags have
been processed.

version ($pkg::VERSION) The version number of the daemon.

MUST-OVERRIDE CALLBACK METHODS
The package that subclasses Daemon::Generic must provide the following
callback methods.

gd_preconfig() "gd_preconfig()" is called to parse the configuration
file ("$self->{configfile}"). Preconfig is called on all
invocations of the daemon ("daemon reload", "daemon
check", "daemon stop", etc). It shouldn't start anything
but it can and should verify that the config file is
fine.

The return value should be a hash. With one exception,
the return value is only used by "gd_postconfig()". The
exception is that "gd_preconfig()" may return a revised
PID file location (key "pidfile").

gd_run() This is where you put your main program.

MAY-OVERRIDE CALLBACK METHODS
The package that subclasses Daemon::Generic does not have to override
these methods but it may want to.

gd_postconfig(%config)
Postconfig() is called only when the daeamon is actually
starting up. (Or on reconfigs). It is passed the return
value from "gd_preconfig".

gd_setup_signals()
Set things up so that SIGHUP calls gd_reconfig_event()
and SIGINT calls gd_quit_event(). It will call these at
any time so if you want to delay signal delivery or
something you should override this method.

gd_getopt() This is invoked to parse the command line. Useful things
to modify are:

$self->{configfile} The location of the configuration
file to be parsed by
"gd_preconfig()".

$self->{foreground} Run in the foreground (don't
daemonize).

$self->{debug} Use it yourself.

The supplied "gd_getopt()" method uses Getopt::Long.

gd_parse_argv()
Parse any additional command line arguments beyond what
"gd_getopt()" handled.

$ARGV[0] needs to be left alone if it is one of the
following standard items:

start Start up a new daemon.

stop Stop the running daemon.

restart Stop the running daemon, start a new one.

reload Send a signal to the running daemon, asking it
to reconfigure itself.

check Just check the configuration file.

help Print the help screen (probably usage()).

version Display the daemon's version.

There is no default "gd_parse_argv()".

gd_check($pidfile, $pid)
Normal behavior: return. Define additional checks to run
when the "check" command is given. A $pid will only be
supplied if there is a daemon running.

gd_version() Normal behavior: display a version message and exit.

gd_help() Normal behavior: call "gd_usage()".

gd_commands_more()
Used by "gd_usage()": provide information on additional
commands beyond "start", "stop", "reload", etc. Return is
an array of key value pairs.

sub gd_commands_more
{
return (
savestate => 'Tell xyz server to save its state',
reset => 'Tell xyz servr to reset',
);
}

gd_flags_more Like "gd_commands_more()" but defines additional command
line flags. There should also be a "gd_more_opt()" or an
"options" argument to "new()".

gd_positional_more
Like "gd_commands_more()" but defines positional
arguments.

gd_usage() Display a usage message. The return value from
"gd_usage()" is the exit code for the program.

gd_more_opt() () Additional arguments for Getopt::Long::GetOptions
which is used to parse @ARGV. Alternatively: pass
"options" to "new()".

gd_pidfile() Figure out the PID file should be.

gd_error() Print out an error (call die?)

gd_other_cmd() Called $ARGV[0] isn't one of the commands that
Daemon::Generic knows by default. Default behavior: call
"gd_usage()" and exit(1).

gd_daemonize() Normal behavior: "fork()", "fork()", detach from tty.

gd_redirect_output()
Normal behavior: redirect "STDOUT" and "STDERR" to
"logger -t $progname[$$]". Used by "gd_daemonize()".

gd_logname() Normal behavior: $progname[$$]. Used by
"gd_redirect_output()".

gd_reconfig_event()
Normal behavior: call "gd_postconfig(gd_preconfig))".
Only referenced by "gd_setup_signals()".

gd_quit_event()
Normal behavior: exit. Only referenced by
"gd_setup_signals()".

gd_kill($pid) Used by the "stop" and "restart" commands to get rid of
the old daemon. Normal behavior: send a SIGINT. Check to
see if process $pid has died. If it has not, keep
checking and if it's still alive. After
$Daemon::Generic::force_quit_delay seconds, send a
SIGTERM. Keep checking. After another
$Daemon::Generic::force_quit_delay seconds, send a
SIGKILL (-9). Keep checking. After
"$Daemon::Generic::force_quit_delay * 4" seconds or 60
seconds (whichever is smaller), give up and exit(1).

gd_install Installs the daemon so that it runs automatically at next
reboot. Currently done with a symlink to $0 and
"/usr/sbin/update-rc.d". Please send patches for other
methods!

gd_can_install Returns a function to do an "gd_install" if installation
is possible. Returns 0 otherwise.

gd_install_pre($method)
Normal behavior: return. Called just before doing an
installation. The method indicates the installation
method (currently always "update-rc.d".)

gd_install_post($method)
Normal behavior: return. Called just after doing an
installation.

gd_uninstall Will remove the daemon from the automatic startup regime.

gd_can_uninstall
Returns a function to do the work for "gd_uninstall" if
it's possible. 0 otherwise.

gd_uninstall_pre($method)
Normal behavior: return. Called just before doing an
un-installation. The method indicates the installation
method (currently always "update-rc.d".)

gd_install_post($method)
Normal behavior: return. Called just after doing an
un-installation.

MEMBER DATA
Since you need to subclass Daemon::Generic, you need to know what the
internal data structures for Daemon::Generic are. With two exceptions,
all of the member data items begin with the prefix "gd_".

configfile The location of the configuration file. (Not used by
Daemon::Generic).

debug Display debugging? (Not used by Daemon::Generic)

gd_args The original %args passed to "new".

gd_progname The process name. (defaults to $0)

gd_pidfile The location of the process ID file.

gd_foreground Are we running in the foreground?

EXAMPLE PROGRAM
my $sleeptime = 1;

newdaemon(
progname => 'ticktockd',
pidfile => '/var/run/ticktockd.pid',
configfile => '/etc/ticktockd.conf',
);

sub gd_preconfig
{
my ($self) = @_;
open(CONFIG, "<$self->{gd_configfile}") or die;
while() {
$sleeptime = $1 if /^sleeptime\s+(\d+)/;
}
close(CONFIG);
return ();
}

sub gd_run
{
while(1) {
sleep($sleeptime);
print scalar(localtime(time))."\n";
}
}

SEE ALSO
With a while(1) and delayed signal delivery: Daemon::Generic::While1.

With Event: Daemon::Generic::Event.

Other modules that do similar things: Net::Daemon, Net::Server,
Net::Server::Daemonize, NetServer::Generic, Proc::Application::Daemon,
Proc::Daemon, Proc::Forking.

LICENSE
Copyright(C) 2006 David Muir Sharnoff . This module may
be used and distributed on the same terms as Perl itself.

--