BUTC(5)

🌈 BUTC(5) — AFS File Reference 🌈

okay bestie, grab a snack because we're getting into butc, the Tape Coordinator situation, and it's actually so good when you know what's going on 💖

✨ NAME ✨

butc — defines Tape Coordinator instructions for automated tape devices 🎀

---

🦋 DESCRIPTION 🦋

so the CFG_device_name file is where you put the instructions that configure a Tape Coordinator (butc) for use with automated backup devices like tape stackers and jukeboxes ✨ it also lets the Tape Coordinator dump and restore data to a backup data file on a local disk device, and lets you automate a bunch of other backup-process stuff too. iconic behavior, honestly.

there's a separate configuration file for each tape device or backup data file 💅 creating the file is optional — and genuinely unnecessary if none of the instructions it can include pertain to a given tape device. the file is ASCII-format and it must live in the /var/lib/openafs/backup directory on the Tape Coordinator machine, if it exists at all.

🫶 heads up: the CFG_device_name file does not replace the /var/lib/openafs/backup/tapeconfig file. a single copy of that one still has to exist on every Tape Coordinator machine. no skipping it, bestie.

to let the Tape Coordinator find the configuration file, you build the variable part of the filename, device_name, like this:

• for a tape device: strip off the initial "/dev/" string from the device name, and replace any other slashes in the name with underscores. for example, CFG_rmt_4m is the right filename for a device called /dev/rmt/4m 🌸
• for a backup data file: strip off the initial slash ("/") and replace any other slashes in the name with underscores. for example, CFG_var_tmp_FILE is the right filename for a backup data file called /var/tmp/FILE 🌸

the CFG_device_name file lists one or more of the following instructions, each on its own line 👑 all of them are optional, and they can appear in any order. here's the quick rundown, and then the full deep-dive on each one right after:

• ASK — controls whether the Tape Coordinator prompts for guidance when it hits error conditions.
• AUTOQUERY — controls whether the Tape Coordinator prompts for the first tape.
• BUFFERSIZE — sets the size of the memory buffer the Tape Coordinator uses when transferring data.
• FILE — controls whether the dump is written to a tape device or a file.
• MOUNT — identifies the file that contains routines for inserting tapes into the device's drive.
• NAME_CHECK — controls whether the Tape Coordinator verifies that a tape's AFS tape name matches the dump being written.
• UNMOUNT — identifies the file that contains routines for removing tapes from the device's drive.

---

💅 The ASK Instruction 💅

the ASK instruction takes a boolean value as its argument, in this exact format:

ASK (YES | NO)

when the value is YES, the Tape Coordinator pops a prompt in its window asking for a response to the error cases listed below 👇 and ngl, this is the default behavior if the ASK instruction doesn't appear in the CFG_device_name file.

when the value is NO, the Tape Coordinator does not prompt in error cases — it just uses the automatic default responses described below. it also logs the error in the TE_device_name file 📝 suppressing the prompts is what lets the Tape Coordinator run unattended, though it still prompts for insertion of tapes unless the MOUNT instruction is used.

the error cases this instruction controls are:

• the Backup System can't dump a volume while running the backup dump command. with a YES value, the Tape Coordinator prompts and offers three choices: try to dump the volume again immediately, omit the volume from the dump but continue the operation, or terminate the operation. with a NO value, the Tape Coordinator omits the volume from the dump and continues the operation.
• the Backup System can't restore a volume while running the backup diskrestore, backup volrestore, or backup volsetrestore command. with a YES value, the Tape Coordinator prompts and offers two choices: omit the volume and continue restoring the other volumes, or terminate the operation. with a NO value, it just continues the operation without prompting, omitting the problematic volume but restoring the remaining ones.
• the Backup System can't determine if the dump set includes any more tapes, while running the backup scantape command (the reference page for that command discusses possible reasons for this problem). with a YES value, the Tape Coordinator prompts to ask if there are more tapes to scan. with a NO value, it proceeds as though there are more tapes and invokes the routine named by the MOUNT instruction in the configuration file, or prompts the operator to insert the next tape.
• the Backup System determines that the tape contains an unexpired dump while running the backup labeltape command. with a YES value, the Tape Coordinator prompts and offers two choices: continue or terminate the labeling operation. with a NO value, it terminates the operation without relabeling the tape.

