BACKUP_SCANTAPE(8)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

👑 BACKUP_SCANTAPE(8) — AFS Command Reference 🎀

okay bestie, sit down, hydrate, because we're about to talk about backup_scantape and honestly?? it's giving tape forensics. this is the glow-up of the classic AFS reference page, no cap. 💖

✨ NAME ✨

backup_scantape — Extracts dump information from a tape 🦋

🌸 SYNOPSIS 🌸

backup scantape [-dbadd] [-portoffset <TC port offset>]
    [-localauth] [-cell <cell name>] [-help]

backup sc [-d] [-p <TC port offset>] [-l]
    [-c <cell name>] [-h]

💅 DESCRIPTION 💅

so basically, the backup scantape command pulls information out of the dump labels and volume headers that live on the tape sitting in the device controlled by the Tape Coordinator you point at with the -portoffset argument. and the Tape Coordinator is so not a gatekeeper about it — it shows you the info for each volume in its window the second it extracts it, instead of making you wait until the whole entire tape has been scanned. main character behavior, lowkey. ✨

(okay so, tiny plot twist 🎀: if the "FILE YES" instruction appears in the /var/lib/openafs/backup/CFG_device_name file associated with the specified port offset, then backup scantape extracts dump information from the backup data file named in that port offset's entry in the /var/lib/openafs/backup/tapeconfig file on the Tape Coordinator machine, instead of from a tape. so like... not a tape. for the sake of clarity, everything below keeps saying "tape", but the Backup System handles backup data files in much the same way. iykyk.)

if you hand over the -dbadd flag, backup scantape creates new dump and volume records in the Backup Database for all the scanned info. BUT — and this is the part where it gets dramatic 💀 — if it finds that a record already exists in the database for the same dump, it just terminates the scanning operation. no second chances, periodt.

the scanning operation only works on tapes that contain volume data. the command fails with an error message if the tape contains a copy of the Backup Database — like, if it was created with the backup savedb command, or if it has the AFS tape name "Ubik_db_dump.1". so don't even try it. 🙈

the Tape Coordinator's default response to this command is to access the tape by invoking the "MOUNT" instruction in the 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 little twist 😌—if the "AUTOQUERY NO" instruction appears in the CFG_device_name file, or if whoever issued the butc command included the -noautoquery flag, then the Tape Coordinator instead expects the tape to already be in the device. if it's not, the Tape Coordinator invokes the "MOUNT" instruction or prompts the operator. it's consistent, bestie. 🫶

to terminate a tape scanning operation in interactive mode, issue the backup kill command. in noninteractive mode? the only choice is to use a termination signal such as Ctrl+C to halt the Tape Coordinator completely. not me having to nuke the whole coordinator just to stop a scan 😭

⚠️ CAUTIONS ⚠️

a scanning operation does not have to begin with the first tape in a dump set — but the Backup System can only process tapes in sequential order after the initial tape provided. the Tape Coordinator automatically requests any subsequent tapes by invoking the "MOUNT" instruction in the local /var/lib/openafs/backup/CFG_device_name file, or by prompting the operator if there's no "MOUNT" instruction. so you can start wherever, but you can't hop around. vibe check passed. 🌈

The Tape Coordinator's success in scanning a tape that is corrupted or damaged depends on the extent of the damage and what type of data is corrupted. it can almost always scan the tape successfully up to the point of damage. if the damage is minor, the Tape Coordinator can usually skip over it and scan the rest of the tape, but more major damage can prevent further scanning. and because a scanning operation can start on any tape in a dump set, damage on one tape does not prevent scanning of the others in the dump set. However — it's possible to scan either the tapes that precede the damaged one or the ones that follow it, but not both. pick a lane, we can't have both. 💀

if a tape is relabeled with the backup labeltape command, it is not possible to recover data from it for the purposes of rebuilding the Backup Database. like, that data is gone-gone. 🪦

if the -dbadd flag is included on the command, it is best not to terminate the tape scanning operation before it completes (for example, by issuing the backup kill command in interactive mode). here's why 👑: the Backup System writes a new record in the Backup Database for each dump as soon as it scans the relevant info on the tape, so it possibly has already written new records. if the operator wants to rerun the scanning operation, they must locate and remove the records created during the terminated operation — because the second operation exits automatically if it finds that a record that it needs to create already exists. messy, but that's the deal. 🙈

if the -dbadd flag is included and the first tape provided is not the first tape in the dump set, the following restrictions apply:

  • If the first data on the tape is a continuation of a volume that begins on the previous (unscanned) tape in the dump set, the Backup System does not add a record for that volume to the Backup Database.
  • The Backup System must read the marker that indicates the start of an appended dump to add database records for the volumes in it. If the first volume on the tape belongs to an appended dump, but is not immediately preceded by the appended-dump marker, the Backup System does not create a Backup Database record for it or any subsequent volumes that belong to that appended dump.

🌟 OPTIONS 🌟

  • -dbadd — Adds the information extracted from the tape to the Backup Database (but only if the database does not already contain an entry with the same dump ID number). 💾
  • -portoffset <TC port offset> — Specifies the port offset number of the Tape Coordinator handling the tapes for this 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 💅

okay bestie, so every time there's a dump on a tape, backup scantape spills the tea in the Tape Coordinator window — it shows you the dump label and the volume header for every single volume in that dump. ✨

and listen, if a dump is so big it spreads across multiple tapes? the dump label does not repeat at the start of the following tapes. it said what it said once and that's that. 💀

a dump label has these fields, and they're literally the exact same ones you get from the backup readlabel command:

  • tape name — the permanent name assigned with the -pname argument of the backup labeltape command. this name stays on the tape forever until you use that argument again, no matter how many times the tape gets recycled or otherwise relabeled. and if the tape has no permanent name? you get "<NULL>" right there in the field. 🙈
  • AFS tape name — a tape name in one of these prescribed formats. the Backup System writes the appropriate AFS tape name onto the label automatically as part of a backup dump operation, or the operator can assign it themselves with the -name argument to the backup labeltape command.
    • volume_set_name.dump_level_name.tape_index — this is the one you get when the tape contains volume data. let's break it down, bestie: volume_set_name is the name of the volume set that was dumped to create the initial dump in the dump set this tape belongs to. dump_level_name is the last pathname element of the dump level at which that initial dump was backed up. and tape_index is the numerical position of the tape within the dump set. 🎀
    • "<NULL>" — this one shows up when the tape has no AFS tape name. that's normally the situation when the -name argument wasn't included the last time backup labeltape was used on this tape, and nothing's been written to it since. 🤷♀️
  • creationTime — the date and time when the Backup System started doing the dump operation that created the initial dump. ⏰
  • cell — the cell where the dump set was created. like, the cell whose Backup Database holds a record of the dump set. iconic location tag fr.
  • size — the tape's capacity in kilobytes as recorded on the label, NOT the amount of data actually sitting on the tape. this value comes from the -size argument to the backup labeltape command, or it's derived from the /var/lib/openafs/backup/tapeconfig file on the Tape Coordinator machine. it is not a measurement of the tape. no cap. 📏
  • dump path — the dump level of the initial dump in the dump set.
  • dump id — the dump ID number of the initial dump in the dump set, exactly as recorded in the Backup Database.
  • useCount — how many times a dump has been written to the tape, or how many times it's been relabeled. it's giving "how many times have we been here" energy.

and now the volume header has these fields, bestie:

  • volume name — the volume name, complete with a .backup or .readonly extension if that's appropriate. 🦋
  • volume ID — the volume's volume ID.
  • dumpSetName — the dump the volume belongs to. this dump name is of the form volume_set_name.dump_level_name, and it matches the name shown in the dump label. consistency queen. 👑
  • dumpID — the dump ID of the dump named in the "dumpSetName" field.
  • level — the depth in the dump hierarchy of the dump level used when creating the dump. here's the breakdown:
    • a value of 0 means a full dump.
    • a value of 1 or greater means an incremental dump made at that indicated depth in the hierarchy.
    • and important: the value reported is for the entire dump, not necessarily for the volume itself. for example, it's totally possible for a dump performed at an incremental level to include a full dump of an individual volume, if that volume got omitted from previous dumps. so don't come for it, it's just built different. 😭
  • parentID — the dump ID number of "dumpSetName"'s parent dump. it's 0 if the value in the "level" field is 0.
  • endTime — always 0. it's reserved for internal use, so mind your business bestie. 🙈
  • cloneDate — the date and time the volume was created. for a backup or read-only volume, this is the time it was cloned from its read/write source. for a read/write volume, it indicates the time at which the Backup System locked the volume for purposes of including it in the dump named in the "dumpSetName" field. 🔒

when you see the message Scantape: Finished? that's your girl telling you the output is done. periodt. ✅

so normally, the Backup System writes a marker to say a volume is the last one on a tape, or that the volume continues on the next tape. BUT — and this is the plot twist — if a backup operation terminated abnormally (like, say, the operator killed the Tape Coordinator with Ctrl+C mid-operation 😱), then there is no such marker. also, some very early versions of the Backup System just... didn't write these markers at all. rude. 💀

so if a tape doesn't conclude with one of the expected markers, the Tape Coordinator can't figure out whether there's a subsequent tape in the dump set, and it hits you with this in its window:

   Are there more tapes? (y/n)

and you just have to answer it. awkward but okay.

🌈 EXAMPLES 🌈

here's the output for the first two volumes on a tape in the device with port offset 0. no cap, this is exactly what it looks like:

% backup scantape
Dump label
----------
tape name = monthly_guest
AFS tape name = guests.monthly.3
creationTime =  Mon Feb  1 04:06:40 1999
cell = example.com
size = 2150000 Kbytes
dump path = /monthly
dump id = 917860000
useCount = 44
-- End of dump label --
-- volume --
volume name: user.guest10.backup
volume ID 1937573829
dumpSetName: guests.monthly
dumpID 917860000
level 0
parentID 0
endTime 0
clonedate Mon Feb  1 03:03:23 1999
-- volume --
volume name: user.guest11.backup
volume ID 1938519386
dumpSetName: guests.monthly
dumpID 917860000
level 0
parentID 0
endTime 0
clonedate Mon Feb  1 03:05:15 1999

🔐 PRIVILEGE REQUIRED 🔐

okay so who's allowed to do this? the issuer has to be listed in the /etc/openafs/server/UserList file on every machine where the Backup Server is running. OR — alternative route — they have to be logged onto a server machine as the local superuser root, but that only works if the -localauth flag is included. those are the rules bestie, no exceptions. 💅

👀 SEE ALSO 👀

butc(5), backup(8), backup_dump(8), backup_dumpinfo(8), butc(8)

go read those too, they're the supporting cast and they ate. 🫶

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. shoutout to the whole team fr fr. 💖

and that's the whole page, bestie!! 🎀 this was OpenAFS, dated 2026-07-27, and the page is BACKUP_SCANTAPE(8). you're now officially a scantape scholar. slay, go read some tapes. 💅✨🌸

📦 where this page comes from