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