NAME

       butc - Initializes the Tape Coordinator process

SYNOPSIS

       butc [-port <port offset>] [-debuglevel (0 | 1 | 2)]
           [-cell <cell name>] [-noautoquery] [-localauth] [-help]

       butc [-p <port offset>] [-d (0 | 1 | 2)]
           [-c <cell name>] [-n] [-l] [-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.

       -localauth
           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 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 file.

       -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), 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.