---

🎀 The AUTOQUERY Instruction 🎀

the AUTOQUERY instruction takes a boolean value as its argument, in this format:

AUTOQUERY (YES | NO)

when the value is YES, the Tape Coordinator checks for the MOUNT instruction in the configuration file whenever it needs to read the first tape involved in an operation. as described for that instruction, it then either prompts for the tape or invokes the specified routine to mount it ✨ this is the default behavior if the AUTOQUERY instruction doesn't appear in the configuration file.

when the value is NO, the Tape Coordinator assumes the first tape required for an operation is already in the drive. it does not prompt the operator or invoke the MOUNT routine unless there's an error accessing that first tape. this setting is equivalent in effect to including the -noautoquery flag to the butc command 💅

⭐ note that the AUTOQUERY instruction's setting controls the Tape Coordinator's behavior only with respect to the first tape required for an operation. for subsequent tapes, the Tape Coordinator always checks for the MOUNT instruction. it also refers to the MOUNT instruction if it runs into an error while trying to access the first tape.

---

🍓 The BUFFERSIZE Instruction 🍓

the BUFFERSIZE instruction takes an integer value, and optionally units, in this format:

BUFFERSIZE <size>[(k | K | m | M | g | G)]

where <size> specifies the amount of memory the Tape Coordinator allocates to use as a buffer during both dump and restore operations. the default unit is bytes, but use k or K for kilobytes, m or M for megabytes, and g or G for gigabytes. and listen — there is no space between the <size> value and the units letter 🫶

by default, the Tape Coordinator uses a 16 KB buffer during dump operations. as it receives volume data from the Volume Server, it gathers 16 KB of data in the buffer before transferring the entire 16 KB to the tape device or backup data file. same energy on a restore: by default the Tape Coordinator buffers 32 KB of data from the tape device or backup data file before transferring the entire 32 KB to the Volume Server for restoration into the file system. buffering makes the flow of data to and from a tape device more even, which promotes tape streaming — the most efficient way for a tape device to operate 🔥

in a normal network configuration, the default buffer sizes are usually big enough to promote tape streaming. if the network between the Tape Coordinator machine and file server machines is slow, bumping up the buffer size can help 💜

---

🌸 The FILE Instruction 🌸

the FILE instruction takes a boolean value as its argument, in this format:

FILE (NO | YES)

when the value is NO, the Tape Coordinator writes to a tape device during a dump operation and reads from one during a restore operation. this is the default behavior if the FILE instruction doesn't appear in the configuration file.

when the value is YES, the Tape Coordinator writes volume data to a backup data file on the local disk during a dump operation, and reads volume data from a file during a restore operation. if the file doesn't exist when the Tape Coordinator tries to access it to write a dump, the Tape Coordinator creates it ✨ but for a restore operation to actually succeed, the file must exist and must contain volume data previously written to it by a backup dump operation.

when the value is YES, the backup data file's complete pathname must appear — instead of a tape drive device name — in the third field of the corresponding port offset entry in the local /var/lib/openafs/backup/tapeconfig file. if that field refers to a tape device instead, dump operations look like they succeed but are inoperative 😭 and it is not possible to restore data that was accidentally dumped to a tape device while the FILE instruction was set to YES. (same deal in reverse: if the FILE instruction is set to NO, the tapeconfig entry has to refer to an actual tape device.)

💀 okay but here's the thing — rather than putting an actual file pathname in the third field of the tapeconfig file, the recommended configuration is to create a symbolic link in the /dev directory that points to the actual file pathname, and record the symbolic link in that field. this has a couple of advantages:

