From fbe10c80860ce9f456a056e0d397a10411f22369 Mon Sep 17 00:00:00 2001 From: Jason Edgecombe Date: Fri, 27 Jun 2008 04:19:07 +0000 Subject: [PATCH] man-page-vos-clone-20080626 FIXES 104110 LICENSE BSD Add man page for vos clone. --- doc/man-pages/README | 1 - doc/man-pages/pod1/vos_clone.pod | 155 +++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+), 1 deletion(-) create mode 100644 doc/man-pages/pod1/vos_clone.pod diff --git a/doc/man-pages/README b/doc/man-pages/README index c4b040a3f9..7cc5c535db 100644 --- a/doc/man-pages/README +++ b/doc/man-pages/README @@ -216,7 +216,6 @@ Known Problems rmtsysd tokens.krb vldb_convert - vos clone vos setfields vsys diff --git a/doc/man-pages/pod1/vos_clone.pod b/doc/man-pages/pod1/vos_clone.pod new file mode 100644 index 0000000000..51264d1521 --- /dev/null +++ b/doc/man-pages/pod1/vos_clone.pod @@ -0,0 +1,155 @@ +=head1 NAME + +vos_clone - Creates a shared-space copy of a volume on a partition + +=head1 SYNOPSIS + +=for html +
+ +B S<<< [B<-id>] > >>> + S<<< [B<-server>] > >>> + S<<< [B<-partition>] > >>> + S<<< [B<-toname> >] >>> + S<<< [B<-toid> >] >>> [B<-offline>] [B<-readonly>] + S<<< [B<-cell> >] >>> [B<-noauth>] + [B<-localauth>] [B<-verbose>] [B<-encrypt>] [B<-help>] + +=for html +
+ +=head1 DESCRIPTION + +The B command creates a copy-on-write copy of a volume on the +same partition and server ass the parent volume. + +A clone is a copy of a volume that does only stores the changes from the +parent volume. Cloning is a primitive operation that is used by the B, B, and B commands. A clone functions using +the same mechanism as a backup volume, but it is persistent. Clone volumes +can be used as point-in-time copies of the parent vollume, but they must be +used with care. + +=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. + +Deleting or moving the parent volume makes the clone volume inaccessible, +but the clone volume remains in the VLDB and on disk, and it needs to be +cleaned up manually. + +There is a maximum limitation of 7 clones when using the namei +fileserver. You may safely create up to 4 clones using the B +command. The other three clone slots are used by the backup volume, a +read-only replica and the temporary clone that is created when executing a +B, B, or other B commands. + +Some commands do not work properly on clone volumes. B is one +such command. + +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<-server>] > + +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<-partition>] > + +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<-toname> > + +The complete name of the new volume to create. + +=item B<-toid> > + +The complete id 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<-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 + +=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.