###################################################################### 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 cpan@perlmeister.com

mschilli / app-daemon

readme

Program: