BUTC(8)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💖 butc — like, the Tape Coordinator origin story 💖

okay so bestie, we're in the butc(8) page from the AFS Command Reference, and honestly? this one's a whole vibe. let's go 🎀

✨ NAME ✨

butc — Initializes the Tape Coordinator process 🦋

🌸 SYNOPSIS 🌸

butc [-port <port offset>] [-debuglevel (0 | 1 | 2)]
    [-cell <cell name>] [-noautoquery] [-rxbind] [-localauth]
    [-auditlog <file | sysvmq> [-audit-interface <interface>]]
    [-allow_unauthenticated] [-help]

butc [-p <port offset>] [-d (0 | 1 | 2)]
    [-c <cell name>] [-n] [-r] [-l]
    [-auditl <file | sysvmq> [--audit-i <interface>]]
    [-al] [-h]

💅 DESCRIPTION 💅

So. The butc command initializes a Tape Coordinator process on a Tape Coordinator machine. What that actually means: it lets an operator point Backup System requests at the associated tape device or backup data file. 👑

cute lil parenthesis moment: the Tape Coordinator actually controls a backup data file if the "FILE YES" instruction shows up in the /var/lib/openafs/backup/CFG_device_name file matching that Tape Coordinator's entry in the /var/lib/openafs/backup/tapeconfig file. For simplicity's sake, the rest of this page just talks about tape devices only. periodt. 💖

It's conventional to start and run the Tape Coordinator in the foreground. In that case it runs on its own connection — that connection isn't available for anything else, and it has to stay open the entire time the Tape Coordinator is supposed to accept backup requests and while it's executing them. (If you're using a window manager, that connection = a separate command shell window. 🪟)

The Tape Coordinator can run in the background if the CFG_device_name file is configured so that the Tape Coordinator never needs to prompt the operator. Either way — foreground or background — it writes operation traces and other output to the standard output stream on the connection it was started over. Use the -debuglevel argument to control how much info shows up. ✨

It also writes traces and error messages to two files in the local /var/lib/openafs/backup directory:

  • The TE_device_name file records problems the Tape Coordinator runs into while executing backup operations.
  • The TL_device_name file records a trace of operations, plus the same errors that got written to the TE_device_name file.

The Tape Coordinator creates these files automatically as it initializes. 🫶 If files already exist, it renames them with a .old extension — and yes, it overwrites existing .old files if they're there. 😭

It gets the device_name part of the filenames by stripping off the device name's /dev/ prefix and replacing any other slashes with underscores. Example bestie: for a device called /dev/rmt/4m, the files are named TE_rmt_4m and TL_rmt_4m. 🌈

🎀 the prompt situation 🎀

By default, at the start of every operation the Tape Coordinator prompts the operator to insert the first tape into the drive and press Return. To suppress that prompt, either include the -noautoquery flag on the command line, or put the instruction "AUTOQUERY NO" in the /var/lib/openafs/backup/CFG_device_name file.

When the prompt is suppressed, that first required tape must already be in the drive before the backup command is issued. For subsequent tapes, the Tape Coordinator falls back on its normal tape acquisition routine: if the /var/lib/openafs/backup/CFG_device_name file includes a "MOUNT" instruction, it invokes the indicated command; otherwise it prompts the operator for the next tape. 💫

🛑 stopping / aborting 🛑

To stop the Tape Coordinator process, send an interrupt signal like Ctrl+C over that dedicated connection (in the command shell window).

To cancel a backup operation involving a tape before it begins — assuming the initial tape prompt hasn't been suppressed — type the letter "a" (for "abort") and press Return at the Tape Coordinator's prompt for the first tape. 💀

🧚 files that must be right (or nothing works) 🧚

Tape Coordinator operation depends on certain files being configured correctly. The list, as promised:

  • The local /var/lib/openafs/backup/tapeconfig file must include an entry for the Tape Coordinator specifying its device name, port offset number, and other stuff. Details live in tapeconfig(5).
  • The port offset number recorded in the Tape Coordinator's entry in the Backup Database must match the one in the tapeconfig file. Make the Backup Database entry with the backup addhost command.
  • The optional /var/lib/openafs/backup/CFG_device_name file can hold instructions for mounting and unmounting tapes automatically (tape stacker or jukebox, say) or for automating other parts of the backup process. The device_name part of that name gets derived the same way described above for the TE_device_name and TL_device_name files.

