doc/xml/AdminReference/sect8/butc.xml

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