BACKUP_VOLRESTORE(8)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

🌸 NAME 🌸

backup_volrestore — bestie, this is the one that restores one or more volumes 💖

✨ SYNOPSIS ✨

backup volrestore -server <destination machine>
    -partition <destination partition>
    -volume <volume(s) to restore>+
    [-extension <new volume name extension>]
    [-date <date from which to restore>+]
    [-portoffset <TC port offsets>+] [-dryrun | -n]
    [-usedump <specify the dumpID to restore from>]
    [-localauth] [-cell <cell name>] [-help]

backup volr -s <destination machine>
    -pa <destination partition>
    -v <volume(s) to restore>+
    [-e <new volume name extension>]
    [-d <date from which to restore>+]
    [-po <TC port offsets>+]
    [-u <specify the dumpID to restore from>]
    [-dryrun | -n] [-l] [-c <cell name>] [-h]

🦋 DESCRIPTION 🦋

okay so backup volrestore restores the contents of one or more volumes to the site that you point at with the -server and -partition arguments. And like… you get to pick: either you overwrite the contents of volumes that already exist with the restored data, or you create brand new volumes while keeping the old ones around (iconic, honestly). And the site you name does not have to be the current site for those volumes. freedom 💅

(heads up: if the "FILE YES" instruction shows up in the /var/lib/openafs/backup/CFG_device_name file that's associated with the port offset you specified, then backup volrestore restores data 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. and for clarity's sake, all the text below just says "tapes" — but fr fr, the Backup System treats backup data files pretty much the same way.)

So the command's arguments can be combined like this, bestie:

  • To keep a volume's current contents AND also make a new volume to hold the restored version → use the -extension argument. The Backup System creates the new volume on the server and partition named by the -server and -partition arguments, gives it the same name as the current volume plus the extension you specified, and creates a new Volume Location Database (VLDB) entry for it. making a new volume lets the administrator compare the two versions. it's giving side-by-side, lowkey genius. 🫶
  • To overwrite a volume's existing contents with the restored version → leave out the -extension argument, and specify the site like so:
    • To keep the current site, just specify it with the -server and -partition arguments.
    • To move the volume to a different site while overwriting it, specify the new site with the -server argument, the -partition argument, or both. The Backup System creates a new volume at that site, removes the existing volume, and updates the site info in the volume's VLDB entry. Important though: the backup version of the volume is not removed automatically from the original site, if it exists. Use the vos remove command to remove it, and the vos backup command to create a backup version at the new site. no cap, don't forget that part 💀
  • To restore a volume that no longer exists in the file system → specify its name with the -volume argument and use the -server and -partition arguments to put it at the site you want. The Backup System creates a new volume and a new VLDB entry. resurrection era ✨

In every one of those cases, the command sets each volume's creation date to the date and time at which it restores it. That creation date shows up in the "Creation" field in the output from the vos examine and vos listvol commands. 📅

If you're restoring all of the volumes that lived on a single partition, it's usually more efficient to use the backup diskrestore command. And if you're restoring multiple volumes to lots of different sites, it can be more efficient to use the backup volsetrestore command. efficiency queen 👑

By default, backup volrestore restores the most recent full dump and all the subsequent incremental dumps for each volume, bringing the restored volumes to the most current possible state. 🏁 But if you want to restore the volumes to their state at some point in the past, use the -date argument. The Backup System restores the most recent full dump and each subsequent incremental dump for which the clone date of the volume included in the dump is before the date and time you gave it (the clone date timestamp appears in the "clone date" field of the output from the backup volinfo command). For backup and read-only volumes, the clone date represents the time at which the volume was copied from its read/write source; for read/write volumes, it represents the time at which the volume was locked for inclusion in the dump. And listen — how much a restored volume actually resembles its real state at the time you named depends on how much time elapsed between the volume's clone date in the last eligible dump and the time you specified. so like, manage expectations bestie 😭

If the -volume argument specifies the base (read/write) form of the volume name, the Backup System searches the Backup Database for the newest dump set that includes a dump of either the read/write or the backup version of the volume. It restores the dumps of that version of the volume, starting with the most recent full dump. If, on the other hand, the volume name explicitly includes the .backup or .readonly extension, the Backup System restores dumps of that corresponding volume version only. specific much? yes. correct? also yes. 💅

To generate a list of the tapes the Backup System needs to do the restore operation — without actually doing it — combine the -dryrun flag with the options you'd use on the actual command. a lil peek behind the curtain, we love a test run 🙈

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, use the -portoffset argument to list multiple port offset numbers in the order the tapes are needed (first list the port offset for the full dump, second the port offset for the level 1 incremental dump, and so on). If you're restoring multiple volumes, the same ordered list of port offsets has to apply to all of them. If it doesn't? Either issue this command separately for each volume, or use the vos volsetrestore command after defining groups of volumes that were dumped to compatible tape types. For further discussion, see the OpenAFS Administration Guide. 📚

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 by prompting the backup operator to insert the tape if there's no "MOUNT" instruction. But — plot twist — if the "AUTOQUERY NO" instruction appears in the CFG_device_name file, or if whoever ran the butc command included the -noautoquery flag, the Tape Coordinator instead expects the tape to already be in the device. If it's not there, or 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 extra tapes needed to finish the restore operation, and the backup operator has to arrange to provide them. 🎀

so yeah, the Tape Coordinator will absolutely tap you on the shoulder for tapes. not a drill bestie, stay by the drive.

✨ OPTIONS ✨

  • -server <destination machine> — tells the Backup System which file server machine to restore each volume onto, bestie. Here's the tea tho: if this argument and -partition point at a site that is not the current site of each volume, and you did not also pass -extension, then the Backup System removes the existing volumes from their current sites, drops the restored contents at the specified site, and updates the site info in that volume's VLDB entry. Moving day, fr. 🚚
  • -partition <destination partition> — names the partition each volume gets restored into. Same drama as above: if this one and -server name a site that isn't the volume's current site, and -extension is absent, the Backup System pulls the existing volumes off their current sites, puts the restored contents at the specified site, and rewrites the site info in the volume's VLDB entry. 💅
  • -volume <volume to restore>+ — names one or more volumes to restore, using the name as it's listed in the Backup Database. Give the base (read/write) name of each volume, and the Backup System will search the Backup Database for the newest dump set that includes a dump of either the read/write or the backup version of that volume — then it restores the dumps of that version, starting with the most recent full dump. BUT. If a volume name explicitly includes the .backup or .readonly extension, it restores dumps of that matching volume version only. Pick your fighter. ⚔️
  • -extension <new volume name extension> — makes a whole new volume to hold the restored data, named by appending the string you give to each volume named by -volume. The Backup System creates a brand-new VLDB entry for it too, iconic. Any string other than .readonly or .backup is acceptable, but heads up: the existing volume name + extension can't go over 22 characters total. Want a period separating the extension from the name? Make it the first character of the string (like .rst, for example). 🎀
  • -date <date from which to restore>+ — gives a date, and optionally a time; the restored volume only includes data from dumps performed before that date. Format is mm/dd/yyyy [hh:MM], where the required mm/dd/yyyy part is month (mm), day (dd), and year (yyyy), and the optional hh:MM part is hour and minutes in 24-hour format (so 14:36 means 2:36 p.m., no cap). If you omit the time, it defaults to 59 seconds after midnight (00:00:59 hours). 🌙

Valid year values run from 1970 to 2037; higher values aren't valid because the latest possible date in the standard UNIX representation lands in February 2038. The command interpreter automatically reduces any later date down to the maximum value. Time really does be limited. 😭

If you omit this argument entirely, the Backup System restores all possible dumps, including the most recently created one. Everything, babe.

  • -usedump <dumpID> — specifies the dumpID of the exact dump to use for restoring the volume. Skip this option and the appropriate dump gets found for you, following the same logic described under the -date option. 🧚
  • -portoffset <TC port offest>+ — (yes, the manpage really spells it offest, iykyk 🫶) specifies one or more port offset numbers, up to a max of 128, each one matching a Tape Coordinator to use in the operation. With more than one value, the Backup System uses the first one when restoring the full dump of each volume, the second one when restoring the level 1 incremental dump of each volume, and so on. It uses the final value in the list when restoring dumps at that corresponding depth in the dump hierarchy and all dumps at lower levels.

Pass this argument unless the default value of 0 (zero) happens to be right for all your dumps. And if 0 is just one of the values in your list, you have to spell it out in the right position. No skipping, she's precise. ✨

  • -dryrun | -n — shows you the list of tapes holding the dumps the restore would need, without actually doing the restore. Window shopping, basically. 🙈
  • -localauth — builds a server ticket using a key from the local /etc/openafs/server/KeyFile file. The backup command interpreter shows it to the Backup Server, Volume Server and VL Server during mutual authentication. Do not combine this flag with the -cell argument. More details live in backup(8). 🔑
  • -cell <cell name> — names the cell to run the command in. Do not combine this argument with the -localauth flag. More details in backup(8). 🌐
  • -help — prints the online help for this command. Every other valid option just gets ignored, sorry babes, she's busy.

📼 OUTPUT 📼

If whoever runs the command includes the -dryrun flag, this string shows up at the head of the list of tapes needed to complete the restore operation:

Tapes needed:

🌸 EXAMPLES 🌸

This command restores the volume user.pat to partition /vicepa on the machine "fs5.example.com":

% backup volrestore -server fs5.example.com -partition a -volume user.pat

This command restores the volumes "user.smith" and "user.terry" to partition /vicepb on the machine "fs4.example.com", adding a .rst extension to each volume name and preserving the existing "user.smith" and "user.terry" volumes. Only dumps created before 5:00 p.m. on 31 January 1998 get restored. (The command is shown on multiple lines here purely for legibility reasons, bestie.)

% backup volrestore -server fs4.example.com -partition b  \
                    -volume user.smith user.terry  \
                    -extension .rst -date 1/31/1998 17:00

And this command restores the volume user.pat to partition /vicepb on the machine "fs4.example.com". The Tape Coordinator with port offset 1 handles the tape holding the full dump; the Tape Coordinator with port offset 0 handles all the tapes holding incremental dumps. (Shown on two lines only for legibility reasons.)

% backup volrestore -server fs5.example.com -partition a  \
                    -volume user.pat -portoffset 1 0

👑 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 the -localauth flag is included, the issuer must instead be logged on to a server machine as the local superuser "root". Root access, main character energy only. 💅

🦋 SEE ALSO 🦋

butc(5), backup(8), backup_dump(8), backup_diskrestore(8), backup_volsetrestore(8), butc(8), vos_backup(1), vos_remove(1)

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, we ate and left no crumbs 💅✨ This one's from the OpenAFS era, dated 2026-07-27, and it lives at <hotpink>BACKUP_VOLRESTORE(8)</hotpink> — go restore something responsibly, bestie 🫶🎀

📦 where this page comes from