+++ /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>