1Daemon::Control(3)    User Contributed Perl Documentation   Daemon::Control(3)
2
3
4

NAME

6       Daemon::Control - Create init scripts in Perl
7

DESCRIPTION

9       Daemon::Control provides a library for creating init scripts in perl.
10       Your perl script just needs to set the accessors for what and how you
11       want something to run and the library takes care of the rest.
12
13       You can launch programs through the shell ("/usr/sbin/my_program") or
14       launch Perl code itself into a daemon mode.  Single and double fork
15       methods are supported, and in double-fork mode all the things you would
16       expect such as reopening STDOUT/STDERR, switching UID/GID etc are
17       supported.
18

SYNOPSIS

20       Write a program that describes the daemon:
21
22           #!/usr/bin/perl
23           use warnings;
24           use strict;
25           use Daemon::Control;
26
27           exit Daemon::Control->new(
28               name        => "My Daemon",
29               lsb_start   => '$syslog $remote_fs',
30               lsb_stop    => '$syslog',
31               lsb_sdesc   => 'My Daemon Short',
32               lsb_desc    => 'My Daemon controls the My Daemon daemon.',
33               path        => '/home/symkat/etc/init.d/program',
34
35               program     => '/home/symkat/bin/program',
36               program_args => [ '-a', 'orange', '--verbose' ],
37
38               pid_file    => '/tmp/mydaemon.pid',
39               stderr_file => '/tmp/mydaemon.out',
40               stdout_file => '/tmp/mydaemon.out',
41
42               fork        => 2,
43
44           )->run;
45
46       By default "run" will use @ARGV for the action, and exit with an LSB
47       compatible exit code.  For finer control, you can use "run_command",
48       which will return the exit code, and accepts the action as an argument.
49       This enables more programatic control, as well as running multiple
50       instances of Daemon::Control from one script.
51
52           my $daemon = Daemon::Control->new(
53               ...
54           );
55           my $exit = $daemon->run_command(“start”);
56
57       You can then call the program:
58
59           /home/symkat/etc/init.d/program start
60
61       You can also make an LSB compatible init script:
62
63           /home/symkat/etc/init.d/program get_init_file > /etc/init.d/program
64

CONSTRUCTOR

