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