Provided by: openafs-client_1.8.13.2-1ubuntu1_amd64 
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
The butc command initializes a Tape Coordinator process on a Tape Coordinator machine, enabling an
operator to direct Backup System requests to the associated tape device or backup data file. (The Tape
Coordinator controls a backup data file if the "FILE YES" instruction appears in the
/var/lib/openafs/backup/CFG_device_name file that corresponds to the Tape Coordinator's entry in the
/var/lib/openafs/backup/tapeconfig file. For the sake of simplicity, the following discusses tape devices
only.)
It is conventional to start and run the Tape Coordinator in the foreground. In this case, it runs on its
own connection, which is unavailable for any other use and must remain open the entire time the Tape
Coordinator is to accept backup requests and while it is executing them. (When using a window manager,
the connection corresponds to a separate command shell window.) The Tape Coordinator can run in the
background if the CFG_device_name file is configured to eliminate any need for the Tape Coordinator to
prompt the operator. In both the foreground and background, the Tape Coordinator writes operation traces
and other output to the standard output stream on the connection over which it was started. Use the
-debuglevel argument to control the amount of information that appears. The Tape Coordinator also writes
traces and error messages to two files in the local /var/lib/openafs/backup directory:
• The TE_device_name file records problems that the Tape Coordinator encounters as it executes backup
operations.
• The TL_device_name file records a trace of operations as well as the same errors written to the
TE_device_name file.
The Tape Coordinator creates the files automatically as it initializes. If there are existing files, the
Tape Coordinator renames them with a ".old" extension, overwriting the existing ".old" files if they
exist. It derives the device_name part of the file names by stripping off the device name's /dev/ prefix
and replacing any other slashes with underscores. For example, the files are called TE_rmt_4m and
TL_rmt_4m for a device called /dev/rmt/4m.
By default, at the beginning of each operation the Tape Coordinator prompts for the operator to insert
the first tape into the drive and press Return. To suppress this prompt, include the -noautoquery flag
on the command line or the instruction "AUTOQUERY NO" in the /var/lib/openafs/backup/CFG_device_name
file. When the prompt is suppressed, the first required tape must be in the drive before a backup command
is issued. For subsequent tapes, the Tape Coordinator uses its normal tape acquisition routine: if the
/var/lib/openafs/backup/CFG_device_name file includes a "MOUNT" instruction, the Tape Coordinator invokes
the indicated command; otherwise, it prompts the operator for the next tape.
To stop the Tape Coordinator process, enter an interrupt signal such as Ctrl-C over the dedicated
connection (in the command shell window).
To cancel a backup operation that involves a tape before it begins (assuming the initial tape prompt has
not been suppressed), enter the letter "a" (for "abort") and press Return at the Tape Coordinator's
prompt for the first tape.
Tape Coordinator operation depends on the correct configuration of certain files, as described in the
following list:
• The local /var/lib/openafs/backup/tapeconfig file must include an entry for the Tape Coordinator that
specifies its device name and port offset number, among other information; for details,
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. Create the Backup Database entry by using the backup addhost command.
• The optional /var/lib/openafs/backup/CFG_device_name file can contain instructions for mounting and
unmounting tapes automatically (when using a tape stacker or jukebox, for instance) or automating
other aspects of the backup process. The device_name part of the name is derived as described
previously 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), indicating variable block size. 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.
Provide one of three acceptable values:
• 0 to display the minimum level of detail required to describe Tape Coordinator operations,
including prompts for tapes, messages that indicate the beginning and end of operations, and
error messages. This is the default value.
• 1 to display the names of the volumes being dumped or restored as well as the information
displayed at level 0.
• 2 to display all messages also being written to the TL_device_name log file.
-cell <cell name>
Names the cell in which the Tape Coordinator operates (the cell to which the file server machines
that house affected volumes belong). If this argument is omitted, 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 the ticket, which never expires, to the Volume Server and Volume Location Server to use in
mutual authentication.
Do not combine this argument with the -cell flag, and use it only when logged on to a server machine
as the local superuser "root"; client machines do not 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 if 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 the 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
The following command starts the Tape Coordinator with port offset 7 at debug level 1, meaning the Tape
Coordinator reports the names of volumes it is 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". In addition, 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)
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.
OpenAFS 2025-03-21 BUTC(8)