BACKUP_VOLSETRESTORE(8)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💖 NAME 💖

BACKUP_VOLSETRESTORE(8) — it's an AFS Command Reference page, and the star of the show is:

backup_volsetrestore — restores, like, all the volumes in a volume set. every last one. 💅

✨ SYNOPSIS ✨

okay so here's the whole vibe, both ways you can say it (long form and the lil short form, same command bestie):

backup volsetrestore [-name <volume set name>]
    [-file <file name>]
    [-portoffset <TC port offset>+]
    [-extension <new volume name extension>] [-dryrun | -n]
    [-localauth] [-cell <cell name>] [-help]

backup vols [-na <volume set name>]
    [-f <file name>]
    [-p <TC port offset>+]
    [-e <new volume name extension>]
    [-dryrun | -n] [-l] [-c <cell name>] [-h]

🦋 DESCRIPTION 🦋

So. backup volsetrestore restores the complete contents of a whole group of read/write volumes straight to the file system, by pulling data from the last full dump plus every incremental dump after that for each volume. it's giving "restore everything, no crumbs left". 🧚

It's genuinely the most useful thing when you've lost data across multiple partitions, because it can restore each volume in a defined set to a different site. like yes, ONE volume here, another one over there, we're flexible. 💁

lowkey important aside: if the "FILE YES" instruction shows up in the /var/lib/openafs/backup/CFG_device_name file associated with the port offset you specified, then this command restores from the backup data file listed for that port offset in the Tape Coordinator's /var/lib/openafs/backup/tapeconfig file, instead of from tape. for clarity, the rest of this description just says "tapes" — but the Backup System handles backup data files pretty much the same way. 🎀

Real talk though — pick the right tool:

  • restoring one or more volumes to a single site only? that's usually more efficient with backup volrestore.
  • restoring all the volumes that lived on a single partition? that's usually more efficient with backup diskrestore.

You tell it which volumes to restore by giving it either the -name argument or the -file argument. pick one, bestie, don't ghost us.

  • -name — names a volume set. The Backup System restores every volume listed in the Volume Location Database (VLDB) that matches the server, partition, and volume name criteria defined in the volume set's volume entries — and for which dumps are available. It restores the volumes to their current site (machine and partition), and by default overwrites the existing volume contents. 😭
    • And no, the volume set does not have to have been used to back up volumes before (i.e. used as the -volumeset option to the backup dump command). You can define it fresh, especially to match the volumes you need to restore right now, and honestly that's usually the better choice. In fact, a temporary volume set — created by including the -temporary flag to the backup addvolset command — is extra useful here. A temporary volume set does not get added to the Backup Database and only exists during the current interactive backup session, which is perfect when you only need it for the single restore operation this command kicks off. ✨
    • Why is a specially defined volume set probably better? because volume sets previously defined for dump operations usually match the backup version of volumes, whereas for a restore it's best to define volume entries that match the base (read/write) name. In that case, the Backup System searches the Backup Database for the newest dump set that includes either the read/write or the backup version of the volume. If, in contrast, a volume entry explicitly matches the volume's backup or read-only version, the Backup System restores dumps of that volume version only. choices, choices. 🤔
  • -file — names a file that lists specific volumes and the site to restore each one to. The volume name must match the name used in Backup Database dump records rather than in the VLDB, if those two differ — because the Backup System does not look up volumes in the VLDB. 🙈 The site you specify can be different from the volume's current one; when it is, the Backup System removes the current version of the volume and updates the volume's location information in the VLDB.

Now, the -portoffset situation. If all of the full and incremental dumps of all the relevant volumes were not written to a type of tape that a single Tape Coordinator can read, then use -portoffset to list multiple port offset numbers in the order the tapes are needed. first, the port offset for the full dump, second the port offset for the level 1 incremental dump, and so on. 🌈

That implies the full dumps of all relevant volumes must have been written to a type of tape the first Tape Coordinator can read, the level 1 incremental dumps to a type of tape the second Tape Coordinator can read, and so on down the line. If your dumps are sitting on multiple incompatible tape types, either:

  • use the backup volrestore command to restore individual volumes, or
  • use this command after defining new volume sets that group together volumes that were dumped to compatible tape types.

for further discussion, see the OpenAFS Administration Guide. 📚

