1Daemon::Generic(3)    User Contributed Perl Documentation   Daemon::Generic(3)
2
3
4

NAME

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

SYNOPSIS

9        use Daemon::Generic;
10
11        sub gd_run { ... stuff }
12
13        newdaemon();
14

DESCRIPTION

16       Daemon::Generic provides a framework for starting, stopping,
17       reconfiguring daemon-like programs.  The framework provides for
18       standard commands that work for as init.d files and as apachectl-like
19       commands.
20
21       Programs that use Daemon::Generic subclass Daemon::Generic to override
22       its behavior.  Almost everything that Genric::Daemon does can be
23       overridden as needed.
24

EXAMPLE USAGE OUTPUT

26       Unless overridden, the usage output for your program will look
27       something like this:
28
29        Usage: $progname [ -c file ] [ -f ] { start | stop | reload | restart | help | version | check }
30         -c            Specify configuration file (defaults to $configfile)
31         -f            Run in the foreground (don't detach)
32         start         Starts a new $progname if there isn't one running already
33         stop          Stops a running $progname
34         reload        Causes a running $progname to reload it's config file.  Starts
35                       a new one if none is running.
36         restart       Stops a running $progname if one is running.  Starts a new one.
37         check         Check the configuration file and report the daemon state
38         help          Display this usage info
39         version       Display the version of $progname
40

CONSTRUCTION

42       To hand control over to "Daemon::Generic", call "newdaemon()".  Control
43       will be handed back through method calls to functions you define.
44
45       Your @ISA will be modified to include "Daemon::Generic" if if it isn't
46       already there.
47
48       These are the arguments to "newdaemon()".  Defaults are in
49       (parenthesis).
50
51       progname       ($0) The name of this program.  This will be used for
52                      logging and for naming the PID file.
53
54       configfile     ("/etc/$progname.conf") The location of the
55                      configuration file for this daemon.
56
57       pidbase        (/var/run/$progname) We include the configuration file
58                      name as part of the pid file in case there are multiple
59                      instances of this daemon.  The pidbase is the part of
60                      the PID file that does not include the configuration
61                      file name.
62
63       pidfile        ("$pidbase.$configfile.pid") The location of the process
64                      id file.
65
66       foreground     (0) Do not detach/daemon and run in the foreground
67                      instead.
68
69       debug          (0) Turn on debugging.
70
71       no_srand       (0) Normall srand() is called.  If no_srand is set then
72                      srand() won't be called.
73
74       options        () Additional arguments for Getopt::Long::GetOptions
75                      which is used to parse @ARGV.  Alternatively: define
76                      "&gd_more_opt()".
77
78       minimum_args   (1) Minimum number of @ARGV arguments after flags have
79                      been processed.
80
81       maximum_args   (1) Maximum number of @ARGV arguments after flags have
82                      been processed.
83
84       version        ($pkg::VERSION) The version number of the daemon.
85
86       logpriority    Used for "logger -p".
87

MUST-OVERRIDE CALLBACK METHODS

89       The package that subclasses Daemon::Generic must provide the following
90       callback methods.
91
92       gd_run()       This is where you put your main program.
93
94                      It is okay to change userid/group as the first action of
95                      gd_run().
96

MAY-OVERRIDE CALLBACK METHODS

98       The package that subclasses Daemon::Generic does not have to override
99       these methods but it may want to.
100
101       gd_preconfig() "gd_preconfig()" is called to parse the configuration
102                      file ("$self->{configfile}").  Preconfig is called on
103                      all invocations of the daemon ("daemon reload", "daemon
104                      check", "daemon stop", etc).  It shouldn't start
105                      anything but it can and should verify that the config
106                      file is fine.
107
108                      The return value should be a hash.  With one exception,
109                      the return value is only used by "gd_postconfig()".  The
110                      exception is that "gd_preconfig()" may return a revised
111                      PID file location (key "pidfile").
112
113                      Most uses of Daemon::Generic should define
114                      "gd_preconfig".
115
116       gd_postconfig(%config)
117                      Postconfig() is called only when the daemon is actually
118                      starting up.  (Or on reconfigs).  It is passed the
119                      return value from "gd_preconfig".
120
121       gd_setup_signals()
122                      Set things up so that SIGHUP calls gd_reconfig_event()
123                      and SIGINT calls gd_quit_event().  It will call these at
124                      any time so if you want to delay signal delivery or
125                      something you should override this method.
126
127       gd_getopt()    This is invoked to parse the command line.  Useful
128                      things to modify are:
129
130                      $self->{configfile} The location of the configuration
131                                          file to be parsed by
132                                          "gd_preconfig()".
133
134                      $self->{foreground} Run in the foreground (don't
135                                          daemonize).
136
137                      $self->{debug}      Use it yourself.
138
139                      The supplied "gd_getopt()" method uses Getopt::Long.
140
141       gd_parse_argv()
142                      Parse any additional command line arguments beyond what
143                      "gd_getopt()" handled.
144
145                      $ARGV[0] needs to be left alone if it is one of the
146                      following standard items:
147
148                      start     Start up a new daemon.
149
150                      stop      Stop the running daemon.
151
152                      restart   Stop the running daemon, start a new one.
153
154                      reload    Send a signal to the running daemon, asking it
155                                to reconfigure itself.
156
157                      check     Just check the configuration file.
158
159                      help      Print the help screen (probably usage()).
160
161                      version   Display the daemon's version.
162
163                      There is no default "gd_parse_argv()".
164
165       gd_check($pidfile, $pid)
166                      Normal behavior: return.  Define additional checks to
167                      run when the "check" command is given.  A $pid will only
168                      be supplied if there is a daemon running.
169
170       gd_version()   Normal behavior: display a version message and exit.
171
172       gd_help()      Normal behavior: call "gd_usage()".
173
174       gd_commands_more()
175                      Used by "gd_usage()": provide information on additional
176                      commands beyond "start", "stop", "reload", etc.  Return
177                      is an array of key value pairs.
178
179                       sub gd_commands_more
180                       {
181                              return (
182                                      savestate => 'Tell xyz server to save its state',
183                                      reset     => 'Tell xyz servr to reset',
184                              );
185                       }
186
187       gd_flags_more  Like "gd_commands_more()" but defines additional command
188                      line flags.  There should also be a "gd_more_opt()" or
189                      an "options" argument to "new()".
190
191       gd_positional_more
192                      Like "gd_commands_more()" but defines positional
193                      arguments.
194
195       gd_usage()     Display a usage message.  The return value from
196                      "gd_usage()" is the exit code for the program.
197
198       gd_more_opt()  () Additional arguments for Getopt::Long::GetOptions
199                      which is used to parse @ARGV.  Alternatively: pass
200                      "options" to "new()".
201
202       gd_pidfile()   Figure out the PID file should be.
203
204       gd_error()     Print out an error (call die?)
205
206       gd_other_cmd() Called $ARGV[0] isn't one of the commands that
207                      Daemon::Generic knows by default.  Default behavior:
208                      call "gd_usage()" and exit(1).
209
210       gd_daemonize() Normal behavior: "fork()", "fork()", detach from tty.
211
212       gd_redirect_output()
213                      This is a mis-named method.  Sorry.  This directs
214                      "STDOUT"/"STDERR"/"STDIN" to "/dev/null" as part of
215                      daemonizing.  Used by "gd_daemonize()".
216
217       gd_reopen_output()
218                      After daemonizing, output file descriptors are be re-
219                      established.  Normal behavior: redirect "STDOUT" and
220                      "STDERR" to "logger -t $progname[$$]".  Used by
221                      "gd_daemonize()".
222
223       gd_logname()   Normal behavior: $progname[$$].  Used by
224                      "gd_redirect_output()".
225
226       gd_reconfig_event()
227                      Normal behavior: call "gd_postconfig(gd_preconfig))".
228                      Only referenced by "gd_setup_signals()".
229
230       gd_quit_event()
231                      Normal behavior: exit.  Only referenced by
232                      "gd_setup_signals()".
233
234       gd_kill_groups()
235                      Return true if gd_kill should kill process groups ($pid)
236                      instead of just the one daemon ($pid).  Default is
237                      false.
238
239       gd_kill($pid)  Used by the "stop" and "restart" commands to get rid of
240                      the old daemon.  Normal behavior: send a SIGINT.  Check
241                      to see if process $pid has died.  If it has not, keep
242                      checking and if it's still alive.  After
243                      $Daemon::Generic::force_quit_delay seconds, send a
244                      SIGTERM.  Keep checking.  After another
245                      $Daemon::Generic::force_quit_delay seconds, send a
246                      SIGKILL (-9).  Keep checking.  After
247                      "$Daemon::Generic::force_quit_delay * 4" seconds or 60
248                      seconds (whichever is smaller), give up and exit(1).
249
250       gd_install     Installs the daemon so that it runs automatically at
251                      next reboot.  Currently done with a symlink to $0 and
252                      "/usr/sbin/update-rc.d".  Please send patches for other
253                      methods!
254
255       gd_can_install Returns a function to do an "gd_install" if installation
256                      is possible.  Returns 0 otherwise.
257
258       gd_install_pre($method)
259                      Normal behavior: return.  Called just before doing an
260                      installation.  The method indicates the installation
261                      method (currently always "update-rc.d".)
262
263       gd_install_post($method)
264                      Normal behavior: return.  Called just after doing an
265                      installation.
266
267       gd_uninstall   Will remove the daemon from the automatic startup
268                      regime.
269
270       gd_can_uninstall
271                      Returns a function to do the work for "gd_uninstall" if
272                      it's possible.  0 otherwise.
273
274       gd_uninstall_pre($method)
275                      Normal behavior: return.  Called just before doing an
276                      un-installation.  The method indicates the installation
277                      method (currently always "update-rc.d".)
278
279       gd_install_post($method)
280                      Normal behavior: return.  Called just after doing an un-
281                      installation.
282

MEMBER DATA

284       Since you need to subclass Daemon::Generic, you need to know what the
285       internal data structures for Daemon::Generic are.  With two exceptions,
286       all of the member data items begin with the prefix "gd_".
287
288       configfile     The location of the configuration file.  (Not used by
289                      Daemon::Generic).
290
291       debug          Display debugging?  (Not used by Daemon::Generic)
292
293       gd_args        The original %args passed to "new".
294
295       gd_progname    The process name.  (defaults to $0)
296
297       gd_pidfile     The location of the process ID file.
298
299       gd_logpriority Used for "logger -p".
300
301       gd_foreground  Are we running in the foreground?
302

EXAMPLE PROGRAM

304        my $sleeptime = 1;
305
306        newdaemon(
307               progname        => 'ticktockd',
308               pidfile         => '/var/run/ticktockd.pid',
309               configfile      => '/etc/ticktockd.conf',
310        );
311
312        sub gd_preconfig
313        {
314               my ($self) = @_;
315               open(CONFIG, "<$self->{configfile}") or die;
316               while(<CONFIG>) {
317                       $sleeptime = $1 if /^sleeptime\s+(\d+)/;
318               }
319               close(CONFIG);
320               return ();
321        }
322
323        sub gd_run
324        {
325               while(1) {
326                       sleep($sleeptime);
327                       print scalar(localtime(time))."\n";
328               }
329        }
330

SEE ALSO

332       With a while(1) and delayed signal delivery: Daemon::Generic::While1.
333
334       With Event: Daemon::Generic::Event.
335
336       With AnyEvent: Daemon::Generic::AnyEvent.
337
338       Modules that use Daemon::Generic: SyslogScan::Daemon; IO::Event
339       (rinetd.pl)
340
341       Other modules that do similar things: Net::Daemon, Net::Server,
342       Net::Server::Daemonize, NetServer::Generic, Proc::Application::Daemon,
343       Proc::Daemon, Proc::Forking.
344

LICENSE

346       Copyright (C) 2006-2010 David Muir Sharnoff <cpan@dave.sharnoff.org>.
347       Copyright (C) 2011 Google, Inc.  This module may be used and
348       distributed on the same terms as Perl itself.
349

PACKAGERS

351       Daemon::Generic is packaged for Fedora by Emmanuel Seyman
352       <emmanuel.seyman@club-internet.fr>.
353
354
355
356perl v5.28.1                      2013-10-05                Daemon::Generic(3)
Impressum