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 sub gd_preconfig { ... stuff }
13 newdaemon();
15
17 Daemon::Generic provides a framework for starting, stopping,
18 reconfiguring daemon-like programs. The framework provides for
19 standard commands that work for as init.d files and as apachectl-like
20 commands.
21 Programs that use Daemon::Generic subclass Daemon::Generic to override
23 its behavior. Almost everything that Genric::Daemon does can be
24 overridden as needed.
25
27 Unless overriden, the usage output for your program will look something
28 like this:
29 Usage: $progname [ -c file ] [ -f ] { start | stop | reload | restart | help | version | check }
31 -c Specify configuration file (defaults to $configfile)
32 -f Run in the foreground (don't detach)
33 start Starts a new $progname if there isn't one running already
34 stop Stops a running $progname
35 reload Causes a running $progname to reload it's config file. Starts
36 a new one if none is running.
37 restart Stops a running $progname if one is running. Starts a new one.
38 check Check the configuration file and report the daemon state
39 help Display this usage info
40 version Display the version of $progname
41
43 To hand control over to "Daemon::Generic", call "newdaemon()". Control
44 will be handed back through method calls to functions you define.
45 Your @ISA will be modified to include "Daemon::Generic" if if it isn't
47 already there.
48 These are the arguments to "newdaemon()". Defaults are in
50 (parenthesis).
51 progname ($0) The name of this program. This will be used for
53 logging and for naming the PID file.
54 configfile ("/etc/$progname.conf") The location of the
56 configuration file for this daemon.
57 pidbase (/var/run/$progname) We include the configuration file
59 name as part of the pid file in case there are multiple
60 instances of this deamon. The pidbase is is the part of
61 the PID file that does not include the configuration
62 file name.
63 pidfile ("$pidbase.$configfile.pid") The location of the process
65 id file.
66 foreground (0) Do not detach/daemon and run in the foreground
68 instead.
69 debug (0) Turn on debugging.
71 no_srand (0) Normall srand() is called. If no_srand is set then
73 srand() won't be called.
74 options () Additional arguments for Getopt::Long::GetOptions
76 which is used to parse @ARGV. Alternatively: define
77 "&gd_more_opt()".
78 minimum_args (1) Minimum number of @ARGV arguments after flags have
80 been processed.
81 maximum_args (1) Maximum number of @ARGV arguments after flags have
83 been processed.
84 version ($pkg::VERSION) The version number of the daemon.
86 logpriority Used for "logger -p".
88
90 The package that subclasses Daemon::Generic must provide the following
91 callback methods.
92 gd_preconfig() "gd_preconfig()" is called to parse the configuration
94 file ("$self->{configfile}"). Preconfig is called on
95 all invocations of the daemon ("daemon reload", "daemon
96 check", "daemon stop", etc). It shouldn't start
97 anything but it can and should verify that the config
98 file is fine.
99 The return value should be a hash. With one exception,
101 the return value is only used by "gd_postconfig()". The
102 exception is that "gd_preconfig()" may return a revised
103 PID file location (key "pidfile").
104 gd_run() This is where you put your main program.
106
108 The package that subclasses Daemon::Generic does not have to override
109 these methods but it may want to.
110 gd_postconfig(%config)
112 Postconfig() is called only when the daeamon is actually
113 starting up. (Or on reconfigs). It is passed the
114 return value from "gd_preconfig".
115 gd_setup_signals()
117 Set things up so that SIGHUP calls gd_reconfig_event()
118 and SIGINT calls gd_quit_event(). It will call these at
119 any time so if you want to delay signal delivery or
120 something you should override this method.
121 gd_getopt() This is invoked to parse the command line. Useful
123 things to modify are:
124 $self->{configfile} The location of the configuration
126 file to be parsed by
127 "gd_preconfig()".
128 $self->{foreground} Run in the foreground (don't
130 daemonize).
131 $self->{debug} Use it yourself.
133 The supplied "gd_getopt()" method uses Getopt::Long.
135 gd_parse_argv()
137 Parse any additional command line arguments beyond what
138 "gd_getopt()" handled.
139 $ARGV[0] needs to be left alone if it is one of the
141 following standard items:
142 start Start up a new daemon.
144 stop Stop the running daemon.
146 restart Stop the running daemon, start a new one.
148 reload Send a signal to the running daemon, asking it
150 to reconfigure itself.
151 check Just check the configuration file.
153 help Print the help screen (probably usage()).
155 version Display the daemon's version.
157 There is no default "gd_parse_argv()".
159 gd_check($pidfile, $pid)
161 Normal behavior: return. Define additional checks to
162 run when the "check" command is given. A $pid will only
163 be supplied if there is a daemon running.
164 gd_version() Normal behavior: display a version message and exit.
166 gd_help() Normal behavior: call "gd_usage()".
168 gd_commands_more()
170 Used by "gd_usage()": provide information on additional
171 commands beyond "start", "stop", "reload", etc. Return
172 is an array of key value pairs.
173 sub gd_commands_more
175 {
176 return (
177 savestate => 'Tell xyz server to save its state',
178 reset => 'Tell xyz servr to reset',
179 );
180 }
181 gd_flags_more Like "gd_commands_more()" but defines additional command
183 line flags. There should also be a "gd_more_opt()" or
184 an "options" argument to "new()".
185 gd_positional_more
187 Like "gd_commands_more()" but defines positional
188 arguments.
189 gd_usage() Display a usage message. The return value from
191 "gd_usage()" is the exit code for the program.
192 gd_more_opt() () Additional arguments for Getopt::Long::GetOptions
194 which is used to parse @ARGV. Alternatively: pass
195 "options" to "new()".
196 gd_pidfile() Figure out the PID file should be.
198 gd_error() Print out an error (call die?)
200 gd_other_cmd() Called $ARGV[0] isn't one of the commands that
202 Daemon::Generic knows by default. Default behavior:
203 call "gd_usage()" and exit(1).
204 gd_daemonize() Normal behavior: "fork()", "fork()", detach from tty.
206 gd_redirect_output()
208 Normal behavior: redirect "STDOUT" and "STDERR" to
209 "logger -t $progname[$$]". Used by "gd_daemonize()".
210 gd_logname() Normal behavior: $progname[$$]. Used by
212 "gd_redirect_output()".
213 gd_reconfig_event()
215 Normal behavior: call "gd_postconfig(gd_preconfig))".
216 Only referenced by "gd_setup_signals()".
217 gd_quit_event()
219 Normal behavior: exit. Only referenced by
220 "gd_setup_signals()".
221 gd_kill($pid) Used by the "stop" and "restart" commands to get rid of
223 the old daemon. Normal behavior: send a SIGINT. Check
224 to see if process $pid has died. If it has not, keep
225 checking and if it's still alive. After
226 $Daemon::Generic::force_quit_delay seconds, send a
227 SIGTERM. Keep checking. After another
228 $Daemon::Generic::force_quit_delay seconds, send a
229 SIGKILL (-9). Keep checking. After
230 "$Daemon::Generic::force_quit_delay * 4" seconds or 60
231 seconds (whichever is smaller), give up and exit(1).
232 gd_install Installs the daemon so that it runs automatically at
234 next reboot. Currently done with a symlink to $0 and
235 "/usr/sbin/update-rc.d". Please send patches for other
236 methods!
237 gd_can_install Returns a function to do an "gd_install" if installation
239 is possible. Returns 0 otherwise.
240 gd_install_pre($method)
242 Normal behavior: return. Called just before doing an
243 installation. The method indicates the installation
244 method (currently always "update-rc.d".)
245 gd_install_post($method)
247 Normal behavior: return. Called just after doing an
248 installation.
249 gd_uninstall Will remove the daemon from the automatic startup
251 regime.
252 gd_can_uninstall
254 Returns a function to do the work for "gd_uninstall" if
255 it's possible. 0 otherwise.
256 gd_uninstall_pre($method)
258 Normal behavior: return. Called just before doing an
259 un-installation. The method indicates the installation
260 method (currently always "update-rc.d".)
261 gd_install_post($method)
263 Normal behavior: return. Called just after doing an un-
264 installation.
265
267 Since you need to subclass Daemon::Generic, you need to know what the
268 internal data structures for Daemon::Generic are. With two exceptions,
269 all of the member data items begin with the prefix "gd_".
270 configfile The location of the configuration file. (Not used by
272 Daemon::Generic).
273 debug Display debugging? (Not used by Daemon::Generic)
275 gd_args The original %args passed to "new".
277 gd_progname The process name. (defaults to $0)
279 gd_pidfile The location of the process ID file.
281 gd_logpriority Used for "logger -p".
283 gd_foreground Are we running in the foreground?
285
287 my $sleeptime = 1;
288 newdaemon(
290 progname => 'ticktockd',
291 pidfile => '/var/run/ticktockd.pid',
292 configfile => '/etc/ticktockd.conf',
293 );
294 sub gd_preconfig
296 {
297 my ($self) = @_;
298 open(CONFIG, "<$self->{configfile}") or die;
299 while(<CONFIG>) {
300 $sleeptime = $1 if /^sleeptime\s+(\d+)/;
301 }
302 close(CONFIG);
303 return ();
304 }
305 sub gd_run
307 {
308 while(1) {
309 sleep($sleeptime);
310 print scalar(localtime(time))."\n";
311 }
312 }
313
315 With a while(1) and delayed signal delivery: Daemon::Generic::While1.
316 With Event: Daemon::Generic::Event.
318 Modules that use Daemon::Generic: SyslogScan::Daemon IO::Event
320 (rinetd.pl)
321 Other modules that do similar things: Net::Daemon, Net::Server,
323 Net::Server::Daemonize, NetServer::Generic, Proc::Application::Daemon,
324 Proc::Daemon, Proc::Forking.
325
327 Copyright(C) 2006 David Muir Sharnoff <perl@dave.sharnoff.org>, This
328 module may be used and distributed on the same terms as Perl itself.
329
331 Daemon::Generic is packaged for Fedora by Emmanuel Seyman
332 <emmanuel.seyman@club-internet.fr>.
333perl v5.12.1 2010-07-14 Daemon::Generic(3)