66       The constructor takes the following arguments as a list or a hash ref.
67
68   name
69       The name of the program the daemon is controlling.  This will be used
70       in status messages "name [Started]" and the name for the LSB init
71       script that is generated.
72
73   program
74       This can be a coderef or the path to a shell program that is to be run.
75
76           $daemon->program( sub { ... } );
77
78           $daemon->program( "/usr/sbin/http" );
79
80   program_args
81       This is an array ref of the arguments for the program.  In the context
82       of a coderef being executed this will be given to the coderef as @_,
83       the Daemon::Control instance that called the coderef will be passed as
84       the first arguments.  Your arguments start at $_[1].
85
86       In the context of a shell program, it will be given as arguments to be
87       executed.
88
89           $daemon->program_args( [ 'foo', 'bar' ] );
90
91           $daemon->program_args( [ '--switch', 'argument' ] );
92
93   user
94       When set, the username supplied to this accessor will be used to set
95       the UID attribute.  When this is used, "uid" will be changed from its
96       initial settings if you set it (which you shouldn't, since you're using
97       usernames instead of UIDs).  See "uid" for setting numerical user ids.
98
99           $daemon->user('www-data');
100
101   group
102       When set, the groupname supplied to this accessor will be used to set
103       the GID attribute.  When this is used, "gid" will be changed from its
104       initial settings if you set it (which you shouldn't, since you're using
105       groupnames instead of GIDs).  See "gid" for setting numerical group
106       ids.
107
108           $daemon->group('www-data');
109
110   uid
111       If provided, the UID that the program will drop to when forked.  This
112       is ONLY supported in double-fork mode and will only work if you are
113       running as root. Accepts numeric UID.  For usernames please see "user".
114
115           $daemon->uid( 1001 );
116
117   gid
118       If provided, the GID that the program will drop to when forked.  This
119       is ONLY supported in double-fork mode and will only work if you are
120       running as root. Accepts numeric GID, for groupnames please see
121       "group".
122
123           $daemon->gid( 1001 );
124
125   umask
126       If provided, the umask of the daemon will be set to the umask provided,
127       note that the umask must be in oct.  By default the umask will not be
128       changed.
129
130           $daemon->umask( 022 );
131
132       Or:
133
134           $daemon->umask( oct("022") );
135
136   directory
137       If provided, chdir to this directory before execution.
138
139   path
140       The path of the script you are using Daemon::Control in.  This will be
141       used in the LSB file generation to point it to the location of the
142       script.  If this is not provided, the absolute path of $0 will be used.
143
144   init_config
145       The name of the init config file to load.  When provided your init
146       script will source this file to include the environment variables.
147       This is useful for setting a "PERL5LIB" and such things.
148
149           $daemon->init_config( "/etc/default/my_program" );
150
151       If you are using perlbrew, you probably want to set your init_config to
152       "$ENV{PERLBREW_ROOT} . '/etc/bashrc'".
153
154   init_code
155       When given, whatever text is in this field will be dumped directly into
156       the generated init file.
157
158           $daemon->init_code( "Arbitrary code goes here." )
159
160   help
161       Any text in this accessor will be printed when the script is called
162       with the argument "--help" or <help>.
163
164           $daemon->help( "Read The Friendly Source." );
165
166   redirect_before_fork
167       By default this is set to true.  STDOUT will be redirected to
168       "stdout_file", and STDERR will be redirected to "stderr_file".  Setting
169       this to 0 will disable redirecting before a double fork.  This is
170       useful when you are using a code reference and would like to leave the
171       filehandles alone until you're in control.
172
173       Call "->redirect_filehandles" on the Daemon::Control instance your
174       coderef is passed to redirect the filehandles.
175
176   stdout_file
177       If provided stdout will be redirected to the given file.  This is only
178       supported in double fork mode.
179
180           $daemon->stdout_file( "/tmp/mydaemon.stdout" );
181
182       Alternatively, you can specify an arrayref of arguments to "open()":
183
184           $daemon->stdout_file( [ '>',  '/tmp/overwrite-every-run'  ] );
185           $daemon->stdout_file( [ '|-', 'my_pipe_program', '-a foo' ] );
186
187   stderr_file
188       If provided stderr will be redirected to the given file.  This is only
189       supported in double fork mode.
190
191           $daemon->stderr_file( "/tmp/mydaemon.stderr" );
192
193       Alternatively, you can specify an arrayref of arguments to "open()":
194
195           $daemon->stderr_file( [ '>',  '/tmp/overwrite-every-run'  ] );
196           $daemon->stderr_file( [ '|-', 'my_pipe_program', '-a foo' ] );
197
198   pid_file
199       The location of the PID file to use.  Warning: if using single-fork
200       mode, it is recommended to set this to the file which the daemon
201       launching in single-fork mode will put its PID.  Failure to follow this
202       will most likely result in status, stop, and restart not working.
203
204           $daemon->pid_file( "/var/run/mydaemon/mydaemon.pid" );
205
206   resource_dir
207       This directory will be created, and chowned to the user/group provided
208       in "user", and "group".
209
210           $daemon->resource_dir( "/var/run/mydaemon" );
211
212   prereq_no_process -- EXPERIMENTAL
213       This option is EXPERIMENTAL and defaults to OFF.
214
215       If this is set, then the "ps" list will be checked at startup for any
216       processes that look like the daemon to be started.  By default the
217       pattern used is "/\b<program name>\b/", but you can pass an override
218       regexp in this field instead (to use the default pattern, just pass
219       "prereq_no_process => 1").  If matching processes are found, those pids
220       are output, and the daemon will not start.
221
222       This may produce some false positives on your system, depending on what
223       else is running on your system, but it may still be of some use, e.g.
224       if you seem to have daemons left running where the associated pid file
225       is getting deleted somehow.
226
227   fork
228       The mode to use for fork.  By default a double-fork will be used.
229
230       In double-fork, uid, gid, std*_file, and a number of other things are
231       supported.  A traditional double-fork is used and setsid is called.
232
233       In single-fork none of the above are called, and it is the
234       responsibility of whatever you're forking to reopen files, associate
235       with the init process and do all that fun stuff.  This mode is
236       recommended when the program you want to control has its own
237       daemonizing code.  It is important to note that the PID file should be
238       set to whatever PID file is used by the daemon.
239
240       In no-fork mode, fork(0), the program is run in the foreground.  By
241       default quiet is still turned off, so status updates will be shown on
242       the screen such as that the daemon started.  A shortcut to turn status
243       off and go into foreground mode is "foreground" being set to 1, or
244       "DC_FOREGROUND" being set as an environment variable.  Additionally,
245       calling "foreground" instead of "start" will override the forking mode
246       at run-time.
247
248           $daemon->fork( 0 );
249
250           $daemon->fork( 1 );
251
252           $daemon->fork( 2 ); # Default
253
254   scan_name
255       This provides an extra check to see if the program is running.
256       Normally we only check that the PID listed in the PID file is running.
257       When given a regular expression, we will also match the name of the
258       program as shown in ps.
259
260           $daemon->scan_name( qr|mydaemon| );
261
262   kill_timeout
263       This provides an amount of time in seconds between kill signals being
264       sent to the daemon.  This value should be increased if your daemon has
265       a longer shutdown period.  By default 1 second is used.
266
267           $daemon->kill_timeout( 7 );
268
269   lsb_start
270       The value of this string is used for the 'Required-Start' value of the
271       generated LSB init script.  See <http://wiki.debian.org/LSBInitScripts>
272       for more information.
273
274           $daemon->lsb_start( '$remote_fs $syslog' );
275
276   lsb_stop
277       The value of this string is used for the 'Required-Stop' value of the
278       generated LSB init script.  See <http://wiki.debian.org/LSBInitScripts>
279       for more information.
280
281           $daemon->lsb_stop( '$remote_fs $syslog' );
282
283   lsb_sdesc
284       The value of this string is used for the 'Short-Description' value of
285       the generated LSB init script.  See
286       <http://wiki.debian.org/LSBInitScripts> for more information.
287
288           $daemon->lsb_sdesc( 'My program...' );
289
290   lsb_desc
291       The value of this string is used for the 'Description' value of the
292       generated LSB init script.  See <http://wiki.debian.org/LSBInitScripts>
293       for more information.
294
295           $daemon->lsb_desc( 'My program controls a thing that does a thing.' );
296
297   quiet
298       If this boolean flag is set to a true value all output from the init
299       script (NOT your daemon) to STDOUT will be suppressed.
300
301           $daemon->quiet( 1 );
302
303   reload_signal
304       The signal to send to the daemon when reloading it.  Default signal is
305       "HUP".
306
307   stop_signals
308       An array ref of signals that should be tried (in order) when stopping
309       the daemon.  Default signals are "TERM", "TERM", "INT" and "KILL" (yes,
310       "TERM" is tried twice).
311

