BACKUP_DUMP(8)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💖 NAME 💖

backup_dump — okay so this is the one that creates a dump, aka it dumps a volume set at a particular dump level. 💅 It's BACKUP_DUMP(8), straight out of the AFS Command Reference, so bestie we are in section 8 and we are doing Serious Sysadmin Things.

✨ SYNOPSIS ✨

backup dump [-volumeset <volume set name>]
    [-dump <dump level name>]
    [-portoffset <TC port offset>]
    [-at <date/time to start dump>+]
    [-append] [-dryrun | -n]
    [-file <load file>] [-localauth]
    [-cell <cell name>] [-help]

backup dump [-v <volume set name>]
    [-d <dump level name>]
    [-p <TC port offset>]
    [-at <Date/time to start dump>+] [-ap] [-dryrun | -n]
    [-f <load file>] [-l] [-c <cell name>]
    [-h]

Two forms, same energy — one's the long-form glow-up, one's the shorthand version for when you're typing fast. Both are literally the same command. 🫶

🦋 DESCRIPTION 🦋

The backup dump command does one of two things:

  • It dumps the volume set named by the -volumeset argument, at the dump level named by the -dump argument, and creates a Backup Database dump record about it. 💾
  • Or it goes and executes the dump instructions that are listed in the file named by the -file argument. 📄

Either way, the Tape Coordinator pointed at by the -portoffset argument (or the one named on each command inside the file) is the one that actually executes the operation. No cap.

ngl, there's a little plot twist: if the "FILE YES" instruction shows up in the /var/lib/openafs/backup/CFG_device_name file on the Tape Coordinator machine that's tied to the specified port offset, then the Backup System dumps data to the backup data file listed for that port offset in the Tape Coordinator's /var/lib/openafs/backup/tapeconfig file, instead of to tape. For clarity's sake, everything below just says "tapes", but the Backup System handles backup data files in basically the same way. 🙈

🌸 The vocabulary, because words matter 🌸

  • dumping — the act of copying a collection of data to tape or a backup data file. 🎀
  • a dump — the resulting collection. ✨
  • a dump set — the set of tapes that contain one or more dumps. 📼
  • the initial dump — the first dump in a dump set. 👑
  • appended dumps — any dumps that get added to the dump set afterwards, by using the -append argument.

Creating appended dumps is totally optional, and like, appended dumps can be of different volume sets and at different dump levels than the initial dump. Yes really. Slay.

A full dump, created at a full dump level in the dump hierarchy, contains all of the data that existed at the time of the dump in the volumes belonging to the volume set. Everything. The whole meal. 🍓

An incremental dump, created at an incremental dump level, contains only the data that has changed since the volume set was dumped at the incremental level's parent dump level — and the parent is the dump level immediately above the incremental level in the hierarchy, which can be a full level or another incremental level. More specifically, an incremental dump includes only the files and directories that have modification timestamps later than the clone date of the volume included at the parent dump level.

And what even is the clone date, you ask?

  • For backup and read-only volumes, it's the time at which the volume was cloned from its read/write source before being included in the parent dump. 🧚
  • For read/write volumes, it represents the time at which the volume was locked for inclusion in the parent dump. 🔒

The clone date shows up in the clone date field of the output from the backup volinfo command. iykyk.

Example time, because examples are the moment: an incremental dump at the "/full/week1/thursday" level includes only the files and directories that have changed since the volume set was dumped at the "/full/week1" level. Simple as that. 💅

🎀 Initiating different types of dump operations 🎀

To kick off a dump operation that's gonna start the second the relevant Tape Coordinator is available, you only need -volumeset, -dump, -portoffset, and optionally -append. That's it, that's the whole thing. 🫶

To schedule a single backup dump command to execute in the future, you also throw in the -at argument to specify the start time. ⏰

To append a dump to an existing dump set, include the -append flag. But heads up — the Backup System imposes these conditions on appended dumps:

  • If writing to tape, the Tape Coordinator checks that it is the final one in a dump set for which there are complete and valid tape and dump records in the Backup Database. If it's not, it rejects the tape and requests an acceptable one. The operator can use the -dbadd argument to the backup scantape command to insert the necessary records into the database. 🚫📼
  • The most recent dump on the tape or in the backup data file must have completed successfully. ✅
  • The dump set must begin with an initial dump that is recorded in the Backup Database. If there are no dumps on the tape, then the Backup System treats the dump operation as an initial dump and imposes the relevant requirements (for example, it checks the AFS tape name if appropriate). 🔍

