#
# $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

=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
have the following attributes:

    Attributes			Values
    ----------			------
    path			The pathname
    error			The error string for that path

If no errors were encountered, then the following attributes will be present:

    Attributes			Values
    ----------			------
    path			The pathname
    volname			The AFS volume name that contains the pathname
    total			The size (in KB) of the partition that contains 'volname'
    used			The amount of space (in KB) used on that partition
    avail			The amount of space (in KB) available on that partition
    percent			The amount of space used, as a percentage

=back

=head2 examine

=over

=item Arguments

The fs help string is:

    fs examine: display volume status
    Usage: fs examine [-path <dir/file path>+]

The corresponding method invocation looks like:

    my $result = $fs->examine
      (
       # 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->examine
      (
       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( id volname quota used avail total ) ) {
		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
have the following attributes:

    Attributes			Values
    ----------			------
    path			The pathname
    error			The error string for that path

If no errors were encountered, then the following attributes will be present:

    Attributes			Values
    ----------			------
    path			The pathname
    volname			The AFS volume name that contains the pathname
    id				The numerical volume ID of the above volume
    total			The size (in KB) of the partition that contains 'volname'
    used			The amount of space (in KB) used on that partition
    avail			The amount of space (in KB) available on that partition
    quota			The quota of the volume (in KB), or 0 if set to "unlimited"

=back

=head2 exportafs

=over

=item Arguments

The fs help string is:

    fs exportafs: enable/disable translators to AFS
    Usage: fs exportafs -type <exporter name> [-start <start/stop translator (on | off)>]
		       [-convert <convert from afs to unix mode (on | off)>]
		       [-uidcheck <run on strict 'uid check' mode (on | off)>]
		       [-submounts <allow nfs mounts to subdirs of /afs/.. (on  | off)>]

The corresponding method invocation looks like:

    my $result = $fs->exportafs
      (
       # Required arguments
       type			=> $type,	# 'nfs' is the only supported value
       # Optional arguments
       start			=> $start,	# 'on' or 'off'
       convert			=> $convert,	# 'on' or 'off'
       uidcheck			=> $uidcheck,	# 'on' or 'off'
       submounts		=> $submounts,	# 'on' or 'off'
      );

NOTE: In a future release, the 4 optional arguments will probably take
boolean values, with "off" being a special case that means false, in
order to simply the interface (and be backwards compatible).

=item Return Values

This method returns an AFS::Object::CacheManager object with one or
more attributes.

    my $result = $fs->exportafs
      (
       type			=> 'nfs',
       start			=> 'on',
      ) || die $fs->errors();
    foreach my $attr ( qw( convert uidcheck submounts ) ) {
	print "Translator has '$attr' set to '" . $result->$attr() . "'\n";
    }

The object has the following attribute:

B<AFS::Object::CacheManager>

    Attributes			Values
    ----------			------
    enabled			Boolean, true means the translator is on, false means off
    convert			Boolean, true means mode bits are converted from AFS to UNIX, false means off
    uidcheck			Boolean, true means strict uid checking mode is on, false means off
    submounts			Boolean, true means mounts of subdirs are allowed, false means disallowed

=back

=head2 getcacheparms

=over

=item Arguments

The fs help string is:

    fs getcacheparms: get cache usage info
    Usage: fs getcacheparms

The corresponding method invocation looks like:

    my $result = $fs->getcacheparms();

=item Return Values

This method returns an AFS::Object::CacheManager object with one or
more attributes.

    my $result = $fs->getcacheparms() || die $fs->errors();
    my $used = $result->used();
    my $avail = $result->avail();
    print "Cache is using $used KB of $availa KB available\n";

The object has the following attributes:

B<AFS::Object::CacheManager>

    Attributes			Values
    ----------			------
    used			Number of KB of the AFS cache in use
    avail			Size of the AFS cache, in KB

=back

=head2 getcellstatus

=over

=item Arguments

The fs help string is:

    fs getcellstatus: get cell status
    Usage: fs getcellstatus -cell <cell name>+

The corresponding method invocation looks like:

    my $result = $fs->getcellstatus
      (
       # Required arguments
       cell			-> $cell, # OR [ $cell1, $cell2, ... ]
      );

=item Return Values

This method returns an AFS::Object::CacheManager object which contains
one or more AFS::Object::Cell objects.

    my $result = $fs->getcellstatus
      (
       cell			=> [ $cell1 , $cell2 ],
      ) || die $fs->errors();
    foreach my $cellobj ( $result->getCells() ) {
	my $cell = $cellobj->cell();
	if ( $cellobj->status() ) {
	    print("This client allows setuid binaries from cell '$cell'\n";
	} else {
	    print("This client does NOT allow setuid binaries from cell '$cell'\n";
	}
    }

The objects have the following attributes and methods:

B<AFS::Object::CacheManager>

    Methods			Returns
    -------			-------
    getCellNames()		list of cell names
    getCells()			list of AFS::Object::Cell objects
    getCell($cell)		the AFS::Object::Cell object for cell $cell

B<AFS::Object::Cell>

    Attributes			Values
    ----------			------
    cell			AFS cell name
    status			Boolean, true indicating setuid/gid bits are allowed,
				false indicating they are not

=back

=head2 getclientaddrs

=over

=item Arguments

The fs help string is:

    fs getclientaddrs: get client network interface addresses
    Usage: fs getclientaddrs

The corresponding method invocation looks like:

    my $result = $fs->getclientaddrs();

=item Return Values

This method returns an AFS::Object::CacheManager object with one attribute.

    my $result = $fs->getclientaddrs() || die $fs->errors();
    print "This client has the following addressed configured for AFS:\n";
    foreach my $address ( @{$result->addresses()} ) {
	print "\t$address\n";
    }

The object has the following attribute:

B<AFS::Object::CacheManager>

    Attributes			Values
    ----------			------
    addresses			ARRAY reference of IP addresses

=back

=head2 getcrypt

=over

=item Arguments

The fs help string is:

    fs getcrypt: set cache manager encryption flag
    Usage: fs getcrypt

The corresponding method invocation looks like:

    my $result = $fs->getcrypt();

=item Return Values

This method returns an AFS::Object::CacheManager object with one attribute.

    my $result = $fs->getcrypt() || die $fs->errors();
    print "This client has encryption turned " . ( $result->crypt() ? "on" : "off" ) . "\n";

The object has the following attribute:

B<AFS::Object::CacheManager>

    Attributes			Values
    ----------			------
    crypt			Boolean, indicating whether or not encryption is enabled

=back

=head2 getserverprefs

=over

=item Arguments

The fs help string is:

    fs getserverprefs: get server ranks
    Usage: fs getserverprefs [-file <output to named file>] [-numeric] [-vlservers]
    Where: -numeric    addresses only
	   -vlservers  VL servers

The corresponding method invocation looks like:

    my $result = $fs->getserverprefs
      (
       # Optional arguments
       file			=> $file,
       numeric			=> 1,
       vlservers		=> 1,
      );

=item Return Values

This method returns an AFS::Object::CacheManager object which contains
one or more AFS::Object::Server objects.

    my $result = $fs->getserverprefs() || die $fs->errors();
    foreach my $serverobj ( $result->getServers() ) {
	my $server = $serverobj->server();
	my $pref = $serverobj->preference();
	print "Server '$server' has preference '$preference'\n";
    }

The objects have the following attributes and methods:

B<AFS::Object::CacheManager>

    Methods			Returns
    -------			-------
    getServerNames()		list of server hostnames (or addresses)
    getServers()		list of AFS::Object::Server objects
    getServer($server)		the AFS::Object::Server object for server $server

B<AFS::Object::Server>

    Attributes			Values
    ----------			------
    server			Hostname or IP address of the server
    preference			Numeric preference value

=back

=head2 listacl

=over

=item Arguments

The fs help string is:

    fs listacl: list access control list
    Usage: fs listacl [-path <dir/file path>+] [-id] [-if]
    Where: -id  initial directory acl
	   -if  initial file acl

The corresponding method invocation looks like:

    my $result = $fs->listacl
      (
       # Required arguments
       path			=> $path, # OR [ $path1, $path2, ... ]
       # Optional arguments
       id			=> 1,
       if			=> 1,
      );

=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.  Each AFS::Object::Path object contains
one or two AFS::Object::ACL objects (one for normal, and one for
negative).

    my $result = $fs->listacl
      (
       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 $type ( qw( normal negative ) ) {
		my $acl = $pathobj->getACL($type);
		my %entries = $acl->getEntries();
		foreach my $principal ( keys %entries ) {
		    my $rights = $acl->getRights($principal);
		    print "$type rights for $principal are $rights\n";
		}
	    }
	}
    }

The objects have 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>

    Methods			Returns
    -------			-------
    getACLNormal()		the AFS::Object::ACL object for the normal rights
    getACLNegative()		the AFS::Object::ACL object for the negative rights
    getACL($type)		the AFS::Object::ACL object for rights of type $type,
				where $type is either 'normal' or 'negative'

B<AFS::Object::ACL>

    Methods			Returns
    -------			-------
    getPrincipals()		a list of the principals (users, groups) on the ACL
    getRights($principal)	the rights (permissions) of the specified $principal
    getEntries()		a list of key/value pairs, where the keys are the principals,
				and the values are the rights for that principal

=back

=head2 listaliases

=over

=item Arguments

The fs help string is:

    fs listaliases: list configured cell aliases
    Usage: fs listaliases

The corresponding method invocation looks like:

    my $result = $fs->listaliases();

=item Return Values

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

    my $result = $fs->listaliases() || die $fs->errors();
    foreach my $cellobj ( $result->getCells() ) {
	my $cell = $cellobj->cell();
	my $alias = $cellobj->alias();
	print "Cell '$cell' has alias '$alias'\n";
    }

The objects have the following attributes and methods:

B<AFS::Object::CacheManager>

    Methods			Returns
    -------			-------
    getCellNames()		list of cell names
    getCells()			list of AFS::Object::Cell objects
    getCell($cell)		the AFS::Object::Cell object for cell $cell

B<AFS::Object::Cell>

    Attributes			Values
    ----------			------
    cell			AFS cell name
    alias			Alias name for this cell

=back

=head2 listcells

=over

=item Arguments

The fs help string is:

    fs listcells: list configured cells
    Usage: fs listcells [-numeric]
    Where: -numeric  addresses only

The corresponding method invocation looks like:

    my $result = $fs->listcells
      (
       # Optional arguments
       numeric			=> 1,
      );

=item Return Values

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

    my $result = $fs->listcells() || die $fs->errors();
    foreach my $cellobj ( $result->getCells() ) {
	my $servers = $cellobj->servers();
	print "Cell $cell has servers " . join(" ",@$servers) . "\n";
    }

The objects have the following attributes and methods:

B<AFS::Object::CacheManager>

    Methods			Returns
    -------			-------
    getCellNames()		list of cell names
    getCells()			list of AFS::Object::Cell objects
    getCell($cell)		the AFS::Object::Cell object for cell $cell

B<AFS::Object::Cell>

    Attributes			Values
    ----------			------
    cell			AFS cell name
    servers			ARRAY reference of strings, each of which is
				the hostname of a server

=back

=head2 listquota

=over

=item Arguments

The fs help string is:

    fs listquota: list volume quota
    Usage: fs listquota [-path <dir/file path>+]

The corresponding method invocation looks like:

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

=item Return Values

=back

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->listquota
      (
       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 quota used percent partition ) ) {
		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
have the following attributes:

    Attributes			Values
    ----------			------
    path			The pathname
    error			The error string for that path

If no errors were encountered, then the following attributes will be present:

    Attributes			Values
    ----------			------
    path			The pathname
    volname			The AFS volume name that contains the pathname
    quota			Volume quota, in KB
    used			The amount of space (in KB) used in that volume
    percent			The percentage of the allocated quota in use
    partition			The percentage of space used on the partition where the volume resides

=head2 lsmount

=over

=item Arguments

The fs help string is:

    fs lsmount: list mount point
    Usage: fs lsmount -dir <directory>+

The corresponding method invocation looks like:

    my $result = $fs->lsmount
      (
       # Required arguments
       dir			=> $dir, # OR [ $dir1, $dir2, ... ]
      );

=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->lsmount
      (
       dir			=> [ $dir1, $dir2 ],
      ) || 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 {
            my $volname = $pathobj->volname();
            my $cell = $pathobj->cell();
            print("Path '$path' is a mtpt for volume $volname" .
                  ( $cell ? ", in cell '$cell'\n" : "\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
have the following attributes:

    Attributes			Values
    ----------			------
    path			The pathname
    error			The error string for that path

If no errors were encountered, then the following attributes will
always be present:

    Attributes			Values
    ----------			------
    path			The pathname
    volname			AFS volname in the mount point

The following attributes may or may not be present:

    Attributes			Values
    ----------			------
    symlink			Boolean, true if the pathname is a symlink to a mount point
    readwrite			Boolean, true if the mount point is explicitly readwrite
    cell			AFS cell name in the mount point

=back

=head2 quota

=over

=item Arguments

The fs help string is:

    fs quota: show volume quota usage
    Usage: fs quota [-path <dir/file path>+]

The corresponding method invocation looks like:

    my $result = $fs->quota
      (
       # 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->quota
      (
       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 {
            print "Path '$path' has quota '" . $pathobj->quota() . "'\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
have the following attributes:

    Attributes			Values
    ----------			------
    path			The pathname
    error			The error string for that path

If no errors were encountered, then the following attributes will be present:

    Attributes			Values
    ----------			------
    path			The pathname
    quota			The percentage of the allocated quota in use

=back

=head2 storebehind

=over

=item Arguments

The fs help string is:

    fs storebehind: store to server after file close
    Usage: fs storebehind [-kbytes <asynchrony for specified names>]
			  [-files <specific pathnames>+] [-allfiles <new default (KB)>]
			  [-verbose]
    Where: -verbose  show status

The corresponding method invocation looks like:

    my $result = $fs->storebehind
      (
       # Optional arguments
       kbytes			=> $kbytes,
       files			=> $file, # OR [ $file1, $file2, ... ]
       allfiles			=> $default,
       verbose			=> 1,
      );

=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->quota
      (
       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 quota used percent partition ) ) {
		print "Path '$path' has '$attr' of '" . $pathobj->$attr() . "'\n";
	    }
	}
    }

Each of these objects has the following attributes and methods:

B<AFS::Object::CacheManager>

    Attributes			Values
    ----------			------
    asynchrony			Default value (in KB) of asynchronous writes

    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
have the following attributes:

    Attributes			Values
    ----------			------
    path			The pathname
    error			The error string for that path

If no errors were encountered, then the following attributes will be present:

    Attributes			Values
    ----------			------
    path			The pathname
    asynchrony			The number of KB of asynchronous writes for this file

=back

=head2 sysname

=over

=item Arguments

The fs help string is:

    fs sysname: get/set sysname (i.e. @sys) value
    Usage: fs sysname [-newsys <new sysname>+]

The corresponding method invocation looks like:

    my $result = $fs->sysname
      (
       # Optional arguments
       newsys			=> $sysname, # OR [ $sysname1, $sysname2, ... ]
      );

=item Return Values

This method returns an AFS::Object::CacheManager object which has one
of two possible attributes.

    my $result = $fs->sysname() || die $fs->errors();
    my $sysname = $result->sysname();
    my $sysnames = $result->sysnames();
    print "This client has a primary sysname of '$sysname'\n";
    if ( ref $sysnames eq 'ARRAY' ) {
	print "This client has a list of sysnames: " . join(" ,",@$sysnames) . "\n";
    }

The object has the following attributes:

B<AFS::Object::CacheManager>

    Attributes			Values
    ----------			------
    sysname			The primary sysname of the client
    sysnames			An ARRAY reference of sysnames

NOTE: When a list of sysnames has been configured on the client, then
the 'sysname' attribute is simnply the first one in the list.

=back

=head2 whereis

=over

=item Arguments

The fs help string is:

    fs whereis: list file's location
    Usage: fs whereis [-path <dir/file path>+]

The corresponding method invocation looks like:

    my $result = $fs->whereis
      (
       # 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->whereis
      (
       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 {
            print "Path '$path' is on hosts " . join(" ,",@{pathobj->hosts()}) . "\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
have the following attributes:

    Attributes			Values
    ----------			------
    path			The pathname
    error			The error string for that path

If no errors were encountered, then the following attributes will be present:

    Attributes			Values
    ----------			------
    path			The pathname
    hosts			An ARRAY reference of hostnames

=back

=head2 whichcell

=over

=item Arguments

The fs help string is:

    fs whichcell: list file's cell
    Usage: fs whichcell [-path <dir/file path>+]

The corresponding method invocation looks like:

    my $result = $fs->whichcell
      (
       # 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->whichcell
      (
       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 {
            print "Path '$path' is in cell '" . $pathobj->cell() . "'\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
have the following attributes:

    Attributes			Values
    ----------			------
    path			The pathname
    error			The error string for that path

If no errors were encountered, then the following attributes will be present:

    Attributes			Values
    ----------			------
    path			The pathname
    cell			Cell in which the pathname lives

=back

=head2 wscell

=over

=item Arguments

The fs help string is:

    fs wscell: list workstation's cell
    Usage: fs wscell

The corresponding method invocation looks like:

    my $result = $fs->wscell();

=item Return Values

This method returns an AFS::Object::CacheManager object which has one
attribute.

    my $result = $fs->wscell() || die $fs->errors();
    print "This client lives in cell '" . $result->cell() . "'\n";

The object has the following attribute:

    Attributes			Values
    ----------			------
    cell			The AFS cell of the client

=back

=head1 METHODS (with simple return values)

=head2 checkvolumes

The fs help string is:

    fs checkvolumes: check volumeID/name mappings
    Usage: fs checkvolumes

The corresponding method invocation looks like:

    my $result = $fs->checkvolumes();

=head2 cleanacl

The fs help string is:

    fs cleanacl: clean up access control list
    Usage: fs cleanacl [-path <dir/file path>+]

The corresponding method invocation looks like:

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

=head2 copyacl

The fs help string is:

    fs copyacl: copy access control list
    Usage: fs copyacl -fromdir <source directory (or DFS file)>
		      -todir <destination directory (or DFS file)>+
		      [-clear] [-id] [-if]
    Where: -clear  first clear dest access list
	   -id     initial directory acl
	   -if     initial file acl

The corresponding method invocation looks like:

    my $result = $fs->copyacl
      (
       # Required arguments
       fromdir			=> $fromdir,
       todir			=> $todir, # OR [ $todir1, $todir2, ... ]
       # Optional arguments
       clear			=> 1,
       id			=> 1,
       if			=> 1,
      );

=head2 flush

The fs help string is:

    fs flush: flush file from cache
    Usage: fs flush [-path <dir/file path>+]

The corresponding method invocation looks like:

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

=head2 flushmount

The fs help string is:

    fs flushmount: flush mount symlink from cache
    Usage: fs flushmount [-path <dir/file path>+]

The corresponding method invocation looks like:

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

=head2 flushvolume

The fs help string is:

    fs flushvolume: flush all data in volume
    Usage: fs flushvolume [-path <dir/file path>+]

The corresponding method invocation looks like:

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

=head2 messages

The fs help string is:

    fs messages: control Cache Manager messages
    Usage: fs messages [-show <[user|console|all|none]>]

The corresponding method invocation looks like:

    my $result = $fs->messages
      (
       # Optional arguments
       show			=> $show,
      );

=head2 mkmount

The fs help string is:

    fs mkmount: make mount point
    Usage: fs mkmount -dir <directory> -vol <volume name> [-cell <cell name>] [-rw] [-fast]
    Where: -rw    force r/w volume
	   -fast  don't check name with VLDB

The corresponding method invocation looks like:

    my $result = $fs->mkmount
      (
       # Required arguments
       dir			=> $dir,
       vol			=> $vol,
       # Optional arguments
       cell			=> $cell,
       rw			=> 1,
       fast			=> 1,
      );

=head2 newalias

The fs help string is:

    fs newalias: configure new cell alias
    Usage: fs newalias -alias <alias name> -name <real name of cell>

The corresponding method invocation looks like:

    my $result = $fs->newalias
      (
       # Required arguments
       alias			=> $alias,
       name			=> $name,
      );

=head2 newcell

The fs help string is:

    fs newcell: configure new cell
    Usage: fs newcell -name <cell name> -servers <primary servers>+
		      [-linkedcell <linked cell name>]

The corresponding method invocation looks like:

    my $result = $fs->newcell
      (
       # Required arguments
       name			=> $name,
       servers			=> $server, # OR [ $server1, $server2, ... ]
       # Optional arguments
       linkedcell		=> $linkedcell,
      );

=head2 rmmount

The fs help string is:

    fs rmmount: remove mount point
    Usage: fs rmmount -dir <directory>+

The corresponding method invocation looks like:

    my $result = $fs->rmmount
      (
       # Required arguments
       dir			=> $dir, # OR [ $dir1, $dir2, ... ]
      );

=head2 rxstatpeer

The fs help string is:

    fs rxstatpeer: Manage per peer RX statistics
    Usage: fs rxstatpeer [-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->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:

    my $result = $fs->setcell
      (
       # Required arguments
       cell			=> $cell, # OR [ $cell1, $cell2, ... ]
       # Optional arguments
       suid			=> 1,
       nosuid			=> 1,
      );

=head2 setclientaddrs

The fs help string is:

    fs setclientaddrs: set client network interface addresses
    Usage: fs setclientaddrs [-address <client network interfaces>+]

The corresponding method invocation looks like:

    my $result = $fs->setclientaddrs
      (
       # Required arguments
       address			=> $address, # OR [ $address1, $address2, ... ]
      );

=head2 setcrypt

The fs help string is:

    fs setcrypt: set cache manager encryption flag
    Usage: fs setcrypt -crypt <on or off>

The corresponding method invocation looks like:

    my $result = $fs->setcrypt
      (
       # Required arguments
       crypt			=> 1,
      );

=head2 setquota

The fs help string is:

    fs setquota: set volume quota
    Usage: fs setquota [-path <dir/file path>] -max <max quota in kbytes>

The corresponding method invocation looks like:

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

=head2 setserverprefs

The fs help string is:

    fs setserverprefs: set server ranks
    Usage: fs setserverprefs [-servers <fileserver names and ranks>+]
			     [-vlservers <VL server names and ranks>+]
			     [-file <input from named file>] [-stdin]
    Where: -stdin  input from stdin

The corresponding method invocation looks like:

    my $result = $fs->setserverprefs
      (
       # Optional arguments
       servers			=> $server, # OR [ $server1, $server2, ... ]
       vlservers		=> $vlserver, # OR [ $vlserver1, $vlserver2, ... ]
       file			=> $file,
       stdin			=> 1,
      );

=head2 setvol

The fs help string is:

    fs setvol: set volume status
    Usage: fs setvol [-path <dir/file path>+] [-max <disk space quota in 1K units>]
		     [-offlinemsg <offline message>]

The corresponding method invocation looks like:

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

=head1 SEE ALSO

AFS::Command(1), AFS::Object(1)

=cut

