Debian Codegraph @

README

raw
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