From 3ff8ef499c56008f4d2ebf5b81e08e98eb0c0826 Mon Sep 17 00:00:00 2001 From: Andrew Deason Date: Thu, 28 Jun 2012 15:30:40 -0500 Subject: [PATCH] doc: Consolidate CAUTIONS notes about volume size Change-Id: I264906fb3f61db62c483982f613654a9a897f417 Reviewed-on: http://gerrit.openafs.org/7597 Reviewed-by: Jeffrey Altman Tested-by: Jeffrey Altman --- doc/man-pages/NTMakefile | 11 + doc/man-pages/pod1/.gitignore | 11 + doc/man-pages/pod1/fragments/volsize-caution.pod | 1 + doc/man-pages/pod1/fs_listquota.pod | 124 ------- doc/man-pages/pod1/fs_listquota.pod.in | 124 +++++++ doc/man-pages/pod1/fs_quota.pod | 92 ----- doc/man-pages/pod1/fs_quota.pod.in | 92 +++++ doc/man-pages/pod1/fs_setquota.pod | 99 ----- doc/man-pages/pod1/fs_setquota.pod.in | 99 +++++ doc/man-pages/pod1/fs_setvol.pod | 113 ------ doc/man-pages/pod1/fs_setvol.pod.in | 113 ++++++ doc/man-pages/pod1/vos.pod | 326 ----------------- doc/man-pages/pod1/vos.pod.in | 326 +++++++++++++++++ doc/man-pages/pod1/vos_clone.pod | 172 --------- doc/man-pages/pod1/vos_clone.pod.in | 172 +++++++++ doc/man-pages/pod1/vos_copy.pod.in | 2 +- doc/man-pages/pod1/vos_create.pod | 213 ----------- doc/man-pages/pod1/vos_create.pod.in | 213 +++++++++++ doc/man-pages/pod1/vos_examine.pod | 438 ----------------------- doc/man-pages/pod1/vos_examine.pod.in | 438 +++++++++++++++++++++++ doc/man-pages/pod1/vos_move.pod | 212 ----------- doc/man-pages/pod1/vos_move.pod.in | 212 +++++++++++ doc/man-pages/pod1/vos_partinfo.pod | 145 -------- doc/man-pages/pod1/vos_partinfo.pod.in | 145 ++++++++ doc/man-pages/pod1/vos_shadow.pod | 195 ---------- doc/man-pages/pod1/vos_shadow.pod.in | 195 ++++++++++ 26 files changed, 2153 insertions(+), 2130 deletions(-) create mode 100644 doc/man-pages/pod1/fragments/volsize-caution.pod delete mode 100644 doc/man-pages/pod1/fs_listquota.pod create mode 100644 doc/man-pages/pod1/fs_listquota.pod.in delete mode 100644 doc/man-pages/pod1/fs_quota.pod create mode 100644 doc/man-pages/pod1/fs_quota.pod.in delete mode 100644 doc/man-pages/pod1/fs_setquota.pod create mode 100644 doc/man-pages/pod1/fs_setquota.pod.in delete mode 100644 doc/man-pages/pod1/fs_setvol.pod create mode 100644 doc/man-pages/pod1/fs_setvol.pod.in delete mode 100644 doc/man-pages/pod1/vos.pod create mode 100644 doc/man-pages/pod1/vos.pod.in delete mode 100644 doc/man-pages/pod1/vos_clone.pod create mode 100644 doc/man-pages/pod1/vos_clone.pod.in delete mode 100644 doc/man-pages/pod1/vos_create.pod create mode 100644 doc/man-pages/pod1/vos_create.pod.in delete mode 100644 doc/man-pages/pod1/vos_examine.pod create mode 100644 doc/man-pages/pod1/vos_examine.pod.in delete mode 100644 doc/man-pages/pod1/vos_move.pod create mode 100644 doc/man-pages/pod1/vos_move.pod.in delete mode 100644 doc/man-pages/pod1/vos_partinfo.pod create mode 100644 doc/man-pages/pod1/vos_partinfo.pod.in delete mode 100644 doc/man-pages/pod1/vos_shadow.pod create mode 100644 doc/man-pages/pod1/vos_shadow.pod.in diff --git a/doc/man-pages/NTMakefile b/doc/man-pages/NTMakefile index 38c12c5..a4faf25 100644 --- a/doc/man-pages/NTMakefile +++ b/doc/man-pages/NTMakefile @@ -355,6 +355,10 @@ clean:: $(CD) html $(DEL) /s *.html $(CD) .. + $(DEL) pod1\fs_listquota.pod + $(DEL) pod1\fs_quota.pod + $(DEL) pod1\fs_setquota.pod + $(DEL) pod1\fs_setvol.pod $(DEL) pod1\pts_adduser.pod $(DEL) pod1\pts_chown.pod $(DEL) pod1\pts_creategroup.pod @@ -373,8 +377,15 @@ clean:: $(DEL) pod1\pts_setmax.pod $(DEL) pod1\pts_sleep.pod $(DEL) pod1\pts_source.pod + $(DEL) pod1\vos.pod $(DEL) pod1\vos_addsite.pod + $(DEL) pod1\vos_clone.pod $(DEL) pod1\vos_copy.pod + $(DEL) pod1\vos_create.pod + $(DEL) pod1\vos_examine.pod + $(DEL) pod1\vos_move.pod + $(DEL) pod1\vos_partinfo.pod + $(DEL) pod1\vos_shadow.pod $(DEL) pod1\vos_zap.pod $(DEL) pod8\dafileserver.pod $(DEL) pod8\dasalvager.pod diff --git a/doc/man-pages/pod1/.gitignore b/doc/man-pages/pod1/.gitignore index 9b024d6..fc1716f 100644 --- a/doc/man-pages/pod1/.gitignore +++ b/doc/man-pages/pod1/.gitignore @@ -2,6 +2,10 @@ # git ls-files -i --exclude-standard # to check that you haven't inadvertently ignored any tracked files. +/fs_listquota.pod +/fs_quota.pod +/fs_setquota.pod +/fs_setvol.pod /pts_adduser.pod /pts_chown.pod /pts_creategroup.pod @@ -20,8 +24,15 @@ /pts_setmax.pod /pts_sleep.pod /pts_source.pod +/vos.pod /vos_addsite.pod /vos_backup.pod /vos_copy.pod +/vos_clone.pod +/vos_create.pod /vos_dump.pod +/vos_examine.pod +/vos_move.pod +/vos_partinfo.pod +/vos_shadow.pod /vos_zap.pod diff --git a/doc/man-pages/pod1/fragments/volsize-caution.pod b/doc/man-pages/pod1/fragments/volsize-caution.pod new file mode 100644 index 0000000..92fa418 --- /dev/null +++ b/doc/man-pages/pod1/fragments/volsize-caution.pod @@ -0,0 +1 @@ +Currently, the maximum size of a volume is 2 terabytes (2^31 bytes). diff --git a/doc/man-pages/pod1/fs_listquota.pod b/doc/man-pages/pod1/fs_listquota.pod deleted file mode 100644 index 1a9e5bd..0000000 --- a/doc/man-pages/pod1/fs_listquota.pod +++ /dev/null @@ -1,124 +0,0 @@ -=head1 NAME - -fs_listquota - Displays quota information for a volume - -=head1 SYNOPSIS - -=for html -
- -B S<<< [B<-path> >+] >>> [B<-human>] [B<-help>] - -B S<<< [B<-p> >+] >>> [B<-hu>] [B<-he>] - -B S<<< [B<-p> >+] >>> [B<-hu>] [B<-he>] - -=for html -
- -=head1 DESCRIPTION - -The B command displays information about the volume -containing each specified directory or file (its name, quota, and amount -of disk space used), along with an indicator of the percentage of space -used on the host partition. - -To display more information about the host partition, use the B command. - -To set volume quota, use the B or B command. - -=head1 CAUTIONS - -Currently, the maximum size of a volume is 2 terabytes (2^31 bytes). - -=head1 OPTIONS - -=over 4 - -=item B<-path> >+ - -Names a file or directory that resides in the volume about which to -produce output. Partial pathnames are interpreted relative to the current -working directory, which is also the default value if this argument is -omitted. - -=item B<-human> - -Print space in a "human-readable" format. Instead of always printing space -in kilobytes, show disk space in kilobytes, megabytes, gigabytes, -terabytes, or petabytes, as appropriate. - -=item B<-help> - -Prints the online help for this command. All other valid options are -ignored. - -=back - -=head1 OUTPUT - -The output displays information about the volume that houses each -specified directory or file, in a tabular format that uses the following -headers: - -=over 4 - -=item Volume Name - -The name of the volume. - -=item Quota - -The volume's quota in kilobytes, or the string C to indicate an -unlimited quota. - -=item Used - -The amount of space used. If B<-human> is not specified, this value is in -kilobytes. - -=item % Used - -The percentage of the volume's quota that is used (the C statistic -divided by the C statistic, times 100). - -=item Partition - -The percentage of space used on the partition that houses the -volume. Although not directly related to how much of the user's quota is -used, it is reported because a full partition can cause writing of data -back to the volume to fail even when the volume has not reached its quota. - -=back - -=head1 EXAMPLES - -The following example shows the output for the volume C: - - % fs listquota -path /afs/example.com/usr/smith - Volume Name Quota Used % Used Partition - user.smith 15000 5071 34% 86% - -=head1 PRIVILEGE REQUIRED - -The issuer must have the C (read) permission on the ACL of the root -directory of the volume that houses the file or directory named by the -B<-path> argument, and C (list) permission on the ACL of each -directory that precedes it in the pathname. - -=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/fs_listquota.pod.in b/doc/man-pages/pod1/fs_listquota.pod.in new file mode 100644 index 0000000..f13e5bb --- /dev/null +++ b/doc/man-pages/pod1/fs_listquota.pod.in @@ -0,0 +1,124 @@ +=head1 NAME + +fs_listquota - Displays quota information for a volume + +=head1 SYNOPSIS + +=for html +
+ +B S<<< [B<-path> >+] >>> [B<-human>] [B<-help>] + +B S<<< [B<-p> >+] >>> [B<-hu>] [B<-he>] + +B S<<< [B<-p> >+] >>> [B<-hu>] [B<-he>] + +=for html +
+ +=head1 DESCRIPTION + +The B command displays information about the volume +containing each specified directory or file (its name, quota, and amount +of disk space used), along with an indicator of the percentage of space +used on the host partition. + +To display more information about the host partition, use the B command. + +To set volume quota, use the B or B command. + +=head1 CAUTIONS + +=include fragments/volsize-caution.pod + +=head1 OPTIONS + +=over 4 + +=item B<-path> >+ + +Names a file or directory that resides in the volume about which to +produce output. Partial pathnames are interpreted relative to the current +working directory, which is also the default value if this argument is +omitted. + +=item B<-human> + +Print space in a "human-readable" format. Instead of always printing space +in kilobytes, show disk space in kilobytes, megabytes, gigabytes, +terabytes, or petabytes, as appropriate. + +=item B<-help> + +Prints the online help for this command. All other valid options are +ignored. + +=back + +=head1 OUTPUT + +The output displays information about the volume that houses each +specified directory or file, in a tabular format that uses the following +headers: + +=over 4 + +=item Volume Name + +The name of the volume. + +=item Quota + +The volume's quota in kilobytes, or the string C to indicate an +unlimited quota. + +=item Used + +The amount of space used. If B<-human> is not specified, this value is in +kilobytes. + +=item % Used + +The percentage of the volume's quota that is used (the C statistic +divided by the C statistic, times 100). + +=item Partition + +The percentage of space used on the partition that houses the +volume. Although not directly related to how much of the user's quota is +used, it is reported because a full partition can cause writing of data +back to the volume to fail even when the volume has not reached its quota. + +=back + +=head1 EXAMPLES + +The following example shows the output for the volume C: + + % fs listquota -path /afs/example.com/usr/smith + Volume Name Quota Used % Used Partition + user.smith 15000 5071 34% 86% + +=head1 PRIVILEGE REQUIRED + +The issuer must have the C (read) permission on the ACL of the root +directory of the volume that houses the file or directory named by the +B<-path> argument, and C (list) permission on the ACL of each +directory that precedes it in the pathname. + +=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/fs_quota.pod b/doc/man-pages/pod1/fs_quota.pod deleted file mode 100644 index 30ceb57..0000000 --- a/doc/man-pages/pod1/fs_quota.pod +++ /dev/null @@ -1,92 +0,0 @@ -=head1 NAME - -fs_quota - Displays the quota used in the volume containing a directory or file - -=head1 SYNOPSIS - -=for html -
- -B S<<< [B<-path> >+] >>> [B<-help>] - -B S<<< [B<-p> >+] >>> [B<-h>] - -=for html -
- -=head1 DESCRIPTION - -The B command displays the percent of quota consumed in the -volume that contains each specified directory or file. - -To display more detailed information about the volume and the partition it -resides on, use the B and B commands. - -To set volume quota, use the B or B command. - -=head1 CAUTIONS - -Currently, the maximum size of a volume is 2 terabytes (2^31 bytes). - -=head1 OPTIONS - -=over 4 - -=item B<-path> > - -Names each file or directory for which to display the quota consumed in -its parent volume. Partial pathnames are interpreted relative to the -current working directory, which is also the default value if this -argument is omitted. - -=item B<-help> - -Prints the online help for this command. All other valid options are -ignored. - -=back - -=head1 OUTPUT - -The output reports the percent of volume quota used, in the following -format: - - % of quota used. - -=head1 EXAMPLES - -The following command lists the percent quota used of the volume housing -the current working directory: - - % fs quota - 17% of quota used. - -The following command lists the percent quota used of both the volume -housing the current working directory's parent directory and the volume -housing the directory F: - - % fs quota -path .. /afs/example.com/usr/smith - 43% of quota used. - 92% of quota used. - -=head1 PRIVILEGE REQUIRED - -The issuer must have the C (read) permission on the ACL of the root -directory of the volume that houses the file or directory named by the -B<-path> argument, and C (list) permission on the ACL of each -directory that precedes it in the pathname. - -=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/fs_quota.pod.in b/doc/man-pages/pod1/fs_quota.pod.in new file mode 100644 index 0000000..caa5db1 --- /dev/null +++ b/doc/man-pages/pod1/fs_quota.pod.in @@ -0,0 +1,92 @@ +=head1 NAME + +fs_quota - Displays the quota used in the volume containing a directory or file + +=head1 SYNOPSIS + +=for html +
+ +B S<<< [B<-path> >+] >>> [B<-help>] + +B S<<< [B<-p> >+] >>> [B<-h>] + +=for html +
+ +=head1 DESCRIPTION + +The B command displays the percent of quota consumed in the +volume that contains each specified directory or file. + +To display more detailed information about the volume and the partition it +resides on, use the B and B commands. + +To set volume quota, use the B or B command. + +=head1 CAUTIONS + +=include fragments/volsize-caution.pod + +=head1 OPTIONS + +=over 4 + +=item B<-path> > + +Names each file or directory for which to display the quota consumed in +its parent volume. Partial pathnames are interpreted relative to the +current working directory, which is also the default value if this +argument is omitted. + +=item B<-help> + +Prints the online help for this command. All other valid options are +ignored. + +=back + +=head1 OUTPUT + +The output reports the percent of volume quota used, in the following +format: + + % of quota used. + +=head1 EXAMPLES + +The following command lists the percent quota used of the volume housing +the current working directory: + + % fs quota + 17% of quota used. + +The following command lists the percent quota used of both the volume +housing the current working directory's parent directory and the volume +housing the directory F: + + % fs quota -path .. /afs/example.com/usr/smith + 43% of quota used. + 92% of quota used. + +=head1 PRIVILEGE REQUIRED + +The issuer must have the C (read) permission on the ACL of the root +directory of the volume that houses the file or directory named by the +B<-path> argument, and C (list) permission on the ACL of each +directory that precedes it in the pathname. + +=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/fs_setquota.pod b/doc/man-pages/pod1/fs_setquota.pod deleted file mode 100644 index 8eedeed..0000000 --- a/doc/man-pages/pod1/fs_setquota.pod +++ /dev/null @@ -1,99 +0,0 @@ -=head1 NAME - -fs_setquota - Sets the quota for the volume containing a file or directory - -=head1 SYNOPSIS - -=for html -
- -B S<<< [B<-path> >] >>> - S<<< B<-max> > >>> [B<-help>] - -B S<<< [B<-p> >] >>> S<<< B<-m> > >>> [B<-h>] - -B S<<< [B<-p> >] >>> S<<< B<-m> > >>> [B<-h>] - -=for html -
- -=head1 DESCRIPTION - -The B command sets the quota (maximum possible size) of the -read/write volume that contains the directory or file named by the -B<-path> argument. - -To set the quota on multiple volumes at the same time, use the B command. - -To display a volume's quota, use the B, B, or -B command. - -=head1 CAUTIONS - -Currently, the maximum size of a volume is 2 terabytes (2^31 bytes). - -=head1 OPTIONS - -=over 4 - -=item B<-path> > - -Names the directory or file for which to set the host volume's -quota. Partial pathnames are interpreted relative to the current working -directory, which is also the default value if this argument is omitted. - -Specify the read/write path to the file or directory, to avoid the failure -that results from attempting to change a read-only volume. By convention, -the read/write path is indicated by placing a period before the cell name -at the pathname's second level (for example, F). For -further discussion of the concept of read/write and read-only paths -through the filespace, see the B reference page. - -=item B<-max> > - -Sets the maximum amount of file server disk space the volume can occupy. -The quota value should be a positive integer followed by an optional -suffix: C for kibibytes (1024 bytes, the default), C for mebibytes -(1024 kibibytes), C for gibibytes (1024 mebibytes), and C for -tebibytes (1024 gibibytes). A value of C<0> sets an unlimited quota, but -the size of the disk partition that houses the volume places an absolute -limit on the volume's size. - -If the B<-path> argument is omitted (to set the quota of the volume -housing the current working directory), the B<-max> switch must be -included with this argument. - -=item B<-help> - -Prints the online help for this command. All other valid options are -ignored. - -=back - -=head1 EXAMPLES - -The following command imposes a maximum quota of 3000 kilobytes on the -volume that houses the F directory: - - % fs setquota -path /afs/example.com/usr/smith -max 3000 - -=head1 PRIVILEGE REQUIRED - -The issuer must belong to the system:administrators group. - -=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/fs_setquota.pod.in b/doc/man-pages/pod1/fs_setquota.pod.in new file mode 100644 index 0000000..416a52d --- /dev/null +++ b/doc/man-pages/pod1/fs_setquota.pod.in @@ -0,0 +1,99 @@ +=head1 NAME + +fs_setquota - Sets the quota for the volume containing a file or directory + +=head1 SYNOPSIS + +=for html +
+ +B S<<< [B<-path> >] >>> + S<<< B<-max> > >>> [B<-help>] + +B S<<< [B<-p> >] >>> S<<< B<-m> > >>> [B<-h>] + +B S<<< [B<-p> >] >>> S<<< B<-m> > >>> [B<-h>] + +=for html +
+ +=head1 DESCRIPTION + +The B command sets the quota (maximum possible size) of the +read/write volume that contains the directory or file named by the +B<-path> argument. + +To set the quota on multiple volumes at the same time, use the B command. + +To display a volume's quota, use the B, B, or +B command. + +=head1 CAUTIONS + +=include fragments/volsize-caution.pod + +=head1 OPTIONS + +=over 4 + +=item B<-path> > + +Names the directory or file for which to set the host volume's +quota. Partial pathnames are interpreted relative to the current working +directory, which is also the default value if this argument is omitted. + +Specify the read/write path to the file or directory, to avoid the failure +that results from attempting to change a read-only volume. By convention, +the read/write path is indicated by placing a period before the cell name +at the pathname's second level (for example, F). For +further discussion of the concept of read/write and read-only paths +through the filespace, see the B reference page. + +=item B<-max> > + +Sets the maximum amount of file server disk space the volume can occupy. +The quota value should be a positive integer followed by an optional +suffix: C for kibibytes (1024 bytes, the default), C for mebibytes +(1024 kibibytes), C for gibibytes (1024 mebibytes), and C for +tebibytes (1024 gibibytes). A value of C<0> sets an unlimited quota, but +the size of the disk partition that houses the volume places an absolute +limit on the volume's size. + +If the B<-path> argument is omitted (to set the quota of the volume +housing the current working directory), the B<-max> switch must be +included with this argument. + +=item B<-help> + +Prints the online help for this command. All other valid options are +ignored. + +=back + +=head1 EXAMPLES + +The following command imposes a maximum quota of 3000 kilobytes on the +volume that houses the F directory: + + % fs setquota -path /afs/example.com/usr/smith -max 3000 + +=head1 PRIVILEGE REQUIRED + +The issuer must belong to the system:administrators group. + +=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/fs_setvol.pod b/doc/man-pages/pod1/fs_setvol.pod deleted file mode 100644 index 414d5a5..0000000 --- a/doc/man-pages/pod1/fs_setvol.pod +++ /dev/null @@ -1,113 +0,0 @@ -=head1 NAME - -fs_setvol - Set quota and messages for a volume containing a file or directory - -=head1 SYNOPSIS - -=for html -
- -B S<<< [B<-path> >+] >>> - S<<< [B<-max> >] >>> - S<<< [B<-offlinemsg> >] >>> [B<-help>] - -B S<<< [B<-p> >+] >>> - S<<< [B<-ma> >] >>> - S<<< [B<-o> >] >>> [B<-h>] - -B S<<< [B<-p> >+] >>> - S<<< [B<-ma> >] >>> - S<<< [B<-o> >] >>> [B<-h>] - -=for html -
- -=head1 DESCRIPTION - -The B command sets the quota (maximum possible size) of the -read/write volume that contains each directory or file named by the -B<-path> argument. To associate a message with the volume which then -appears in the output of the B command, include the -B<-offlinemsg> argument. - -To display all of the settings made with this command, use the B command. The B command reports a fileset's quota, -and the B command the percent of quota used. - -To set quota on one volume at a time, use the B command. - -=head1 CAUTIONS - -Currently, the maximum size of a volume is 2 terabytes (2^31 bytes). - -=head1 OPTIONS - -=over 4 - -=item B<-path> >+ - -Names each file or directory for which to set the host volume's quota and -offline message. Partial pathnames are interpreted relative to the current -working directory, which is also the default value if this argument is -omitted. - -Specify the read/write path to the file or directory, to avoid the failure -that results from attempting to change a read-only volume. By convention, -the read/write path is indicated by placing a period before the cell name -at the pathname's second level (for example, F). For -further discussion of the concept of read/write and read-only paths -through the filespace, see the B reference page. - -=item B<-max> > - -Sets the maximum amount of file server disk space the volume can -occupy. Provide a positive integer to indicate the number of one-kilobyte -blocks (C<1024> is one megabyte). A value of C<0> sets an unlimited quota, -but the size of the disk partition that houses the volume places an -absolute limit on the volume's size. - -If the B<-path> argument is omitted (so that the command sets the quota of -the volume housing the current working directory), the B<-max> switch must -be provided. - -=item B<-offlinemsg> - -Associates a message with the volume which then appears in the output of -the B command. Its intended use is to explain why the volume -is currently offline. - -=item B<-help> - -Prints the online help for this command. All other valid options are -ignored. - -=back - -=head1 EXAMPLES - -The following command imposes a 6500 kilobyte quota on the volumes mounted -at the home directories F and -F: - - % cd /afs/example.com/usr - % fs setvol -path smith pat -max 6500B<> - -=head1 PRIVILEGE REQUIRED - -The issuer must belong to the system:administrators group. - -=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/fs_setvol.pod.in b/doc/man-pages/pod1/fs_setvol.pod.in new file mode 100644 index 0000000..fa48fe8 --- /dev/null +++ b/doc/man-pages/pod1/fs_setvol.pod.in @@ -0,0 +1,113 @@ +=head1 NAME + +fs_setvol - Set quota and messages for a volume containing a file or directory + +=head1 SYNOPSIS + +=for html +
+ +B S<<< [B<-path> >+] >>> + S<<< [B<-max> >] >>> + S<<< [B<-offlinemsg> >] >>> [B<-help>] + +B S<<< [B<-p> >+] >>> + S<<< [B<-ma> >] >>> + S<<< [B<-o> >] >>> [B<-h>] + +B S<<< [B<-p> >+] >>> + S<<< [B<-ma> >] >>> + S<<< [B<-o> >] >>> [B<-h>] + +=for html +
+ +=head1 DESCRIPTION + +The B command sets the quota (maximum possible size) of the +read/write volume that contains each directory or file named by the +B<-path> argument. To associate a message with the volume which then +appears in the output of the B command, include the +B<-offlinemsg> argument. + +To display all of the settings made with this command, use the B command. The B command reports a fileset's quota, +and the B command the percent of quota used. + +To set quota on one volume at a time, use the B command. + +=head1 CAUTIONS + +=include fragments/volsize-caution.pod + +=head1 OPTIONS + +=over 4 + +=item B<-path> >+ + +Names each file or directory for which to set the host volume's quota and +offline message. Partial pathnames are interpreted relative to the current +working directory, which is also the default value if this argument is +omitted. + +Specify the read/write path to the file or directory, to avoid the failure +that results from attempting to change a read-only volume. By convention, +the read/write path is indicated by placing a period before the cell name +at the pathname's second level (for example, F). For +further discussion of the concept of read/write and read-only paths +through the filespace, see the B reference page. + +=item B<-max> > + +Sets the maximum amount of file server disk space the volume can +occupy. Provide a positive integer to indicate the number of one-kilobyte +blocks (C<1024> is one megabyte). A value of C<0> sets an unlimited quota, +but the size of the disk partition that houses the volume places an +absolute limit on the volume's size. + +If the B<-path> argument is omitted (so that the command sets the quota of +the volume housing the current working directory), the B<-max> switch must +be provided. + +=item B<-offlinemsg> + +Associates a message with the volume which then appears in the output of +the B command. Its intended use is to explain why the volume +is currently offline. + +=item B<-help> + +Prints the online help for this command. All other valid options are +ignored. + +=back + +=head1 EXAMPLES + +The following command imposes a 6500 kilobyte quota on the volumes mounted +at the home directories F and +F: + + % cd /afs/example.com/usr + % fs setvol -path smith pat -max 6500B<> + +=head1 PRIVILEGE REQUIRED + +The issuer must belong to the system:administrators group. + +=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.pod b/doc/man-pages/pod1/vos.pod deleted file mode 100644 index 8b2198a..0000000 --- a/doc/man-pages/pod1/vos.pod +++ /dev/null @@ -1,326 +0,0 @@ -=head1 NAME - -vos - Introduction to the vos command suite - -=head1 DESCRIPTION - -The commands in the B command suite are the administrative interface -to the Volume Server and Volume Location (VL) Server. System -administrators use B commands to create, move, delete, replicate, -back up and examine volumes, among other operations. The VL Server -automatically records in the Volume Location Database (VLDB) changes in -volume status and location that result from B commands. - -The operations invoked by most B commands are idempotent, meaning -that if an operation is interrupted by a network, server machine, or -process outage, then a subsequent attempt at the same operation continues -from the interruption point, rather than starting over at the beginning of -the operation. Before executing a command, the Volume and VL Servers check -the current state of the volumes and VLDB records to be altered by the -command. If they are already in the desired end state (or a consistent -intermediate state), there is no need to repeat the internal steps that -brought them there. Idempotency does not apply if the command issuer -explicitly interrupts the operation with the Ctrl-C command or another -interrupt signal. In that case, the volume is left locked and the -administrator must use the L|vos_unlock(1)> command to -unlock it before proceeding. - -It is important that the VLDB accurately indicate the status of the -volumes on file server machines at all times. L and -L describe the information recorded in the VLDB and -volume headers, respectively. If a B command changes volume status, -it automatically records the change in the corresponding VLDB entry. The -most common cause of discrepancies between the VLDB and volume status on -file server machines is interrupted operations; to restore consistency, -use the L|vos_syncserv(1)> and -L|vos_syncvldb(1)> commands. - -There are several categories of commands in the vos command suite: - -=over 4 - -=item * - -Commands to create, move, and rename volumes: -L|vos_backup(1)>, -L|vos_backupsys(1)>, -L|vos_changeloc(1)>, -L|vos_create(1)>, -L|vos_move(1)>, -and L|vos_rename(1)>. - -=item * - -Commands to remove VLDB volume records or volumes or both: -L|vos_delentry(1)>, -L|vos_remove(1)>, -and L|vos_zap(1)>. - -=item * - -Commands to edit or display VLDB server entries: -L|vos_changeaddr(1)>, -L|vos_listaddrs(1)> -and L|vos_setaddrs(1)>. - -=item * - -Commands to create, size, and restore dump files: -L|vos_dump(1)>, -L|vos_restore(1)>, -and L|vos_size(1)>. - -=item * - -Commands to administer replicated volumes: -L|vos_addsite(1)>, -L|vos_release(1)>, -and L|vos_remsite(1)>. - -=item * - -Commands to display VLDB records, volume headers, or both: -L|vos_examine(1)>, -L|vos_listvldb(1)>, -and L|vos_listvol(1)>. - -=item * - -Commands to display information about partitions that house volumes: -L|vos_listpart(1)> -and L|vos_partinfo(1)>. - -=item * - -Commands to restore consistency between the VLDB and volume headers: -L|vos_syncserv(1)> -and L|vos_syncvldb(1)>. - -=item * - -Commands to lock and unlock VLDB entries: -L|vos_lock(1)>, -L|vos_unlock(1)>, -and L|vos_unlockvldb(1)>. - -=item * - -A command to report Volume Server status: -L|vos_status(1)>. - -=item * - -A command to end Volume Server transactions: -L|vos_endtrans(1)>. - -=item * - -A command to change volume fields: -L|vos_setfields(1)>. - -=item * - -Commands to obtain help: -L|vos_apropos(1)> -and L|vos_help(1)>. - -=back - -=head1 CAUTIONS - -Currently, the maximum size of a volume is 2 terabytes (2^31 bytes). - -=head1 OPTIONS - -The following arguments and flags are available on many commands in the -B suite. The reference page for each command also lists them, but -they are described here in greater detail. - -=over 4 - -=item B<-cell> > - -Names the cell in which to run the command. It is acceptable to abbreviate -the cell name to the shortest form that distinguishes it from the other -entries in the F file on the local machine. If -the B<-cell> argument is omitted, the command interpreter determines the -name of the local cell by reading the following in order: - -=over 4 - -=item * - -The value of the AFSCELL environment variable. - -=item * - -The local F file. - -=back - -Do not combine the B<-cell> and B<-localauth> options. A command on which -the B<-localauth> flag is included always runs in the local cell (as -defined in the server machine's local F file), -whereas a command on which the B<-cell> argument is included runs in the -specified foreign cell. - -=item B<-config> > - -The location of the directory to use to obtain configuration information, -including the CellServDB. This is primarily provided for testing purposes. - -=item B<-help> - -Prints a command's online help message on the standard output stream. Do -not combine this flag with any of the command's other options; when it is -provided, the command interpreter ignores all other options, and only -prints the help message. - -=item B<-localauth> - -Constructs a server ticket using the server encryption key with the -highest key version number in the local F file. The -B command interpreter presents the ticket, which never expires, to -the Volume Server and VL Server during mutual authentication. - -Use this flag only when issuing a command on a server machine; client -machines do not usually have a F file. The issuer -of a command that includes this flag must be logged on to the server -machine as the local superuser C. The flag is useful for commands -invoked by an unattended application program, such as a process controlled -by the UNIX B utility or by a cron entry in the machine's -F file. It is also useful if an administrator is -unable to authenticate to AFS but is logged in as the local superuser -B. - -Do not combine the B<-cell> and B<-localauth> options. A command on which -the B<-localauth> flag is included always runs in the local cell (as -defined in the server machine's local F file), -whereas a command on which the B<-cell> argument is included runs in the -specified foreign cell. Also, do not combine the B<-localauth> and -B<-noauth> flags. - -=item B<-noauth> - -Establishes an unauthenticated connection to the Volume Server and VL -Server, in which the servers treat the issuer as the unprivileged user -C. It is useful only when authorization checking is disabled on -the server machine (during the installation of a file server machine or -when the L|bos_setauth(8)> command has been used during -other unusual circumstances). In normal circumstances, the servers allow -only privileged users to issue commands that change the status of a volume -or VLDB record, and refuses to perform such an action even if the -B<-noauth> flag is provided. Do not combine the B<-noauth> and -B<-localauth> flags. - -=item B<-partition> > - -Identifies the AFS server partition on a file server machine that houses, -or is to house, the volumes of interest, or about which to list -information. The B command interpreter accepts any of the following -four name formats: - - /vicepa = vicepa = a = 0 - /vicepb = vicepb = b = 1 - -After /vicepz (for which the index is 25) comes - - /vicepaa = vicepaa = aa = 26 - /vicepab = vicepab = ab = 27 - -and so on through - - /vicepiv = vicepiv = iv = 255 - -The B<-frompartition> and B<-topartition> arguments to the -L|vos_move(1)> command also accept this notation. - -=item B<-server> > - -Identifies the file server machine that houses, or is to house, the -volumes or AFS server partitions of interest. Provide the machine's IP -address in dotted decimal format, its fully qualified host name (for -example, C), or the shortest abbreviated form of its host -name that distinguishes it from other machines. Successful use of an -abbreviated form depends on the availability of a name resolution service -(such as the Domain Name Service or a local host table) at the time the -command is issued. - -The B<-fromserver> and B<-toserver> arguments to the -L|vos_move(1)> command also accept these name formats. - -=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. The B<-noresolve> option is available in OpenAFS -versions 1.4.8 or later and 1.5.35 or later. - -=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. - -=back - -=head1 PRIVILEGE REQUIRED - -To issue most vos commands, the issuer must be listed in the -F file on each server machine that houses or is to -house an affected volume, and on each database server machine. The most -predictable performance results if all database server and file server -machines in the cell share a common F file. Alternatively, if -the B<-localauth> flag is included, the issuer must be logged on to a -server machine as the local superuser C. - -To issue a vos command that only displays information, no privilege is -required. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -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.pod.in b/doc/man-pages/pod1/vos.pod.in new file mode 100644 index 0000000..8ce7fd4 --- /dev/null +++ b/doc/man-pages/pod1/vos.pod.in @@ -0,0 +1,326 @@ +=head1 NAME + +vos - Introduction to the vos command suite + +=head1 DESCRIPTION + +The commands in the B command suite are the administrative interface +to the Volume Server and Volume Location (VL) Server. System +administrators use B commands to create, move, delete, replicate, +back up and examine volumes, among other operations. The VL Server +automatically records in the Volume Location Database (VLDB) changes in +volume status and location that result from B commands. + +The operations invoked by most B commands are idempotent, meaning +that if an operation is interrupted by a network, server machine, or +process outage, then a subsequent attempt at the same operation continues +from the interruption point, rather than starting over at the beginning of +the operation. Before executing a command, the Volume and VL Servers check +the current state of the volumes and VLDB records to be altered by the +command. If they are already in the desired end state (or a consistent +intermediate state), there is no need to repeat the internal steps that +brought them there. Idempotency does not apply if the command issuer +explicitly interrupts the operation with the Ctrl-C command or another +interrupt signal. In that case, the volume is left locked and the +administrator must use the L|vos_unlock(1)> command to +unlock it before proceeding. + +It is important that the VLDB accurately indicate the status of the +volumes on file server machines at all times. L and +L describe the information recorded in the VLDB and +volume headers, respectively. If a B command changes volume status, +it automatically records the change in the corresponding VLDB entry. The +most common cause of discrepancies between the VLDB and volume status on +file server machines is interrupted operations; to restore consistency, +use the L|vos_syncserv(1)> and +L|vos_syncvldb(1)> commands. + +There are several categories of commands in the vos command suite: + +=over 4 + +=item * + +Commands to create, move, and rename volumes: +L|vos_backup(1)>, +L|vos_backupsys(1)>, +L|vos_changeloc(1)>, +L|vos_create(1)>, +L|vos_move(1)>, +and L|vos_rename(1)>. + +=item * + +Commands to remove VLDB volume records or volumes or both: +L|vos_delentry(1)>, +L|vos_remove(1)>, +and L|vos_zap(1)>. + +=item * + +Commands to edit or display VLDB server entries: +L|vos_changeaddr(1)>, +L|vos_listaddrs(1)> +and L|vos_setaddrs(1)>. + +=item * + +Commands to create, size, and restore dump files: +L|vos_dump(1)>, +L|vos_restore(1)>, +and L|vos_size(1)>. + +=item * + +Commands to administer replicated volumes: +L|vos_addsite(1)>, +L|vos_release(1)>, +and L|vos_remsite(1)>. + +=item * + +Commands to display VLDB records, volume headers, or both: +L|vos_examine(1)>, +L|vos_listvldb(1)>, +and L|vos_listvol(1)>. + +=item * + +Commands to display information about partitions that house volumes: +L|vos_listpart(1)> +and L|vos_partinfo(1)>. + +=item * + +Commands to restore consistency between the VLDB and volume headers: +L|vos_syncserv(1)> +and L|vos_syncvldb(1)>. + +=item * + +Commands to lock and unlock VLDB entries: +L|vos_lock(1)>, +L|vos_unlock(1)>, +and L|vos_unlockvldb(1)>. + +=item * + +A command to report Volume Server status: +L|vos_status(1)>. + +=item * + +A command to end Volume Server transactions: +L|vos_endtrans(1)>. + +=item * + +A command to change volume fields: +L|vos_setfields(1)>. + +=item * + +Commands to obtain help: +L|vos_apropos(1)> +and L|vos_help(1)>. + +=back + +=head1 CAUTIONS + +=include fragments/volsize-caution.pod + +=head1 OPTIONS + +The following arguments and flags are available on many commands in the +B suite. The reference page for each command also lists them, but +they are described here in greater detail. + +=over 4 + +=item B<-cell> > + +Names the cell in which to run the command. It is acceptable to abbreviate +the cell name to the shortest form that distinguishes it from the other +entries in the F file on the local machine. If +the B<-cell> argument is omitted, the command interpreter determines the +name of the local cell by reading the following in order: + +=over 4 + +=item * + +The value of the AFSCELL environment variable. + +=item * + +The local F file. + +=back + +Do not combine the B<-cell> and B<-localauth> options. A command on which +the B<-localauth> flag is included always runs in the local cell (as +defined in the server machine's local F file), +whereas a command on which the B<-cell> argument is included runs in the +specified foreign cell. + +=item B<-config> > + +The location of the directory to use to obtain configuration information, +including the CellServDB. This is primarily provided for testing purposes. + +=item B<-help> + +Prints a command's online help message on the standard output stream. Do +not combine this flag with any of the command's other options; when it is +provided, the command interpreter ignores all other options, and only +prints the help message. + +=item B<-localauth> + +Constructs a server ticket using the server encryption key with the +highest key version number in the local F file. The +B command interpreter presents the ticket, which never expires, to +the Volume Server and VL Server during mutual authentication. + +Use this flag only when issuing a command on a server machine; client +machines do not usually have a F file. The issuer +of a command that includes this flag must be logged on to the server +machine as the local superuser C. The flag is useful for commands +invoked by an unattended application program, such as a process controlled +by the UNIX B utility or by a cron entry in the machine's +F file. It is also useful if an administrator is +unable to authenticate to AFS but is logged in as the local superuser +B. + +Do not combine the B<-cell> and B<-localauth> options. A command on which +the B<-localauth> flag is included always runs in the local cell (as +defined in the server machine's local F file), +whereas a command on which the B<-cell> argument is included runs in the +specified foreign cell. Also, do not combine the B<-localauth> and +B<-noauth> flags. + +=item B<-noauth> + +Establishes an unauthenticated connection to the Volume Server and VL +Server, in which the servers treat the issuer as the unprivileged user +C. It is useful only when authorization checking is disabled on +the server machine (during the installation of a file server machine or +when the L|bos_setauth(8)> command has been used during +other unusual circumstances). In normal circumstances, the servers allow +only privileged users to issue commands that change the status of a volume +or VLDB record, and refuses to perform such an action even if the +B<-noauth> flag is provided. Do not combine the B<-noauth> and +B<-localauth> flags. + +=item B<-partition> > + +Identifies the AFS server partition on a file server machine that houses, +or is to house, the volumes of interest, or about which to list +information. The B command interpreter accepts any of the following +four name formats: + + /vicepa = vicepa = a = 0 + /vicepb = vicepb = b = 1 + +After /vicepz (for which the index is 25) comes + + /vicepaa = vicepaa = aa = 26 + /vicepab = vicepab = ab = 27 + +and so on through + + /vicepiv = vicepiv = iv = 255 + +The B<-frompartition> and B<-topartition> arguments to the +L|vos_move(1)> command also accept this notation. + +=item B<-server> > + +Identifies the file server machine that houses, or is to house, the +volumes or AFS server partitions of interest. Provide the machine's IP +address in dotted decimal format, its fully qualified host name (for +example, C), or the shortest abbreviated form of its host +name that distinguishes it from other machines. Successful use of an +abbreviated form depends on the availability of a name resolution service +(such as the Domain Name Service or a local host table) at the time the +command is issued. + +The B<-fromserver> and B<-toserver> arguments to the +L|vos_move(1)> command also accept these name formats. + +=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. The B<-noresolve> option is available in OpenAFS +versions 1.4.8 or later and 1.5.35 or later. + +=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. + +=back + +=head1 PRIVILEGE REQUIRED + +To issue most vos commands, the issuer must be listed in the +F file on each server machine that houses or is to +house an affected volume, and on each database server machine. The most +predictable performance results if all database server and file server +machines in the cell share a common F file. Alternatively, if +the B<-localauth> flag is included, the issuer must be logged on to a +server machine as the local superuser C. + +To issue a vos command that only displays information, no privilege is +required. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +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_clone.pod b/doc/man-pages/pod1/vos_clone.pod deleted file mode 100644 index 13b6c9f..0000000 --- a/doc/man-pages/pod1/vos_clone.pod +++ /dev/null @@ -1,172 +0,0 @@ -=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<-noresolve>] [B<-help>] - -B S<<< [B<-i>] > >>> - S<<< [B<-s>] > >>> - S<<< [B<-p>] > >>> - S<<< [B<-ton> >] >>> - S<<< [B<-toi> >] >>> [B<-o>] [B<-r>] - S<<< [B<-c> >] >>> [B<-noa>] - [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] - -=for html -
- -=head1 DESCRIPTION - -The B command creates a copy-on-write copy of a volume on the -same partition and server as the parent volume. - -A clone is a copy of a volume that 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 volume, 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. 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 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. diff --git a/doc/man-pages/pod1/vos_clone.pod.in b/doc/man-pages/pod1/vos_clone.pod.in new file mode 100644 index 0000000..34fdcd6 --- /dev/null +++ b/doc/man-pages/pod1/vos_clone.pod.in @@ -0,0 +1,172 @@ +=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<-noresolve>] [B<-help>] + +B S<<< [B<-i>] > >>> + S<<< [B<-s>] > >>> + S<<< [B<-p>] > >>> + S<<< [B<-ton> >] >>> + S<<< [B<-toi> >] >>> [B<-o>] [B<-r>] + S<<< [B<-c> >] >>> [B<-noa>] + [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] + +=for html +
+ +=head1 DESCRIPTION + +The B command creates a copy-on-write copy of a volume on the +same partition and server as the parent volume. + +A clone is a copy of a volume that 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 volume, 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. + +=include fragments/volsize-caution.pod + +=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. 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 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. diff --git a/doc/man-pages/pod1/vos_copy.pod.in b/doc/man-pages/pod1/vos_copy.pod.in index 50cc0a0..dfbfaa6 100644 --- a/doc/man-pages/pod1/vos_copy.pod.in +++ b/doc/man-pages/pod1/vos_copy.pod.in @@ -38,7 +38,7 @@ the volume be stored locally by the client. =head1 CAUTIONS -Currently, the maximum size of a volume is 2 terabytes (2^31 bytes). +=include fragments/volsize-caution.pod =head1 OPTIONS diff --git a/doc/man-pages/pod1/vos_create.pod b/doc/man-pages/pod1/vos_create.pod deleted file mode 100644 index 4f1b3c4..0000000 --- a/doc/man-pages/pod1/vos_create.pod +++ /dev/null @@ -1,213 +0,0 @@ -=head1 NAME - -vos_create - Creates a read/write volume and associated VLDB entry - -=head1 SYNOPSIS - -=for html -
- -B S<<< B<-server> > >>> - S<<< B<-partition> > >>> - S<<< B<-name> > >>> - S<<< [B<-maxquota> >] >>> - S<<< [B<-cell> >] >>> - [B<-noauth>] [B<-localauth>] [B<-verbose>] - [B<-encrypt>] [B<-noresolve>] [B<-help>] - -B S<<< B<-s> > >>> S<<< B<-p> > >>> - S<<< B<-na> > >>> S<<< [B<-m> >] >>> - S<<< [B<-c> >] >>> [B<-noa>] [B<-l>] [B<-v>] - [B<-e>] [B<-nor>] [B<-h>] - -=for html -
- -=head1 DESCRIPTION - -The B command creates a read/write volume with the name -specified by the B<-name> argument at the site specified by the B<-server> -and B<-partition> arguments. In addition, the command allocates or sets -the following: - -=over 4 - -=item * - -Volume ID numbers for the read/write volume and its associated read-only -and backup volumes (this command does not actually create the latter two -types of volume). A volume ID number is an identification number -guaranteed to be unique within a cell. - -=item * - -An access control list (ACL) associated with the volume's root directory, -which takes the same name as volume's mount point when the volume is -mounted with the B command. An entry that grants all seven -permissions to the members of the system:administrators group is -automatically placed on the ACL. (In addition, the File Server by default -always implicitly grants the C (lookup) and C (administer) -permissions on every ACL to members of the system:administrators group, -even when the group does not appear on an ACL; use the B<-implicit> -argument to the B initialization command to alter the set of -rights on a server-by-server basis if desired.) - -=item * - -The volume's space quota, set to 5000 kilobyte blocks by default. Use the -B<-maxquota> argument to specify a different quota, or use the B command to change the volume's quota after mounting the volume -with the B command. - -=back - -The volume is empty when created. To access it via the Cache Manager, -mount it in the file space by using the B command. - -=head1 CAUTIONS - -Currently, the maximum size of a volume is 2 terabytes (2^31 bytes). - -=head1 OPTIONS - -=over 4 - -=item B<-server> > - -Identifies the file server machine on which to create the read/write -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 which to create the read/write volume, on the -file server machine specified 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<-name> > - -Specifies a name for the read/write volume. The maximum length is 22 -characters, which can include any alphanumeric or punctuation -character. By convention, periods separate the fields in a name. Do not -apply the C<.backup> or C<.readonly> extension to a read/write volume -name; they are reserved for the Volume Server to add to the read/write -name when creating those backup and read-only volumes respectively. - -=item B<-maxquota> > - -Specifies the maximum amount of disk space the volume can use. The size -should be a positive integer followed by an optional suffix: C for -kibibytes (1024 bytes, the default), C for mebibytes (1024 kibibytes), -C for gibibytes (1024 mebibytes), and C for tebibytes (1024 -gibibytes). The value C<0> (zero) grants an unlimited quota, but the size -of the disk partition that houses the volume places an absolute limit on -its size. If this argument is omitted, the default value is C<5000K>. - -=item B<-id> > - -Specifies the volume ID for the read/write volume. If this options is not -specified, or the given volume ID is 0, a volume ID will be allocated for -the volume automatically. The volume IDs allocated should be fine for -almost all cases, so you should almost never need to specify this option. - -=item B<-roid> > - -Specifies the volume ID for the readonly volume corresponding to the -read/write volume that is being created. The readonly volume will not be -created; this merely specifies what volume ID the readonly volume will use -when it is created. If a volume ID of 0 is specified here, no readonly -volume ID will be assigned to the created volume immediately. A readonly -volume ID can still be assigned later when B is run; if a -volume does not have a readonly volume ID associated with it by the time -B is run, a volume ID will be allocated for it. - -If this option is not specified, the default readonly volume ID is one -number higher than the read-write volume ID, whether or not that ID was -manually specified. - -As with the B<-id> option, the default allocated volume IDs should be -sufficient 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<-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 OUTPUT - -The Volume Server produces the following message to confirm that it -created the volume: - - Volume created on partition of - -=head1 EXAMPLES - -The following command creates the read/write volume C on the -F partition of the file server machine C. - - % vos create -server fs4.example.com -partition /vicepf -name user.pat - Volume user.pat created on partition /vicepf of fs4.example.com - -=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 - -=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_create.pod.in b/doc/man-pages/pod1/vos_create.pod.in new file mode 100644 index 0000000..b99ae4a --- /dev/null +++ b/doc/man-pages/pod1/vos_create.pod.in @@ -0,0 +1,213 @@ +=head1 NAME + +vos_create - Creates a read/write volume and associated VLDB entry + +=head1 SYNOPSIS + +=for html +
+ +B S<<< B<-server> > >>> + S<<< B<-partition> > >>> + S<<< B<-name> > >>> + S<<< [B<-maxquota> >] >>> + S<<< [B<-cell> >] >>> + [B<-noauth>] [B<-localauth>] [B<-verbose>] + [B<-encrypt>] [B<-noresolve>] [B<-help>] + +B S<<< B<-s> > >>> S<<< B<-p> > >>> + S<<< B<-na> > >>> S<<< [B<-m> >] >>> + S<<< [B<-c> >] >>> [B<-noa>] [B<-l>] [B<-v>] + [B<-e>] [B<-nor>] [B<-h>] + +=for html +
+ +=head1 DESCRIPTION + +The B command creates a read/write volume with the name +specified by the B<-name> argument at the site specified by the B<-server> +and B<-partition> arguments. In addition, the command allocates or sets +the following: + +=over 4 + +=item * + +Volume ID numbers for the read/write volume and its associated read-only +and backup volumes (this command does not actually create the latter two +types of volume). A volume ID number is an identification number +guaranteed to be unique within a cell. + +=item * + +An access control list (ACL) associated with the volume's root directory, +which takes the same name as volume's mount point when the volume is +mounted with the B command. An entry that grants all seven +permissions to the members of the system:administrators group is +automatically placed on the ACL. (In addition, the File Server by default +always implicitly grants the C (lookup) and C (administer) +permissions on every ACL to members of the system:administrators group, +even when the group does not appear on an ACL; use the B<-implicit> +argument to the B initialization command to alter the set of +rights on a server-by-server basis if desired.) + +=item * + +The volume's space quota, set to 5000 kilobyte blocks by default. Use the +B<-maxquota> argument to specify a different quota, or use the B command to change the volume's quota after mounting the volume +with the B command. + +=back + +The volume is empty when created. To access it via the Cache Manager, +mount it in the file space by using the B command. + +=head1 CAUTIONS + +=include fragments/volsize-caution.pod + +=head1 OPTIONS + +=over 4 + +=item B<-server> > + +Identifies the file server machine on which to create the read/write +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 which to create the read/write volume, on the +file server machine specified 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<-name> > + +Specifies a name for the read/write volume. The maximum length is 22 +characters, which can include any alphanumeric or punctuation +character. By convention, periods separate the fields in a name. Do not +apply the C<.backup> or C<.readonly> extension to a read/write volume +name; they are reserved for the Volume Server to add to the read/write +name when creating those backup and read-only volumes respectively. + +=item B<-maxquota> > + +Specifies the maximum amount of disk space the volume can use. The size +should be a positive integer followed by an optional suffix: C for +kibibytes (1024 bytes, the default), C for mebibytes (1024 kibibytes), +C for gibibytes (1024 mebibytes), and C for tebibytes (1024 +gibibytes). The value C<0> (zero) grants an unlimited quota, but the size +of the disk partition that houses the volume places an absolute limit on +its size. If this argument is omitted, the default value is C<5000K>. + +=item B<-id> > + +Specifies the volume ID for the read/write volume. If this options is not +specified, or the given volume ID is 0, a volume ID will be allocated for +the volume automatically. The volume IDs allocated should be fine for +almost all cases, so you should almost never need to specify this option. + +=item B<-roid> > + +Specifies the volume ID for the readonly volume corresponding to the +read/write volume that is being created. The readonly volume will not be +created; this merely specifies what volume ID the readonly volume will use +when it is created. If a volume ID of 0 is specified here, no readonly +volume ID will be assigned to the created volume immediately. A readonly +volume ID can still be assigned later when B is run; if a +volume does not have a readonly volume ID associated with it by the time +B is run, a volume ID will be allocated for it. + +If this option is not specified, the default readonly volume ID is one +number higher than the read-write volume ID, whether or not that ID was +manually specified. + +As with the B<-id> option, the default allocated volume IDs should be +sufficient 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<-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 OUTPUT + +The Volume Server produces the following message to confirm that it +created the volume: + + Volume created on partition of + +=head1 EXAMPLES + +The following command creates the read/write volume C on the +F partition of the file server machine C. + + % vos create -server fs4.example.com -partition /vicepf -name user.pat + Volume user.pat created on partition /vicepf of fs4.example.com + +=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 + +=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_examine.pod b/doc/man-pages/pod1/vos_examine.pod deleted file mode 100644 index d8d85ea..0000000 --- a/doc/man-pages/pod1/vos_examine.pod +++ /dev/null @@ -1,438 +0,0 @@ -=head1 NAME - -vos_examine - Shows volume header and VLDB entry information for a volume - -=head1 SYNOPSIS - -=for html -
- -B S<<< B<-id> > >>> [B<-extended>] - [B<-format>] S<<< [B<-cell> >] >>> - [B<-noauth>] [B<-localauth>] [B<-verbose>] - [B<-encrypt>] [B<-noresolve>] [B<-help>] - -B S<<< B<-i> > >>> [B<-ex>] [B<-f>] - S<<< [B<-c> >] >>> - [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] - -B S<<< B<-id> > >>> [B<-extended>] - [B<-format>] S<<< [B<-cell> >] >>> - [B<-noauth>] [B<-localauth>] [B<-verbose>] - [B<-encrypt>] [B<-noresolve>] [B<-help>] - -B S<<< B<-i> > >>> [B<-ex>] [B<-f>] - S<<< [B<-c> >] >>> - [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] - -=for html -
- -=head1 DESCRIPTION - -The B command formats and displays information from the -Volume Location Database (VLDB) entry and the volume header of the volume -specified by the B<-id> argument. - -To display the volume header only, use the B command. To -display information from the VLDB only, use the B command. - -=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 the volume, -which can be read/write, read-only, or backup. - -=item B<-extended> - -Displays statistics about read and write operations on files and -directories in the volume. - -=item B<-format> - -Shows information in a format suitable for machine parsing. - -=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 OUTPUT - -The first seven lines of the output show information from the volume -header and the remaining lines come from the VLDB. Each item in the -following list corresponds to a line of output derived from the volume -header. - -=over 4 - -=item * - -Basic information about the specified volume (displayed on a single -line): - -=over 4 - -=item * - -Name - -=item * - -Volume ID number - -=item * - -Type (the flag is C for read/write, C for read-only, C for -backup) - -=item * - -Size in kilobytes (C<1024> equals a megabyte) - -=item * - -Number of files in the volume, if the B<-extended> flag is provided - -=item * - -Status on the file server machine, which is one of the following: - -=over 4 - -=item On-line - -The volume is completely accessible to Cache Managers. - -=item Off-line - -The volume is not accessible to Cache Managers, but does not seem to be -corrupted. This status appears while a volume is being dumped, for -example. - -=item Off-line**needs salvage** - -The volume is not accessible to Cache Managers, because it seems to be -corrupted. Use the B or B command to repair the -corruption. - -=back - -=back - -=item * - -The file server machine and partition that house the volume, as determined -by the command interpreter as the command runs, rather than derived from -the VLDB or the volume header. - -=item * - -The volume ID numbers associated with the various versions of the volume: -read/write (C), read-only (C), backup (C), and -ReleaseClone (C). One of them matches the volume ID number that -appears on the first line of the volume's output. If the value in the -C, C, or C field is C<0> (zero), there is no volume -of that type. If there is currently no ReleaseClone, the C field -does not appear at all. - -=item * - -The maximum space quota allotted to the read/write copy of the volume, -expressed in kilobyte blocks in the C field. - -=item * - -The date and time the volume was created, in the C field. If the -volume has been restored with the B, B, or B command, this is the restore time. For a -read-only volume, this is the last release time. - -=item * - -The date and time this copy of this volume was created, in the C -field. This is the time when the volume was created on this server and -partition. For read-only volumes, it is not updated by a release (unlike -the Creation date). The copy date is not stored in volume dumps. - -=item * - -The date and time when the contents of the volume last changed, in the -C field. For read-only and backup volumes, it matches the -timestamp in the C field. - -=item * - -The number of times the volume has been accessed for a fetch or store -operation since the later of the two following times: - -=over 4 - -=item * - -12:00 a.m. on the day the command is issued - -=item * - -The last time the volume changed location - -=back - -=back - -When the B<-extended> flag is included, two tables appear next: - -=over 4 - -=item * - -The table labeled C contains information on the -number of reads (fetches) and writes (stores) made on the specified -volume. - -=item * - -The table labeled C contains information on -writes made to files and directories in the specified volume. - -=back - -If the following message appears instead of the previously listed -information, it indicates that a volume is not accessible to Cache -Managers or the B command interpreter, for example because a clone is -being created. - - **** Volume is busy **** - -If the following message appears instead of the previously listed -information, it indicates that the File Server is unable to attach the -volume, perhaps because it is seriously corrupted. The F and -F log files in the F directory on the file -server machine possibly provide additional information; use the B command to display them. - - **** Could not attach volume **** - -Following a blank line, information from the VLDB entry appears. Each -item in this list corresponds to a separate line in the output: - -=over 4 - -=item * - -The base (read/write) volume name. The read-only and backup versions have -the same name with a C<.readonly> and C<.backup> extension, respectively. - -=item * - -The volume ID numbers allocated to the versions of the volume that -actually exist, in fields labeled C for the read/write, C -for the read-only, C for the backup, and C for the -ReleaseClone. (If a field does not appear, the corresponding version of -the volume does not exist.) The appearance of the C field normally -indicates that a release operation did not complete successfully; the -C and C flags often also appear on one or more -of the site definition lines described just following. - -=item * - -The number of sites that house a read/write or read-only copy of the -volume, following the string C<< number of sites -> >>. - -=item * - -A line for each site that houses a read/write or read-only copy of the -volume, specifying the file server machine, partition, and type of volume -(C for read/write or C for read-only). If a backup version exists, -it is understood to share the read/write site. Several flags can appear -with a site definition: - -=over 4 - -=item Not released - -Indicates that the vos release command has not been issued since the B command was used to define the read-only site. - -=item Old release - -Indicates that a vos release command did not complete successfully, -leaving the previous, obsolete version of the volume at this site. - -=item New release - -Indicates that a vos release command did not complete successfully, but -that this site did receive the correct new version of the volume. - -=back - -=item * - -If the VLDB entry is locked, the string C, as -well as (in OpenAFS 1.5.75 and later) one or more of the following strings: - -=over 4 - -=item Volume is locked for a move operation - -Indicates that the volume was locked due to a B or a B command. - -=item Volume is locked for a release operation - -Indicates that the volume was locked due to a B command. - -=item Volume is locked for a backup operation - -Indicates that the volume was locked due to a B command. - -=item Volume is locked for a delete/misc operation - -Indicates that the volume was locked due to a B, B, B, B, B, B, B, or B command. - -=item Volume is locked for a dump/restore operation - -Indicates that the volume was locked due to a B or B -command. - -=back - -=back - -For further discussion of the C and C flags, see -L. - -=head1 EXAMPLES - -The following example shows output for the Example Corporation volume called -C with two read-only replication sites (this volume is mounted at the -F directory). For the sake of illustration, the output -shows the volume as locked. - - % vos examine usr - usr 536870981 RW 3459 K On-line - fs2.example.com /vicepb - RWrite 5360870981 ROnly 536870982 Backup 536870983 - MaxQuota 40000 K - Creation Mon Jun 12 15:22:06 1989 - Copy Mon Jun 12 15:22:06 1989 - Last Update Fri Jun 16 09:34:35 1989 - 5719 accesses in the past day (i.e., vnode references) - RWrite: 5360870981 ROnly: 536870982 Backup: 536870983 - number of sites -> 3 - server fs1.example.com partition /vicepa RO Site - server fs3.example.com partition /vicepa RO Site - server fs2.example.com partition /vicepb RW Site - Volume is currently LOCKED - -The following example shows the output for the volume C using -the B<-extended> flag. The volume has no read-only replication sites. - - % vos examine -id user.terry -extended - user.terry 354287190 RW 2302 K used 119 files On-line - fs4.example.com /vicepc - RWrite 354287190 ROnly 0 Backup 354287192 - MaxQuota 5000 K - Creation Wed Nov 25 17:38:57 1992 - Copy Wed Nov 25 17:38:57 1992 - Last Update Tue Dec 15 10:46:20 1992 - 598 accesses in the past day (i.e., vnode references) - Raw Read/Write Stats - |-------------------------------------------| - | Same Network | Diff Network | - |----------|----------|----------|----------| - | Total | Auth | Total | Auth | - |----------|----------|----------|----------| - Reads | 55 | 55 | 38 | 38 | - Writes | 95 | 95 | 0 | 0 | - |-------------------------------------------| - Writes Affecting Authorship - |-------------------------------------------| - | File Authorship | Directory Authorship| - |----------|----------|----------|----------| - | Same | Diff | Same | Diff | - |----------|----------|----------|----------| - 0-60 sec | 38 | 0 | 21 | 1 | - 1-10 min | 2 | 0 | 7 | 0 | - 10min-1hr | 0 | 0 | 1 | 0 | - 1hr-1day | 1 | 0 | 5 | 1 | - 1day-1wk | 0 | 0 | 0 | 0 | - > 1wk | 0 | 0 | 0 | 0 | - |-------------------------------------------| - RWrite: 354287190 Backup: 354287192 - number of sites -> 1 - server fs4.example.com partition /vicepc RW Site - -=head1 PRIVILEGE REQUIRED - -None - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -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_examine.pod.in b/doc/man-pages/pod1/vos_examine.pod.in new file mode 100644 index 0000000..0e08fb7 --- /dev/null +++ b/doc/man-pages/pod1/vos_examine.pod.in @@ -0,0 +1,438 @@ +=head1 NAME + +vos_examine - Shows volume header and VLDB entry information for a volume + +=head1 SYNOPSIS + +=for html +
+ +B S<<< B<-id> > >>> [B<-extended>] + [B<-format>] S<<< [B<-cell> >] >>> + [B<-noauth>] [B<-localauth>] [B<-verbose>] + [B<-encrypt>] [B<-noresolve>] [B<-help>] + +B S<<< B<-i> > >>> [B<-ex>] [B<-f>] + S<<< [B<-c> >] >>> + [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] + +B S<<< B<-id> > >>> [B<-extended>] + [B<-format>] S<<< [B<-cell> >] >>> + [B<-noauth>] [B<-localauth>] [B<-verbose>] + [B<-encrypt>] [B<-noresolve>] [B<-help>] + +B S<<< B<-i> > >>> [B<-ex>] [B<-f>] + S<<< [B<-c> >] >>> + [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] + +=for html +
+ +=head1 DESCRIPTION + +The B command formats and displays information from the +Volume Location Database (VLDB) entry and the volume header of the volume +specified by the B<-id> argument. + +To display the volume header only, use the B command. To +display information from the VLDB only, use the B command. + +=head1 CAUTIONS + +=include fragments/volsize-caution.pod + +=head1 OPTIONS + +=over 4 + +=item B<-id> > + +Specifies either the complete name or volume ID number of the volume, +which can be read/write, read-only, or backup. + +=item B<-extended> + +Displays statistics about read and write operations on files and +directories in the volume. + +=item B<-format> + +Shows information in a format suitable for machine parsing. + +=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 OUTPUT + +The first seven lines of the output show information from the volume +header and the remaining lines come from the VLDB. Each item in the +following list corresponds to a line of output derived from the volume +header. + +=over 4 + +=item * + +Basic information about the specified volume (displayed on a single +line): + +=over 4 + +=item * + +Name + +=item * + +Volume ID number + +=item * + +Type (the flag is C for read/write, C for read-only, C for +backup) + +=item * + +Size in kilobytes (C<1024> equals a megabyte) + +=item * + +Number of files in the volume, if the B<-extended> flag is provided + +=item * + +Status on the file server machine, which is one of the following: + +=over 4 + +=item On-line + +The volume is completely accessible to Cache Managers. + +=item Off-line + +The volume is not accessible to Cache Managers, but does not seem to be +corrupted. This status appears while a volume is being dumped, for +example. + +=item Off-line**needs salvage** + +The volume is not accessible to Cache Managers, because it seems to be +corrupted. Use the B or B command to repair the +corruption. + +=back + +=back + +=item * + +The file server machine and partition that house the volume, as determined +by the command interpreter as the command runs, rather than derived from +the VLDB or the volume header. + +=item * + +The volume ID numbers associated with the various versions of the volume: +read/write (C), read-only (C), backup (C), and +ReleaseClone (C). One of them matches the volume ID number that +appears on the first line of the volume's output. If the value in the +C, C, or C field is C<0> (zero), there is no volume +of that type. If there is currently no ReleaseClone, the C field +does not appear at all. + +=item * + +The maximum space quota allotted to the read/write copy of the volume, +expressed in kilobyte blocks in the C field. + +=item * + +The date and time the volume was created, in the C field. If the +volume has been restored with the B, B, or B command, this is the restore time. For a +read-only volume, this is the last release time. + +=item * + +The date and time this copy of this volume was created, in the C +field. This is the time when the volume was created on this server and +partition. For read-only volumes, it is not updated by a release (unlike +the Creation date). The copy date is not stored in volume dumps. + +=item * + +The date and time when the contents of the volume last changed, in the +C field. For read-only and backup volumes, it matches the +timestamp in the C field. + +=item * + +The number of times the volume has been accessed for a fetch or store +operation since the later of the two following times: + +=over 4 + +=item * + +12:00 a.m. on the day the command is issued + +=item * + +The last time the volume changed location + +=back + +=back + +When the B<-extended> flag is included, two tables appear next: + +=over 4 + +=item * + +The table labeled C contains information on the +number of reads (fetches) and writes (stores) made on the specified +volume. + +=item * + +The table labeled C contains information on +writes made to files and directories in the specified volume. + +=back + +If the following message appears instead of the previously listed +information, it indicates that a volume is not accessible to Cache +Managers or the B command interpreter, for example because a clone is +being created. + + **** Volume is busy **** + +If the following message appears instead of the previously listed +information, it indicates that the File Server is unable to attach the +volume, perhaps because it is seriously corrupted. The F and +F log files in the F directory on the file +server machine possibly provide additional information; use the B command to display them. + + **** Could not attach volume **** + +Following a blank line, information from the VLDB entry appears. Each +item in this list corresponds to a separate line in the output: + +=over 4 + +=item * + +The base (read/write) volume name. The read-only and backup versions have +the same name with a C<.readonly> and C<.backup> extension, respectively. + +=item * + +The volume ID numbers allocated to the versions of the volume that +actually exist, in fields labeled C for the read/write, C +for the read-only, C for the backup, and C for the +ReleaseClone. (If a field does not appear, the corresponding version of +the volume does not exist.) The appearance of the C field normally +indicates that a release operation did not complete successfully; the +C and C flags often also appear on one or more +of the site definition lines described just following. + +=item * + +The number of sites that house a read/write or read-only copy of the +volume, following the string C<< number of sites -> >>. + +=item * + +A line for each site that houses a read/write or read-only copy of the +volume, specifying the file server machine, partition, and type of volume +(C for read/write or C for read-only). If a backup version exists, +it is understood to share the read/write site. Several flags can appear +with a site definition: + +=over 4 + +=item Not released + +Indicates that the vos release command has not been issued since the B command was used to define the read-only site. + +=item Old release + +Indicates that a vos release command did not complete successfully, +leaving the previous, obsolete version of the volume at this site. + +=item New release + +Indicates that a vos release command did not complete successfully, but +that this site did receive the correct new version of the volume. + +=back + +=item * + +If the VLDB entry is locked, the string C, as +well as (in OpenAFS 1.5.75 and later) one or more of the following strings: + +=over 4 + +=item Volume is locked for a move operation + +Indicates that the volume was locked due to a B or a B command. + +=item Volume is locked for a release operation + +Indicates that the volume was locked due to a B command. + +=item Volume is locked for a backup operation + +Indicates that the volume was locked due to a B command. + +=item Volume is locked for a delete/misc operation + +Indicates that the volume was locked due to a B, B, B, B, B, B, B, or B command. + +=item Volume is locked for a dump/restore operation + +Indicates that the volume was locked due to a B or B +command. + +=back + +=back + +For further discussion of the C and C flags, see +L. + +=head1 EXAMPLES + +The following example shows output for the Example Corporation volume called +C with two read-only replication sites (this volume is mounted at the +F directory). For the sake of illustration, the output +shows the volume as locked. + + % vos examine usr + usr 536870981 RW 3459 K On-line + fs2.example.com /vicepb + RWrite 5360870981 ROnly 536870982 Backup 536870983 + MaxQuota 40000 K + Creation Mon Jun 12 15:22:06 1989 + Copy Mon Jun 12 15:22:06 1989 + Last Update Fri Jun 16 09:34:35 1989 + 5719 accesses in the past day (i.e., vnode references) + RWrite: 5360870981 ROnly: 536870982 Backup: 536870983 + number of sites -> 3 + server fs1.example.com partition /vicepa RO Site + server fs3.example.com partition /vicepa RO Site + server fs2.example.com partition /vicepb RW Site + Volume is currently LOCKED + +The following example shows the output for the volume C using +the B<-extended> flag. The volume has no read-only replication sites. + + % vos examine -id user.terry -extended + user.terry 354287190 RW 2302 K used 119 files On-line + fs4.example.com /vicepc + RWrite 354287190 ROnly 0 Backup 354287192 + MaxQuota 5000 K + Creation Wed Nov 25 17:38:57 1992 + Copy Wed Nov 25 17:38:57 1992 + Last Update Tue Dec 15 10:46:20 1992 + 598 accesses in the past day (i.e., vnode references) + Raw Read/Write Stats + |-------------------------------------------| + | Same Network | Diff Network | + |----------|----------|----------|----------| + | Total | Auth | Total | Auth | + |----------|----------|----------|----------| + Reads | 55 | 55 | 38 | 38 | + Writes | 95 | 95 | 0 | 0 | + |-------------------------------------------| + Writes Affecting Authorship + |-------------------------------------------| + | File Authorship | Directory Authorship| + |----------|----------|----------|----------| + | Same | Diff | Same | Diff | + |----------|----------|----------|----------| + 0-60 sec | 38 | 0 | 21 | 1 | + 1-10 min | 2 | 0 | 7 | 0 | + 10min-1hr | 0 | 0 | 1 | 0 | + 1hr-1day | 1 | 0 | 5 | 1 | + 1day-1wk | 0 | 0 | 0 | 0 | + > 1wk | 0 | 0 | 0 | 0 | + |-------------------------------------------| + RWrite: 354287190 Backup: 354287192 + number of sites -> 1 + server fs4.example.com partition /vicepc RW Site + +=head1 PRIVILEGE REQUIRED + +None + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +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_move.pod b/doc/man-pages/pod1/vos_move.pod deleted file mode 100644 index 7678073..0000000 --- a/doc/man-pages/pod1/vos_move.pod +++ /dev/null @@ -1,212 +0,0 @@ -=head1 NAME - -vos_move - Moves a read/write volume to another site - -=head1 SYNOPSIS - -=for html -
- -B S<<< B<-id> > >>> - S<<< B<-fromserver> > >>> - S<<< B<-frompartition> > >>> - S<<< B<-toserver> > >>> - S<<< B<-topartition> > >>> - [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<-tos> > >>> - S<<< B<-top> > >>> - [B<-li>] S<<< [B<-c> >] >>> [B<-noa>] - [B<-lo>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] - -=for html -
- -=head1 DESCRIPTION - -The B command moves the indicated read/write volume from its -current site (specified with the B<-fromserver> and B<-frompartition> -arguments) to the destination site (specified with the B<-toserver> and -B<-topartition> arguments). This command automatically removes the backup -copy from the current site, if it exists. To create a new backup volume at -the destination site, use the B command. - -This command works on read/write volumes only. To move a read-only volume, -use the B and B commands to define a new -read-only site and release the volume contents to it, and then use the -B command to remove the previous read-only volume's definition -from the Volume Location Database (VLDB) and data from the partition. To -move a backup volume, use this command to move its read/write source and -then issue the B command. - -Before executing this command, the B command interpreter initiates a -check that the destination partition contains enough space to house the -volume being moved. If there is not enough space, the move operation is -not attempted and the following message appears: - - vos: no space on target partition to move volume - -=head1 CAUTIONS - -Unless there is a compelling reason, do not interrupt a B -command in progress. Interrupting a move can result in one or more of the -following inconsistent states: - -=over 4 - -=item * - -There are two versions of the volume, one at the source site and one at -the destination site. (If this happens, retain the version identified by -the VLDB and use the B command to remove the other version.) - -=item * - -The backup version of the volume is stranded at the old site. (If this -happens, use the B command to remove it.) - -=item * - -The volume is off-line. (If this happens, run the B command -to bring it back on line.) - -=back - -If the Ctrl-C interrupt signal is pressed while a vos move operation is -executing, the following message warns of the consequences and requests -confirmation of the kill signal: - - SIGINT handler: vos move operation in progress - WARNING: may leave AFS storage and metadata in indeterminate state - enter second control-c to exit - -To confirm termination of the operation, press Ctrl-C a second time; press -any other key to continue the operation. - -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 volume currently -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 volume currently 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 move 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 move the volume. Provide the full -partition name (for, example, B) or one of the abbreviated forms -described in L. - -=item B<-live> - -Avoids making a temporary copy of the volume during the move. This is -useful if the partition is full, but the administrator needs to move -volumes to a another partition or server to free up disk space. The -caveat is that the volume is locked during the entire operation -instead of the short time that is needed to make the temporary clone. - -=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 moves the volume C from the F -partition on the file server machine C to the F -partition on the file server machine C. - - % vos move -id user.smith -fromserver fs3.example.com -frompartition b \ - -toserver fs7.example.com -topartition g - -=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, -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_move.pod.in b/doc/man-pages/pod1/vos_move.pod.in new file mode 100644 index 0000000..28b3cd9 --- /dev/null +++ b/doc/man-pages/pod1/vos_move.pod.in @@ -0,0 +1,212 @@ +=head1 NAME + +vos_move - Moves a read/write volume to another site + +=head1 SYNOPSIS + +=for html +
+ +B S<<< B<-id> > >>> + S<<< B<-fromserver> > >>> + S<<< B<-frompartition> > >>> + S<<< B<-toserver> > >>> + S<<< B<-topartition> > >>> + [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<-tos> > >>> + S<<< B<-top> > >>> + [B<-li>] S<<< [B<-c> >] >>> [B<-noa>] + [B<-lo>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] + +=for html +
+ +=head1 DESCRIPTION + +The B command moves the indicated read/write volume from its +current site (specified with the B<-fromserver> and B<-frompartition> +arguments) to the destination site (specified with the B<-toserver> and +B<-topartition> arguments). This command automatically removes the backup +copy from the current site, if it exists. To create a new backup volume at +the destination site, use the B command. + +This command works on read/write volumes only. To move a read-only volume, +use the B and B commands to define a new +read-only site and release the volume contents to it, and then use the +B command to remove the previous read-only volume's definition +from the Volume Location Database (VLDB) and data from the partition. To +move a backup volume, use this command to move its read/write source and +then issue the B command. + +Before executing this command, the B command interpreter initiates a +check that the destination partition contains enough space to house the +volume being moved. If there is not enough space, the move operation is +not attempted and the following message appears: + + vos: no space on target partition to move volume + +=head1 CAUTIONS + +Unless there is a compelling reason, do not interrupt a B +command in progress. Interrupting a move can result in one or more of the +following inconsistent states: + +=over 4 + +=item * + +There are two versions of the volume, one at the source site and one at +the destination site. (If this happens, retain the version identified by +the VLDB and use the B command to remove the other version.) + +=item * + +The backup version of the volume is stranded at the old site. (If this +happens, use the B command to remove it.) + +=item * + +The volume is off-line. (If this happens, run the B command +to bring it back on line.) + +=back + +If the Ctrl-C interrupt signal is pressed while a vos move operation is +executing, the following message warns of the consequences and requests +confirmation of the kill signal: + + SIGINT handler: vos move operation in progress + WARNING: may leave AFS storage and metadata in indeterminate state + enter second control-c to exit + +To confirm termination of the operation, press Ctrl-C a second time; press +any other key to continue the operation. + +=include fragments/volsize-caution.pod + +=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 volume currently +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 volume currently 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 move 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 move the volume. Provide the full +partition name (for, example, B) or one of the abbreviated forms +described in L. + +=item B<-live> + +Avoids making a temporary copy of the volume during the move. This is +useful if the partition is full, but the administrator needs to move +volumes to a another partition or server to free up disk space. The +caveat is that the volume is locked during the entire operation +instead of the short time that is needed to make the temporary clone. + +=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 moves the volume C from the F +partition on the file server machine C to the F +partition on the file server machine C. + + % vos move -id user.smith -fromserver fs3.example.com -frompartition b \ + -toserver fs7.example.com -topartition g + +=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, +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_partinfo.pod b/doc/man-pages/pod1/vos_partinfo.pod deleted file mode 100644 index 3af5b1a..0000000 --- a/doc/man-pages/pod1/vos_partinfo.pod +++ /dev/null @@ -1,145 +0,0 @@ -=head1 NAME - -vos_partinfo - Reports the available and total space on a partition - -=head1 SYNOPSIS - -=for html -
- -B S<<< B<-server> > >>> - S<<< [B<-partition> >] >>> [B<-summary>] - S<<< [B<-cell> >] >>> - [B<-noauth>] [B<-localauth>] - [B<-verbose>] [B<-encrypt>] [B<-noresolve>] [B<-help>] - -B S<<< B<-se> > >>> - S<<< [B<-p> >] >>> [B<-su>] - S<<< [B<-c> >] >>> - [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] - -=for html -
- -=head1 DESCRIPTION - -The vos partinfo command reports the amount of space available and total -size on either all of the partitions on the indicated file server machine -(if the B<-partition> argument is omitted) or the specified partition on -that file server machine. The Volume Location Database (VLDB) is not -consulted. - -=head1 CAUTIONS - -Currently, the maximum size of a volume is 2 terabytes (2^31 bytes). - -=head1 OPTIONS - -=over 4 - -=item B<-server> > - -Identifies the file server machine for which to display partition -information. 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 which partition on the file server machine specified by the -B<-server> argument for which to display information. 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<-summary> - -Prints storage summary. - -=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 CAUTIONS - -The partition-related statistics in this command's output do not always -agree with the corresponding values in the output of the standard UNIX -B command. The statistics reported by this command can be up to five -minutes old, because the Cache Manager polls the File Server for partition -information at that frequency. Also, on some operating systems, the B -command's report of partition size includes reserved space not included in -this command's calculation, and so is likely to be about 10% larger. - -=head1 OUTPUT - -The output reports the amount of space available and total space for each -specified partition. - -=head1 EXAMPLES - -The following command displays all partitions on the file server machine -C. - - % vos partinfo fs2.example.com - Free space on partition /vicepa: 27301 K blocks out of total 549197 - Free space on partition /vicepb: 13646 K blocks out of total 69194 - Free space on partition /vicepc: 31798 K blocks out of total 320315 - Free space on partition /vicepd: 33302 K blocks out of total 494954 - -=head1 PRIVILEGE REQUIRED - -None - -=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_partinfo.pod.in b/doc/man-pages/pod1/vos_partinfo.pod.in new file mode 100644 index 0000000..0991ce2 --- /dev/null +++ b/doc/man-pages/pod1/vos_partinfo.pod.in @@ -0,0 +1,145 @@ +=head1 NAME + +vos_partinfo - Reports the available and total space on a partition + +=head1 SYNOPSIS + +=for html +
+ +B S<<< B<-server> > >>> + S<<< [B<-partition> >] >>> [B<-summary>] + S<<< [B<-cell> >] >>> + [B<-noauth>] [B<-localauth>] + [B<-verbose>] [B<-encrypt>] [B<-noresolve>] [B<-help>] + +B S<<< B<-se> > >>> + S<<< [B<-p> >] >>> [B<-su>] + S<<< [B<-c> >] >>> + [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] + +=for html +
+ +=head1 DESCRIPTION + +The vos partinfo command reports the amount of space available and total +size on either all of the partitions on the indicated file server machine +(if the B<-partition> argument is omitted) or the specified partition on +that file server machine. The Volume Location Database (VLDB) is not +consulted. + +=head1 CAUTIONS + +=include fragments/volsize-caution.pod + +=head1 OPTIONS + +=over 4 + +=item B<-server> > + +Identifies the file server machine for which to display partition +information. 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 which partition on the file server machine specified by the +B<-server> argument for which to display information. 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<-summary> + +Prints storage summary. + +=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 CAUTIONS + +The partition-related statistics in this command's output do not always +agree with the corresponding values in the output of the standard UNIX +B command. The statistics reported by this command can be up to five +minutes old, because the Cache Manager polls the File Server for partition +information at that frequency. Also, on some operating systems, the B +command's report of partition size includes reserved space not included in +this command's calculation, and so is likely to be about 10% larger. + +=head1 OUTPUT + +The output reports the amount of space available and total space for each +specified partition. + +=head1 EXAMPLES + +The following command displays all partitions on the file server machine +C. + + % vos partinfo fs2.example.com + Free space on partition /vicepa: 27301 K blocks out of total 549197 + Free space on partition /vicepb: 13646 K blocks out of total 69194 + Free space on partition /vicepc: 31798 K blocks out of total 320315 + Free space on partition /vicepd: 33302 K blocks out of total 494954 + +=head1 PRIVILEGE REQUIRED + +None + +=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_shadow.pod b/doc/man-pages/pod1/vos_shadow.pod deleted file mode 100644 index 4987ba2..0000000 --- a/doc/man-pages/pod1/vos_shadow.pod +++ /dev/null @@ -1,195 +0,0 @@ -=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<-noresolve>] [B<-help>] - -B S<<< [B<-id>] > >>> - S<<< [B<-froms>] > >>> - S<<< [B<-fromp>] > >>> - S<<< [B<-tos>] > >>> - S<<< [B<-top>] > >>> - S<<< [B<-ton> >] >>> - S<<< [B<-toi> >] >>> - [B<-o>] [B<-r>] [B<-l>] [B<-in>] - S<<< [B<-c> >] >>> - [B<-noa>] [B<-lo>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] - -=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. 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 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. diff --git a/doc/man-pages/pod1/vos_shadow.pod.in b/doc/man-pages/pod1/vos_shadow.pod.in new file mode 100644 index 0000000..3852151 --- /dev/null +++ b/doc/man-pages/pod1/vos_shadow.pod.in @@ -0,0 +1,195 @@ +=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<-noresolve>] [B<-help>] + +B S<<< [B<-id>] > >>> + S<<< [B<-froms>] > >>> + S<<< [B<-fromp>] > >>> + S<<< [B<-tos>] > >>> + S<<< [B<-top>] > >>> + S<<< [B<-ton> >] >>> + S<<< [B<-toi> >] >>> + [B<-o>] [B<-r>] [B<-l>] [B<-in>] + S<<< [B<-c> >] >>> + [B<-noa>] [B<-lo>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>] + +=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. + +=include fragments/volsize-caution.pod + +=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. 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 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. -- 1.9.4