view release on metacpan or  search on metacpan

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

=over

=item new

=item errors

=item supportsOperation

=item supportsArgument

=back

=head1 METHODS (dump, restore)

Both the 'dump' and 'restore' methods are special, since this API
supports compression to and from the filesystem when dumping or
restoring the volume.  Normally, "vos dump -file" will just wrote the
uncompressed volume dump to the file, but this API can compress it.
This is a huge cost savings in disk space, assuming you can afford the
CPU time to perform the compression (this is the 21st century -- you
probably can).

Both of these commands return simply boolean true/false values, but
they have some special case handling for the -file argument, and
support several special arguments that are extensions implemented in
this API only.

=head2 dump

The vos help string is:

    vos dump: dump a volume
    Usage: vos dump -id <volume name or ID> [-time <dump from time>] [-file <dump file>]
		    [-server <server>] [-partition <partition>] [-cell <cell name>]
		    [-noauth] [-localauth] [-verbose] [-encrypt]

The corresponding method invocation looks like:

    my $result = $vos->dump
      (
       # Required arguments
       id			=> $id,
       file			=> $file, # SPECIAL CASE!!! (see below)
       # Optional arguments
       time			=> $time,
       server			=> $server,
       partition		=> $partition,
       cell                     => $cell,
       noauth                   => 1,
       localauth                => 1,
       verbose                  => 1,
       encrypt                  => 1,
       # Enhanced arguments
       gzip			=> $gzip,
       bzip2			=> $bzip2,
       filterout		=> [ @command ], # OR [ [ @cmd1 ], [ @cmd2 ], ... ]
      );

The first thing to notice is that 'file' is optional to the vos dump
command itself, but required in this API.  The second thing to notice
is the addition of three new arguments: gzip, bzip2 and filterout.

=over

=item file

This argument specifies the file to which the vos dump output should
be written.  If this file ends in '.gz' or '.bz2', then gzip or bzip2
will be used to compress the output before it is written to the
filesystem.  This is accomplished using a pipe, so there is no
intermediate file written to disk first.

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

   my $result = $vos->dump
     (
      ...
      file			=> 'stdout',
      ...
     );

=item gzip, bzip2

Both of these arguments will turn on compression explicitly, and if
the file specified doesn't end in the appropriate extension already
('.gz' for gzip, and '.bz2' for bzip2), then the extension is appended
to the filename.

The value of these arguments specifies the degree of compression used,
an should be a single numeric digit, from 0 to 9.  See the gzip and
bzip2 man pages for more information.

These arguments are also mutually exclusive.

=item filterout

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' ],
       ...
      );

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

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

The corresponding method invocation looks like:

    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
      (