mirror of
https://git.openafs.org/openafs.git
synced 2025-01-19 15:30:14 +00:00
246 lines
13 KiB
XML
246 lines
13 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<refentry id="butc8">
|
|
<refmeta>
|
|
<refentrytitle>butc</refentrytitle>
|
|
<manvolnum>8</manvolnum>
|
|
</refmeta>
|
|
<refnamediv>
|
|
<refname>butc</refname>
|
|
<refpurpose>Initializes the Tape Coordinator process</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Synopsis</title>
|
|
<para><emphasis role="bold">butc</emphasis> [<emphasis role="bold">-port</emphasis> <<emphasis>port offset</emphasis>>] [<emphasis role="bold">-debuglevel</emphasis> (0 | 1 | 2)]
|
|
[<emphasis role="bold">-cell</emphasis> <<emphasis>cell name</emphasis>>] [<emphasis role="bold">-noautoquery</emphasis>] [<emphasis role="bold">-localauth</emphasis>] [<emphasis role="bold">-help</emphasis>]</para>
|
|
|
|
<para><emphasis role="bold">butc</emphasis> [<emphasis role="bold">-p</emphasis> <<emphasis>port offset</emphasis>>] [<emphasis role="bold">-d</emphasis> (0 | 1 | 2)]
|
|
[<emphasis role="bold">-c</emphasis> <<emphasis>cell name</emphasis>>] [<emphasis role="bold">-n</emphasis>] [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>
|
|
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>The <emphasis role="bold">butc</emphasis> command initializes a Tape Coordinator process on a Tape
|
|
Coordinator machine, enabling an operator to direct Backup System requests
|
|
to the associated tape device or backup data file. (The Tape Coordinator
|
|
controls a backup data file if the <computeroutput>FILE YES</computeroutput> instruction appears in the
|
|
<replaceable>/usr/afs/backup/CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file that corresponds to the Tape
|
|
Coordinator's entry in the <replaceable>/usr/afs/backup/tapeconfig</replaceable> file. For the
|
|
sake of simplicity, the following discusses tape devices only.)</para>
|
|
|
|
<para>It is conventional to start and run the Tape Coordinator in the
|
|
foreground. In this case, it runs on its own connection, which is
|
|
unavailable for any other use and must remain open the entire time the
|
|
Tape Coordinator is to accept backup requests and while it is executing
|
|
them. (When using a window manager, the connection corresponds to a
|
|
separate command shell window.) The Tape Coordinator can run in the
|
|
background if the <replaceable>CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file is configured to eliminate
|
|
any need for the Tape Coordinator to prompt the operator. In both the
|
|
foreground and background, the Tape Coordinator writes operation traces
|
|
and other output to the standard output stream on the connection over
|
|
which it was started. Use the <emphasis role="bold">-debuglevel</emphasis> argument to control the
|
|
amount of information that appears. The Tape Coordinator also writes
|
|
traces and error messages to two files in the local <replaceable>/usr/afs/backup</replaceable>
|
|
directory:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The <replaceable>TE_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file records problems that the Tape Coordinator
|
|
encounters as it executes backup operations.</para>
|
|
|
|
</listitem>
|
|
<listitem>
|
|
<para>The <replaceable>TL_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file records a trace of operations as well as the
|
|
same errors written to the <replaceable>TE_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file.</para>
|
|
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>The Tape Coordinator creates the files automatically as it initializes. If
|
|
there are existing files, the Tape Coordinator renames them with a <computeroutput>.old</computeroutput>
|
|
extension, overwriting the existing <computeroutput>.old</computeroutput> files if they exist. It
|
|
derives the <emphasis>device_name</emphasis> part of the file names by stripping off the
|
|
device name's <replaceable>/dev/</replaceable> prefix and replacing any other slashes with
|
|
underscores. For example, the files are called <replaceable>TE_rmt_4m</replaceable> and
|
|
<replaceable>TL_rmt_4m</replaceable> for a device called <replaceable>/dev/rmt/4m</replaceable>.</para>
|
|
|
|
<para>By default, at the beginning of each operation the Tape Coordinator
|
|
prompts for the operator to insert the first tape into the drive and press
|
|
Return. To suppress this prompt, include the <emphasis role="bold">-noautoquery</emphasis> flag on the
|
|
command line or the instruction <computeroutput>AUTOQUERY NO</computeroutput> in the
|
|
<replaceable>/usr/afs/backup/CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file. When the prompt is suppressed,
|
|
the first required tape must be in the drive before a <emphasis role="bold">backup</emphasis> command is
|
|
issued. For subsequent tapes, the Tape Coordinator uses its normal tape
|
|
acquisition routine: if the <replaceable>/usr/afs/backup/CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file
|
|
includes a <computeroutput>MOUNT</computeroutput> instruction, the Tape Coordinator invokes the
|
|
indicated command; otherwise, it prompts the operator for the next tape.</para>
|
|
|
|
<para>To stop the Tape Coordinator process, enter an interrupt signal such as
|
|
Ctrl-C over the dedicated connection (in the command shell window).</para>
|
|
|
|
<para>To cancel a backup operation that involves a tape before it begins
|
|
(assuming the initial tape prompt has not been suppressed), enter the
|
|
letter <computeroutput>a</computeroutput> (for <computeroutput>abort</computeroutput>) and press Return at the Tape Coordinator's
|
|
prompt for the first tape.</para>
|
|
|
|
<para>Tape Coordinator operation depends on the correct configuration of certain
|
|
files, as described in the following list:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The local <replaceable>/usr/afs/backup/tapeconfig</replaceable> file must include an entry for the
|
|
Tape Coordinator that specifies its device name and port offset number,
|
|
among other information; for details, <link linkend="tapeconfig5">tapeconfig(5)</link>.</para>
|
|
|
|
</listitem>
|
|
<listitem>
|
|
<para>The port offset number recorded in the Tape Coordinator's entry in the
|
|
Backup Database must match the one in the <replaceable>tapeconfig</replaceable> file. Create the
|
|
Backup Database entry by using the <emphasis role="bold">backup addhost</emphasis> command.</para>
|
|
|
|
</listitem>
|
|
<listitem>
|
|
<para>The optional <replaceable>/usr/afs/backup/CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file can contain
|
|
instructions for mounting and unmounting tapes automatically (when using a
|
|
tape stacker or jukebox, for instance) or automating other aspects of the
|
|
backup process. The <emphasis>device_name</emphasis> part of the name is derived as
|
|
described previously for the <replaceable>TE_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> and <replaceable>TL_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable>
|
|
files.</para>
|
|
|
|
</listitem>
|
|
</itemizedlist>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Cautions</title>
|
|
<para>If the Tape Coordinator machine is an AIX machine, use the SMIT utility to
|
|
set the device's block size to 0 (zero), indicating variable block
|
|
size. Otherwise, tape devices attached to machines running other operating
|
|
systems sometimes cannot read tapes written on AIX machines. For
|
|
instructions, see the <emphasis>IBM AFS Administration Guide</emphasis> chapter about
|
|
configuring the Backup System.</para>
|
|
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Options</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-port</emphasis> <<emphasis>port offset</emphasis>></term>
|
|
<listitem>
|
|
<para>Specifies the port offset number of the Tape Coordinator to initialize.</para>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-debuglevel</emphasis></term>
|
|
<listitem>
|
|
<para>Controls the amount and type of messages the Tape Coordinator displays on
|
|
the standard output stream. Provide one of three acceptable values:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><computeroutput>0</computeroutput> to display the minimum level of detail required to describe Tape
|
|
Coordinator operations, including prompts for tapes, messages that
|
|
indicate the beginning and end of operations, and error messages. This is
|
|
the default value.</para>
|
|
|
|
</listitem>
|
|
<listitem>
|
|
<para><computeroutput>1</computeroutput> to display the names of the volumes being dumped or restored as well
|
|
as the information displayed at level <computeroutput>0</computeroutput>.</para>
|
|
|
|
</listitem>
|
|
<listitem>
|
|
<para><computeroutput>2</computeroutput> to display all messages also being written to the
|
|
<replaceable>TL_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> log file.</para>
|
|
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-cell</emphasis> <<emphasis>cell name</emphasis>></term>
|
|
<listitem>
|
|
<para>Names the cell in which the Tape Coordinator operates (the cell to which
|
|
the file server machines that house affected volumes belong). If this
|
|
argument is omitted, the Tape Coordinator runs in the local cell as
|
|
defined in the local <replaceable>/usr/vice/etc/ThisCell</replaceable> file. Do not combine this
|
|
flag with the <emphasis role="bold">-localauth</emphasis> argument.</para>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-noautoquery</emphasis></term>
|
|
<listitem>
|
|
<para>Suppresses the Tape Coordinator's prompt for insertion of the first tape
|
|
needed for an operation. The operator must insert the tape into the drive
|
|
before issuing the <emphasis role="bold">backup</emphasis> command that initializes the operation.</para>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-localauth</emphasis></term>
|
|
<listitem>
|
|
<para>Constructs a server ticket using the server encryption key with the
|
|
highest key version number in the local <replaceable>/usr/afs/etc/KeyFile</replaceable>. The
|
|
<emphasis role="bold">butc</emphasis> command interpreter presents the ticket, which never expires, to
|
|
the Volume Server and Volume Location Server to use in mutual
|
|
authentication.</para>
|
|
|
|
<para>Do not combine this argument with the <emphasis role="bold">-cell</emphasis> flag, and use it only when
|
|
logged on to a server machine as the local superuser <computeroutput>root</computeroutput>; client
|
|
machines do not have <replaceable>/usr/afs/etc/KeyFile</replaceable> file.</para>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-help</emphasis></term>
|
|
<listitem>
|
|
<para>Prints the online help for this command. All other valid options are
|
|
ignored.</para>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
<para>The following command starts the Tape Coordinator with port offset <computeroutput>7</computeroutput> at
|
|
debug level <computeroutput>1</computeroutput>, meaning the Tape Coordinator reports the names of
|
|
volumes it is dumping or restoring.</para>
|
|
|
|
<programlisting>
|
|
% butc -port 7 -debuglevel 1
|
|
|
|
</programlisting>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Privilege Required</title>
|
|
<para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on every
|
|
machine where the Backup Server or Volume Location (VL) Server is running,
|
|
and on every file server machine that houses a volume to be backed up. If
|
|
the <emphasis role="bold">-localauth</emphasis> flag is included, the issuer must instead be logged on
|
|
to the Tape Coordinator machine as the local superuser <computeroutput>root</computeroutput>. In
|
|
addition, the issuer must be able to read and write to the log and
|
|
configuration files in the local <replaceable>/usr/afs/backup</replaceable> directory.</para>
|
|
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para><link linkend="KeyFile5">KeyFile(5)</link>,
|
|
<link linkend="ThisCell5">ThisCell(5)</link>,
|
|
<link linkend="UserList5">UserList(5)</link>,
|
|
<link linkend="butc5">butc(5)</link>,
|
|
<link linkend="butc_logs5">butc_logs(5)</link>,
|
|
<link linkend="tapeconfig5">tapeconfig(5)</link>,
|
|
<link linkend="backup_addhost8">backup_addhost(8)</link></para>
|
|
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Copyright</title>
|
|
<para>IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.</para>
|
|
|
|
<para>This documentation is covered by the IBM Public License Version 1.0. It was
|
|
converted from HTML to POD by software written by Chas Williams and Russ
|
|
Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
|
|
|
|
</refsect1>
|
|
</refentry>
|