Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
CPAN Module: Start an Application as a Daemon
Perl
tag: rel_010

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
adm
eg
t
.cvsignore
.gitignore
Changes
Daemon.pm
MANIFEST
Makefile.PL
README

README

######################################################################
    App::Daemon 0.10
######################################################################

NAME
    App::Daemon - Start an Application as a Daemon

SYNOPSIS
         # Program:
       use App::Daemon qw( daemonize );
       daemonize();
       do_something_useful(); # your application

         # Then, in the shell: start application,
         # which returns immediately, but continues 
         # to run do_something_useful() in the background
       $ app start
       $

         # stop application
       $ app stop

         # start app in foreground (for testing)
       $ app -X

         # show if app is currently running
       $ app status

DESCRIPTION
    "App::Daemon" helps running an application as a daemon. The idea is that
    you prepend your script with the

        use App::Daemon qw( daemonize ); 
        daemonize();

    and 'daemonize' it that way. That means, that if you write

        use App::Daemon qw( daemonize ); 

        daemonize();
        sleep(10);

    you'll get a script that, when called from the command line, returns
    immediatly, but continues to run as a daemon for 10 seconds.

    Along with the common features offered by similar modules on CPAN, it

    *   supports logging with Log4perl: In background mode, it logs to a
        logfile. In foreground mode, log messages go directly to the screen.

    *   detects if another instance is already running and ends itself
        automatically in this case.

    *   shows with the 'status' command if an instance is already running
        and which PID it has:

            ./my-app status
            Pid file:    /tmp/tt.pid
            Pid in file: 14914
            Running:     no
            Name match:  0

  Actions
    "App::Daemon" recognizes three different actions:

    my-app start
        will start up the daemon. "start" itself is optional, as this is the
        default action,

                $ ./my-app
        
        will also run the 'start' action. If the -X option is given, the
        program is run in foreground mode for testing purposes.

    stop
        will find the daemon's PID in the pidfile and send it a kill signal.
        It won't verify if this actually shut down the daemon or if it's
        immune to the kill signal.

    status
        will print out diagnostics on what the status of the daemon is.
        Typically, the output look like this:

            Pid file:    /tmp/tt.pid
            Pid in file: 15562
            Running:     yes
            Name match:  1
                /usr/local/bin/perl -w test.pl

        This indicates that the pidfile says that the daemon has PID 15562
        and that a process with this PID is actually running at this moment.
        Also, a name grep on the process name in the process table results
        in 1 match, according to the output above.

        Note that the name match is unreliable, as it just looks for a
        command line that looks approximately like the script itself. So if
        the script is "test.pl", it will match lines like "perl -w test.pl"
        or "perl test.pl start", but unfortunately also lines like "vi
        test.pl".

        If the process is no longer running, the status output might look
        like this instead:

            Pid file:    /tmp/tt.pid
            Pid in file: 14914
            Running:     no
            Name match:  0

  Command Line Options
    -X  Foreground mode. Log messages go to the screen.

    -l logfile
        Logfile to send Log4perl messages to in background mode. Defaults to
        "/tmp/[appname].log".

    -u as_user
        User to run as if started as root. Defaults to 'nobody'.

    -l4p l4p.conf
        Path to Log4perl configuration file. Note that in this case the -v
        option will be ignored.

    -p pidfile
        Where to save the pid of the started process. Defaults to
        "/tmp/[appname].pid".

    -v  Increase default Log4perl verbosity from $INFO to $DEBUG. Note that
        this option will be ignored if Log4perl is initialized independently
        or if a user-provided Log4perl configuration file is used.

  Setting Parameters
    Instead of setting paramteters like the logfile, the pidfile etc. from
    the command line, you can directly manipulate App::Daemon's global
    variables:

        use App::Daemon qw(daemonize);

        $App::Daemon::logfile    = "mylog.log";
        $App::Daemon::pidfile    = "mypid.log";
        $App::Daemon::l4p_conf   = "myconf.l4p";
        $App::Daemon::background = 1;
        $App::Daemon::as_user    = "nobody";

        use Log::Log4perl qw(:levels);
        $App::Daemon::loglevel   = $DEBUG;

        daemonize();

  Application-specific command line options
    If an application needs additional command line options, it can use
    whatever is not yet taken by App::Daemon, as described previously in the
    "Command Line Options" section.

    However, it needs to make sure to remove these additional options before
    calling daemonize(), or App::Daemon will complain. To do this, create an
    options hash %opts and store application-specific options in there while
    removing them from @ARGV:

        my %opts = ();

        for my $opt (qw(-k -P -U)) {
            my $v = App::Daemon::find_option( $opt, 1 );
            $opts{ $opt } = $v if defined $v;
        }

    After this, options "-k", "-P", and "-U" will have disappeared from
    @ARGV and can be checked in $opts{k}, $opts{P}, and $opts{U}.

  Gotchas
    If the process is started as root but later drops permissions to a
    non-priviledged user for security purposes, it's important that logfiles
    are created with correct permissions.

    If they're created as root when the program starts, the non-priviledged
    user won't be able to write to them later (unless they're world-writable
    which is also undesirable because of security concerns).

    The best strategy to handle this case is to specify the non-priviledged
    user as the owner of the logfile in the Log4perl configuration:

        log4perl.logger = DEBUG, FileApp
        log4perl.appender.FileApp = Log::Log4perl::Appender::File
        log4perl.appender.FileApp.filename = /var/log/foo-app.log
        log4perl.appender.FileApp.owner    = nobody
        log4perl.appender.FileApp.layout   = PatternLayout
        log4perl.appender.FileApp.layout.ConversionPattern = %d %m%n

    This way, the process starts up as root, creates the logfile if it
    doesn't exist yet, and changes its owner to 'nobody'. Later, when the
    process assumes the identity of the user 'nobody', it will continue to
    write to the logfile without permission problems.

  Detach only
    If you want to create a daemon without the fancy command line parsing
    and PID file checking functions, use

        use App::Daemon qw(detach);
        detach();
        # ... some code here

    This will fork a child, terminate the parent and detach the child from
    the terminal. Issued from the command line, the program above will
    continue to run the code following the detach() call but return to the
    shell prompt immediately.

AUTHOR
    Mike Schilli, cpan@perlmeister.com

COPYRIGHT AND LICENSE
    Copyright (C) 2008 by Mike Schilli

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.8.5 or, at
    your option, any later version of Perl 5 you may have available.

Something went wrong with that request. Please try again.