From: Jason Edgecombe Date: Sun, 8 Apr 2012 16:10:58 +0000 (-0400) Subject: DOC: Factored common text out of the vos_backup and vos_dump man pages X-Git-Tag: upstream/1.8.0_pre1^2~2612 X-Git-Url: https://git.michaelhowe.org/gitweb/?a=commitdiff_plain;h=f26330904607c6c939c037587b473644deea669d;p=packages%2Fo%2Fopenafs.git DOC: Factored common text out of the vos_backup and vos_dump man pages Change-Id: I84bd722834297778ab2e719996b2f8528d8706d6 Reviewed-on: http://gerrit.openafs.org/7126 Reviewed-by: Simon Wilkinson Tested-by: Simon Wilkinson Reviewed-by: Jeffrey Altman Tested-by: Jeffrey Altman --- diff --git a/doc/man-pages/pod1/.gitignore b/doc/man-pages/pod1/.gitignore index 1a1d4d6cd..9b024d68e 100644 --- a/doc/man-pages/pod1/.gitignore +++ b/doc/man-pages/pod1/.gitignore @@ -21,5 +21,7 @@ /pts_sleep.pod /pts_source.pod /vos_addsite.pod +/vos_backup.pod /vos_copy.pod +/vos_dump.pod /vos_zap.pod diff --git a/doc/man-pages/pod1/vos_backup.pod b/doc/man-pages/pod1/vos_backup.pod deleted file mode 100644 index f35c6e6d1..000000000 --- a/doc/man-pages/pod1/vos_backup.pod +++ /dev/null @@ -1,119 +0,0 @@ -=head1 NAME - -vos_backup - Creates a backup volume for a single read/write volume - -=head1 SYNOPSIS - -=for html -
- -B S<<< B<-id> > >>> - S<<< [B<-cell> >] >>> - [B<-noauth>] [B<-localauth>] [B<-verbose>] - [B<-encrypt>] [B<-noresolve>] [B<-help>] - -B S<<< B<-i> > >>> [B<-c> >] - [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] - -=for html -
- -=head1 DESCRIPTION - -The B command clones the indicated read/write volume to create -a backup version, placing it at the same site as the read/write -version. The backup volume's name is the same as the read/write source's -with the addition of the C<.backup> extension. Its volume ID number is the -one allocated for it in the Volume Location Database (VLDB) when the -read/write source was created with the B command. If a backup -version already exists, the new clone replaces it. - -To create a backup version of multiple volumes, use the B -command. - -=head1 OPTIONS - -=over 4 - -=item B<-id> > - -Specifies either the complete name or volume ID number of the read/write -source 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 anonymous 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. This option is available in OpenAFS -versions 1.4.11 or later and 1.5.60 or later. - -=item B<-noresolve> - -Shows all servers as IP addresses instead of the DNS name. This is very -useful when the server address is registered as 127.0.0.1 or when dealing -with multi-homed servers. This option is available in OpenAFS -versions 1.4.8 or later and 1.5.35 or later. - -=item B<-help> - -Prints the online help for this command. All other valid options are -ignored. - -=back - -=head1 OUTPUT - -The following message confirms that the command succeeded: - - Created backup volume for I - -=head1 EXAMPLES - -The following example creates a backup version of the volume -C. - - % vos backup user.smith - Created backup volume for user.smith - -=head1 PRIVILEGE REQUIRED - -The issuer must be listed in the F file on the -machine specified with the B<-server> argument 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 - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -This documentation is covered by the IBM Public License Version 1.0. It was -converted from HTML to POD by software written by Chas Williams and Russ -Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. diff --git a/doc/man-pages/pod1/vos_backup.pod.in b/doc/man-pages/pod1/vos_backup.pod.in new file mode 100644 index 000000000..8d0bb2a9f --- /dev/null +++ b/doc/man-pages/pod1/vos_backup.pod.in @@ -0,0 +1,79 @@ +=head1 NAME + +vos_backup - Creates a backup volume for a single read/write volume + +=head1 SYNOPSIS + +=for html +
+ +B S<<< B<-id> > >>> + S<<< [B<-cell> >] >>> + [B<-noauth>] [B<-localauth>] [B<-verbose>] + [B<-encrypt>] [B<-noresolve>] [B<-help>] + +B S<<< B<-i> > >>> [B<-c> >] + [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] + +=for html +
+ +=head1 DESCRIPTION + +The B command clones the indicated read/write volume to create +a backup version, placing it at the same site as the read/write +version. The backup volume's name is the same as the read/write source's +with the addition of the C<.backup> extension. Its volume ID number is the +one allocated for it in the Volume Location Database (VLDB) when the +read/write source was created with the B command. If a backup +version already exists, the new clone replaces it. + +To create a backup version of multiple volumes, use the B +command. + +=head1 OPTIONS + +=over 4 + +=item B<-id> > + +Specifies either the complete name or volume ID number of the read/write +source volume. + +=include fragments/vos-common.pod + +=back + +=head1 OUTPUT + +The following message confirms that the command succeeded: + + Created backup volume for I + +=head1 EXAMPLES + +The following example creates a backup version of the volume +C. + + % vos backup user.smith + Created backup volume for user.smith + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the F file on the +machine specified with the B<-server> argument 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 + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +This documentation is covered by the IBM Public License Version 1.0. It was +converted from HTML to POD by software written by Chas Williams and Russ +Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. diff --git a/doc/man-pages/pod1/vos_dump.pod b/doc/man-pages/pod1/vos_dump.pod deleted file mode 100644 index eb226095c..000000000 --- a/doc/man-pages/pod1/vos_dump.pod +++ /dev/null @@ -1,237 +0,0 @@ -=head1 NAME - -vos_dump - Converts a volume into ASCII format and writes it to a file - -=head1 SYNOPSIS - -=for html -
- -B S<<< B<-id> > >>> - S<<< [B<-time> >] >>> - S<<< [B<-file> >] >>> S<<< [B<-server> >] >>> - S<<< [B<-partition> >] >>> [B<-clone>] [B<-omitdirs>] - S<<< [B<-cell> >] >>> [B<-noauth>] [B<-localauth>] - [B<-verbose>] [B<-encrypt>] [B<-noresolve>] [B<-help>] - -B S<<< B<-i> > >>> - S<<< [B<-t> >] >>> - S<<< [B<-f> >] >>> S<<< [B<-s> >] >>> - S<<< [B<-p> >] >>> - [B<-cl>] [B<-o>] S<<< [B<-ce> >] >>> [B<-noa>] [B<-l>] - [B<-v>] [B<-e>] [B<-nor>] [B<-h>] - -=for html -
- -=head1 DESCRIPTION - -The B command converts the contents of the indicated volume, -which can be read/write, read-only or backup, into ASCII format. The -Volume Server writes the converted contents to the file named by the -B<-file> argument, or to the standard output stream. In the latter case, -the output can be directed to a named pipe, which enables interoperation -with third-party backup utilities. - -To dump the complete contents of a volume (create a I), omit -the B<-time> argument or specify the value C<0> (zero) for it. To create -an I, which includes only the files and directories in -the volume that have modification timestamps later than a certain time, -specify a date and time as the value for the B<-time> argument. - -By default, the vos command interpreter consults the Volume Location -Database (VLDB) to learn the volume's location, so the B<-server> and -B<-partition> arguments are not required. If the B<-id> argument -identifies a read-only volume that resides at multiple sites, the command -dumps the version from just one of them (normally, the one listed first in -the volume's VLDB entry as reported by the B or B command). To dump the read-only volume from a particular site, -use the B<-server> and B<-partition> arguments to specify the site. To -bypass the VLDB lookup entirely, provide a volume ID number (rather than a -volume name) as the value for the B<-id> argument, together with the -B<-server> and B<-partition> arguments. This makes it possible to dump a -volume for which there is no VLDB entry. - -During the dump operation, the volume is inaccessible both to Cache -Managers and to other volume operations. Dumping a volume does not -otherwise affect its status on the partition or its VLDB entry. - -To restore a dumped volume back into AFS, use the B command. - -=head1 CAUTIONS - -Support for incremental dumps is provided to facilitate interoperation -with third-party backup utilities. The B command does not -provide any of the administrative facilities of an actual backup system, -so the administrator must keep manual records of dump times and the -relationship between full and incremental dumps of a volume. For a -volume's contents to be consistent after restoration of incremental dumps, -there must be no gap between the time at which a prior dump of the volume -was created and the value of the B<-time> argument to the B -command that creates the incremental dump. More specifically, for a -read/write volume, the B<-time> argument must specify the time that the -prior dump was performed, and for a read-only or backup volume it must -specify the time that the volume was last released (using the B command) or cloned (using the B or B -command) prior to dumping it. The parent dump can be either a full dump or -another incremental dump. - -=head1 OPTIONS - -=over 4 - -=item B<-id> > - -Specifies either the complete name or volume ID number of the read/write, -read-only, or backup volume to dump. - -=item B<-time> > - -Specifies whether the dump is full or incremental. Omit this argument to -create a full dump, or provide one of three acceptable values: - -=over 4 - -=item * - -The value C<0> (zero) to create a full dump. - -=item * - -A date in the format IBI
BI (month, day and year) to -create an incremental dump that includes only files and directories with -modification timestamps later than midnight (12:00 a.m.) on the indicated -date. Valid values for the year range from C<1970> to C<2037>; higher -values are not valid because the latest possible date in the standard UNIX -representation is in 2038. The command interpreter automatically reduces -later dates to the maximum value. An example is C<01/13/1999>. - -=item * - -A date and time in the format B<">IBI
BI -IB<:>IB<"> to create an incremental dump that includes only files -and directories with modification timestamps later than the specified date -and time. The date format is the same as for a date alone. Express the -time as hours and minutes (I:I) in 24-hour format (for example, -B<20:30> is 8:30 p.m.). Surround the entire expression with double quotes -(C<"">) because it contains a space. An example is C<"01/13/1999 22:30">. - -=back - -=item B<-file> > - -Specifies the pathname of the file to which to write the dump. The file -can be in AFS, but not in the volume being dumped. A partial pathname is -interpreted relative to the current working directory. If this argument is -omitted, the dump is directed to the standard output stream. - -=item B<-server> > - -Specifies the file server machine on which the volume resides. Provide -the B<-partition> argument along with this one. - -=item B<-partition> > - -Specifies the partition on which the volume resides. Provide the -B<-server> argument along with this one. - -=item B<-clone> - -Normally, B locks the volume and dumps it, which blocks writes -to the volume while the dump is in progress. If this flag is given, B will instead clone the volume first (similar to what B -would do) and then dumps the clone. This can significantly decrease the -amount of time the volume is kept locked for dumps of large volumes. - -=item B<-omitdirs> - -By default, B includes all directory objects in an incremental -dump whether they've been changed or not. If this option is given, -unchanged directories will be omitted. This will reduce the size of the -dump and not cause problems if the incremental is restored, as expected, -on top of a volume containing the correct directory structure (such as one -created by restoring previous full and incremental dumps). - -=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 anonymous 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 error 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. This option is available in OpenAFS -versions 1.4.11 or later and 1.5.60 or later. - -=item B<-noresolve> - -Shows all servers as IP addresses instead of the DNS name. This is very -useful when the server address is registered as 127.0.0.1 or when dealing -with multi-homed servers. This option is available in OpenAFS -versions 1.4.8 or later and 1.5.35 or later. - -=item B<-help> - -Prints the online help for this command. All other valid options are -ignored. - -=back - -=head1 EXAMPLES - -The following command writes a full dump of the volume C to -the file F. - - % vos dump -id user.terry -time 0 -file /afs/example.com/common/dumps/terry.dump - -The following command writes an incremental dump of the volume -C to the file C in the current working -directory. Only those files in the volume with modification time stamps -later than 6:00 p.m. on 31 January 1999 are included in the dump. - - % vos dump -id user.smith -time "01/31/1999 18:00" -file smith.990131.dump - -=head1 PRIVILEGE REQUIRED - -The issuer must be listed in the F file on the -machine specified with the B<-server> argument 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. - -If the B<-file> argument is included, the issuer must also have permission -to insert and write in the directory that houses the file. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -This documentation is covered by the IBM Public License Version 1.0. It was -converted from HTML to POD by software written by Chas Williams and Russ -Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. diff --git a/doc/man-pages/pod1/vos_dump.pod.in b/doc/man-pages/pod1/vos_dump.pod.in new file mode 100644 index 000000000..39ab52dbb --- /dev/null +++ b/doc/man-pages/pod1/vos_dump.pod.in @@ -0,0 +1,197 @@ +=head1 NAME + +vos_dump - Converts a volume into ASCII format and writes it to a file + +=head1 SYNOPSIS + +=for html +
+ +B S<<< B<-id> > >>> + S<<< [B<-time> >] >>> + S<<< [B<-file> >] >>> S<<< [B<-server> >] >>> + S<<< [B<-partition> >] >>> [B<-clone>] [B<-omitdirs>] + S<<< [B<-cell> >] >>> [B<-noauth>] [B<-localauth>] + [B<-verbose>] [B<-encrypt>] [B<-noresolve>] [B<-help>] + +B S<<< B<-i> > >>> + S<<< [B<-t> >] >>> + S<<< [B<-f> >] >>> S<<< [B<-s> >] >>> + S<<< [B<-p> >] >>> + [B<-cl>] [B<-o>] S<<< [B<-ce> >] >>> [B<-noa>] [B<-l>] + [B<-v>] [B<-e>] [B<-nor>] [B<-h>] + +=for html +
+ +=head1 DESCRIPTION + +The B command converts the contents of the indicated volume, +which can be read/write, read-only or backup, into ASCII format. The +Volume Server writes the converted contents to the file named by the +B<-file> argument, or to the standard output stream. In the latter case, +the output can be directed to a named pipe, which enables interoperation +with third-party backup utilities. + +To dump the complete contents of a volume (create a I), omit +the B<-time> argument or specify the value C<0> (zero) for it. To create +an I, which includes only the files and directories in +the volume that have modification timestamps later than a certain time, +specify a date and time as the value for the B<-time> argument. + +By default, the vos command interpreter consults the Volume Location +Database (VLDB) to learn the volume's location, so the B<-server> and +B<-partition> arguments are not required. If the B<-id> argument +identifies a read-only volume that resides at multiple sites, the command +dumps the version from just one of them (normally, the one listed first in +the volume's VLDB entry as reported by the B or B command). To dump the read-only volume from a particular site, +use the B<-server> and B<-partition> arguments to specify the site. To +bypass the VLDB lookup entirely, provide a volume ID number (rather than a +volume name) as the value for the B<-id> argument, together with the +B<-server> and B<-partition> arguments. This makes it possible to dump a +volume for which there is no VLDB entry. + +During the dump operation, the volume is inaccessible both to Cache +Managers and to other volume operations. Dumping a volume does not +otherwise affect its status on the partition or its VLDB entry. + +To restore a dumped volume back into AFS, use the B command. + +=head1 CAUTIONS + +Support for incremental dumps is provided to facilitate interoperation +with third-party backup utilities. The B command does not +provide any of the administrative facilities of an actual backup system, +so the administrator must keep manual records of dump times and the +relationship between full and incremental dumps of a volume. For a +volume's contents to be consistent after restoration of incremental dumps, +there must be no gap between the time at which a prior dump of the volume +was created and the value of the B<-time> argument to the B +command that creates the incremental dump. More specifically, for a +read/write volume, the B<-time> argument must specify the time that the +prior dump was performed, and for a read-only or backup volume it must +specify the time that the volume was last released (using the B command) or cloned (using the B or B +command) prior to dumping it. The parent dump can be either a full dump or +another incremental dump. + +=head1 OPTIONS + +=over 4 + +=item B<-id> > + +Specifies either the complete name or volume ID number of the read/write, +read-only, or backup volume to dump. + +=item B<-time> > + +Specifies whether the dump is full or incremental. Omit this argument to +create a full dump, or provide one of three acceptable values: + +=over 4 + +=item * + +The value C<0> (zero) to create a full dump. + +=item * + +A date in the format IBI
BI (month, day and year) to +create an incremental dump that includes only files and directories with +modification timestamps later than midnight (12:00 a.m.) on the indicated +date. Valid values for the year range from C<1970> to C<2037>; higher +values are not valid because the latest possible date in the standard UNIX +representation is in 2038. The command interpreter automatically reduces +later dates to the maximum value. An example is C<01/13/1999>. + +=item * + +A date and time in the format B<">IBI
BI +IB<:>IB<"> to create an incremental dump that includes only files +and directories with modification timestamps later than the specified date +and time. The date format is the same as for a date alone. Express the +time as hours and minutes (I:I) in 24-hour format (for example, +B<20:30> is 8:30 p.m.). Surround the entire expression with double quotes +(C<"">) because it contains a space. An example is C<"01/13/1999 22:30">. + +=back + +=item B<-file> > + +Specifies the pathname of the file to which to write the dump. The file +can be in AFS, but not in the volume being dumped. A partial pathname is +interpreted relative to the current working directory. If this argument is +omitted, the dump is directed to the standard output stream. + +=item B<-server> > + +Specifies the file server machine on which the volume resides. Provide +the B<-partition> argument along with this one. + +=item B<-partition> > + +Specifies the partition on which the volume resides. Provide the +B<-server> argument along with this one. + +=item B<-clone> + +Normally, B locks the volume and dumps it, which blocks writes +to the volume while the dump is in progress. If this flag is given, B will instead clone the volume first (similar to what B +would do) and then dumps the clone. This can significantly decrease the +amount of time the volume is kept locked for dumps of large volumes. + +=item B<-omitdirs> + +By default, B includes all directory objects in an incremental +dump whether they've been changed or not. If this option is given, +unchanged directories will be omitted. This will reduce the size of the +dump and not cause problems if the incremental is restored, as expected, +on top of a volume containing the correct directory structure (such as one +created by restoring previous full and incremental dumps). + +=include fragments/vos-common.pod + +=back + +=head1 EXAMPLES + +The following command writes a full dump of the volume C to +the file F. + + % vos dump -id user.terry -time 0 -file /afs/example.com/common/dumps/terry.dump + +The following command writes an incremental dump of the volume +C to the file C in the current working +directory. Only those files in the volume with modification time stamps +later than 6:00 p.m. on 31 January 1999 are included in the dump. + + % vos dump -id user.smith -time "01/31/1999 18:00" -file smith.990131.dump + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the F file on the +machine specified with the B<-server> argument 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. + +If the B<-file> argument is included, the issuer must also have permission +to insert and write in the directory that houses the file. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +This documentation is covered by the IBM Public License Version 1.0. It was +converted from HTML to POD by software written by Chas Williams and Russ +Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.