TAPECONFIG(5)

✨ TAPECONFIG ✨

okay so first things first: bestie, this is the TAPECONFIG(5) page from the AFS File Reference family. Sit down, grab a boba, and let's talk about telling the Backup System what your tapes even are. 🎀

---

🌸 NAME 🌸

tapeconfig — it's giving "defines parameters for tape devices and backup data files." That's the whole gig. 💖

---

💅 DESCRIPTION 💅

So this tapeconfig file is where you define the basic config parameters for all the tape devices or backup data files that are available for backup operations on a Tape Coordinator machine. It's plain ASCII format, no frills, and it must live in the local /var/lib/openafs/backup directory. Like, it's not optional, that's just where it goes. 🫶

Every instruction for each tape device or backup data file gets its own line, and each line looks like this:

[<capacity> <filemark_size>] <device_name> <port_offset>

and here's what all of that actually means, one by one:

• <capacity> — this is the capacity of the tapes used with a tape device, OR the amount of data to write into a backup data file. Either way. The Tape Coordinator pulls this value out in exactly two situations:
  1. When the capacity field of a tape's or backup data file's label is empty (this happens when the tape has never been labeled, rip). The Tape Coordinator records this value on the label and uses it when figuring out how much data it can write to the tape or file during a backup dump or backup savedb operation. But — and this is the plot twist — if there's already a capacity value on the label, the Tape Coordinator uses that one instead. It does not care about your little field here. 💀
  1. When the -size argument is omitted the first time the backup labeltape command is used on a given tape or file. In that case the Tape Coordinator copies this value right into the label's capacity field. Slay.

So the Tape Coordinator uses this capacity value, or the one sitting on the Backup System tape label, to track how much space is left while it writes data to a tape or backup data file. The right value to record for a tape depends on the size of the tapes you usually use in the device and whether it has a compression mode. For suggested values, go read the OpenAFS Administration Guide chapter on configuring the Backup System — it has the numbers, I'm not making them up. And if you're using a value you got from the fms command, reduce it by 10% to 15% before you write it in the file. Important!

For a backup data file: it's best to give a value that helps the Tape Coordinator avoid hitting end-of-file (EOF) unexpectedly, because that's a bad time. Make it at least somewhat smaller than the amount of space available on the partition housing the file when the dump operation begins, and never larger than the maximum file size allowed by the operating system. Not negotiable.

Now the notation: specify a (positive) integer or decimal value followed by a letter that indicates units, with no intervening space. In a decimal number, the number of digits after the decimal point must not translate to fractions of bytes. The maximum acceptable value is 2048 GB (2 TB). The acceptable unit letters are:

• "k" or "K" for kilobytes (KB).
• "m" or "M" for megabytes (MB).
• "g" or "G" for gigabytes (GB).
• "t" or "T" for terabytes (TB).

And if the letter is omitted, the default is kilobytes. If this whole field is omitted, the Tape Coordinator just uses the maximum acceptable value, 2048 GB or 2 TB. Either leave both this field and the <filemark_size> field empty, or give a value in both of them. No half-and-half situations, bestie. 🙈

• <filemark_size> — this is the size of a tape device's filemarks (they're also called end-of-file marks, or EOF marks, iykyk), which is set by the device's manufacturer. During a dump to tape, the Tape Coordinator inserts filemarks at the boundary between the data from each volume, so this filemark size genuinely affects how much space is left over for actual data. That's real.

The right value to record for a tape depends on the size of the tapes usually used in the device and whether it has a compression mode. For suggested values, see the OpenAFS Administration Guide chapter on configuring the Backup System. And if you're using a value from the fms command, increase it by 10% to 15% before recording it in the file. (Yes, opposite direction from capacity. Don't mix them up, I'm begging. 😭)

For backup data files, record a value of 0 (zero). The Tape Coordinator actually ignores this field for backup data files anyway, because it doesn't use filemarks when writing to a file. So it's purely decorative, but write the zero, it's the vibe.

Use the same notation as for <capacity>, but heads up: the default units here is bytes, not kilobytes. The maximum acceptable value is 2048 GB.

If this field is empty, the Tape Coordinator uses the value 0 (zero). And again: either leave both this field and the <capacity> field empty, or provide a value in both. 🦋

• <device_name> — the complete pathname of the tape device or backup data file. The format of tape device names depends on the operating system, but on UNIX systems device names generally begin with the string /dev/. For a backup data file, this field defines the complete pathname. For a whole discussion of suggested naming conventions, go see the description of the "FILE" instruction in butc(5).
• <port_offset> — the port offset number associated with this exact combination of Tape Coordinator and tape device or backup data file.

Acceptable values are the integers 0 through 58510. (The Backup System can track a maximum of 58,511 port offset numbers — that's the ceiling, periodt.) Each value must be unique among the cell's Tape Coordinators, but any number of them can be associated with a single machine. Port offset numbers don't need to be assigned sequentially, and they can appear in any order in the tapeconfig file. Assign port offset 0 to the Tape Coordinator for the tape device or backup data file used most often for backup operations — doing that lets the operator omit the -portoffset argument from the largest possible number of backup commands, which is a genuine quality-of-life slay. 👑

---

🔐 PRIVILEGE REQUIRED 🔐

Creating the file requires UNIX "w" (write) and "x" (execute) permissions on the /var/lib/openafs/backup directory. Editing the file requires UNIX "w" (write) permission on the file itself. So like, you need actual permissions, you can't just manifest it. ✨

---

🍓 EXAMPLES 🍓

Okay here's the moment. The following example tapeconfig file configures three tape devices and a backup data file. Let's break down the drama:

The first device has device name /dev/rmt/0h, and it's assigned port offset 0 because it's going to be the most frequently used device for all backup operations in the cell. Its default tape capacity is 2 GB and filemark size is 1 MB.

The /dev/rmt/3h drive has half the capacity but a much smaller filemark size; its port offset is 3.

The third device listed, /dev/rmt/4h, has the same capacity and filemark size as the first device, and is assigned port offset 2.

Port offset 4 is assigned to the backup data file /dev/FILE, which is actually a symbolic link to the actual file located elsewhere on the local disk. The Tape Coordinator writes up to 1.5 GB into the file; and as recommended, the filemark size is set to zero.

2G 1M /dev/rmt/0h 0
1g 4k /dev/rmt/3h 3
2G 1m /dev/rmt/4h 2
1.5G 0 /dev/FILE 4

Look at that. Immaculate. 🌈

---

👀 SEE ALSO 👀

backup_addhost(8), backup_dump(8), backup_labeltape(8), backup_savedb(8), butc(8), fms(8)

Go read those too, bestie, they're all connected. 💜

---

©️ COPYRIGHT ©️

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, mwah 💋 — this little love letter to tape configs is brought to you by OpenAFS, dated 2026-07-27, and it lives at TAPECONFIG(5). go label your tapes, you absolute icon 🎀✨