diff --git a/doc/man-pages/README b/doc/man-pages/README index 022cc2fc5e..164340f298 100644 --- a/doc/man-pages/README +++ b/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 diff --git a/doc/man-pages/pod1/vos_shadow.pod b/doc/man-pages/pod1/vos_shadow.pod new file mode 100644 index 0000000000..ee7598154c --- /dev/null +++ b/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 +
+ +B S<<< [B<-id>] > >>> + S<<< [B<-fromserver>] > >>> + S<<< [B<-frompartition>] > >>> + S<<< [B<-toserver>] > >>> + S<<< [B<-topartition>] > >>> + S<<< [B<-toname> >] >>> + S<<< [B<-toid> >] >>> [B<-offline>] [B<-readonly>] + [B<-live>] [B<-incremental>] S<<< [B<-cell> >] >>> [B<-noauth>] + [B<-localauth>] [B<-verbose>] [B<-encrypt>] [B<-help>] + +=for html +
+ +=head1 DESCRIPTION + +The B 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 or B 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>] > + +Specifies either the complete name or volume ID number of a read/write +volume. + +=item [B<-fromserver>] > + +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. + +=item [B<-frompartition>] > + +Names the partition where the source volume resides. Provide the full +partition name (for, example, B) or one of the abbreviated forms +described in L. + +=item [B<-toserver>] > + +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. + +=item [B<-topartition>] > + +Names the partition to which to copy the volume. Provide the full partition +name (for, example, B) or one of the abbreviated forms described in +L. + +=item B<-toname> > + +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> > + +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. + +=item B<-noauth> + +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +F file. The B 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. + +=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 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. + +=head1 SEE ALSO + +L, +L, +L, +L + +L +discusses motivation for the creation of this command. + +L discusses +one possible use for it. + +=head1 COPYRIGHT + +Copyright 2008 Jason Edgecombe + +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.