AFS-Command
view release on metacpan or search on metacpan
#
# We need a valid pathname (directory) in AFS that we can abuse (that
# is, we will be hacking the ACL on this directory, and a few other
# intrusive things, to test the FS API). This directory must be in a
# RW volume, and system:administratoirs must have write access to it.
#
AFS_COMMAND_PATHNAME_AFS = /afs/your.cell.name/home/you/hackmebaby
#
# We will need to create a pts group and user, and if these names are
# already taken, then change these lines. The code will *remove* them
# when its done.
#
AFS_COMMAND_PTS_GROUP = afscmdgroup
AFS_COMMAND_PTS_USER = afscmduser
#
# If the AFS client on which the tests run does NOT match that
# specified above, then the pts group/user we create will NOT be
# visible to the fs setacl command. Therefore, we need the name of an
# existing pts user or group to use for that test.
When a volume's status is "offline", there is really more than one
status the volume can be in. A volume might be unattached, and
offline, or it might be attached, but adminitratively offline. For
example, "vos offline" put a vlume in the latter state, and if for
some reason there are two volumes with the same ID on the same
fileserver, they will both be attached (if possible), but only the
first one encountered will be brought online.
Changing the value of status would been a non-backwards compatible
change, and caused some subtle problems for some applications. Rather
than introduce such a change, I have chosen to represent this state
with an additional attribute "attached", which is just a Boolean,
indicating whether or not the volume is attached.
=head1 Bugs
=head1 Changes in 1.5
=head1 Enhancements
=head2 Principal names, as user supplied arguments, are lowercased
Documentation for two important new vos restore arguments was added to
the documentation (-creation and -lastupdate). These options are only
available in a patch to vos, which should be in one the next two major
OpenAFS 1.2.X releases.
=head1 Bugs
=head2 AFS::Object::VolumeHeader 'accesses' attribute was incorrect
The actual attribute on the objects was named "access". Oops. The
attribute was changed to "accesses" to match the documentation, and
the string that is parsed in vos output.
=head1 Changes in 1.4
=head1 Enhancements
=head2 Test suite is disabled by default.
There is a well intentioned effort to automatically test all new
submissions to CPAN (see http://testers.cpan.org). Unfortunately, the
in the CONFIG file has not been modified, thus allowing the automated
CPAN testing to continue, automatically, without the author getting a
bunch of bogus emails.
=head1 Bugs
=head2 Volume status value inconsistency
!!!!!!!! WARNING !!!!!!!!
This change is NOT backwards compatible with previous releases, so
verify that your code handles the new, consistent values correctly.
The "status" field returned from either vos->examine() or
vos->listvol(), in previous releases, had inconsistent values. When a
volume is online, the status would be one of:
online
On-line
Likewise, when offline, one of:
=head1 Changes in 1.3
=head1 Enhancements
=head2 AFS::Command::VOS->release support both -f and -force
Someone at some point changed vos release's force argument from -f to
-force. API calls written with one of those will not work with a vos
binary that doesn't agree on the choice of force option. This would
have require developers to write code like this:
$vos->release
(
id => $id,
cell => $cell,
( $vos->supportsArgument('release','force') ?
( force => 1 ) :
( f => 1 )
),
);
OK, that's the authors twisted way of doing it, and it seems like
needless complexity. Both f and force are now supported as options,
using a simply alias mechanism to translate from one to the other,
based on what is supported by the vos binary.
The documentation hasn't been changed, since you can use 'force' in
all cases, and since that is the newer of the two, the docs will stay
as they are. The fact that your vos binary really wants 'f' is hidden
from you, and will stay that way.
=head1 Bugs
=head2 AFS::Command::BOS->listhosts
The returned object has a cell attribute, as well as the hosts
attribute, but the docs forgot to mention this.
=head2 AFS::Command::VOS->status()
This method now parses the individual transaction stanzas, and the API
provides access to objects that encapsulate each of them. So, instead
of just finding out how many transactions are active, you can analyze
each of them in detail.
=head2 AFS::Object::VLDB data is now keyed on volume ID, as well as name
This changes the way the AFS::Object::VLDB data can be extracted. In
1.0, the API allowed AFS::Object::VLDBEntry object to be queried only
by name, but 3 new methods calls allow this data to be queried by
numeric ID as well as name:
getVLDBEntryById($id)
getVLDBEntryByName($name)
getVolumeIds()
The API for getVLDBEntry has changed, and the single argument usage:
getVLDBEntry($name) # DEPRECATED!!!!
has been deprecated. If warnings are enabled (perl -w), then the API
will carp at you. In the next release (1.2), that usage will no
longer be supported. Upgrade your code, or pay the price.
The new usage of getVLDBEntry is one of:
getVLDBEntry( name => $name )
Changes.html view on Meta::CPAN
the volume can be in. A volume might be unattached, and offline, or it
might be attached, but adminitratively offline. For example, ``vos
offline'' put a vlume in the latter state, and if for some reason there are
two volumes with the same ID on the same fileserver, they will both be
attached (if possible), but only the first one encountered will be brought
online.
<P>
Changing the value of status would been a non-backwards compatible change,
and caused some subtle problems for some applications. Rather than
introduce such a change, I have chosen to represent this state with an
additional attribute ``attached'', which is just a Boolean, indicating
whether or not the volume is attached.
<P>
<P>
<HR>
<H1><A NAME="Bugs">Bugs
Changes.html view on Meta::CPAN
<HR>
<H1><A NAME="Bugs">Bugs
</A></H1>
<P>
<HR>
<H2><A NAME="AFS_Object_VolumeHeader_acces">AFS::Object::VolumeHeader 'accesses' attribute was incorrect
</A></H2>
The actual attribute on the objects was named ``access''. Oops. The
attribute was changed to ``accesses'' to match the documentation, and the
string that is parsed in vos output.
<P>
<P>
<HR>
<H1><A NAME="Changes_in_1_4">Changes in 1.4
</A></H1>
Changes.html view on Meta::CPAN
<P>
<HR>
<H2><A NAME="Volume_status_value_inconsistenc">Volume status value inconsistency
</A></H2>
!!!!!!!! WARNING !!!!!!!!
<P>
This change is NOT backwards compatible with previous releases, so verify
that your code handles the new, consistent values correctly.
<P>
The ``status'' field returned from either vos->examine() or
vos->listvol(), in previous releases, had inconsistent values. When a
volume is online, the status would be one of:
Changes.html view on Meta::CPAN
<P>
<HR>
<H1><A NAME="Enhancements">Enhancements
</A></H1>
<P>
<HR>
<H2><A NAME="AFS_Command_VOS_release_suppo">AFS::Command::VOS->release support both -f and -force
</A></H2>
Someone at some point changed vos release's force argument from -f to
-force. API calls written with one of those will not work with a vos binary
that doesn't agree on the choice of force option. This would have require
developers to write code like this:
<P>
<PRE> $vos->release
(
id => $id,
Changes.html view on Meta::CPAN
<P>
OK, that's the authors twisted way of doing it, and it seems like needless
complexity. Both f and force are now supported as options, using a simply
alias mechanism to translate from one to the other, based on what is
supported by the vos binary.
<P>
The documentation hasn't been changed, since you can use 'force' in all
cases, and since that is the newer of the two, the docs will stay as they
are. The fact that your vos binary really wants 'f' is hidden from you, and
will stay that way.
<P>
<P>
<HR>
<H1><A NAME="Bugs">Bugs
Changes.html view on Meta::CPAN
them in detail.
<P>
<P>
<HR>
<H2><A NAME="AFS_Object_VLDB_data_is_now_ke">AFS::Object::VLDB data is now keyed on volume ID, as well as name
</A></H2>
This changes the way the AFS::Object::VLDB data can be extracted. In 1.0,
the API allowed AFS::Object::VLDBEntry object to be queried only by name,
but 3 new methods calls allow this data to be queried by numeric ID as well
as name:
<P>
<PRE> getVLDBEntryById($id)
getVLDBEntryByName($name)
getVolumeIds()
</PRE>
<P>
The API for getVLDBEntry has changed, and the single argument usage:
<P>
<PRE> getVLDBEntry($name) # DEPRECATED!!!!
</PRE>
<P>
has been deprecated. If warnings are enabled (perl -w), then the API will
the Standard Version of this Package without restriction, provided
that you duplicate all of the original copyright notices and
associated disclaimers.
2. You may apply bug fixes, portability fixes and other modifications
derived from the Public Domain or from the Copyright Holder. A
Package modified in such a way shall still be considered the
Standard Version.
3. You may otherwise modify your copy of this Package in any way,
provided that you insert a prominent notice in each changed file
stating how and when you changed that file, and provided that you
do at least ONE of the following:
a) place your modifications in the Public Domain or otherwise make
them Freely Available, such as by posting said modifications to
Usenet or an equivalent medium, or placing the modifications on
a major archive site such as uunet.uu.net, or by allowing the
Copyright Holder to include your modifications in the Standard
Version of the Package.
b) use the modified Package only within your corporation or
image shall neither be construed as a distribution of this Package
nor shall it fall under the restrictions of Paragraphs 3 and 4,
provided that you do not represent such an executable image as a
Standard Version of this Package.
7. C subroutines (or comparably compiled subroutines in other
languages) supplied by you and linked into this Package in order to
emulate subroutines and variables of the language defined by this
Package shall not be considered part of this Package, but are the
equivalent of input as in Paragraph 6, provided these subroutines
donot change the language in any way that would cause it to fail
the regression tests for the language.
8. Aggregation of this Package with a commercial distribution is
always permitted provided that the use of this Package is embedded;
that is, when no overt attempt is made to make this Package's
interfaces visible to the end user of the commercial distribution.
Such use shall not be construed as a distribution of this Package.
9. The name of the Copyright Holder may not be used to endorse or
promote products derived from this software without specific prior
If you can't determine the source of the problem(s), send the verbose
test output, along with the output from "perl -V", as well as the
versions of AFS in use at your site, to the author, and I'll do my
best to figure out why things are breaking, and if you're lucky,
actually fix it.
=head1 RELEASE NOTES
In addition to the README file (which in case you hadn't noticed,
you're reading right now), the history of changes is maintained in
Changes.html.
=head1 DOCUMENTATION
Docs for these modules are split across several files, and will be
installed as man pages.
man AFS::Command
will provide the general overview of the API, its basic design. The
README.html view on Meta::CPAN
<P>
<P>
<HR>
<H1><A NAME="RELEASE_NOTES">RELEASE NOTES
</A></H1>
In addition to the README file (which in case you hadn't noticed, you're
reading right now), the history of changes is maintained in Changes.html.
<P>
<P>
<HR>
<H1><A NAME="DOCUMENTATION">DOCUMENTATION
</A></H1>
Docs for these modules are split across several files, and will be
We should pass in some bogus paths, too, to verify the error handling
is correct as well (that code feels dubious to me).
=head1 Bugs
=head2 stdout/stderr buffering will break the fs examine/diskfree commands
Actually, all of the commands that parse per-path output, really.
Currently the code assumes the stderr output will appear first, which
is a side effect of the buffering. Some attempts to turn of buffering
didn't change this, and in any case, we don't want to be sensitive to
this (we currently are).
We need to process stderr first, to determine which paths had errors,
and then parse stdout. This will require the change descibred above
for how we handle stderr.
=cut
<H1><A NAME="Bugs">Bugs
</A></H1>
<P>
<HR>
<H2><A NAME="stdout_stderr_buffering_will_bre">stdout/stderr buffering will break the fs examine/diskfree commands
</A></H2>
Actually, all of the commands that parse per-path output, really. Currently
the code assumes the stderr output will appear first, which is a side
effect of the buffering. Some attempts to turn of buffering didn't change
this, and in any case, we don't want to be sensitive to this (we currently
are).
<P>
We need to process stderr first, to determine which paths had errors, and
then parse stdout. This will require the change descibred above for how we
handle stderr.
<P>
</DL>
</BODY>
</HTML>
lib/AFS/Command.pod view on Meta::CPAN
library, and this API leverages this fact. The methods available, and
their available arguments, are determined dynamically by parsing the
command help strings.
This API is also designed to complement the existing perl5 AFS::*
namespace, and co-exist with it.
=head1 OBJECT ARCHITECTURE
WARNING: This is an early design phase (1.x) of this API, and it is in
its infancy, so expect it to change in future releases, and expect to
change your code to accomodate it.
The entire API is designed to be pure OO, with the following classes:
=head2 AFS::Command::(VOS|BOS|PTS|FS)
These are the primary classes used by applications directly. All of
the other objects are used internally to encapsulate the data parsed
from the underlying commands, and returned by the primary methods.
Each of these classes has a shared constructor (new), and methods that
lib/AFS/Command.pod view on Meta::CPAN
AFS::Object::Partition
AFS::Object::Volume
AFS::Object::VolumeHeader
The subclasses for encapsulating the bosserver data are:
AFS::Object::BosServer
AFS::Object::Instance
Note that none of these classes are specifically documented, since the
structure of the classes is subject to change. The API for accessin
the results of any given AFS command (eg. vos listvol) is considered
reasonably stable, but the encapsulation may change radically.
Don't get too attached to these class names, because they will likely
be rearranged in a future release.
=cut
lib/AFS/Command/BOS.pm view on Meta::CPAN
if ( /has cksum (\d+)/ ) {
$key->_setAttribute( cksum => $1 );
} elsif ( /is \'([^\']+)\'/ ) {
$key->_setAttribute( value => $1 );
}
$result->_addKey($key);
}
if ( /last changed on (.*)\./ ) {
$result->_setAttribute( keyschanged => $1 );
}
}
$errors++ unless $self->_reap_cmds();
$errors++ unless $self->_restore_stderr();
return if $errors;
return $result;
lib/AFS/Command/BOS.pod view on Meta::CPAN
my ($index,$value) = ($key->index(),$key->value());
print "\t$index => $cksum\n";
}
The objects have the following attributes and methods:
B<AFS::Object::BosServer>
Attributes Values
---------- ------
keychanged Date the keys were last changed
Methods Returns
------- -------
getKeyIndexes() list of numeric key indexes
getKeys() list of AFS::Object objects
getKey($index) the AFS::Object object for the key with index $index
B<AFS::Object>
The following attribute is always present:
lib/AFS/Command/BOS.pod view on Meta::CPAN
-rootfiles (MR-AFS) Show files owned by root - debugging flag
-salvagedirs (MR-AFS) Force rebuild/salvage of all directories
-blockreads (MR-AFS) Read smaller blocks to handle IO/bad blocks
-ListResidencies (MR-AFS) Just list affected file residencies - debugging flag
-SalvageRemote (MR-AFS) Salvage storage systems that are not directly attached
-SalvageArchival (MR-AFS) Salvage HSM storage systems
-IgnoreCheck (MR-AFS) Don't perform VLDB safety check when deleting unreferenced files.
Only a good idea in single server cell.
-ForceOnLine (MR-AFS) Force the volume to come online, even if it hasn't salvaged cleanly.
-UseRootDirACL (MR-AFS) Use the root directory ACL for lost+found directory if it is created.
-TraceBadLinkCounts (MR-AFS) Print out lines about volume reference count changes.
-DontAskFS (MR-AFS) Don't ask fileserver to take volume offline. THIS IS VERY DANGEROUS.
-rxdebug (MR-AFS) Write out rx debug information.
The corresponding method invocation looks like:
my $result = $bos->salvage
(
# Required arguments
server => $server,
# Optional arguments
lib/AFS/Command/Base.pm view on Meta::CPAN
last;
}
}
#
# XXX -- Hack Alert!!!
#
# Because some asshole decided to change the force option to vos
# release from -f to -force, you can't use the API tranparently
# with 2 different vos binaries that support the 2 different options.
#
# If we need more of these, we can add them, as this let's us
# alias one argument to another.
#
if ( $self->isa("AFS::Command::VOS") && $operation eq 'release' ) {
if ( exists $arguments->{optional}->{f} ) {
$arguments->{aliases}->{force} = 'f';
} elsif ( exists $arguments->{optional}->{force} ) {
lib/AFS/Command/Base.pod view on Meta::CPAN
);
unless ( $result ) {
die "Unable to examine volname '$volname' in cell '$cell':" .
$vos->errors();
}
=head2 supportsOperation
This class method allows the developer to test whether or not any
given operation is supported by the underlying command line utility.
For example, the "vos changeloc" operation is not supported in older
release of vos.
unless ( $vos->supportsOperation('changeloc') {
die "Unable to continue -- 'vos changeloc' is unsupported.\n";
}
The return value is simply true or false.
=head2 supportsArgument
Similar to supportsOperation, supportsArgument will test whether or
not a given argument is a support command line argument for the
specified operation. For example, the -encrypt argument is only
supported in more recent versions of vos, so that support can be
lib/AFS/Command/PTS.pod view on Meta::CPAN
# Optional arguments
cell => $cell,
noauth => 1,
force => 1,
);
=head2 chown
The pts help string is:
pts chown: change ownership of a group
Usage: pts chown -name <group name> -owner <new owner>
[-cell <cell name>] [-noauth] [-force]
The corresponding method invocation looks like:
my $result = $pts->chown
(
# Required arguments
name => $name,
owner => $owner,
lib/AFS/Command/VOS.pod view on Meta::CPAN
This is an advanced feature, and one that allows the volume dump to be
filtered through any arbitrary number of commands before it is
compressed (optionally) and written to the filesystem. The value of
this argument is either an ARRAY reference to a list of command line
arguments, suitable for passing to exec(), or an ARRAY or such ARRAYS,
when more than one filter command is being used.
For example, the author has a requirement to pass all volume dumps
through a simple filter called 'newversion', which reads a volume
dump, changes the directory version numbers to the current utime
value, and writes the volume dump to stdout. Trust me, you really
don't want to know why.
my $result = $vos->dump
(
...
filterout => [ 'newversion' ],
...
);
lib/AFS/Command/VOS.pod view on Meta::CPAN
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
lib/AFS/Command/VOS.pod view on Meta::CPAN
exclude => 1,
prefix => $xprefix, # OR [ $xprefix1, $xprefix2, ... ]
dryrun => 1,
cell => $cell,
noauth => 1,
localauth => 1,
verbose => 1,
encrypt => 1,
);
=head2 changeaddr
The vos help string is:
vos changeaddr: change the IP address of a file server
Usage: vos changeaddr -oldaddr <original IP address> [-newaddr <new IP address>]
[-remove] [-cell <cell name>] [-noauth]
[-localauth] [-verbose] [-encrypt]
Where: -remove remove the IP address from the VLDB
The corresponding method invocation looks like:
my $result = $vos->changeaddr
(
# Required arguments
oldaddr => $oldaddr,
# Optional arguments
newaddr => $newaddr,
remove => 1,
cell => $cell,
noauth => 1,
localauth => 1,
verbose => 1,
encrypt => 1,
);
=head2 changeloc
The vos help string is:
vos changeloc: change an RW volume's location in the VLDB
Usage: vos changeloc -server <machine name for new location>
-partition <partition name for new location>
-id <volume name or ID> [-cell <cell name>] [-noauth]
[-localauth] [-verbose] [-encrypt]
The corresponding method invocation looks like:
my $result = $vos->changeloc
(
# Required arguments
server => $server,
partition => $partition,
id => $id,
# Optional arguments
cell => $cell,
noauth => 1,
localauth => 1,
verbose => 1,
lib/AFS/Command/VOS.pod view on Meta::CPAN
noauth => 1,
localauth => 1,
verbose => 1,
encrypt => 1,
);
=head2 setfields
The vos help string is:
vos setfields: change volume info fields
Usage: vos setfields -id <volume name or ID> [-maxquota <quota (KB)>]
[-clearuse] [-cell <cell name>] [-noauth]
[-localauth] [-verbose] [-encrypt]
Where: -clearuse clear dayUse
The corresponding method invocation looks like:
my $result = $vos->setfields
(
# Required arguments
t/00vos_basic.t view on Meta::CPAN
die Data::Dumper->Dump([$result],['result']) if $errors;
} else {
print "not ok $TestCounter..$TestTotal\n";
die("Unable to examine volume '$volname' in cell '$cell':\n" .
$vos->errors());
}
#
# Create a backup, an verify that the changes in the examine output.
#
$result = $vos->backup
(
id => $volname,
cell => $cell,
);
if ( $result ) {
print "ok $TestCounter\n";
$TestCounter++;
} else {
t/00vos_basic.t view on Meta::CPAN
my $rwrite = 0;
if ( ref $header && $header->isa("AFS::Object::VolumeHeader") ) {
print "ok $TestCounter\n";
$TestCounter++;
#
# This time through, we're looking for just the things we
# expect a vos backup to change, and nothing else.
#
if ( $header->backup() =~ /^\d+/ ) {
print "ok $TestCounter\n";
$TestCounter++;
if ( $header->backup() > 0 ) {
print "ok $TestCounter\n";
} else {
print "not ok $TestCounter\n";
( run in 0.532 second using v1.01-cache-2.11-cpan-c333fce770f )