• it makes the device_name portion of the CFG_device_name, TE_device_name, and TL_device_name names as short as possible. because the symbolic link is in the /dev directory as though it were a tape device, the device configuration file's name is constructed by stripping off the entire /dev/ prefix, instead of just the initial slash. if, for example, the symbolic link is called /dev/FILE, the device configuration file name is CFG_FILE — whereas if the actual pathname /var/tmp/FILE appears in the tapeconfig file, the file's name has to be CFG_var_tmp_FILE 👑
• it provides for a more graceful, and potentially automated, recovery if the Tape Coordinator can't write a complete dump into the backup data file (because the partition housing the backup data file becomes full, for example). the Tape Coordinator's reaction to this problem is to invoke the MOUNT script, or to prompt the operator if the MOUNT instruction does not appear in the configuration file.
  • if there is a MOUNT routine, the operator can prepare for this situation by adding a subroutine that changes the symbolic link to point to another backup data file on a partition where there is space available.
• If there's no MOUNT instruction in play, the prompt lets the operator manually repoint the symbolic link at another backup data file, then hit Return — and that is the "go ahead bestie" signal that tells the Tape Coordinator to pick the operation back up. 💫

Okay so, real talk: if the third field in the tapeconfig file names the actual file, there is genuinely no way to recover from running out of space on the partition that houses the backup data file. And you cannot edit the tapeconfig file in the middle of an operation. Not a thing. 🙈

When it's writing out to a backup data file, the Tape Coordinator writes data at 16 KB offsets. If some block of data — say a marker that signals the beginning or end of a volume — doesn't fill up the whole entire 16 KB, the Tape Coordinator still hops to the next offset before writing the next block. So in the output of a backup dumpinfo command run with the -id option, the value in the "Pos" column is the ordinal of the 16-KB offset where the volume data begins. Which means it's generally not just one higher than the position number on the line above it — unlike for dumps to tape, where it is. Ik it's weird, it's fine, it's just how it is. 🦋

---

🎬 The MOUNT Instruction 🎬

The MOUNT instruction takes a pathname as its argument, in this exact format:

MOUNT <filename>

The executable file it points at has to live on the local disk, and it has to contain a shell script or program that tells an automated tape device — think jukebox or stacker — to mount a tape (i.e. insert it into the tape reader). 🎀

You (the operator) have to write that routine yourself, calling whatever mount command the device's manufacturer specified. AFS ships zero scripts for this. None. Zip. (There is an example over in "EXAMPLES" though, so peek there.) The script or program inherits the Tape Coordinator's AFS authentication status.

So when the Tape Coordinator needs a tape mounted, it goes and checks the configuration file for a MOUNT instruction:

• No MOUNT instruction? The Tape Coordinator prompts the operator to insert a tape before it even tries to open the tape device.
• There is one? The Tape Coordinator executes the routine in the referenced file. That routine inherits the local identity (UNIX UID) and the AFS tokens of whoever issued the butc command.

There's one exception to that whole sequence though. If the AUTOQUERY NO instruction shows up in the configuration file, or the -noautoquery flag was on the butc command, then the Tape Coordinator just assumes the operator already inserted the first tape needed for the operation. It goes straight to reading the tape, and only checks for the MOUNT instruction or prompts the operator if the tape is missing or isn't the one it needed. Main character energy: it just assumes. 👑

When the Tape Coordinator does invoke the routine named by the MOUNT instruction, it passes these parameters to it, in this order:

• The tape device or backup data file's pathname, as recorded in the /var/lib/openafs/backup/tapeconfig file.
• The tape operation, which — apart from the exceptions in the list right below — matches the backup command operation code that kicked off the operation:
  • appenddump (when a backup dump command includes the -append flag).
  • dump (when a backup dump command does not include the -append flag).
  • labeltape
  • readlabel
  • restore (for a backup diskrestore, backup volrestore, or backup volsetrestore command).
  • restoredb
  • savedb
  • scantape
• The number of times the Tape Coordinator has attempted to open the tape device or backup data file. If that open attempt returns an error, the Tape Coordinator bumps this value by one and invokes the MOUNT instruction all over again. 😭
• The tape name. For some operations the Tape Coordinator passes the string none, because it doesn't know the tape name (running backup scantape or backup readlabel, for example), or because the tape doesn't necessarily have a name (running backup labeltape, for example).
• The tape ID recorded in the Backup Database. Same energy as the tape name: the Backup System passes the string none for operations where it doesn't know the tape ID, or where the tape doesn't necessarily have an ID.

The routine invoked by the MOUNT instruction has to hand an exit code back to the Tape Coordinator:

