Provided by: libapp-daemon-perl_0.20-1_all bug

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'.

       -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";

           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>

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.