AFS-Command
view release on metacpan or search on metacpan
lib/AFS/Command/VOS.pod view on Meta::CPAN
filterin => [
[ 'command1', '-arg1', '-value1' ],
[ 'command2', '-arg2', '-value2' ],
[ 'command3', '-arg3', '-value3' ],
],
...
);
If B<ANY> of the filterin commands exits with a non-zero status, then
the entire restore method invocation is considered to fail. You may
or may not get a valid volume restored to your fileserver, depending
on the behavior of the commands you specify.
=back
=head1 METHODS (with complex return values)
=head2 examine
=over
=item Arguments
The vos help string is:
vos examine: everything about the volume
Usage: vos examine -id <volume name or ID> [-extended] [-cell <cell name>]
[-noauth] [-localauth] [-verbose] [-encrypt]
Where: -extended list extended volume fields
The corresponding method invocation looks like:
my $result = $vos->examine
(
# Required arguments
id => $id,
# Optional arguments
cell => $cell,
extended => 1,
noauth => 1,
localauth => 1,
verbose => 1,
encrypt => 1,
);
=item Return Values
This method returns an AFS::Object::Volume object, which in
turn contains one or more AFS::Object::VolumeHeader objects,
as well as an AFS::Object::VLDBEntry, which contains one or
more AFS::Object::VLDBSite objects.
my $result = $vos->examine
(
id => $volname,
cell => $cell,
) || die $vos->errors();
foreach my $header ( $result->getVolumeHeaders() ) {
my ($server,$partition) = ($header->server(),$header->partition());
print "[header] server = $server, partition = $partition\n";
}
my $vldbentry = $result->getVLDBEntry();
foreach my $vldbsite ( $vldbentry->getVLDBSites() ) {
my ($server,$partition) = ($vldbsite->server(),$vldbsite->partition());
print "[vldbsite] server = $server, partition = $partition\n";
}
Each of these objects has the following attributes and methods:
B<AFS::Object::Volume>
This object is nothing more than a container for the VolumeHeader and
VLDBEntry objects, and has no attributes of its own. It has two
methods for extracting the objects it contains.
Methods Returns
------- -------
getVLDBEntry() a single AFS::Object::VLDBEntry object
getVolumeHeaders() list of AFS:Command::Result::VolumeHeader objects
B<AFS::Object::VLDBEntry>
This object is created by parsing this stanza of output:
root.afs
RWrite: 536918445 ROnly: 536918450
number of sites -> 6
server pasafq3 partition /vicepc RW Site
server pasafq3 partition /vicepc RO Site
server pasafq1 partition /viceph RO Site
server pasafq2 partition /vicepg RO Site
server pasafq4 partition /vicepc RO Site
server pasafq5 partition /vicepg RO Site
The object attributes are taken from the first two lines of output:
root.afs
RWrite: 536918445 ROnly: 536918450
The following attributes should always be present:
Attributes Values
---------- ------
name Volume name
rwrite Numeric Volume ID for the RW volume
locked Boolean value, indicating the VLDB entry is locked or not
The following attributes may be present, if there are volumes of the
associated type in the VLDB entry:
Attributes Values
---------- ------
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
Note that the 'rclone' attribute is only present if the volume was
actively being cloned while being examined. This is true when a 'vos
release' command is actively updating the RO volumes.
The following methods are available:
Methods Returns
------- -------
getVLDBSites() list of AFS::Object::VLDBSite objects
lib/AFS/Command/VOS.pod view on Meta::CPAN
1min Generic AFS::Object object
10min Generic AFS::Object object
1hr Generic AFS::Object object
1day Generic AFS::Object object
1wk Generic AFS::Object object
Each of the above interval value objects has the following attributes:
Attributes Values
---------- ------
file Generic AFS::Object object
dir Generic AFS::Object object
Both the 'file' and 'dir' objects have the following attributes:
Attributes Values
---------- ------
same Numeric value
diff Numeric value
At this point, any sane individual is probably hopelessly confused how
to make sense of the statistics, so let's make this clear with an
example.
First of all, the 'raw' and 'author' statistics are parsed from this
noise, generated when -extended is given:
Raw Read/Write Stats
|-------------------------------------------|
| Same Network | Diff Network |
|----------|----------|----------|----------|
| Total | Auth | Total | Auth |
|----------|----------|----------|----------|
Reads | 162 | 162 | 6 | 6 |
Writes | 1815 | 1815 | 0 | 0 |
|-------------------------------------------|
Writes Affecting Authorship
|-------------------------------------------|
| File Authorship | Directory Authorship|
|----------|----------|----------|----------|
| Same | Diff | Same | Diff |
|----------|----------|----------|----------|
0-60 sec | 226 | 0 | 621 | 0 |
1-10 min | 87 | 0 | 105 | 0 |
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
attributes, since once you have the names, you have all the information
already.
Compare this with 'vos partinfo', which provides a lot more
information. For pedantic completeness (the author is kinda
anal-retentive in that way), here's the description of the complete
interface.
B<AFS::Object::FileServer>
This object has no attributes, and is merely a container for the
AFS::Object::Partition objects. It has the following methods
for extracting the objects is contains.
Methods Returns
------- -------
getPartitionNames() list of strings (partition names)
getPartitions() list of AFS::Object::Partition objects
getPartition($partname) a single AFS::Object::Partition object,
for the partition named $partname
B<AFS::Object::Partition>
This object has one boring attribute:
Attributes Values
---------- ------
partition Fileserver /vice partition name
When used to encapsulate 'vos listpart' output, this object has no
relevant methods. Note, however, that this version of the API reuses
this object to represent other partition-related data (see 'vos
listvol' method documentation, for example), but they are not relevant
in this usage of the object. This multiple personality of the objects
may be changed in a future release, so don't get too attached to the
specific class names.
See the AFS::Object documentation for a discussion of the
planned evolution of the API.
=back
=head2 listvldb
=over
=item Arguments
The vos help string is:
vos listvldb: list volumes in the VLDB
Usage: vos listvldb [-name <volume name or ID>] [-server <machine name>]
[-partition <partition name>] [-locked] [-quiet] [-nosort]
[-cell <cell name>] [-noauth] [-localauth] [-verbose] [-encrypt]
Where: -locked locked volumes only
-quiet generate minimal information
-nosort do not alphabetically sort the volume names
The corresponding method invocation looks like:
my $result = $vos->listvldb
(
# Optional arguments
name => $name,
server => $server,
partition => $partition,
locked => 1,
quiet => 1,
nosort => 1,
cell => $cell,
noauth => 1,
localauth => 1,
verbose => 1,
encrypt => 1,
);
=item Return Values
This method returns an AFS::Object::VLDB object, which has a
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
lib/AFS/Command/VOS.pod view on Meta::CPAN
=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
partition => $partition,
fast => 1,
long => 1,
quiet => 1,
extended => 1, # Not really... see below
cell => $cell,
noauth => 1,
localauth => 1,
verbose => 1,
encrypt => 1,
);
NOTE: 'extended' is not supported in this version of the API, and
specifying it will result in a warning, but not an error. However,
'vos examine' does parse the extended output, so if you really want
that data you can get it on a volume by volume basis. Adding support
for 'extended' to 'vos listvol' is on the todo list.
=item Return Values
This method returns an AFS::Object::VolServer object, which
merely contains one or more AFS::Object::Partition objects,
which in turn have a few attributes and contain one or more
AFS::Object::VolumeHeader objects.
my $result = $vos->listvol
(
server => $server,,
cell => $cell,
) || die $vos->errors();
foreach my $partition ( $result->getPartitions() ) {
my $partname = $partition->partition();
my $total = $partition->total();
my $online = $partition->online();
my $offline = $partition->offline();
my $busy = $partition->busy();
print("Partition $partname has $total total volumes, of which " .
"$online are online, $offline are offline, and $busy are busy.\n");
foreach my $header ( $partition->getVolumeHeaders() ) {
# Do something interesting with $header.
}
}
There are several other ways to get at the headers, of course.
foreach my $name ( $partition->getVolumeNames() ) {
my $header = $partition->getVolumeHeaderByName($name)
# Do something interesting with $header.
}
foreach my $id ( $partition->getVolumeIds() ) {
my $header = $partition->getVolumeHeaderById($id);
# Do something interesting with $header.
}
And there is yet one more method to extract the headers (don't say the
author doesn't pander to lots of different programming styles,
provided of course they are one of his own).
foreach my $name ( $partition->getVolumeNames() ) {
my $header = $partition->getVolumeHeader( name => $name );
# Do something interesting with $header.
}
foreach my $id ( $partition->getVolumeIds() ) {
my $header = $partition->getVolumeHeader( id => $id );
# Do something interesting with $header.
}
Each of these objects has the following attributes and methods:
B<AFS::Object::VolServer>
This object has no attributes, and has several methods for extracting
the partition objects.
Methods Returns
------- -------
getPartitionNames() list of partition names
getPartitions() list of AFS::Object::Partition objects
getPartition($name) the AFS::Object::Partition for partition $name
B<AFS::Object::Partition>
This objects has several attributes, and several methods for
extracting the VolumeHeader objects.
Attributes Values
---------- ------
partition Partition name
total Total number of volumes on the partition
online Total number of online volumes
offline Total number of offline volumes
busy Total number of busy volumes
Methods Returns
lib/AFS/Command/VOS.pod view on Meta::CPAN
server Fileserver hostname
partition Fileserver /vice partition
maxquota Volume quota in KB
creation Volume creation date (ctime format, eg: Sat Oct 6 04:39:50 2001)
copyTime Volume copy date (also in ctime format)
backupTime Volume backup date (also in ctime format)
access Volume Last Access date (also in ctime format)
update Volume update date (also in ctime format)
accesses Number of volume accesses since the last reset
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
=back
=head2 partinfo
=over
=item Arguments
The vos help string is:
vos partinfo: list partition information
Usage: vos partinfo -server <machine name> [-partition <partition name>]
[-cell <cell name>] [-noauth] [-localauth]
[-verbose] [-encrypt]
The corresponding method invocation looks like:
my $result = $vos->partinfo
(
# Required arguments
server => $server,
# Optional arguments
partition => $partition,
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, which
have more interesting attributes than those returned by 'vos
partinfo'.
my $result = $vos->partinfo
(
server => $server,
cell => $cell,
) || die $vos->errors();
foreach my $partition ( $result->getPartitions() ) {
my $partname = $partition->partition();
my $available = $partition->available();
my $total = $partition->total();
print("Partition $partname has $available KB of " .
"space available out of $total KB total\n");
}
B<AFS::Object::FileServer>
This object has no attributes, and is merely a container for the
AFS::Object::Partition objects. It has the following methods
for extracting the objects is contains.
Methods Returns
------- -------
getPartitionNames() list of strings (partition names)
getPartitions() list of AFS::Object::Partition objects
getPartition($partname) a single AFS::Object::Partition object,
for the partition named $partname
B<AFS::Object::Partition>
This object has three attributes:
Attributes Values
---------- ------
partition Fileserver /vice partition name
available Space available, in KB
total Total space, in KB
=back
=head2 status
=over
=item Arguments
The vos help string is:
vos status: report on volser status
Usage: vos status -server <machine name> [-cell <cell name>] [-noauth]
[-localauth] [-verbose] [-encrypt]
The corresponding method invocation looks like:
my $result = $vos->status
(
# 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::VolServer object with one
attribute, which also may or may not contain one or more
AFS::Object::Transaction objects.
my $result = $vos->status
(
server => $server,
) || die $vos->errors();
print "Server has " . $result->transactions() . "active transactions\n";
foreach my $transaction ( $result->getTransactions() ) {
print("There are active transactions for volume ID " .
$transaction->volume() . "\n");
}
B<AFS::Object::VolServer>
This object has exactly one attribute, and several methods:
Attributes Values
---------- ------
transactions Number of active transactions on the volserver
Methods Returns
------- -------
getTransactions list of AFS::Object::Transaction objects
getVolumes list of volume IDs for which there are transactions
getTransactionByVolume($volume) a single AFS::Object::Transaction object for the volume $volume
B<AFS::Object::Transaction>
This object has several attributes:
Attributes Values
---------- ------
transaction Numeric transaction ID
created Creation date (in ctime format)
attachFlags String (exact meaning unclear)
volume Numeric volume ID
partition Vice partition on whcih the volume resides
procedure What is being done to the volume
packetRead Numeric value
lastReceiveTime Time value (utime format)
packetSend Numeric value
lastSendTime Time value (utime format)
NOTE: These attributes just come from a straight parsing of output like this:
--------------------------------------
transaction: 170423 created: Wed Oct 8 15:59:12 2003
attachFlags: offline
volume: 536963097 partition: /vicepf procedure: Restore
packetRead: 222 lastReceiveTime: 1065643165 packetSend: 1 lastSendTime: 1065643165
--------------------------------------
To understand the meaning of these various fields (which to the
author's knowledge are not documented anywhere), see the OpenAFS
source code. Some of these values are obvious, or intuitive, but
others are not.
=back
=head1 METHODS (with simple return values)
All of the following commands return a simple Boolean (true/false)
value, if they succeed or fail.
=head2 addsite
The vos help string is:
vos addsite: add a replication site
( run in 0.972 second using v1.01-cache-2.11-cpan-39bf76dae61 )