From 9ec343cf4292e178fa1e4a9757232dc983ea9ba3 Mon Sep 17 00:00:00 2001 From: Jason Edgecombe Date: Sun, 1 Aug 2010 21:39:56 -0400 Subject: [PATCH] Factor out the common text in vos_addsite, vos_copy, and vos_zap Factor out some common options out of the man pages. LICENSE IPL Change-Id: Ic79e53a2d6464cc62d49987ab58d38c9898f372b Reviewed-on: http://gerrit.openafs.org/2496 Reviewed-by: Derrick Brashear Tested-by: Derrick Brashear --- doc/man-pages/pod1/.gitignore | 3 + doc/man-pages/pod1/fragments/vos-common.pod | 42 +++++++ doc/man-pages/pod1/vos_addsite.pod | 173 -------------------------- doc/man-pages/pod1/vos_addsite.pod.in | 133 ++++++++++++++++++++ doc/man-pages/pod1/vos_copy.pod | 182 ---------------------------- doc/man-pages/pod1/vos_copy.pod.in | 152 +++++++++++++++++++++++ doc/man-pages/pod1/vos_zap.pod | 180 --------------------------- doc/man-pages/pod1/vos_zap.pod.in | 139 +++++++++++++++++++++ 8 files changed, 469 insertions(+), 535 deletions(-) create mode 100644 doc/man-pages/pod1/fragments/vos-common.pod delete mode 100644 doc/man-pages/pod1/vos_addsite.pod create mode 100644 doc/man-pages/pod1/vos_addsite.pod.in delete mode 100644 doc/man-pages/pod1/vos_copy.pod create mode 100644 doc/man-pages/pod1/vos_copy.pod.in delete mode 100644 doc/man-pages/pod1/vos_zap.pod create mode 100644 doc/man-pages/pod1/vos_zap.pod.in diff --git a/doc/man-pages/pod1/.gitignore b/doc/man-pages/pod1/.gitignore index b794ac3..1a1d4d6 100644 --- a/doc/man-pages/pod1/.gitignore +++ b/doc/man-pages/pod1/.gitignore @@ -20,3 +20,6 @@ /pts_setmax.pod /pts_sleep.pod /pts_source.pod +/vos_addsite.pod +/vos_copy.pod +/vos_zap.pod diff --git a/doc/man-pages/pod1/fragments/vos-common.pod b/doc/man-pages/pod1/fragments/vos-common.pod new file mode 100644 index 0000000..5a05f37 --- /dev/null +++ b/doc/man-pages/pod1/fragments/vos-common.pod @@ -0,0 +1,42 @@ +=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. 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. diff --git a/doc/man-pages/pod1/vos_addsite.pod b/doc/man-pages/pod1/vos_addsite.pod deleted file mode 100644 index 5bc3973..0000000 --- a/doc/man-pages/pod1/vos_addsite.pod +++ /dev/null @@ -1,173 +0,0 @@ -=head1 NAME - -vos_addsite - Adds a read-only site definition to a volume's VLDB entry - -=head1 SYNOPSIS - -=for html -
- -B S<<< B<-server> > >>> - S<<< B<-partition> > >>> - S<<< B<-id> > >>> - S<<< [B<-roid> >] >>> - [B<-valid>] S<<< [B<-cell> >] >>> - [B<-noauth>] [B<-localauth>] - [B<-verbose>] [B<-encrypt>] [B<-noresolve>] [B<-help>] - -B S<<< B<-s> > >>> - S<<< B<-p> > >>> - S<<< B<-i> > >>> - S<<< [B<-r> >] >>> - [B<-va>] [B<-c> >] >>> [B<-noa>] [B<-l>] - [B<-ve>] [B<-e>] [B<-nor>] [B<-h>] - -=for html -
- -=head1 DESCRIPTION - -The B command defines a new read-only site (partition on a -file server machine, specified by the B<-server> and B<-partition> -arguments) in the Volume Location Database (VLDB) entry of the read/write -volume named by the B<-id> argument. When the B command is -next issued against the read/write volume, a read-only copy of it is -distributed to all of the read-only sites, including the newly defined -one. - -=head1 CAUTIONS - -A volume's VLDB entry accommodates a maximum number of 16 site -definitions. The site housing the read/write and backup versions of the -volume counts as one site, the backup snapshot counts as one site, and one -site should be reserved for a transient clone for volume moves and similar -operations. Each read-only site counts as an additional site (even the -read-only site defined on the same file server machine and partition as -the read/write site counts as a separate site). The limit in the VLDB -entry effectively determines the maximum number of copies of the volume -that are available to AFS clients. - -Attempts to create additional sites by using this command fail with an -error. - -=head1 OPTIONS - -=over 4 - -=item B<-server> > - -Identifies the file server machine where the read-only volume is to -reside. 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> > - -Identifies the partition where the read-only volume is to reside, on the -file server machine named by the B<-server> argument. Provide the -partition's complete name with preceding slash (for example, C) -or use one of the three acceptable abbreviated forms. For details, see -L. - -=item B<-id> > - -Specifies either the complete name or volume ID number of the read/write -source volume. - -=item B<-roid> > - -Specifies either the complete name or volume ID number of the readonly -volume. This will only be honored if the source read/write volume does not -already have a readonly volume ID associated with it. If the source -read/write volume already has a readonly volume ID, the specified ID will -be ignored, and a warning will be printed. - -If this is not specified and the source read/write volume does not already -have a readonly volume ID, a volume ID for the readonly volume will be -allocated for it when the B command is run. - -The automatically allocated readonly volume IDs should be fine for almost -all cases, so you should almost never need to specify them explicitly. -This option is available in OpenAFS versions 1.5.61 or later. - -=item B<-valid> - -Marks the site as up-to-date in the VLDB. You should only do this if the -new site already has a current readonly replica of the volume, but for -some reason it is not in the VLDB as a replica site. This is useful when -an existing read-only volume is dumped and restored with the B<-readonly> -flag at the new site. This option is available in OpenAFS clients 1.4.7 or -later and 1.5.31 or later. This option can be used with OpenAFS server -versions later than 1.4.1 or 1.5.0. - -=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 EXAMPLES - -The following example, appropriate in the State University cell, defines a -read-only site for the cell's C volume. - - % vos addsite -server sv7.stateu.edu -partition /vicepb -id root.afs - -=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, -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_addsite.pod.in b/doc/man-pages/pod1/vos_addsite.pod.in new file mode 100644 index 0000000..c9645e9 --- /dev/null +++ b/doc/man-pages/pod1/vos_addsite.pod.in @@ -0,0 +1,133 @@ +=head1 NAME + +vos_addsite - Adds a read-only site definition to a volume's VLDB entry + +=head1 SYNOPSIS + +=for html +
+ +B S<<< B<-server> > >>> + S<<< B<-partition> > >>> + S<<< B<-id> > >>> + S<<< [B<-roid> >] >>> + [B<-valid>] S<<< [B<-cell> >] >>> + [B<-noauth>] [B<-localauth>] + [B<-verbose>] [B<-encrypt>] [B<-noresolve>] [B<-help>] + +B S<<< B<-s> > >>> + S<<< B<-p> > >>> + S<<< B<-i> > >>> + S<<< [B<-r> >] >>> + [B<-va>] [B<-c> >] >>> [B<-noa>] [B<-l>] + [B<-ve>] [B<-e>] [B<-nor>] [B<-h>] + +=for html +
+ +=head1 DESCRIPTION + +The B command defines a new read-only site (partition on a +file server machine, specified by the B<-server> and B<-partition> +arguments) in the Volume Location Database (VLDB) entry of the read/write +volume named by the B<-id> argument. When the B command is +next issued against the read/write volume, a read-only copy of it is +distributed to all of the read-only sites, including the newly defined +one. + +=head1 CAUTIONS + +A volume's VLDB entry accommodates a maximum number of 16 site +definitions. The site housing the read/write and backup versions of the +volume counts as one site, the backup snapshot counts as one site, and one +site should be reserved for a transient clone for volume moves and similar +operations. Each read-only site counts as an additional site (even the +read-only site defined on the same file server machine and partition as +the read/write site counts as a separate site). The limit in the VLDB +entry effectively determines the maximum number of copies of the volume +that are available to AFS clients. + +Attempts to create additional sites by using this command fail with an +error. + +=head1 OPTIONS + +=over 4 + +=item B<-server> > + +Identifies the file server machine where the read-only volume is to +reside. 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> > + +Identifies the partition where the read-only volume is to reside, on the +file server machine named by the B<-server> argument. Provide the +partition's complete name with preceding slash (for example, C) +or use one of the three acceptable abbreviated forms. For details, see +L. + +=item B<-id> > + +Specifies either the complete name or volume ID number of the read/write +source volume. + +=item B<-roid> > + +Specifies either the complete name or volume ID number of the readonly +volume. This will only be honored if the source read/write volume does not +already have a readonly volume ID associated with it. If the source +read/write volume already has a readonly volume ID, the specified ID will +be ignored, and a warning will be printed. + +If this is not specified and the source read/write volume does not already +have a readonly volume ID, a volume ID for the readonly volume will be +allocated for it when the B command is run. + +The automatically allocated readonly volume IDs should be fine for almost +all cases, so you should almost never need to specify them explicitly. +This option is available in OpenAFS versions 1.5.61 or later. + +=item B<-valid> + +Marks the site as up-to-date in the VLDB. You should only do this if the +new site already has a current readonly replica of the volume, but for +some reason it is not in the VLDB as a replica site. This is useful when +an existing read-only volume is dumped and restored with the B<-readonly> +flag at the new site. This option is available in OpenAFS clients 1.4.7 or +later and 1.5.31 or later. This option can be used with OpenAFS server +versions later than 1.4.1 or 1.5.0. + +=include fragments/vos-common.pod + +=back + +=head1 EXAMPLES + +The following example, appropriate in the State University cell, defines a +read-only site for the cell's C volume. + + % vos addsite -server sv7.stateu.edu -partition /vicepb -id root.afs + +=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, +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_copy.pod b/doc/man-pages/pod1/vos_copy.pod deleted file mode 100644 index b0c3bd9..0000000 --- a/doc/man-pages/pod1/vos_copy.pod +++ /dev/null @@ -1,182 +0,0 @@ -=head1 NAME - -vos_copy - Make a copy of a volume - -=head1 SYNOPSIS - -=for html -
- -B S<<< [B<-id>] > >>> - S<<< [B<-fromserver>] > >>> - S<<< [B<-frompartition>] > >>> - S<<< [B<-toname>] > >>> - S<<< [B<-toserver>] > >>> - S<<< [B<-topartition>] > >>> - [B<-offline>] [B<-readonly>] [B<-live>] S<<< [B<-cell> >] >>> - [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-encrypt>] [B<-noresolve>] - [B<-help>] - -B S<<< [B<-i>] > >>> - S<<< [B<-froms>] > >>> - S<<< [B<-fromp>] > >>> - S<<< [B<-ton>] > >>> - S<<< [B<-tos>] > >>> - S<<< [B<-top>] > >>> - [B<-o>] [B<-r>] [B<-li>] S<<< [B<-c> >] >>> - [B<-noa>] [B<-lo>] [B<-v>] [B<-e>] [B<-nor>] - [B<-h>] - -=for html -
- -=head1 DESCRIPTION - -The B command makes a copy of a volume with a new name. It is -equivalent to B followed by B, but doesn't require -the volume be stored locally by the client. - -=head1 CAUTIONS - -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<-toname>] > - -The complete name of the new volume to create. - -=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<-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<-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 - -This command has no output unless C<-verbose> is specified or there is -an error. - -=head1 EXAMPLES - -The following example makes a verbose copy of the C volume named -C in the cell C. The volume and copy both reside on -C of C. - - % vos copy test server1 a test2 server1 a -cell localcell -verbose - Starting transaction on source volume 536870921 ... done - Allocating new volume id for clone of volume 536870921 ... done - Allocating new volume id for copy of volume 536870921 ... done - Cloning source volume 536870921 ... done - Ending the transaction on the source volume 536870921 ... done - Starting transaction on the cloned volume 536870926 ... done - Setting flags on cloned volume 536870926 ... done - Getting status of cloned volume 536870926 ... done - Creating the destination volume 536870927 ... done - Setting volume flags on destination volume 536870927 ... done - Dumping from clone 536870926 on source to volume 536870927 on destination ... done - Ending transaction on cloned volume 536870926 ... done - Starting transaction on source volume 536870921 ... done - Doing the incremental dump from source to destination for volume 536870921 ... done - Setting volume flags on destination volume 536870927 ... done - Ending transaction on destination volume 536870927 ... done - Ending transaction on source volume 536870921 ... done - Starting transaction on the cloned volume 536870926 ... done - Deleting the cloned volume 536870926 ... done - Ending transaction on cloned volume 536870926 ... done - Created the VLDB entry for the volume test2 536870927 - Volume 536870921 copied from server1 /vicepa to test2 on server1 /vicepa - -=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, -L - -=head1 COPYRIGHT - -Copyright 2007 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. diff --git a/doc/man-pages/pod1/vos_copy.pod.in b/doc/man-pages/pod1/vos_copy.pod.in new file mode 100644 index 0000000..50cc0a0 --- /dev/null +++ b/doc/man-pages/pod1/vos_copy.pod.in @@ -0,0 +1,152 @@ +=head1 NAME + +vos_copy - Make a copy of a volume + +=head1 SYNOPSIS + +=for html +
+ +B S<<< [B<-id>] > >>> + S<<< [B<-fromserver>] > >>> + S<<< [B<-frompartition>] > >>> + S<<< [B<-toname>] > >>> + S<<< [B<-toserver>] > >>> + S<<< [B<-topartition>] > >>> + [B<-offline>] [B<-readonly>] [B<-live>] S<<< [B<-cell> >] >>> + [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-encrypt>] [B<-noresolve>] + [B<-help>] + +B S<<< [B<-i>] > >>> + S<<< [B<-froms>] > >>> + S<<< [B<-fromp>] > >>> + S<<< [B<-ton>] > >>> + S<<< [B<-tos>] > >>> + S<<< [B<-top>] > >>> + [B<-o>] [B<-r>] [B<-li>] S<<< [B<-c> >] >>> + [B<-noa>] [B<-lo>] [B<-v>] [B<-e>] [B<-nor>] + [B<-h>] + +=for html +
+ +=head1 DESCRIPTION + +The B command makes a copy of a volume with a new name. It is +equivalent to B followed by B, but doesn't require +the volume be stored locally by the client. + +=head1 CAUTIONS + +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<-toname>] > + +The complete name of the new volume to create. + +=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<-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. + +=include fragments/vos-common.pod + +=back + +=head1 OUTPUT + +This command has no output unless C<-verbose> is specified or there is +an error. + +=head1 EXAMPLES + +The following example makes a verbose copy of the C volume named +C in the cell C. The volume and copy both reside on +C of C. + + % vos copy test server1 a test2 server1 a -cell localcell -verbose + Starting transaction on source volume 536870921 ... done + Allocating new volume id for clone of volume 536870921 ... done + Allocating new volume id for copy of volume 536870921 ... done + Cloning source volume 536870921 ... done + Ending the transaction on the source volume 536870921 ... done + Starting transaction on the cloned volume 536870926 ... done + Setting flags on cloned volume 536870926 ... done + Getting status of cloned volume 536870926 ... done + Creating the destination volume 536870927 ... done + Setting volume flags on destination volume 536870927 ... done + Dumping from clone 536870926 on source to volume 536870927 on destination ... done + Ending transaction on cloned volume 536870926 ... done + Starting transaction on source volume 536870921 ... done + Doing the incremental dump from source to destination for volume 536870921 ... done + Setting volume flags on destination volume 536870927 ... done + Ending transaction on destination volume 536870927 ... done + Ending transaction on source volume 536870921 ... done + Starting transaction on the cloned volume 536870926 ... done + Deleting the cloned volume 536870926 ... done + Ending transaction on cloned volume 536870926 ... done + Created the VLDB entry for the volume test2 536870927 + Volume 536870921 copied from server1 /vicepa to test2 on server1 /vicepa + +=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, +L + +=head1 COPYRIGHT + +Copyright 2007 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. diff --git a/doc/man-pages/pod1/vos_zap.pod b/doc/man-pages/pod1/vos_zap.pod deleted file mode 100644 index ae31fef..0000000 --- a/doc/man-pages/pod1/vos_zap.pod +++ /dev/null @@ -1,180 +0,0 @@ -=head1 NAME - -vos_zap - Removes a volume from its site without writing to the VLDB - -=head1 SYNOPSIS - -=for html -
- -B S<<< B<-server> > >>> - S<<< B<-partition> > >>> - S<<< B<-id> > >>> - [B<-force>] [B<-backup>] - S<<< [B<-cell> >] >>> - [B<-noauth>] [B<-localauth>] - [B<-verbose>] [B<-encrypt>] [B<-noresolve>] [B<-help>] - -B S<<< B<-s> > >>> - S<<< B<-p> > >>> - S<<< B<-i> > >>> - [B<-f>] [B<-b>] S<<< [B<-c> >] >>> - [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] - -=for html -
- -=head1 DESCRIPTION - -The B command removes the volume with the specified I -from the site defined by the B<-server> and B<-partition> arguments, -without attempting to change the corresponding Volume Location Database -(VLDB) entry. If removing the volume can possibly result in incorrect data -in the VLDB, a warning message is displayed. - -The B<-force> flag removes a volume even if it cannot be "attached" -(brought online), which can happen either because the volume is extremely -damaged or because the Salvager functioned abnormally. Without this flag, -this command cannot remove volumes that are not attachable. See also -L. - -To remove the specified read/write volume's backup version at the same -time, include the B<-backup> flag. - -=head1 CAUTIONS - -Do not use this command as the standard way to remove a volume, as it is -likely to put the VLDB out of sync with the volumes on servers. Use the -B command instead. - -This command is useful in situations where it is important to delete the -volume, but for some reason the VLDB is unreachable -- for example, -because the Volume Location Server is unavailable. The issuer can remove -the VLDB entry later with the B or B command, or -it is removed automatically when the B and B -commands run. - -To remove a read-only site defined in the VLDB by mistake, before a copy -actually exists at the site, use the B command. To remove an -entire VLDB entry without affecting volumes at their sites, use the B command. - -Do not use the B<-force> flag if the volume is online, but only when -attempts to remove the volume with the B or the B -command have failed, or the volume definitely cannot be attached. After -using the B<-force> flag, make sure that the volume's VLDB entry is also -removed (issue the B command if necessary). - -Adding the B<-force> flag makes the command take considerably longer -- -about as long as a salvage of the relevant partition -- since the Volume -Server examines all inodes on the partition for traces of the volume. - -=head1 OPTIONS - -=over 4 - -=item B<-server> > - -Identifies the file server machine from which to remove 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<-partition> > - -Identifies the partition (on the file server machine specified by the -B<-server> argument) from which to remove the volume. Provide the -partition's complete name with preceding slash (for example, C) -or use one of the three acceptable abbreviated forms. For details, see -L. - -=item B<-id> > - -Specifies the volume ID number of the volume to remove, which can be of -any of the three types. The volume name is not acceptable. - -=item B<-force> - -Removes the volume even though it cannot be attached (brought online). Use -only after the failure of previous attempts to remove the volume by using -the B command or the B command without this flag. - -=item B<-backup> - -Removes the backup version of the read/write volume specified by the -B<-id> argument. Do not use this flag if the B<-id> argument identifies a -read-only or backup 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. 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 example removes the volume with volume ID 536870988 from the -F partition of the file server machine C, without -noting the change in the VLDB. - - % vos zap -server fs6.abc.com -partition f -id 536870988 - -=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, -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_zap.pod.in b/doc/man-pages/pod1/vos_zap.pod.in new file mode 100644 index 0000000..b3f3517 --- /dev/null +++ b/doc/man-pages/pod1/vos_zap.pod.in @@ -0,0 +1,139 @@ +=head1 NAME + +vos_zap - Removes a volume from its site without writing to the VLDB + +=head1 SYNOPSIS + +=for html +
+ +B S<<< B<-server> > >>> + S<<< B<-partition> > >>> + S<<< B<-id> > >>> + [B<-force>] [B<-backup>] + S<<< [B<-cell> >] >>> + [B<-noauth>] [B<-localauth>] + [B<-verbose>] [B<-encrypt>] [B<-noresolve>] [B<-help>] + +B S<<< B<-s> > >>> + S<<< B<-p> > >>> + S<<< B<-i> > >>> + [B<-f>] [B<-b>] S<<< [B<-c> >] >>> + [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] + +=for html +
+ +=head1 DESCRIPTION + +The B command removes the volume with the specified I +from the site defined by the B<-server> and B<-partition> arguments, +without attempting to change the corresponding Volume Location Database +(VLDB) entry. If removing the volume can possibly result in incorrect data +in the VLDB, a warning message is displayed. + +The B<-force> flag removes a volume even if it cannot be "attached" +(brought online), which can happen either because the volume is extremely +damaged or because the Salvager functioned abnormally. Without this flag, +this command cannot remove volumes that are not attachable. See also +L. + +To remove the specified read/write volume's backup version at the same +time, include the B<-backup> flag. + +=head1 CAUTIONS + +Do not use this command as the standard way to remove a volume, as it is +likely to put the VLDB out of sync with the volumes on servers. Use the +B command instead. + +This command is useful in situations where it is important to delete the +volume, but for some reason the VLDB is unreachable -- for example, +because the Volume Location Server is unavailable. The issuer can remove +the VLDB entry later with the B or B command, or +it is removed automatically when the B and B +commands run. + +To remove a read-only site defined in the VLDB by mistake, before a copy +actually exists at the site, use the B command. To remove an +entire VLDB entry without affecting volumes at their sites, use the B command. + +Do not use the B<-force> flag if the volume is online, but only when +attempts to remove the volume with the B or the B +command have failed, or the volume definitely cannot be attached. After +using the B<-force> flag, make sure that the volume's VLDB entry is also +removed (issue the B command if necessary). + +Adding the B<-force> flag makes the command take considerably longer -- +about as long as a salvage of the relevant partition -- since the Volume +Server examines all inodes on the partition for traces of the volume. + +=head1 OPTIONS + +=over 4 + +=item B<-server> > + +Identifies the file server machine from which to remove 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<-partition> > + +Identifies the partition (on the file server machine specified by the +B<-server> argument) from which to remove the volume. Provide the +partition's complete name with preceding slash (for example, C) +or use one of the three acceptable abbreviated forms. For details, see +L. + +=item B<-id> > + +Specifies the volume ID number of the volume to remove, which can be of +any of the three types. The volume name is not acceptable. + +=item B<-force> + +Removes the volume even though it cannot be attached (brought online). Use +only after the failure of previous attempts to remove the volume by using +the B command or the B command without this flag. + +=item B<-backup> + +Removes the backup version of the read/write volume specified by the +B<-id> argument. Do not use this flag if the B<-id> argument identifies a +read-only or backup volume. + +=include fragments/vos-common.pod + +=back + +=head1 EXAMPLES + +The following example removes the volume with volume ID 536870988 from the +F partition of the file server machine C, without +noting the change in the VLDB. + + % vos zap -server fs6.abc.com -partition f -id 536870988 + +=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, +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. -- 1.9.4