BACKUP_READLABEL(8)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💖 backup_readlabel — AFS Command Reference 💖

okay bestie, sit DOWN. this is backup_readlabel from the AFS Command Reference, and it's literally the "what's on this tape tho" command. let's go 🎀

✨ NAME ✨

backup_readlabel — reads and displays a tape's label. that's it. that's the whole job. she does one thing and she slays it 💅

🌸 SYNOPSIS 🌸

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

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

🦋 DESCRIPTION 🦋

so like. the backup readlabel command pulls up the info off a magnetic tape's label and shows it to you. what's in there? the tape's name (either a permanent name, or an AFS tape name that describes what's actually on the tape, in a very specific prescribed format) and its capacity. that's the tea ☕

now here's the plot twist: if the "FILE YES" instruction shows up in the /var/lib/openafs/backup/CFG_device_name file that's tied to the port offset you specified, then backup readlabel does not read from the start of a tape. nope. instead it reads the label info out of the first 16 KB block in the backup data file listed for that port offset in the Tape Coordinator's /var/lib/openafs/backup/tapeconfig file. iconique behavior, honestly.

and now the Tape Coordinator's default response to this command: it accesses the tape by invoking the "MOUNT" instruction in the local /var/lib/openafs/backup/CFG_device_name file — or, if there's no "MOUNT" instruction, it just prompts the backup operator to insert the tape. classic. BUT. if the "AUTOQUERY NO" instruction is hanging out in that CFG_device_name file, or if whoever ran the butc command threw in the -noautoquery flag, then the Tape Coordinator flips the script and expects the tape to already be in the device. if it's not? it goes right back to invoking the "MOUNT" instruction or prompting the operator. no cap 🫶

✨ OPTIONS ✨

  • -portoffset <TC port offset> — tells you the port offset number of the Tape Coordinator that's handling the tapes for this operation. that's the whole vibe.
  • -localauth — builds a server ticket using a key from the local /etc/openafs/server/KeyFile file. then the backup command interpreter shows it off to the Backup Server, Volume Server and VL Server during mutual authentication. 🎀 do NOT combine this flag with the -cell argument, i'm serious. for more deets, go read backup(8).
  • -cell <cell name> — names the cell where you wanna run the command. do NOT combine this argument with the -localauth flag. same deal, more details in backup(8).
  • -help — prints the online help for this command. and listen, every other valid option just gets ignored when you use this. they said "one at a time, bestie."

🌈 OUTPUT 🌈

the output shows up in two places: the shell window where you issued the command, AND the Tape Coordinator window. double the slay, double the drama ✨

if the tape is unlabeled, or if the tape device you specified is just... empty (💀), the output reads:

Failed to read tape label.

otherwise? the output in the shell window has this exact format:

Tape read was labelled: <tape name> (<dump id>)
     size: <size> Kbytes

where <tape name> is the permanent name if the tape has one, and the AFS tape name if it doesn't. the <dump ID> is the dump ID of the initial dump on the tape, and <size> is the recorded capacity of the tape in kilobytes. periodt.

meanwhile the output in the Tape Coordinator windows is wrapped up top by an underlined "Tape label" header, and at the bottom by this string:

-- End of tape label --

and in between? lines reporting all of this:

  • tape name — the permanent name that got assigned by using the -pname argument of the backup labeltape command. this name stays on the tape until that argument gets used again — no matter how many times the tape is recycled or otherwise relabeled. and if the tape has no permanent name? the value <NULL> shows up in this field. yeah. <NULL>. we've all been there 🥲
  • AFS tape name — a tape name in one of these prescribed formats. the Backup System automatically writes the appropriate AFS tape name onto the label as part of a backup dump or backup savedb operation, or the operator can assign it with the -name argument to the backup labeltape command.
    • volume_set_name.dump_level_name.tape_index, if the tape contains volume data. volume_set_name is the name of the volume set that got dumped to create the initial dump in the dump set that this tape belongs to; dump_level_name is the last pathname element of the dump level at which the initial dump was backed up; and tape_index is the numerical position of the tape in the dump set.
    • "Ubik.db.dump."tape_index if the tape contains a dump of the Backup Database, created with the backup savedb command. tape_index is the ordinal of the tape in the dump set.
    • "<NULL>" if the tape has no AFS tape name. this is normally the case if the -name argument wasn't included the last time the backup labeltape command was used on this tape, and no data has been written to it since. 🫠
  • creationTime — the date and time the Backup System started performing the dump operation that created the initial dump.
  • cell — the cell where the dump set was created. this is the cell whose Backup Database contains a record of the dump set.
  • size — the tape's capacity (in kilobytes) as recorded on the label — not the amount of data actually on the tape. this value is assigned by the -size argument to the backup labeltape command, or derived from the /var/lib/openafs/backup/tapeconfig file on the Tape Coordinator machine. it is not a measurement of the tape. no measuring tape was harmed. 📏
  • 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, as recorded in the Backup Database.
  • useCount — the number of times a dump has been written to the tape, or the number of times it's been relabeled.

and the message "ReadLabel: Finished" is what tells you the output is done. bye bestie 👋

💜 EXAMPLES 💜

here's the example for the tape with permanent name "oct.guest.dump" and capacity 2 MB, expressed in kilobyte units (where 2097152 equals 2 times 10242):

% backup readlabel -portoffset 6
Tape read was labelled: oct.guest.dump (907215000)
     size: 2097152 Kbytes

and the output in the Tape Coordinator window reads:

Tape label
----------
tape name = oct.guest.dump
AFS tape name = guests.monthly.3
creationTime = Thu Oct 1 00:10:00 1998
cell = example.com
size = 2097152 Kbytes
dump path = /monthly
dump id = 907215000
useCount = 5
---- End of tape label ----

and this next example is for a tape that doesn't have a permanent tape:

% backup readlabel -portoffset 6
Tape read was labelled: guests.monthly.2 (909899900)
     size: 2097152 Kbytes

and the output in the Tape Coordinator window reads:

Tape label
----------
tape name = <NULL>
AFS tape name = guests.monthly.2
creationTime = Sun Nov 1 00:58:20 1998
cell = example.com
size = 2097152 Kbytes
dump path = /monthly
dump id = 909899900
useCount = 1
---- End of tape label ----

👑 PRIVILEGE REQUIRED 👑

the person issuing this command has to be listed in the /etc/openafs/server/UserList file on every machine where the Backup Server is running. OR — plot twist — they have to be logged onto a server machine as the local superuser "root" if the -localauth flag is included. so like, either you're on the list or you're root. those are the options, bestie. ✨

🌟 SEE ALSO 🌟

butc(5), backup(8), backup_labeltape(8), butc(8)

go read them. iykyk 📚

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 the whole page, bestie!! this one came from OpenAFS, dated 2026-07-27 — and it's the BACKUP_READLABEL(8) manual, so now you know exactly what's on that tape. go forth and read labels 🦋💖✨

📦 where this page comes from