\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename readme.info
@settitle Perl IPC::Locker Installation
@c %**end of header

@c DESCRIPTION: TexInfo: DOCUMENT source run through texinfo to produce README file
@c Use 'make README' to produce the output file
@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update)

@node Top, Copyright, (dir), (dir)
@chapter IPC::Locker

This is the IPC::Locker Perl Package.

@menu
* Copyright::
* Description::
* Obtaining Distribution::
* Supported Systems::
* Installation::
@end menu

@node Copyright, Description, Top, Top
@section Copyright

This package is Copyright 1999-2017 by Wilson Snyder @email{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.

@node Description, Obtaining Distribution, Copyright, Top
@section 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.

@subsection IPC::Locker

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

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

See @samp{man IPC::Locker} after installation.

@subsection lockerd

lockerd is the daemon that supports IPC::Locker. See @samp{man
lockerd} after installation.

@subsection IPC::PidStat

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

@subsection pidstat

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

@subsection pidstatd

pidstat is the daemon that supports IPC::PidStat and pidstat. See
@samp{man pidstatd} after installation.

@subsection pidwatch

pidwatch is a program which starts other programs, and kill that program
when another job exists.  See @samp{man pidwatch} after installation.

@subsection 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 @samp{man uriexec} after
installation.

@subsection check_lockerd and check_pidstatd

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

@node Obtaining Distribution, Supported Systems, Description, Top
@section Obtaining Distribution

The latest version is available at
@uref{http://www.perl.org/CPAN/}

Download the latest package from that site, and decompress.
@samp{gunzip IPC::Locker_version.tar.gz ; tar xvf IPC::Locker_version.tar}

@node Supported Systems, Installation, Obtaining Distribution, Top
@section Supported Systems

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

@itemize @bullet
@item i386-linux
@item sparc-sun-solaris2.7
@end itemize

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

@node Installation,  , Supported Systems, Top
@section Installation

@enumerate
@item
@code{cd} to the directory containing this README notice.

@item
Type @samp{perl Makefile.PL} to configure IPC::Locker for your system.

@item
Type @samp{make} to compile IPC::Locker.

@item
Type @samp{make test} to check the compilation.

@item
Type @samp{make install} to install the programs and any data files and
documentation.

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

@samp{cp  init.d/lockerd   /etc/init.d/lockerd}  (On one server only)

@samp{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.

@samp{/etc/init.d/lockerd start}  (On one server only)

@samp{/etc/init.d/pidstatd start} (On all machines)

@samp{chkconfig lockerd on}  (On one server only)

@samp{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.

@item
If you are using Nagios (@url{http://www.nagios.org}), sample scripts
to check the daemons are included in the nagios subdirectory.

@end enumerate