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