To schedule multiple dump operations, you list the operations in the file named by the -file argument. Optionally include -at to specify when the backup command interpreter reads the file — otherwise it reads it immediately. ⚠️ And do not combine the -file argument with the command's first three arguments, or with the -append or -dryrun flags. The commands inside the file can include any of the backup dump command's arguments, including -at to schedule them to run even later in the future. 👑

To generate a list of the volumes included in a dump without actually dumping them, combine the -dryrun flag with the options you'd use on the actual command. Peek, don't leak. 🙈

🧚 How the Backup System executes a dump operation 🧚

Before it begins a dump operation, the Backup System verifies that there is a Backup Database entry for the volume set, dump level, and port offset. If the command is correctly formed and issued in interactive mode, it gets assigned a job number and added to the jobs list. 📋 You can list jobs in interactive mode with the backup jobs command, and terminate them with the backup kill command.

After it gets the list of volumes to dump from the Volume Location (VL) Server, the Backup System sorts the list by site (server and partition). It groups volumes from the same site together in the dump to minimize the number of times the operator has to change tapes during restore operations. Efficiency queen. 👑

Now, here's the thing about incremental dumps and their parents: because a child depends on its parent, a valid parent dump must already exist for the Backup System to create its child incremental dump. If the Backup System doesn't find a record of a dump created at the immediate parent dump level, it goes looking in the Backup Database for a dump created one level higher in the hierarchy, and so on, all the way up to the full dump level if it has to. It creates an incremental dump at the level one below the lowest valid parent dump set that it finds. And if it fails to find even a full dump? It just dumps the volume set at the full dump level. Periodt. 💅

If the Backup System can't access a volume during a dump operation, it skips that volume and dumps the remaining volumes from the volume set. 😭 Possible reasons a volume is inaccessible include:

  • server machine or process outages, or
  • the volume was moved between the time the Volume Location (VL) Server generated the list of sites for the volume in the volume set and the time the Backup System actually attempts to dump the data in it.

After the first dumping pass, the Backup System attempts to dump each volume it skipped. If it still can't dump a volume and the "ASK NO" instruction does not appear in the CFG_device_name file, it queries the operator: do we attempt to dump the volume again, omit the volume from the dump, or halt the dump operation altogether? When prompted, the operator can try to solve whatever problem was preventing the Backup System from accessing the volumes. But if the "ASK NO" instruction does appear in the CFG_device_name file, the Backup System just omits the volume from the dump. 🫥

Before scheduling a dump operation, the Backup System verifies that the date specified by the -at argument is in the future, and checks the validity of the volume set, dump level and port offset the same way it would for a regular dump operation. Then it checks the validity of the parameters again just before actually running the scheduled operation. Double-checking is self-care. ✨

Before writing an initial dump to a tape that doesn't have a permanent name on the label, the Backup System checks that the AFS tape name on the label is acceptable. If you want, you can disable name checking by including the "NAME_CHECK NO" instruction in the CFG_device_name file. 🏷️

If AFS tape name checking is enabled, the Backup System accepts these three types of values for the AFS tape name. If the name on the label doesn't conform, the Backup System obtains a tape with an acceptable label by invoking the "MOUNT" instruction in the CFG_device_name file, or by prompting the operator. 🌈

  • A name of the form volume_set_name.dump_level_name.tape_index, where volume_set_name matches the value of the -volumeset argument, dump_level_name matches the last element in the pathname value of the -dump argument, and tape_index reflects the tape's place in a multitape dump set. For example: the first tape in a dump set for which the initial dump is of volume set "user" at the dump level "/sunday2/monday" has AFS tape name "user.monday.1". If the label records this type of AFS tape name, the Backup System retains the AFS tape name and writes the dump to the tape. 📼
  • The string "<NULL>", which usually means a backup operator used the backup labeltape command to write a label on the tape, but didn't include the -name argument to assign an AFS tape name. Presumably they did include the -pname argument to assign a permanent name though. If the label records a "<NULL>" value, the Backup System constructs and records on the label the appropriate AFS tape name, and writes the dump on the tape. 🏷️
  • No value at all, because the tape has never been labeled or used in the Backup System. Same as when the AFS tape name is "<NULL>": the Backup System constructs and records on the label the appropriate AFS tape name, and writes the dump on the tape. 🆕