By default, the Backup System overwrites the contents of an existing volume with the restored data. To make a brand new volume to house the restored version instead, use the -extension argument. 💖 The Backup System derives the new volume's name by adding the specified extension to the read/write base name, and creates a new VLDB entry. The command does not affect the existing volume in any way — iconic, no collateral damage. However, if a volume with the specified extension also already exists, the command overwrites it. so, y'know. be aware. 💀

The -dryrun flag produces a list of the volumes that would be restored if -dryrun weren't included, without actually restoring anything. peek before you leap, bestie. 👑 See "OUTPUT" for a detailed description of the output, plus suggestions on how to combine it most effectively with the -file and -name arguments.

How long does this take? The execution time for a backup volsetrestore command depends on the number of volumes to be restored and the amount of data in them, but it can take hours to restore a large number of volumes. 😭 One way to cut the time down is to run multiple instances of the command simultaneously — either using the -name argument to specify disjoint volume sets for each command, or the -file argument to name files that list different volumes. This is possible if there are multiple available Tape Coordinators that can read the required tapes. And depending on how the volumes to be restored were dumped to tape, specifying disjoint volume sets can also reduce the number of tape changes required. multitasking queen behavior. 💅

Finally, the Tape Coordinator's default response to this command is to access the first tape it needs by invoking the "MOUNT" instruction in the local /var/lib/openafs/backup/CFG_device_name file — or, if there's no "MOUNT" instruction, by prompting the backup operator to insert the tape. 🎀

But if the "AUTOQUERY NO" instruction appears in the CFG_device_name file, or if whoever issued the butc command included the -noautoquery flag, the Tape Coordinator instead expects the tape to already be in the device. If it isn't, or if it's the wrong tape, the Tape Coordinator invokes the "MOUNT" instruction or prompts the operator. It also invokes the "MOUNT" instruction or prompts for any additional tapes needed to complete the restore operation — and the backup operator has to arrange to provide them. no cap, that part is on you. 🫶

✨ OPTIONS ✨

  • -name <volume set name> — names the volume set you wanna restore. The Backup System restores all the volumes in the VLDB that match that volume set's volume entries. Give this one or -file, bestie, not both 💅
  • -file <file name> — the full pathname of a file listing one or more volumes plus the site (file server machine + partition) each one goes back to. Use either this or -name, not both, okay?

Every volume's entry needs to sit on its own unbroken line, in exactly this shape:

<machine> <partition> <volume> [<comments> ...]

where:

  • <machine> — names the file server machine you're restoring the volume to.
  • <partition> — names the partition you're restoring the volume to.
  • <volume> — the volume to restore. Genuinely best practice: put the base (read/write) name of each volume here. Then the Backup System digs through the Backup Database for the newest dump set containing a dump of either the read/write or the backup version of that volume, and restores the dumps of that version, starting from the most recent full dump. If instead the name explicitly has the ".backup" or ".readonly" extension on it, the Backup System restores dumps of that volume version only. no mixing 🫶
  • <comments> ... — literally any other text. The Backup System ignores everything on a line after the volume name, so spill your notes here, bestie — super helpful for the backup operator or any other admin who comes along later.
  • Do NOT use wildcards (like ".*") in the <machine>, <partition>, or <volume> fields. It's fine for multiple lines to name the same volume — but the Backup System only processes the first one of them. periodt.
  • -extension <new volume name extension> — makes a brand new volume for each volume named by -name or -file, and that new volume houses the restored data. The Backup System builds the new name by appending your string to the read/write base name, and creates a fresh VLDB volume entry for it. Your existing volumes keep all their contents, untouched 💖 Any string other than ".readonly" or ".backup" is acceptable, but base name + extension cannot exceed 22 characters. If you want a period between the name and the extension, make it the first character of the string (like ".rst", for example).
  • -portoffset <TC port offset>+ — one or more port offset numbers (max of 128), each one matching a Tape Coordinator to use. If you list more than one value, the Backup System uses the first for the full dump of each volume, the second for the level 1 incremental dump of each volume, and so on and so on. It uses the final value in the list when restoring dumps at the corresponding depth in the dump hierarchy and all dumps at lower levels.

Give this argument unless the default of 0 (zero) works for all your dumps. And if 0 is just one of the values in your list, write it out explicitly in the right spot. don't be sneaky about it 🙈

  • -dryrun | -n — shows you a list of the volumes that would be restored if the flag weren't there, without actually restoring anything. The OUTPUT section down below breaks down the format. Bonus: when you pair it with -name, the output is super easy to edit and reuse as input for the -file argument on a later backup volsetrestore command. iconic behavior honestly ✨
  • -localauth — constructs a server ticket using a key from the local /etc/openafs/server/KeyFile file. The backup command interpreter presents it to the Backup Server, Volume Server and VL Server during mutual authentication. Do not combine this flag with -cell. More deets in backup(8).
  • -cell <cell name> — names the cell to run the command in. Do not combine this argument with -localauth. More deets in backup(8).
  • -help — prints the online help for this command. Every other valid option gets ignored, sorry not sorry 💀

