#-*-cperl-*-
#
# $Id: README,v 7.1 2004/01/13 19:01:11 wpm Exp $
#
# (c) 2003-2004 Morgan Stanley and Co.
# See ..../src/LICENSE for terms of distribution.
#

=head1 INTRODUCTION

AFS::Command -- An OO wrapper API for the AFS command line utilities (vos, bos, pts, fs)

=head1 SUMMARY

This suite of perl modules implements an API for the command line
utilities for managing and using the AFS distributed file system.  AFS
is available as both an Open Source product (http://www.openafs.org),
as well as a commercial version from IBM
(http://www.ibm.com/software/stormgmt/afs/).

For example, AFS volumes are managed using the command line utility
'vos', for which there is currently no programmatic API, in any
language.  This API is a pure perl wrapper around the command line
utility, that implements an OO API that allows for the easy
development of systems management applications for AFS.

=head1 PREREQUISITES

This module requires perl5.6 or later, as well as an installed AFS
infrastructure to work with.  The code is pure perl, with no compiled
components, do it should work on any variant of UNIX (sorry, but this
code makes aggressive use of pipe() and fork(), so porting it to
Windows is gonna be painful...  but then, why anyone would want to
manage their AFS infrastructure from Windows escapes me).

=head1 INSTALLATION

This module builds like almost everything else on CPAN:

  perl Makefile.PL
  make
  make test
  make install

Before running 'make test', edit the CONFIG file and follow the
instructions in the comments.  Minimally, you have to specify a couple
of AFS file servers and one AFS database server against which to run
the tests, as well as a pathname in AFS where we can create mount
points.

The test suite will require AFS super-user privileges, so you must
either be a member of the system:administrators protection group, or a
member of the super users list on the servers.  If you don't know what
that means, you shouldn't be testing this module, so consult your AFS
administrators.

See the CONFIG file for more details.  Its pretty verbosely
documented.

Any failure in the test suite is a cause for concern.  For more
verbose output, run:

  make test TEST_VERBOSE=1

If you can't determine the source of the problem(s), send the verbose
test output, along with the output from "perl -V", as well as the
versions of AFS in use at your site, to the author, and I'll do my
best to figure out why things are breaking, and if you're lucky,
actually fix it.

=head1 RELEASE NOTES

In addition to the README file (which in case you hadn't noticed,
you're reading right now), the history of changes is maintained in
Changes.html.

=head1 DOCUMENTATION

Docs for these modules are split across several files, and will be
installed as man pages.

  man AFS::Command

will provide the general overview of the API, its basic design.  The
details of the API calls, their arguments, and return values, are
found in the following documents:

  man AFS::Command::Base
  man AFS::Command::VOS
  man AFS::Command::BOS
  man AFS::Command::PTS
  man AFS::Command::FS
  man AFS::Object

=head1 AUTHOR

This code is a product of the demented mind of:

    W. Phillip Moore <[email protected]>

Feedback, patches, recommendations, adulations, and even flames are
all welcome.   Feed my ego (or try to shoot it down :-), please...

=cut