STABLE14-man-page-vos-shadow-20080331

LICENSE BSD

Man page for vos shadow.


(cherry picked from commit 4bcb7d01b2)

doc/man-pages/README

@@ -213,7 +213,6 @@ Known Problems
        vldb_convert
        vos clone
        vos setfields
-       vos shadow
        vsys
 
    * klog.krb, pagsh.krb, and tokens.krb need to be listed as alternative

doc/man-pages/pod1/vos_shadow.pod

@@ -0,0 +1,174 @@
+=head1 NAME
+
+vos_shadow - Creates a shadow copy of a volume on a different server/partition
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<vos shadow> S<<< [B<-id>] <I<volume name or ID on source>> >>>
+    S<<< [B<-fromserver>] <I<machine name on source>> >>>
+    S<<< [B<-frompartition>] <I<partition name on source>> >>>
+    S<<< [B<-toserver>] <I<machine name on destination>> >>>
+    S<<< [B<-topartition>] <I<partition name on destination>> >>>
+    S<<< [B<-toname> <I<volume name on destination>>] >>>
+    S<<< [B<-toid> <I<volume ID on destination>>] >>> [B<-offline>] [B<-readonly>]
+    [B<-live>] [B<-incremental>] S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>]
+    [B<-localauth>] [B<-verbose>] [B<-encrypt>] [B<-help>]
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+The B<vos shadow> command creates a shadow copy of a volume on a
+different partition or server.
+
+A shadow volume is a copy of a volume that does not normally appear in
+the volume location database (VLDB). It is a primitive operation that
+is meant to be used in backup or disaster recovery situations.
+
+=head1 CAUTIONS
+
+This command is not used during normal OpenAFS administration and may
+have adverse effects on the VLDB if not used properly! This command
+should only be used by an expert.
+
+Using this command on a volume when the source volume is not the same
+as parent volume used to create the shadow will leave the destination
+volume in a unknown state.
+
+Do NOT run the B<vos syncserv> or B<vos syncvldb> on any fileserver
+containing shadow volumes. This would update the VLDB to show all
+shadowed Read/Write volumes instead of the source volumes from which
+they were copied.
+
+Currently, the maximum size of a volume is 2 terabytes (2^31 bytes).
+
+=head1 OPTIONS
+
+=over 4
+
+=item [B<-id>] <I<volume name or ID>>
+
+Specifies either the complete name or volume ID number of a read/write
+volume.
+
+=item [B<-fromserver>] <I<machine name for source>>
+
+Identifies the file server machine where the source volume resides. Provide
+the machine's IP address or its host name (either fully qualified or using
+an unambiguous abbreviation). For details, see L<vos(1)>.
+
+=item [B<-frompartition>] <I<partition name for source>>
+
+Names the partition where the source volume resides. Provide the full
+partition name (for, example, B</vicepa>) or one of the abbreviated forms
+described in L<vos(1)>.
+
+=item [B<-toserver>] <I<machine name for destination>>
+
+Identifies the file server machine to which to copy the volume.  Provide
+the machine's IP address or its host name (either fully qualified or using
+an unambiguous abbreviation). For details, see L<vos(1)>.
+
+=item [B<-topartition>] <I<partition name for destination>>
+
+Names the partition to which to copy the volume. Provide the full partition
+name (for, example, B</vicepa>) or one of the abbreviated forms described in
+L<vos(1)>.
+
+=item B<-toname> <I<volume name for new copy>>
+
+The complete name of the new volume to create.
+
+=item B<-offline>
+
+Leaves the new volume flagged as off-line in the volume database.
+
+=item B<-readonly>
+
+Flags the new volume as read-only in the volume database.
+
+=item B<-live>
+
+Copies the live volume without cloning.  This is normally not necessary and
+causes the volume to be kept locked for longer than the normal copy
+mechanism.
+
+=item B<-incremental>
+
+Copy the changes from the source volume to a previously created shadow
+volume.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents
+it to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=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<-encrypt>
+
+Encrypts the command so that the operation's results are not transmitted
+across the network in clear text.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+This command has no output unless C<-verbose> is specified or there is
+an error.
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machines specified with the B<-toserver> and B<-fromserver> arguments and
+on each database server machine.  If the B<-localauth> flag is included,
+the issuer must instead be logged on to a server machine as the local
+superuser C<root>.
+
+=head1 SEE ALSO
+
+L<vos(1)>,
+L<vos_backup(1)>,
+L<vos_copy(1)>,
+L<vos_move(1)>
+
+L<http://www.openafs.org/pipermail/openafs-info/2005-July/018469.html>
+discusses motivation for the creation of this command.
+
+L<http://workshop.openafs.org/afsbpw06/talks/drh.scs.html> discusses
+one possible use for it.
+
+=head1 COPYRIGHT
+
+Copyright 2008 Jason Edgecombe <jason@rampaginggeek.com>
+
+This documentation is covered by the BSD License as written in the
+doc/LICENSE file. This man page was written by Jason Edgecombe for
+OpenAFS.