App-Daemon-0.22/000755 040416 000024 00000000000 12410731227 014321 5ustar00mschillistaff000000 000000 App-Daemon-0.22/.licensizer.yml000644 040416 000024 00000000562 12073646363 017307 0ustar00mschillistaff000000 000000 # .licensizer.yml author: text: | 2008, Mike Schilli header: AUTHORS mode: verbatim license: text: | Copyright 2008-2012 by Mike Schilli, all rights reserved. This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself. header: LEGALESE path_exclude: - t/ - blib/ App-Daemon-0.22/adm/000755 040416 000024 00000000000 12410731226 015061 5ustar00mschillistaff000000 000000 App-Daemon-0.22/Changes000644 040416 000024 00000011070 12410323041 015602 0ustar00mschillistaff000000 000000 Revision history for Perl extension App::Daemon. 0.22 (09/23/2014) (ms) Fixed test suite to shut down fork daemon at the end. 0.21 (04/28/2014) (ms) Nicolai Langfeldt added -g option to switch to specified group when app was started as root. (ms) Makefile.PL now dies on Win32 to save the CPAN smoke testers some grief with hanging tests ([rt.cpan.org #81980]) 0.20 (11/11/2013) (ms) [rt.cpan.org #61428] Fixed bug in detach() which no longer attempts to write to a non-existing pid file. 0.19 (07/07/2013) (ms) [rt.cpan.org #86762] Peter noticed that App::Daemon's fork() check was incorrect. Fixed. 0.18 (10/31/2012) (ms) [rt.cpan.org #75931] Fixed previous release to actually work with Proc::ProcessTable missing. 0.17 (10/30/2012) (ms) [rt.cpan.org #75931] To address problems with Proc::ProcessTable on some platforms, changed process_is_running() to use POSIX methods only. Proc::ProcessTable is now optional and only required when using process_running_by_name(). 0.16 (10/21/2012) (ms) [rt.cpan.org #44462] forked children now don't remove the master's pid file anymore when they exit. Thanks to Felix Ostmann and Vadim Troshchinskiy for proposing the fix. 0.15 (02/22/2012) (ms) [rt.cpan.org #75219] Umask is now set to 0 to allow OS calls to provide their own permission masks and not to depend on the umask of the caller. 0.14 (12/25/2011) (ms) [rt.cpan.org #72835] Patch by Peter to fix 'restart'. 0.13 (07/19/2011) (ms) [rt.cpan.org #69561] default log and pid files are now in the current directory, not in /tmp by default because of security concerns. (ms) [rt.cpan.org #69561] not setting umask anymore 0.12 (07/18/2011) (ms) 'status' now doesn't write to the logfile (suggested by Brian Pitts) (ms) 'stop' now verifies if the process is still up, and retries $App::Daemon::kill_retries times (defaults to 3) times, with 1-second sleeps in between. (ms) Upon successful 'stop', pid file now gets removed (suggested by Brian Pitts) (ms) 'status' now triggers exit codes in compliance with http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html (suggested by Brian Pitts) (ms) using SIGTERM now instead of SIGINT to terminate a process 0.11 (08/28/2010) (ms) Fixed test suite. 0.10 (08/19/2010) (ms) Writing pid file before dropping privileges (just like logfile). 0.09 (04/09/2010) (ms) Fixed find_option example on manual page. Thanks to Rolf Schaufelberger for pointing it out. (ms) Added github repository link to Makefile.PL (ms) Changed dropping privileges to setuid() (http://www.perlmonks.org/?node_id=833950) 0.08 (11/05/2009) (ms) [RT 50884] Applied patch by Matthew Byng-Maddick allow overriding app-internal option settings by command line options. Order is now: command line > app-internal > App::Daemon internal (ms) [RT 51066] Applied patch by Mike Whitaker to point stdin/out/err to /dev/null instead of closing them. 0.07 (10/08/2009) (ms) Applied patch by Sadrak [rt:44513] to check if Log4perl has already been initialized and skip the easy_init call in this case. Note that -v then has to be handled by the user-provided Log4perl configuration instead. (ms) [RT 50326] Fixed insecure dependency error in tainted mode by untainting the string obtained by appname(). 0.06 (03/05/2009) (ms) Added detach() as an importable method for simple daemons. 0.05 (02/17/2009) (ms) Better docs as requested by Tim Appnel (ms) docs on application-specific command line options (ms) Better daemonization according to Stevens (Advanced Programming in the UNIX environment) (ms) Make sure the child isn't killed by a closed session before it is able to detach from the tty. (ms) Better __DIE__ handler as suggested by Karl Rune Nilsen in http://rt.cpan.org/Ticket/Display.html?id=39917. 0.04 10/02/2008 (ms) Fixed logfile permissions if daemon starts up at root and then drops priviledges. Added docs. 0.03 08/03/2008 (ms) Fixed test suite for Freebsd, which locks tempfiles exclusively. Thanks to to CPAN tester Slaven Rezic. (ms) Removed restriction on perl-5.8. 0.02 08/01/2008 (ms) Added setting logfile and pidfile within the script itself, as suggested by Kimo Rosenbaum. (ms) Fixed OLDERR warnings in test suite. 0.01 07/19/2008 (ms) Where it all began. App-Daemon-0.22/Daemon.pm000644 040416 000024 00000052043 12410323102 016053 0ustar00mschillistaff000000 000000 package App::Daemon; use strict; use warnings; our $VERSION = '0.22'; use Getopt::Std; use Pod::Usage; use File::Basename; use Log::Log4perl qw(:easy); use POSIX; use Exporter; use Fcntl qw/:flock/; our @ISA = qw(Exporter); our @EXPORT_OK = qw(daemonize cmd_line_parse detach); use constant LSB_OK => 0; use constant LSB_DEAD_PID_EXISTS => 1; use constant LSB_DEAD_LOCK_EXISTS => 2; use constant LSB_NOT_RUNNING => 3; use constant LSB_UNKNOWN => 4; use constant ALREADY_RUNNING => 150; our ($pidfile, $logfile, $l4p_conf, $as_user, $as_group, $background, $loglevel, $action, $appname, $default_pid_dir, $default_log_dir); $action = ""; $appname = appname(); $default_pid_dir = "."; $default_log_dir = "."; our $kill_retries = 3; our $kill_sig = SIGTERM; # maps to 15 via POSIX.pm ########################################### sub cmd_line_parse { ########################################### if( find_option("-h") ) { pod2usage(); } if(my $_pidfile = find_option('-p', 1)) { $pidfile = $_pidfile; } else { $pidfile ||= ( "$default_pid_dir/" . $appname . ".pid" ); } if(my $_logfile = find_option('-l', 1)) { $logfile = $_logfile; } else { $logfile ||= ( "$default_log_dir/" . $appname . ".log" ); } if(my $_l4p_conf = find_option('-l4p', 1)) { $l4p_conf = $_l4p_conf; } if(my $_as_user = find_option('-u', 1)) { $as_user = $_as_user; } else { $as_user ||= 'nobody'; } if(my $_as_group = find_option('-g', 1)) { $as_group = $_as_group; } else { $as_group ||= 'nogroup'; } if($> != 0) { # Not root? Then we're ourselves ($as_user) = getpwuid($>); ($as_group) = getgrgid(POSIX::getgid()); } $background = 1 if(!defined $background); $background = find_option('-X') ? 0 : $background; $loglevel = $background ? $INFO : $DEBUG if(!defined $loglevel); $loglevel = find_option('-v') ? $DEBUG : $loglevel; for (qw(start stop restart status)) { if( find_option( $_ ) ) { $action = $_; last; } } if($action eq "stop" or $action eq "status") { $background = 0; } if( Log::Log4perl->initialized() ) { DEBUG "Log4perl already initialized, doing nothing"; } elsif( $action eq "status" ) { Log::Log4perl->easy_init( $loglevel ); } elsif( $l4p_conf ) { Log::Log4perl->init( $l4p_conf ); } elsif( $logfile ) { my $levelstring = Log::Log4perl::Level::to_level( $loglevel ); Log::Log4perl->init(\ qq{ log4perl.logger = $levelstring, FileApp log4perl.appender.FileApp = Log::Log4perl::Appender::File log4perl.appender.FileApp.filename = $logfile log4perl.appender.FileApp.owner = $as_user # this umask is only temporary log4perl.appender.FileApp.umask = 0133 log4perl.appender.FileApp.layout = PatternLayout log4perl.appender.FileApp.layout.ConversionPattern = %d %m%n }); } if(!$background) { DEBUG "Running in foreground"; } } ########################################### sub daemonize { ########################################### cmd_line_parse(); # Check beforehand so the user knows what's going on. if(! -w dirname($pidfile) or -f $pidfile and ! -w $pidfile) { my ($name,$passwd,$uid) = getpwuid($>); LOGDIE "$pidfile not writable by user $name"; } if($action eq "status") { exit status(); } if($action eq "stop" or $action eq "restart") { my $exit_code = LSB_NOT_RUNNING; if(-f $pidfile) { my $pid = pid_file_read(); if(kill 0, $pid) { kill $kill_sig, $pid; my $killed = 0; for (1..$kill_retries) { if(!kill 0, $pid) { INFO "Process $pid stopped successfully."; unlink $pidfile or die "Can't remove $pidfile ($!)"; $exit_code = LSB_OK; $killed++; last; } INFO "Process $pid still running, waiting ..."; sleep 1; } if(! $killed) { ERROR "Process $pid still up, out of retries, giving up."; $exit_code = LSB_DEAD_PID_EXISTS; } } else { ERROR "Process $pid not running\n"; unlink $pidfile or die "Can't remove $pidfile ($!)"; $exit_code = LSB_NOT_RUNNING; } } else { ERROR "According to my pidfile, there's no instance ", "of me running."; $exit_code = LSB_NOT_RUNNING; } if($action eq "restart") { sleep 1; } else { exit $exit_code; } } if ( my $num = pid_file_process_running() ) { LOGWARN "Already running: $num (pidfile=$pidfile)\n"; exit ALREADY_RUNNING; } if( $background ) { detach( $as_user ); } elsif ($as_user) { id_switch(); } my $prev_sig = $SIG{__DIE__}; my $master_pid = $$; DEBUG "Defining die handler"; $SIG{__DIE__} = sub { DEBUG __PACKAGE__, " die handler triggered."; # In case we had a previously defined signal handler, call # it first and add ours to the end of the chain. $prev_sig->(@_) if ($prev_sig); if( $master_pid != $$ ) { # Verify that it's the main process calling the # handler and not a previously forked child. DEBUG "Die handler called for pid $$ but master pid is $master_pid"; } elsif( !defined $^S or $^S != 0 ) { # Make sure it's not an eval{} triggering the handler. DEBUG "Die handler called by eval. Ignored."; } else { DEBUG "Die handler removes pidfile $pidfile"; unlink $pidfile or warn "Cannot remove $pidfile"; } }; return 1; } ########################################### sub detach { ########################################### my($as_user) = @_; # [rt #75219] umask(0); # Make sure the child isn't killed when the user closes the # terminal session before the child detaches from the tty. $SIG{'HUP'} = 'IGNORE'; my $child = fork(); if(! defined $child ) { LOGDIE "Fork failed ($!)"; } if( $child ) { # parent doesn't do anything exit 0; } # Become the session leader of a new session, become the # process group leader of a new process group. POSIX::setsid(); if( defined $pidfile ) { INFO "Process ID is $$"; pid_file_write($$); INFO "Written to $pidfile"; } if($as_user) { id_switch(); } # close std file descriptors if(-e "/dev/null") { # On Unix, we want to point these file descriptors at /dev/null, # so that any libary routines that try to read form stdin or # write to stdout/err will have no effect (Stevens, APitUE, p. 426 # and [RT 51066]. open STDIN, '/dev/null'; open STDOUT, '>>/dev/null'; open STDERR, '>>/dev/null'; } else { close(STDIN); close(STDOUT); close(STDERR); } } ########################################### sub id_switch { ########################################### if($> == 0) { # If we're root, become user set as 'as_user' and the group in # 'as_group'. # Set the group first because it only works when still root my ($group,undef,$gid) = getgrnam($as_group); if(! defined $group) { LOGDIE "Cannot switch to group $as_group"; } POSIX::setgid($gid); my ($name,$passwd,$uid) = getpwnam($as_user); if(! defined $name) { LOGDIE "Cannot switch to user $as_user"; } POSIX::setuid( $uid ); } } ########################################### sub status { ########################################### # Define exit codes according to # http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html my $exit_code = LSB_UNKNOWN; print "Pid file: $pidfile\n"; if(-f $pidfile) { my $pid = pid_file_read(); my $running = process_running($pid); print "Pid in file: $pid\n"; print "Running: ", $running ? "yes" : "no", "\n"; if($running) { # see above $exit_code = LSB_OK; } else { # see above $exit_code = LSB_DEAD_PID_EXISTS; } } else { print "No pidfile found\n"; $exit_code = LSB_NOT_RUNNING; } if( proc_processtable_available() ) { my @cmdlines = processes_running_by_name( $appname ); print "Name match: ", scalar @cmdlines, "\n"; for(@cmdlines) { print " ", $_, "\n"; } } return $exit_code; } ########################################### sub process_running { ########################################### my($pid) = @_; my $rc = kill( 0, $pid ); if( $rc ) { # pseudo signal got delivered, process exists return 1; } elsif( $! == ESRCH ) { # process doesn't exist return 0; } elsif( $! == EPERM ) { # process does exist, but we don't have permission to # send the signal return 1; } # Weirdness ensued. return 0; } ########################################### sub processes_running_by_name { ########################################### my($name) = @_; require Proc::ProcessTable; $name = basename($name); my @procs = (); my $t = Proc::ProcessTable->new(); foreach my $p ( @{$t->table} ){ if($p->cmndline() =~ /\b\Q${name}\E\b/) { next if $p->pid() == $$; DEBUG "Match: ", $p->cmndline(); push @procs, $p->cmndline(); } } return @procs; } ########################################### sub appname { ########################################### my $appname = basename($0); # Make sure -T regards it as untainted now ($appname) = ($appname =~ /([\w-]+)/); return $appname; } ########################################### sub find_option { ########################################### my($opt, $has_arg) = @_; my $idx = 0; for my $argv (@ARGV) { if($argv eq $opt) { if( $has_arg ) { my @args = splice @ARGV, $idx, 2; return $args[1]; } else { return splice @ARGV, $idx, 1; } } $idx++; } return undef; } ########################################### sub def_or { ########################################### if(! defined $_[0]) { $_[0] = $_[1]; } } ########################################### sub pid_file_write { ########################################### my($pid) = @_; sysopen FILE, $pidfile, O_RDWR|O_CREAT, 0644 or LOGDIE "Cannot open pidfile $pidfile"; flock FILE, LOCK_EX; seek(FILE, 0, 0); print FILE "$pid\n"; close FILE; } ########################################### sub pid_file_read { ########################################### open FILE, "<$pidfile" or LOGDIE "Cannot open pidfile $pidfile"; flock FILE, LOCK_SH; my $pid = ; chomp $pid if defined $pid; close FILE; $pid =~ /^(\d+)$/; # Untaint return $1; } ########################################### sub pid_file_process_running { ########################################### if(! -f $pidfile) { return undef; } my $pid = pid_file_read(); if(! $pid) { return undef; } if(process_running($pid)) { return $pid; } return undef; } ########################################### sub proc_processtable_available { ########################################### my $module = "Proc::ProcessTable"; eval "require $module;"; if( $@ ) { return 0; } return 1; } 1; __END__ =head1 NAME App::Daemon - Start an Application as a Daemon =head1 SYNOPSIS # Program: use App::Daemon qw( daemonize ); daemonize(); do_something_useful(); # your application # Then, in the shell: start application, # which returns immediately, but continues # to run do_something_useful() in the background $ app start $ # stop application $ app stop # start app in foreground (for testing) $ app -X # show if app is currently running $ app status =head1 DESCRIPTION C helps running an application as a daemon. The idea is that you prepend your script with the use App::Daemon qw( daemonize ); daemonize(); and 'daemonize' it that way. That means, that if you write use App::Daemon qw( daemonize ); daemonize(); sleep(10); you'll get a script that, when called from the command line, returns immediatly, but continues to run as a daemon for 10 seconds. Along with the common features offered by similar modules on CPAN, it =over 4 =item * supports logging with Log4perl: In background mode, it logs to a logfile. In foreground mode, log messages go directly to the screen. =item * detects if another instance is already running and ends itself automatically in this case. =item * shows with the 'status' command if an instance is already running and which PID it has: ./my-app status Pid file: ./tt.pid Pid in file: 14914 Running: no Name match: 0 =back =head2 Actions C recognizes three different actions: =over 4 =item my-app start will start up the daemon. "start" itself is optional, as this is the default action, $ ./my-app $ will also run the 'start' action. By default, it will create a pid file and a log file in the current directory (named C and C. To change these locations, see the C<-l> and C<-p> options. If the -X option is given, the program is running in foreground mode for testing purposes: $ ./my-app -X ... =item stop will find the daemon's PID in the pidfile and send it a SIGTERM signal. It will verify $App::Daemon::kill_retries times if the process is still alive, with 1-second sleeps in between. To have App::Daemon send a different signal than SIGTERM (e.g., SIGINT), set use POSIX; $App::Daemon::kill_sig = SIGINT; Note that his requires the numerial value (SIGINT via POSIX.pm), not a string like "SIGINT". =item status will print out diagnostics on what the status of the daemon is. Typically, the output looks like this: Pid file: ./tt.pid Pid in file: 15562 Running: yes Name match: 1 /usr/local/bin/perl -w test.pl This indicates that the pidfile says that the daemon has PID 15562 and that a process with this PID is actually running at this moment. Also, a name grep on the process name in the process table results in 1 match, according to the output above. Note that the name match is unreliable, as it just looks for a command line that looks approximately like the script itself. So if the script is C, it will match lines like "perl -w test.pl" or "perl test.pl start", but unfortunately also lines like "vi test.pl". If the process is no longer running, the status output might look like this instead: Pid file: ./tt.pid Pid in file: 14914 Running: no Name match: 0 The status commands exit code complies with http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html and returns 0: if the process is up and running 1: the process is dead but the pid file still exists 3: the process is not running These constants are defined within App::Daemon to help writing test scripts: use constant LSB_OK => 0; use constant LSB_DEAD_PID_EXISTS => 1; use constant LSB_DEAD_LOCK_EXISTS => 2; use constant LSB_NOT_RUNNING => 3; use constant LSB_UNKNOWN => 4; use constant ALREADY_RUNNING => 150; =back =head2 Command Line Options =over 4 =item -X Foreground mode. Log messages go to the screen. =item -l logfile Logfile to send Log4perl messages to in background mode. Defaults to C<./[appname].log>. Note that having a logfile in the current directory doesn't make sense except for testing environments, make sure to set this to somewhere within C for production use. =item -u as_user User to run as if started as root. Defaults to 'nobody'. =item -g as_group Group to run as if started as root. Defaults to 'nogroup'. =item -l4p l4p.conf Path to Log4perl configuration file. Note that in this case the -v option will be ignored. =item -p pidfile Where to save the pid of the started process. Defaults to C<./[appname].pid>. Note that having a pidfile in the current directory doesn't make sense except for testing environments, make sure to set this to somewhere within C for production use. =item -v Increase default Log4perl verbosity from $INFO to $DEBUG. Note that this option will be ignored if Log4perl is initialized independently or if a user-provided Log4perl configuration file is used. =back =head2 Setting Parameters Instead of setting paramteters like the logfile, the pidfile etc. from the command line, you can directly manipulate App::Daemon's global variables: use App::Daemon qw(daemonize); $App::Daemon::logfile = "mylog.log"; $App::Daemon::pidfile = "mypid.log"; $App::Daemon::l4p_conf = "myconf.l4p"; $App::Daemon::background = 1; $App::Daemon::as_user = "nobody"; $App::Daemon::as_group = "nogroup"; use Log::Log4perl qw(:levels); $App::Daemon::loglevel = $DEBUG; daemonize(); =head2 Application-specific command line options If an application needs additional command line options, it can use whatever is not yet taken by App::Daemon, as described previously in the L section. However, it needs to make sure to remove these additional options before calling daemonize(), or App::Daemon will complain. To do this, create an options hash C<%opts> and store application-specific options in there while removing them from @ARGV: my %opts = (); for my $opt (qw(-k -P -U)) { my $v = App::Daemon::find_option( $opt, 1 ); $opts{ $opt } = $v if defined $v; } After this, options C<-k>, C<-P>, and C<-U> will have disappeared from @ARGV and can be checked in C<$opts{k}>, C<$opts{P}>, and C<$opts{U}>. =head2 Gotchas =over 4 =item Log File Permissions If the process is started as root but later drops permissions to a non-priviledged user for security purposes, it's important that logfiles are created with correct permissions. If they're created as root when the program starts, the non-priviledged user won't be able to write to them later (unless they're world-writable which is also undesirable because of security concerns). The best strategy to handle this case is to specify the non-priviledged user as the owner of the logfile in the Log4perl configuration: log4perl.logger = DEBUG, FileApp log4perl.appender.FileApp = Log::Log4perl::Appender::File log4perl.appender.FileApp.filename = /var/log/foo-app.log log4perl.appender.FileApp.owner = nobody log4perl.appender.FileApp.layout = PatternLayout log4perl.appender.FileApp.layout.ConversionPattern = %d %m%n This way, the process starts up as root, creates the logfile if it doesn't exist yet, and changes its owner to 'nobody'. Later, when the process assumes the identity of the user 'nobody', it will continue to write to the logfile without permission problems. =item Log4perl Categories Note that App::Daemon is logging messages in Log4perl's App::Daemon namespace. So, if you're running your own Log4perl configuration and define a root logger like log4perl.logger=DEBUG, appendername then App::Daemon's messages will bubble up to it and be visible in the output. If you don't want that, either use log4perl.logger.My.App=DEBUG, appendername to explicitly enable verbose logging in your application namespace (and not in App::Daemon's) or tone down App::Daemon's verbosity via log4perl.logger.App.Daemon=ERROR explicitly. If you want more details on basic Log4perl features, check out the L manual page. =back =head2 Detach only If you want to create a daemon without the fancy command line parsing and PID file checking functions, use use App::Daemon qw(detach); detach(); # ... some code here This will fork a child, terminate the parent and detach the child from the terminal. Issued from the command line, the program above will continue to run the code following the detach() call but return to the shell prompt immediately. =head1 AUTHOR 2008, Mike Schilli =head1 LICENSE Copyright 2008-2012 by Mike Schilli, all rights reserved. This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself. App-Daemon-0.22/eg/000755 040416 000024 00000000000 12410731226 014713 5ustar00mschillistaff000000 000000 App-Daemon-0.22/Makefile.PL000644 040416 000024 00000002054 12410321567 016276 0ustar00mschillistaff000000 000000 use ExtUtils::MakeMaker; # See lib/ExtUtils/MakeMaker.pm for details of how to influence # the contents of the Makefile that is written. my $meta_merge = { META_MERGE => { resources => { repository => 'http://github.com/mschilli/app-daemon', }, } }; if( $^O eq "MSWin32" ) { die "$^O: OS unsupported"; } WriteMakefile( NAME => 'App::Daemon', VERSION_FROM => 'Daemon.pm', # finds $VERSION PREREQ_PM => { Log::Log4perl => "1.0", File::Pid => 0, Getopt::Std => 0, Pod::Usage => 0, File::Basename => 0, Test::More => 0, File::Temp => 0, Sysadm::Install => 0.37, }, # e.g., Module::Name => 1.1 $ExtUtils::MakeMaker::VERSION >= 6.50 ? (%$meta_merge) : (), ($] >= 5.005 ? ## Add these new keywords supported since 5.005 (ABSTRACT_FROM => 'Daemon.pm', # retrieve abstract from module AUTHOR => 'Mike Schilli ') : ()), ); App-Daemon-0.22/MANIFEST000644 040416 000024 00000000571 12410731227 015455 0ustar00mschillistaff000000 000000 .licensizer.yml adm/release Changes Daemon.pm eg/test-daemon eg/test-detach eg/test-fork-daemon Makefile.PL MANIFEST MANIFEST.SKIP README t/001Basic.t t/002Params.t t/003CmdLine.t t/004Pidfile.t t/005Detach.t META.yml Module YAML meta-data (added by MakeMaker) META.json Module JSON meta-data (added by MakeMaker) App-Daemon-0.22/MANIFEST.SKIP000644 040416 000024 00000000107 12073646363 016230 0ustar00mschillistaff000000 000000 \.git \.gz$ Makefile$ Makefile.old \.bak$ ^pm_to_blib$ ^blib/ MYMETA.* App-Daemon-0.22/META.json000644 040416 000024 00000002323 12410731227 015742 0ustar00mschillistaff000000 000000 { "abstract" : "Start an Application as a Daemon", "author" : [ "Mike Schilli " ], "dynamic_config" : 1, "generated_by" : "ExtUtils::MakeMaker version 6.6302, CPAN::Meta::Converter version 2.130880", "license" : [ "unknown" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : "2" }, "name" : "App-Daemon", "no_index" : { "directory" : [ "t", "inc" ] }, "prereqs" : { "build" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "configure" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "runtime" : { "requires" : { "File::Basename" : "0", "File::Pid" : "0", "File::Temp" : "0", "Getopt::Std" : "0", "Log::Log4perl" : "1.0", "Pod::Usage" : "0", "Sysadm::Install" : "0.37", "Test::More" : "0" } } }, "release_status" : "stable", "resources" : { "repository" : { "url" : "http://github.com/mschilli/app-daemon" } }, "version" : "0.22" } App-Daemon-0.22/META.yml000644 040416 000024 00000001257 12410731226 015576 0ustar00mschillistaff000000 000000 --- abstract: 'Start an Application as a Daemon' author: - 'Mike Schilli ' build_requires: ExtUtils::MakeMaker: 0 configure_requires: ExtUtils::MakeMaker: 0 dynamic_config: 1 generated_by: 'ExtUtils::MakeMaker version 6.6302, CPAN::Meta::Converter version 2.130880' license: unknown meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: 1.4 name: App-Daemon no_index: directory: - t - inc requires: File::Basename: 0 File::Pid: 0 File::Temp: 0 Getopt::Std: 0 Log::Log4perl: 1.0 Pod::Usage: 0 Sysadm::Install: 0.37 Test::More: 0 resources: repository: http://github.com/mschilli/app-daemon version: 0.22 App-Daemon-0.22/README000644 040416 000024 00000023701 12410731226 015203 0ustar00mschillistaff000000 000000 ###################################################################### App::Daemon 0.22 ###################################################################### NAME App::Daemon - Start an Application as a Daemon SYNOPSIS # Program: use App::Daemon qw( daemonize ); daemonize(); do_something_useful(); # your application # Then, in the shell: start application, # which returns immediately, but continues # to run do_something_useful() in the background $ app start $ # stop application $ app stop # start app in foreground (for testing) $ app -X # show if app is currently running $ app status DESCRIPTION "App::Daemon" helps running an application as a daemon. The idea is that you prepend your script with the use App::Daemon qw( daemonize ); daemonize(); and 'daemonize' it that way. That means, that if you write use App::Daemon qw( daemonize ); daemonize(); sleep(10); you'll get a script that, when called from the command line, returns immediatly, but continues to run as a daemon for 10 seconds. Along with the common features offered by similar modules on CPAN, it * supports logging with Log4perl: In background mode, it logs to a logfile. In foreground mode, log messages go directly to the screen. * detects if another instance is already running and ends itself automatically in this case. * shows with the 'status' command if an instance is already running and which PID it has: ./my-app status Pid file: ./tt.pid Pid in file: 14914 Running: no Name match: 0 Actions "App::Daemon" recognizes three different actions: my-app start will start up the daemon. "start" itself is optional, as this is the default action, $ ./my-app $ will also run the 'start' action. By default, it will create a pid file and a log file in the current directory (named "my-app.pid" and "my-app.log". To change these locations, see the "-l" and "-p" options. If the -X option is given, the program is running in foreground mode for testing purposes: $ ./my-app -X ... stop will find the daemon's PID in the pidfile and send it a SIGTERM signal. It will verify $App::Daemon::kill_retries times if the process is still alive, with 1-second sleeps in between. To have App::Daemon send a different signal than SIGTERM (e.g., SIGINT), set use POSIX; $App::Daemon::kill_sig = SIGINT; Note that his requires the numerial value (SIGINT via POSIX.pm), not a string like "SIGINT". status will print out diagnostics on what the status of the daemon is. Typically, the output looks like this: Pid file: ./tt.pid Pid in file: 15562 Running: yes Name match: 1 /usr/local/bin/perl -w test.pl This indicates that the pidfile says that the daemon has PID 15562 and that a process with this PID is actually running at this moment. Also, a name grep on the process name in the process table results in 1 match, according to the output above. Note that the name match is unreliable, as it just looks for a command line that looks approximately like the script itself. So if the script is "test.pl", it will match lines like "perl -w test.pl" or "perl test.pl start", but unfortunately also lines like "vi test.pl". If the process is no longer running, the status output might look like this instead: Pid file: ./tt.pid Pid in file: 14914 Running: no Name match: 0 The status commands exit code complies with http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html and returns 0: if the process is up and running 1: the process is dead but the pid file still exists 3: the process is not running These constants are defined within App::Daemon to help writing test scripts: use constant LSB_OK => 0; use constant LSB_DEAD_PID_EXISTS => 1; use constant LSB_DEAD_LOCK_EXISTS => 2; use constant LSB_NOT_RUNNING => 3; use constant LSB_UNKNOWN => 4; use constant ALREADY_RUNNING => 150; Command Line Options -X Foreground mode. Log messages go to the screen. -l logfile Logfile to send Log4perl messages to in background mode. Defaults to "./[appname].log". Note that having a logfile in the current directory doesn't make sense except for testing environments, make sure to set this to somewhere within "/var/log" for production use. -u as_user User to run as if started as root. Defaults to 'nobody'. -g as_group Group to run as if started as root. Defaults to 'nogroup'. -l4p l4p.conf Path to Log4perl configuration file. Note that in this case the -v option will be ignored. -p pidfile Where to save the pid of the started process. Defaults to "./[appname].pid". Note that having a pidfile in the current directory doesn't make sense except for testing environments, make sure to set this to somewhere within "/var/run" for production use. -v Increase default Log4perl verbosity from $INFO to $DEBUG. Note that this option will be ignored if Log4perl is initialized independently or if a user-provided Log4perl configuration file is used. Setting Parameters Instead of setting paramteters like the logfile, the pidfile etc. from the command line, you can directly manipulate App::Daemon's global variables: use App::Daemon qw(daemonize); $App::Daemon::logfile = "mylog.log"; $App::Daemon::pidfile = "mypid.log"; $App::Daemon::l4p_conf = "myconf.l4p"; $App::Daemon::background = 1; $App::Daemon::as_user = "nobody"; $App::Daemon::as_group = "nogroup"; use Log::Log4perl qw(:levels); $App::Daemon::loglevel = $DEBUG; daemonize(); Application-specific command line options If an application needs additional command line options, it can use whatever is not yet taken by App::Daemon, as described previously in the "Command Line Options" section. However, it needs to make sure to remove these additional options before calling daemonize(), or App::Daemon will complain. To do this, create an options hash %opts and store application-specific options in there while removing them from @ARGV: my %opts = (); for my $opt (qw(-k -P -U)) { my $v = App::Daemon::find_option( $opt, 1 ); $opts{ $opt } = $v if defined $v; } After this, options "-k", "-P", and "-U" will have disappeared from @ARGV and can be checked in $opts{k}, $opts{P}, and $opts{U}. Gotchas Log File Permissions If the process is started as root but later drops permissions to a non-priviledged user for security purposes, it's important that logfiles are created with correct permissions. If they're created as root when the program starts, the non-priviledged user won't be able to write to them later (unless they're world-writable which is also undesirable because of security concerns). The best strategy to handle this case is to specify the non-priviledged user as the owner of the logfile in the Log4perl configuration: log4perl.logger = DEBUG, FileApp log4perl.appender.FileApp = Log::Log4perl::Appender::File log4perl.appender.FileApp.filename = /var/log/foo-app.log log4perl.appender.FileApp.owner = nobody log4perl.appender.FileApp.layout = PatternLayout log4perl.appender.FileApp.layout.ConversionPattern = %d %m%n This way, the process starts up as root, creates the logfile if it doesn't exist yet, and changes its owner to 'nobody'. Later, when the process assumes the identity of the user 'nobody', it will continue to write to the logfile without permission problems. Log4perl Categories Note that App::Daemon is logging messages in Log4perl's App::Daemon namespace. So, if you're running your own Log4perl configuration and define a root logger like log4perl.logger=DEBUG, appendername then App::Daemon's messages will bubble up to it and be visible in the output. If you don't want that, either use log4perl.logger.My.App=DEBUG, appendername to explicitly enable verbose logging in your application namespace (and not in App::Daemon's) or tone down App::Daemon's verbosity via log4perl.logger.App.Daemon=ERROR explicitly. If you want more details on basic Log4perl features, check out the Log::Log4perl manual page. Detach only If you want to create a daemon without the fancy command line parsing and PID file checking functions, use use App::Daemon qw(detach); detach(); # ... some code here This will fork a child, terminate the parent and detach the child from the terminal. Issued from the command line, the program above will continue to run the code following the detach() call but return to the shell prompt immediately. AUTHOR 2008, Mike Schilli LICENSE Copyright 2008-2012 by Mike Schilli, all rights reserved. This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself. App-Daemon-0.22/t/000755 040416 000024 00000000000 12410731226 014563 5ustar00mschillistaff000000 000000 App-Daemon-0.22/t/001Basic.t000644 040416 000024 00000001310 12073646363 016221 0ustar00mschillistaff000000 000000 use Test::More tests => 3; use App::Daemon qw(daemonize cmd_line_parse); use File::Temp qw(tempfile); use Fcntl qw/:flock/; use Log::Log4perl qw(:easy); Log::Log4perl->easy_init({ level => $DEBUG, layout => "%F-%L> %m%n" }); my($fh, $tempfile) = tempfile(); # Turdix locks temp files, so unlock them just in case flock $fh, LOCK_UN; ok(1, "loaded ok"); open(OLDERR, ">&STDERR"); open(STDERR, ">$tempfile"); @ARGV = ("-X"); daemonize(); close STDERR; open(STDERR, ">&OLDERR"); close OLDERR; ok(1, "Running in foreground with -X"); open FILE, "<$tempfile" or die "Cannot open tempfile $tempfile ($!)"; my $data = join '', ; close FILE; like($data, qr/Running in foreground/, "log message"); App-Daemon-0.22/t/002Params.t000644 040416 000024 00000001247 12073646363 016435 0ustar00mschillistaff000000 000000 use Test::More tests => 3; use App::Daemon qw(daemonize cmd_line_parse); use File::Temp qw(tempfile); use Fcntl qw/:flock/; use Log::Log4perl qw(:easy); Log::Log4perl->easy_init({ level => $DEBUG, layout => "%F-%L> %m%n" }); my($fh, $tempfile) = tempfile(); # Turdix locks temp files, so unlock them just in case flock $fh, LOCK_UN; ok(1, "loaded ok"); open(OLDERR, ">&STDERR"); open(STDERR, ">$tempfile"); @ARGV = (); $App::Daemon::background = 0; daemonize(); close STDERR; open(STDERR, ">&OLDERR"); close OLDERR; ok(1, "running in foreground"); open FILE, "<$tempfile"; my $data = join '', ; close FILE; like($data, qr/Running in foreground/, "log message"); App-Daemon-0.22/t/003CmdLine.t000644 040416 000024 00000002142 12073646363 016521 0ustar00mschillistaff000000 000000 # launch app-daemon use File::Temp qw(tempdir); use FindBin qw($Bin); use Sysadm::Install qw(:all); use Test::More; use App::Daemon; use Log::Log4perl qw(:easy); # Log::Log4perl->easy_init($DEBUG); plan tests => 6; my $tempdir = tempdir( CLEANUP => 1 ); my ( $stdout, $stderr, $rc ); my @cmdline = ( $^X, "-I$Bin/../blib/lib", "$Bin/../eg/test-daemon", "-l", "$tempdir/log", "-p", "$tempdir/pid" ); # start sleep daemon ( $stdout, $stderr, $rc ) = tap @cmdline, "start"; is $rc, 0, "app start"; # start once again ( $stdout, $stderr, $rc ) = tap @cmdline, "start"; is $rc>>8, App::Daemon::ALREADY_RUNNING, "app start again"; # check status ( $stdout, $stderr, $rc ) = tap @cmdline, "status"; is $rc>>8, App::Daemon::LSB_OK, "status started"; # stop daemon ( $stdout, $stderr, $rc ) = tap @cmdline, "stop"; is $rc, 0, "app stop"; # stop daemon again ( $stdout, $stderr, $rc ) = tap @cmdline, "stop"; is $rc>>8, App::Daemon::LSB_NOT_RUNNING, "app stop again"; # check status ( $stdout, $stderr, $rc ) = tap @cmdline, "status"; is $rc>>8, App::Daemon::LSB_NOT_RUNNING, "status stopped"; App-Daemon-0.22/t/004Pidfile.t000644 040416 000024 00000002310 12410322757 016551 0ustar00mschillistaff000000 000000 use warnings; use strict; use Test::More tests => 5; use File::Temp qw( tempdir ); use Sysadm::Install qw(:all); use FindBin qw( $Bin ); use App::Daemon qw(daemonize cmd_line_parse); use Fcntl qw/:flock/; use Log::Log4perl qw(:easy); Log::Log4perl->easy_init({ level => $DEBUG, layout => "%F-%L> %m%n" }); my $tempdir = tempdir( CLEANUP => 1 ); my ( $stdout, $stderr, $rc ); my $pidfile = "$tempdir/pid"; my $logfile = "$tempdir/log"; my @cmdline = ( $^X, "-I$Bin/../blib/lib", "$Bin/../eg/test-fork-daemon", "-l", $logfile, "-p", $pidfile, "-v" ); ( $stdout, $stderr, $rc ) = tap @cmdline, "start"; is $rc, 0, "app start"; # wait until process is up while( 1 ) { DEBUG "Checking for logfile"; if( -f $logfile ) { ok 1, "daemon started"; last; } sleep 1; } # wait until child exits while( 1 ) { my $data = slurp $logfile; DEBUG "Checking logfile for 'waitpid done': [$data]"; if( $data =~ /parent waitpid done/ ) { ok 1, "parent waitpid done"; last; } sleep 1; } ok -f $pidfile, "pidfile still exists after child exit"; ( $stdout, $stderr, $rc ) = tap @cmdline, "stop"; is $rc, 0, "app stop"; # print slurp( $logfile ); App-Daemon-0.22/t/005Detach.t000644 040416 000024 00000001167 12410321567 016375 0ustar00mschillistaff000000 000000 # launch app-daemon use File::Temp qw(tempfile); use FindBin qw($Bin); use Sysadm::Install qw(:all); use Test::More; use App::Daemon; use Log::Log4perl qw(:easy); # Log::Log4perl->easy_init($DEBUG); plan tests => 2; my( $fh, $tmpfile ) = tempfile( UNLINK => 1 ); my ( $stdout, $stderr, $rc ); my @cmdline = ( $^X, "-I$Bin/../blib/lib", "$Bin/../eg/test-detach", $tmpfile); ( $stdout, $stderr, $rc ) = tap @cmdline; is $rc, 0, "detached process started"; for( 1 .. 10 ) { my $data = slurp $tmpfile; if( $data =~ /Done/ ) { ok 1, "detached process finished"; last; } sleep 1; } App-Daemon-0.22/eg/test-daemon000755 040416 000024 00000000160 12073646363 017072 0ustar00mschillistaff000000 000000 #!/usr/local/bin/perl -w use strict; # Program: use App::Daemon qw( daemonize ); daemonize(); sleep(100); App-Daemon-0.22/eg/test-detach000755 040416 000024 00000000373 12410321567 017054 0ustar00mschillistaff000000 000000 #!/usr/local/bin/perl -w use strict; my( $done_file ) = @ARGV; die "usage: $0 done_file" if !defined $done_file; # Program: use App::Daemon qw( detach ); detach(); sleep(1); open FILE, ">", $done_file or die; print FILE "Done\n"; close FILE; App-Daemon-0.22/eg/test-fork-daemon000755 040416 000024 00000000622 12073646363 020034 0ustar00mschillistaff000000 000000 #!/usr/local/bin/perl -w use strict; use Log::Log4perl qw(:easy); # Program: use App::Daemon qw( daemonize ); daemonize(); my $pid = fork(); if( !defined $pid ) { die "fork failed"; } if( $pid ) { # parent } else { # child INFO "child exits"; die "Aiieeeeeh"; } waitpid $pid, 0; INFO "parent waitpid done"; INFO "parent sleep"; sleep(100); INFO "parent exiting"; App-Daemon-0.22/adm/release000755 040416 000024 00000000320 12073646363 016436 0ustar00mschillistaff000000 000000 #!/usr/local/bin/perl use warnings; use strict; # Available at http://perlmeister.com/scripts use lib "$ENV{HOME}/perl-modules"; use ModDevUtils; system("licensizer"); ModDevUtils::release(0) or exit 0;