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 (parenthesis).
49 progname ($0) The name of this program. This will be used for
51 logging and for naming the PID file.
52 configfile ("/etc/$progname.conf") The location of the
54 configuration file for this daemon.
55 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 pidfile ("$pidbase.$configfile.pid") The location of the process
63 id file.
64 foreground (0) Do not detach/daemon and run in the foreground
66 instead.
67 debug (0) Turn on debugging.
69 no_srand (0) Normall srand() is called. If no_srand is set then
71 srand() won't be called.
72 options () Additional arguments for Getopt::Long::GetOptions
74 which is used to parse @ARGV. Alternatively: define
75 &gd_more_opt().
76 minimum_args (1) Minimum number of @ARGV arguments after flags have
78 been processed.
79 maximum_args (1) Maximum number of @ARGV arguments after flags have
81 been processed.
82 version ($pkg::VERSION) The version number of the daemon.
84 logpriority Used for "logger -p".
86
88 The package that subclasses Daemon::Generic must provide the following
89 callback methods.
90 gd_run() This is where you put your main program.
92 It is okay to change userid/group as the first action of
94 gd_run().
95
97 The package that subclasses Daemon::Generic does not have to override
98 these methods but it may want to.
99 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 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 Most uses of Daemon::Generic should define
113 "gd_preconfig".
114 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 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 gd_getopt() This is invoked to parse the command line. Useful
127 things to modify are:
128 $self->{configfile} The location of the configuration
130 file to be parsed by gd_preconfig().
131 $self->{foreground} Run in the foreground (don't
133 daemonize).
134 $self->{debug} Use it yourself.
136 The supplied gd_getopt() method uses Getopt::Long.
138 gd_parse_argv()
140 Parse any additional command line arguments beyond what
141 gd_getopt() handled.
142 $ARGV[0] needs to be left alone if it is one of the
144 following standard items:
145 start Start up a new daemon.
147 stop Stop the running daemon.
149 restart Stop the running daemon, start a new one.
151 reload Send a signal to the running daemon, asking it
153 to reconfigure itself.
154 check Just check the configuration file.
156 help Print the help screen (probably usage()).
158 version Display the daemon's version.
160 There is no default gd_parse_argv().
162 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 gd_version() Normal behavior: display a version message and exit.
169 gd_help() Normal behavior: call gd_usage().
171 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 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 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 gd_positional_more
190 Like gd_commands_more() but defines positional
191 arguments.
192 gd_usage() Display a usage message. The return value from
194 gd_usage() is the exit code for the program.
195 gd_more_opt() () Additional arguments for Getopt::Long::GetOptions
197 which is used to parse @ARGV. Alternatively: pass
198 "options" to new().
199 gd_pidfile() Figure out the PID file should be.
201 gd_error() Print out an error (call die?)
203 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 gd_daemonize() Normal behavior: fork(), fork(), detach from tty.
209 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 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 gd_logname() Normal behavior: $progname[$$]. Used by
222 gd_redirect_output().
223 gd_reconfig_event()
225 Normal behavior: call "gd_postconfig(gd_preconfig))".
226 Only referenced by gd_setup_signals().
227 gd_quit_event()
229 Normal behavior: exit. Only referenced by
230 gd_setup_signals().
231 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 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 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 gd_can_install Returns a function to do an "gd_install" if installation
254 is possible. Returns 0 otherwise.
255 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 gd_install_post($method)
262 Normal behavior: return. Called just after doing an
263 installation.
264 gd_uninstall Will remove the daemon from the automatic startup
266 regime.
267 gd_can_uninstall
269 Returns a function to do the work for "gd_uninstall" if
270 it's possible. 0 otherwise.
271 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 gd_install_post($method)
278 Normal behavior: return. Called just after doing an un-
279 installation.
280
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 configfile The location of the configuration file. (Not used by
287 Daemon::Generic).
288 debug Display debugging? (Not used by Daemon::Generic)
290 gd_args The original %args passed to "new".
292 gd_progname The process name. (defaults to $0)
294 gd_pidfile The location of the process ID file.
296 gd_logpriority Used for "logger -p".
298 gd_foreground Are we running in the foreground?
300
302 my $sleeptime = 1;
303 newdaemon(
305 progname => 'ticktockd',
306 pidfile => '/var/run/ticktockd.pid',
307 configfile => '/etc/ticktockd.conf',
308 );
309 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 sub gd_run
322 {
323 while(1) {
324 sleep($sleeptime);
325 print scalar(localtime(time))."\n";
326 }
327 }
328
330 With a while(1) and delayed signal delivery: Daemon::Generic::While1.
331 With Event: Daemon::Generic::Event.
333 With AnyEvent: Daemon::Generic::AnyEvent.
335 Modules that use Daemon::Generic: SyslogScan::Daemon; IO::Event
337 (rinetd.pl)
338 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
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
349 Daemon::Generic is packaged for Fedora by Emmanuel Seyman
350 <emmanuel.seyman@club-internet.fr>.
351perl v5.38.0 2023-07-20 Daemon::Generic(3)