The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Cluster-Init-0.202
River stage zero No dependents
++
/ Cluster::Init

status(group=>'foo',level=>'bar',clstat=>'/tmp/clstat')

This method will read the status file for you, dumping it to stdout. All arguments are optional. If you provide 'group' or 'level', then output will be filtered accordingly. If you specify 'clstat', then the status file at the given pathname wil be read (this is handy if you need to query multiple Cluster::Init status files in a shared cluster filesystem).

In addition to the usual $obj->status() syntax, the status() method can also be called as a class function, as in Cluster::Init::status(clstat=>'/tmp/clstat'). The 'clstat' argument is required in this case. Again, this is handy if you want to query a running Cluster::Init on another machine via a shared filesystem, without creating an Cluster::Init object or daemon here.

shutdown()

Causes daemon to stop all child processes and exit.

NAME

Cluster::Init - Clusterwide "init", spawn cluster applications

SYNOPSIS

  use Cluster::Init;

  my $init = new Cluster::Init;

  # spawn all apps for resource group "foo", runlevel "run"
  $init->tell("foo","run");

  # spawn all apps for resource group "foo", runlevel "runmore"
  # (this stops everything started by runlevel "run")
  $init->tell("foo","runmore");

DESCRIPTION

This module provides basic "init" functionality, giving you a single inittab-like file to manage initialization and daemon startup across a cluster or collection of machines.

USAGE

This module's package includes a script 'clinit', which is intended to be a bolt-in cluster init tool, calling Cluster::Init. The script is called like 'init', with the addition of a new "resource group" argument.

This module is intended to be used like 'init' and 'telinit' -- the first execution runs as a daemon, spawning and managing processes. Later executions talk to the first, requesting it to switch to different runlevels.

The module references a configuration file, /etc/cltab by default, which is identical in format to /etc/cltab, with a new "resource group" column added. See t/cltab in the Cluster::Init distribution for an example. This file must be replicated across all hosts in the cluster by some means of your own. See OpenMosix::HA for a way to do this on OpenMosix clusters (and get high availability in the bargain).

A "resource group" is a collection of applications and physical resources which together make up a coherent function. For example, sendmail, /etc/sendmail.cf, and the /var/spool/mqueue directory might make up a resource group. From /etc/cltab you could spawn the scripts which update sendmail.cf, mount mqueue, and then start sendmail itself.

Any time the module changes the runlevel of a resource group, it will update a status file, /var/run/clinit/clstat by default. The format of this file might change -- you are encouraged to use the Cluster::Init::status() method to read it (though the interface for status() might change also.) This will be firmed up before version 1.0. The reason for this state of flux is that I need status() for an openMosix HA cluster init layer, which I'll probably call Cluster::Mosix:HA or somesuch. Watch CPAN.

In addition to the init-style modes of 'once', 'wait', 'respawn', and 'off', Cluster::Init also supports a 'test' mode. If the return code of a 'test' mode command is anything other than zero, then the resource group as a whole is marked as 'failed' in the status file. If the return code is zero, then the resource group is marked 'running'. Again, this interface may change to support Cluster::Mosix:HA. See t/* for examples.

PUBLIC METHODS

new

The constructor accepts an optional hash containing the paths to the configuration file, socket, and/or status output file, like this:

  my $init = new Cluster::Init (
      'cltab' => '/etc/cltab',
      'socket' => '/var/run/clinit/init.s'
      'clstat' => '/var/run/clinit/clstat'
                          );

You can also specify 'socket' and 'clstat' locations in the configuration file itself, like this:

  # location of socket
  :::socket:/tmp/init.s
  # location of status file
  :::clstat:/tmp/clstat

Settings passed to the constructor normally override any found in the cltab file. You can cause the cltab file settings to take precedence though, by saying 'overrride' in the third column of the cltab file, like this:

  # location of socket
  ::override:socket:/tmp/init.s
  # location of status file
  ::override:clstat:/tmp/clstat

The first time this method is executed on a machine, it opens a UNIX domain socket, /var/run/clinit/init.s by default. Subsequent executions communicate with the first via this socket.

tell($resource_group,$runlevel)

This method talks to a running Cluster::Init daemon, telling it to switch the given resource group to the given runlevel.

All processes listed in the configuration file (normally /etc/cltab) which belong to the new runlevel will be started if they aren't already running.

All processes in the resource group which do not belong to the new runlevel will be killed.

Other resource groups will not be affected.

shutdown()

Causes daemon to stop all child processes and exit.

status(group=>'foo',level=>'bar',clstat=>'/tmp/clstat')

This method will read the status file for you, dumping it to stdout. All arguments are optional. If you provide 'group' or 'level', then output will be filtered accordingly. If you specify 'clstat', then the status file at the given pathname wil be read (this is handy if you need to query multiple Cluster::Init status files in a shared cluster filesystem).

In addition to the usual $obj->status() syntax, the status() method can also be called as a class function, as in Cluster::Init::status(clstat=>'/tmp/clstat'). The 'clstat' argument is required in this case. Again, this is handy if you want to query a running Cluster::Init on another machine via a shared filesystem, without creating an Cluster::Init object or daemon here.

PRIVATE METHODS

The following methods are documented here for internal use only. No user serviceable parts inside.

_open_socket()

Opens a client-side socket.

_start_daemon()

Opens server-side socket, starts main event loop, with long-running event watchers for accepting and processing commands from client, child exits, status file maintenance, etc.

_daemon()

Watcher triggered by I/O activity on server socket; calls accept() and sets a watcher for client I/O.

_client()

Watcher triggered by I/O activity on accept()ed client socket; parses text from client and does the right thing.

_tellgroup($group,$level)

Finds the watcher for a particular resource group, and tells it what the new runlevel is. If the watcher isn't running yet, then we start it.

_group()

Watcher triggered by control activity for a resource group; start and/or stop watchers for the individual entries in the group. Maintain master summary of group info.

Setting a runlevel of undef() causes the group to stop all of its processes and cancel its watcher.

_entry()

Watcher triggered by control activity for an individual cltab entry; start or stop process accordingly. Will also be triggered indirectly by signals, via _sigchld.

Each entry gets an active watcher, all the time, regardless of whether the entry is for a currently active runlevel or not.

If the cltab entry for a given watcher disappears, then the watcher kills its own process and cancels itself.

BUGS

AUTHOR

        Steve Traugott
        CPAN ID: STEVEGT
        stevegt@TerraLuna.Org
        http://www.stevegt.com

COPYRIGHT

Copyright (c) 2003 Steve Traugott. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

perl(1).