| 1 |
###################################################################### |
| 2 |
App::Daemon 0.22 |
| 3 |
###################################################################### |
| 4 |
|
| 5 |
NAME |
| 6 |
App::Daemon - Start an Application as a Daemon |
| 7 |
|
| 8 |
SYNOPSIS |
| 9 |
# Program: |
| 10 |
use App::Daemon qw( daemonize ); |
| 11 |
daemonize(); |
| 12 |
do_something_useful(); # your application |
| 13 |
|
| 14 |
# Then, in the shell: start application, |
| 15 |
# which returns immediately, but continues |
| 16 |
# to run do_something_useful() in the background |
| 17 |
$ app start |
| 18 |
$ |
| 19 |
|
| 20 |
# stop application |
| 21 |
$ app stop |
| 22 |
|
| 23 |
# start app in foreground (for testing) |
| 24 |
$ app -X |
| 25 |
|
| 26 |
# show if app is currently running |
| 27 |
$ app status |
| 28 |
|
| 29 |
DESCRIPTION |
| 30 |
"App::Daemon" helps running an application as a daemon. The idea is that |
| 31 |
you prepend your script with the |
| 32 |
|
| 33 |
use App::Daemon qw( daemonize ); |
| 34 |
daemonize(); |
| 35 |
|
| 36 |
and 'daemonize' it that way. That means, that if you write |
| 37 |
|
| 38 |
use App::Daemon qw( daemonize ); |
| 39 |
|
| 40 |
daemonize(); |
| 41 |
sleep(10); |
| 42 |
|
| 43 |
you'll get a script that, when called from the command line, returns |
| 44 |
immediatly, but continues to run as a daemon for 10 seconds. |
| 45 |
|
| 46 |
Along with the common features offered by similar modules on CPAN, it |
| 47 |
|
| 48 |
* supports logging with Log4perl: In background mode, it logs to a |
| 49 |
logfile. In foreground mode, log messages go directly to the screen. |
| 50 |
|
| 51 |
* detects if another instance is already running and ends itself |
| 52 |
automatically in this case. |
| 53 |
|
| 54 |
* shows with the 'status' command if an instance is already running |
| 55 |
and which PID it has: |
| 56 |
|
| 57 |
./my-app status |
| 58 |
Pid file: ./tt.pid |
| 59 |
Pid in file: 14914 |
| 60 |
Running: no |
| 61 |
Name match: 0 |
| 62 |
|
| 63 |
Actions |
| 64 |
"App::Daemon" recognizes three different actions: |
| 65 |
|
| 66 |
my-app start |
| 67 |
will start up the daemon. "start" itself is optional, as this is the |
| 68 |
default action, |
| 69 |
|
| 70 |
$ ./my-app |
| 71 |
$ |
| 72 |
|
| 73 |
will also run the 'start' action. By default, it will create a pid |
| 74 |
file and a log file in the current directory (named "my-app.pid" and |
| 75 |
"my-app.log". To change these locations, see the "-l" and "-p" |
| 76 |
options. |
| 77 |
|
| 78 |
If the -X option is given, the program is running in foreground mode |
| 79 |
for testing purposes: |
| 80 |
|
| 81 |
$ ./my-app -X |
| 82 |
... |
| 83 |
|
| 84 |
stop |
| 85 |
will find the daemon's PID in the pidfile and send it a SIGTERM |
| 86 |
signal. It will verify $App::Daemon::kill_retries times if the |
| 87 |
process is still alive, with 1-second sleeps in between. |
| 88 |
|
| 89 |
To have App::Daemon send a different signal than SIGTERM (e.g., |
| 90 |
SIGINT), set |
| 91 |
|
| 92 |
use POSIX; |
| 93 |
$App::Daemon::kill_sig = SIGINT; |
| 94 |
|
| 95 |
Note that his requires the numerial value (SIGINT via POSIX.pm), not |
| 96 |
a string like "SIGINT". |
| 97 |
|
| 98 |
status |
| 99 |
will print out diagnostics on what the status of the daemon is. |
| 100 |
Typically, the output looks like this: |
| 101 |
|
| 102 |
Pid file: ./tt.pid |
| 103 |
Pid in file: 15562 |
| 104 |
Running: yes |
| 105 |
Name match: 1 |
| 106 |
/usr/local/bin/perl -w test.pl |
| 107 |
|
| 108 |
This indicates that the pidfile says that the daemon has PID 15562 |
| 109 |
and that a process with this PID is actually running at this moment. |
| 110 |
Also, a name grep on the process name in the process table results |
| 111 |
in 1 match, according to the output above. |
| 112 |
|
| 113 |
Note that the name match is unreliable, as it just looks for a |
| 114 |
command line that looks approximately like the script itself. So if |
| 115 |
the script is "test.pl", it will match lines like "perl -w test.pl" |
| 116 |
or "perl test.pl start", but unfortunately also lines like "vi |
| 117 |
test.pl". |
| 118 |
|
| 119 |
If the process is no longer running, the status output might look |
| 120 |
like this instead: |
| 121 |
|
| 122 |
Pid file: ./tt.pid |
| 123 |
Pid in file: 14914 |
| 124 |
Running: no |
| 125 |
Name match: 0 |
| 126 |
|
| 127 |
The status commands exit code complies with |
| 128 |
|
| 129 |
http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html |
| 130 |
|
| 131 |
and returns |
| 132 |
|
| 133 |
0: if the process is up and running |
| 134 |
1: the process is dead but the pid file still exists |
| 135 |
3: the process is not running |
| 136 |
|
| 137 |
These constants are defined within App::Daemon to help writing test |
| 138 |
scripts: |
| 139 |
|
| 140 |
use constant LSB_OK => 0; |
| 141 |
use constant LSB_DEAD_PID_EXISTS => 1; |
| 142 |
use constant LSB_DEAD_LOCK_EXISTS => 2; |
| 143 |
use constant LSB_NOT_RUNNING => 3; |
| 144 |
use constant LSB_UNKNOWN => 4; |
| 145 |
use constant ALREADY_RUNNING => 150; |
| 146 |
|
| 147 |
Command Line Options |
| 148 |
-X Foreground mode. Log messages go to the screen. |
| 149 |
|
| 150 |
-l logfile |
| 151 |
Logfile to send Log4perl messages to in background mode. Defaults to |
| 152 |
"./[appname].log". Note that having a logfile in the current |
| 153 |
directory doesn't make sense except for testing environments, make |
| 154 |
sure to set this to somewhere within "/var/log" for production use. |
| 155 |
|
| 156 |
-u as_user |
| 157 |
User to run as if started as root. Defaults to 'nobody'. |
| 158 |
|
| 159 |
-g as_group |
| 160 |
Group to run as if started as root. Defaults to 'nogroup'. |
| 161 |
|
| 162 |
-l4p l4p.conf |
| 163 |
Path to Log4perl configuration file. Note that in this case the -v |
| 164 |
option will be ignored. |
| 165 |
|
| 166 |
-p pidfile |
| 167 |
Where to save the pid of the started process. Defaults to |
| 168 |
"./[appname].pid". Note that having a pidfile in the current |
| 169 |
directory doesn't make sense except for testing environments, make |
| 170 |
sure to set this to somewhere within "/var/run" for production use. |
| 171 |
|
| 172 |
-v Increase default Log4perl verbosity from $INFO to $DEBUG. Note that |
| 173 |
this option will be ignored if Log4perl is initialized independently |
| 174 |
or if a user-provided Log4perl configuration file is used. |
| 175 |
|
| 176 |
Setting Parameters |
| 177 |
Instead of setting paramteters like the logfile, the pidfile etc. from |
| 178 |
the command line, you can directly manipulate App::Daemon's global |
| 179 |
variables: |
| 180 |
|
| 181 |
use App::Daemon qw(daemonize); |
| 182 |
|
| 183 |
$App::Daemon::logfile = "mylog.log"; |
| 184 |
$App::Daemon::pidfile = "mypid.log"; |
| 185 |
$App::Daemon::l4p_conf = "myconf.l4p"; |
| 186 |
$App::Daemon::background = 1; |
| 187 |
$App::Daemon::as_user = "nobody"; |
| 188 |
$App::Daemon::as_group = "nogroup"; |
| 189 |
|
| 190 |
use Log::Log4perl qw(:levels); |
| 191 |
$App::Daemon::loglevel = $DEBUG; |
| 192 |
|
| 193 |
daemonize(); |
| 194 |
|
| 195 |
Application-specific command line options |
| 196 |
If an application needs additional command line options, it can use |
| 197 |
whatever is not yet taken by App::Daemon, as described previously in the |
| 198 |
"Command Line Options" section. |
| 199 |
|
| 200 |
However, it needs to make sure to remove these additional options before |
| 201 |
calling daemonize(), or App::Daemon will complain. To do this, create an |
| 202 |
options hash %opts and store application-specific options in there while |
| 203 |
removing them from @ARGV: |
| 204 |
|
| 205 |
my %opts = (); |
| 206 |
|
| 207 |
for my $opt (qw(-k -P -U)) { |
| 208 |
my $v = App::Daemon::find_option( $opt, 1 ); |
| 209 |
$opts{ $opt } = $v if defined $v; |
| 210 |
} |
| 211 |
|
| 212 |
After this, options "-k", "-P", and "-U" will have disappeared from |
| 213 |
@ARGV and can be checked in $opts{k}, $opts{P}, and $opts{U}. |
| 214 |
|
| 215 |
Gotchas |
| 216 |
Log File Permissions |
| 217 |
If the process is started as root but later drops permissions to a |
| 218 |
non-priviledged user for security purposes, it's important that |
| 219 |
logfiles are created with correct permissions. |
| 220 |
|
| 221 |
If they're created as root when the program starts, the |
| 222 |
non-priviledged user won't be able to write to them later (unless |
| 223 |
they're world-writable which is also undesirable because of security |
| 224 |
concerns). |
| 225 |
|
| 226 |
The best strategy to handle this case is to specify the |
| 227 |
non-priviledged user as the owner of the logfile in the Log4perl |
| 228 |
configuration: |
| 229 |
|
| 230 |
log4perl.logger = DEBUG, FileApp |
| 231 |
log4perl.appender.FileApp = Log::Log4perl::Appender::File |
| 232 |
log4perl.appender.FileApp.filename = /var/log/foo-app.log |
| 233 |
log4perl.appender.FileApp.owner = nobody |
| 234 |
log4perl.appender.FileApp.layout = PatternLayout |
| 235 |
log4perl.appender.FileApp.layout.ConversionPattern = %d %m%n |
| 236 |
|
| 237 |
This way, the process starts up as root, creates the logfile if it |
| 238 |
doesn't exist yet, and changes its owner to 'nobody'. Later, when |
| 239 |
the process assumes the identity of the user 'nobody', it will |
| 240 |
continue to write to the logfile without permission problems. |
| 241 |
|
| 242 |
Log4perl Categories |
| 243 |
Note that App::Daemon is logging messages in Log4perl's App::Daemon |
| 244 |
namespace. So, if you're running your own Log4perl configuration and |
| 245 |
define a root logger like |
| 246 |
|
| 247 |
log4perl.logger=DEBUG, appendername |
| 248 |
|
| 249 |
then App::Daemon's messages will bubble up to it and be visible in |
| 250 |
the output. If you don't want that, either use |
| 251 |
|
| 252 |
log4perl.logger.My.App=DEBUG, appendername |
| 253 |
|
| 254 |
to explicitly enable verbose logging in your application namespace |
| 255 |
(and not in App::Daemon's) or tone down App::Daemon's verbosity via |
| 256 |
|
| 257 |
log4perl.logger.App.Daemon=ERROR |
| 258 |
|
| 259 |
explicitly. If you want more details on basic Log4perl features, |
| 260 |
check out the Log::Log4perl manual page. |
| 261 |
|
| 262 |
Detach only |
| 263 |
If you want to create a daemon without the fancy command line parsing |
| 264 |
and PID file checking functions, use |
| 265 |
|
| 266 |
use App::Daemon qw(detach); |
| 267 |
detach(); |
| 268 |
# ... some code here |
| 269 |
|
| 270 |
This will fork a child, terminate the parent and detach the child from |
| 271 |
the terminal. Issued from the command line, the program above will |
| 272 |
continue to run the code following the detach() call but return to the |
| 273 |
shell prompt immediately. |
| 274 |
|
| 275 |
AUTHOR |
| 276 |
2008, Mike Schilli <[email protected]> |
| 277 |
|
| 278 |
LICENSE |
| 279 |
Copyright 2008-2012 by Mike Schilli, all rights reserved. This program |
| 280 |
is free software, you can redistribute it and/or modify it under the |
| 281 |
same terms as Perl itself. |
| 282 |
|