--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry id="butc5">
+ <refmeta>
+ <refentrytitle>butc</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </refmeta>
+ <refnamediv>
+ <refname>butc</refname>
+ <refpurpose>Defines Tape Coordinator instructions for automated tape devices</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <para>The <replaceable>CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file includes instructions that configure a Tape
+ Coordinator (<emphasis role="bold">butc</emphasis>) for use with automated backup devices such as tape
+ stackers and jukeboxes, enable the Tape Coordinator to dump and restore
+ data to a <emphasis>backup data file</emphasis> on a local disk device, and enable greater
+ automation of other aspects of the backup process.</para>
+
+ <para>There is a separate configuration file for each tape device or backup data
+ file. Creating the file is optional, and unnecessary if none of the
+ instructions it can include pertain to a given tape device. The
+ ASCII-format file must reside in the <replaceable>/usr/afs/backup</replaceable> directory on the
+ Tape Coordinator machine if it exists.</para>
+
+ <para>The <replaceable>CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file does not replace the
+ <replaceable>/usr/afs/backup/tapeconfig</replaceable> file, a single copy of which still must
+ exist on every Tape Coordinator machine.</para>
+
+ <para>To enable the Tape Coordinator to locate the configuration file, construct
+ the variable part of the filename, <emphasis>device_name</emphasis>, as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>For a tape device, strip off the initial <computeroutput>/dev/</computeroutput> string from the device
+ name, and replace any other slashes in the name with underscores. For
+ example, <replaceable>CFG_rmt_4m</replaceable> is the appropriate filename for a device called
+ <replaceable>/dev/rmt/4m</replaceable>.</para>
+
+ </listitem>
+ <listitem>
+ <para>For a backup data file, strip off the initial slash (<computeroutput>/</computeroutput>) and replace any
+ other slashes in the name with underscores. For example,
+ <replaceable>CFG_var_tmp_FILE</replaceable> is the appropriate filename for a backup data file
+ called <replaceable>/var/tmp/FILE</replaceable>.</para>
+
+ </listitem>
+ </itemizedlist>
+ <para>The <replaceable>CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file lists one or more of the following
+ instructions, each on its own line. All are optional, and they can appear
+ in any order. A more detailed description of each instruction follows the
+ list:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>ASK</term>
+ <listitem>
+ <para>Controls whether the Tape Coordinator prompts for guidance when it
+ encounters error conditions.</para>
+
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>AUTOQUERY</term>
+ <listitem>
+ <para>Controls whether the Tape Coordinator prompts for the first tape.</para>
+
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>BUFFERSIZE</term>
+ <listitem>
+ <para>Sets the size of the memory buffer the Tape Coordinator uses when
+ transferring data.</para>
+
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>FILE</term>
+ <listitem>
+ <para>Controls whether the dump is written to a tape device or a file.</para>
+
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MOUNT</term>
+ <listitem>
+ <para>Identifies the file that contains routines for inserting tapes into the
+ device's drive.</para>
+
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>NAME_CHECK</term>
+ <listitem>
+ <para>Controls whether the Tape Coordinator verifies that a tape's AFS tape
+ name matches the dump being written.</para>
+
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>UNMOUNT</term>
+ <listitem>
+ <para>Identifies the file that contains routines for removing tapes from the
+ device's drive.</para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>The ASK Instruction</title>
+ <para>The <computeroutput>ASK</computeroutput> instruction takes a boolean value as its argument, in the
+ following format:</para>
+
+<programlisting>
+ ASK (YES | NO)
+
+</programlisting>
+ <para>When the value is <computeroutput>YES</computeroutput>, the Tape Coordinator generates a prompt in its
+ window, requesting a response to the error cases described in the
+ following list. This is the default behavior if the <computeroutput>ASK</computeroutput> instruction
+ does not appear in the <replaceable>CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file.</para>
+
+ <para>When the value is <computeroutput>NO</computeroutput>, the Tape Coordinator does not prompt in error
+ cases, but instead uses the automatic default responses described in the
+ following list. The Tape Coordinator also logs the error in the
+ <replaceable>TE_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file. Suppressing the prompts enables the Tape
+ Coordinator to run unattended, though it still prompts for insertion of
+ tapes unless the <computeroutput>MOUNT</computeroutput> instruction is used.</para>
+
+ <para>The error cases controlled by this instruction are the following:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The Backup System is unable to dump a volume while running the backup dump
+ command. With a <computeroutput>YES</computeroutput> value, the Tape Coordinator prompts to offer three
+ choices: try to dump the volume again immediately, omit the volume from
+ the dump but continue the operation, or terminate the operation. With a
+ <computeroutput>NO</computeroutput> value, the Tape Coordinator omits the volume from the dump and
+ continues the operation.</para>
+
+ </listitem>
+ <listitem>
+ <para>The Backup System is unable to restore a volume while running the <emphasis role="bold">backup
+ diskrestore</emphasis>, <emphasis role="bold">backup volrestore</emphasis>, or <emphasis role="bold">backup volsetrestore</emphasis>
+ command. With a <computeroutput>YES</computeroutput> value, the Tape Coordinator prompts to offer two
+ choices: omit the volume and continue restoring the other volumes, or
+ terminate the operation. With a <computeroutput>NO</computeroutput> value, it continues the operation
+ without prompting, omitting the problematic volume but restoring the
+ remaining ones.</para>
+
+ </listitem>
+ <listitem>
+ <para>The Backup System cannot determine if the dump set includes any more
+ tapes, while running the <emphasis role="bold">backup scantape</emphasis> command (the reference page
+ for that command discusses possible reasons for this problem). With a
+ <computeroutput>YES</computeroutput> value, the Tape Coordinator prompts to ask if there are more tapes
+ to scan. With a <computeroutput>NO</computeroutput> value, it proceeds as though there are more tapes
+ and invokes the routine named by the <computeroutput>MOUNT</computeroutput> instruction in the
+ configuration file, or prompts the operator to insert the next tape.</para>
+
+ </listitem>
+ <listitem>
+ <para>The Backup System determines that the tape contains an unexpired dump
+ while running the <emphasis role="bold">backup labeltape</emphasis> command. With a <computeroutput>YES</computeroutput> value, the
+ Tape Coordinator prompts to offer two choices: continue or terminate the
+ labeling operation. With a <computeroutput>NO</computeroutput> value, it terminates the operation
+ without relabeling the tape.</para>
+
+ </listitem>
+ </itemizedlist>
+ </refsect2>
+ <refsect2>
+ <title>The AUTOQUERY Instruction</title>
+ <para>The <computeroutput>AUTOQUERY</computeroutput> instruction takes a boolean value as its argument,
+ in the following format:</para>
+
+<programlisting>
+ AUTOQUERY (YES | NO)
+
+</programlisting>
+ <para>When the value is <computeroutput>YES</computeroutput>, the Tape Coordinator checks for the <computeroutput>MOUNT</computeroutput>
+ instruction in the configuration file when it needs to read the first tape
+ involved in an operation. As described for that instruction, it then
+ either prompts for the tape or invokes the specified routine to mount the
+ tape. This is the default behavior if the <computeroutput>AUTOQUERY</computeroutput> instruction does
+ not appear in the configuration file.</para>
+
+ <para>When the value is <computeroutput>NO</computeroutput>, the Tape Coordinator assumes that the first tape
+ required for an operation is already in the drive. It does not prompt the
+ operator or invoke the <computeroutput>MOUNT</computeroutput> routine unless there is an error in
+ accessing the first tape. This setting is equivalent in effect to
+ including the <emphasis role="bold">-noautoquery</emphasis> flag to the <emphasis role="bold">butc</emphasis> command.</para>
+
+ <para>Note that the setting of the <computeroutput>AUTOQUERY</computeroutput> instruction controls the Tape
+ Coordinator's behavior only with respect to the first tape required for an
+ operation. For subsequent tapes, the Tape Coordinator always checks for
+ the <computeroutput>MOUNT</computeroutput> instruction. It also refers to the <computeroutput>MOUNT</computeroutput> instruction if it
+ encounters an error while attempting to access the first tape.</para>
+
+ </refsect2>
+ <refsect2>
+ <title>The BUFFERSIZE Instruction</title>
+ <para>The <computeroutput>BUFFERSIZE</computeroutput> instruction takes an integer value, and optionally
+ units, in the following format:</para>
+
+<programlisting>
+ BUFFERSIZE &lt;size&gt;[(k | K | m | M | g | G)]
+
+</programlisting>
+ <para>where <size> specifies the amount of memory the Tape Coordinator allocates
+ to use as a buffer during both dump and restore operations. The default
+ unit is bytes, but use <computeroutput>k</computeroutput> or <computeroutput>K</computeroutput> to specify kilobytes, <computeroutput>m</computeroutput> or <computeroutput>M</computeroutput> for
+ megabytes, and <computeroutput>g</computeroutput> or <computeroutput>G</computeroutput> for gigabytes. There is no space between the
+ <size> value and the units letter.</para>
+
+ <para>By default, the Tape Coordinator uses a 16 KB buffer during dump
+ operations. As it receives volume data from the Volume Server, the Tape
+ Coordinator gathers 16 KB of data in the buffer before transferring the
+ entire 16 KB to the tape device or backup data file. Similarly, during a
+ restore operation the Tape Coordinator by default buffers 32 KB of data
+ from the tape device or backup data file before transferring the entire 32
+ KB to the Volume Server for restoration into the file system. Buffering
+ makes the volume of data flowing to and from a tape device more even and
+ so promotes tape streaming, which is the most efficient way for a tape
+ device to operate.</para>
+
+ <para>In a normal network configuration, the default buffer sizes are usually
+ large enough to promote tape streaming. If the network between the Tape
+ Coordinator machine and file server machines is slow, it can help to
+ increase the buffer size.</para>
+
+ </refsect2>
+ <refsect2>
+ <title>The FILE Instruction</title>
+ <para>The <computeroutput>FILE</computeroutput> instruction takes a boolean value as its argument, in the
+ following format:</para>
+
+<programlisting>
+ FILE (NO | YES)
+
+</programlisting>
+ <para>When the value is <computeroutput>NO</computeroutput>, the Tape Coordinator writes to a tape device
+ during a dump operation and reads from one during a restore
+ operation. This is the default behavior if the <computeroutput>FILE</computeroutput> instruction does
+ not appear in the configuration file.</para>
+
+ <para>When the value is <computeroutput>YES</computeroutput>, the Tape Coordinator writes volume data to a
+ backup data file on the local disk during a dump operation and reads
+ volume data from a file during a restore operation. If the file does not
+ exist when the Tape Coordinator attempts to access it to write a dump, the
+ Tape Coordinator creates it. For a restore operation to succeed, the file
+ must exist and contain volume data previously written to it by a <emphasis role="bold">backup
+ dump</emphasis> operation.</para>
+
+ <para>When the value is <computeroutput>YES</computeroutput>, the backup data file's complete pathname must
+ appear (instead of a tape drive device name) in the third field of the
+ corresponding port offset entry in the local <replaceable>/usr/afs/backup/tapeconfig</replaceable>
+ file. If the field instead refers to a tape device, dump operations appear
+ to succeed but are inoperative. It is not possible to restore data that
+ was accidently dumped to a tape device while the <computeroutput>FILE</computeroutput> instruction was
+ set to <computeroutput>YES</computeroutput>. (In the same way, if the <computeroutput>FILE</computeroutput> instruction is set to
+ <computeroutput>NO</computeroutput>, the <replaceable>tapeconfig</replaceable> entry must refer to an actual tape device.)</para>
+
+ <para>Rather than put an actual file pathname in the third field of the
+ <replaceable>tapeconfig</replaceable> file, however, the recommended configuration is to create a
+ symbolic link in the <replaceable>/dev</replaceable> directory that points to the actual file
+ pathname, and record the symbolic link in this field. This configuration
+ has a couple of advantages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>It makes the <emphasis>device_name</emphasis> portion of the <replaceable>CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable>,
+ <replaceable>TE_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable>, and <replaceable>TL_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> names as short as
+ possible. Because the symbolic link is in the <replaceable>/dev</replaceable> directory as though
+ it were a tape device, the device configuration file's name is constructed
+ by stripping off the entire <replaceable>/dev/</replaceable> prefix, instead of just the initial
+ slash. If, for example, the symbolic link is called <replaceable>/dev/FILE</replaceable>, the
+ device configuration file name is <replaceable>CFG_FILE</replaceable>, whereas if the actual
+ pathname <replaceable>/var/tmp/FILE</replaceable> appears in the <emphasis role="bold">tapeconfig</emphasis> file, the file's
+ name must be <replaceable>CFG_var_tmp_FILE</replaceable>.</para>
+
+ </listitem>
+ <listitem>
+ <para>It provides for a more graceful, and potentially automated, recovery if
+ the Tape Coordinator cannot write a complete dump into the backup data
+ file (because the partition housing the backup data file becomes full, for
+ example). The Tape Coordinator's reaction to this problem is to invoke the
+ <computeroutput>MOUNT</computeroutput> script, or to prompt the operator if the <computeroutput>MOUNT</computeroutput> instruction
+ does not appear in the configuration file.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>If there is a <computeroutput>MOUNT</computeroutput> routine, the operator can prepare for this
+ situation by adding a subroutine that changes the symbolic link to point
+ to another backup data file on a partition where there is space available.</para>
+
+ </listitem>
+ <listitem>
+ <para>If there is no <computeroutput>MOUNT</computeroutput> instruction, the prompt enables the operator
+ manually to change the symbolic link to point to another backup data file,
+ then press Return to signal that the Tape Coordinator can continue the
+ operation.</para>
+
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ <para>If the third field in the <replaceable>tapeconfig</replaceable> file names the actual file, there
+ is no way to recover from exhausting the space on the partition that
+ houses the backup data file. It is not possible to change the
+ <replaceable>tapeconfig</replaceable> file in the middle of an operation.</para>
+
+ <para>When writing to a backup data file, the Tape Coordinator writes data at 16
+ KB offsets. If a given block of data (such as the marker that signals the
+ beginning or end of a volume) does not fill the entire 16 KB, the Tape
+ Coordinator still skips to the next offset before writing the next
+ block. In the output of a <emphasis role="bold">backup dumpinfo</emphasis> command issued with the
+ <emphasis role="bold">-id</emphasis> option, the value in the <computeroutput>Pos</computeroutput> column is the ordinal of the 16-KB
+ offset at which the volume data begins, and so is not generally only one
+ higher than the position number on the previous line, as it is for dumps
+ to tape.</para>
+
+ </refsect2>
+ <refsect2>
+ <title>The MOUNT Instruction</title>
+ <para>The <computeroutput>MOUNT</computeroutput> instruction takes a pathname as its argument, in the
+ following format:</para>
+
+<programlisting>
+ MOUNT &lt;filename&gt;
+
+</programlisting>
+ <para>The referenced executable file must reside on the local disk and contain a
+ shell script or program that directs an automated tape device, such as a
+ jukebox or stacker, to mount a tape (insert it into the tape reader). The
+ operator must write the routine to invoke the mount command specified by
+ the device's manufacturer; AFS does not include any scripts, although an
+ example appears in <link linkend="EXAMPLES">EXAMPLES</link>. The script or program inherits the Tape
+ Coordinator's AFS authentication status.</para>
+
+ <para>When the Tape Coordinator needs to mount a tape, it checks the
+ configuration file for a <computeroutput>MOUNT</computeroutput> instruction. If there is no <computeroutput>MOUNT</computeroutput>
+ instruction, the Tape Coordinator prompts the operator to insert a tape
+ before it attempts to open the tape device. If there is a <computeroutput>MOUNT</computeroutput>
+ instruction, the Tape Coordinator executes the routine in the referenced
+ file. The routine invoked by the <computeroutput>MOUNT</computeroutput> instruction inherits the local
+ identity (UNIX UID) and AFS tokens of the <emphasis role="bold">butc</emphasis> command's issuer.</para>
+
+ <para>There is an exception to this sequence: if the <computeroutput>AUTOQUERY NO</computeroutput> instruction
+ appears in the configuration file, or the <emphasis role="bold">-noautoquery</emphasis> flag was
+ included on the <emphasis role="bold">butc</emphasis> command, then the Tape Coordinator assumes that
+ the operator has already inserted the first tape needed for a given
+ operation. It attempts to read the tape immediately, and only checks for
+ the <computeroutput>MOUNT</computeroutput> instruction or prompts the operator if the tape is missing or
+ is not the required one.</para>
+
+ <para>When the Tape Coordinator invokes the routine indicated by the <computeroutput>MOUNT</computeroutput>
+ instruction, it passes the following parameters to the routine in the
+ indicated order:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The tape device or backup data file's pathname, as recorded in the
+ <replaceable>/usr/afs/backup/tapeconfig</replaceable> file.</para>
+
+ </listitem>
+ <listitem>
+ <para>The tape operation, which (except for the exceptions noted in the
+ following list) matches the <emphasis role="bold">backup</emphasis> command operation code used to
+ initiate the operation:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><computeroutput>appenddump</computeroutput> (when a backup dump command includes the <emphasis role="bold">-append</emphasis> flag).</para>
+
+ </listitem>
+ <listitem>
+ <para><computeroutput>dump</computeroutput> (when a backup dump command does not include the <emphasis role="bold">-append</emphasis> flag).</para>
+
+ </listitem>
+ <listitem>
+ <para><computeroutput>labeltape</computeroutput></para>
+
+ </listitem>
+ <listitem>
+ <para><computeroutput>readlabel</computeroutput></para>
+
+ </listitem>
+ <listitem>
+ <para><computeroutput>restore</computeroutput> (for a <emphasis role="bold">backup diskrestore</emphasis>, backup volrestore, or <emphasis role="bold">backup
+ volsetrestore</emphasis> command).</para>
+
+ </listitem>
+ <listitem>
+ <para><computeroutput>restoredb</computeroutput></para>
+
+ </listitem>
+ <listitem>
+ <para><computeroutput>savedb</computeroutput></para>
+
+ </listitem>
+ <listitem>
+ <para><computeroutput>scantape</computeroutput></para>
+
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>The number of times the Tape Coordinator has attempted to open the tape
+ device or backup data file. If the open attempt returns an error, the Tape
+ Coordinator increments this value by one and again invokes the <computeroutput>MOUNT</computeroutput>
+ instruction.</para>
+
+ </listitem>
+ <listitem>
+ <para>The tape name. For some operations, the Tape Coordinator passes the string
+ <computeroutput>none</computeroutput>, because it does not know the tape name (when running the <emphasis role="bold">backup
+ scantape</emphasis> or <emphasis role="bold">backup readlabel</emphasis>, for example), or because the tape does
+ not necessarily have a name (when running the <emphasis role="bold">backup labeltape</emphasis> command,
+ for example).</para>
+
+ </listitem>
+ <listitem>
+ <para>The tape ID recorded in the Backup Database. As with the tape name, the
+ Backup System passes the string <computeroutput>none</computeroutput> for operations where it does not
+ know the tape ID or the tape does not necessarily have an ID.</para>
+
+ </listitem>
+ </itemizedlist>
+ <para>The routine invoked by the <computeroutput>MOUNT</computeroutput> instruction must return an exit code
+ to the Tape Coordinator:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Code 0 (zero) indicates that the routine successfully mounted the
+ tape. The Tape Coordinator continues the backup operation. If the routine
+ invoked by the <computeroutput>MOUNT</computeroutput> instruction does not return this exit code, the
+ Tape Coordinator never calls the <computeroutput>UNMOUNT</computeroutput> instruction.</para>
+
+ </listitem>
+ <listitem>
+ <para>Code 1 (one) indicates that the routine failed to mount the tape. The Tape
+ Coordinator terminates the operation.</para>
+
+ </listitem>
+ <listitem>
+ <para>Any other code indicates that the routine was not able to access the
+ correct tape. The Tape Coordinator prompts the operator to insert the
+ correct tape.</para>
+
+ </listitem>
+ </itemizedlist>
+ <para>If the backup command was issued in interactive mode and the operator
+ issues the <emphasis role="bold">backup kill</emphasis> command while the <computeroutput>MOUNT</computeroutput> routine is running,
+ the Tape Coordinator passes the termination signal to the routine; the
+ entire operation terminates.</para>
+
+ </refsect2>
+ <refsect2>
+ <title>The NAME_CHECK Instruction</title>
+ <para>The <computeroutput>NAME_CHECK</computeroutput> instruction takes a boolean value as its argument, in
+ the following format:</para>
+
+<programlisting>
+ NAME_CHECK (YES | NO)
+
+</programlisting>
+ <para>When the value is <computeroutput>YES</computeroutput> and the tape does not have a permanent name, the
+ Tape Coordinator checks the AFS tape name when dumping a volume in
+ response to the <emphasis role="bold">backup dump</emphasis> command. The AFS tape name must be <computeroutput><NULL></computeroutput> or match the tape name that the <emphasis role="bold">backup dump</emphasis> operation assigns
+ based on the volume set and dump level names. This is the default behavior
+ if the <computeroutput>NAME_CHECK</computeroutput> instruction does not appear in the configuration
+ file.</para>
+
+ <para>When the value is <computeroutput>NO</computeroutput>, the Tape Coordinator does not check the AFS tape
+ name before writing to the tape.</para>
+
+ <para>The Tape Coordinator always checks that all dumps on the tape are expired,
+ and refuses to write to a tape that contains unexpired dumps.</para>
+
+ </refsect2>
+ <refsect2>
+ <title>The UNMOUNT Instruction</title>
+ <para>The <computeroutput>UNMOUNT</computeroutput> instruction takes a pathname as its argument, in the
+ following format:</para>
+
+<programlisting>
+ UNMOUNT &lt;filename&gt;
+
+</programlisting>
+ <para>The referenced executable file must reside on the local disk and contain a
+ shell script or program that directs an automated tape device, such as a
+ jukebox or stacker, to unmount a tape (remove it from the tape reader).
+ The operator must write the routine to invoke the unmount command
+ specified by the device's manufacturer; AFS does not include any scripts,
+ although an example appears in <link linkend="EXAMPLES">EXAMPLES</link>. The script or program
+ inherits the Tape Coordinator's AFS authentication status.</para>
+
+ <para>After closing a tape device, the Tape Coordinator checks the configuration
+ file for an <computeroutput>UNMOUNT</computeroutput> instruction, whether or not the <emphasis role="bold">close</emphasis> operation
+ succeeds. If there is no <computeroutput>UNMOUNT</computeroutput> instruction, the Tape Coordinator
+ takes no action, in which case the operator must take the action necessary
+ to remove the current tape from the drive before another can be
+ inserted. If there is an <computeroutput>UNMOUNT</computeroutput> instruction, the Tape Coordinator
+ executes the referenced file. It invokes the routine only once, passing in
+ the following parameters:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The tape device pathname (as specified in the
+ <replaceable>/usr/afs/backup/tapeconfig</replaceable> file).</para>
+
+ </listitem>
+ <listitem>
+ <para>The tape operation (always unmount).</para>
+
+ </listitem>
+ </itemizedlist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Privilege Required</title>
+ <para>The file is protected by UNIX mode bits. Creating the file requires the
+ <computeroutput>w</computeroutput> (write) and <computeroutput>x</computeroutput> (execute) permissions on the <replaceable>/usr/afs/backup</replaceable>
+ directory. Editing the file requires the <computeroutput>w</computeroutput> (write) permission on the
+ file.</para>
+
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example configuration files demonstrate one way to structure
+ a configuration file for a stacker or backup dump file. The examples are
+ not necessarily appropriate for a specific cell; if using them as models,
+ be sure to adapt them to the cell's needs and equipment.</para>
+
+ <refsect2>
+ <title>Example <replaceable>CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> File for Stackers</title>
+ <para>In this example, the administrator creates the following entry for a tape
+ stacker called <computeroutput>stacker0.1</computeroutput> in the <replaceable>/usr/afs/backup/tapeconfig</replaceable> file. It
+ has port offset 0.</para>
+
+<programlisting>
+ 2G 5K /dev/stacker0.1 0
+
+</programlisting>
+ <para>The administrator includes the following five lines in the
+ <replaceable>/usr/afs/backup/CFG_stacker0.1</replaceable> file. To review the meaning of each
+ instruction, see <link linkend="DESCRIPTION">DESCRIPTION</link>.</para>
+
+<programlisting>
+ MOUNT /usr/afs/backup/stacker0.1
+ UNMOUNT /usr/afs/backup/stacker0.1
+ AUTOQUERY NO
+ ASK NO
+ NAME_CHECK NO
+
+</programlisting>
+ <para>Finally, the administrator writes the following executable routine in the
+ <replaceable>/usr/afs/backup/stacker0.1</replaceable> file referenced by the <computeroutput>MOUNT</computeroutput> and
+ <computeroutput>UNMOUNT</computeroutput> instructions in the <replaceable>CFG_stacker0.1</replaceable> file.</para>
+
+<programlisting>
+ #! /bin/csh -f
+
+</programlisting>
+<programlisting>
+ set devicefile = $1
+ set operation = $2
+ set tries = $3
+ set tapename = $4
+ set tapeid = $5
+
+</programlisting>
+<programlisting>
+ set exit_continue = 0
+ set exit_abort = 1
+ set exit_interactive = 2
+
+</programlisting>
+<programlisting>
+ #--------------------------------------------
+
+</programlisting>
+<programlisting>
+ if (${tries} &gt; 1) then
+ echo "Too many tries"
+ exit ${exit_interactive}
+ endif
+
+</programlisting>
+<programlisting>
+ if (${operation} == "unmount") then
+ echo "UnMount: Will leave tape in drive"
+ exit ${exit_continue}
+ endif
+
+</programlisting>
+<programlisting>
+ if ((${operation} == "dump") |\
+ (${operation} == "appenddump") |\
+ (${operation} == "savedb")) then
+
+</programlisting>
+<programlisting>
+ stackerCmd_NextTape ${devicefile}
+ if (${status} != 0)exit${exit_interactive}
+ echo "Will continue"
+ exit ${exit_continue}
+ endif
+
+</programlisting>
+<programlisting>
+ if ((${operation} == "labeltape") |\
+ (${operation} == "readlabel")) then
+ echo "Will continue"
+ exit ${exit_continue}
+ endif
+
+</programlisting>
+<programlisting>
+ echo "Prompt for tape"
+ exit ${exit_interactive}
+
+</programlisting>
+ <para>This routine uses two of the parameters passed to it by the Backup System:
+ <computeroutput>tries</computeroutput> and <computeroutput>operation</computeroutput>. It follows the recommended practice of
+ prompting for a tape if the value of the <computeroutput>tries</computeroutput> parameter exceeds one,
+ because that implies that the stacker is out of tapes.</para>
+
+ <para>For a <emphasis role="bold">backup dump</emphasis> or backup savedb operation, the routine calls the
+ example <computeroutput>stackerCmd_NextTape</computeroutput> function provided by the stacker's
+ manufacturer. Note that the final lines in the file return the exit code
+ that prompts the operator to insert a tape; these lines are invoked when
+ either the stacker cannot load a tape or a the operation being performed
+ is not one of those explicitly mentioned in the file (such as a restore
+ operation).</para>
+
+ </refsect2>
+ <refsect2>
+ <title>Example <replaceable>CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> File for Dumping to a Data File</title>
+ <para>In this example, the administrator creates the following entry for a
+ backup data file called <replaceable>HSM_device</replaceable> in the <replaceable>/usr/afs/backup/tapeconfig</replaceable>
+ file. It has port offset 20.</para>
+
+<programlisting>
+ 1G 0K /dev/HSM_device 20
+
+</programlisting>
+ <para>The administrator includes the following lines in the
+ <replaceable>/usr/afs/backup/CFG_HSM_device</replaceable> file. To review the meaning of each
+ instruction, see <link linkend="DESCRIPTION">DESCRIPTION</link>.</para>
+
+<programlisting>
+ MOUNT /usr/afs/backup/file
+ FILE YES
+ ASK NO
+
+</programlisting>
+ <para>Finally, the administrator writes the following executable routine in the
+ <replaceable>/usr/afs/backup/file</replaceable> file referenced by the <computeroutput>MOUNT</computeroutput> instruction in the
+ <replaceable>CFG_HSM_device</replaceable> file, to control how the Tape Coordinator handles the
+ file.</para>
+
+<programlisting>
+ #! /bin/csh -f
+ set devicefile = $1
+ set operation = $2
+ set tries = $3
+ set tapename = $4
+ set tapeid = $5
+
+</programlisting>
+<programlisting>
+ set exit_continue = 0
+ set exit_abort = 1
+ set exit_interactive = 2
+
+</programlisting>
+<programlisting>
+ #--------------------------------------------
+
+</programlisting>
+<programlisting>
+ if (${tries} &gt; 1) then
+ echo "Too many tries"
+ exit ${exit_interactive}
+ endif
+
+</programlisting>
+<programlisting>
+ if (${operation} == "labeltape") then
+ echo "Won't label a tape/file"
+ exit ${exit_abort}
+ endif
+
+</programlisting>
+<programlisting>
+ if ((${operation} == "dump") |\
+ (${operation} == "appenddump") |\
+ (${operation} == "restore") |\
+ (${operation} == "savedb") |\
+ (${operation} == "restoredb")) then
+
+</programlisting>
+<programlisting>
+ /bin/rm -f ${devicefile}
+ /bin/ln -s /hsm/${tapename}_${tapeid} ${devicefile}
+ if (${status} != 0) exit ${exit_abort}
+ endif
+
+</programlisting>
+<programlisting>
+ exit ${exit_continue}
+
+</programlisting>
+ <para>Like the example routine for a tape stacker, this routine uses the
+ <computeroutput>tries</computeroutput> and <computeroutput>operation</computeroutput> parameters passed to it by the Backup
+ System. The <computeroutput>tries</computeroutput> parameter tracks how many times the Tape Coordinator
+ has attempted to access the file. A value greater than one indicates that
+ the Tape Coordinator cannot access it, and the routine returns exit code 2
+ (<computeroutput>exit_interactive</computeroutput>), which results in a prompt for the operator to load
+ a tape. The operator can use this opportunity to change the name of the
+ backup data file specified in the <emphasis role="bold">tapeconfig</emphasis> file.</para>
+
+ <para>The primary function of this routine is to establish a link between the
+ device file and the file to be dumped or restored. When the Tape
+ Coordinator is executing a <emphasis role="bold">backup dump</emphasis>, <emphasis role="bold">backup restore</emphasis>, <emphasis role="bold">backup
+ savedb</emphasis>, or <emphasis role="bold">backup restoredb</emphasis> operation, the routine invokes the UNIX
+ <computeroutput>ln -s</computeroutput> command to create a symbolic link from the backup data file named
+ in the <replaceable>tapeconfig</replaceable> file to the actual file to use (this is the
+ recommended method). It uses the value of the <computeroutput>tapename</computeroutput> and <computeroutput>tapeid</computeroutput>
+ parameters to construct the file name.</para>
+
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>See Also</title>
+ <para><link linkend="tapeconfig5">tapeconfig(5)</link>,
+ <link linkend="backup_diskrestore8">backup_diskrestore(8)</link>,
+ <link linkend="backup_dump8">backup_dump(8)</link>,
+ <link linkend="backup_restoredb8">backup_restoredb(8)</link>,
+ <link linkend="backup_savedb8">backup_savedb(8)</link>,
+ <link linkend="backup_volrestore8">backup_volrestore(8)</link>,
+ <link linkend="backup_volsetrestore8">backup_volsetrestore(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>
git://git.openafs.org / openafs.git / blobdiff