[OpenAFS-Doc] first draft of new pod8/read_tape.pod

[Jason Edgecombe]

This is a multi-part message in MIME format.
--------------080009030501080403070808
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

This is the first draft of pod8/read_tape.pod

I don't have a tape drive to test with. It still needs the output 
section filled in and any cautions should be listed.

Jason

--------------080009030501080403070808
Content-Type: text/plain; x-mac-type="0"; x-mac-creator="0";
 name="read_tape.pod"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="read_tape.pod"

=head1 NAME

read_tape - Reads volume dumps from a backup tape and saves them to a file.

=head1 SYNOPSIS

=for html
<div class="synopsis">

B<read_tape> S<<< B<-tape> <I<tape device>> >>>
   S<<< B<-restore> <I<# of volumes to restore>> >>>
   S<<< B<-skip> # <I<# of volumes to skip>> >>>
   S<<< B<-file> <I<filename>> >>> [B<-scan>] [B<-noask>] [B<-label>]
   [B<-vheaders>] [B<-verbose>] [B<-help>]

=for html
</div>

=head1 DESCRIPTION

B<read_tape> reads an OpenAFS backup tape and prompts for each dump
file to save. This command does not require any OpenAFS
infrastructure. This command does not need an OpenAFS client or server
to be available, which is not the case with the B<backup(8)> command.

After saving each dump file, B<vos restore> or B<restorevol> can be
used to restore the volume into AFS and non-AFS space respectively.

B<read_tape> reads the tape while skipping the specified number of
volumes. After that, it restores the specified number of
volumes. B<read_tape> doesn't rewind the tape, so it can be used
multiple times in succession.

=head1 CAUTIONS



=head1 OPTIONS

=over 4

=item B<-tape> <I<tape device>>

Specifies the tape device from which to restore.

=item B<-restore> <I<# of volumes to restore>>

Specifies the number of volumes to restore from tape.

=item B<-skip> <I<# of volumes to skip>>

Specifies the number of volumes to skip before starting the restore.

=item B<-file> <I<filename>>

Specifies an alternate name for the restored volume dump file.

=item B<-scan>

Scans the tape.

=item B<-noask>

Doesn't prompt for each volume

=item B<-label>

Displays the full dump label.

=item B<-vheaders>

Displays the full volume headers

=item B<-verbose>

Produces on the standard output stream a detailed trace of the command's
execution. If this argument is omitted, only warnings and error messages
appear.

=item B<-help>

Prints the online help for this command. All other valid options are
ignored.

=back

=head1 OUTPUT



=head1 EXAMPLES

The following command will read the third through fifth volumes from
the tape device /dev/tape without prompting:

   % read_tape -tape /dev/tape -skip 2 -restore 3 -noask

=head1 PRIVILEGE REQUIRED

The issuer must have access to read and write to the specified tape
device.

=head1 SEE ALSO

L<backup(8),
L<restorevol(8),
L<vos_restore(1)

IBM AFS Disaster Recovery at
L<http://www-1.ibm.com/support/docview.wss?rs=961&context=SSXMUG&dc=DA400&uid=swg27004312&loc=en_US&cs=UTF-8&lang=en&rss=ct961other#32>.

=head1 COPYRIGHT

Copyright 2007 Jason Edgecombe <jason@rampaginggeek.com>

This documentation is covered by the IBM Public License Version 1.0. This
man page was written by Jason Edgecombe for OpenAFS.

--------------080009030501080403070808--