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