view release on metacpan or  search on metacpan

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

#
# $Id: FS.pod,v 8.1 2004/05/17 13:05:47 wpm Exp $
#
# (c) 2003-2004 Morgan Stanley and Co.
# See ..../src/LICENSE for terms of distribution.
#

=head1 NAME

AFS::Command::FS - OO API to the AFS fs command

=head1 SYNOPSIS

    use AFS::Command::FS;

    my $fs = AFS::Command::FS->new();

    my $fs = AFS::Command::FS->new
      (
       command			=> $path_to_your_fs_binary,
      );

=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

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

	   -clear    Clear RX stats

The corresponding method invocation looks like:

    my $result = $fs->rxstatpeer
      (
       # Optional arguments
       enable			=> 1,
       disable			=> 1,
       clear			=> 1,
      );

=head2 rxstatproc

The fs help string is:

    fs rxstatproc: Manage per process RX statistics
    Usage: fs rxstatproc [-enable] [-disable] [-clear]
    Where: -enable   Enable RX stats
	   -disable  Disable RX stats
	   -clear    Clear RX stats

The corresponding method invocation looks like:

    my $result = $fs->rxstatproc
      (
       # Optional arguments
       enable			=> 1,
       disable			=> 1,
       clear			=> 1,
      );

=head2 setacl

The fs help string is:

    fs setacl: set access control list
    Usage: fs setacl -dir <directory>+ -acl <access list entries>+
		     [-clear] [-negative] [-id] [-if]
    Where: -clear     clear access list
	   -negative  apply to negative rights
	   -id        initial directory acl (DFS only)
	   -if        initial file acl (DFS only)

The corresponding method invocation looks like:

    my $result = $fs->setacl
      (
       # Required arguments
       dir			=> $dir, # OR [ $dir1, $dir2, ... ]
       acl			=> [ <<see below>> ],
       # Optional arguments
       clear			=> 1,
       negative			=> 1,
       id			=> 1,
       if			=> 1,
      );

NOTE: The values passed to the 'acl' argument has to be constructed
with care.  Unlike many of the other arguments, this has to be a seen
by the 'fs' command as an even number of additional command line
arguments immediately after the -acl flag.

If you construct a single string, such as "user read group write",
then the method will fail.  There is no shell involved in exec'ing fs,
so there will be no splitting of this string on whitespace before we
construct the arguments to fs, so it will look like a single argument,
not four distinct arguments.

Therefore, there are two ways to construct an ACL to pass to setacl():

    my @acl = ( $user, 'read', $group, 'write' );
    my $result = $fs->setacl
      (
       dir			=> $dir,
       acl			=> \@acl,
      );

    my %acl =
      (
       $user			=> 'read',
       $group			=> 'write',
      );
    my $result = $fs->setacl
      (
       dir			=> $dir,
       acl			=> \%acl,
      );

In a future release of the API, maybe even 1.1, it will be possible to
pass AFS::Object::ACL objects as arguments to these API
calls, but not yet...

=head2 setcachesize

The fs help string is:

    fs setcachesize: set cache size
    Usage: fs setcachesize [-blocks <size in 1K byte blocks (0 => reset)>] [-reset]
    Where: -reset  reset size back to boot value

The corresponding method invocation looks like:

    my $result = $fs->setcachesize
      (
       # Optional arguments
       blocks			=> $blocks,
       reset			=> 1,
      );

=head2 setcell

The fs help string is:

    fs setcell: set cell status
    Usage: fs setcell -cell <cell name>+ [-suid] [-nosuid]
    Where: -suid    allow setuid programs
	   -nosuid  disallow setuid programs

The corresponding method invocation looks like: