BACKUP_DISKRESTORE(8)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💖 BACKUP_DISKRESTORE(8) 💖 — the AFS Command Reference, but make it make sense

okay bestie, you already know it's giving AFS Command Reference. This is the manual page for backup_diskrestore, and it's a whole journey, so strap in. 🦋

✨ NAME ✨

backup_diskrestore — restores the entire contents of a partition 💅 (yes, the whole partition, main character energy only)

✨ SYNOPSIS ✨

backup diskrestore -server <machine to restore>
    -partition <partition to restore>
    [-portoffset <TC port offset>+]
    [-newserver <destination machine>]
    [-newpartition <destination partition>]
    [-extension <new volume name extension>]
    [-dryrun | -n] [-localauth] [-cell <cell name>] [-help]

backup di -s <machine to restore>
    -pa <partition to restore>
    [-po <TC port offset>+]
    [-news <destination machine>]
    [-newp <destination partition>]
    [-e <new volume name extension>] [-dryrun | -n] [-l]
    [-c <cell name>] [-h]
ngl, the second block is just the first block in its cropped-top era ✂️ — same command, shorter flags.

✨ DESCRIPTION ✨

So. backup diskrestore restores all of the volumes for which the Volume Location Database (VLDB) lists a read/write site on the partition you name with the -server and -partition arguments. This is your emergency button when a disk or machine failure has corrupted or destroyed the data on an entire partition 😭💀. And before you ask — to restore any read-only or backup volumes that lived on that partition, you use the vos release and vos backup commands, respectively, after you've restored the read/write version. order matters, bestie 🫶

If you're only restoring selected volumes to a single site, it's usually more efficient to use backup volrestore. And if you need to restore multiple volumes to many different sites, use backup volsetrestore. right tool, right job ✨

(Okay, side quest: if the "FILE YES" instruction appears in the /var/lib/openafs/backup/CFG_device_name file on the Tape Coordinator machine associated with the specified port offset, then the Backup System 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. For the sake of clarity, the text below only talks about tapes, but the Backup System handles backup data files in pretty much the same way. iykyk 🎀)

The Backup System figures out whether the read/write or the backup version of each volume was dumped more recently, and restores the dumps of that version, starting with the most recent full dump. It resets the creation timestamp of each restored volume to the date and time at which it begins restoring the volume — that creation timestamp is the one that shows up in the "Creation" field of the output from the vos examine and vos listvol commands 👑

Now, if all of the full and incremental dumps of all relevant volumes were not written on compatible tape devices, you use the -portoffset argument to list multiple port offset numbers in the order in which 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. This implies that the full dumps of all relevant volumes must have been written to a type of tape that the first Tape Coordinator can read, the level 1 incremental dumps to a type of tape the second Tape Coordinator can read, etc. etc. If your dumps are on multiple incompatible tape types, use the backup volrestore command to restore individual volumes, or the backup volsetrestore command after defining groups of volumes that were dumped to compatible tape types. For further discussion, see the OpenAFS Administration Guide 📚

By default, the Backup System restores the contents of the specified partition to that same partition. To restore the contents to an alternate site, combine the following options as indicated. The Backup System removes each volume from the original site, if it still exists, and records the change of site in the VLDB. 🏠➡️🏡

  • To restore to a different partition on the same file server machine, provide the -newpartition argument.
  • To restore to the partition with the same name on a different file server machine, provide the -newserver argument.
  • To restore to a completely different site, combine the -newserver and -newpartition arguments.

By default, the Backup System overwrites the contents of existing volumes with the restored data. To create a new volume to house the restored data instead, use the -extension argument. The Backup System creates the new volume at the site designated by the -newserver and -newpartition arguments if they're used, or the -server and -partition arguments otherwise. It derives the volume name by adding the extension to the read/write base name listed in the VLDB, and creates a new VLDB entry. The command does not affect the existing volume in any way. However, if a volume with the specified extension also already exists, the command overwrites it 😳 so be careful out there.

To print out a list of the tapes containing the needed dumps, without actually performing the restore operation, include the -dryrun flag along with the other options you'd use on the actual command. window shopping, but for tapes 🛍️

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 CFG_device_name file, or by prompting the backup operator to insert the tape if there's no "MOUNT" instruction. However — and this is the plot twist — if the "AUTOQUERY NO" instruction appears in the CFG_device_name file, or if the issuer of 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; the backup operator must arrange to provide them, no one else is gonna do it 🙈

⚠️ CAUTIONS ⚠️

If you're issuing this command to recover data after a disk crash or other damage, be sure not to issue the vos syncserv command first. Doing so destroys the VLDB record of the volumes that resided on the partition. like, unalives it. do not. 💀🚫

