1Daemon::Control(3) User Contributed Perl Documentation Daemon::Control(3)
2
6 Daemon::Control - Create init scripts in Perl
7
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 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
20 Write a program that describes the daemon:
21 #!/usr/bin/perl
23 use warnings;
24 use strict;
25 use Daemon::Control;
26 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 program => '/home/symkat/bin/program',
36 program_args => [ '-a', 'orange', '--verbose' ],
37 pid_file => '/tmp/mydaemon.pid',
39 stderr_file => '/tmp/mydaemon.out',
40 stdout_file => '/tmp/mydaemon.out',
41 fork => 2,
43 )->run;
45 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 my $daemon = Daemon::Control->new(
53 ...
54 );
55 my $exit = $daemon->run_command(“start”);
56 You can then call the program:
58 /home/symkat/etc/init.d/program start
60 You can also make an LSB compatible init script:
62 /home/symkat/etc/init.d/program get_init_file > /etc/init.d/program
64
66 The constructor takes the following arguments as a list or a hash ref.
67 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 program
74 This can be a coderef or the path to a shell program that is to be run.
75 $daemon->program( sub { ... } );
77 $daemon->program( "/usr/sbin/http" );
79 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 In the context of a shell program, it will be given as arguments to be
87 executed.
88 $daemon->program_args( [ 'foo', 'bar' ] );
90 $daemon->program_args( [ '--switch', 'argument' ] );
92 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 $daemon->user('www-data');
100 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 $daemon->group('www-data');
109 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 $daemon->uid( 1001 );
116 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 $daemon->gid( 1001 );
124 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 $daemon->umask( 022 );
131 Or:
133 $daemon->umask( oct("022") );
135 directory
137 If provided, chdir to this directory before execution.
138 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 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 $daemon->init_config( "/etc/default/my_program" );
150 If you are using perlbrew, you probably want to set your init_config to
152 "$ENV{PERLBREW_ROOT} . '/etc/bashrc'".
153 init_code
155 When given, whatever text is in this field will be dumped directly into
156 the generated init file.
157 $daemon->init_code( "Arbitrary code goes here." )
159 help
161 Any text in this accessor will be printed when the script is called
162 with the argument "--help" or <help>.
163 $daemon->help( "Read The Friendly Source." );
165 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 Call "->redirect_filehandles" on the Daemon::Control instance your
174 coderef is passed to redirect the filehandles.
175 stdout_file
177 If provided stdout will be redirected to the given file. This is only
178 supported in double fork mode.
179 $daemon->stdout_file( "/tmp/mydaemon.stdout" );
181 Alternatively, you can specify an arrayref of arguments to "open()":
183 $daemon->stdout_file( [ '>', '/tmp/overwrite-every-run' ] );
185 $daemon->stdout_file( [ '|-', 'my_pipe_program', '-a foo' ] );
186 stderr_file
188 If provided stderr will be redirected to the given file. This is only
189 supported in double fork mode.
190 $daemon->stderr_file( "/tmp/mydaemon.stderr" );
192 Alternatively, you can specify an arrayref of arguments to "open()":
194 $daemon->stderr_file( [ '>', '/tmp/overwrite-every-run' ] );
196 $daemon->stderr_file( [ '|-', 'my_pipe_program', '-a foo' ] );
197 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 $daemon->pid_file( "/var/run/mydaemon/mydaemon.pid" );
205 resource_dir
207 This directory will be created, and chowned to the user/group provided
208 in "user", and "group".
209 $daemon->resource_dir( "/var/run/mydaemon" );
211 prereq_no_process -- EXPERIMENTAL
213 This option is EXPERIMENTAL and defaults to OFF.
214 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 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 fork
228 The mode to use for fork. By default a double-fork will be used.
229 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 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 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 $daemon->fork( 0 );
249 $daemon->fork( 1 );
251 $daemon->fork( 2 ); # Default
253 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 $daemon->scan_name( qr|mydaemon| );
261 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 $daemon->kill_timeout( 7 );
268 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 $daemon->lsb_start( '$remote_fs $syslog' );
275 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 $daemon->lsb_stop( '$remote_fs $syslog' );
282 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 $daemon->lsb_sdesc( 'My program...' );
289 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 $daemon->lsb_desc( 'My program controls a thing that does a thing.' );
296 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 $daemon->quiet( 1 );
302 reload_signal
304 The signal to send to the daemon when reloading it. Default signal is
305 "HUP".
306 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
313 Daemon Control supports a simple plugin system using Role::Tiny.
314 with_plugins
316 With plugins adds the plugins to Daemon::Control.
317 Daemon::Control->with_plugins( qw( MyFirstPlugin +MySecondPlugin) )->new(
319 ...
320 );
321 Note:
323 MyFirstPlugin will load Daemon::Control::Plugin::MyFirstPlugin
325 +MySecondPlugin will load MySecondPlugin
327 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 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 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
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 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 exit Daemon::Control->new(...)->run_command( @ARGV );
357 do_start
359 Is called when start is given as an argument. Starts the forking and
360 exits. Called by:
361 /usr/bin/my_program_launcher.pl start
363 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 /usr/bin/my_program_launcher.pl foreground
371 do_stop
373 Is called when stop is given as an argument. Stops the running program
374 if it can. Called by:
375 /usr/bin/my_program_launcher.pl stop
377 do_restart
379 Is called when restart is given as an argument. Calls do_stop and
380 do_start. Called by:
381 /usr/bin/my_program_launcher.pl restart
383 do_reload
385 Is called when reload is given as an argument. Sends the signal
386 "reload_signal" to the daemon.
387 /usr/bin/my_program_launcher.pl reload
389 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 /usr/bin/my_program_launcher.pl status
395 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 /usr/bin/my_program_launcher.pl get_init_file
401 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 $daemon->pretty_print( "My Status", "red" );
408 write_pid
410 This will write the PID to the file in pid_file.
411 read_pid
413 This will read the PID from the file in pid_file and set it in pid.
414 pid
416 An accessor for the PID. Set by read_pid, or when the program is
417 started.
418 dump_init_script
420 A function to dump the LSB compatible init script. Used by
421 do_get_init_file.
422
424 Kaitlyn Parkhurst (SymKat) <symkat@symkat.com> ( Blog:
425 <http://symkat.com/> )
426 CONTRIBUTORS
428 • Matt S. Trout (mst) <mst@shadowcat.co.uk>
429 • Mike Doherty (doherty) <doherty@cpan.org>
431 • Karen Etheridge (ether) <ether@cpan.org>
433 • Ævar Arnfjörð Bjarmason (avar) <avar@cpan.org>
435 • Kieren Diment <zarquon@cpan.org<gt>
437 • Mark Curtis <mark.curtis@affinitylive.com<gt>
439 • Zoffix Znet <zoffix@cpan.org<gt>
441 SPONSORS
443 Parts of this code were paid for by
444 (mt) Media Temple <http://www.mediatemple.net>
446
448 Copyright (c) 2012 the Daemon::Control "AUTHOR", "CONTRIBUTORS", and
449 "SPONSORS" as listed above.
450
452 This library is free software and may be distributed under the same
453 terms as perl itself.
454 AVAILABILITY
456 The most current version of Daemon::Control can be found at
457 <https://github.com/symkat/Daemon-Control>
458perl v5.34.0 2022-01-21 Daemon::Control(3)