view release on metacpan or  search on metacpan

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

    10min-1hr |       42 |        0 |       44 |        0 |
    1hr-1day  |       18 |        0 |        6 |        0 |
    1day-1wk  |        0 |        0 |        0 |        0 |
    > 1wk     |        1 |        0 |        0 |        0 |
	      |-------------------------------------------|

Since attributes can most easily be accessed by calling the method of
the same name, one can easily dig into the hierarchy as follows:

    my $result = $vos->examine
      (
       id			=> 'user.wpm',
       cell			=> 'q.ny.ms.com',
       extended			=> 1,
      );

    print $result->raw()->reads()->same()->total();  # 162, in the above output.
    print $result->author()->10min()->dir()->same(); # 44, in the above output.

See?  It's not as ugly as the pedantic description above implies.

=back

=head2 listaddrs

=over

=item Arguments

The vos help string is:

    vos listaddrs: list the IP address of all file servers registered in the VLDB
    Usage: vos listaddrs [-uuid <uuid of server>] [-host <address of host>]
			 [-noresolve] [-printuuid] [-cell <cell name>] [-noauth]
			 [-localauth] [-verbose] [-encrypt] 
    Where: -noresolve  don't resolve addresses
	   -printuuid  print uuid of hosts

The corresponding method invocation looks like:

    my $result = $vos->listaddrs
      (
       # Optional arguments
       uuid			=> $uuid,
       host			=> $host,
       noresolve		=> 1,
       printuuid		=> 1,
       cell			=> $cell,
       noauth			=> 1,
       localauth		=> 1,
       verbose			=> 1,
       encrypt			=> 1,
      );

=item Return Values

This method returns a list of AFS::Object::FileServer
objects, each of which has attributes that vary depending on the
arguments to the method call.