PLUGINS

313       Daemon Control supports a simple plugin system using Role::Tiny.
314
315   with_plugins
316       With plugins adds the plugins to Daemon::Control.
317
318           Daemon::Control->with_plugins( qw( MyFirstPlugin +MySecondPlugin) )->new(
319           ...
320           );
321
322       Note:
323
324       MyFirstPlugin will load Daemon::Control::Plugin::MyFirstPlugin
325
326       +MySecondPlugin will load MySecondPlugin
327
328   Writing A Plugin
329       Your plugin should use the name Daemon::Control::Plugin::YourModuleName
330       and YourModuleName should reasonably match the effect your plugin has
331       on Daemon::Control.
332
333       You can replace Daemon::Control methods by writing your own and using
334       Role::Tiny within your class to allow it to be composed into
335       Daemon::Control.
336
337       The default Daemon::Control ships with no dependancies and supports
338       Perl 5.8.1+, to use the plugin system your module MUST declare
339       dependency on Role::Tiny and if you wish to use the "around", "before"
340       and "after" your module MUST declare dependance on
341       Class::Method::Modifiers in your package.
342

METHODS

344   run_command
345       This function will process an action on the Daemon::Control instance.
346       Valid arguments are those which a "do_" method exists for, such as
347       start, stop, restart.  Returns the LSB exit code for the action
348       processed.
349
350   run
351       This will make your program act as an init file, accepting input from
352       the command line.  Run will exit with 0 for success and uses LSB exit
353       codes.  As such no code should be used after ->run is called.  Any code
354       in your file should be before this.  This is a shortcut for
355
356           exit Daemon::Control->new(...)->run_command( @ARGV );
357
358   do_start
359       Is called when start is given as an argument.  Starts the forking and
360       exits. Called by:
361
362           /usr/bin/my_program_launcher.pl start
363
364   do_foreground
365       Is called when foreground is given as an argument.  Starts the program
366       or code reference and stays in the foreground -- no forking is done,
367       regardless of the compile-time arguments.  Additionally, turns "quiet"
368       on to avoid showing Daemon::Control output.
369
370           /usr/bin/my_program_launcher.pl foreground
371
372   do_stop
373       Is called when stop is given as an argument.  Stops the running program
374       if it can. Called by:
375
376           /usr/bin/my_program_launcher.pl stop
377
378   do_restart
379       Is called when restart is given as an argument.  Calls do_stop and
380       do_start.  Called by:
381
382           /usr/bin/my_program_launcher.pl restart
383
384   do_reload
385       Is called when reload is given as an argument.  Sends the signal
386       "reload_signal" to the daemon.
387
388           /usr/bin/my_program_launcher.pl reload
389
390   do_status
391       Is called when status is given as an argument.  Displays the status of
392       the program, basic on the PID file. Called by:
393
394           /usr/bin/my_program_launcher.pl status
395
396   do_get_init_file
397       Is called when get_init_file is given as an argument.  Dumps an LSB
398       compatible init file, for use in /etc/init.d/. Called by:
399
400           /usr/bin/my_program_launcher.pl get_init_file
401
402   pretty_print
403       This is used to display status to the user.  It accepts a message and a
404       color.  It will default to green text, if no color is explicitly given.
405       Only supports red and green.
406
407           $daemon->pretty_print( "My Status", "red" );
408
409   write_pid
410       This will write the PID to the file in pid_file.
411
412   read_pid
413       This will read the PID from the file in pid_file and set it in pid.
414
415   pid
416       An accessor for the PID.  Set by read_pid, or when the program is
417       started.
418
419   dump_init_script
420       A function to dump the LSB compatible init script.  Used by
421       do_get_init_file.
422

