AFS::Command::FS - OO API to the AFS fs command
use AFS::Command::FS; my $fs = AFS::Command::FS->new(); my $fs = AFS::Command::FS->new ( command => $path_to_your_fs_binary, );
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.
All of the following methods are inherited from the AFS::Command::Base class. See that documentation for details.
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.
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, );
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.
fs diskfree: show server disk space usage Usage: fs diskfree [-path <dir/file path>+]
my $result = $fs->diskfree ( # Optional arguments path => $path, # OR [ $path1, $path2, ... ] );
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:
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
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
fs examine: display volume status Usage: fs examine [-path <dir/file path>+]
my $result = $fs->examine ( # Optional arguments path => $path, # OR [ $path1, $path2, ... ] );
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"; } } }
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"
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)>]
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).
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:
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
fs getcacheparms: get cache usage info Usage: fs getcacheparms
my $result = $fs->getcacheparms();
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";
Attributes Values ---------- ------ used Number of KB of the AFS cache in use avail Size of the AFS cache, in KB
fs getcellstatus: get cell status Usage: fs getcellstatus -cell <cell name>+
my $result = $fs->getcellstatus ( # Required arguments cell -> $cell, # OR [ $cell1, $cell2, ... ] );
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:
Methods Returns ------- ------- getCellNames() list of cell names getCells() list of AFS::Object::Cell objects getCell($cell) the AFS::Object::Cell object for cell $cell
AFS::Object::Cell
Attributes Values ---------- ------ cell AFS cell name status Boolean, true indicating setuid/gid bits are allowed, false indicating they are not
fs getclientaddrs: get client network interface addresses Usage: fs getclientaddrs
my $result = $fs->getclientaddrs();
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"; }
Attributes Values ---------- ------ addresses ARRAY reference of IP addresses
fs getcrypt: set cache manager encryption flag Usage: fs getcrypt
my $result = $fs->getcrypt();
my $result = $fs->getcrypt() || die $fs->errors(); print "This client has encryption turned " . ( $result->crypt() ? "on" : "off" ) . "\n";
Attributes Values ---------- ------ crypt Boolean, indicating whether or not encryption is enabled
fs getserverprefs: get server ranks Usage: fs getserverprefs [-file <output to named file>] [-numeric] [-vlservers] Where: -numeric addresses only -vlservers VL servers
my $result = $fs->getserverprefs ( # Optional arguments file => $file, numeric => 1, vlservers => 1, );
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"; }
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
AFS::Object::Server
Attributes Values ---------- ------ server Hostname or IP address of the server preference Numeric preference value
fs listacl: list access control list Usage: fs listacl [-path <dir/file path>+] [-id] [-if] Where: -id initial directory acl -if initial file acl
my $result = $fs->listacl ( # Required arguments path => $path, # OR [ $path1, $path2, ... ] # Optional arguments id => 1, if => 1, );
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"; } } } }
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'
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
fs listaliases: list configured cell aliases Usage: fs listaliases
my $result = $fs->listaliases();
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"; }
Attributes Values ---------- ------ cell AFS cell name alias Alias name for this cell
fs listcells: list configured cells Usage: fs listcells [-numeric] Where: -numeric addresses only
my $result = $fs->listcells ( # Optional arguments numeric => 1, );
my $result = $fs->listcells() || die $fs->errors(); foreach my $cellobj ( $result->getCells() ) { my $servers = $cellobj->servers(); print "Cell $cell has servers " . join(" ",@$servers) . "\n"; }
Attributes Values ---------- ------ cell AFS cell name servers ARRAY reference of strings, each of which is the hostname of a server
fs listquota: list volume quota Usage: fs listquota [-path <dir/file path>+]
my $result = $fs->listquota ( # Optional arguments path => $path, # OR [ $path1, $path2, ... ] );
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"; } } }
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
fs lsmount: list mount point Usage: fs lsmount -dir <directory>+
my $result = $fs->lsmount ( # Required arguments dir => $dir, # OR [ $dir1, $dir2, ... ] );
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" )); } }
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
fs quota: show volume quota usage Usage: fs quota [-path <dir/file path>+]
my $result = $fs->quota ( # Optional arguments path => $path, # OR [ $path1, $path2, ... ] );
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"; } }
Attributes Values ---------- ------ path The pathname quota The percentage of the allocated quota in use
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
my $result = $fs->storebehind ( # Optional arguments kbytes => $kbytes, files => $file, # OR [ $file1, $file2, ... ] allfiles => $default, verbose => 1, );
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"; } } }
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
Attributes Values ---------- ------ path The pathname asynchrony The number of KB of asynchronous writes for this file
fs sysname: get/set sysname (i.e. @sys) value Usage: fs sysname [-newsys <new sysname>+]
my $result = $fs->sysname ( # Optional arguments newsys => $sysname, # OR [ $sysname1, $sysname2, ... ] );
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"; }
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.
fs whereis: list file's location Usage: fs whereis [-path <dir/file path>+]
my $result = $fs->whereis ( # Optional arguments path => $path, # OR [ $path1, $path2, ... ] );
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"; } }
Attributes Values ---------- ------ path The pathname hosts An ARRAY reference of hostnames
fs whichcell: list file's cell Usage: fs whichcell [-path <dir/file path>+]
my $result = $fs->whichcell ( # Optional arguments path => $path, # OR [ $path1, $path2, ... ] );
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"; } }
Attributes Values ---------- ------ path The pathname cell Cell in which the pathname lives
fs wscell: list workstation's cell Usage: fs wscell
my $result = $fs->wscell();
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";
Attributes Values ---------- ------ cell The AFS cell of the client
fs checkvolumes: check volumeID/name mappings Usage: fs checkvolumes
my $result = $fs->checkvolumes();
fs cleanacl: clean up access control list Usage: fs cleanacl [-path <dir/file path>+]
my $result = $fs->cleanacl ( # Optional arguments path => $path, # OR [ $path1, $path2, ... ] );
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
my $result = $fs->copyacl ( # Required arguments fromdir => $fromdir, todir => $todir, # OR [ $todir1, $todir2, ... ] # Optional arguments clear => 1, id => 1, if => 1, );
fs flush: flush file from cache Usage: fs flush [-path <dir/file path>+]
my $result = $fs->flush ( # Optional arguments path => $path, # OR [ $path1, $path2, ... ] );
fs flushmount: flush mount symlink from cache Usage: fs flushmount [-path <dir/file path>+]
my $result = $fs->flushmount ( # Optional arguments path => $path, # OR [ $path1, $path2, ... ] );
fs flushvolume: flush all data in volume Usage: fs flushvolume [-path <dir/file path>+]
my $result = $fs->flushvolume ( # Optional arguments path => $path, # OR [ $path1, $path2, ... ] );
fs messages: control Cache Manager messages Usage: fs messages [-show <[user|console|all|none]>]
my $result = $fs->messages ( # Optional arguments show => $show, );
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
my $result = $fs->mkmount ( # Required arguments dir => $dir, vol => $vol, # Optional arguments cell => $cell, rw => 1, fast => 1, );
fs newalias: configure new cell alias Usage: fs newalias -alias <alias name> -name <real name of cell>
my $result = $fs->newalias ( # Required arguments alias => $alias, name => $name, );
fs newcell: configure new cell Usage: fs newcell -name <cell name> -servers <primary servers>+ [-linkedcell <linked cell name>]
my $result = $fs->newcell ( # Required arguments name => $name, servers => $server, # OR [ $server1, $server2, ... ] # Optional arguments linkedcell => $linkedcell, );
fs rmmount: remove mount point Usage: fs rmmount -dir <directory>+
my $result = $fs->rmmount ( # Required arguments dir => $dir, # OR [ $dir1, $dir2, ... ] );
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
my $result = $fs->rxstatpeer ( # Optional arguments enable => 1, disable => 1, clear => 1, );
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
my $result = $fs->rxstatproc ( # Optional arguments enable => 1, disable => 1, clear => 1, );
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)
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...
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
my $result = $fs->setcachesize ( # Optional arguments blocks => $blocks, reset => 1, );
fs setcell: set cell status Usage: fs setcell -cell <cell name>+ [-suid] [-nosuid] Where: -suid allow setuid programs -nosuid disallow setuid programs
my $result = $fs->setcell ( # Required arguments cell => $cell, # OR [ $cell1, $cell2, ... ] # Optional arguments suid => 1, nosuid => 1, );
fs setclientaddrs: set client network interface addresses Usage: fs setclientaddrs [-address <client network interfaces>+]
my $result = $fs->setclientaddrs ( # Required arguments address => $address, # OR [ $address1, $address2, ... ] );
fs setcrypt: set cache manager encryption flag Usage: fs setcrypt -crypt <on or off>
my $result = $fs->setcrypt ( # Required arguments crypt => 1, );
fs setquota: set volume quota Usage: fs setquota [-path <dir/file path>] -max <max quota in kbytes>
my $result = $fs->setquota ( # Required arguments max => $max, # Optional arguments path => $path, # OR [ $path1, $path2, ... ] );
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
my $result = $fs->setserverprefs ( # Optional arguments servers => $server, # OR [ $server1, $server2, ... ] vlservers => $vlserver, # OR [ $vlserver1, $vlserver2, ... ] file => $file, stdin => 1, );
fs setvol: set volume status Usage: fs setvol [-path <dir/file path>+] [-max <disk space quota in 1K units>] [-offlinemsg <offline message>]
my $result = $fs->setvol ( # Optional arguments path => $path, # OR [ $path1, $path2, ... ] max => $max, offlinemsg => $offlinemsg, );
AFS::Command(1), AFS::Object(1)
To install AFS::Object, copy and paste the appropriate command in to your terminal.
cpanm
cpanm AFS::Object
CPAN shell
perl -MCPAN -e shell install AFS::Object
For more information on module installation, please visit the detailed CPAN module installation guide.