1 IPC::Locker
*************

This is the IPC::Locker Perl Package.

1.1 Copyright
=============

This package is Copyright 1999-2012 by Wilson Snyder
<wsnyder@wsnyder.org>.

   This program is free software; you can redistribute it and/or modify
it under the terms of either the GNU Lesser General Public License
Version 3 or the Perl Artistic License Version 2.0.

   This code is provided with no warranty of any kind, and is used
entirely at your own risk.

1.2 Description
===============

This package provides a server for locks and a package for clients to
access that server.  The result is that clients can access named locks
on a Internet wide bases, solving critical section problems without the
mess of NFS or other file locking techniques.

1.2.1 IPC::Locker
-----------------

IPC::Locker is a Perl package which allows cross cluster locking.  For
example:

       my $lock = IPC::Locker->lock(host=>'example.std.com');
       ... Critical section ...
       $lock->unlock();

   See `man IPC::Locker' after installation.

1.2.2 lockerd
-------------

lockerd is the daemon that supports IPC::Locker. See `man lockerd'
after installation.

1.2.3 IPC::PidStat
------------------

IPC::PidStat is a Perl package which answers the question, "is pid X
running on host Y?".  See `man IPC::PidStat' after installation.

1.2.4 pidstat
-------------

pidstat is a program which answers the question, "is pid X running on
host Y?".  See `man pidstat' after installation.

1.2.5 pidstatd
--------------

pidstat is the daemon that supports IPC::PidStat and pidstat. See `man
pidstatd' after installation.

1.2.6 pidwatch
--------------

pidwatch is a program which starts other programs, and kill that program
when another job exists.  See `man pidwatch' after installation.

1.2.7 uriexec
-------------

uriexec is a simple wrapper which allows executing a command which is
quoted using URI escapes.  This prevents layered shells from
interpreting special characters.  See `man uriexec' after installation.

1.2.8 check_lockerd and check_pidstatd
--------------------------------------

check_lockerd and check_pidstatd are Nagios plugins to check lockerd
and pidstatd.  See the Nagios documentation `http://www.nagios.org' for
information on installing plugins.

1.3 Obtaining Distribution
==========================

The latest version is available at `http://www.perl.org/CPAN/'

   Download the latest package from that site, and decompress.  `gunzip
IPC::Locker_version.tar.gz ; tar xvf IPC::Locker_version.tar'

1.4 Supported Systems
=====================

This version of IPC::Locker has been built and tested on:

   * i386-linux

   * sparc-sun-solaris2.7

   It should run on any system with perl and TCP/IP socketing.

1.5 Installation
================

  1. `cd' to the directory containing this README notice.

  2. Type `perl Makefile.PL' to configure IPC::Locker for your system.

  3. Type `make' to compile IPC::Locker.

  4. Type `make test' to check the compilation.

  5. Type `make install' to install the programs and any data files and
     documentation.

  6. You may wish to install `lockerd' and `pidstatd' in a init.rc file
     so that it is run at system startup.  Depending on your
     distribution, you may be able to just:

     `cp  init.d/lockerd   /etc/init.d/lockerd'  (On one server only)

     `cp  init.d/pidstatd  /etc/init.d/pidstatd' (On all machines)

     Edit paths in above to point to /usr/bin instead of
     /usr/local/bin, if needed.

     `/etc/init.d/lockerd start'  (On one server only)

     `/etc/init.d/pidstatd start' (On all machines)

     `chkconfig lockerd on'  (On one server only)

     `chkconfig pidstatd on' (On all machines)

     If you get "This account is currently not available."  you need to
     change the daemon account from a shell of /sbin/nologin to
     /sbin/bash.

  7. If you are using Nagios (`http://www.nagios.org'), sample scripts
     to check the daemons are included in the nagios subdirectory.