🌈 OUTPUT 🌈

If you skipped -dryrun, the command shows you a unique task ID number for the operation, in two places:

  • In the shell window, right after the command line.
  • In the Tape Coordinator window, if the butc process was started at debug level 1.
Heads up bestie: the task ID number is not the same thing as the job ID number that backup jobs shows when you run backup volsetrestore in interactive mode. The Backup System doesn't assign either kind of ID number until the restoration process actually begins. no cap.

When -dryrun is included, no task ID or job ID numbers get reported, because none get assigned at all. Instead, the output opens with a count of how many volumes will be restored, then a line for each dump of a volume. For each volume, the line for the most recent full dump comes first, then lines for any subsequent incremental dumps follow, ordered by dump level. Just so you know — the lines for one given volume don't necessarily show up all together 👀

Each line looks like this (shown on two lines here purely so you can actually read it):

<machine> <partition> <volume_dumped> # as <volume_restored>; \
    <tape_name> (<tape_ID>); pos <position_number>; <date>

where:

  • <machine> — the file server machine that currently houses the volume, as listed in the VLDB.
  • <partition> — the partition that currently houses the volume, as listed in the VLDB.
  • <volume_dumped> — the version (read/write or backup) of the volume that got dumped, as listed in the Backup Database.
  • <volume_restored> — the name the volume gets restored under. The Backup System only restores data to read/write volumes. If -extension was included, that extension shows up on the name in this field (like "user.pat.rst", for example).
  • <tape_name> — the tape holding the dump of the volume, from the Backup Database. If the tape has a permanent name, that shows here; otherwise it's the AFS tape name.
  • <tape_ID> — the tape ID of the tape holding the dump of the volume, from the Backup Database.
  • <position_number> — the dump's position on the tape (so 31 means 30 volume dumps come before this one on the tape). If the dump got written to a backup data file, this number is the ordinal of the 16 KB-offset where the volume's data begins.
  • <date> — the date and time when the volume was dumped.

One cute way to generate a file for the -file argument: combine -name and -dryrun and pipe the output into a file. The OpenAFS Administration Guide section on using the Backup System to restore data walks you through editing that file however you need before feeding it to -file. 🎀

The output of this command only ever includes volumes where the Backup Database has at least one dump record. For volumes that have no dump records but are either listed in the file named by -file or show up in the VLDB as a match to a volume entry in the volume set named by -name, the command interpreter writes a message to the standard error stream. keep an eye out 💅

🦋 EXAMPLES 🦋

This command restores every volume in the entries of the volume set named "data.restore" — that set was made expressly to restore data to a pair of file server machines where all the data got corrupted by a software error 😭 Every volume goes back to the sites recorded in its VLDB entry.

% backup volsetrestore -name data.restore
Starting restore
backup: task ID of restore operation: 112
backup: Finished doing restore

This next one restores all the volumes with entries in the file named /tmp/restore:

% backup volsetrestore -file /tmp/restore
Starting restore
backup: task ID of restore operation: 113
backup: Finished doing restore

And the /tmp/restore file itself looks like this:

fs1.example.com b user.pat
fs1.example.com b user.terry
fs1.example.com b user.smith
fs2.example.com c user.jones
       .         .     .
       .         .     .

👑 PRIVILEGE REQUIRED 👑

The issuer has to be listed in the /etc/openafs/server/UserList file on every machine where the Backup Server or Volume Location (VL) Server is running, and on every file server machine that houses an affected volume. If you threw in the -localauth flag, then instead the issuer must be logged on to a server machine as the local superuser "root". that's the vibe check, bestie ✨

💜 SEE ALSO 💜

butc(5), backup(8), backup_addvolentry(8), backup_addvolset(8), backup_diskrestore(8), backup_dump(8), backup_volrestore(8), butc(8)

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 a wrap on part 2, bestie 🫶 this page is from OpenAFS, dated 2026-07-27, and yes BACKUP_VOLSETRESTORE(8) ate and left no crumbs 💅✨

📦 where this page comes from