VOS_DUMP(1)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💾 vos_dump(1) — bestie, we're turning a whole volume into ASCII ✨

okay so literally welcome to vos_dump, the AFS Command Reference's own little conversion station 💅 it takes a volume and turns it into ASCII, and yes we're getting into it.

📛 NAME

vos_dump — converts a volume into ASCII format and writes it to a file 🎀

🌸 SYNOPSIS

vos dump -id <volume name or ID>
    [-time <dump from time>]
    [-file <dump file>] [-server <server>]
    [-partition <partition>] [-clone] [-omitdirs]
    [-cell <cell name>] [-noauth] [-localauth]
    [-verbose] [-encrypt] [-noresolve]
    [-config <config directory>]
    [-help]

vos du -i <volume name or ID>
    [-t <dump from time>]
    [-f <dump file>] [-s <server>]
    [-p <partition>]
    [-cl] [-o] [-ce <cell name>] [-noa] [-l]
    [-v] [-e] [-nor]
    [-co <config directory>]
    [-h]

ngl the short version is doing the absolute most with those two-letter flags and I respect it 🫶

🗂️ DESCRIPTION

So vos dump converts the contents of the volume you point at — and it can be read/write, read-only or backup, all three are welcome here 👑 — into ASCII format. The Volume Server writes the converted contents to the file named by the -file argument, or straight to the standard output stream. And if you go the standard-output route, you can pipe that output into a named pipe, which is how you get interop with third-party backup utilities. iconic behaviour fr fr 🦋

Want the complete contents of a volume (a full dump)? Then just omit the -time argument, or pass it the value 0 (zero). Periodt. Want an incremental dump instead — like, only the files and directories in the volume whose modification timestamps are later than a certain time — then you give -time a date and time as its value ✨