To figure out how much data it can write to a tape, the Tape Coordinator reads the capacity recorded on the tape's label (which got put there by including the -size argument to the backup labeltape command). If the label's capacity field is empty, the Tape Coordinator uses the capacity recorded for the specified port offset in the local tapeconfig file. And if the capacity field in the tapeconfig file is also empty, the Tape Coordinator falls back on the maximum capacity of 2 TB. 😤

During a dump operation, the Tape Coordinator tracks how much data it has written and stops shortly before it reaches what it believes is the tape's capacity. If it's in the middle of writing the data for a volume when it hits that point, it writes a special marker that indicates an interrupted volume, and continues writing the volume on the next tape. It can split a volume this way during both an initial and an appended dump, and the fact that the volume lives on multiple tapes is automatically recorded in the Backup Database. 💀📼

If the tape is actually bigger than the capacity everyone thought it had 🌈 then the Tape Coordinator just... doesn't use the extra tape. like, the surplus is right there and it's ignoring it. no harm, no foul, it simply doesn't touch it.

But if the tape is smaller than the expected capacity?? 😭 the Tape Coordinator can hit end-of-tape (EOT) at the worst possible moment, mid-write, totally unplanned. And if that happens while it's in the middle of writing the data from a volume, it goes and obtains a fresh tape and rewrites the entire contents of the interrupted volume onto it. The data from that volume that already landed on the previous tape? It's still sitting there. It is never used. it's giving ghost data, decaying, forgotten 💀

The Backup System does allow recycling of tapes — that's writing a brand new dump set over an old dump set nobody needs anymore — but bestie, it comes with conditions ✨:

  • Every dump in the old dump set has to be expired. The Backup System always checks expiration dates. Always. Even when name checking is disabled. no exceptions, it does not care 👑
  • If the tape you wanna recycle doesn't have a permanent name and name checking is enabled, then the AFS tape name that gets derived from the new initial dump's volume set name and dump level name has to match the AFS tape name already recorded on the label.
  • The tape cannot already have data on it that belongs to the dump currently being performed. Why? Because that would mean the operator or the automated tape device didn't remove the previous tape from the drive, or it got mistakenly reinserted 🙈 When that happens the Tape Coordinator prints this and goes looking for another tape:

Can't overwrite tape containing the dump in progress

  • The tape cannot hold data from a parent dump of the current (incremental) dump either — because overwriting a parent dump makes it impossible to restore data from the current dump. straight up impossible, do not do this So the Tape Coordinator prints this and goes looking for another tape:

Can't overwrite the parent dump I<parent_name> (I<parent_dump_ID>)

To recycle a tape before all the dumps on it have expired, or if the AFS tape name is wrong, you use the backup labeltape command 💅 — that overwrites the tape's label and removes all the associated tape and dump records from the Backup Database. clean slate energy ✨

The Tape Coordinator's default response to this command is to access the first tape by invoking the "MOUNT" instruction in the CFG_device_name file — or, if there's no "MOUNT" instruction, by prompting the backup operator to insert the tape. hi bestie, please insert the tape 🫶

BUT. If the "AUTOQUERY NO" instruction appears in the CFG_device_name file, or if whoever issued the butc command threw in the -noautoquery flag, then the Tape Coordinator instead just expects the tape to already be in the device. If it isn't? It invokes the "MOUNT" instruction or prompts the operator. It also invokes the "MOUNT" instruction (or prompts) for any additional tapes needed to finish the dump operation — and the issuer is the one who has to arrange to provide them. that's on you, not on the TC 💅

🚨 CAUTIONS 🚨

If a dump operation gets interrupted or fails for any reason, the data from all the volumes that were written to tape before the interrupt are valid and can be used in a restore operation. The Backup Database includes an entry for the failed dump and for each volume that was successfully dumped. See the OpenAFS Administration Guide for info on dealing with interrupted dumps 📖

