automagick.us

Soop.pm

You can download Soop.pm here.

NAME

Soop - Supervise any process, and make it behave like a daemon

SYNOPSIS

 use Soop;
 my $supervisor = Soop->new( %options_hash );
 $supervisor->begin();

DESCRIPTION

Soop is a process supervisor along the lines of djb's daemontools. It will fork a child, execute the given process, and restart it whenever it exits. Soop can also run user-defined tests at a preset interval to determine whether or not the child process should be stopped or restarted. Logging is done to STDERR or syslog, user's choice.

METHODS

• new()

  Returns a new Soop object. The process() argument is required.

• process()

  The process hashref defines the process the Soop object should supervise. It must have two keys, cmd, which defines the process executable, and args, an optional arrayref of arguments to pass to the executable.

  In addition to the process arg, any of the following may be supplied as arguments to the new() method, or called using instance methods on an existing Soop object (excluding the begin() method; see below).

• daemonize()

  If true, the main process should become a daemon ( via fork() ) before spawning the process to monitor. Suitable for starting Sooped processes from init scripts and the like. The default value is false (do not become a daemon).

• path()

  If specified, override the PATH environment variable of the spawned process.

• uid() and gid()

  If specified, the process will drop the current user's permissions and set the effective UID and GID to the given values. Useful for init scripts, which typically start as root.

• If specified, attempt to write the Soop process's ID to this file.

• use_syslog()

  If true, redirect warnings and error messages to syslog. The default is false (do not log to syslog).

• syslog_facility()

  The facility to use when logging to syslog. The default is 'daemon'.

• syslog_ident()

  The ident to use when logging to syslog. The default is 'sooper.'

• snoozetime()

  How long to sleep before executing tests, in seconds. The default is 30.

• tests()

  An arrayref of code references that should be executed every snoozetime seconds. A test is must return true on success; a false return will skip the remaining tests, if any, send a HUP to the supervised process. If a test dies, The supervisor process will send a TERM signal to the supervised process, then shut down (with appropriate dire complaints in the log).

• verbose()

  Turn on verbose logging.

• begin()

  Start the main program loop. Calling this method will cause the Soop object to spawn the process to monitor and begin its loop. The begin() method does not return!

EXAMPLE

The following example code will create an SSH tunnel to an SMTP server running on localhost, daemonize, sleep for 30 seconds, and then restart the tunnel when the second test is evaluated (and returns failure):

  my $supervisor = Soop->new(
    process => {
        cmd => '/usr/bin/ssh',
        args => [ '-N', '-L 2222:localhost:25', 'localhost' ]
    },

    verbose         => 1,
    daemonize       => 1,
    path            => '/bin',
    uid             => 1000,
    gid             => 1000,
    pid_file        => './sooptest.pid',

    use_syslog      => 1,
    syslog_facility => 'daemon',
    syslog_ident    => 'sooptest',

    snoozetime      => 30,
    
    tests           => [
        sub {
            my $self = shift;
            print "This is a successful test.\n";
            return 1;
        },
        sub {
            my $self = shift;
                        print "This test will always fail!\n";
            return 0;
        }
    ]
);
$supervisor->begin();

VERSION

This is verison 1.1 of Soop.pm

AUTHOR

Greg Boyington <greg@automagick.us>