From 26b064ed3eb0d5efe1c683c0527008971edc0105 Mon Sep 17 00:00:00 2001 From: Kieren Diment Date: Fri, 10 Apr 2015 13:11:04 +1000 Subject: [PATCH 1/5] some syslog related documentation --- README.md | 90 ++++++++++++++++++++++++++++++++++++------- lib/Daemon/Control.pm | 58 ++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 966b61f..ec10d29 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Write a program that describes the daemon: use strict; use Daemon::Control; - Daemon::Control->new( + exit Daemon::Control->new( name => "My Daemon", lsb_start => '$syslog $remote_fs', lsb_stop => '$syslog', @@ -44,7 +44,7 @@ Write a program that describes the daemon: By default `run` will use @ARGV for the action, and exit with an LSB compatible exit code. For finer control, you can use `run_command`, which will return the exit code, and accepts the action as an argument. This enables more programatic -control, as well as running multiple instances of M from one script. +control, as well as running multiple instances of [Daemon::Control](https://metacpan.org/pod/Daemon::Control) from one script. my $daemon = Daemon::Control->new( ... @@ -59,10 +59,6 @@ You can also make an LSB compatible init script: /home/symkat/etc/init.d/program get_init_file > /etc/init.d/program - - - - # CONSTRUCTOR The constructor takes the following arguments as a list or a hash ref. @@ -185,7 +181,7 @@ and STDERR will be redirected to `stderr_file`. 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. -Call `-`redirect\_filehandles> on the Daemon::Control instance your coderef is +Call `->redirect_filehandles` on the Daemon::Control instance your coderef is passed to redirect the filehandles. ## stdout\_file @@ -253,7 +249,6 @@ as that the daemon started. A shortcut to turn status off and go into foregroun mode is `foreground` being set to 1, or `DC_FOREGROUND` being set as an environment variable. Additionally, calling `foreground` instead of `start` will override the forking mode at run-time. - $daemon->fork( 0 ); @@ -317,13 +312,25 @@ If this boolean flag is set to a true value all output from the init script $daemon->quiet( 1 ); +## reload\_signal + +The signal to send to the daemon when reloading it. +Default signal is `HUP`. + +## stop\_signals + +An array ref of signals that should be tried (in order) when +stopping the daemon. +Default signals are `TERM`, `TERM`, `INT` and `KILL` (yes, `TERM` +is tried twice). + # METHODS ## run\_command This function will process an action on the Daemon::Control instance. Valid arguments are those which a `do_` method exists for, such as -__start__, __stop__, __restart__. Returns the LSB exit code for the +**start**, **stop**, **restart**. Returns the LSB exit code for the action processed. ## run @@ -344,10 +351,10 @@ exits. Called by: ## do\_foreground -Is called when __foreground__ is given as an argument. Starts the +Is called when **foreground** 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 `quiet` on to avoid showing M output. +turns `quiet` on to avoid showing [Daemon::Control](https://metacpan.org/pod/Daemon::Control) output. /usr/bin/my_program_launcher.pl foreground @@ -367,8 +374,8 @@ Called by: ## do\_reload -Is called when reload is given as an argument. Sends a HUP signal to the -daemon. +Is called when reload is given as an argument. Sends the signal +`reload_signal` to the daemon. /usr/bin/my_program_launcher.pl reload @@ -410,9 +417,62 @@ An accessor for the PID. Set by read\_pid, or when the program is started. A function to dump the LSB compatible init script. Used by do\_get\_init\_file. +# FAQ + +## LOGGING TO SYSLOG + +Logging a daemon::control script to syslog can be a little involved. +If you're using Log4perl or similar, consider using +[Log::Dispatch::Syslog](https://metacpan.org/pod/Log::Dispatch::Syslog) and/or [Sys::Syslog](https://metacpan.org/pod/Sys::Syslog). An alternative +approach using a fifo is as follows: + +First, set up the stderr\_file and stdout\_file to a fifo. + +Daemon::Control->new({ + ..., # normal setup + stderr\_file => "/var/log/myuser/myservice.fifo", + stdout\_file => "/var/log/myuser/myservice.fifo", + ..., })->run; + +However you need a service running that reads from the fifo, in this +case logger(1). When your main service (that writes to the fifos) exits +this close is read by ` logger ` and causes it to exit. In order to avoid +that we created a service that respawns logger when it dies. This +example is for a redhat system running upstart: + +The following script can be dropped into /etc/init as fifo-logger.conf +And then started with ` initctl start fifo-logger `. + + # fifo-logger - logger process for fcgi + # + # Will respawn the logger process as it exits on file close + + start on stopped rc RUNLEVEL=[345] + + stop on starting shutdown + + console output + respawn + + script + echo $$ > /var/run/fifo-logger.pid + exec logger -f /var/log/myuser/myservice.fifo -t myservice -p local0.notice + end script + + pre-start script + if [ ! -e /var/log/myuser/myservice.fifo ]; then + mkfifo /var/log/myuser/myservice.fifo + fi + chown hiive.hiive /var/log/myuser/myservice.fifo + chmod 660 /var/log/myuser/myservice.fifo + end script + +From this point, all the output will be sent to syslog as local0.notice and can +then be routed/cycled a needed without requiring a restart of the application. + # AUTHOR - Kaitlyn Parkhurst (SymKat) __ ( Blog: [http://symkat.com/](http://symkat.com/) ) +> Kaitlyn Parkhurst (SymKat) __ ( Blog: [http://symkat.com/](http://symkat.com/) ) ## CONTRIBUTORS @@ -420,6 +480,8 @@ A function to dump the LSB compatible init script. Used by do\_get\_init\_file. - Mike Doherty (doherty) __ - Karen Etheridge (ether) __ - Ævar Arnfjörð Bjarmason (avar) __ +- Kieren Diment _ +- Mark Curtis _ ## SPONSORS diff --git a/lib/Daemon/Control.pm b/lib/Daemon/Control.pm index 2d3dbb3..4437d5c 100644 --- a/lib/Daemon/Control.pm +++ b/lib/Daemon/Control.pm @@ -1112,6 +1112,60 @@ An accessor for the PID. Set by read_pid, or when the program is started. A function to dump the LSB compatible init script. Used by do_get_init_file. +=head1 FAQ + +=head2 LOGGING TO SYSLOG + +Logging a daemon::control script to syslog can be a little involved. +If you're using Log4perl or similar, consider using +L and/or L. An alternative +approach using a fifo is as follows: + +First, set up the stderr_file and stdout_file to a fifo. + +Daemon::Control->new({ + ..., # normal setup + stderr_file => "/var/log/myuser/myservice.fifo", + stdout_file => "/var/log/myuser/myservice.fifo", + ..., })->run; + +However you need a service running that reads from the fifo, in this +case logger(1). When your main service (that writes to the fifos) exits +this close is read by C< logger > and causes it to exit. In order to avoid +that we created a service that respawns logger when it dies. This +example is for a redhat system running upstart: + +The following script can be dropped into /etc/init as fifo-logger.conf +And then started with C< initctl start fifo-logger >. + + # fifo-logger - logger process for fcgi + # + # Will respawn the logger process as it exits on file close + + start on stopped rc RUNLEVEL=[345] + + stop on starting shutdown + + console output + respawn + + script + echo $$ > /var/run/fifo-logger.pid + exec logger -f /var/log/myuser/myservice.fifo -t myservice -p local0.notice + end script + + pre-start script + if [ ! -e /var/log/myuser/myservice.fifo ]; then + mkfifo /var/log/myuser/myservice.fifo + fi + chown hiive.hiive /var/log/myuser/myservice.fifo + chmod 660 /var/log/myuser/myservice.fifo + end script + +From this point, all the output will be sent to syslog as local0.notice and can +then be routed/cycled a needed without requiring a restart of the application. + + =head1 AUTHOR =over 4 @@ -1132,6 +1186,10 @@ Kaitlyn Parkhurst (SymKat) Isymkat@symkat.comE> ( Blog: Lavar@cpan.orgE> +=item * Kieren Diment Izarquon@cpan.org> + +=item * Mark Curtis Imark.curtis@affinitylive.com> + =back =head2 SPONSORS From 0f7ef43c3fb33ec2dbffe72b68af6c934bbff182 Mon Sep 17 00:00:00 2001 From: Kieren Diment Date: Fri, 10 Apr 2015 13:13:45 +1000 Subject: [PATCH 2/5] markdown formatting error --- README.md | 10 +++++----- lib/Daemon/Control.pm | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index ec10d29..fbd8b99 100644 --- a/README.md +++ b/README.md @@ -428,11 +428,11 @@ approach using a fifo is as follows: First, set up the stderr\_file and stdout\_file to a fifo. -Daemon::Control->new({ - ..., # normal setup - stderr\_file => "/var/log/myuser/myservice.fifo", - stdout\_file => "/var/log/myuser/myservice.fifo", - ..., })->run; + Daemon::Control->new({ + ..., # normal setup + stderr_file => "/var/log/myuser/myservice.fifo", + stdout_file => "/var/log/myuser/myservice.fifo", + ..., })->run; However you need a service running that reads from the fifo, in this case logger(1). When your main service (that writes to the fifos) exits diff --git a/lib/Daemon/Control.pm b/lib/Daemon/Control.pm index 4437d5c..9d84dbf 100644 --- a/lib/Daemon/Control.pm +++ b/lib/Daemon/Control.pm @@ -1123,11 +1123,11 @@ approach using a fifo is as follows: First, set up the stderr_file and stdout_file to a fifo. -Daemon::Control->new({ - ..., # normal setup - stderr_file => "/var/log/myuser/myservice.fifo", - stdout_file => "/var/log/myuser/myservice.fifo", - ..., })->run; + Daemon::Control->new({ + ..., # normal setup + stderr_file => "/var/log/myuser/myservice.fifo", + stdout_file => "/var/log/myuser/myservice.fifo", + ..., })->run; However you need a service running that reads from the fifo, in this case logger(1). When your main service (that writes to the fifos) exits From 10a813fcd6769663248fd9e333c1a705bb18e73c Mon Sep 17 00:00:00 2001 From: Kieren Diment Date: Fri, 10 Apr 2015 13:11:04 +1000 Subject: [PATCH 3/5] some syslog related documentation --- README.md | 90 ++++++++++++++++++++++++++++++++++++------- lib/Daemon/Control.pm | 58 ++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 966b61f..ec10d29 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Write a program that describes the daemon: use strict; use Daemon::Control; - Daemon::Control->new( + exit Daemon::Control->new( name => "My Daemon", lsb_start => '$syslog $remote_fs', lsb_stop => '$syslog', @@ -44,7 +44,7 @@ Write a program that describes the daemon: By default `run` will use @ARGV for the action, and exit with an LSB compatible exit code. For finer control, you can use `run_command`, which will return the exit code, and accepts the action as an argument. This enables more programatic -control, as well as running multiple instances of M from one script. +control, as well as running multiple instances of [Daemon::Control](https://metacpan.org/pod/Daemon::Control) from one script. my $daemon = Daemon::Control->new( ... @@ -59,10 +59,6 @@ You can also make an LSB compatible init script: /home/symkat/etc/init.d/program get_init_file > /etc/init.d/program - - - - # CONSTRUCTOR The constructor takes the following arguments as a list or a hash ref. @@ -185,7 +181,7 @@ and STDERR will be redirected to `stderr_file`. 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. -Call `-`redirect\_filehandles> on the Daemon::Control instance your coderef is +Call `->redirect_filehandles` on the Daemon::Control instance your coderef is passed to redirect the filehandles. ## stdout\_file @@ -253,7 +249,6 @@ as that the daemon started. A shortcut to turn status off and go into foregroun mode is `foreground` being set to 1, or `DC_FOREGROUND` being set as an environment variable. Additionally, calling `foreground` instead of `start` will override the forking mode at run-time. - $daemon->fork( 0 ); @@ -317,13 +312,25 @@ If this boolean flag is set to a true value all output from the init script $daemon->quiet( 1 ); +## reload\_signal + +The signal to send to the daemon when reloading it. +Default signal is `HUP`. + +## stop\_signals + +An array ref of signals that should be tried (in order) when +stopping the daemon. +Default signals are `TERM`, `TERM`, `INT` and `KILL` (yes, `TERM` +is tried twice). + # METHODS ## run\_command This function will process an action on the Daemon::Control instance. Valid arguments are those which a `do_` method exists for, such as -__start__, __stop__, __restart__. Returns the LSB exit code for the +**start**, **stop**, **restart**. Returns the LSB exit code for the action processed. ## run @@ -344,10 +351,10 @@ exits. Called by: ## do\_foreground -Is called when __foreground__ is given as an argument. Starts the +Is called when **foreground** 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 `quiet` on to avoid showing M output. +turns `quiet` on to avoid showing [Daemon::Control](https://metacpan.org/pod/Daemon::Control) output. /usr/bin/my_program_launcher.pl foreground @@ -367,8 +374,8 @@ Called by: ## do\_reload -Is called when reload is given as an argument. Sends a HUP signal to the -daemon. +Is called when reload is given as an argument. Sends the signal +`reload_signal` to the daemon. /usr/bin/my_program_launcher.pl reload @@ -410,9 +417,62 @@ An accessor for the PID. Set by read\_pid, or when the program is started. A function to dump the LSB compatible init script. Used by do\_get\_init\_file. +# FAQ + +## LOGGING TO SYSLOG + +Logging a daemon::control script to syslog can be a little involved. +If you're using Log4perl or similar, consider using +[Log::Dispatch::Syslog](https://metacpan.org/pod/Log::Dispatch::Syslog) and/or [Sys::Syslog](https://metacpan.org/pod/Sys::Syslog). An alternative +approach using a fifo is as follows: + +First, set up the stderr\_file and stdout\_file to a fifo. + +Daemon::Control->new({ + ..., # normal setup + stderr\_file => "/var/log/myuser/myservice.fifo", + stdout\_file => "/var/log/myuser/myservice.fifo", + ..., })->run; + +However you need a service running that reads from the fifo, in this +case logger(1). When your main service (that writes to the fifos) exits +this close is read by ` logger ` and causes it to exit. In order to avoid +that we created a service that respawns logger when it dies. This +example is for a redhat system running upstart: + +The following script can be dropped into /etc/init as fifo-logger.conf +And then started with ` initctl start fifo-logger `. + + # fifo-logger - logger process for fcgi + # + # Will respawn the logger process as it exits on file close + + start on stopped rc RUNLEVEL=[345] + + stop on starting shutdown + + console output + respawn + + script + echo $$ > /var/run/fifo-logger.pid + exec logger -f /var/log/myuser/myservice.fifo -t myservice -p local0.notice + end script + + pre-start script + if [ ! -e /var/log/myuser/myservice.fifo ]; then + mkfifo /var/log/myuser/myservice.fifo + fi + chown hiive.hiive /var/log/myuser/myservice.fifo + chmod 660 /var/log/myuser/myservice.fifo + end script + +From this point, all the output will be sent to syslog as local0.notice and can +then be routed/cycled a needed without requiring a restart of the application. + # AUTHOR - Kaitlyn Parkhurst (SymKat) __ ( Blog: [http://symkat.com/](http://symkat.com/) ) +> Kaitlyn Parkhurst (SymKat) __ ( Blog: [http://symkat.com/](http://symkat.com/) ) ## CONTRIBUTORS @@ -420,6 +480,8 @@ A function to dump the LSB compatible init script. Used by do\_get\_init\_file. - Mike Doherty (doherty) __ - Karen Etheridge (ether) __ - Ævar Arnfjörð Bjarmason (avar) __ +- Kieren Diment _ +- Mark Curtis _ ## SPONSORS diff --git a/lib/Daemon/Control.pm b/lib/Daemon/Control.pm index fe1c7ad..dc01a36 100644 --- a/lib/Daemon/Control.pm +++ b/lib/Daemon/Control.pm @@ -1112,6 +1112,60 @@ An accessor for the PID. Set by read_pid, or when the program is started. A function to dump the LSB compatible init script. Used by do_get_init_file. +=head1 FAQ + +=head2 LOGGING TO SYSLOG + +Logging a daemon::control script to syslog can be a little involved. +If you're using Log4perl or similar, consider using +L and/or L. An alternative +approach using a fifo is as follows: + +First, set up the stderr_file and stdout_file to a fifo. + +Daemon::Control->new({ + ..., # normal setup + stderr_file => "/var/log/myuser/myservice.fifo", + stdout_file => "/var/log/myuser/myservice.fifo", + ..., })->run; + +However you need a service running that reads from the fifo, in this +case logger(1). When your main service (that writes to the fifos) exits +this close is read by C< logger > and causes it to exit. In order to avoid +that we created a service that respawns logger when it dies. This +example is for a redhat system running upstart: + +The following script can be dropped into /etc/init as fifo-logger.conf +And then started with C< initctl start fifo-logger >. + + # fifo-logger - logger process for fcgi + # + # Will respawn the logger process as it exits on file close + + start on stopped rc RUNLEVEL=[345] + + stop on starting shutdown + + console output + respawn + + script + echo $$ > /var/run/fifo-logger.pid + exec logger -f /var/log/myuser/myservice.fifo -t myservice -p local0.notice + end script + + pre-start script + if [ ! -e /var/log/myuser/myservice.fifo ]; then + mkfifo /var/log/myuser/myservice.fifo + fi + chown hiive.hiive /var/log/myuser/myservice.fifo + chmod 660 /var/log/myuser/myservice.fifo + end script + +From this point, all the output will be sent to syslog as local0.notice and can +then be routed/cycled a needed without requiring a restart of the application. + + =head1 AUTHOR =over 4 @@ -1132,6 +1186,10 @@ Kaitlyn Parkhurst (SymKat) Isymkat@symkat.comE> ( Blog: Lavar@cpan.orgE> +=item * Kieren Diment Izarquon@cpan.org> + +=item * Mark Curtis Imark.curtis@affinitylive.com> + =back =head2 SPONSORS From a3a3da0b0a15742c46c75852c4c8b5e507539bab Mon Sep 17 00:00:00 2001 From: Kieren Diment Date: Fri, 10 Apr 2015 13:13:45 +1000 Subject: [PATCH 4/5] markdown formatting error --- README.md | 10 +++++----- lib/Daemon/Control.pm | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index ec10d29..fbd8b99 100644 --- a/README.md +++ b/README.md @@ -428,11 +428,11 @@ approach using a fifo is as follows: First, set up the stderr\_file and stdout\_file to a fifo. -Daemon::Control->new({ - ..., # normal setup - stderr\_file => "/var/log/myuser/myservice.fifo", - stdout\_file => "/var/log/myuser/myservice.fifo", - ..., })->run; + Daemon::Control->new({ + ..., # normal setup + stderr_file => "/var/log/myuser/myservice.fifo", + stdout_file => "/var/log/myuser/myservice.fifo", + ..., })->run; However you need a service running that reads from the fifo, in this case logger(1). When your main service (that writes to the fifos) exits diff --git a/lib/Daemon/Control.pm b/lib/Daemon/Control.pm index dc01a36..5d35931 100644 --- a/lib/Daemon/Control.pm +++ b/lib/Daemon/Control.pm @@ -1123,11 +1123,11 @@ approach using a fifo is as follows: First, set up the stderr_file and stdout_file to a fifo. -Daemon::Control->new({ - ..., # normal setup - stderr_file => "/var/log/myuser/myservice.fifo", - stdout_file => "/var/log/myuser/myservice.fifo", - ..., })->run; + Daemon::Control->new({ + ..., # normal setup + stderr_file => "/var/log/myuser/myservice.fifo", + stdout_file => "/var/log/myuser/myservice.fifo", + ..., })->run; However you need a service running that reads from the fifo, in this case logger(1). When your main service (that writes to the fifos) exits From b867d7fd0c5e9b6a7a3a691f574472e2fec6152d Mon Sep 17 00:00:00 2001 From: Kaitlyn Parkhurst Date: Fri, 7 Aug 2015 07:30:15 -0700 Subject: [PATCH 5/5] 0.1.8 * Fix issue with author name * Allow for custom open() args for stdout_file and stderr_file --- Changes | 4 +++- lib/Daemon/Control.pm | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/Changes b/Changes index 3bd9520..3e9c110 100644 --- a/Changes +++ b/Changes @@ -1,4 +1,6 @@ - * allow for custom open() args for stdout_file and stderr_file +0.001008 2015-08-07 + * Fix issue with author name + * Allow for custom open() args for stdout_file and stderr_file 0.001007 2015-07-26 SymKat * Module name POD format fixed (RT 93280) diff --git a/lib/Daemon/Control.pm b/lib/Daemon/Control.pm index 0b7b814..a37b399 100644 --- a/lib/Daemon/Control.pm +++ b/lib/Daemon/Control.pm @@ -8,7 +8,7 @@ use File::Path qw( make_path ); use Cwd 'abs_path'; require 5.008001; # Supporting 5.8.1+ -our $VERSION = '0.001007'; # 0.1.7 +our $VERSION = '0.001008'; # 0.1.8 $VERSION = eval $VERSION; my @accessors = qw(