doc/man-pages/pod/butc.pod

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