1Daemon(3)             User Contributed Perl Documentation            Daemon(3)
2
3
4

NAME

6       App::Daemon - Start an Application as a Daemon
7

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

DESCRIPTION

30       "App::Daemon" helps running an application as a daemon. The idea is
31       that 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
50           screen.
51
52       •   detects if another instance is already running and ends itself
53           automatically in this case.
54
55       •   shows with the 'status' command if an instance is already running
56           and which PID it has:
57
58               ./my-app status
59               Pid file:    ./tt.pid
60               Pid in file: 14914
61               Running:     no
62               Name match:  0
63
64   Actions
65       "App::Daemon" recognizes three different actions:
66
67       my-app start
68           will start up the daemon. "start" itself is optional, as this is
69           the default action,
70
71                   $ ./my-app
72                   $
73
74           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
79           If the -X option is given, the program is running in foreground
80           mode for testing purposes:
81
82                   $ ./my-app -X
83                   ...
84
85       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
90           To have App::Daemon send a different signal than SIGTERM (e.g.,
91           SIGINT), set
92
93               use POSIX;
94               $App::Daemon::kill_sig = SIGINT;
95
96           Note that his requires the numerial value (SIGINT via POSIX.pm),
97           not a string like "SIGINT".
98
99       status
100           will print out diagnostics on what the status of the daemon is.
101           Typically, the output looks like this:
102
103               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
109           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
114           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
120           If the process is no longer running, the status output might look
121           like this instead:
122
123               Pid file:    ./tt.pid
124               Pid in file: 14914
125               Running:     no
126               Name match:  0
127
128           The status commands exit code complies with
129
130               http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html
131
132           and returns
133
134               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
138           These constants are defined within App::Daemon to help writing test
139           scripts:
140
141               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
148   Command Line Options
149       -X  Foreground mode. Log messages go to the screen.
150
151       -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
157       -u as_user
158           User to run as if started as root. Defaults to 'nobody'.
159
160       -g as_group
161           Group to run as if started as root.  Defaults to 'nogroup'.
162
163       -l4p l4p.conf
164           Path to Log4perl configuration file. Note that in this case the -v
165           option will be ignored.
166
167       -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
173       -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
178   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
183           use App::Daemon qw(daemonize);
184
185           $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
192           use Log::Log4perl qw(:levels);
193           $App::Daemon::loglevel   = $DEBUG;
194
195           daemonize();
196
197   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
202       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
207           my %opts = ();
208
209           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
214       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
217   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
223           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
228           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
232               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
239           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
244       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
249               log4perl.logger=DEBUG, appendername
250
251           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
254               log4perl.logger.My.App=DEBUG, appendername
255
256           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
259               log4perl.logger.App.Daemon=ERROR
260
261           explicitly. If you want more details on basic Log4perl features,
262           check out the Log::Log4perl manual page.
263
264   Detach only
265       If you want to create a daemon without the fancy command line parsing
266       and PID file checking functions, use
267
268           use App::Daemon qw(detach);
269           detach();
270           # ... some code here
271
272       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

AUTHOR

278           2008, Mike Schilli <cpan@perlmeister.com>
279

LICENSE

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.
284
285
286
287perl v5.36.0                      2023-01-19                         Daemon(3)
Impressum