If you're dumping to tape rather than to a backup data file, it is best to use only compatible tape devices — meaning ones that can read the same type of tape. Compatible devices make restore operations so much simpler, no cap. The -portoffset argument to the backup diskrestore and backup volsetrestore commands accepts multiple port offset numbers, but here's the tea ☕: the Backup System uses the first listed port offset when restoring all full dumps, the second port offset when restoring all level 1 dumps, and so on. At the very least, use compatible tape devices to perform dumps at each level. If you don't use compatible tape devices, then you gotta use the backup volrestore command to restore one volume at a time. one. at. a. time. 😭

Valid (unexpired) administrative tokens must be available to the backup command interpreter both when it reads the file named by the -file argument and when it runs each operation listed in that file. Presumably the issuer is scheduling dumps for times when no human operator is around 👻 — so they've gotta arrange for valid tokens to be available on the local machine.

One option: issue all the commands (or run all the scripts) on file server machines and use the -localauth flag on the backup and vos commands. But to protect against improper access to the machine or to the tokens, the machine must be physically secure — maybe even more protected than a Tape Coordinator machine that has a human operator watching it during operation. like, locked-closet levels of secure 🔒

Also, if an unattended dump needs multiple tapes, the operator has to properly configure a tape stacker or jukebox and the device configuration file. no shortcuts 💅

When the command is issued in regular (non-interactive) mode, the command shell prompt does not return until the dump operation completes. not me waiting forever at a shell prompt 🙈 To avoid having to open additional connections, issue the command in interactive mode — especially when you're including the -at argument to schedule dump operations.

✨ OPTIONS ✨

  • -volumeset <volume set name> — names the volume set you wanna dump. The -dump argument has to come along with this one (they're a duo 🫶), and do not combine them with the -file argument. If you're using a temporary volume set, the vos dump command must be issued within the interactive session in which the backup addvolset command was issued with the -temporary flag. iykyk ✨
  • -dump <dump level name> — specifies the complete pathname of the dump level at which to dump the volume set. The -volumeset argument must be provided alongside this one, and again — do not combine them with the -file argument.
  • -portoffset <TC port offset> — the port offset number of the Tape Coordinator that's handling the tapes for this operation. You must provide it unless the default value of 0 (zero) happens to be the right vibe. Do not combine it with the -file argument.
  • -at <date/time to start dump> — the date and time in the future at which to run the command, or to read the file named by the -file argument. Format is mm/dd/yyyy [hh:MM], where month (mm), day (dd) and year (yyyy) are all required. Valid year values run from 1970 to 2037 — anything higher isn't valid, because the latest possible date in the standard UNIX representation lands in February 2038 ⏳ The Backup System automatically reduces any later date to the maximum value. (it's giving "we'll cap you for your own good")

The hour and minutes (hh:MM) are optional, but if you do provide them they must be in 24-hour format — for example, the value "14:36" represents 2:36 p.m. If you leave them out, the time defaults to midnight (00:00 hours) 🌙

Example time: the value 04/23/1999 20:20 schedules the command for 8:20 p.m. on 23 April 1999 ⭐

  • -append — appends the dump onto the end of a tape that already contains data from another dump. Except… if that tape isn't actually part of an existing dump set, the Backup System just creates a new dump set using the parameters of this dump. plot twist 💀 And if the tape isn't the last tape in the dump set, the Tape Coordinator prompts for insertion of the appropriate tape. Do not combine this argument with the -file argument.
  • -dryrun, -n — displays the names of the volumes that would be included in the indicated dump, without actually performing the dump operation. it's the preview mode bestie 👀 Do not combine this argument with the -file argument.
  • -file <load file> — the local disk or AFS pathname of a file containing backup commands. The Backup System reads the file immediately, or at the time specified by the -at argument if you provided one. A partial pathname gets interpreted relative to the current working directory.

Put each backup dump command on its own line in that file, using the same syntax as the command line — but without the word backup at the start of the line. Each command must include a value for the -volumeset and -dump arguments, and for the -portoffset argument unless the default value of 0 is appropriate. Commands in the file can also include any of the backup dump command's optional options. In the example file below, the first command runs as soon as the Backup System reads the file, whereas the other commands are themselves scheduled — and those specified dates and times must be later than the date and time at which the Backup System reads the file ⏰

