| App::Daemon - Start an Application as a Daemon |
App::Daemon - Start an Application as a Daemon
# 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
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: /tmp/tt.pid
Pid in file: 14914
Running: no
Name match: 0
App::Daemon recognizes three different actions:
will start up the daemon. "start" itself is optional, as this is the default action,
$ ./my-app
will also run the 'start' action. If the -X option is given, the program is run in foreground mode for testing purposes.
will find the daemon's PID in the pidfile and send it a kill signal. It won't verify if this actually shut down the daemon or if it's immune to the kill signal.
will print out diagnostics on what the status of the daemon is. Typically, the output look like this:
Pid file: /tmp/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: /tmp/tt.pid
Pid in file: 14914
Running: no
Name match: 0
Foreground mode. Log messages go to the screen.
Logfile to send Log4perl messages to in background mode. Defaults
to /tmp/[appname].log.
User to run as if started as root. Defaults to 'nobody'.
Path to Log4perl configuration file.
Where to save the pid of the started process.
Defaults to /tmp/[appname].pid.
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";
use Log::Log4perl qw(:levels);
$App::Daemon::loglevel = $DEBUG;
daemonize();
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}.
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.
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.
Mike Schilli, cpan@perlmeister.com
Copyright (C) 2008 by Mike Schilli
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.
| App::Daemon - Start an Application as a Daemon |