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