File: README

package info (click to toggle)
libdaemon-generic-perl 0.85-1
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye, buster, sid
  • size: 132 kB
  • ctags: 60
  • sloc: perl: 865; makefile: 2
file content (345 lines) | stat: -rw-r--r-- 13,375 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
NAME
     Daemon::Generic - framework to provide start/stop/reload for a daemon

SYNOPSIS
     use Daemon::Generic;

     sub gd_run { ... stuff }

     newdaemon();

DESCRIPTION
    Daemon::Generic provides a framework for starting, stopping,
    reconfiguring daemon-like programs. The framework provides for standard
    commands that work for as init.d files and as apachectl-like commands.

    Programs that use Daemon::Generic subclass Daemon::Generic to override
    its behavior. Almost everything that Genric::Daemon does can be
    overridden as needed.

EXAMPLE USAGE OUTPUT
    Unless overridden, the usage output for your program will look something
    like this:

     Usage: $progname [ -c file ] [ -f ] { start | stop | reload | restart | help | version | check }
      -c            Specify configuration file (defaults to $configfile)
      -f            Run in the foreground (don't detach)
      start         Starts a new $progname if there isn't one running already
      stop          Stops a running $progname
      reload        Causes a running $progname to reload it's config file.  Starts
                    a new one if none is running.
      restart       Stops a running $progname if one is running.  Starts a new one.
      check         Check the configuration file and report the daemon state
      help          Display this usage info
      version       Display the version of $progname

CONSTRUCTION
    To hand control over to "Daemon::Generic", call "newdaemon()". Control
    will be handed back through method calls to functions you define.

    Your @ISA will be modified to include "Daemon::Generic" if if it isn't
    already there.

    These are the arguments to "newdaemon()". Defaults are in (parenthesis).

    progname       ($0) The name of this program. This will be used for
                   logging and for naming the PID file.

    configfile     ("/etc/$progname.conf") The location of the configuration
                   file for this daemon.

    pidbase        (/var/run/$progname) We include the configuration file
                   name as part of the pid file in case there are multiple
                   instances of this daemon. The pidbase is the part of the
                   PID file that does not include the configuration file
                   name.

    pidfile        ("$pidbase.$configfile.pid") The location of the process
                   id file.

    foreground     (0) Do not detach/daemon and run in the foreground
                   instead.

    debug          (0) Turn on debugging.

    no_srand       (0) Normall srand() is called. If no_srand is set then
                   srand() won't be called.

    options        () Additional arguments for Getopt::Long::GetOptions
                   which is used to parse @ARGV. Alternatively: define
                   "&gd_more_opt()".

    minimum_args   (1) Minimum number of @ARGV arguments after flags have
                   been processed.

    maximum_args   (1) Maximum number of @ARGV arguments after flags have
                   been processed.

    version        ($pkg::VERSION) The version number of the daemon.

    logpriority    Used for "logger -p".

MUST-OVERRIDE CALLBACK METHODS
    The package that subclasses Daemon::Generic must provide the following
    callback methods.

    gd_run()       This is where you put your main program.

                   It is okay to change userid/group as the first action of
                   gd_run().

MAY-OVERRIDE CALLBACK METHODS
    The package that subclasses Daemon::Generic does not have to override
    these methods but it may want to.

    gd_preconfig() "gd_preconfig()" is called to parse the configuration
                   file ("$self->{configfile}"). Preconfig is called on all
                   invocations of the daemon ("daemon reload", "daemon
                   check", "daemon stop", etc). It shouldn't start anything
                   but it can and should verify that the config file is
                   fine.

                   The return value should be a hash. With one exception,
                   the return value is only used by "gd_postconfig()". The
                   exception is that "gd_preconfig()" may return a revised
                   PID file location (key "pidfile").

                   Most uses of Daemon::Generic should define
                   "gd_preconfig".

    gd_postconfig(%config)
                   Postconfig() is called only when the daemon is actually
                   starting up. (Or on reconfigs). It is passed the return
                   value from "gd_preconfig".

    gd_setup_signals()
                   Set things up so that SIGHUP calls gd_reconfig_event()
                   and SIGINT calls gd_quit_event(). It will call these at
                   any time so if you want to delay signal delivery or
                   something you should override this method.

    gd_getopt()    This is invoked to parse the command line. Useful things
                   to modify are:

                   $self->{configfile} The location of the configuration
                                       file to be parsed by
                                       "gd_preconfig()".

                   $self->{foreground} Run in the foreground (don't
                                       daemonize).

                   $self->{debug}      Use it yourself.

                   The supplied "gd_getopt()" method uses Getopt::Long.

    gd_parse_argv()
                   Parse any additional command line arguments beyond what
                   "gd_getopt()" handled.

                   $ARGV[0] needs to be left alone if it is one of the
                   following standard items:

                   start     Start up a new daemon.

                   stop      Stop the running daemon.

                   restart   Stop the running daemon, start a new one.

                   reload    Send a signal to the running daemon, asking it
                             to reconfigure itself.

                   check     Just check the configuration file.

                   help      Print the help screen (probably usage()).

                   version   Display the daemon's version.

                   There is no default "gd_parse_argv()".

    gd_check($pidfile, $pid)
                   Normal behavior: return. Define additional checks to run
                   when the "check" command is given. A $pid will only be
                   supplied if there is a daemon running.

    gd_version()   Normal behavior: display a version message and exit.

    gd_help()      Normal behavior: call "gd_usage()".

    gd_commands_more()
                   Used by "gd_usage()": provide information on additional
                   commands beyond "start", "stop", "reload", etc. Return is
                   an array of key value pairs.

                    sub gd_commands_more 
                    {
                           return (
                                   savestate => 'Tell xyz server to save its state',
                                   reset     => 'Tell xyz servr to reset',
                           );
                    }

    gd_flags_more  Like "gd_commands_more()" but defines additional command
                   line flags. There should also be a "gd_more_opt()" or an
                   "options" argument to "new()".

    gd_positional_more
                   Like "gd_commands_more()" but defines positional
                   arguments.

    gd_usage()     Display a usage message. The return value from
                   "gd_usage()" is the exit code for the program.

    gd_more_opt()  () Additional arguments for Getopt::Long::GetOptions
                   which is used to parse @ARGV. Alternatively: pass
                   "options" to "new()".

    gd_pidfile()   Figure out the PID file should be.

    gd_error()     Print out an error (call die?)

    gd_other_cmd() Called $ARGV[0] isn't one of the commands that
                   Daemon::Generic knows by default. Default behavior: call
                   "gd_usage()" and exit(1).

    gd_daemonize() Normal behavior: "fork()", "fork()", detach from tty.

    gd_redirect_output()
                   This is a mis-named method. Sorry. This directs
                   "STDOUT"/"STDERR"/"STDIN" to "/dev/null" as part of
                   daemonizing. Used by "gd_daemonize()".

    gd_reopen_output()
                   After daemonizing, output file descriptors are be
                   re-established. Normal behavior: redirect "STDOUT" and
                   "STDERR" to "logger -t $progname[$$]". Used by
                   "gd_daemonize()".

    gd_logname()   Normal behavior: $progname[$$]. Used by
                   "gd_redirect_output()".

    gd_reconfig_event()
                   Normal behavior: call "gd_postconfig(gd_preconfig))".
                   Only referenced by "gd_setup_signals()".

    gd_quit_event()
                   Normal behavior: exit. Only referenced by
                   "gd_setup_signals()".

    gd_kill_groups()
                   Return true if gd_kill should kill process groups ($pid)
                   instead of just the one daemon ($pid). Default is false.

    gd_kill($pid)  Used by the "stop" and "restart" commands to get rid of
                   the old daemon. Normal behavior: send a SIGINT. Check to
                   see if process $pid has died. If it has not, keep
                   checking and if it's still alive. After
                   $Daemon::Generic::force_quit_delay seconds, send a
                   SIGTERM. Keep checking. After another
                   $Daemon::Generic::force_quit_delay seconds, send a
                   SIGKILL (-9). Keep checking. After
                   "$Daemon::Generic::force_quit_delay * 4" seconds or 60
                   seconds (whichever is smaller), give up and exit(1).

    gd_install     Installs the daemon so that it runs automatically at next
                   reboot. Currently done with a symlink to $0 and
                   "/usr/sbin/update-rc.d". Please send patches for other
                   methods!

    gd_can_install Returns a function to do an "gd_install" if installation
                   is possible. Returns 0 otherwise.

    gd_install_pre($method)
                   Normal behavior: return. Called just before doing an
                   installation. The method indicates the installation
                   method (currently always "update-rc.d".)

    gd_install_post($method)
                   Normal behavior: return. Called just after doing an
                   installation.

    gd_uninstall   Will remove the daemon from the automatic startup regime.

    gd_can_uninstall
                   Returns a function to do the work for "gd_uninstall" if
                   it's possible. 0 otherwise.

    gd_uninstall_pre($method)
                   Normal behavior: return. Called just before doing an
                   un-installation. The method indicates the installation
                   method (currently always "update-rc.d".)

    gd_install_post($method)
                   Normal behavior: return. Called just after doing an
                   un-installation.

MEMBER DATA
    Since you need to subclass Daemon::Generic, you need to know what the
    internal data structures for Daemon::Generic are. With two exceptions,
    all of the member data items begin with the prefix "gd_".

    configfile     The location of the configuration file. (Not used by
                   Daemon::Generic).

    debug          Display debugging? (Not used by Daemon::Generic)

    gd_args        The original %args passed to "new".

    gd_progname    The process name. (defaults to $0)

    gd_pidfile     The location of the process ID file.

    gd_logpriority Used for "logger -p".

    gd_foreground  Are we running in the foreground?

EXAMPLE PROGRAM
     my $sleeptime = 1;

     newdaemon(
            progname        => 'ticktockd',
            pidfile         => '/var/run/ticktockd.pid',
            configfile      => '/etc/ticktockd.conf',
     );

     sub gd_preconfig
     {
            my ($self) = @_;
            open(CONFIG, "<$self->{configfile}") or die;
            while(<CONFIG>) {
                    $sleeptime = $1 if /^sleeptime\s+(\d+)/;
            }
            close(CONFIG);
            return ();
     }

     sub gd_run
     {
            while(1) {
                    sleep($sleeptime);
                    print scalar(localtime(time))."\n";
            }
     }

SEE ALSO
    With a while(1) and delayed signal delivery: Daemon::Generic::While1.

    With Event: Daemon::Generic::Event.

    With AnyEvent: Daemon::Generic::AnyEvent.

    Modules that use Daemon::Generic: SyslogScan::Daemon; IO::Event
    (rinetd.pl)

    Other modules that do similar things: Net::Daemon, Net::Server,
    Net::Server::Daemonize, NetServer::Generic, Proc::Application::Daemon,
    Proc::Daemon, Proc::Forking.

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

PACKAGERS
    Daemon::Generic is packaged for Fedora by Emmanuel Seyman
    <emmanuel.seyman@club-internet.fr>.