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: /tmp/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 will also run the 'start' action. If the -X option is given, the
74 program is run in foreground mode for testing purposes.
75 stop
77 will find the daemon's PID in the pidfile and send it a kill
78 signal. It won't verify if this actually shut down the daemon or if
79 it's immune to the kill signal.
80 status
82 will print out diagnostics on what the status of the daemon is.
83 Typically, the output look like this:
84 Pid file: /tmp/tt.pid
86 Pid in file: 15562
87 Running: yes
88 Name match: 1
89 /usr/local/bin/perl -w test.pl
90 This indicates that the pidfile says that the daemon has PID 15562
92 and that a process with this PID is actually running at this
93 moment. Also, a name grep on the process name in the process table
94 results in 1 match, according to the output above.
95 Note that the name match is unreliable, as it just looks for a
97 command line that looks approximately like the script itself. So if
98 the script is "test.pl", it will match lines like "perl -w test.pl"
99 or "perl test.pl start", but unfortunately also lines like "vi
100 test.pl".
101 If the process is no longer running, the status output might look
103 like this instead:
104 Pid file: /tmp/tt.pid
106 Pid in file: 14914
107 Running: no
108 Name match: 0
109 Command Line Options
111 -X Foreground mode. Log messages go to the screen.
112 -l logfile
114 Logfile to send Log4perl messages to in background mode. Defaults
115 to "/tmp/[appname].log".
116 -u as_user
118 User to run as if started as root. Defaults to 'nobody'.
119 -l4p l4p.conf
121 Path to Log4perl configuration file. Note that in this case the -v
122 option will be ignored.
123 -p pidfile
125 Where to save the pid of the started process. Defaults to
126 "/tmp/[appname].pid".
127 -v Increase default Log4perl verbosity from $INFO to $DEBUG. Note that
129 this option will be ignored if Log4perl is initialized
130 independently or if a user-provided Log4perl configuration file is
131 used.
132 Setting Parameters
134 Instead of setting paramteters like the logfile, the pidfile etc. from
135 the command line, you can directly manipulate App::Daemon's global
136 variables:
137 use App::Daemon qw(daemonize);
139 $App::Daemon::logfile = "mylog.log";
141 $App::Daemon::pidfile = "mypid.log";
142 $App::Daemon::l4p_conf = "myconf.l4p";
143 $App::Daemon::background = 1;
144 $App::Daemon::as_user = "nobody";
145 use Log::Log4perl qw(:levels);
147 $App::Daemon::loglevel = $DEBUG;
148 daemonize();
150 Application-specific command line options
152 If an application needs additional command line options, it can use
153 whatever is not yet taken by App::Daemon, as described previously in
154 the "Command Line Options" section.
155 However, it needs to make sure to remove these additional options
157 before calling daemonize(), or App::Daemon will complain. To do this,
158 create an options hash %opts and store application-specific options in
159 there while removing them from @ARGV:
160 my %opts = ();
162 for my $opt (qw(-k -P -U)) {
164 my $v = App::Daemon::find_option( $opt, 1 );
165 $opts{ $opt } = $v if defined $v;
166 }
167 After this, options "-k", "-P", and "-U" will have disappeared from
169 @ARGV and can be checked in $opts{k}, $opts{P}, and $opts{U}.
170 Gotchas
172 If the process is started as root but later drops permissions to a non-
173 priviledged user for security purposes, it's important that logfiles
174 are created with correct permissions.
175 If they're created as root when the program starts, the non-priviledged
177 user won't be able to write to them later (unless they're world-
178 writable which is also undesirable because of security concerns).
179 The best strategy to handle this case is to specify the non-priviledged
181 user as the owner of the logfile in the Log4perl configuration:
182 log4perl.logger = DEBUG, FileApp
184 log4perl.appender.FileApp = Log::Log4perl::Appender::File
185 log4perl.appender.FileApp.filename = /var/log/foo-app.log
186 log4perl.appender.FileApp.owner = nobody
187 log4perl.appender.FileApp.layout = PatternLayout
188 log4perl.appender.FileApp.layout.ConversionPattern = %d %m%n
189 This way, the process starts up as root, creates the logfile if it
191 doesn't exist yet, and changes its owner to 'nobody'. Later, when the
192 process assumes the identity of the user 'nobody', it will continue to
193 write to the logfile without permission problems.
194 Detach only
196 If you want to create a daemon without the fancy command line parsing
197 and PID file checking functions, use
198 use App::Daemon qw(detach);
200 detach();
201 # ... some code here
202 This will fork a child, terminate the parent and detach the child from
204 the terminal. Issued from the command line, the program above will
205 continue to run the code following the detach() call but return to the
206 shell prompt immediately.
207
209 Mike Schilli, cpan@perlmeister.com
210
212 Copyright (C) 2008 by Mike Schilli
213 This library is free software; you can redistribute it and/or modify it
215 under the same terms as Perl itself, either Perl version 5.8.5 or, at
216 your option, any later version of Perl 5 you may have available.
217perl v5.12.1 2010-08-28 Daemon(3)