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