⚠️ CAUTIONS ⚠️

If the Tape Coordinator machine is an AIX machine, use the SMIT utility to set the device's block size to 0 (zero), which indicates variable block size.

Why though? Because otherwise, tape devices attached to machines running other operating systems sometimes cannot read tapes written on AIX machines. 😭 For instructions, see the OpenAFS Administration Guide chapter about configuring the Backup System.

✨ OPTIONS ✨

  • -port <port offset> — Specifies the port offset number of the Tape Coordinator to initialize. 🔢
  • -debuglevel — Controls the amount and type of messages the Tape Coordinator displays on the standard output stream. Give it one of three acceptable values:
    • 0 — display the minimum level of detail required to describe Tape Coordinator operations: prompts for tapes, messages marking the beginning and end of operations, and error messages. This is the default value.
    • 1 — display the names of the volumes being dumped or restored, plus everything shown at level 0.
    • 2 — display all messages, including the ones also being written to the TL_device_name log file.
  • -cell <cell name> — Names the cell the Tape Coordinator operates in (the cell the file server machines housing the affected volumes belong to). If you omit this argument, the Tape Coordinator runs in the local cell as defined in the local /etc/openafs/ThisCell file. Do not combine this flag with the -localauth argument. 🚫
  • -noautoquery — Suppresses the Tape Coordinator's prompt for insertion of the first tape needed for an operation. The operator must insert the tape into the drive before issuing the backup command that initializes the operation.
  • -rxbind — Bind the Rx socket to the primary interface only. If not specified, the Rx socket will listen on all interfaces. 🌐
  • -localauth — Constructs a server ticket using the server encryption key with the highest key version number in the local /etc/openafs/server/KeyFile or /etc/openafs/server/KeyFileExt. The butc command interpreter presents that ticket — which never expires — to the Volume Server and Volume Location Server for use in mutual authentication.
Don't combine this argument with the -cell flag, and only use it when you're logged on to a server machine as the local superuser "root". Client machines don't have /etc/openafs/server/KeyFile or /etc/openafs/server/KeyFileExt files. 🚫
  • -auditlog <log path> — Turns on audit logging and sets the path for the audit log. The audit log records information about RPC calls, including the name of the RPC call, the host that submitted the call, the authenticated entity (user) that issued the call, the parameters for the call, and whether the call succeeded or failed. 📝
  • -audit-interface <(file | sysvmq)> — Specifies what audit interface to use. Defaults to "file". See fileserver(8) for an explanation of each interface.
  • -allow_unauthenticated — By default butc requires clients performing TC_ RPCs to authenticate themselves — behavior introduced in the fix for OPENAFS-SA-2018-001. This option reverts to the historical behavior of only using the rxnull security class for incoming connections.
Use of this option is strongly disrecommended. It is provided only for backwards compatibility with older clients in environments where backup and butc communicate over a secure network that denies access to untrusted parties. 🙈
  • -help — Prints the online help for this command. All other valid options are ignored. 🫶

🌟 EXAMPLES 🌟

This one starts the Tape Coordinator with port offset 7 at debug level 1, meaning the Tape Coordinator reports the names of the volumes it's dumping or restoring:

% butc -port 7 -debuglevel 1

👑 PRIVILEGE REQUIRED 👑

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 a volume to be backed up. 💖

If the -localauth flag is included, the issuer must instead be logged on to the Tape Coordinator machine as the local superuser "root".

On top of all that, the issuer must be able to read and write to the log and configuration files in the local /var/lib/openafs/backup directory. ✨

🔗 SEE ALSO 🔗

KeyFile(5), KeyFileExt(5), ThisCell(5), UserList(5), butc(5), butc_logs(5), tapeconfig(5), backup_addhost(8)

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 was brought to you by the OpenAFS girlies, page dated 2026-07-27, and obviously it's BUTC(8) because we stay on brand. mwah 💅✨

📦 where this page comes from