In particular, vos will try to map IP addresses into hostnames, and
this may or may not succeed, depending on the stability and
correctness of the hostname resolution mechanism (usually DNS, of
course, but that is outside of vos' control).

    my @result = $vos->listaddrs
      (
       cell				=> $cell,
      );

    foreach my $result ( @result ) {
	if ( $result->hasAttribute('hostname') {
	    print "Hostname: " . $result-hostname() . "\n";
	} elsif ( $result->hasAttribute('addresses') {
	    my $addresses = $result->addresses();
	    foreach my $address ( @addresses ) {
		print "IP Address: $address\n";
	    }
	}
    }

If a specific 'host' or 'uuid' is specified, then only one object will
be returned (assuming the specified host or uuid is valid, of course,
otherwise, you get nothing).

B<AFS::Object::FileServer>

This object will have one or more of the following attributes,
depending on the choice of arguments to the method, as well as the
ability of vos to map the IP addresses back into hostnames.

    Attributes			Values
    ----------			------
    hostname			Server's hostname (duh)
    addresses			ARRAY reference of IP addresses
    uuid			Servers's UUID (duh)

The 'uuid' will be present if the 'printuuid' or 'uuid' arguments were
passed to the method call.  The 'addresses' will be present either
'noresolve' was specified, or vos has problems with hostname
resolution.

=back

=head2 listpart

=over

=item Arguments

The vos help string is:

    vos listpart: list partitions
    Usage: vos listpart -server <machine name> [-cell <cell name>] [-noauth]
			[-localauth] [-verbose] [-encrypt]

The corresponding method invocation looks like:

    my $result = $vos->listpart
      (
       # Required arguments
       server			=> $server,
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       localauth		=> 1,
       verbose			=> 1,
       encrypt			=> 1,
      );

=item Return Values

This method returns an AFS::Object::FileServer object, which
contains one or more AFS::Object::Partition objects.  Because
'listpart' returns nothing other than the partition names, the
underlying Partition objects have only one attribute ('partition'), so
the API for access this data is trivial:

    my $result = $vos->listpart
      (
       server			=> 'fs1.ms.com',
      ) || die $vos->errors();

    foreach my $partition ( $result->getPartitionNames() ) {
	print "Server '$server' has partition '$partition'\n";
    }

The FileServer object has no attributes at all, it merely contains the
Partition objects.  Since the Partition objects are indexed by name,
there's no need to extract the partition objects and query their

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

few attributes, and contains one or more
AFS::Object::VLDBEntry objects, which in turn contain
AFS::Object::VLDBSite objects, as well as their own
attributes.

NOTE: the VLDBEntry and VLDBSite objects are the same as those used by
the 'examine' method, since that command also queries the VLDB for
part of its return values.  See that discussion above for some
relevant details on the parsing of those objects, which will no be
repeated here.

    my $result = $vos->listvldb
      (
       cell				=> $cell,
      ) || die $vos->errors();

    print("VLDB contains " . $result->total() " volumes, " .
	  $result->locked() . " of which are locked\n");

    foreach my $entry ( $result->getVLDBEntries() ) {
	my $name = $entry->name();
	foreach my $attr ( $entry->listAttributes() ) {
	    print "Volume $name has attribute $attr => " . $entry->$attr() . "\n";
	}
	foreach my $site ( $entry->getVLDBSites() ) {
	    my %attrs = $site->getAttributes();
	    while ( my($attr,$value) = each %attrs ) {
		print "Site has attribute $attr => $value\n";
	    }
	}
    }

Another way to slice and dice this data:

    foreach my $name ( $result->getVolumeNames() ) {
	my $entry = $result->getVLDBEntry( name => $name );
	....
    }

Each of these objects has the following attributes and methods:

B<AFS::Object::VLDB>

This object has two attributes, and several methods:

    Attributes			Values
    ----------			------
    total			Number of VLDBEntries in the results
    locked			Number of locked volumes in the results

    Methods			Returns
    -------			-------
    getVolumeNames()		list of volume names in the results
    getVolumeIds()		list of numeric volume IDs
    getVLDBEntry(name => $name)	the AFS::Object::VLDBEntry for name $name
    getVLDBEntry(id => $id)	the AFS::Object::VLDBEntry for id $id
    getVLDBEntries()		list of AFS::Object::VLDBEntry objects
    getVLDBEntryByName($name)   the AFS::Object::VLDBEntry for $name
    getVLDBEntryById($id)   	the AFS::Object::VLDBEntry for $id

NOTE: name to volume mappings are one to one, but id to volume
mappings are many to one, since a single logical VLDB entry can have
several IDs associated with it (RW, RO, BK, and/or RC).

B<AFS::Object::VLDBEntry>

This object also has a few attributes, and a few methods.  The 'name'
attribute is always present, but the others vary, depending on the
volume (again, see the 'examine' documentation for more verbosity).

    Attributes			Values
    ----------			------
    name			Volume name
    rwrite			Numeric Volume ID for the RW volume
    ronly			Numeric Volume ID for the RO volume
    backup			Numeric Volume ID for the BK volume
    rclone			Numeric Volume ID for the RClone volume, if present
    locked			Boolean, indicating whether or not the VLDB entry is locked

    Methods			Returns
    -------			-------
    getVLDBSites()		list of AFS::Object::VLDBSite objects

B<AFS::Object::VLDBSite>

The following attributes are always available:

    Attributes			Values
    ----------			------
    server			Fileserver hostname
    partition			Fileserver /vice partition name
    type			"RO" | "RW" | "BK"
    status			Site status.

This object has no special methods.

=back

=head2 listvol

=over

=item Arguments

The vos help string is:

    vos listvol: list volumes on server (bypass VLDB)
    Usage: vos listvol -server <machine name> [-partition <partition name>]
		       [-fast] [-long] [-quiet] [-extended] [-cell <cell name>]
		       [-noauth] [-localauth] [-verbose] [-encrypt] 
    Where: -fast       minimal listing
	   -long       list all normal volume fields
	   -quiet      generate minimal information
	   -extended   list extended volume fields

The corresponding method invocation looks like:

    my $result = $vos->listvol
      (
       # Required arguments
       server			=> $server,
       # Optional arguments