.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Daemon::Control 3pm" .TH Daemon::Control 3pm "2019-02-23" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Daemon::Control \- Create init scripts in Perl .SH "DESCRIPTION" .IX Header "DESCRIPTION" Daemon::Control provides a library for creating init scripts in perl. Your perl script just needs to set the accessors for what and how you want something to run and the library takes care of the rest. .PP You can launch programs through the shell (\f(CW\*(C`/usr/sbin/my_program\*(C'\fR) or launch Perl code itself into a daemon mode. Single and double fork methods are supported, and in double-fork mode all the things you would expect such as reopening \s-1STDOUT/STDERR,\s0 switching \s-1UID/GID\s0 etc are supported. .SH "SYNOPSIS" .IX Header "SYNOPSIS" Write a program that describes the daemon: .PP .Vb 4 \& #!/usr/bin/perl \& use warnings; \& use strict; \& use Daemon::Control; \& \& exit Daemon::Control\->new( \& name => "My Daemon", \& lsb_start => \*(Aq$syslog $remote_fs\*(Aq, \& lsb_stop => \*(Aq$syslog\*(Aq, \& lsb_sdesc => \*(AqMy Daemon Short\*(Aq, \& lsb_desc => \*(AqMy Daemon controls the My Daemon daemon.\*(Aq, \& path => \*(Aq/home/symkat/etc/init.d/program\*(Aq, \& \& program => \*(Aq/home/symkat/bin/program\*(Aq, \& program_args => [ \*(Aq\-a\*(Aq, \*(Aqorange\*(Aq, \*(Aq\-\-verbose\*(Aq ], \& \& pid_file => \*(Aq/tmp/mydaemon.pid\*(Aq, \& stderr_file => \*(Aq/tmp/mydaemon.out\*(Aq, \& stdout_file => \*(Aq/tmp/mydaemon.out\*(Aq, \& \& fork => 2, \& \& )\->run; .Ve .PP By default \f(CW\*(C`run\*(C'\fR will use \f(CW@ARGV\fR for the action, and exit with an \s-1LSB\s0 compatible exit code. For finer control, you can use \f(CW\*(C`run_command\*(C'\fR, which will return the exit code, and accepts the action as an argument. This enables more programmatic control, as well as running multiple instances of Daemon::Control from one script. .PP .Vb 4 \& my $daemon = Daemon::Control\->new( \& ... \& ); \& my $exit = $daemon\->run_command(“start”); .Ve .PP You can then call the program: .PP .Vb 1 \& /home/symkat/etc/init.d/program start .Ve .PP You can also make an \s-1LSB\s0 compatible init script: .PP .Vb 1 \& /home/symkat/etc/init.d/program get_init_file > /etc/init.d/program .Ve .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" The constructor takes the following arguments as a list or a hash ref. .SS "name" .IX Subsection "name" The name of the program the daemon is controlling. This will be used in status messages \*(L"name [Started]\*(R" and the name for the \s-1LSB\s0 init script that is generated. .SS "program" .IX Subsection "program" This can be a coderef or the path to a shell program that is to be run. .PP .Vb 1 \& $daemon\->program( sub { ... } ); \& \& $daemon\->program( "/usr/sbin/http" ); .Ve .SS "program_args" .IX Subsection "program_args" This is an array ref of the arguments for the program. In the context of a coderef being executed this will be given to the coderef as \f(CW@_\fR, the Daemon::Control instance that called the coderef will be passed as the first arguments. Your arguments start at \f(CW$_\fR[1]. .PP In the context of a shell program, it will be given as arguments to be executed. .PP .Vb 1 \& $daemon\->program_args( [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ] ); \& \& $daemon\->program_args( [ \*(Aq\-\-switch\*(Aq, \*(Aqargument\*(Aq ] ); .Ve .SS "user" .IX Subsection "user" When set, the username supplied to this accessor will be used to set the \s-1UID\s0 attribute. When this is used, \f(CW\*(C`uid\*(C'\fR will be changed from its initial settings if you set it (which you shouldn't, since you're using usernames instead of UIDs). See \*(L"uid\*(R" for setting numerical user ids. .PP .Vb 1 \& $daemon\->user(\*(Aqwww\-data\*(Aq); .Ve .SS "group" .IX Subsection "group" When set, the groupname supplied to this accessor will be used to set the \s-1GID\s0 attribute. When this is used, \f(CW\*(C`gid\*(C'\fR will be changed from its initial settings if you set it (which you shouldn't, since you're using groupnames instead of GIDs). See \*(L"gid\*(R" for setting numerical group ids. .PP .Vb 1 \& $daemon\->group(\*(Aqwww\-data\*(Aq); .Ve .SS "uid" .IX Subsection "uid" If provided, the \s-1UID\s0 that the program will drop to when forked. This is \&\s-1ONLY\s0 supported in double-fork mode and will only work if you are running as root. Accepts numeric \s-1UID.\s0 For usernames please see \*(L"user\*(R". .PP .Vb 1 \& $daemon\->uid( 1001 ); .Ve .SS "gid" .IX Subsection "gid" If provided, the \s-1GID\s0 that the program will drop to when forked. This is \&\s-1ONLY\s0 supported in double-fork mode and will only work if you are running as root. Accepts numeric \s-1GID,\s0 for groupnames please see \*(L"group\*(R". .PP .Vb 1 \& $daemon\->gid( 1001 ); .Ve .SS "umask" .IX Subsection "umask" If provided, the umask of the daemon will be set to the umask provided, note that the umask must be in oct. By default the umask will not be changed. .PP .Vb 1 \& $daemon\->umask( 022 ); .Ve .PP Or: .PP .Vb 1 \& $daemon\->umask( oct("022") ); .Ve .SS "directory" .IX Subsection "directory" If provided, chdir to this directory before execution. .SS "path" .IX Subsection "path" The path of the script you are using Daemon::Control in. This will be used in the \s-1LSB\s0 file generation to point it to the location of the script. If this is not provided, the absolute path of \f(CW$0\fR will be used. .SS "init_config" .IX Subsection "init_config" The name of the init config file to load. When provided your init script will source this file to include the environment variables. This is useful for setting a \f(CW\*(C`PERL5LIB\*(C'\fR and such things. .PP .Vb 1 \& $daemon\->init_config( "/etc/default/my_program" ); .Ve .PP If you are using perlbrew, you probably want to set your init_config to \&\f(CW\*(C`$ENV{PERLBREW_ROOT} . \*(Aq/etc/bashrc\*(Aq\*(C'\fR. .SS "init_code" .IX Subsection "init_code" When given, whatever text is in this field will be dumped directly into the generated init file. .PP .Vb 1 \& $daemon\->init_code( "Arbitrary code goes here." ) .Ve .SS "help" .IX Subsection "help" Any text in this accessor will be printed when the script is called with the argument \f(CW\*(C`\-\-help\*(C'\fR or . .PP .Vb 1 \& $daemon\->help( "Read The Friendly Source." ); .Ve .SS "redirect_before_fork" .IX Subsection "redirect_before_fork" By default this is set to true. \s-1STDOUT\s0 will be redirected to \f(CW\*(C`stdout_file\*(C'\fR, and \s-1STDERR\s0 will be redirected to \f(CW\*(C`stderr_file\*(C'\fR. Setting this to 0 will disable redirecting before a double fork. This is useful when you are using a code reference and would like to leave the filehandles alone until you're in control. .PP Call \f(CW\*(C`\->redirect_filehandles\*(C'\fR on the Daemon::Control instance your coderef is passed to redirect the filehandles. .SS "stdout_file" .IX Subsection "stdout_file" If provided stdout will be redirected to the given file. This is only supported in double fork mode. .PP .Vb 1 \& $daemon\->stdout_file( "/tmp/mydaemon.stdout" ); .Ve .PP Alternatively, you can specify an arrayref of arguments to \f(CW\*(C`open()\*(C'\fR: .PP .Vb 2 \& $daemon\->stdout_file( [ \*(Aq>\*(Aq, \*(Aq/tmp/overwrite\-every\-run\*(Aq ] ); \& $daemon\->stdout_file( [ \*(Aq|\-\*(Aq, \*(Aqmy_pipe_program\*(Aq, \*(Aq\-a foo\*(Aq ] ); .Ve .SS "stderr_file" .IX Subsection "stderr_file" If provided stderr will be redirected to the given file. This is only supported in double fork mode. .PP .Vb 1 \& $daemon\->stderr_file( "/tmp/mydaemon.stderr" ); .Ve .PP Alternatively, you can specify an arrayref of arguments to \f(CW\*(C`open()\*(C'\fR: .PP .Vb 2 \& $daemon\->stderr_file( [ \*(Aq>\*(Aq, \*(Aq/tmp/overwrite\-every\-run\*(Aq ] ); \& $daemon\->stderr_file( [ \*(Aq|\-\*(Aq, \*(Aqmy_pipe_program\*(Aq, \*(Aq\-a foo\*(Aq ] ); .Ve .SS "pid_file" .IX Subsection "pid_file" The location of the \s-1PID\s0 file to use. Warning: if using single-fork mode, it is recommended to set this to the file which the daemon launching in single-fork mode will put its \s-1PID.\s0 Failure to follow this will most likely result in status, stop, and restart not working. .PP .Vb 1 \& $daemon\->pid_file( "/var/run/mydaemon/mydaemon.pid" ); .Ve .SS "resource_dir" .IX Subsection "resource_dir" This directory will be created, and chowned to the user/group provided in \&\f(CW\*(C`user\*(C'\fR, and \f(CW\*(C`group\*(C'\fR. .PP .Vb 1 \& $daemon\->resource_dir( "/var/run/mydaemon" ); .Ve .SS "prereq_no_process \*(-- \s-1EXPERIMENTAL\s0" .IX Subsection "prereq_no_process EXPERIMENTAL" This option is \s-1EXPERIMENTAL\s0 and defaults to \s-1OFF.\s0 .PP If this is set, then the \f(CW\*(C`ps\*(C'\fR list will be checked at startup for any processes that look like the daemon to be started. By default the pattern used is \f(CW\*(C`/\eb\eb/\*(C'\fR, but you can pass an override regexp in this field instead (to use the default pattern, just pass \f(CW\*(C`prereq_no_process => 1\*(C'\fR). If matching processes are found, those pids are output, and the daemon will not start. .PP This may produce some false positives on your system, depending on what else is running on your system, but it may still be of some use, e.g. if you seem to have daemons left running where the associated pid file is getting deleted somehow. .SS "fork" .IX Subsection "fork" The mode to use for fork. By default a double-fork will be used. .PP In double-fork, uid, gid, std*_file, and a number of other things are supported. A traditional double-fork is used and setsid is called. .PP In single-fork none of the above are called, and it is the responsibility of whatever you're forking to reopen files, associate with the init process and do all that fun stuff. This mode is recommended when the program you want to control has its own daemonizing code. It is important to note that the \s-1PID\s0 file should be set to whatever \s-1PID\s0 file is used by the daemon. .PP In no-fork mode, \f(CWfork(0)\fR, the program is run in the foreground. By default quiet is still turned off, so status updates will be shown on the screen such as that the daemon started. A shortcut to turn status off and go into foreground mode is \f(CW\*(C`foreground\*(C'\fR being set to 1, or \f(CW\*(C`DC_FOREGROUND\*(C'\fR being set as an environment variable. Additionally, calling \f(CW\*(C`foreground\*(C'\fR instead of \f(CW\*(C`start\*(C'\fR will override the forking mode at run-time. .PP .Vb 1 \& $daemon\->fork( 0 ); \& \& $daemon\->fork( 1 ); \& \& $daemon\->fork( 2 ); # Default .Ve .SS "scan_name" .IX Subsection "scan_name" This provides an extra check to see if the program is running. Normally we only check that the \s-1PID\s0 listed in the \s-1PID\s0 file is running. When given a regular expression, we will also match the name of the program as shown in ps. .PP .Vb 1 \& $daemon\->scan_name( qr|mydaemon| ); .Ve .SS "kill_timeout" .IX Subsection "kill_timeout" This provides an amount of time in seconds between kill signals being sent to the daemon. This value should be increased if your daemon has a longer shutdown period. By default 1 second is used. .PP .Vb 1 \& $daemon\->kill_timeout( 7 ); .Ve .SS "lsb_start" .IX Subsection "lsb_start" The value of this string is used for the 'Required\-Start' value of the generated \s-1LSB\s0 init script. See for more information. .PP .Vb 1 \& $daemon\->lsb_start( \*(Aq$remote_fs $syslog\*(Aq ); .Ve .SS "lsb_stop" .IX Subsection "lsb_stop" The value of this string is used for the 'Required\-Stop' value of the generated \s-1LSB\s0 init script. See for more information. .PP .Vb 1 \& $daemon\->lsb_stop( \*(Aq$remote_fs $syslog\*(Aq ); .Ve .SS "lsb_sdesc" .IX Subsection "lsb_sdesc" The value of this string is used for the 'Short\-Description' value of the generated \s-1LSB\s0 init script. See for more information. .PP .Vb 1 \& $daemon\->lsb_sdesc( \*(AqMy program...\*(Aq ); .Ve .SS "lsb_desc" .IX Subsection "lsb_desc" The value of this string is used for the 'Description' value of the generated \s-1LSB\s0 init script. See for more information. .PP .Vb 1 \& $daemon\->lsb_desc( \*(AqMy program controls a thing that does a thing.\*(Aq ); .Ve .SS "quiet" .IX Subsection "quiet" If this boolean flag is set to a true value all output from the init script (\s-1NOT\s0 your daemon) to \s-1STDOUT\s0 will be suppressed. .PP .Vb 1 \& $daemon\->quiet( 1 ); .Ve .SS "reload_signal" .IX Subsection "reload_signal" The signal to send to the daemon when reloading it. Default signal is \f(CW\*(C`HUP\*(C'\fR. .SS "stop_signals" .IX Subsection "stop_signals" An array ref of signals that should be tried (in order) when stopping the daemon. Default signals are \f(CW\*(C`TERM\*(C'\fR, \f(CW\*(C`TERM\*(C'\fR, \f(CW\*(C`INT\*(C'\fR and \f(CW\*(C`KILL\*(C'\fR (yes, \f(CW\*(C`TERM\*(C'\fR is tried twice). .SH "PLUGINS" .IX Header "PLUGINS" Daemon Control supports a simple plugin system using Role::Tiny. .SS "with_plugins" .IX Subsection "with_plugins" With plugins adds the plugins to Daemon::Control. .PP .Vb 3 \& Daemon::Control\->with_plugins( qw( MyFirstPlugin +MySecondPlugin) )\->new( \& ... \& ); .Ve .PP Note: .PP MyFirstPlugin will load Daemon::Control::Plugin::MyFirstPlugin .PP +MySecondPlugin will load MySecondPlugin .SS "Writing A Plugin" .IX Subsection "Writing A Plugin" Your plugin should use the name Daemon::Control::Plugin::YourModuleName and YourModuleName should reasonably match the effect your plugin has on Daemon::Control. .PP You can replace Daemon::Control methods by writing your own and using Role::Tiny within your class to allow it to be composed into Daemon::Control. .PP The default Daemon::Control ships with no dependencies and supports Perl 5.8.1+, to use the plugin system your module \s-1MUST\s0 declare dependency on Role::Tiny and if you wish to use the \f(CW\*(C`around\*(C'\fR, \f(CW\*(C`before\*(C'\fR and \f(CW\*(C`after\*(C'\fR your module \s-1MUST\s0 declare dependence on Class::Method::Modifiers in your package. .SH "METHODS" .IX Header "METHODS" .SS "run_command" .IX Subsection "run_command" This function will process an action on the Daemon::Control instance. Valid arguments are those which a \f(CW\*(C`do_\*(C'\fR method exists for, such as \&\fBstart\fR, \fBstop\fR, \fBrestart\fR. Returns the \s-1LSB\s0 exit code for the action processed. .SS "run" .IX Subsection "run" This will make your program act as an init file, accepting input from the command line. Run will exit with 0 for success and uses \s-1LSB\s0 exit codes. As such no code should be used after \->run is called. Any code in your file should be before this. This is a shortcut for .PP .Vb 1 \& exit Daemon::Control\->new(...)\->run_command( @ARGV ); .Ve .SS "do_start" .IX Subsection "do_start" Is called when start is given as an argument. Starts the forking and exits. Called by: .PP .Vb 1 \& /usr/bin/my_program_launcher.pl start .Ve .SS "do_foreground" .IX Subsection "do_foreground" Is called when \fBforeground\fR is given as an argument. Starts the program or code reference and stays in the foreground \*(-- no forking is done, regardless of the compile-time arguments. Additionally, turns \f(CW\*(C`quiet\*(C'\fR on to avoid showing Daemon::Control output. .PP .Vb 1 \& /usr/bin/my_program_launcher.pl foreground .Ve .SS "do_stop" .IX Subsection "do_stop" Is called when stop is given as an argument. Stops the running program if it can. Called by: .PP .Vb 1 \& /usr/bin/my_program_launcher.pl stop .Ve .SS "do_restart" .IX Subsection "do_restart" Is called when restart is given as an argument. Calls do_stop and do_start. Called by: .PP .Vb 1 \& /usr/bin/my_program_launcher.pl restart .Ve .SS "do_reload" .IX Subsection "do_reload" Is called when reload is given as an argument. Sends the signal \&\f(CW\*(C`reload_signal\*(C'\fR to the daemon. .PP .Vb 1 \& /usr/bin/my_program_launcher.pl reload .Ve .SS "do_status" .IX Subsection "do_status" Is called when status is given as an argument. Displays the status of the program, basic on the \s-1PID\s0 file. Called by: .PP .Vb 1 \& /usr/bin/my_program_launcher.pl status .Ve .SS "do_get_init_file" .IX Subsection "do_get_init_file" Is called when get_init_file is given as an argument. Dumps an \s-1LSB\s0 compatible init file, for use in /etc/init.d/. Called by: .PP .Vb 1 \& /usr/bin/my_program_launcher.pl get_init_file .Ve .SS "pretty_print" .IX Subsection "pretty_print" This is used to display status to the user. It accepts a message and a color. It will default to green text, if no color is explicitly given. Only supports red and green. .PP .Vb 1 \& $daemon\->pretty_print( "My Status", "red" ); .Ve .SS "write_pid" .IX Subsection "write_pid" This will write the \s-1PID\s0 to the file in pid_file. .SS "read_pid" .IX Subsection "read_pid" This will read the \s-1PID\s0 from the file in pid_file and set it in pid. .SS "pid" .IX Subsection "pid" An accessor for the \s-1PID.\s0 Set by read_pid, or when the program is started. .SS "dump_init_script" .IX Subsection "dump_init_script" A function to dump the \s-1LSB\s0 compatible init script. Used by do_get_init_file. .SH "AUTHOR" .IX Header "AUTHOR" Kaitlyn Parkhurst (SymKat) \fI\fR ( Blog: ) .SS "\s-1CONTRIBUTORS\s0" .IX Subsection "CONTRIBUTORS" .IP "\(bu" 4 Matt S. Trout (mst) \fI\fR .IP "\(bu" 4 Mike Doherty (doherty) \fI\fR .IP "\(bu" 4 Karen Etheridge (ether) \fI\fR .IP "\(bu" 4 Ævar Arnfjörð Bjarmason (avar) \fI\fR .IP "\(bu" 4 Kieren Diment \fI .IP "\(bu" 4 Mark Curtis \fI .IP "\(bu" 4 Zoffix Znet \fI .SS "\s-1SPONSORS\s0" .IX Subsection "SPONSORS" Parts of this code were paid for by .IP "(mt) Media Temple " 4 .IX Item "(mt) Media Temple " .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2012 the Daemon::Control \*(L"\s-1AUTHOR\*(R"\s0, \*(L"\s-1CONTRIBUTORS\*(R"\s0, and \*(L"\s-1SPONSORS\*(R"\s0 as listed above. .SH "LICENSE" .IX Header "LICENSE" This library is free software and may be distributed under the same terms as perl itself. .SS "\s-1AVAILABILITY\s0" .IX Subsection "AVAILABILITY" The most current version of Daemon::Control can be found at