view release on metacpan or  search on metacpan

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

    my $result = $vos->restore
      (
       # Required arguments
       server			=> $server,
       partition		=> $partition,
       name			=> $name,
       file			=> $file, # SPECIAL CASE!!! (see below)
       # Optional arguments
       id			=> $id,
       overwrite		=> 'abort' | 'full' | 'incremental',
       offline			=> 1,
       readonly			=> 1,
       creation			=> 'dump' | 'keep' | 'new',
       lastupdate		=> 'dump' | 'keep' | 'new',
       cell                     => $cell,
       noauth                   => 1,
       localauth                => 1,
       verbose                  => 1,
       encrypt                  => 1,
       # Enhanced arguments
       gunzip			=> 1,
       bunzip2			=> 1,
       filterin			=> [ @command ], # OR [ [ @cmd1 ], [ @cmd2 ], ... ]
      );

NOTE: The 'creation' and 'lastupdate' options are available only in a
very recent patch to the vos command, which should be available in the
OpenAFS 1.2.11 or 1.2.12 releases.  These options control how the
Creation and LastUpdate timestamps are set on the restored volume.

The 3 values these options can take, and their meanings, are:

=over

=item dump

Use the timestamp from the volume dump file being restored to the
volume.  This is the default behavior for the LastUpdate timestamp.

=item keep

Preserve the existing timestamp on the volume.

=item new

Set the timestamp to the current time.  This is the default behavior
for the Creation timestamp.

=back

Note that the default behavior creates the condition where the
Creation time is newer than the LastUpdate time, and when this is
true, "vos examine" (or any command that display the timestamps in the
volume header, really) will show the Creation time as the LastUpdate
time, presumably because it would be confusing to show the volume as
having been updated before it was created.

Similar to 'vos dump', the 'file' argument is optional to 'vos
restore', but required in this API.  There are also three new
arguments: gunzip, bunzip2, and filterin.  The analogy with 'vos dump'
is by design entirely symmetrical.

=over

=item file

This argument specifies the file from which the vos restore input
should be read.  If the file ends in '.gz' or '.bz2', then gunzip or
bunzip2 will be used to uncompress the input before it is read by vos
restore.  This is accomplished using a pipe, so there is no
intermediate file written to disk first.

By default, 'vos restore' will read the volume dump from stdin, which
is not what you want in most applications.  If you really want the
volume to be read from stdin, then you have to explicitly say so:

   my $result = $vos->restore
     (
      ...
      file			=> 'stdin',
      ...
     );

=item gunzip, bunzip2

Both of these arguments will turn on uncompression explicitly,
although they only need to be specified if the need for uncompression
can not be determined dynamically from the filename.  If the files are
compressed, but lack the proper extension ('.gz' or '.bz2'), or if the
compressed input is being read from stdin, then uncompression must be
specified explicitly.

These arguments have boolean values, since uncompression is either on
or off.  They are mutually exclusive as well.

=item filterin

This is an advanced feature, and one that allows the volume dump to be
filtered through any arbitrary number of commands after it is
uncompressed (optionally) and read by vos restore.  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.

Lacking a better example, let's assume the author's 'newversion'
utility is being applied to the restore process, rather than the dump.

    my $result = $vos->restore
      (
       ...
       filterin			=> [ 'newversion' ],
       ...
      );

If there were command line arguments for this command, then they must
be given as follows:

    my $result = $vos->restore
      (
       ...

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

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