1Daemon::Generic(3) User Contributed Perl Documentation Daemon::Generic(3)
2
6 Daemon::Generic - framework to provide start/stop/reload for a daemon
7
9 use Daemon::Generic;
10 sub gd_run { ... stuff }
12 newdaemon();
14
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 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
26 Unless overridden, the usage output for your program will look
27 something like this:
28 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
42 To hand control over to "Daemon::Generic", call "newdaemon()". Control
43 will be handed back through method calls to functions you define.
44 Your @ISA will be modified to include "Daemon::Generic" if if it isn't
46 already there.
47 These are the arguments to "newdaemon()". Defaults are in
49 (parenthesis).
50 progname ($0) The name of this program. This will be used for
52 logging and for naming the PID file.
53 configfile ("/etc/$progname.conf") The location of the
55 configuration file for this daemon.
56 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 pidfile ("$pidbase.$configfile.pid") The location of the process
64 id file.
65 foreground (0) Do not detach/daemon and run in the foreground
67 instead.
68 debug (0) Turn on debugging.
70 no_srand (0) Normall srand() is called. If no_srand is set then
72 srand() won't be called.
73 options () Additional arguments for Getopt::Long::GetOptions
75 which is used to parse @ARGV. Alternatively: define
76 "&gd_more_opt()".
77 minimum_args (1) Minimum number of @ARGV arguments after flags have
79 been processed.
80 maximum_args (1) Maximum number of @ARGV arguments after flags have
82 been processed.
83 version ($pkg::VERSION) The version number of the daemon.
85 logpriority Used for "logger -p".
87
89 The package that subclasses Daemon::Generic must provide the following
90 callback methods.
91 gd_run() This is where you put your main program.
93 It is okay to change userid/group as the first action of
95 gd_run().
96
98 The package that subclasses Daemon::Generic does not have to override
99 these methods but it may want to.
100 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 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 Most uses of Daemon::Generic should define
114 "gd_preconfig".
115 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 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 gd_getopt() This is invoked to parse the command line. Useful
128 things to modify are:
129 $self->{configfile} The location of the configuration
131 file to be parsed by
132 "gd_preconfig()".
133 $self->{foreground} Run in the foreground (don't
135 daemonize).
136 $self->{debug} Use it yourself.
138 The supplied "gd_getopt()" method uses Getopt::Long.
140 gd_parse_argv()
142 Parse any additional command line arguments beyond what
143 "gd_getopt()" handled.
144 $ARGV[0] needs to be left alone if it is one of the
146 following standard items:
147 start Start up a new daemon.
149 stop Stop the running daemon.
151 restart Stop the running daemon, start a new one.
153 reload Send a signal to the running daemon, asking it
155 to reconfigure itself.
156 check Just check the configuration file.
158 help Print the help screen (probably usage()).
160 version Display the daemon's version.
162 There is no default "gd_parse_argv()".
164 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 gd_version() Normal behavior: display a version message and exit.
171 gd_help() Normal behavior: call "gd_usage()".
173 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 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 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 gd_positional_more
192 Like "gd_commands_more()" but defines positional
193 arguments.
194 gd_usage() Display a usage message. The return value from
196 "gd_usage()" is the exit code for the program.
197 gd_more_opt() () Additional arguments for Getopt::Long::GetOptions
199 which is used to parse @ARGV. Alternatively: pass
200 "options" to "new()".
201 gd_pidfile() Figure out the PID file should be.
203 gd_error() Print out an error (call die?)
205 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 gd_daemonize() Normal behavior: "fork()", "fork()", detach from tty.
211 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 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 gd_logname() Normal behavior: $progname[$$]. Used by
224 "gd_redirect_output()".
225 gd_reconfig_event()
227 Normal behavior: call "gd_postconfig(gd_preconfig))".
228 Only referenced by "gd_setup_signals()".
229 gd_quit_event()
231 Normal behavior: exit. Only referenced by
232 "gd_setup_signals()".
233 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 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 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 gd_can_install Returns a function to do an "gd_install" if installation
256 is possible. Returns 0 otherwise.
257 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 gd_install_post($method)
264 Normal behavior: return. Called just after doing an
265 installation.
266 gd_uninstall Will remove the daemon from the automatic startup
268 regime.
269 gd_can_uninstall
271 Returns a function to do the work for "gd_uninstall" if
272 it's possible. 0 otherwise.
273 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 gd_install_post($method)
280 Normal behavior: return. Called just after doing an un-
281 installation.
282
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 configfile The location of the configuration file. (Not used by
289 Daemon::Generic).
290 debug Display debugging? (Not used by Daemon::Generic)
292 gd_args The original %args passed to "new".
294 gd_progname The process name. (defaults to $0)
296 gd_pidfile The location of the process ID file.
298 gd_logpriority Used for "logger -p".
300 gd_foreground Are we running in the foreground?
302
304 my $sleeptime = 1;
305 newdaemon(
307 progname => 'ticktockd',
308 pidfile => '/var/run/ticktockd.pid',
309 configfile => '/etc/ticktockd.conf',
310 );
311 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 sub gd_run
324 {
325 while(1) {
326 sleep($sleeptime);
327 print scalar(localtime(time))."\n";
328 }
329 }
330
332 With a while(1) and delayed signal delivery: Daemon::Generic::While1.
333 With Event: Daemon::Generic::Event.
335 With AnyEvent: Daemon::Generic::AnyEvent.
337 Modules that use Daemon::Generic: SyslogScan::Daemon; IO::Event
339 (rinetd.pl)
340 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
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
351 Daemon::Generic is packaged for Fedora by Emmanuel Seyman
352 <emmanuel.seyman@club-internet.fr>.
353perl v5.28.0 2013-10-05 Daemon::Generic(3)