By default the vos command interpreter goes and asks the Volume Location Database (VLDB) where the volume lives, so you don't need -server and -partition. But here's the tea: if -id names a read-only volume that lives at multiple sites, the command dumps the version from just one of them (normally the one listed first in the volume's VLDB entry, as reported by the vos examine or vos listvldb command). Wanna dump that read-only volume from a particular site? Use -server and -partition to specify it 💅

And if you want to bypass the VLDB lookup entirely? Give a volume ID number (not a name) as the value for -id, plus the -server and -partition arguments. This makes it possible to dump a volume that has no VLDB entry at all. iykyk 😌

Heads up bestie: during the dump operation, the volume is inaccessible both to Cache Managers and to other volume operations. Dumping a volume doesn't otherwise affect its status on the partition or its VLDB entry though. We love a temporary lock 🔒

And to restore a dumped volume back into AFS, you use the vos restore command. that's the whole circle of life 🌈

⚠️ CAUTIONS

okay this part is serious, listen up 🙈

Support for incremental dumps exists to facilitate interoperation with third-party backup utilities. The vos dump command does not provide any of the administrative facilities of an actual backup system, so the administrator has to keep manual records of dump times and the relationship between full and incremental dumps of a volume. No cap.

For a volume's contents to be consistent after restoration of incremental dumps, there must be no gap between the time at which a prior dump of the volume was created and the value of the -time argument to the vos dump command that creates the incremental dump. Let me say that again in smaller words 🔍

  • For a read/write volume: the -time argument must specify the time that the prior dump was performed.
  • For a read-only or backup volume: it must specify the time that the volume was last released (using the vos release command) or cloned (using the vos backup or vos backupsys command) prior to dumping it.

And the parent dump can be either a full dump or another incremental dump. it's giving "lineage" 🌳

✨ OPTIONS ✨

  • -id <volume name or ID> — Specifies either the complete name or volume ID number of the read/write, read-only, or backup volume to dump. this one is mandatory bestie 🎀
  • -time <dump from time> — Specifies whether the dump is full or incremental. Omit this argument to create a full dump, or provide one of three acceptable values:
    • The value 0 (zero) to create a full dump. 🫶
    • A date in the format mm/dd/yyyy (month, day and year) to create an incremental dump that includes only files and directories with modification timestamps later than midnight (12:00 a.m.) on the indicated date. Valid values for the year range from 1970 to 2037; higher values are not valid because the latest possible date in the standard UNIX representation is in 2038. The command interpreter automatically reduces later dates to the maximum value. An example is "01/13/1999".
    • A date and time in the format "mm/dd/yyyy hh:MM" to create an incremental dump that includes only files and directories with modification timestamps later than the specified date and time. The date format is the same as for a date alone. Express the time as hours and minutes (hh:MM) in 24-hour format (for example, 20:30 is 8:30 p.m.). Surround the entire expression with double quotes ("") because it contains a space. An example is "01/13/1999 22:30".
the 2038 thing?? yeah. UNIX said "no thoughts, head empty" after that 💀
  • -file <dump file> — Specifies the pathname of the file to which to write the dump. The file can be in AFS, but not in the volume being dumped. A partial pathname is interpreted relative to the current working directory. If this argument is omitted, the dump is directed to the standard output stream. 🌊
  • -server <server name> — Specifies the file server machine on which the volume resides. Provide the -partition argument along with this one. they're a package deal, don't separate them 😭
  • -partition <partition name> — Specifies the partition on which the volume resides. Provide the -server argument along with this one. see? told you 💞
  • -clone — Normally, vos dump locks the volume and dumps it, which blocks writes to the volume while the dump is in progress. If this flag is given, vos dump will instead clone the volume first (similar to what vos move would do) and then dumps the clone. This can significantly decrease the amount of time the volume is kept locked for dumps of large volumes. lowkey the main character flag for big volumes 👑
  • -omitdirs — By default, vos dump includes all directory objects in an incremental dump whether they've been changed or not. If this option is given, unchanged directories will be omitted. This will reduce the size of the dump and not cause problems if the incremental is restored, as expected, on top of a volume containing the correct directory structure (such as one created by restoring previous full and incremental dumps). smol dump, big brain 🧚
  • -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. For more details, see vos(1). hi mysterious stranger 🙈
  • -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 -noauth flag. For more details, see vos(1). 🔑
  • -verbose — Produces on the standard output stream a detailed trace of the command's execution. If this argument is omitted, only warnings and error messages appear. she's chatty and we love her 💬
  • -encrypt — Encrypts the command so that 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. This is very useful when the server address is registered as 127.0.0.1 or when 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> — Set 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 allows the use of alternative configuration locations for testing purposes. 🧪
  • -help — Prints the online help for this command. All other valid options are ignored. she said "I'm the only one talking now" 💅

🍓 EXAMPLES

The following command writes a full dump of the volume "user.terry" to the file /afs/example.com/common/dumps/terry.dump.

% vos dump -id user.terry -time 0 -file /afs/example.com/common/dumps/terry.dump

The following command writes an incremental dump of the volume "user.smith" to the file "smith.990131.dump" in the current working directory. Only those files in the volume with modification time stamps later than 6:00 p.m. on 31 January 1999 are included in the dump.

% vos dump -id user.smith -time "01/31/1999 18:00" -file smith.990131.dump

see how the quotes wrap the whole date and time? that's the vibe check passing ✅

👑 PRIVILEGE REQUIRED

The issuer must be listed in the /etc/openafs/server/UserList file on the machine specified with the -server argument and on each database server machine. If the -localauth flag is included, the issuer must instead be logged on to a server machine as the local superuser "root". 🌟

If the -file argument is included, the issuer must also have permission to insert and write in the directory that houses the file. 📝

🔗 SEE ALSO

restorevol(1), vos(1), vos_examine(1), vos_listvldb(1), vos_restore(1)

the whole friend group honestly 🫶

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.

and that's the whole page bestie 💖 this was OpenAFS, dated 2026-07-27, from the VOS_DUMP(1) manual — go dump a volume (responsibly, and write down your dump times, I'm begging you 😭) ✨🎀

📦 where this page comes from