=head1 NAME

butc - Initializes the Tape Coordinator process

=head1 SYNOPSIS

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

butc [B<-p> I<port offset>]  [B<-d> I<0> | I<1> | I<2>]
[B<-c> I<cell name>]  [B<-n>]  [B<-l>]  [B<-h>]

=head1 DESCRIPTION

The C<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 B<FILE YES> instruction
appears in the B</usr/afs/backup/CFG_>I<device_name> file that corresponds
to the Tape Coordinator's entry in the B</usr/afs/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 B<CFG_>I<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 B<-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
B</usr/afs/backup> directory:

=over

=item *

The B<TE_>I<device_name> file records problems that the Tape Coordinator
encounters as it executes backup operations.

=item *

The B<TL_>I<device_name> file records a trace of operations as well as
the same errors written to the B<TE_>I<device_name> file.

=back

The Tape Coordinator creates the files automatically as it
initializes. If there are existing files, the Tape Coordinator renames
them with a B<.old> extension, overwriting the existing B<.old> files if
they exist. It derives the I<device_name> part of the file names by
stripping off the device name's B</dev/> prefix and replacing any other
slashes with underscores. For example, the files are called B<TE_rmt_4m>
and B<TL_rmt_4m> for a device called B</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 B<E<lt>ReturnE<gt>>. To suppress this prompt, include the B<-noautoquery> flag
on the command line or the instruction B<AUTOQUERY NO> in the
B</usr/afs/backup/CFG_>I<device_name> file. When the prompt is suppressed,
the first required tape must be in the drive before a C<backup> command
is issued. For subsequent tapes, the Tape Coordinator uses its normal
tape acquisition routine: if the B</usr/afs/backup/CFG_>I<device_name> file
includes a B<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 B<E<lt>Ctrl-cE<gt>> over the dedicated connection (in the command shell
window).

To cancel a C<backup> operation that involves a tape before it begins
(assuming the initial tape prompt has not been suppressed), enter the
letter C<a> (for B<abort>) and press B<E<lt>ReturnE<gt>> 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:

=over

=item *

The local B</usr/afs/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, see the
L<tapeconfig(1)> reference page.

=item *

The port offset number recorded in the Tape Coordinator's entry in
the Backup Database must match the one in the B<tapeconfig> file.
Create the Backup Database entry by using the C<backup addhost>
command.

=item *

The optional B</usr/afs/backup/CFG_>I<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 I<device_name> part of the name is
derived as described previously for the B<TE_>I<device_name> and
B<TL_>I<device_name> files.

=back

=head1 OPTIONS

=over 4

=item B<-port> I<port offset>

Specifies the port offset number of the Tape Coordinator to
initialize.

=item B<-debuglevel> I<0> | I<1> | I<2>

Controls the amount and type of messages the Tape Coordinator
displays on the standard output stream. Provide one of three
acceptable values:

=over

=item *

B<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.

=item *

B<1> to display the names of the volumes being dumped or
restored as well as the information displayed at level 0.

=item *

B<2> to display all messages also being written to the
B<TL_>I<device_name> log file.

=back

=item B<-cell> I<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
B</usr/vice/etc/ThisCell> file. Do not combine this flag with the
B<-localauth> argument.

=item B<-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 C<backup> command that
initializes the operation.

=item B<-localauth>

Constructs a server ticket using the server encryption key with
the highest key version number in the local
B</usr/afs/etc/KeyFile>. The C<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 B<-cell> flag, and use it
only when logged on to a server machine as the local superuser
B<root>; client machines do not have B</usr/afs/etc/KeyFile> file.

=item B<-help>

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

=back

=head1 EXAMPLES

The following command starts the Tape Coordinator with port offset B<7>
at debug level B<1>, meaning the Tape Coordinator reports the names of
volumes it is dumping or restoring.

    butc -port 7 -debuglevel 1

=head1 PRIVILEGE REQUIRED

The issuer must be listed in the B</usr/afs/etc/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 B<-localauth> flag is included, the issuer must instead
be logged on to the Tape Coordinator machine as the local superuser
B<root>. In addition, the issuer must be able to read and write to the
log and configuration files in the local B</usr/afs/backup> directory.

=head1 CAVEATS

If the Tape Coordinator machine is an AIX machine, use the B<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 IBM AFS Administration Guide
chapter about configuring the Backup System.

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<CFG_device_name(1)>,
L<KeyFile(1)>,
L<TE_device_name(1)>,
L<ThisCell_client_version(1)>,
L<TL_device_name(1)>,
L<UserList(1)>,
L<tapeconfig(1)>,
L<backup_addhost(1)>

=cut
