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