• Code 0 (zero) means the routine successfully mounted the tape. The Tape Coordinator continues the backup operation. 🔥 And heads up — if the routine doesn't return this exit code, the Tape Coordinator never calls the UNMOUNT instruction.
• Code 1 (one) means the routine failed to mount the tape. The Tape Coordinator terminates the operation. 💀
• Any other code means the routine couldn't access the correct tape. The Tape Coordinator prompts the operator to insert the correct tape.

One more thing: if the backup command was issued in interactive mode and the operator fires off the backup kill command while the MOUNT routine is still running, the Tape Coordinator passes the termination signal along to the routine, and the entire operation terminates. Periodt. ✋

🕵️ The NAME_CHECK Instruction 🕵️

The NAME_CHECK instruction takes a boolean value as its argument, in this format:

NAME_CHECK (YES | NO)

When the value is YES and the tape doesn't have a permanent name, the Tape Coordinator checks the AFS tape name while dumping a volume in response to the backup dump command. That AFS tape name has to be "<NULL>" or match the tape name that the backup dump operation assigns based on the volume set and dump level names. And fun fact: this is the default behavior if the NAME_CHECK instruction does not appear in the configuration file. ✨

When the value is NO, the Tape Coordinator does not check the AFS tape name before writing to the tape.

And always, no matter what: the Tape Coordinator checks that all dumps on the tape are expired, and it outright refuses to write to a tape that contains unexpired dumps. It said no. 💅

🧚 The UNMOUNT Instruction 🧚

The UNMOUNT instruction takes a pathname as its argument, in this format:

UNMOUNT <filename>

Same deal as MOUNT — the referenced executable file has to live on the local disk and contain a shell script or program that directs an automated tape device, like a jukebox or a stacker, to unmount a tape (take it out of the tape reader). You write the routine that calls the unmount command the device's manufacturer specified. AFS does not include any scripts, though there's an example in "EXAMPLES". The script or program inherits the Tape Coordinator's AFS authentication status. 🎀

So after closing a tape device, the Tape Coordinator checks the configuration file for an UNMOUNT instruction — and it does this whether or not the close operation succeeded. If there's no UNMOUNT instruction, the Tape Coordinator does nothing at all, which means the operator has to physically do whatever it takes to remove the current tape from the drive before another one can go in. If there is an UNMOUNT instruction, the Tape Coordinator executes the referenced file.

It invokes that routine exactly once, passing in these parameters:

• The tape device pathname (as specified in the /var/lib/openafs/backup/tapeconfig file).
• The tape operation (always unmount).

---

💖 PRIVILEGE REQUIRED 💖

This file is protected by UNIX mode bits, bestie. 🫶

• Creating the file needs the "w" (write) and "x" (execute) permissions on the /var/lib/openafs/backup directory.
• Editing the file needs the "w" (write) permission on the file itself.

💖 EXAMPLES 💖

okay bestie so these example config files are here to show you one way to structure a config file for a stacker or a backup dump file. but literally do not just copy-paste them into your cell and call it a day — they're not necessarily appropriate for every specific cell, so if you're using them as models, adapt them to what your cell actually needs and what equipment you've got. periodt.

🌸 Example CFG_device_name File for Stackers 🌸

in this example, the administrator creates the following entry for a tape stacker called stacker0.1 in the /var/lib/openafs/backup/tapeconfig file. it has port offset 0.

2G   5K   /dev/stacker0.1   0

then the administrator includes these five lines in the /var/lib/openafs/backup/CFG_stacker0.1 file. if you wanna review what each instruction means, go back up to "DESCRIPTION" bestie 🫶

MOUNT /var/lib/openafs/backup/stacker0.1
UNMOUNT /var/lib/openafs/backup/stacker0.1
AUTOQUERY NO
ASK NO
NAME_CHECK NO

and finally, the administrator writes the following executable routine in the /var/lib/openafs/backup/stacker0.1 file — the one referenced by the MOUNT and UNMOUNT instructions in the CFG_stacker0.1 file.

#! /bin/csh -f

set devicefile = $1
set operation = $2
set tries = $3
set tapename = $4
set tapeid = $5

set exit_continue = 0
set exit_abort = 1
set exit_interactive = 2

