doc/man-pages/pod8/butc.pod

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