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 (parenthesis).
49
50       progname       ($0) The name of this program.  This will be used for
51                      logging and for naming the PID file.
52
53       configfile     ("/etc/$progname.conf") The location of the
54                      configuration file for this daemon.
55
56       pidbase        (/var/run/$progname) We include the configuration file
57                      name as part of the pid file in case there are multiple
58                      instances of this daemon.  The pidbase is the part of
59                      the PID file that does not include the configuration
60                      file name.
61
62       pidfile        ("$pidbase.$configfile.pid") The location of the process
63                      id file.
64
65       foreground     (0) Do not detach/daemon and run in the foreground
66                      instead.
67
68       debug          (0) Turn on debugging.
69
70       no_srand       (0) Normall srand() is called.  If no_srand is set then
71                      srand() won't be called.
72
73       options        () Additional arguments for Getopt::Long::GetOptions
74                      which is used to parse @ARGV.  Alternatively: define
75                      &gd_more_opt().
76
77       minimum_args   (1) Minimum number of @ARGV arguments after flags have
78                      been processed.
79
80       maximum_args   (1) Maximum number of @ARGV arguments after flags have
81                      been processed.
82
83       version        ($pkg::VERSION) The version number of the daemon.
84
85       logpriority    Used for "logger -p".
86

MUST-OVERRIDE CALLBACK METHODS

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

MAY-OVERRIDE CALLBACK METHODS

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

MEMBER DATA

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

EXAMPLE PROGRAM

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

SEE ALSO

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

LICENSE

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

PACKAGERS

349       Daemon::Generic is packaged for Fedora by Emmanuel Seyman
350       <emmanuel.seyman@club-internet.fr>.
351
352
353
354perl v5.36.0                      2023-01-20                Daemon::Generic(3)
Impressum