view release on metacpan or  search on metacpan

lib/AFS/Command/FS.pod  view on Meta::CPAN

=head1 DESCRIPTION

This module implements an OO API wrapper around the AFS 'fs' command.
The supported methods depend on the version of the fs binary used,
and are determined automagically.

=head1 METHODS -- Inherited

All of the following methods are inherited from the AFS::Command::Base
class.  See that documentation for details.

=over

=item new

=item errors

=item supportsOperation

=item supportsArgument

=back

=head1 METHODS (with complex return values)

=head2 NOTE: Error checking for commands that accept a list of paths

A number of these methods accept a list of paths, and will return
information for each path, individually.  If you specify a
non-existent path, or one which is not in AFS, then the fs command
returns a non-zero exist status, which normally would mean the command
failed.

If you specify a list of paths to this API, and one or more of them
result in errors, the API call is still considered to succeed, as long
as we can determine the error for each path specified.  The API will
still return an AFS::Object::CacheManager object, which contains a set
of AFS::Object::Path object, for each path specified in the arguments,
as long as we saw some kind of output from the fs commands for each
path.

Each AFS::Object::Path object must be examined to determine the
success of failure for that individual path.  When errors were
encountered for any given path, then the objects will have an "error"
attribute, and nothing else (no other data attributes, except the path
itself).

This holds true for the following API methods: diskfree, examine,
listquota, quota, storebehind, whereis, whichcell, and listacl.

=head2 checkservers

=over

=item Arguments

The fs help string is:

    fs checkservers: check local cell's servers
    Usage: fs checkservers [-cell <cell to check>] [-all] [-fast]
			   [-interval <seconds between probes>]
    Where: -all   check all cells
	   -fast  just list, don't check

The corresponding method invocation looks like:

    my $result = $fs->checkservers
      (
       # Optional arguments
       cell			=> $cell,
       interval			=> $interval,
       all			=> 1,
       fast			=> 1,
      );

=item Return Values

This method returns an AFS::Object::CacheManager object, which
contains one or more attributes.

    my $result = $fs->checkservers() || die $fs->errors();
    my @servers = $result->servers();
    foreach my $server ( @servers ) {
        print "Server $server appears to be down\n";
    }

The object has the following attributes:

    Attributes			Values
    ----------			------
    servers			ARRAY reference of strings, each of which is
				the hostname of a server which is down
    interval			The value of the probe interval, in seconds

Note that the interval attribute is only present of the internal
argument was specified, and the servers list will be empty if nothing
was down.

=back

=head2 diskfree

=over

=item Arguments

The fs help string is:

    fs diskfree: show server disk space usage
    Usage: fs diskfree [-path <dir/file path>+]

The corresponding method invocation looks like:

    my $result = $fs->diskfree
      (
       # Optional arguments
       path			=> $path, # OR [ $path1, $path2, ... ]
      );

=item Return Values

This method returns an AFS::Object::CacheManager object, which
contains one or more AFS::Object::Path objects, one for each path
specified in the arguments.

    my $result = $fs->diskfree
      (
       path		=> [ $afspath, $ufspath, $boguspath ],
      ) || die $fs->errors();
    foreach my $pathobj ( $result->getPaths() ) {
	my $path = $pathobj->path();
	if ( $pathobj->hasAttribute('error') ) {
	    print "Path '$path' has errors '" . $pathobj->error() . "'\n";
	} else {
	    foreach my $attr ( qw( volname used total avail percent ) ) {
		print "Path '$path' has '$attr' of '" . $pathobj->$attr() . "'\n";
	    }
	}
    }

Each of these objects has the following attributes and methods:

B<AFS::Object::CacheManager>

    Methods			Returns
    -------			-------
    getPathNames()		list of strings, each of which is a single pathname
    getPaths()			list of AFS::Object::Path objects, one for each path
    getPath($pathname)		a single AFS::Object::Path object, for the pathname $pathname

B<AFS::Object::Path>

If errors were encountered for any given path, then its object will