#--------------------------------------------

if (${tries} > 1) then
   echo "Too many tries"
   exit ${exit_interactive}
endif

if (${operation} == "unmount") then
   echo "UnMount: Will leave tape in drive"
   exit ${exit_continue}
endif

if ((${operation} == "dump")     |\
    (${operation} == "appenddump")     |\
    (${operation} == "savedb"))  then

    stackerCmd_NextTape ${devicefile}
    if (${status} != 0)exit${exit_interactive}
    echo "Will continue"
    exit ${exit_continue}
endif

if ((${operation} == "labeltape")    |\
    (${operation} == "readlabel")) then
   echo "Will continue"
   exit ${exit_continue}
endif

echo "Prompt for tape"
exit ${exit_interactive}

so this routine uses two of the parameters the Backup System hands it: tries and operation. it follows the recommended practice of prompting for a tape if the value of the tries parameter exceeds one — because that means the stacker is out of tapes, lowkey a whole situation 😭

for a backup dump or backup savedb operation, the routine calls the example stackerCmd_NextTape function that the stacker's manufacturer provides. note that the final lines in the file return the exit code that prompts the operator to insert a tape — these lines get invoked when either the stacker can't load a tape, or the operation being performed isn't one of those explicitly mentioned in the file (like a restore operation, fr fr).

🦋 Example CFG_device_name File for Dumping to a Data File 🦋

in this example, the administrator creates the following entry for a backup data file called HSM_device in the /var/lib/openafs/backup/tapeconfig file. it has port offset 20.

1G   0K   /dev/HSM_device   20

the administrator includes these lines in the /var/lib/openafs/backup/CFG_HSM_device file. wanna know what each instruction means? "DESCRIPTION" has you covered, bestie 💅

MOUNT /var/lib/openafs/backup/file
FILE YES
ASK NO

and finally, the administrator writes the following executable routine in the /var/lib/openafs/backup/file file — the one referenced by the MOUNT instruction in the CFG_HSM_device file — to control how the Tape Coordinator handles the file.

#! /bin/csh -f
set devicefile = $1
set operation = $2
set tries = $3
set tapename = $4
set tapeid = $5

set exit_continue = 0
set exit_abort = 1
set exit_interactive = 2

#--------------------------------------------

if (${tries} > 1) then
   echo "Too many tries"
   exit ${exit_interactive}
endif

if (${operation} == "labeltape") then
   echo "Won't label a tape/file"
   exit ${exit_abort}
endif

if ((${operation} == "dump")   |\
    (${operation} == "appenddump")   |\
    (${operation} == "restore")   |\
    (${operation} == "savedb")    |\
    (${operation} == "restoredb")) then

   /bin/rm -f ${devicefile}
   /bin/ln -s /hsm/${tapename}_${tapeid} ${devicefile}
   if (${status} != 0) exit ${exit_abort}
endif

exit ${exit_continue}

just like the example routine for a tape stacker, this one uses the tries and operation parameters the Backup System passes to it. the tries parameter tracks how many times the Tape Coordinator has tried to access the file. a value greater than one means the Tape Coordinator cannot access it, and the routine returns exit code 2 (exit_interactive), which results in a prompt for the operator to load a tape. and the operator can use that moment to change the name of the backup data file specified in the tapeconfig file. slay, a second chance ✨

the main character of this routine, its primary function, is to establish a link between the device file and the file to be dumped or restored. when the Tape Coordinator is executing a backup dump, backup restore, backup savedb, or backup restoredb operation, the routine invokes the UNIX ln -s command to create a symbolic link from the backup data file named in the tapeconfig file to the actual file to use (and yes, that's the recommended method 🫶). it uses the value of the tapename and tapeid parameters to construct the file name.

---

👀 SEE ALSO 👀

tapeconfig(5), backup_diskrestore(8), backup_dump(8), backup_restoredb(8), backup_savedb(8), backup_volrestore(8), backup_volsetrestore(8)

---

📜 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, bestie!! 🎀 this beauty is OpenAFS, dated 2026-07-27, and it lives under the name BUTC(5) — go forth and stack those tapes, you absolute icon 👑 💜