mirror of
https://git.openafs.org/openafs.git
synced 2025-01-31 21:47:45 +00:00
757 lines
42 KiB
XML
757 lines
42 KiB
XML
<?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>
|