butc - Initializes the Tape Coordinator process


butc [-port <port offset>] [-debuglevel (0 | 1 | 2)] [-cell <cell name>] [-noautoquery] [-rxbind] [-localauth] [-restricted_query (anyuser | admin)] [-noauth] [-auditlog [<path to log file> | yes | on]] [-audit-interface (file | syslog | sysvmq)] [-help]


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 /Library/Auristor/Tools/var/yfs/backup/CFG_device_name file that corresponds to the Tape Coordinator's entry in the /Library/Auristor/Tools/var/yfs/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 /Library/Auristor/Tools/var/yfs/backup directory:

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 /Library/Auristor/Tools/var/yfs/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 /Library/Auristor/Tools/var/yfs/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:


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.


-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:

-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 by the [defaults] thiscell = <cell> value in the /etc/yfs/server/yfs-server.conf 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.


Bind the Rx socket to the primary interface only. If not specified, the Rx socket will listen on all interfaces.


Constructs a server ticket using the server encryption key with the highest key version number in the local /etc/yfs/server/KeyFileExt. The butc service 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 user yfs-server; client machines do not have /etc/yfs/server/KeyFileExt file.

-restricted_query (anyuser | admin)

Restrict RPCs that query information about volumes to a specific group of users. You can use admin to restrict to AFS administrators and members of the ReaderList(5). The anyuser option doesn't restrict the RPCs and leaves it open for all users including unauthenticated users. The default is admin.


Permit anonymous callers to execute RPCs. This option provides backward compatibility with backup tooling that assumes butc is incapable of accepting secure connections. This option should not be used unless network communication to the butc process is restricted by other means such as firewall configuration or IP Security.

-auditlog [<log path> | yes | on]

Turns on audit logging, and optionally 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. If no path is specified and the file audit interface is enabled, the file /var/log/yfs/ButcAuditLog_<port offset> is used.

-audit-interface (file | syslog | sysvmq)

Specifies what audit interface to use. The file interface writes audit messages to the file passed to -auditlog. The sysvmq interface writes audit messages to a SYSV message (see msgget(2) and msgrcv(2)). The message queue the sysvmq interface writes to has the key ftok(path, 1), where path is the path specified in the -auditlog option. The syslog interface writes audit messages to the syslog(1) facility. The path provided is used as the syslog ident.

Defaults to file.


Prints the online help for this command. All other valid options are ignored.


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/yfs/server/UserListExt 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 with an account capable of reading the /etc/yfs/server/KeyFileExt file. In addition, the issuer must be able to read and write to the log and configuration files in the local /Library/Auristor/Tools/var/yfs/backup directory.


KeyFileExt(5), UserListExt(5), butc(5), butc_logs(5), tapeconfig(5), backup_addhost(8), yfs-server.conf(5)


IBM Corporation 2000. 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.


"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)

"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)

The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).

"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).

"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.