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