doc/man-pages/pod1/vos_listvldb.pod

   1 =head1 NAME
   2
   3 vos listvldb - Displays a volume's VLDB entry
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<vos listvldb> S<<< [B<-name> <I<volume name or ID>>] >>>
  11     S<<< [B<-server> <I<machine name>>] >>> S<<< [B<-partition> <I<partition name>>] >>>
  12     [B<-locked>] [B<-quiet>] [B<-nosort>] S<<< [B<-cell> <I<cell name>>] >>>
  13     [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
  14
  15 B<vos listvl> S<<< [B<-na> <I<volume name or ID>>] >>> S<<< [B<-s> <I<machine name>>] >>>
  16     S<<< [B<-p> <I<partition name>>] >>> [B<-lock>] [B<-q>] [B<-nos>]
  17     S<<< [B<-c> <I<cell name>>] >>> [B<-noa>] [B<-loca>] [B<-v>] [B<-h>]
  18
  19 =for html
  20 </div>
  21
  22 =head1 DESCRIPTION
  23
  24 The B<vos listvldb> command formats and displays information from the
  25 Volume Location Database (VLDB) entry for each volume specified.  The
  26 output depends on the combination of options supplied on the command
  27 line. Combine options as indicated to display the desired type of VLDB
  28 entries:
  29
  30 =over 4
  31
  32 =item *
  33
  34 Every entry in the VLDB: provide no options.
  35
  36 =item *
  37
  38 Every VLDB entry that mentions a certain file server machine as the site
  39 for a volume: specify the machine's name as the B<-server> argument.
  40
  41 =item *
  42
  43 Every VLDB entry that mentions a certain partition on any file server
  44 machine as the site for a volume: specify the partition name as the
  45 B<-partition> argument.
  46
  47 =item *
  48
  49 Every VLDB entry that mentions a certain partition on a certain file
  50 server machine as the site for a volume: combine the B<-server> and
  51 B<-partition> arguments.
  52
  53 =item *
  54
  55 A single VLDB entry: specify a volume name or ID number with the B<-name>
  56 argument.
  57
  58 =item *
  59
  60 The VLDB entry only for the volumes with locked VLDB entries found at a
  61 certain site: combine the B<-locked> flag with any of arguments that
  62 define sites.
  63
  64 =back
  65
  66 =head1 OPTIONS
  67
  68 =over 4
  69
  70 =item B<-name> <I<volume name or ID>>
  71
  72 Specifies either the complete name or volume ID number of a volume of any
  73 of the three types.
  74
  75 =item B<-server> <I<server name>>
  76
  77 Identifies the file server machine listed as a site in each VLDB entry to
  78 display. Provide the machine's IP address or its host name (either fully
  79 qualified or using an unambiguous abbreviation). For details, see
  80 L<vos(1)>.
  81
  82 This argument can be combined with the B<-partition> argument, the
  83 B<-locked> flag, or both.
  84
  85 =item B<-partition> <I<partition name>>
  86
  87 Identifies the partition (on the file server machine specified by the
  88 B<-server> argument) listed as a site in each VLDB entry to
  89 display. Provide the partition's complete name with preceding slash (for
  90 example, C</vicepa>) or use one of the three acceptable abbreviated
  91 forms. For details, see L<vos(1)>.
  92
  93 This argument can be combined with the B<-server> argument, the B<-locked>
  94 flag, or both.
  95
  96 =item B<-locked>
  97
  98 Displays only locked VLDB entries. This flag can be combined with the
  99 B<-server> argument, the B<-partition> argument, or both.
 100
 101 =item B<-quiet>
 102
 103 Suppresses the lines that summarize the number of volumes listed and their
 104 status, which otherwise appear at the beginning and end of the output when
 105 the output includes more than one volume.
 106
 107 =item B<-nosort>
 108
 109 Suppresses the default sorting of volume entries alphabetically by volume
 110 name.
 111
 112 =item B<-cell> <I<cell name>>
 113
 114 Names the cell in which to run the command. Do not combine this argument
 115 with the B<-localauth> flag. For more details, see L<vos(1)>.
 116
 117 =item B<-noauth>
 118
 119 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
 120 combine this flag with the B<-localauth> flag. For more details, see
 121 L<vos(1)>.
 122
 123 =item B<-localauth>
 124
 125 Constructs a server ticket using a key from the local
 126 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
 127 to the Volume Server and Volume Location Server during mutual
 128 authentication. Do not combine this flag with the B<-cell> argument or
 129 B<-noauth> flag. For more details, see L<vos(1)>.
 130
 131 =item B<-verbose>
 132
 133 Produces on the standard output stream a detailed trace of the command's
 134 execution. If this argument is omitted, only warnings and error messages
 135 appear.
 136
 137 =item B<-help>
 138
 139 Prints the online help for this command. All other valid options are
 140 ignored.
 141
 142 =back
 143
 144 =head1 OUTPUT
 145
 146 If the output includes more than one VLDB entry, by default the first line
 147 reports which file server machine, partition, or both, houses the
 148 volumes. The final line of output reports the total number of entries
 149 displayed. Including the B<-quiet> flag suppresses these lines.
 150
 151 By default, volumes are sorted alphabetically by volume name.  Including
 152 the B<-nosort> flag skips the sorting step, which can speed up the
 153 production of output if there are a large number of entries.
 154
 155 The VLDB entry for each volume includes the following information:
 156
 157 =over 4
 158
 159 =item *
 160
 161 The base (read/write) volume name. The read-only and backup versions have
 162 the same name with a C<.readonly> and C<.backup> extension, respectively.
 163
 164 =item *
 165
 166 The volume ID numbers allocated to the versions of the volume that
 167 actually exist, in fields labeled C<RWrite> for the read/write, C<ROnly>
 168 for the read-only, C<Backup> for the backup, and C<RClone> for the
 169 ReleaseClone. (If a field does not appear, the corresponding version of
 170 the volume does not exist.) The appearance of the C<RClone> field normally
 171 indicates that a release operation did not complete successfully; the
 172 C<Old release> and C<New release> flags often also appear on one or more
 173 of the site definition lines described just following.
 174
 175 =item *
 176
 177 The number of sites that house a read/write or read-only copy of the
 178 volume, following the string C<< number of sites -> >>.
 179
 180 =item *
 181
 182 A line for each site that houses a read/write or read-only copy of the
 183 volume, specifying the file server machine, partition, and type of volume
 184 (C<RW> for read/write or C<RO> for read-only). If a backup version exists,
 185 it is understood to share the read/write site.  Several flags can appear
 186 with a site definition:
 187
 188 =over 4
 189
 190 =item Not released
 191
 192 Indicates that the vos release command has not been issued since the B<vos
 193 addsite> command was used to define the read-only site.
 194
 195 =item Old release
 196
 197 Indicates that a vos release command did not complete successfully,
 198 leaving the previous, obsolete version of the volume at this site.
 199
 200 =item New release
 201
 202 Indicates that a vos release command did not complete successfully, but
 203 that this site did receive the correct new version of the volume.
 204
 205 =back
 206
 207 =item *
 208
 209 If the VLDB entry is locked, the string C<Volume is currently LOCKED>.
 210
 211 =back
 212
 213 For further discussion of the C<New release> and C<Old release> flags, see
 214 L<vos_release(1)>.
 215
 216 =head1 EXAMPLES
 217
 218 The following command displays VLDB information for the ABC Corporation
 219 volume called C<usr>, which has two read-only replication sites:
 220
 221    % vos listvldb -name usr
 222    usr
 223     RWrite: 5360870981   ROnly: 536870982   Backup: 536870983
 224     number of sites -> 3
 225        server fs1.abc.com partition /vicepa RO Site
 226        server fs3.abc.com partition /vicepa RO Site
 227        server fs2.abc.com partition /vicepb RW Site
 228
 229 The following example shows entries for two of the volumes that reside on
 230 the file server machine C<fs4.abc.com>. The first VLDB entry is currently
 231 locked. There are 508 entries that mention the machine as a volume site.
 232
 233    % vos listvldb -server fs4.abc.com
 234    VLDB entries for server fs4.abc.com
 235        .       .           .        .
 236        .       .           .        .
 237    user.smith
 238     RWrite: 278541326   ROnly: 278541327   Backup: 278542328
 239     number of sites -> 1
 240       server fs4.abc.com partition /vicepg RW Site
 241     Volume is currently LOCKED
 242       user.terry
 243     RWrite 354287190   ROnly 354287191   Backup 354287192
 244     number of sites -> 1
 245       server fs4.abc.com partition /vicepc RW Site
 246       .       .           .        .
 247       .       .           .        .
 248    Total entries: 508
 249
 250 =head1 PRIVILEGE REQUIRED
 251
 252 None
 253
 254 =head1 SEE ALSO
 255
 256 L<vos(1)>,
 257 L<vos_examine(1)>,
 258 L<vos_listvol(1)>,
 259 L<vos_lock(1)>,
 260 L<vos_unlock(1)>,
 261 L<vos_unlockvldb(1)>
 262
 263 =head1 COPYRIGHT
 264
 265 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 266
 267 This documentation is covered by the IBM Public License Version 1.0.  It was
 268 converted from HTML to POD by software written by Chas Williams and Russ
 269 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.