VOS_LISTVLDB(1)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💖 vos_listvldb — one sec bestie, we're reading the VLDB 💖

okay so this is a page from the AFS Command Reference family — it's vos_listvldb(1), the little icon that shows you what's inside a volume's Volume Location Database entry. and yes, lowercase name, uppercase DRAMA. let's go ✨

🌸 NAME 🌸

vos_listvldb — literally just displays a volume's VLDB entry. that's the whole job. she's an open book, no cap 📖

🎀 SYNOPSIS 🎀

vos listvldb [-name <volume name or ID>]
    [-server <machine name>]
    [-partition <partition name>]
    [-locked] [-quiet] [-nosort]
    [-cell <cell name>] [-noauth] [-localauth]
    [-verbose] [-encrypt] [-noresolve]
    [-config <config directory>]
    [-help]

vos listvl [-na <volume name or ID>]
    [-s <machine name>]
    [-p <partition name>]
    [-lock] [-q] [-nos] [-c <cell name>]
    [-noa] [-loca] [-v] [-e] [-nor]
    [-co <config directory>]
    [-h]

(the second form is the same girl, just with her abbreviations on — listvl is listvldb's lowercase alter ego, iykyk 💅)

💅 DESCRIPTION 💅

vos listvldb formats and displays info from the Volume Location Database (VLDB) entry for each volume you point at. what you actually see depends entirely on which options you stack together on the command line. so mix and match like this if you want a specific flavor of VLDB entries:

  • Every single entry in the VLDB: give it no options at all. zero. nothing. just vibes 🌈
  • Every VLDB entry that names a certain file server machine as a volume's site: pass that machine's name as the -server argument.
  • Every VLDB entry that names a certain partition on any file server machine as a volume's site: pass the partition name as the -partition argument.
  • Every VLDB entry that names a certain partition on a certain file server machine as a volume's site: combine -server and -partition together 🫶 they're a duo.
  • A single VLDB entry: hand over a volume name or ID number with the -name argument.
  • Just the VLDB entries for volumes with locked VLDB entries at a certain site: combine the -locked flag with any of the arguments that define sites.

✨ OPTIONS ✨

  • -name <volume name or ID> — gives either the complete name or the volume ID number of a volume of any of the three types. all three. she doesn't play favorites 👑
  • -server <server name> — names the file server machine listed as a site in each VLDB entry you're displaying. hand over the machine's IP address or its host name (fully qualified, or an unambiguous abbreviation — she'll figure it out). for the deets, see vos(1).

this argument can be combined with the -partition argument, the -locked flag, or both 🎀

  • -partition <partition name> — names the partition (on the file server machine you gave with -server) that's listed as a site in each VLDB entry you're displaying. give the partition's complete name with the preceding slash (like "/vicepa") or use one of the three acceptable abbreviated forms. for details, see vos(1).

this argument can be combined with the -server argument, the -locked flag, or both 🌸

  • -locked — shows only locked VLDB entries. this flag can be combined with the -server argument, the -partition argument, or both 🔒
  • -quiet — suppresses those lines that summarize the number of volumes listed and their status, which otherwise pop up at the beginning AND the end of the output when the output includes more than one volume. she's shy, let her be 🤫
  • -nosort — suppresses the default sorting of volume entries alphabetically by volume name. chaos mode, enabled.
  • -cell <cell name> — names the cell in which to run the command. do NOT combine this argument with the -localauth flag. for more details, see vos(1).
  • -noauth — assigns the unprivileged identity "anonymous" to the issuer. do NOT combine this flag with the -localauth flag. more details live in vos(1).
  • -localauth — constructs a server ticket using a key from the local /etc/openafs/server/KeyFile file. the vos command interpreter presents it to the Volume Server and Volume Location Server during mutual authentication. do NOT combine this flag with the -cell argument or the -noauth flag. more details in vos(1).
  • -verbose — produces a detailed trace of the command's execution on the standard output stream. if this argument is omitted, only warnings and error messages show up. quiet queen behavior.
  • -encrypt — encrypts the command so the operation's results are not transmitted across the network in clear text 🔐 this option is available in OpenAFS versions 1.4.11 or later and 1.5.60 or later.
  • -noresolve — shows all servers as IP addresses instead of the DNS name. super useful when the server address is registered as 127.0.0.1 or when you're dealing with multi-homed servers. this option is available in OpenAFS versions 1.4.8 or later and 1.5.35 or later.
  • -config <configuration directory> — sets the location of the configuration directory to be used. this defaults to /etc/openafs, except if -localauth is specified, in which case the default is /etc/openafs/server. this option lets you use alternative configuration locations for testing purposes 🧪
  • -help — prints the online help for this command. all other valid options are ignored. she said what she said.

🌈 OUTPUT 🌈

if the output includes more than one VLDB entry, by default the first line reports which file server machine, partition, or both houses the volumes. the final line of output reports the total number of entries displayed. including the -quiet flag suppresses these lines entirely 🙈

by default, volumes are sorted alphabetically by volume name. including the -nosort flag skips the sorting step, which can speed up output production when there's a huge number of entries. efficiency is hot 🔥

the VLDB entry for each volume includes the following:

  • the base (read/write) volume name. the read-only and backup versions have the same name, with a .readonly and .backup extension respectively 💖
  • the volume ID numbers allocated to the versions of the volume that actually exist, in fields labeled "RWrite" for the read/write, "ROnly" for the read-only, "Backup" for the backup, and "RClone" for the ReleaseClone. (if a field doesn't appear, that version of the volume doesn't exist.) the appearance of the "RClone" field normally means a release operation did not complete successfully; the "Old release" and "New release" flags often also appear on one or more of the site definition lines described right after this 👀
  • the number of sites that house a read/write or read-only copy of the volume, following the string "number of sites ->".
  • a line for each site that houses a read/write or read-only copy of the volume, specifying the file server machine, partition, and type of volume ("RW" for read/write or "RO" for read-only). if a backup version exists, it's understood to share the read/write site. several flags can appear with a site definition:
    • Not released — indicates that the vos release command has not been issued since the vos addsite command was used to define the read-only site.
    • Old release — indicates that a vos release command did not complete successfully, leaving the previous, obsolete version of the volume at this site 💀
    • New release — indicates that a vos release command did not complete successfully, but that this site did receive the correct new version of the volume. messy but she pulled through.
  • if the VLDB entry is locked, the string "Volume is currently LOCKED", as well as (in OpenAFS 1.5.75 and later) one or more of the following strings:
    • Volume is locked for a move operation — indicates that the volume was locked due to a vos move or a vos convertROtoRW command.
    • Volume is locked for a release operation — indicates that the volume was locked due to a vos release command.
    • Volume is locked for a backup operation — indicates that the volume was locked due to a vos backup command.
    • Volume is locked for a delete/misc operation — indicates that the volume was locked due to a vos delentry, vos addsite, vos remsite, vos changeloc, vos syncvldb, vos syncserv, vos rename, or vos lock command.
    • Volume is locked for a dump/restore operation — indicates that the volume was locked due to a vos dump or vos restore command.

for further discussion of the "New release" and "Old release" flags, go read vos_release(1) bestie, she has the lore 📚

🦋 EXAMPLES 🦋

this command displays VLDB info for the Example Corporation volume called "usr", which has two read-only replication sites:

% vos listvldb -name usr
usr
 RWrite: 5360870981   ROnly: 536870982   Backup: 536870983
 number of sites -> 3
    server fs1.example.com partition /vicepa RO Site
    server fs3.example.com partition /vicepa RO Site
    server fs2.example.com partition /vicepb RW Site

this next one shows entries for two of the volumes that live on the file server machine "fs4.example.com". the first VLDB entry is currently locked. there are 508 entries that mention the machine as a volume site. five hundred and eight. periodt 💅

% vos listvldb -server fs4.example.com
VLDB entries for server fs4.example.com
    .       .           .        .
    .       .           .        .
user.smith
 RWrite: 278541326   ROnly: 278541327   Backup: 278542328
 number of sites -> 1
   server fs4.example.com partition /vicepg RW Site
 Volume is currently LOCKED
   user.terry
 RWrite 354287190   ROnly 354287191   Backup 354287192
 number of sites -> 1
   server fs4.example.com partition /vicepc RW Site
   .       .           .        .
   .       .           .        .
Total entries: 508

👑 PRIVILEGE REQUIRED 👑

None. zero. nada. you don't need a single special privilege to run this — she's for everyone 🫶

🌸 SEE ALSO 🌸

vos(1), vos_examine(1), vos_listvol(1), vos_lock(1), vos_unlock(1), vos_unlockvldb(1)

go read the whole friend group, they're all iconic ✨

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0. It was converted from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.

okay that's the whole page bestie, no cap, every last flag accounted for 🫡 now go forth and read your VLDB entries like the main character you are. the fine print says this came out of OpenAFS and it's dated 2026-07-27 — so like, fresh off the press, lowkey timeless, mwah 💋💖

📦 where this page comes from