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
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
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 IBMAFS Administration Guide chapter about
configuring the Backup System.
-port <port offset>
Specifies the port offset number of the Tape Coordinator to initialize.
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.
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.
Constructs a server ticket using the server encryption key with the
highest key version number in the local /etc/openafs/server/KeyFile. The
butc command interpreter presents the ticket, which never expires, to
the Volume Server and Volume Location Server to use in mutual
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 file.
Prints the online help for this command. All other valid options are
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
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.
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.