✨ OPTIONS ✨

  • -server <machine to restore> — Names the file server machine that the VLDB lists as the site of the volumes that need to be restored.
  • -partition <partition to restore> — Names the partition that the VLDB lists as the site of the volumes that need to be restored.
  • -portoffset <TC port offset>+ — Specifies one or more port offset numbers (up to a maximum of 128), each one corresponding to a Tape Coordinator to use in the operation. If there's 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 the corresponding depth in the dump hierarchy and at all lower levels. Provide this argument unless the default value of 0 (zero) is appropriate for all dumps. If 0 is just one of the values in the list, provide it explicitly in the appropriate order. no skipping, bestie 👑
  • -newserver <destination machine> — Names an alternate file server machine to which to restore the volumes. If this argument is omitted, the volumes are restored to the file server machine named by the -server argument.
  • -newpartition <destination partition> — Names an alternate partition to which to restore the data. If this argument is omitted, the volumes are restored to the partition named by the -partition argument.
  • -extension <new volume name extension> — Creates a new volume for each volume being restored, to house the restored data. The Backup System derives the new volume's name by appending the specified string to the read/write base name listed in the VLDB, and creates a new VLDB volume entry. The Backup System preserves the contents of the volumes on the partition, if any still exist. Any string other than ".readonly" or ".backup" is acceptable, but the combination of the base name and extension cannot exceed 22 characters in length. To use a period to separate the extension from the name, specify it as the first character of the string (as in ".rst", for example). 🎀
  • -dryrun | -n — Displays a list of the tapes necessary to perform the requested restore, without actually performing the operation.
  • -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 the -cell argument. For more details, see backup(8).
  • -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 backup(8).
  • -help — Prints the online help for this command. All other valid options are ignored.

✨ OUTPUT ✨

If a tape error occurs during the restore operation, the Tape Coordinator displays these messages:

Restore operation on volume I<name> failed due to tape error
Do you want to continue (y/n)?

where name is the name of the volume that was being restored when the tape error occurred. Enter the value y to continue the operation without restoring the indicated volume, or enter the value n to terminate the operation. In the latter case, the operator can then attempt to figure out the cause of the tape error. detective era 🔍

If the issuer includes the -dryrun flag with the command, the following string appears at the head of the list of the tapes necessary to perform the restore operation:

Tapes needed:

✨ EXAMPLES ✨

Okay this next one restores the volumes for which the VLDB lists a read/write site on the /vicepd partition of the machine fs5.example.com. The Tape Coordinator associated with port offset 3 performs the operation 💫

% backup diskrestore -server fs5.example.com   \
                     -partition /vicepd -portoffset 3

And this one restores the volumes for which the VLDB lists a read/write site on the /vicepb partition of the machine fs1.example.com to a new site: the /vicepa partition on the machine fs3.example.com. The Tape Coordinator associated with port offset 0 performs the operation. (The command appears here on two lines only for legibility, she's just being dramatic 🌸)

% backup diskrestore  -server fs1.example.com -partition /vicepb   \
                      -newserver fs3.example.com -newpartition /vicepa

And finally, this one lists the tapes required to restore the volumes for which the VLDB lists a read/write site on the /vicepm partition of the machine fs4.example.com 🎀

% backup diskrestore -server fs4.example.com -partition /vicepm -dryrun
Tapes needed:
user.sunday1.1
user.sunday1.2
user.monday1.1
user.tuesday1.1
user.wednesday1.1
⭐ psst — this is only part 1, bestie, don't go anywhere. the rest is coming 💜

🔐 PRIVILEGE REQUIRED 🔐

okay bestie this is the part where you find out if you're actually allowed to do the thing, and the vibes are strict but fair 💅

  • the issuer — that's you, hi — must be listed in the /etc/openafs/server/UserList file on every machine where the Backup Server or Volume Location (VL) Server is running 👑
  • …and also on every file server machine that houses an affected volume. like, all of them. no skipping. she checks everywhere 🧐
  • but wait — if the -localauth flag is included, then instead of all that, the issuer must be logged on to a server machine as the local superuser "root" ✨
fr fr, don't sleep on this one — no UserList entry and no -localauth means you're just a girl standing in front of a Backup Server asking it to restore a volume, and it's gonna say no 😭

👀 SEE ALSO 👀

the group chat of related commands, all iconic in their own right 🫶

the legal girlypop section, we respect her 🎀

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. legends, honestly 🌟

and that's the whole page bestie, you ate that 💖 this was BACKUP_DISKRESTORE(8) from OpenAFS, dated 2026-07-27 — go restore something and slay responsibly, mwah 💅✨

📦 where this page comes from