.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Daemon 3pm"
.TH Daemon 3pm "2018-07-08" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
App::Daemon \- Start an Application as a Daemon
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&     # 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
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`App::Daemon\*(C'\fR helps running an application as a daemon. The idea is
that you prepend your script with the
.PP
.Vb 2
\&    use App::Daemon qw( daemonize ); 
\&    daemonize();
.Ve
.PP
and 'daemonize' it that way. That means, that if you write
.PP
.Vb 1
\&    use App::Daemon qw( daemonize ); 
\&
\&    daemonize();
\&    sleep(10);
.Ve
.PP
you'll get a script that, when called from the command line, returns 
immediately, but continues to run as a daemon for 10 seconds.
.PP
Along with the
common features offered by similar modules on \s-1CPAN,\s0 it
.IP "\(bu" 4
supports logging with Log4perl: In background mode, it logs to a 
logfile. In foreground mode, log messages go directly to the screen.
.IP "\(bu" 4
detects if another instance is already running and ends itself 
automatically in this case.
.IP "\(bu" 4
shows with the 'status' command if an instance is already running
and which \s-1PID\s0 it has:
.Sp
.Vb 5
\&    ./my\-app status
\&    Pid file:    ./tt.pid
\&    Pid in file: 14914
\&    Running:     no
\&    Name match:  0
.Ve
.SS "Actions"
.IX Subsection "Actions"
\&\f(CW\*(C`App::Daemon\*(C'\fR recognizes three different actions:
.IP "my-app start" 4
.IX Item "my-app start"
will start up the daemon. \*(L"start\*(R" itself is optional, as this is the 
default action,
.Sp
.Vb 2
\&        $ ./my\-app
\&        $
.Ve
.Sp
will also run the 'start' action. By default, it will create a pid file
and a log file in the current directory
(named \f(CW\*(C`my\-app.pid\*(C'\fR and \f(CW\*(C`my\-app.log\*(C'\fR. To change these locations, see
the \f(CW\*(C`\-l\*(C'\fR and \f(CW\*(C`\-p\*(C'\fR options.
.Sp
If the \-X option is given, the program
is running in foreground mode for testing purposes:
.Sp
.Vb 2
\&        $ ./my\-app \-X
\&        ...
.Ve
.IP "stop" 4
.IX Item "stop"
will find the daemon's \s-1PID\s0 in the pidfile and send it a \s-1SIGTERM\s0 signal. It
will verify \f(CW$App::Daemon::kill_retries\fR times if the process is still alive,
with 1\-second sleeps in between.
.Sp
To have App::Daemon send a different signal than \s-1SIGTERM\s0 (e.g., \s-1SIGINT\s0), set
.Sp
.Vb 2
\&    use POSIX;
\&    $App::Daemon::kill_sig = SIGINT;
.Ve
.Sp
Note that his requires the numerial value (\s-1SIGINT\s0 via \s-1POSIX\s0.pm), not a
string like \*(L"\s-1SIGINT\*(R".\s0
.IP "status" 4
.IX Item "status"
will print out diagnostics on what the status of the daemon is. Typically,
the output looks like this:
.Sp
.Vb 5
\&    Pid file:    ./tt.pid
\&    Pid in file: 15562
\&    Running:     yes
\&    Name match:  1
\&        /usr/local/bin/perl \-w test.pl
.Ve
.Sp
This indicates that the pidfile says that the daemon has \s-1PID 15562\s0 and
that a process with this \s-1PID\s0 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.
.Sp
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
\&\f(CW\*(C`test.pl\*(C'\fR, it will match lines like \*(L"perl \-w test.pl\*(R" or 
\&\*(L"perl test.pl start\*(R", but unfortunately also lines like 
\&\*(L"vi test.pl\*(R".
.Sp
If the process is no longer running, the status output might look like
this instead:
.Sp
.Vb 4
\&    Pid file:    ./tt.pid
\&    Pid in file: 14914
\&    Running:     no
\&    Name match:  0
.Ve
.Sp
The status commands exit code complies with
.Sp
.Vb 1
\&    http://refspecs.freestandards.org/LSB_3.1.1/LSB\-Core\-generic/LSB\-Core\-generic/iniscrptact.html
.Ve
.Sp
and returns
.Sp
.Vb 3
\&    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
.Ve
.Sp
These constants are defined within App::Daemon to help writing test
scripts:
.Sp
.Vb 6
\&    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;
.Ve
.SS "Command Line Options"
.IX Subsection "Command Line Options"
.IP "\-X" 4
.IX Item "-X"
Foreground mode. Log messages go to the screen.
.IP "\-l logfile" 4
.IX Item "-l logfile"
Logfile to send Log4perl messages to in background mode. Defaults
to \f(CW\*(C`./[appname].log\*(C'\fR. 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 \f(CW\*(C`/var/log\*(C'\fR for production use.
.IP "\-u as_user" 4
.IX Item "-u as_user"
User to run as if started as root. Defaults to 'nobody'.
.IP "\-g as_group" 4
.IX Item "-g as_group"
Group to run as if started as root.  Defaults to 'nogroup'.
.IP "\-l4p l4p.conf" 4
.IX Item "-l4p l4p.conf"
Path to Log4perl configuration file. Note that in this case the \-v option 
will be ignored.
.IP "\-p pidfile" 4
.IX Item "-p pidfile"
Where to save the pid of the started process.
Defaults to \f(CW\*(C`./[appname].pid\*(C'\fR.
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 \f(CW\*(C`/var/run\*(C'\fR for production use.
.IP "\-v" 4
.IX Item "-v"
Increase default Log4perl verbosity from \f(CW$INFO\fR to \f(CW$DEBUG\fR. Note that this
option will be ignored if Log4perl is initialized independently or if
a user-provided Log4perl configuration file is used.
.SS "Setting Parameters"
.IX Subsection "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:
.PP
.Vb 1
\&    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();
.Ve
.SS "Application-specific command line options"
.IX Subsection "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"Command Line Options\*(R" section.
.PP
However, it needs to make sure to remove these additional options before
calling \fIdaemonize()\fR, or App::Daemon will complain. To do this, create 
an options hash \f(CW%opts\fR and store application-specific options in there
while removing them from \f(CW@ARGV:\fR
.PP
.Vb 1
\&    my %opts = ();
\&
\&    for my $opt (qw(\-k \-P \-U)) {
\&        my $v = App::Daemon::find_option( $opt, 1 );
\&        $opts{ $opt } = $v if defined $v;
\&    }
.Ve
.PP
After this, options \f(CW\*(C`\-k\*(C'\fR, \f(CW\*(C`\-P\*(C'\fR, and \f(CW\*(C`\-U\*(C'\fR will have disappeared from
\&\f(CW@ARGV\fR and can be checked in \f(CW$opts{k}\fR, \f(CW$opts{P}\fR, and \f(CW$opts{U}\fR.
.SS "Gotchas"
.IX Subsection "Gotchas"
.IP "Log File Permissions" 4
.IX 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.
.Sp
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).
.Sp
The best strategy to handle this case is to specify the non-priviledged
user as the owner of the logfile in the Log4perl configuration:
.Sp
.Vb 6
\&    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
.Ve
.Sp
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.
.IP "Log4perl Categories" 4
.IX 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
.Sp
.Vb 1
\&    log4perl.logger=DEBUG, appendername
.Ve
.Sp
then App::Daemon's messages will bubble up to it and be visible in
the output. If you don't want that, either use
.Sp
.Vb 1
\&    log4perl.logger.My.App=DEBUG, appendername
.Ve
.Sp
to explicitly enable verbose logging in your application namespace
(and not in App::Daemon's) or tone down App::Daemon's verbosity via
.Sp
.Vb 1
\&    log4perl.logger.App.Daemon=ERROR
.Ve
.Sp
explicitly. If you want more details on basic Log4perl features,
check out the Log::Log4perl manual page.
.SS "Detach only"
.IX Subsection "Detach only"
If you want to create a daemon without the fancy command line parsing
and \s-1PID\s0 file checking functions, use
.PP
.Vb 3
\&    use App::Daemon qw(detach);
\&    detach();
\&    # ... some code here
.Ve
.PP
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 \fIdetach()\fR call but return to the
shell prompt immediately.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 1
\&    2008, Mike Schilli <cpan@perlmeister.com>
.Ve
.SH "LICENSE"
.IX Header "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.