doc/man-pages/pod1/vos_listvol.pod.in

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