AUTHOR

424       Kaitlyn Parkhurst (SymKat) <symkat@symkat.com> ( Blog:
425       <http://symkat.com/> )
426
427   CONTRIBUTORS
428       •   Matt S. Trout (mst) <mst@shadowcat.co.uk>
429
430       •   Mike Doherty (doherty) <doherty@cpan.org>
431
432       •   Karen Etheridge (ether) <ether@cpan.org>
433
434       •   Ævar Arnfjörð Bjarmason (avar) <avar@cpan.org>
435
436       •   Kieren Diment <zarquon@cpan.org<gt>
437
438       •   Mark Curtis <mark.curtis@affinitylive.com<gt>
439
440       •   Zoffix Znet <zoffix@cpan.org<gt>
441
442   SPONSORS
443       Parts of this code were paid for by
444
445       (mt) Media Temple <http://www.mediatemple.net>
446
448       Copyright (c) 2012 the Daemon::Control "AUTHOR", "CONTRIBUTORS", and
449       "SPONSORS" as listed above.
450

LICENSE

452       This library is free software and may be distributed under the same
453       terms as perl itself.
454
455   AVAILABILITY
456       The most current version of Daemon::Control can be found at
457       <https://github.com/symkat/Daemon-Control>
458
459
460
461perl v5.34.0                      2021-07-22                Daemon::Control(3)
Impressum