doc/man-pages/pod1/vos_listvol.pod

   1 =head1 NAME
   2
   3 vos listvol - Displays information from a volume header
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<vos listvol> S<<< B<-server> <I<machine name>> >>>
  11     S<<< [B<-partition> <I<partition name>>] >>> [B<-fast>] [B<-long>] [B<-quiet>]
  12     [B<-extended>] S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>]
  13     [B<-verbose>] [B<-help>]
  14
  15 B<vos listvo> S<<< B<-s> <I<machine name>> >>> S<<< [B<-p> <I<partition name>>] >>> [B<-f>]
  16     [-lon] [B<-q>] [B<-e>] S<<< [B<-c> <I<cell name>>] >>> [B<-n>] [B<-loc>]
  17     [B<-v>] [B<-h>]
  18
  19 =for html
  20 </div>
  21
  22 =head1 DESCRIPTION
  23
  24 The B<vos listvol> command formats and displays the following information
  25 from the volume header of each specified volume: volume name, volume ID,
  26 volume type, size, and status at the server. The actual information
  27 displayed depends on the combination of arguments supplied when the
  28 command is issued. To display volume header information for various
  29 numbers of volumes, combine the command's arguments as indicated:
  30
  31 =over 4
  32
  33 =item *
  34
  35 For every volume on a file server machine, specify the machine's name with
  36 the B<-server> argument.
  37
  38 =item *
  39
  40 For every volume at a particular site, combine the B<-server> argument
  41 with the B<-partition> argument.
  42
  43 =back
  44
  45 To display the Volume Location Database (VLDB) entry for one or more
  46 volumes, use the B<vos listvldb> command. To display both the VLDB entry
  47 and the volume header for a single volume, use the B<vos examine> command.
  48
  49 =head1 OPTIONS
  50
  51 =over 4
  52
  53 =item B<-server> <I<server name>>
  54
  55 Identifies the file server machine that houses volumes for which to
  56 display the header. Provide the machine's IP address or its host name
  57 (either fully qualified or using an unambiguous abbreviation). For
  58 details, see L<vos(1)>.
  59
  60 This argument can be combined with the B<-partition> argument, as well as
  61 the B<-fast>, B<-long>, or B<-extended> flag.
  62
  63 =item B<-partition> <I<partition name>>
  64
  65 Identifies the partition (on the file server machine specified by the
  66 B<-server> argument) that houses volumes for which to display the
  67 header. Provide the partition's complete name with preceding slash (for
  68 example, F</vicepa>) or use one of the three acceptable abbreviated
  69 forms. For details, see L<vos(1)>.
  70
  71 =item B<-fast>
  72
  73 Displays only the volume ID numbers of volumes stored at the site
  74 specified by the B<-server>, and optionally B<-partition>, argument. Do
  75 not combine this flag with the B<-extended> flag.
  76
  77 =item B<-long>
  78
  79 Displays more detailed information about each volume stored at the site
  80 specified by the B<-server>, and optionally B<-partition>, argument. The
  81 information includes the volume IDs of all three volume types associated
  82 with the volume, and the read/write volume's quota, creation date and
  83 update date.
  84
  85 =item B<-quiet>
  86
  87 Suppresses the lines that summarize the number of volumes listed and their
  88 status, which otherwise appear at the beginning and end of the output when
  89 the output includes more than one volume.
  90
  91 =item B<-extended>
  92
  93 Displays extensive statistics about access patterns for each volume stored
  94 at the site specified by the B<-server>, and optionally B<-partition>,
  95 argument. The statistics include the number of reads and writes to files
  96 in the volume, and how recently files and directories have been updated by
  97 their owners or other users. Do not combine this flag with the B<-fast>
  98 flag.
  99
 100 =item B<-cell> <I<cell name>>
 101
 102 Names the cell in which to run the command. Do not combine this argument
 103 with the B<-localauth> flag. For more details, see L<vos(1)>.
 104
 105 =item B<-noauth>
 106
 107 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
 108 combine this flag with the B<-localauth> flag. For more details, see
 109 L<vos(1)>.
 110
 111 =item B<-localauth>
 112
 113 Constructs a server ticket using a key from the local
 114 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
 115 to the Volume Server and Volume Location Server during mutual
 116 authentication. Do not combine this flag with the B<-cell> argument or
 117 B<-noauth> flag. For more details, see L<vos(1)>.
 118
 119 =item B<-verbose>
 120
 121 Produces on the standard output stream a detailed trace of the command's
 122 execution. If this argument is omitted, only warnings and error messages
 123 appear.
 124
 125 =item B<-help>
 126
 127 Prints the online help for this command. All other valid options are
 128 ignored.
 129
 130 =back
 131
 132 =head1 OUTPUT
 133
 134 The output is ordered alphabetically by volume name and by default
 135 provides the following information on a single line for each volume:
 136
 137 =over 4
 138
 139 =item *
 140
 141 Name
 142
 143 =item *
 144
 145 Volume ID number
 146
 147 =item *
 148
 149 Type (the flag is C<RW> for read/write, C<RO> for read-only, C<BK> for
 150 backup)
 151
 152 =item *
 153
 154 Size in kilobytes (C<1024> equals a megabyte)
 155
 156 =item *
 157
 158 Number of files in the volume, if the B<-extended> flag is provided
 159
 160 =item *
 161
 162 Status on the file server machine, which is one of the following:
 163
 164 =over 4
 165
 166 =item On-line
 167
 168 The volume is completely accessible to Cache Managers.
 169
 170 =item Off-line
 171
 172 The volume is not accessible to Cache Managers, but does not seem to be
 173 corrupted. This status appears while a volume is being dumped, for
 174 example.
 175
 176 =item Off-line**needs salvage**
 177
 178 The volume is not accessible to Cache Managers, because it seems to be
 179 corrupted. Use the B<bos salvage> or B<salvager> command to repair the
 180 corruption.
 181
 182 =back
 183
 184 =back
 185
 186 If the following message appears instead of the previously listed
 187 information, it indicates that a volume is not accessible to Cache
 188 Managers or the B<vos> command interpreter, for example because a clone is
 189 being created.
 190
 191    **** Volume <volume_ID> is busy ****
 192
 193 If the following message appears instead of the previously listed
 194 information, it indicates that the File Server is unable to attach the
 195 volume, perhaps because it is seriously corrupted. The F<FileLog> and
 196 F<VolserLog> log files in the F</usr/afs/logs> directory on the file
 197 server machine possibly provide additional information; use the B<bos
 198 getlog> command to display them.
 199
 200    **** Could not attach volume <volume_ID> ****
 201
 202 The information about individual volumes is bracketed by summary
 203 lines. The first line of output specifies the number of volumes in the
 204 listing. The last line of output summarizes the number of volumes that are
 205 online, offline, and busy. These lines do not appear if the B<-quiet> flag
 206 is used.
 207
 208 If the B<-fast> flag is added, the output displays only the volume ID
 209 number of each volume, arranged in increasing numerical order. The final
 210 line (which summarizes the number of online, offline, and busy volumes) is
 211 omitted.
 212
 213 If the B<-long> flag is included, the output for each volume includes all
 214 of the information in the default listing plus the following. Each item in
 215 this list corresponds to a separate line of output:
 216
 217 =over 4
 218
 219 =item *
 220
 221 The file server machine and partition that house the volume, as determined
 222 by the command interpreter as the command runs, rather than derived from the
 223 VLDB or the volume header.
 224
 225 =item *
 226
 227 The volume ID numbers associated with the various versions of the volume:
 228 read/write (C<RWrite>), read-only (C<ROnly>), backup (C<Backup>), and
 229 ReleaseClone (C<RClone>). One of them matches the volume ID number that
 230 appears on the first line of the volume's output. If the value in the
 231 C<RWrite>, C<ROnly>, or C<Backup> field is C<0> (zero), there is no volume
 232 of that type. If there is currently no ReleaseClone, the C<RClone> field
 233 does not appear at all.
 234
 235 =item *
 236
 237 The maximum space quota allotted to the read/write copy of the volume,
 238 expressed in kilobyte blocks in the C<MaxQuota> field.
 239
 240 =item *
 241
 242 The date and time the volume was created, in the C<Creation> field. If the
 243 volume has been restored with the B<backup diskrestore>, B<backup
 244 volrestore>, or B<vos restore> command, this is the restore time.
 245
 246 =item *
 247
 248 The date and time when the contents of the volume last changed, in the
 249 C<Last Update> field. For read-only and backup volumes, it matches the
 250 timestamp in the C<Creation> field.
 251
 252 =item *
 253
 254 The number of times the volume has been accessed for a fetch or store
 255 operation since the later of the two following times:
 256
 257 =over 4
 258
 259 =item *
 260
 261 12:00 a.m. on the day the command is issued
 262
 263 =item *
 264
 265 The last time the volume changed location
 266
 267 =back
 268
 269 =back
 270
 271 If the B<-extended> flag is included, the output for each volume includes
 272 all of the information reported with the B<-long> flag, plus two tables of
 273 statistics:
 274
 275 =over 4
 276
 277 =item *
 278
 279 The table labeled C<Raw Read/Write Stats> table summarizes the number of
 280 times the volume has been accessed for reading or writing.
 281
 282 =item *
 283
 284 The table labeled C<Writes Affecting Authorship> table contains
 285 information on writes made to files and directories in the specified
 286 volume.
 287
 288 =back
 289
 290 =head1 EXAMPLES
 291
 292 The following example shows the output for the F</vicepb> partition on the
 293 file server machine C<fs2.abc.com> when no flags are provided:
 294
 295    % vos listvol -server fs2.abc.com -partition b
 296    Total number of volumes on server fs2.abc.com partition /vicepb : 66
 297    sys                  1969534847 RW       1582 K On-line
 298    sys.backup           1969535105 BK       1582 K On-line
 299          .                   .     .         .   .    .
 300          .                   .     .         .   .    .
 301    user.pat             1969534536 RW      17518 K On-line
 302    user.pat.backup      1969534538 BK      17537 K On-line
 303    Total volumes onLine 66 ; Total volumes offLine 0 ;  Total busy 0
 304
 305 The following example shows the output when the B<-fast> flag is added:
 306
 307    % vos listvol -server fs2.abc.com -partition b -fast
 308    Total number of volumes on server fs2.abc.com partition /vicepb : 66
 309     1969516782
 310     1969516784
 311         .
 312         .
 313     1969535796
 314
 315 The following example shows two volumes from the output that appears when
 316 the B<-long> flag is added:
 317
 318    % vos listvol -server fs2.abc.com -partition b -long
 319    Total number of volumes on server fs2.abc.com partition /vicepb: 66
 320          .                   .      .         .   .    .
 321          .                   .      .         .   .    .
 322    user.pat             1969534536 RW      17518 K On-line
 323         fs2.abc.com /vicepb
 324         RWrite 1969534536 ROnly 0        Backup 1969534538
 325         MaxQuota      20000 K
 326         Creation    Mon Jun 12 09:02:25 1989
 327         Last Update Thu May 20 17:39:34 1999
 328         1573 accesses in the past day (i.e., vnode references)
 329    user.pat.backup      1969534538 BK      17537 K On-line
 330         fs2.abc.com /vicepb
 331         RWrite 1969534536 ROnly 0        Backup 1969534538
 332         MaxQuota      20000 K
 333         Creation    Tue Jun 13 04:37:59 1989
 334         Last Update Wed May 19 06:37:59 1999
 335         0 accesses in the past day (i.e., vnode references)
 336           .                   .      .         .   .    .
 337           .                   .      .         .   .    .
 338    Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
 339
 340 =head1 PRIVILEGE REQUIRED
 341
 342 None
 343
 344 =head1 SEE ALSO
 345
 346 L<backup_diskrestore(8)>,
 347 L<backup_volrestore(8)>,
 348 L<bos_getlog(8)>,
 349 L<bos_salvage(8)>,
 350 L<salvager(8)>,
 351 L<vos(1)>,
 352 L<vos_examine(1)>,
 353 L<vos_listvldb(1)>,
 354 L<vos_restore(1)>
 355
 356 =head1 COPYRIGHT
 357
 358 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 359
 360 This documentation is covered by the IBM Public License Version 1.0.  It was
 361 converted from HTML to POD by software written by Chas Williams and Russ
 362 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.