Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Daemon::Generic(3)    User Contributed Perl Documentation   Daemon::Generic(3)

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

SYNOPSIS
	use Daemon::Generic;

	sub gd_run { ... 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 overridden, 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	daemon.	 The pidbase 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.

       logpriority    Used for "logger -p".

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

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

		      It is okay to change userid/group	as the first action of
		      gd_run().

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

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

		      Most uses	of Daemon::Generic should define
		      "gd_preconfig".

       gd_postconfig(%config)
		      Postconfig() is called only when the daemon 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()
		      This is a	mis-named method.  Sorry.  This	directs
		      "STDOUT"/"STDERR"/"STDIN"	to "/dev/null" as part of
		      daemonizing.  Used by "gd_daemonize()".

       gd_reopen_output()
		      After daemonizing, output	file descriptors are be	re-
		      established.  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_groups()
		      Return true if gd_kill should kill process groups	($pid)
		      instead of just the one daemon ($pid).  Default is
		      false.

       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_logpriority Used for "logger -p".

       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->{configfile}") or die;
	       while(<CONFIG>) {
		       $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.

       With AnyEvent: Daemon::Generic::AnyEvent.

       Modules that use	Daemon::Generic: SyslogScan::Daemon; IO::Event
       (rinetd.pl)

       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-2010 David Muir Sharnoff <cpan@dave.sharnoff.org>.
       Copyright (C) 2011 Google, Inc.	This module may	be used	and
       distributed on the same terms as	Perl itself.

PACKAGERS
       Daemon::Generic is packaged for Fedora by Emmanuel Seyman
       <emmanuel.seyman@club-internet.fr>.

perl v5.32.0			  2013-10-05		    Daemon::Generic(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE USAGE OUTPUT | CONSTRUCTION | MUST-OVERRIDE CALLBACK METHODS | MAY-OVERRIDE CALLBACK METHODS | MEMBER DATA | EXAMPLE PROGRAM | SEE ALSO | LICENSE | PACKAGERS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Daemon::Generic&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help