dump user /sunday1/wednesday -port 1
dump sun4x_56 /sunday1/friday -port 2 -at 04/08/1999
dump sun4x_55 /sunday1/friday -port 2 -at 04/08/1999 02:00 -append

Do not combine this argument with the -volumeset, -dump, -portoffset, -append, or -dryrun options. pick a lane 💅

  • -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. the classic "I don't see anyone else" move ✨

📤 OUTPUT 📤

The command interpreter first generates a list of the volumes to be included in the dump, by matching the entries in the volume set against the volumes listed in the Volume Location Database (VLDB) 👑 It prints that list after this header:

Preparing to dump the following volumes:

Then this message shows up to tell you the command interpreter has handed the dump request off to the appropriate Tape Coordinator for processing:

Starting dump.

If the issuer includes the -dryrun flag, the output looks like this instead:

Starting dump of volume set '<volume set>' (dump set '<dump level>')
Total number of volumes : <number dumped>
Would have dumped the following volumes:
<list_of_volumes>

where list_of_volumes identifies each volume by name and volume ID number 🔍

And if the Tape Coordinator can't access a volume, it prints an error message in its own window and records the error in its log and error files. so check the logs, bestie 📝

🌸 EXAMPLES 🌸

Okay bestie, real talk, this is where it all comes together. Let me show you what this actually looks like in the wild. 💅

🎀 Dumping a whole volume set at a specific dump level

So the command below dumps the volumes in the volume set called "user" at the dump level "/full/sunday2/monday". And the person running it (the issuer, hi bestie 👋) places the necessary tapes in the device with port offset 5.

% backup dump -volumeset user -dump /full/sunday2/monday -portoffset 5
Preparing to dump the following volumes:
user.jones.backup   387623900
user.pat.backup     486219245
user.smith.backup   597315841
       .                .
       .                .
Starting dump.

See how it lists every single volume it's about to touch? That's the vibe check before anything gets written. No surprises. 👑

🦋 Just peeking, not dumping (dry run era)

The following command displays the list of volumes to be dumped when the user dumps the "sys_sun" volume set at the "/full" dump level.

% backup dump -volumeset sys_sun -dump /full -dryrun
Starting dump of volume set 'sys_sun' (dump set '/full')
Total number of volumes: 24
Would have dumped the following volumes:
sun4x_56      124857238
sun4x_56.bin  124857241
    .            .
    .            .
sun4x_55      124857997
    .            .
    .            .

The -dryrun flag is literally the "would have" flag. It tells you exactly what would have happened, and then does nothing. Perfect for when you're not ready to commit. 💀 We love a low-stakes preview.

✨ Scheduling it for later because we are not staying up for this

The following command schedules a dump of the volumes in the volume set "user" at the dump level "/sunday2/monday1" for 11:00 p.m. on 14 June 1999.

The appropriate Tape Coordinator has port offset 0 (zero), so that argument is omitted. Yes bestie, zero is the default, so you can just... not type it. Self-care. 🫶

% backup dump -volumeset user -dump /sunday2/monday1 -at 06/14/1999 23:00

Notice the date and time are two separate arguments after -at, and the time is in 24-hour format. 23:00 is 11:00 p.m. Twenty-three hundred hours. Night owl behavior. 🌙

👑 PRIVILEGE REQUIRED 👑

Gather round, this part matters and I need you to actually read it, fr fr. ⭐

The issuer 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
  • on every file server machine that houses an affected volume.

That's every. single. one. No picking and choosing, no "well I added myself on the one I care about." All of them. Periodt. 💅

🫶 Tiny plot twist though: if the -localauth flag is included, the issuer must instead be logged on to a server machine as the local superuser "root". Different path, same energy.

🌈 SEE ALSO 🌈

The squad, the crew, the ones you'll be reading next. Go give them a little love:

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 and that's the whole page bestie, you made it to the end, I'm so proud of you 🥹💖 This one's from OpenAFS, dated 2026-07-27, and it's the man page for BACKUP_DUMP(8). Go forth and dump responsibly. No cap. 💅✨🎀🦋

📦 where this page comes from