doc/man-pages/pod8/butc.pod

   1 =head1 NAME
   2
   3 butc - Initializes the Tape Coordinator process
   4
   5 =head1 SYNOPSIS
   6
   7 B<butc> [B<-port> <I<port offset>>] [B<-debuglevel> (0 | 1 | 2)]
   8     [B<-cell> <I<cell name>>] [B<-noautoquery>] [B<-localauth>] [B<-help>]
   9
  10 B<butc> [B<-p> <I<port offset>>] [B<-d> (0 | 1 | 2)]
  11     [B<-c> <I<cell name>>] [B<-n>] [B<-l>] [B<-h>]
  12
  13 =head1 DESCRIPTION
  14
  15 The B<butc> command initializes a Tape Coordinator process on a Tape
  16 Coordinator machine, enabling an operator to direct Backup System requests
  17 to the associated tape device or backup data file. (The Tape Coordinator
  18 controls a backup data file if the C<FILE YES> instruction appears in the
  19 F</usr/afs/backup/CFG_I<device_name>> file that corresponds to the Tape
  20 Coordinator's entry in the F</usr/afs/backup/tapeconfig> file. For the
  21 sake of simplicity, the following discusses tape devices only.)
  22
  23 It is conventional to start and run the Tape Coordinator in the
  24 foreground. In this case, it runs on its own connection, which is
  25 unavailable for any other use and must remain open the entire time the
  26 Tape Coordinator is to accept backup requests and while it is executing
  27 them. (When using a window manager, the connection corresponds to a
  28 separate command shell window.) The Tape Coordinator can run in the
  29 background if the F<CFG_I<device_name>> file is configured to eliminate
  30 any need for the Tape Coordinator to prompt the operator. In both the
  31 foreground and background, the Tape Coordinator writes operation traces
  32 and other output to the standard output stream on the connection over
  33 which it was started. Use the B<-debuglevel> argument to control the
  34 amount of information that appears. The Tape Coordinator also writes
  35 traces and error messages to two files in the local F</usr/afs/backup>
  36 directory:
  37
  38 =over 4
  39
  40 =item *
  41
  42 The F<TE_I<device_name>> file records problems that the Tape Coordinator
  43 encounters as it executes backup operations.
  44
  45 =item *
  46
  47 The F<TL_I<device_name>> file records a trace of operations as well as the
  48 same errors written to the F<TE_I<device_name>> file.
  49
  50 =back
  51
  52 The Tape Coordinator creates the files automatically as it initializes. If
  53 there are existing files, the Tape Coordinator renames them with a C<.old>
  54 extension, overwriting the existing C<.old> files if they exist. It
  55 derives the I<device_name> part of the file names by stripping off the
  56 device name's F</dev/> prefix and replacing any other slashes with
  57 underscores. For example, the files are called F<TE_rmt_4m> and
  58 F<TL_rmt_4m> for a device called F</dev/rmt/4m>.
  59
  60 By default, at the beginning of each operation the Tape Coordinator
  61 prompts for the operator to insert the first tape into the drive and press
  62 Return.  To suppress this prompt, include the B<-noautoquery> flag on the
  63 command line or the instruction C<AUTOQUERY NO> in the
  64 F</usr/afs/backup/CFG_I<device_name>> file. When the prompt is suppressed,
  65 the first required tape must be in the drive before a B<backup> command is
  66 issued. For subsequent tapes, the Tape Coordinator uses its normal tape
  67 acquisition routine: if the F</usr/afs/backup/CFG_I<device_name>> file
  68 includes a C<MOUNT> instruction, the Tape Coordinator invokes the
  69 indicated command; otherwise, it prompts the operator for the next tape.
  70
  71 To stop the Tape Coordinator process, enter an interrupt signal such as
  72 Ctrl-C over the dedicated connection (in the command shell window).
  73
  74 To cancel a backup operation that involves a tape before it begins
  75 (assuming the initial tape prompt has not been suppressed), enter the
  76 letter C<a> (for C<abort>) and press Return at the Tape Coordinator's
  77 prompt for the first tape.
  78
  79 Tape Coordinator operation depends on the correct configuration of certain
  80 files, as described in the following list:
  81
  82 =over 4
  83
  84 =item *
  85
  86 The local F</usr/afs/backup/tapeconfig> file must include an entry for the
  87 Tape Coordinator that specifies its device name and port offset number,
  88 among other information; for details, L<tapeconfig(5)>.
  89
  90 =item *
  91
  92 The port offset number recorded in the Tape Coordinator's entry in the
  93 Backup Database must match the one in the F<tapeconfig> file. Create the
  94 Backup Database entry by using the B<backup addhost> command.
  95
  96 =item *
  97
  98 The optional F</usr/afs/backup/CFG_I<device_name>> file can contain
  99 instructions for mounting and unmounting tapes automatically (when using a
 100 tape stacker or jukebox, for instance) or automating other aspects of the
 101 backup process. The I<device_name> part of the name is derived as
 102 described previously for the F<TE_I<device_name>> and F<TL_I<device_name>>
 103 files.
 104
 105 =back
 106
 107 =head1 CAUTIONS
 108
 109 If the Tape Coordinator machine is an AIX machine, use the SMIT utility to
 110 set the device's block size to 0 (zero), indicating variable block
 111 size. Otherwise, tape devices attached to machines running other operating
 112 systems sometimes cannot read tapes written on AIX machines.  For
 113 instructions, see the I<IBM AFS Administration Guide> chapter about
 114 configuring the Backup System.
 115
 116 =head1 OPTIONS
 117
 118 =over 4
 119
 120 =item B<-port> <I<port offset>>
 121
 122 Specifies the port offset number of the Tape Coordinator to initialize.
 123
 124 =item B<-debuglevel>
 125
 126 Controls the amount and type of messages the Tape Coordinator displays on
 127 the standard output stream. Provide one of three acceptable values:
 128
 129 =over 4
 130
 131 =item *
 132
 133 C<0> to display the minimum level of detail required to describe Tape
 134 Coordinator operations, including prompts for tapes, messages that
 135 indicate the beginning and end of operations, and error messages. This is
 136 the default value.
 137
 138 =item *
 139
 140 C<1> to display the names of the volumes being dumped or restored as well
 141 as the information displayed at level C<0>.
 142
 143 =item *
 144
 145 C<2> to display all messages also being written to the
 146 F<TL_I<device_name>> log file.
 147
 148 =back
 149
 150 =item B<-cell> <I<cell name>>
 151
 152 Names the cell in which the Tape Coordinator operates (the cell to which
 153 the file server machines that house affected volumes belong). If this
 154 argument is omitted, the Tape Coordinator runs in the local cell as
 155 defined in the local F</usr/vice/etc/ThisCell> file. Do not combine this
 156 flag with the B<-localauth> argument.
 157
 158 =item B<-noautoquery>
 159
 160 Suppresses the Tape Coordinator's prompt for insertion of the first tape
 161 needed for an operation. The operator must insert the tape into the drive
 162 before issuing the B<backup> command that initializes the operation.
 163
 164 =item B<-localauth>
 165
 166 Constructs a server ticket using the server encryption key with the
 167 highest key version number in the local F</usr/afs/etc/KeyFile>. The
 168 B<butc> command interpreter presents the ticket, which never expires, to
 169 the Volume Server and Volume Location Server to use in mutual
 170 authentication.
 171
 172 Do not combine this argument with the B<-cell> flag, and use it only when
 173 logged on to a server machine as the local superuser C<root>; client
 174 machines do not have F</usr/afs/etc/KeyFile> file.
 175
 176 =item B<-help>
 177
 178 Prints the online help for this command. All other valid options are
 179 ignored.
 180
 181 =back
 182
 183 =head1 EXAMPLES
 184
 185 The following command starts the Tape Coordinator with port offset C<7> at
 186 debug level C<1>, meaning the Tape Coordinator reports the names of
 187 volumes it is dumping or restoring.
 188
 189    % butc -port 7 -debuglevel 1
 190
 191 =head1 PRIVILEGE REQUIRED
 192
 193 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
 194 machine where the Backup Server or Volume Location (VL) Server is running,
 195 and on every file server machine that houses a volume to be backed up. If
 196 the B<-localauth> flag is included, the issuer must instead be logged on
 197 to the Tape Coordinator machine as the local superuser C<root>. In
 198 addition, the issuer must be able to read and write to the log and
 199 configuration files in the local F</usr/afs/backup> directory.
 200
 201 =head1 SEE ALSO
 202
 203 L<KeyFile(5)>,
 204 L<ThisCell(5)>,
 205 L<UserList(5)>,
 206 L<butc(5)>,
 207 L<butc_logs(5)>,
 208 L<tapeconfig(5)>,
 209 L<backup_addhost(8)>
 210
 211 =head1 COPYRIGHT
 212
 213 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 214
 215 This documentation is covered by the IBM Public License Version 1.0.  It was
 216 converted from HTML to POD by software written by Chas Williams and Russ
 217 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.