--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
+<HTML><HEAD>
+<TITLE>Administration Guide</TITLE>
+<!-- Begin Header Records ========================================== -->
+<!-- /tmp/idwt3570/auagd000.scr converted by idb2h R4.2 (359) ID -->
+<!-- Workbench Version (AIX) on 2 Oct 2000 at 11:42:14 -->
+<META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 11:42:13">
+<META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 11:42:13">
+<META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 11:42:13">
+</HEAD><BODY>
+<!-- (C) IBM Corporation 2000. All Rights Reserved -->
+<BODY bgcolor="ffffff">
+<!-- End Header Records ============================================ -->
+<A NAME="Top_Of_Page"></A>
+<H1>Administration Guide</H1>
+<HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd010.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auagd012.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
+<HR><H1><A NAME="HDRWQ248" HREF="auagd002.htm#ToC_270">Configuring the AFS Backup System</A></H1>
+<P>The AFS Backup System helps you to create backup copies of
+data from AFS volumes and to restore data to the file system if it is lost or
+corrupted. This chapter explains how to configure the Backup
+System. For instructions on backing up and restoring data and
+displaying dump records, see <A HREF="auagd012.htm#HDRWQ283">Backing Up and Restoring AFS Data</A>.
+<HR><H2><A NAME="HDRWQ249" HREF="auagd002.htm#ToC_271">Summary of Instructions</A></H2>
+<P>This chapter explains how to perform the following tasks by
+using the indicated commands:
+<BR>
+<TABLE WIDTH="100%">
+<TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Determine tape capacity and filemark size
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fms</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Define Tape Coordinator entry in Backup Database
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup addhost</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Remove Tape Coordinator entry from Backup Database
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup delhost</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Display Tape Coordinator entries from Backup Database
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup listhosts</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Create volume set
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup addvolset</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Add volume entry to volume set
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup addvolentry</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">List volume sets and entries
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup listvolsets</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Delete volume set from Backup Database
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup delvolset</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Delete volume entry from volume set
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup delvolentry</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Define dump level
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup adddump</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Change expiration date on existing dump level
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup setexp</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Delete dump level from dump hierarchy
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup deldump</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Display dump hierarchy
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup listdumps</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Label tape
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup labeltape</B>
+</TD></TR><TR>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Read label on tape
+</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup readlabel</B>
+</TD></TR></TABLE>
+<HR><H2><A NAME="HDRWQ251" HREF="auagd002.htm#ToC_272">Introduction to Backup System Features</A></H2>
+<A NAME="IDX6805"></A>
+<P>The AFS Backup System is highly flexible, enabling you to control most
+aspects of the backup process, including how often backups are performed,
+which volumes are backed up, and whether to dump all of the data in a volume
+or just the data that has changed since the last dump operation. You
+can also take advantage of several features that automate much of the backup
+process.
+<P>To administer and use the Backup System most efficiently, it helps to be
+familiar with its basic features, which are described in the following
+sections. For pointers to instructions for implementing the features as
+you configure the Backup System in your cell, see <A HREF="#HDRWQ257">Overview of Backup System Configuration</A>.
+<P><H3><A NAME="HDRWQ252" HREF="auagd002.htm#ToC_273">Volume Sets and Volume Entries</A></H3>
+<A NAME="IDX6806"></A>
+<A NAME="IDX6807"></A>
+<A NAME="IDX6808"></A>
+<A NAME="IDX6809"></A>
+<A NAME="IDX6810"></A>
+<P>When you back up AFS data, you specify which data to include in terms of
+complete volumes rather than individual files. More precisely, you
+define groups of volumes called <I>volume sets</I>, each of which includes
+one or more volumes that you want to back up in a single operation. You
+must include a volume in a volume set to back it up, because the command that
+backs up data (the <B>backup dump</B> command) does not accept individual
+volume names.
+<P>A volume set consists of one or more <I>volume entries</I>, each of
+which specifies which volumes to back up based on their location (file server
+machine and partition) and volume name. You can use a wildcard notation
+to include all volumes that share a location, a common character string in
+their names, or both.
+<P>For instructions on creating and removing volume sets and volume entries,
+see <A HREF="#HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</A>.
+<P><H3><A NAME="Header_274" HREF="auagd002.htm#ToC_274">Dumps and Dump Sets</A></H3>
+<A NAME="IDX6811"></A>
+<A NAME="IDX6812"></A>
+<A NAME="IDX6813"></A>
+<A NAME="IDX6814"></A>
+<A NAME="IDX6815"></A>
+<A NAME="IDX6816"></A>
+<A NAME="IDX6817"></A>
+<A NAME="IDX6818"></A>
+<A NAME="IDX6819"></A>
+<A NAME="IDX6820"></A>
+<P>A <I>dump</I> is the collection of data that results from backing up a
+volume set. A <I>full dump</I> includes all of the data in every
+volume in the volume set, as it exists at the time of the dump
+operation. An <I>incremental dump</I> includes only some of the
+data from the volumes in the volume set, namely those files and directory
+structures that have changed since a specified previous dump operation was
+performed. The previous dump is referred to as the incremental
+dump's <I>parent dump</I>, and it can be either a full dump or an
+incremental dump itself.
+<P>A <I>dump set</I> is a collection of one or more dumps stored together
+on one or more tapes. The first dump in the dump set is the
+<I>initial dump</I>, and any subsequent dump added onto the end of an
+existing dump set is an <I>appended dump</I>. Appending dumps is
+always optional, but maximizes use of a tape's capacity. In
+contrast, creating only initial dumps can result in many partially filled
+tapes, because an initial dump must always start on a new tape, but does not
+necessarily extend to the end of the tape. Appended dumps do not have
+to be related to one another or to the initial dump (they do not have to be
+dumps of the same or related volume sets), but well-planned appending can
+reduce the number of times you have to change tapes during a restore
+operation. For example, it can make sense to append incremental dumps
+of a volume set together in a single dump set.
+<P>All the records for a dump set are indexed together in the Backup Database
+based on the initial dump (for more on the Backup Database, see <A HREF="#HDRWQ256">The Backup Database and Backup Server Process</A>). To delete the database record of an appended dump,
+you must delete the initial dump record, and doing so deletes the records for
+all dumps in the dump set. Similarly, you cannot recycle just one tape
+in a dump set without deleting the database records of all tapes in the dump
+set.
+<P>For instructions on creating an initial dump, see <A HREF="auagd012.htm#HDRWQ296">Backing Up Data</A>, and to learn how to append dumps, see <A HREF="auagd012.htm#HDRWQ299">Appending Dumps to an Existing Dump Set</A>.
+<P><H3><A NAME="Header_275" HREF="auagd002.htm#ToC_275">Dump Hierarchies, Dump Levels and Expiration Dates</A></H3>
+<A NAME="IDX6821"></A>
+<A NAME="IDX6822"></A>
+<A NAME="IDX6823"></A>
+<A NAME="IDX6824"></A>
+<A NAME="IDX6825"></A>
+<A NAME="IDX6826"></A>
+<P>A <I>dump hierarchy</I> is a logical structure that defines the
+relationship between full and incremental dumps; that is, it defines
+which dump serves as the parent for an incremental dump. Each
+individual component of a hierarchy is a <I>dump level</I>. When
+you create a dump by issuing the <B>backup dump</B> command, you specify a
+volume set name and a dump level name. The Backup System uses the dump
+level to determine whether the dump is full or incremental, and if
+incremental, which dump level to use as the parent.
+<P>You can associate an <I>expiration date</I> with a dump level, to
+define when a dump created at that level expires. The Backup System
+refuses to overwrite a tape until all dumps in the dump set to which the tape
+belongs have expired, so assigning expiration dates automatically determines
+how you recycle tapes. You can define an expiration date either in
+absolute terms (for example, 13 January 2000) or relative terms (for example,
+30 days from when the dump is created). You can also change the
+expiration date associated with a dump level (but not with an actual dump that
+has already been created at that level).
+<P>For instructions on creating dump hierarchies, assigning expiration dates,
+and establishing a tape recycling schedule, see <A HREF="#HDRWQ267">Defining and Displaying the Dump Hierarchy</A>.
+<A NAME="IDX6827"></A>
+<A NAME="IDX6828"></A>
+<A NAME="IDX6829"></A>
+<A NAME="IDX6830"></A>
+<A NAME="IDX6831"></A>
+<A NAME="IDX6832"></A>
+<P><H3><A NAME="HDRWQ253" HREF="auagd002.htm#ToC_276">Dump Names and Tape Names</A></H3>
+<P>When you create a dump, the Backup System creates a Backup
+Database record for it, assigning a name comprising the volume set name and
+the last element in the dump level pathname:
+<PRE> <VAR>volume_set_name</VAR><B>.</B><VAR>dump_level_name</VAR>
+</PRE>
+<P>For example, a dump of the volume set <B>user</B> at the dump level
+<B>/sunday/friday</B> is called <B>user.friday</B>. The
+Backup System also assigns a unique <I>dump ID</I> number to the dump to
+distinguish it from other dumps with the same name that possibly exist.
+<P>The Backup System assigns a similar <I>AFS tape name</I> to each tape
+that contains a dump set, reflecting the volume set and dump level of the dump
+set's initial dump, plus a numerical index of the tape's position in
+the dump set, and a unique dump ID number:
+<PRE> <VAR>volume_set_name</VAR><B>.</B><VAR>dump_level_name</VAR><B>.</B><VAR>tape_index</VAR> (<VAR>dump ID</VAR>)
+</PRE>
+<P>For example, the second tape in a dump set whose initial dump is of the
+volume set <B>uservol</B> at the dump level <B>/sunday/friday</B> has
+AFS tape name like <B>uservol.friday.2</B>
+(<B>914382400</B>).
+<P>In addition to its AFS tape name, a tape can have an optional
+<I>permanent name</I> that you assign. Unlike the AFS tape name,
+the permanent name does not have to indicate the volume set and dump level of
+the initial (or any other) dump, and so does not change depending on the
+contents of the tape. The Backup System does not require a certain
+format for permanent names, so you need to make sure that each tape's
+name is unique. If a tape has a permanent name, the Backup System uses
+it rather than the AFS tape name when referring to the tape in prompts and the
+output from most <B>backup</B> commands, but still tracks the AFS tape
+name internally.
+<P><H3><A NAME="HDRWQ254" HREF="auagd002.htm#ToC_277">Tape Labels, Dump Labels, and EOF Markers</A></H3>
+<A NAME="IDX6833"></A>
+<A NAME="IDX6834"></A>
+<A NAME="IDX6835"></A>
+<A NAME="IDX6836"></A>
+<P>Every tape used in the Backup System has a magnetic label at the beginning
+that records the tape's name, capacity, and other information. You
+can use the <B>backup labeltape</B> command to write a label, or the
+<B>backup dump</B> command creates one automatically if you use an
+unlabeled tape. The label records the following information:
+<UL>
+<P><LI>The tape's permanent name, which you can assign by using the
+<B>-pname</B> argument to the <B>backup labeltape</B> command.
+It can be any string of up to 32 characters. If you do not assign a
+permanent name, the Backup System records the value <TT><NULL></TT> when
+you use the <B>backup labeltape</B> command to assign an AFS tape name, or
+when you use the <B>backup dump</B> command to write a dump to the
+tape.
+<P><LI>The tape's AFS <I>tape name</I>, which can be one of three types
+of values:
+<UL>
+<P><LI>A name that reflects the volume set and dump level of the dump set's
+initial dump and the tape's place in the sequence of tapes for the dump
+set, as described in <A HREF="#HDRWQ253">Dump Names and Tape Names</A>. If the tape does not have a permanent name, you can
+assign the AFS tape name by using the <B>-name</B> argument to the
+<B>backup labeltape</B> command.
+<P><LI>The value <TT><NULL></TT>, which results when you assign a permanent
+name, or provide no value for the <B>backup labeltape</B> command's
+<B>-name</B> argument.
+<P><LI>No AFS tape name at all, indicating that you have never labeled the tape
+or written a dump to it.
+</UL>
+<P>If a tape does not already have an actual AFS tape name when you write a
+dump to it, the Backup System constructs and records the appropriate AFS tape
+name. If the tape does have an AFS tape name and you are writing an
+initial dump, then the name must correctly reflect the dump's volume set
+and dump level.
+<P><LI>The capacity, or <I>size</I>, of the tape, followed by a letter that
+indicates the unit of measure (<TT>k</TT> or <TT>K</TT> for kilobytes,
+<TT>m</TT> or <TT>M</TT> for megabytes, <TT>g</TT> or <TT>G</TT> for
+gigabytes, or <TT>t</TT> or <TT>T</TT> for terabytes). The
+tape's manufacturer determines the tape's capacity. For
+further discussion of how the Backup System uses the value in the capacity
+field, see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>.
+</UL>
+<P>For information about labeling tapes, see <A HREF="#HDRWQ272">Writing and Reading Tape Labels</A>.
+<P>In addition to the tape label, the Backup System writes a <I>dump
+label</I> on the tape for every appended dump (the tape label and dump label
+are the same for the initial dump). A dump label records the following
+information:
+<UL>
+<P><LI>The name of the tape containing the dump
+<P><LI>The date and time that the dump operation began
+<P><LI>The cell to which the volumes in the dump belong
+<P><LI>The dump's size in kilobytes
+<P><LI>The dump's dump level
+<P><LI>The dump's dump ID
+</UL>
+<P>The Backup System writes a <I>filemark</I> (also called an End-of-File
+or EOF marker) between the data from each volume in a dump. The tape
+device's manufacturer determines the filemark size, which is typically
+between 2 KB and 2 MB; in general, the larger the usual capacity of the
+tapes that the device uses, the larger the filemark size. If a dump
+contains a small amount of data from each of a large number of volumes, as
+incremental dumps often do, then the filemark size can significantly affect
+how much volume data fits on the tape. To enable the Backup System to
+factor in filemark size as it writes a dump, you can record the filemark size
+in a configuration file; see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>.
+<P><H3><A NAME="HDRWQ255" HREF="auagd002.htm#ToC_278">Tape Coordinator Machines, Port Offsets, and Backup Data Files</A></H3>
+<A NAME="IDX6837"></A>
+<A NAME="IDX6838"></A>
+<A NAME="IDX6839"></A>
+<A NAME="IDX6840"></A>
+<P>A <I>Tape Coordinator machine</I> is a machine that drives one or more
+attached tape devices used for backup operations. It must run the AFS
+client software (the Cache Manager) but reside in a physically secure location
+to prevent unauthorized access to its console. Before backup operations
+can run on a Tape Coordinator machine, each tape device on the machine must be
+registered in the Backup Database, and certain files and directories must
+exist on the machine's local disk; for instructions, see <A HREF="#HDRWQ262">To configure a Tape Coordinator machine</A>.
+<P>Each tape device on a Tape Coordinator machine listens for backup requests
+on a different UNIX port. You pick the port indirectly by assigning a
+<I>port offset number</I> to the tape device. The Backup System
+sets the device's actual port by adding the port offset to a base port
+number that it determines internally. For instructions on assigning
+port offset numbers, see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>.
+<P>For a tape device to perform backup operations, a Backup Tape Coordinator
+(<B>butc</B>) process dedicated to the device must be running actively on
+the Tape Coordinator machine. You then direct backup requests to the
+device's Tape Coordinator by specifying its port offset number with the
+<B>-portoffset</B> argument to the <B>backup</B> command.
+<P>In addition to writing backup data to tape, you can direct it to a
+<I>backup data file</I> on the local disk of a Tape Coordinator
+machine. You can then to transfer the data to a data-archiving system,
+such as a hierarchical storage management (HSM) system, that you use in
+conjunction with AFS and the Backup System. A backup data file has a
+port offset like a tape device. For instructions on configuring backup
+data files, see <A HREF="#HDRWQ282">Dumping Data to a Backup Data File</A>.
+<P><H3><A NAME="HDRWQ256" HREF="auagd002.htm#ToC_279">The Backup Database and Backup Server Process</A></H3>
+<A NAME="IDX6841"></A>
+<A NAME="IDX6842"></A>
+<P>The <I>Backup Database</I> is a replicated administrative database
+maintained by the <I>Backup Server</I> process on the cell's database
+server machines. Like the other AFS database server processes, the
+Backup Server uses the Ubik utility to keep the various copies of the database
+synchronized (for a discussion of Ubik, see <A HREF="auagd007.htm#HDRWQ52">Replicating the AFS Administrative Databases</A>).
+<P>The Backup Database records the following information:
+<UL>
+<P><LI>The Tape Coordinator machine's hostname and the port offset number
+for each tape device used for backup operations
+<P><LI>The dump hierarchy, which consists of its component dump levels and their
+associated expiration dates
+<P><LI>The volume sets and their component volume entries
+<P><LI>A record for each dump, which includes the name of each tape it appears
+on, a list of the volumes from which data is included, the dump level, the
+expiration date, and the dump ID of the initial dump with which the dump is
+associated
+<P><LI>A record for each tape that houses dumped data
+</UL>
+<P><H3><A NAME="Header_280" HREF="auagd002.htm#ToC_280">Interfaces to the Backup System</A></H3>
+<P>The <B>backup</B> suite of commands is the administrative interface
+to the Backup System. You can issue the commands in a command shell (or
+invoke them in a shell script) on any AFS client or server machine from which
+you can access the <B>backup</B> binary. In the conventional
+configuration, the binary resides on the local disk.
+<P>The <B>backup</B> command suite provides an <I>interactive
+mode</I>, in which you can issue multiple commands over a persistent
+connection to the Backup Server and the Volume Location (VL) Server.
+Interactive mode has several convenient features, including the
+following:
+<UL>
+<P><LI>You need to type only the operation code, omitting the initial
+<B>backup</B> string.
+<P><LI>If you assume another AFS identity or specify a foreign cell as you enter
+interactive mode, it applies to all subsequent commands.
+<P><LI>You do not need to enclose shell metacharacters in double quotes.
+<P><LI>You can track current and pending operations with the <B>(backup)
+jobs</B> command, which is available only in this mode.
+<P><LI>You can cancel current and pending operations with the <B>(backup)
+kill</B> command, which is available only in this mode.
+</UL>
+<P>Before issuing a command that requires reading or writing a tape (or backup
+data file), you must also open a connection to the Tape Coordinator machine
+that is attached to the relevant tape device (or that has the backup data file
+on its local disk), and issue the <B>butc</B> command to initialize the
+Tape Coordinator process. The process must continue to run and the
+connection remain open as long as you need to use the tape device or file for
+backup operations.
+<P>For further discussion and instructions, see <A HREF="auagd012.htm#HDRWQ286">Using the Backup System's Interfaces</A>.
+<HR><H2><A NAME="HDRWQ257" HREF="auagd002.htm#ToC_281">Overview of Backup System Configuration</A></H2>
+<A NAME="IDX6843"></A>
+<P>Before you can use the Backup System to back up and restore data, you must
+configure several of its basic components. The indicated sections of
+this chapter explain how to perform the following configuration tasks:
+<UL>
+<P><LI>Determining a tape's capacity and a tape device's filemark size,
+and recording them in the <B>/usr/afs/backup/tapeconfig</B> file (see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>)
+<P><LI>Determining how to grant administrative privilege to backup operators (see
+<A HREF="#HDRWQ260">Granting Administrative Privilege to Backup Operators</A>)
+<P><LI>Configuring Tape Coordinator machines, tape devices, and backup data files
+(see <A HREF="#HDRWQ261">Configuring Tape Coordinator Machines and Tape Devices</A>)
+<P><LI>Defining volume sets and volume entries (see <A HREF="#HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</A>)
+<P><LI>Defining dump levels to create a dump hierarchy (see <A HREF="#HDRWQ267">Defining and Displaying the Dump Hierarchy</A>)
+<P><LI>Labeling tapes (see <A HREF="#HDRWQ272">Writing and Reading Tape Labels</A>)
+<P><LI>Creating a device configuration file to automate the backup process (see <A HREF="#HDRWQ275">Automating and Increasing the Efficiency of the Backup Process</A>)
+</UL>
+<P>If you have already configured all of the components required for
+performing a backup dump or restore operation, you can proceed to the
+instructions in <A HREF="auagd012.htm#HDRWQ296">Backing Up Data</A> and <A HREF="auagd012.htm#HDRWQ306">Restoring and Recovering Data</A>.
+<HR><H2><A NAME="HDRWQ258" HREF="auagd002.htm#ToC_282">Configuring the tapeconfig File</A></H2>
+<A NAME="IDX6844"></A>
+<A NAME="IDX6845"></A>
+<A NAME="IDX6846"></A>
+<A NAME="IDX6847"></A>
+<A NAME="IDX6848"></A>
+<P>Several factors interact to determine how much data the Tape Coordinator
+can fit on a tape:
+<UL>
+<P><LI>The tape's capacity (size), as set by the tape manufacturer.
+<P><LI>The tape device's filemark size, as set by the tape device's
+manufacturer. Recall from <A HREF="#HDRWQ254">Tape Labels, Dump Labels, and EOF Markers</A> that the Tape Coordinator writes a filemark between the data
+from each volume in a dump. If a dump contains a small amount of data
+from each of a large number of volumes, as incremental dumps often do, then
+the filemark size can significantly affect how much volume data fits on the
+tape.
+<P><LI>Whether or not you use the tape device's compression mode.
+</UL>
+<P>(The amount of data that can fit in a backup data file is determined by
+amount of space available on the partition, and the operating system's
+maximum file size. The Tape Coordinator does not write filemarks when
+writing to a backup data file. For further information about
+configuring a Tape Coordinator to write to a backup data file, see <A HREF="#HDRWQ282">Dumping Data to a Backup Data File</A>.)
+<P>As the Tape Coordinator (<B>butc</B>) process initializes, it reads the
+<B>/usr/afs/backup/tapeconfig</B> file on its local disk to learn the tape
+capacity and filemark size (for a tape device) or the file size (for a backup
+data file) to use for dump operations. When you begin a dump operation,
+the Tape Coordinator also reads the tape or backup data file's label to
+see if you have recorded a different tape capacity or file size. If you
+have, the value on the label overrides the default value from the
+<B>tapeconfig</B> file.
+<P>As the Tape Coordinator writes data to a tape during a dump operation, it
+uses the capacity and filemark information to track how much tape it has used
+and how much remains before the physical end-of-tape (EOT). Shortly
+before reaching EOT, the Tape Coordinator stops writing and requests a new
+tape. Similarly, it uses a backup data file's size to know when it
+is about to exhaust the space in the file. If the Tape Coordinator
+reaches the EOT unexpectedly, it recovers by obtaining a new tape and writing
+to it the entire contents of the volume it was writing when it reached
+EOT. The interrupted volume remains on the first tape, but is never
+used.
+<P>Many tape devices use tapes that can accommodate multiple gigabytes, or
+even multiple terabytes, of backup data, especially if you use the
+device's compression mode. When writing to such devices and tapes,
+allowing the Tape Coordinator to hit the EOT unexpectedly is generally
+recommended. The devices write data so quickly that it usually does not
+take much extra time to rewrite the interrupted volume on the new tape.
+Similarly, they compress data so well that the data abandoned on the first
+tape from the interrupted volume does not constitute a waste of much
+tape.
+<P>When writing to tapes that accommodate a smaller amount of data (say, less
+than two GB), it is better to avoid having the Tape Coordinator hit EOT
+unexpectedly. AFS supports volumes up to 2 GB in size, so an
+interrupted volume can in fact take up most of the tape. For such
+tapes, recording accurate values for tape capacity and filemark size, if
+possible, helps to maximize both use of tape and the efficiency of dump
+operations. The following discussion of the fields in the
+<B>tapeconfig</B> file explains how to determine the appropriate
+values.
+<P>Use a text editor to create an entry in a Tape Coordinator's
+<B>tapeconfig</B> file for each tape device or backup data file that it
+uses. Each device or file's entry is on its own line and has the
+following format:
+<PRE> [<VAR>capacity</VAR> <VAR>filemark_size</VAR>] <VAR>device_name</VAR> <VAR>port_offset</VAR>
+</PRE>
+<P>where
+<DL>
+<P><DT><B><VAR>capacity</VAR>
+</B><DD>Specifies the capacity of the tapes used with a tape device, or the amount
+of data to write into a backup data file. Specify an integer value
+followed by a letter that indicates units, with no intervening space.
+The letter <B>k</B> or <B>K</B> indicates kilobytes, <B>m</B> or
+<B>M</B> indicates megabytes, <B>g</B> or <B>G</B> indicates
+gigabytes, and <B>t</B> or <B>T</B> indicates terabytes. If the
+units letter is omitted, the default is kilobytes.
+<P>To determine the capacity of a tape under two GB in size that you are going
+to use in regular (noncompression) mode, you can either use the value that the
+tape's manufacturer specifies on the tape's packaging or use the
+<B>fms</B> command to calculate the capacity, as described later in this
+section. To avoid having the Tape Coordinator reach the EOT
+unexpectedly, it is best to record in the <B>tapeconfig</B> file or on the
+label a capacity that is about 10% smaller than the actual capacity of the
+tape. To calculate the appropriate value for a small tape used in
+compression mode, one method is to multiply the tape capacity (as recorded by
+the manufacturer) by the device's compression ratio.
+<P>For tapes that hold multiple gigabytes or terabytes of data, or if using a
+tape drive's compression mode, the recommended configuration is to record
+a value quite a bit (for instance, two times) larger than the maximum amount
+you believe can fit on the tape. It is not generally worthwhile to run
+the <B>fms</B> command on large tapes, even in noncompression mode.
+The command definitely does not yield accurate results in compression
+mode. The Tape Coordinator is likely to reach the EOT unexpectedly, but
+compression mode fits so much data on the tape that the data abandoned from an
+interrupted volume does not represent much of the tape's capacity.
+<P>For a backup data file, record a value slightly smaller than the amount of
+space available on the partition, and definitely smaller than the operating
+system's maximum file size. It is also best to limit the ability
+of other processes to write to the partition, to prevent them from using up
+the space in the partition.
+<P>If this field is empty, the Tape Coordinator uses the maximum acceptable
+value (2048 GB or 2 TB). Either leave both this field and the
+<VAR>filemark_size</VAR> field empty, or provide a value in both of them.
+<P><DT><B><VAR>filemark_size</VAR>
+</B><DD>Specifies the tape device's filemark size, which usually falls
+between 2 KB and 2 MB. Use the same notation as for the
+<VAR>capacity</VAR> field, but note that if you omit the units letter, the
+default unit is bytes rather than kilobytes.
+<P>For a tape device in regular (noncompression) mode, you can use the
+<B>fms</B> command to determine filemark size, or use the value reported
+by the device's manufacturer. To help the Tape Coordinator avoid
+reaching EOT unexpectedly, increase the value by about 10% when recording it
+in the <B>tapeconfig</B> file.
+<P>The recommended value for a tape device in compression mode is <B>0</B>
+(zero). The <B>fms</B> command does not yield accurate results in
+compression mode, so you cannot use it to determine the filemark size.
+<P>The recommended value for a backup data file is also <B>0</B>
+(zero). The Tape Coordinator does not use filemarks when writing to a
+file, but a value must appear in this field nevertheless if there is also a
+value in the <VAR>capacity</VAR> field.
+<P>If this field is empty, the Tape Coordinator uses the value <B>0</B>
+(zero). Either leave both this field and the <VAR>capacity</VAR> field
+empty, or provide a value in both of them.
+<P><DT><B><VAR>device_name</VAR>
+</B><DD>Specifies the complete pathname of the tape device or backup data
+file. The format of tape device names depends on the operating system,
+but on UNIX systems, device names generally begin with the string
+<B>/dev/</B>. For a backup data file, this field defines the
+complete pathname, but for suggestions on how to name a backup data file, see <A HREF="#HDRWQ282">Dumping Data to a Backup Data File</A>.
+<P><DT><B><VAR>port_offset</VAR>
+</B><DD>Specifies the port offset number for a specific tape device or backup data
+file. Each tape device listens for backup requests on a different UNIX
+port. You pick the port indirectly by recording a value in this
+field. The Backup System sets the device's actual port by adding
+the port offset to a base port number that it determines internally.
+<P>Legal values are the integers <B>0</B> through <B>58510</B> (the
+Backup System can track a maximum of 58,511 port offset numbers). Each
+value must be unique among the cell's Tape Coordinators, but you do not
+have to assign port offset numbers sequentially, and you can associate any
+number of them with a single machine or even tape device. For example,
+if you plan to use a device in both compression and noncompression mode,
+assign it two different port offsets with appropriate tape capacity and
+filemark values for the different modes.
+<P>Assign port offset <B>0</B> (zero) to the Tape Coordinator for the tape
+device or backup data file that you use most often for backup operations;
+doing so enables you to omit the <B>-portoffset</B> argument from the
+largest possible number of <B>backup</B> commands.
+</DL>
+<P>The following example <B>tapeconfig</B> file includes entries for two
+tape devices, <B>/dev/rmt0h</B> and <B>/dev/rmt1h</B>. Each one
+uses tapes with a capacity of 2 GB and has a filemark size of 1 MB.
+Their port offset numbers are <TT>0</TT> and <TT>1</TT>.
+<PRE> 2g 1m /dev/rmt0h 0
+ 2G 1M /dev/rmt1h 1
+</PRE>
+<P>The <B>fms</B> command reports the capacity of the tape you have
+inserted and the tape device's filemark size, both on the standard output
+stream (stdout) and in its <B>fms.log</B> file, which it writes in
+the current working directory. The command interpreter must write data
+to the entire tape, so running the command can take from several hours to more
+than a day, depending on the size of the tape.
+<P><H3><A NAME="HDRWQ259" HREF="auagd002.htm#ToC_283">To run the fms command on a noncompressing tape device</A></H3>
+<A NAME="IDX6849"></A>
+<A NAME="IDX6850"></A>
+<A NAME="IDX6851"></A>
+<A NAME="IDX6852"></A>
+<A NAME="IDX6853"></A>
+<OL TYPE=1>
+<P><LI>If an <B>fms.log</B> file does not already exist in the current
+directory, verify that you can insert and write to files in the current
+directory. If the log file already exists, you must be able to write to
+the file.
+<P><LI>Insert a tape into the drive. Running the command completely
+overwrites the tape, so use a blank tape or one that you want to
+recycle.
+<P><LI>Issue the <B>fms</B> command.
+<PRE> % <B>fms</B> <<VAR>tape special file</VAR>>
+</PRE>
+<P>where
+<DL>
+<P><DT><B>fms
+</B><DD>Must be typed in full.
+<P><DT><B><VAR>tape special file</VAR>
+</B><DD>Specifies the tape device's UNIX device name, such as
+<B>/dev/rmt0h</B>.
+</DL>
+</OL>
+<P>The following example output reports that the tape in the device with
+device name <B>/dev/rmt0h</B> has a capacity of 2136604672 bytes (about 2
+GB), and that the device's filemark size is 1910205 bytes (close to 2
+MB).
+<PRE> % <B>fms /dev/rmt0h</B>
+ wrote block: 130408
+ Finished data capacity test - rewinding
+ wrote 1109 blocks, 1109 file marks
+ Finished file mark test
+ Tape capacity is 2136604672 bytes
+ File marks are 1910205 bytes
+</PRE>
+<HR><H2><A NAME="HDRWQ260" HREF="auagd002.htm#ToC_284">Granting Administrative Privilege to Backup Operators</A></H2>
+<P>Each person who issues the <B>backup</B> and
+<B>butc</B> commands in your cell must be listed in the
+<B>/usr/afs/etc/UserList</B> file on every database server machine that
+stores the Backup Database and Volume Location Database (VLDB), and every
+machine that houses a volume included in a volume set. By convention,
+the <B>UserList</B> file is the same on every server machine in the
+cell; the instructions in this document assume that your cell is
+configured in this way. To edit the <B>UserList</B> file, use the
+<B>bos adduser</B> and <B>bos removeuser</B> commands as described in <A HREF="auagd021.htm#HDRWQ592">Administering the UserList File</A>.
+<P>In addition to being listed in the <B>UserList</B> file, backup
+operators who issue the <B>butc</B> command must be able to write to the
+files stored in each Tape Coordinator machine's local
+<B>/usr/afs/backup</B> directory, which are protected by UNIX mode
+bits. Before configuring your cell's first Tape Coordinator
+machine, decide which local user and group to designate as the owner of the
+directory and the files in it. Among the possible ownership options are
+the following:
+<UL>
+<P><LI>The local superuser <B>root</B>. With this option, the issuer
+of the <B>butc</B> command must log onto the local file system as the
+local superuser <B>root</B>. If the Tape Coordinator is also a
+server machine, the <B>-localauth</B> flag is used on the <B>butc</B>
+command to construct a server ticket from the local
+<B>/usr/afs/etc/KeyFile</B> file. On non-server machine, the issuer
+must issue the <B>klog</B> command to authenticate as an AFS administrator
+while logged in as <B>root</B>.
+<P><LI>A single AFS administrator. Logging in and authenticating are a
+single step if an AFS-modified login utility is used. The administrator
+is the only user who can start the Tape Coordinator.
+<P><LI>An administrative account for which several operators know the
+password. This allows them all to start the Tape Coordinator.
+</UL>
+<P>Another option is to define a group in the local group file
+(<B>/etc/group</B> or equivalent) to which all backup operators
+belong. Then turn on the <B>w</B> mode bit (<B>write</B>
+permission) in the group mode bits rather than the user mode bits of the
+<B>/usr/afs/backup</B> directory and files in it. An advantage over
+the methods listed previously is that each operator can retain an individual
+administrative account for finer granularity in auditing.
+<P>For instructions on implementing your choice of protection methods, see <A HREF="#HDRWQ261">Configuring Tape Coordinator Machines and Tape Devices</A>.
+<HR><H2><A NAME="HDRWQ261" HREF="auagd002.htm#ToC_285">Configuring Tape Coordinator Machines and Tape Devices</A></H2>
+<A NAME="IDX6854"></A>
+<A NAME="IDX6855"></A>
+<A NAME="IDX6856"></A>
+<A NAME="IDX6857"></A>
+<P>This section explains how to configure a machine as a Tape Coordinator
+machine, and how to configure or remove the Tape Coordinator associated with a
+single tape device or backup data file.
+<TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">When configuring a tape device attached to an AIX system, you must set the
+device's tape block size to <B> 0</B> (zero) to indicate variable
+block size. If you do not, it is possible that devices attached to
+machines of other system types cannot read the tapes made on the AIX
+system. Use the AIX <B>smit</B> program to verify or change the
+value of the tape block size for a tape device, as instructed in Sep <A HREF="#LIWQ263">3</A>.
+</TD></TR></TABLE>
+<P><H3><A NAME="HDRWQ262" HREF="auagd002.htm#ToC_286">To configure a Tape Coordinator machine</A></H3>
+<OL TYPE=1>
+<P><LI>Verify that you are authenticated as a user listed in the
+<B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
+listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
+<PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
+</PRE>
+<P><LI>Become the local superuser <B>root</B> on the machine, if you are not
+already, by issuing the <B>su</B> command.
+<PRE> % <B>su root</B>
+ Password: <VAR>root_password</VAR>
+</PRE>
+<P><LI><A NAME="LIWQ263"></A>Install one or more tape devices on the Tape Coordinator
+machine according to the manufacturer's instructions. The Backup
+System can track a maximum of 58,511 tape devices or backup data files per
+cell.
+<P>If the Tape Coordinator machine is an AIX system, issue the following
+command to change the tape device's tape block size to <B>0</B>
+(zero), which indicates variable block size. Repeat for each tape
+device.
+<PRE> # <B>chdev -l '</B><VAR>device_name</VAR><B>' -a block_size='0'</B>
+</PRE>
+<P>where <VAR>device_name</VAR> is the tape device's device name (for
+example, <B>/dev/rmt0h</B>).
+<P><LI>Verify that the binary files for the <B>backup</B>, <B>butc</B>,
+and <B>fms</B> commands are available on the local disk. If the
+machine is an AFS client, the conventional location is the
+<B>/usr/afsws/etc</B> directory.
+<PRE> # <B>ls /usr/afsws/etc</B>
+</PRE>
+<P><LI>Create the <B>/usr/afs</B> directory. (If the Tape Coordinator
+machine is also configured as a file server machine, this directory already
+exists.) Then create the <B>/usr/afs/backup</B> directory.
+<PRE> # <B>mkdir /usr/afs</B>
+ # <B>mkdir /usr/afs/backup</B>
+</PRE>
+<P><LI>Use a text editor to create the <B>/usr/afs/backup/tapeconfig</B>
+file. Include a single line for each tape device or backup data file,
+specifying the following information in the indicated order. For syntax
+details and suggestions on the values to use in each field, see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>.
+<UL>
+<P><LI>The capacity of tapes to be used in the device, or the size of the backup
+data file
+<P><LI>The device's filemark size
+<P><LI>The device's device name, starting with the string <B>/dev/</B>
+<P><LI>The device's port offset number
+</UL>
+<A NAME="IDX6858"></A>
+<A NAME="IDX6859"></A>
+<A NAME="IDX6860"></A>
+<A NAME="IDX6861"></A>
+<P><LI>Decide which user and group are to own the <B>/usr/afs/backup</B>
+directory and <B>/usr/afs/backup/tapeconfig</B> file, based on the
+suggestions in <A HREF="#HDRWQ260">Granting Administrative Privilege to Backup Operators</A>. Correct the UNIX mode bits on the directory and
+file, if necessary.
+<PRE> # <B>chown</B> <VAR>admin_owner</VAR> <B>/usr/afs/backup</B>
+ # <B>chown</B> <VAR>admin_owner</VAR> <B>/usr/afs/backup/tapeconfig</B>
+ # <B>chgrp</B> <VAR>admin_group</VAR> <B>/usr/afs/backup</B>
+ # <B>chgrp</B> <VAR>admin_group</VAR> <B>/usr/afs/backup/tapeconfig</B>
+ # <B>chmod 774 /usr/afs/backup</B>
+ # <B>chmod 664 /usr/afs/backup/tapeconfig</B>
+</PRE>
+<A NAME="IDX6862"></A>
+<A NAME="IDX6863"></A>
+<A NAME="IDX6864"></A>
+<A NAME="IDX6865"></A>
+<P><LI><A NAME="LICONFTC-ADDHOST"></A>Issue the <B>backup addhost</B> command to create
+a Tape Coordinator entry in the Backup Database. Repeat the command for
+each Tape Coordinator.
+<PRE> # <B>backup addhost</B> <<VAR>tape machine name</VAR>> [<<VAR>TC port offset</VAR>>]
+</PRE>
+<P>where
+<DL>
+<P><DT><B>addh
+</B><DD>Is the shortest acceptable abbreviation of <B>addhost</B>.
+<P><DT><B><VAR>tape machine name</VAR>
+</B><DD>Specifies the Tape Coordinator machine's fully qualified
+hostname.
+<P><DT><B><VAR>TC port offset</VAR>
+</B><DD>Specifies the tape device's port offset number. Provide the
+same value as you specified for the device in the <B>tapeconfig</B>
+file. You must provide this argument unless the default value of 0
+(zero) is appropriate.
+</DL>
+</OL>
+<P><H3><A NAME="Header_287" HREF="auagd002.htm#ToC_287">To configure an additional Tape Coordinator on an existing Tape Coordinator machine</A></H3>
+<OL TYPE=1>
+<P><LI>Verify that you are authenticated as a user listed in the
+<B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
+listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
+<PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
+</PRE>
+<P><LI>Become the local superuser <B>root</B> on the machine, if you are not
+already, by issuing the <B>su</B> command.
+<PRE> % <B>su root</B>
+ Password: <VAR>root_password</VAR>
+</PRE>
+<P><LI>Install the tape device on the Tape Coordinator machine according to the
+manufacturer's instructions.
+<P>If the Tape Coordinator machine is an AIX system, issue the following
+command to change the tape device's tape block size to <B>0</B>
+(zero), which indicates variable block size.
+<PRE> # <B>chdev -l '</B><VAR>device_name</VAR><B>' -a block_size='0'</B>
+</PRE>
+<P><LI>Choose the port offset number to assign to the tape device. If
+necessary, use the <B>backup listhosts</B> command to display the port
+offset numbers that are already used; for a discussion of the output, see
+<A HREF="#HDRWQ264">To display the list of configured Tape Coordinators</A>.
+<PRE> # <B>backup listhosts</B>
+</PRE>
+<P>where <B>listh</B> is the shortest acceptable abbreviation of
+<B>listhosts</B>.
+<P><LI>Use a text editor to add one or more entries for the device to the
+<B>/usr/afs/backup/tapeconfig</B> file. Specify the following
+information in the indicated order. For syntax details and suggestions
+on the values to use in each field, see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>.
+<UL>
+<P><LI>The capacity of tapes to be used in the device, or the size of the backup
+data file
+<P><LI>The device's filemark size
+<P><LI>The device's device name, starting with the string <B>/dev/</B>
+<P><LI>The device's port offset number
+</UL>
+<P><LI>Issue the <B>backup addhost</B> command to create an entry in the
+Backup Database for the Tape Coordinator. For complete syntax, see Step
+<A HREF="#LICONFTC-ADDHOST">8</A> in <A HREF="#HDRWQ262">To configure a Tape Coordinator machine</A>.
+<PRE> # <B>backup addhost</B> <<VAR>tape machine name</VAR>> [<<VAR>TC port offset</VAR>>]
+</PRE>
+</OL>
+<A NAME="IDX6866"></A>
+<A NAME="IDX6867"></A>
+<A NAME="IDX6868"></A>
+<A NAME="IDX6869"></A>
+<P><H3><A NAME="Header_288" HREF="auagd002.htm#ToC_288">To unconfigure a Tape Coordinator</A></H3>
+<OL TYPE=1>
+<P><LI>Verify that you are authenticated as a user listed in the
+<B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
+listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
+<PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
+</PRE>
+<P><LI>Using a text editor, remove each of the Tape Coordinator's entries
+from the <B>/usr/afs/backup/tapeconfig</B> file.
+<P><LI>Issue the <B>backup delhost</B> command to delete the Tape
+Coordinator's Backup Database entry.
+<PRE> % <B>backup delhost</B> <<VAR>tape machine name</VAR>> [<<VAR>TC port offset</VAR>>]
+</PRE>
+<P>where
+<DL>
+<P><DT><B>delh
+</B><DD>Is the shortest acceptable abbreviation of <B>delhost</B>.
+<P><DT><B><VAR>tape machine name</VAR>
+</B><DD>Is the complete Internet host name of the Tape Coordinator machine.
+<P><DT><B><VAR>TC port offset</VAR>
+</B><DD>Is the same port offset number removed from the <B>tapeconfig</B>
+file. You must provide this argument unless the default value of
+<B>0</B> (zero) is appropriate.
+</DL>
+</OL>
+<A NAME="IDX6870"></A>
+<A NAME="IDX6871"></A>
+<A NAME="IDX6872"></A>
+<A NAME="IDX6873"></A>
+<P><H3><A NAME="HDRWQ264" HREF="auagd002.htm#ToC_289">To display the list of configured Tape Coordinators</A></H3>
+<OL TYPE=1>
+<P><LI>Issue the <B>backup listhosts</B> command to list the Tape
+Coordinators and port offset numbers currently configured in the Backup
+Database.
+<PRE> % <B>backup listhosts</B>
+</PRE>
+<P>where
+<DL>
+<P><DT><B>listh
+</B><DD>Is the shortest acceptable abbreviation of <B>listhosts</B>.
+</DL>
+</OL>
+<P>The output lists each Tape Coordinator machine and the port offset numbers
+currently allocated to it in the Backup Database. The appearance of a
+port offset number does not imply that the associated Tape Coordinator is
+actually running. Machine names appear in the format in which they were
+specified with the <B>backup addhost</B> command.
+<P>The following example output lists the Tape Coordinators currently defined
+in the Backup Database of the ABC Corporation cell:
+<PRE> % <B>backup listhosts</B>
+ Tape hosts:
+ Host backup1.abc.com, port offset 0
+ Host backup1.abc.com, port offset 2
+ Host backup2.abc.com, port offset 1
+ Host backup2.abc.com, port offset 3
+</PRE>
+<HR><H2><A NAME="HDRWQ265" HREF="auagd002.htm#ToC_290">Defining and Displaying Volume Sets and Volume Entries</A></H2>
+<P>The Backup System handles data at the level of volumes
+rather than individual files. You must define groups of volumes called
+<I>volume sets</I> before performing backup operations, by using the
+<B>backup addvolset</B> command. A volume set name can be up to 31
+characters long and can include any character other than the period
+(<B>.</B>), but avoid using metacharacters that have special
+meanings to the shell.
+<P>After creating a volume set, use the <B>backup addvolentry</B> command
+to place one or more <I>volume entries</I> in it. They define the
+volumes that belong to it in terms of their location (file server machine and
+partition) and name. Use the command's required <B>-server</B>
+argument to designate the file server machine that houses the volumes of
+interest and its required <B>-partition</B> argument to designate the
+partition. Two types of values are acceptable:
+<UL>
+<P><LI>The fully qualified hostname of one machine or full name of one partition
+(such as <B>/vicepm</B>)
+<P><LI>The regular expression <B>.*</B> (period and asterisk), which
+matches every machine name or partition name in the VLDB
+</UL>
+<P>For the volume name (the required <B>-volume</B> argument), specify a
+combination of alphanumeric characters and one or more metacharacters to
+specify part or all of the volume name with a wildcard. You can use any
+of the following metacharacters in the volume name field:
+<A NAME="IDX6874"></A>
+<A NAME="IDX6875"></A>
+<DL>
+<P><DT><B>.
+</B><DD>The period matches any single character.
+<P><DT><B>*
+</B><DD>The asterisk matches zero or more instances of the preceding
+character. Combine it with any other alphanumeric character or
+metacharacter.
+<P><DT><B>[ ]
+</B><DD>Square brackets around a list of characters match a single instance of any
+of the characters, but no other characters; for example, <B>[abc]</B>
+matches a single <B>a</B> or <B>b</B> or <B>c</B>, but not
+<B>d</B> or <B>A</B>. You can combine this expression with the
+asterisk.
+<P><DT><B>^
+</B><DD>The caret, when used as the first character in a square-bracketed set,
+designates a match with any single character other than the characters that
+follow it; for example, <B>[^a]</B> matches any single character
+except lowercase <B>a</B>. You can combine this expression with the
+asterisk.
+<P><DT><B>\
+</B><DD>A backslash preceding any of the metacharacters in this list makes it
+match its literal value only. For example, the expression
+<B>\.</B> (backslash and period) matches a single period,
+<B>\*</B> matches a single asterisk, and <B>\\</B> matches a single
+backslash. You can combine such expressions with the asterisk (for
+example, <B>\.*</B> matches any number of periods).
+</DL>
+<P>Perhaps the most common regular expression is the period followed by an
+asterisk (<B>.*</B>). This expression matches any string of
+any length, because the period matches any character and the asterisk means
+any number of that character. As mentioned, it is the only acceptable
+regular expression in the file server and partition fields of a volume
+entry. In the volume name field, it can stand alone (in which case it
+matches every volume listed in the VLDB), or can combine with alphanumeric
+characters. For example, the string
+<B>user.*\.backup</B> matches any volume name that begins
+with the string <B>user</B> and ends with
+<B>.backup</B>.
+<P>Issuing the <B>backup addvolentry</B> command in interactive mode is
+simplest. If you issue it at the shell prompt, you must surround any
+string that includes a regular expression with double quotes (<B>" "</B>)
+so that the shell passes them uninterpreted to the <B>backup</B> command
+interpreter rather than resolving them.
+<P>To define various combinations of volumes, provide the following types of
+values for the <B>backup addvolentry</B> command's three
+arguments. The list uses the notation appropriate for interactive
+mode; if you issue the command at the shell prompt instead, place double
+quotes around any string that includes a regular expression. To create
+a volume entry that includes:
+<UL>
+<P><LI>All volumes listed in the VLDB, use the regular expression
+<B>.*</B> for all three arguments (<B>-server .*
+-partition .* -volume .*</B>)
+<P><LI>Every volume on a specific file server machine, specify its fully
+qualified hostname as the <B>-server</B> argument and use the regular
+expression <B>.*</B> for the <B>-partition</B> and
+-<B>volume</B> arguments (for example: <B>-server
+fs1.abc.com -partition .* -volume .*</B>)
+<P><LI>All volumes that reside on a partition with the same name on various file
+server machines, specify the complete partition name as the
+<B>-partition</B> argument and use the regular expression
+<B>.*</B> for the <B>-server</B> and <B>-volume</B>
+arguments (for example: <B>-server .* -partition /vicepd
+-volume .*</B>)
+<P><LI>Every volume with a common string in its name, use the regular expression
+<B>.*</B> for the <B>-server</B> and <B>-partition</B>
+arguments, and provide a combination of alphanumeric characters and
+metacharacters as the <B>-volume</B> argument (for example:
+<B>-server .* -partition .* -volume
+.*\.backup</B> includes all volumes whose names end in the
+string <B>.backup</B>).
+<P><LI>All volumes on one partition, specify the machine's fully qualified
+hostname as the <B>-server</B> argument and the full partition name as the
+<B>-partition</B> argument, and use the regular expression
+<B>.*</B> for the <B>-volume</B> argument (for example:
+<B>-server fs2.abc.com -partition /vicepb -volume
+.*</B>).
+<P><LI>A single volume, specify its complete name as the <B>-volume</B>
+argument. To bypass the potentially time-consuming search through the
+VLDB for matching entries, you can specify an actual machine and partition
+name for the <B>-server</B> and <B>-partition</B> arguments
+respectively. However, if it is possible that you need to move the
+volume in future, it is best to use the regular expression
+<B>.*</B> for the machine and partition name.
+</UL>
+<P>As you create volume sets, define groups of volumes you want to dump to the
+same tape at the same time (for example, weekly or daily) and in the same
+manner (fully or incrementally). In general, a volume set that includes
+volumes with similar contents (as indicated by similar names) is more useful
+than one that includes volumes that share a common location, especially if you
+often move volumes for load-balancing or space reasons. Most often,
+then, it is appropriate to use the regular expression <B>.*</B>
+(period followed by a backslash) for the <B>-server</B> and
+<B>-partition</B> arguments to the <B>backup addvolentry</B>
+command.
+<P>It is generally more efficient to include a limited number of volumes in a
+volume entry. Dumps of a volume set that includes a large number of
+volume can take a long time to complete, increasing the possibility that the
+operation fails due to a service interruption or outage.
+<P>To remove a volume entry from a volume set, use the <B>backup
+delvolentry</B> command. To remove a volume set and all of its
+component volume entries from the Backup Database, use the <B>backup
+delvolset</B> command. To display the volume entries in a volume set,
+use the <B>backup listvolsets</B> command.
+<P>By default, a Backup Database record is created for the new volume
+set. Sometimes it is convenient to create volume sets without recording
+them permanently in the Backup Database, for example when using the
+<B>backup volsetrestore</B> command to restore a group of volumes that
+were not necessarily backed up together (for further discussion, see <A HREF="auagd012.htm#HDRWQ312">Using the backup volsetrestore Command</A>). To create a <I>temporary</I> volume set,
+include the <B>-temporary</B> flag to the <B>backup addvolset</B>
+command. A temporary volume set exists only during the lifetime of the
+current interactive session, so the flag is effective only when used during an
+interactive session (opened by issuing the <B>backup (interactive)</B>
+command). You can use the <B>backup delvolset</B> command to delete
+a temporary volume set before the interactive session ends, if you wish, but
+as noted it is automatically deleted when you end the session. One
+advantage of temporary volume sets is that the <B>backup addvolset</B>
+command, and any <B>backup addvolentry</B> commands subsequently used to
+add volume entries to it, complete more quickly than for regular volume sets,
+because you are not creating any Backup Database records.
+<A NAME="IDX6876"></A>
+<A NAME="IDX6877"></A>
+<A NAME="IDX6878"></A>
+<A NAME="IDX6879"></A>
+<P><H3><A NAME="Header_291" HREF="auagd002.htm#ToC_291">To create a volume set</A></H3>
+<OL TYPE=1>
+<P><LI>Verify that you are authenticated as a user listed in the
+<B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
+listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
+<PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
+</PRE>
+<P><LI><B>(Optional)</B> Issue the <B>backup</B> command to enter
+interactive mode. If you are going to define volume entries right away
+with the <B>backup addvolentry</B> command, this eliminates the need to
+surround metacharacter expressions with double quotes. You must enter
+interactive mode if creating a temporary volume set.
+<PRE> % <B>backup</B>
+</PRE>
+<P><LI>Issue the <B>(backup) addvolset</B> command to create the volume
+set. You must then issue the <B>(backup) addvolentry</B> command to
+define volume entries in it.
+<PRE> backup> <B>addvolset</B> <<VAR>volume set name</VAR>> [<B>-temporary</B>]
+</PRE>
+<P>where
+<DL>
+<P><DT><B>addvols
+</B><DD>Is the shortest acceptable abbreviation of <B>addvolset</B>.
+<P><DT><B><VAR>volume set name</VAR>
+</B><DD>Names the volume set. The name can include no more than 31
+characters, cannot include periods, and must be unique within the Backup
+Database. (A temporary volume set can have the same name as an existing
+permanent volume set, but this is not recommended because of the confusion it
+can cause.)
+<P><DT><B>-temporary
+</B><DD>Creates a temporary volume set, which exists only during the current
+interactive session.
+</DL>
+</OL>
+<A NAME="IDX6880"></A>
+<A NAME="IDX6881"></A>
+<A NAME="IDX6882"></A>
+<A NAME="IDX6883"></A>
+<P><H3><A NAME="Header_292" HREF="auagd002.htm#ToC_292">To add a volume entry to a volume set</A></H3>
+<OL TYPE=1>
+<P><LI>Verify that you are authenticated as a user listed in the
+<B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
+listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
+<PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
+</PRE>
+<P><LI><B>(Optional)</B> Issue the <B>backup</B> command to enter
+interactive mode if you have not already. This makes it simpler to use
+metacharacter expressions, because you do not need to surround them with
+double quotes. If you are adding entries to a temporary volume set, you
+must already have entered interactive mode before creating the volume
+set.
+<PRE> % <B>backup</B>
+</PRE>
+<P><LI>Issue the <B>(backup) addvolentry</B> command to define volume entries
+in an existing volume set. The Backup System assigns each volume entry
+an index within the volume set, starting with 1 (one).
+<PRE> backup> <B>addvolentry -name</B> <<VAR>volume set name</VAR>> \
+ <B>-server</B> <<VAR>machine name</VAR>> \
+ <B>-partition</B> <<VAR>partition name</VAR>> \
+ <B>-volumes</B> <<VAR>volume name (regular expression)</VAR>>
+</PRE>
+<P>where
+<DL>
+<P><DT><B>addvole
+</B><DD>Is the shortest acceptable abbreviation of <B>addvolentry</B>.
+<P><DT><B>-name
+</B><DD>Names the volume set to which to add the volume entry. It must
+already exist (use the <B>backup addvolset</B> command to create
+it).
+<P><DT><B>-server
+</B><DD>Defines the set of one or more file server machines that house the volumes
+in the volume entry. Provide either one fully-qualified hostname (such
+as <B>fs1.abc.com</B>) or the metacharacter expression
+<B>.*</B> (period and asterisk), which matches all machine names in
+the VLDB.
+<P><DT><B>-partition
+</B><DD>Defines the set of one or more partitions that house the volumes in the
+volume entry. Provide either one complete partition name (such as
+<B>/vicepa</B>) or the metacharacter expression <B>.*</B>
+(period and asterisk), which matches all partition names.
+<P><DT><B>-volumes
+</B><DD>Defines the set of one or more volumes included in the volume entry,
+identifying them by name. This argument can include a combination of
+alphanumeric characters and one or more of the metacharacter expressions
+discussed in the introductory material in this section.
+</DL>
+</OL>
+<A NAME="IDX6884"></A>
+<A NAME="IDX6885"></A>
+<A NAME="IDX6886"></A>
+<A NAME="IDX6887"></A>
+<A NAME="IDX6888"></A>
+<A NAME="IDX6889"></A>
+<P><H3><A NAME="HDRWQ266" HREF="auagd002.htm#ToC_293">To display volume sets and volume entries</A></H3>
+<OL TYPE=1>
+<P><LI>Issue the <B>backup listvolsets</B> command to display the volume
+entries in a specific volume set or all of them. If you are displaying
+a temporary volume set, you must still be in the interactive session in which
+you created it.
+<PRE> % <B>backup listvolsets</B> [<<VAR>volume set name</VAR>>]
+</PRE>
+<P>where
+<DL>
+<P><DT><B>listv
+</B><DD>Is the shortest acceptable abbreviation of <B>listvolsets</B>.
+<P><DT><B><VAR>volume set name</VAR>
+</B><DD>Names the volume set to display. Omit this argument to display all
+defined volume sets.
+</DL>
+<P>The output from the command uses the wildcard notation used when the volume
+entries were created. The string <TT>(temporary)</TT> marks a
+temporary volume set. The following example displays all three of the
+volume sets defined in a cell's Backup Database, plus a temporary volume
+set <B>pat+jones</B> created during the current interactive session:
+<P>
+<PRE> backup> <B>listv</B>
+ Volume set pat+jones (temporary):
+ Entry 1: server fs1.abc.com, partition /vicepe, volumes: user.pat.backup
+ Entry 2: server fs5.abc.com, partition /viceph, volumes: user.jones.backup
+ Volume set user:
+ Entry 1: server .*, partition .*, volumes: user.*\.backup
+ Volume set sun:
+ Entry 1: server .*, partition .*, volumes: sun4x_55\..*
+ Entry 2: server .*, partition .*, volumes: sun4x_56\..*
+ Volume set rs:
+ Entry 1: server .*, partition .*, volumes: rs_aix42\..*
+</PRE>
+</OL>
+<A NAME="IDX6890"></A>
+<A NAME="IDX6891"></A>
+<A NAME="IDX6892"></A>
+<A NAME="IDX6893"></A>
+<P><H3><A NAME="Header_294" HREF="auagd002.htm#ToC_294">To delete a volume set</A></H3>
+<OL TYPE=1>
+<P><LI>Verify that you are authenticated as a user listed in the
+<B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
+listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
+<PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
+</PRE>
+<P><LI>Issue the <B>backup delvolset</B> command to delete one or more volume
+sets and all of the component volume entries in them. If you are
+deleting a temporary volume set, you must still be in the interactive session
+in which you created it.
+<PRE> % <B>backup delvolset</B> <<VAR>volume set name</VAR>><SUP>+</SUP>
+</PRE>
+<P>where
+<DL>
+<P><DT><B>delvols
+</B><DD>Is the shortest acceptable abbreviation of <B>delvolset</B>.
+<P><DT><B><VAR>volume set name</VAR>
+</B><DD>Names each volume set to delete.
+</DL>
+</OL>
+<A NAME="IDX6894"></A>
+<A NAME="IDX6895"></A>
+<A NAME="IDX6896"></A>
+<A NAME="IDX6897"></A>
+<A NAME="IDX6898"></A>
+<P><H3><A NAME="Header_295" HREF="auagd002.htm#ToC_295">To delete a volume entry from a volume set</A></H3>
+<OL TYPE=1>
+<P><LI>Verify that you are authenticated as a user listed in the
+<B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
+listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
+<PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
+</PRE>
+<P><LI>Issue the <B>backup</B> command to enter interactive mode.
+<PRE> % <B>backup</B>
+</PRE>
+<P><LI>If the volume set includes more than one volume entry, issue the
+<B>(backup) listvolsets</B> command to display the index number associated
+with each one (if there is only one volume entry, its index is 1). For
+a more detailed description of the command's output, see <A HREF="#HDRWQ266">To display volume sets and volume entries</A>.
+<PRE> backup> <B>listvolsets</B> <<VAR>volume set name</VAR>>
+</PRE>
+<P>where
+<DL>
+<P><DT><B>listv
+</B><DD>Is the shortest acceptable abbreviation of <B>listvolsets</B>.
+<P><DT><B><VAR>volume set name</VAR>
+</B><DD>Names the volume set for which to display volume entries.
+</DL>
+<P><LI>Issue the <B>(backup) delvolentry</B> command to delete the volume
+entry.
+<PRE> backup> <B>delvolentry</B> <<VAR>volume set name</VAR>> <<VAR>volume entry index</VAR>>
+</PRE>
+<P>where
+<DL>
+<P><DT><B>delvole
+</B><DD>Is the shortest acceptable abbreviation of <B>delvolentry</B>.
+<P><DT><B><VAR>volume set name</VAR>
+</B><DD>Names the volume set from which to delete a volume entry.
+<P><DT><B><VAR>volume entry index</VAR>
+</B><DD>Specifies the index number of the volume entry to delete.
+</DL>
+</OL>
+<HR><H2><A NAME="HDRWQ267" HREF="auagd002.htm#ToC_296">Defining and Displaying the Dump Hierarchy</A></H2>
+<A NAME="IDX6899"></A>
+<A NAME="IDX6900"></A>
+<P>A dump hierarchy is a logical structure in the Backup Database that defines
+the relationship between full and incremental dumps; that is, it defines
+which dump serves as the parent for an incremental dump. Each
+individual component of a hierarchy is a dump level.
+<P>As you define dump levels with the <B>backup adddump</B> command, keep
+the following rules and suggestions in mind:
+<UL>
+<P><LI>Each full dump level is the top level of a hierarchy. You can
+create as many hierarchies as you need to dump different volume sets on
+different schedules.
+<P><LI>The name of a full dump level consists of an initial slash (<B>/</B>),
+followed by a string of up to 28 alphanumeric characters.
+<P><LI>The name of an incremental dump level resembles a pathname, starting with
+the name of a full dump level, then the first incremental level, and so on,
+down to the final incremental level. Precede each level name with a
+slash to separate it from the preceding level. Like the full level,
+each component level in the name can have up to 28 alphanumeric characters,
+not including the slash.
+<P><LI>A hierarchy can have any have any number of levels, but the maximum length
+of a complete dump level name is 256 characters, including the slashes.
+<P><LI>Before defining a given incremental level, you must define all of the
+levels above it in the hierarchy.
+<P><LI>Do not use the period (<B>.</B>) in dump level names.
+The Backup System uses the period as the separator between a dump's
+volume set name and dump level name when it creates the dump name and AFS tape
+name. Any other alphanumeric and punctuation characters are allowed,
+but it is best to avoid metacharacters. If you include a metacharacter,
+you must precede it with a backslash (<B>\</B>) or surround the entire
+dump level name with double quotes (<B>" "</B>).
+<P><LI>Naming dump levels for days or other actual time points reminds you when
+to perform dumps, and makes it easier to track the relationship between dumps
+performed at different levels. However, the names have no meaning to
+the Backup System: it does not automatically create dumps according to
+the names, and does not prevent you from, for example, using the
+<B>/sunday</B> level when creating a dump on a Tuesday.
+<P><LI>It is best not to use the same name for more than one component level in a
+hierarchy, because it means the resulting dump name no longer indicates which
+level was used. For example, if you name a dump level
+<B>/full/incr/incr</B>, then the dump name and AFS tape name that result
+from dumping a volume set at the first incremental level
+(<B>/full/incr</B>) look the same as the names that result from dumping at
+the second incremental level (<B>/full/incr/incr</B>).
+<P><LI>Individual levels in different hierarchies can have the same name, but the
+complete pathnames must be unique. For example,
+<B>/sunday1/monday</B> and <B>/sunday2/monday</B> share the same name
+at the final level, but are unique because they have different names at the
+full level (belong to different hierarchies). However, using the same
+name in multiple hierarchies means that dump and AFS tape names do not
+unambiguously indicate which hierarchy was used.
+</UL>
+<P>The following example shows three hierarchies. Each begins with a
+full dump at the top: <B>sunday1</B> for the first hierarchy,
+<B>sunday2</B> for the second hierarchy, and <B>sunday_bin</B> for the
+third hierarchy. In all three hierarchies, each of the other dump
+levels is an incremental level.
+<PRE> /sunday1
+ /monday
+ /tuesday
+ /wednesday
+ /thursday
+ /friday
+ /sunday2
+ /monday
+ /tuesday
+ /wednesday
+ /thursday
+ /friday
+ /sunday_bin
+ /monday
+ /wednesday
+ /friday
+</PRE>
+<P>In the first hierarchy, each incremental dump level refers to the full
+level <B>/sunday1</B> as its parent. When (for example) you dump a
+volume set at the <B>/sunday1/wednesday</B> level, it includes data that
+has changed since the volume set was dumped at the <B>/sunday1</B>
+level.
+<P>In contrast, each incremental dump level in the second hierarchy refers to
+the immediately preceding dump level as its parent. When you dump a
+volume set at the corresponding level in the second hierarchy
+(<B>/sunday2/monday/tuesday/wednesday</B>), the dump includes only data
+that has changed since the volume set was dumped at the
+<B>/sunday2/monday/tuesday</B> level (presumably the day before).
+Assuming you create dumps on the indicated days, an incremental dump made
+using this hierarchy contains less data than an incremental dump made at the
+corresponding level in the first hierarchy.
+<P>The third hierarchy is more appropriate for dumping volumes for which a
+daily backup is excessive because the data does not change often (for example,
+system binaries).
+<P><H3><A NAME="HDRWQ268" HREF="auagd002.htm#ToC_297">Creating a Tape Recycling Schedule</A></H3>
+<A NAME="IDX6901"></A>
+<A NAME="IDX6902"></A>
+<A NAME="IDX6903"></A>
+<A NAME="IDX6904"></A>
+<A NAME="IDX6905"></A>
+<A NAME="IDX6906"></A>
+<A NAME="IDX6907"></A>
+<A NAME="IDX6908"></A>
+<P>If your cell is like most cells, you have a limited amount of room for
+storing backup tapes and a limited budget for new tapes. The easiest
+solution is to recycle tapes by overwriting them when you no longer need the
+backup data on them. The Backup System helps you implement a recycling
+schedule by enabling you to associate an expiration date with each dump
+level. The expiration date defines when a dump created at that level
+expires. Until that time the Backup System refuses to overwrite a tape
+that contains the dump. Thus, assigning expiration dates automatically
+determines how you recycle tapes.
+<P>When designing a tape-recycling schedule, you must decide how far in the
+past and to what level of precision you want to guarantee access to backed up
+data. For instance, if you decide to guarantee that you can restore a
+user's home volume to its state on any given day in the last two weeks,
+you cannot recycle the tape that contains a given daily dump for at least two
+weeks after you create it. Similarly, if you decide to guarantee that
+you can restore home volumes to their state at the beginning of any given week
+in the last month, you cannot recycle the tapes in a dump set containing a
+weekly dump for at least four weeks. The following example dump
+hierarchy implements this recycling schedule by setting the expiration date
+for each daily incremental dump to 13 days and the expiration date of the
+weekly full dumps to 27 days.
+<P>The tapes used to store dumps created at the daily incremental levels in
+the <B>/sunday1</B> hierarchy expire just in time to be recycled for daily
+dumps in the <B>/sunday3</B> hierarchy (and vice versa), and there is a
+similar relationship between the <B>/sunday2</B> and <B>/sunday4</B>
+hierarchies. Similarly, the tape that houses a full dump at the
+<B>/sunday1</B> level expires just in time to be used for a full dump on
+the first Sunday of the following month.
+<PRE>
+ /sunday1 expires in 27d
+ /monday1 expires in 13d
+ /tuesday1 expires in 13d
+ /wednesday1 expires in 13d
+ /thursday1 expires in 13d
+ /friday1 expires in 13d
+ /sunday2 expires in 27d
+ /monday2 expires in 13d
+ /tuesday2 expires in 13d
+ /wednesday2 expires in 13d
+ /thursday2 expires in 13d
+ /friday2 expires in 13d
+ /sunday3 expires in 27d
+ /monday1 expires in 13d
+ /tuesday1 expires in 13d
+ /wednesday1 expires in 13d
+ /thursday1 expires in 13d
+ /friday1 expires in 13d
+ /sunday4 expires in 27d
+ /monday2 expires in 13d
+ /tuesday2 expires in 13d
+ /wednesday2 expires in 13d
+ /thursday2 expires in 13d
+ /friday2 expires in 13d
+</PRE>
+<P>If you use appended dumps in your cell, keep in mind that all dumps in a
+dump set are subject to the latest (furthest into the future) expiration date
+associated with any of the constituent dumps. You cannot recycle any of
+the tapes that contain a dump set until all of the dumps have reached their
+expiration date. See also <A HREF="auagd012.htm#HDRWQ299">Appending Dumps to an Existing Dump Set</A>.
+<P>Most tape manufacturers recommend that you write to a tape a limited number
+of times, and it is best not to exceed this limit when recycling tapes.
+To help you track tape usage, the Backup System records a <TT>useCount</TT>
+counter on the tape's label. It increments the counter each time
+the tape's label is rewritten (each time you use the <B>backup
+labeltape</B> or <B>backup dump</B> command). To display the
+<TT>useCount</TT> counter, use the <B>backup readlabel</B> or
+<B>backup scantape</B> command or include the <B>-id</B> and
+<B>-verbose</B> options when you issue the <B>backup dumpinfo</B>
+command. For instructions see <A HREF="#HDRWQ272">Writing and Reading Tape Labels</A> or <A HREF="auagd012.htm#HDRWQ302">Displaying Backup Dump Records</A>.
+<A NAME="IDX6909"></A>
+<A NAME="IDX6910"></A>
+<A NAME="IDX6911"></A>
+<A NAME="IDX6912"></A>
+<P><H3><A NAME="HDRWQ269" HREF="auagd002.htm#ToC_298">Archiving Tapes</A></H3>
+<A NAME="IDX6913"></A>
+<A NAME="IDX6914"></A>
+<P>Even if you make extensive use of tape recycling, there is probably some
+backup data that you need to archive for a long (or even an indefinite) period
+of time. You can use the Backup System to archive data on a regular
+schedule, and you can also choose to archive data on tapes that you previously
+expected to recycle.
+<P>If you want to archive data on a regular basis, you can create
+date-specific dump levels in the dump hierarchy. For example, if you
+decide to archive a full dump of all data in your cell at the beginning of
+each quarter in the year 2000, you can define the following levels in the dump
+hierarchy:
+<PRE> /1Q2000
+ /2Q2000
+ /3Q2000
+ /4Q2000
+</PRE>
+<P>If you decide to archive data that is on tapes you previously planned to
+recycle, you must gather all of the tapes that contain the relevant dumps,
+both full and incremental. To avoid accidental erasure, it is best to
+set the switch on the tapes that makes them read-only, before placing them in
+your archive storage area. If the tapes also contain a large amount of
+extraneous data that you do not want to archive, you can restore just the
+relevant data into a new temporary volume, and back up that volume to the
+smallest number of tapes possible. One reason to keep a dump set small
+is to minimize the amount of irrelevant data in a dump set you end up needing
+to archive.
+<P>If you do not expect to restore archived data to the file system, you can
+consider using the <B>backup deletedump</B> command to remove the
+associated dump records from the Backup Database, which helps keep it to an
+efficient size. If you ever need to restore the data, you can use the
+<B>-dbadd</B> flag to the <B>backup scantape</B> command to reinsert
+the dump records into the database. For instructions, see <A HREF="auagd012.htm#HDRWQ305">To scan the contents of a tape</A>.
+<P><H3><A NAME="HDRWQ270" HREF="auagd002.htm#ToC_299">Defining Expiration Dates</A></H3>
+<P>To associate an expiration date with a dump level as you
+create it, use the <B>-expires</B> argument to the <B>backup
+adddump</B> command. To change an existing dump level's
+expiration date, use the <B>-expires</B> argument to the <B>backup
+setexp</B> command. (Note that it is not possible to change the
+expiration date of an actual dump that has already been created at that
+level). With both commands, you can define an expiration date either in
+absolute terms (for example, 13 January 2000) or relative terms (for example,
+30 days from when the dump is created).
+<UL>
+<P><LI>To define an absolute expiration date, provide a value for the
+<B>-expires</B> argument with the following format:
+<PRE> [<B>at</B>] <VAR>mm</VAR><B>/</B><VAR>dd</VAR><B>/</B><VAR>yyyy</VAR> [<VAR>hh</VAR><B>:</B><VAR>MM</VAR>]
+</PRE>
+<P>where <VAR>mm</VAR> indicates the month, <VAR>dd</VAR> the day, and
+<VAR>yyyy</VAR> the year when the dump expires. Valid values for the year
+fall in the range <B>1970</B> through <B>2037</B> (the latest possible
+date that the UNIX time representation can express is in early 2038).
+If you provide a time, it must be in 24-hour format with <VAR>hh</VAR> the hours
+and <VAR>MM</VAR> the minutes (for example, <B>21:50</B> is 9:50
+p.m.). If you omit the time, the default is 00:00
+hours (12:00 midnight) on the indicated date.
+<P><LI>To define a relative expiration date, provide a value for the
+<B>-expires</B> argument with the following format:
+<PRE> [<B>in</B>] [<VAR>years</VAR><B>y</B>] [<VAR>months</VAR><B>m</B>] [<VAR>days</VAR><B>d</B>]
+</PRE>
+<P>where each of <VAR>years</VAR>, <VAR>months</VAR>, and <VAR>days</VAR> is an
+integer. Provide at least one of them together with the corresponding
+units letter (<B>y</B>, <B>m</B>, or <B>d</B> respectively), with
+no intervening space. If you provide more than one of the three, list
+them in the indicated order.
+<P>The Backup System calculates a dump's actual expiration date by adding
+the indicated relative value to the start time of the dump operation.
+For example, it assigns an expiration date 1 year, 6 months, and 2 days in the
+future to a dump created at a dump level with associated expiration date
+<B>in 1y 6m 2d</B>.
+<P><LI>To indicate that a dump backed up at the corresponding dump level never
+expires, provide the value <B>NEVER</B> instead of a date and time.
+To recycle tapes that contain dumps created at such a level, you must use the
+<B>backup readlabel</B> command to overwrite the tape's label.
+</UL>
+<P>If you omit the <B>-expires</B> argument to the <B>backup
+adddump</B> command, then the expiration date is set to UNIX time zero
+(00:00 hours on 1 January 1970). The Backup System considers
+dumps created at such a dump level to expire at their creation time. If
+no dumps in a dump set have an expiration date, then the Backup System does
+not impose any restriction on recycling the tapes that contain the dump
+set. If you need to prevent premature recycling of the tapes that
+contain the dump set, you must use a manual tracking system.
+<A NAME="IDX6915"></A>
+<A NAME="IDX6916"></A>
+<A NAME="IDX6917"></A>
+<A NAME="IDX6918"></A>
+<A NAME="IDX6919"></A>
+<A NAME="IDX6920"></A>
+<A NAME="IDX6921"></A>
+<A NAME="IDX6922"></A>
+<A NAME="IDX6923"></A>
+<P><H3><A NAME="Header_300" HREF="auagd002.htm#ToC_300">To add a dump level to the dump hierarchy</A></H3>
+<OL TYPE=1>
+<P><LI>Verify that you are authenticated as a user listed in the
+<B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
+listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
+<PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
+</PRE>
+<P><LI><B>Optional</B>. Issue the <B>backup</B> command to enter
+interactive mode.
+<PRE> % <B>backup</B>
+</PRE>
+<P><LI>Issue the <B>backup adddump</B> command to define one or more dump
+levels. If you are defining an incremental level, then all of the
+parent levels that precede it in its pathname must either already exist or
+precede it on the command line.
+<PRE> backup> <B>adddump -dump</B> <<VAR>dump level name</VAR>><SUP>+</SUP> [<B>-expires</B> <<VAR>expiration date</VAR>><SUP>+</SUP>]
+</PRE>
+<P>where
+<DL>
+<P><DT><B>addd
+</B><DD>Is the shortest acceptable abbreviation of <B>adddump</B>.
+<P><DT><B>-dump
+</B><DD>Names each dump level to added. If you specify more than one dump
+level name, you must include the <B>-dump</B> switch.
+<P>Provide the entire pathname of the dump level, preceding each level in the
+pathname with a slash (<B>/</B>). Each component level can be up to
+28 characters in length, and the pathname can include up to 256 characters
+including the slashes.
+<P><DT><B>-expires
+</B><DD>Sets the expiration date associated with each dump level. Specify
+either a relative or absolute expiration date, as described in <A HREF="#HDRWQ270">Defining Expiration Dates</A>, or omit this argument to assign no expiration date to the
+dump levels.
+<TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">A plus sign follows this argument in the command's syntax statement
+because it accepts a multiword value which does not need to be enclosed in
+double quotes or other delimiters, not because it accepts multiple
+dates. Provide only one date (and optionally, time) definition to be
+associated with each dump level specified by the <B>-dump</B>
+argument.
+</TD></TR></TABLE>
+</DL>
+</OL>
+<A NAME="IDX6924"></A>
+<A NAME="IDX6925"></A>
+<A NAME="IDX6926"></A>
+<A NAME="IDX6927"></A>
+<A NAME="IDX6928"></A>
+<A NAME="IDX6929"></A>
+<P><H3><A NAME="Header_301" HREF="auagd002.htm#ToC_301">To change a dump level's expiration date</A></H3>
+<OL TYPE=1>
+<P><LI>Verify that you are authenticated as a user listed in the
+<B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
+listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
+<PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
+</PRE>
+<P><LI><B>Optional</B>. Issue the <B>backup</B> command to enter
+interactive mode.
+<PRE> % <B>backup</B>
+</PRE>
+<P><LI>Issue the <B>(backup) setexp</B> command to change the expiration date
+associated with one or more dump levels.
+<PRE> backup> <B>setexp -dump</B> <<VAR>dump level name</VAR>><SUP>+</SUP> [<B>-expires</B> <<VAR>expiration date</VAR>><SUP>+</SUP>]
+</PRE>
+<P>where
+<DL>
+<P><DT><B>se
+</B><DD>Is the shortest acceptable abbreviation of <B>setexp</B>.
+<P><DT><B>-dump
+</B><DD>Names each existing dump level for which to change the expiration
+date.
+<P><DT><B>-expires
+</B><DD>Sets the expiration date associated with each dump level. Specify
+either a relative or absolute expiration date, as described in <A HREF="#HDRWQ270">Defining Expiration Dates</A>; omit this argument to remove the expiration date
+currently associated with each dump level.
+<TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">A plus sign follows this argument in the command's syntax statement
+because it accepts a multiword value which does not need to be enclosed in
+double quotes or other delimiters, not because it accepts multiple
+dates. Provide only one date (and optionally, time) definition to be
+associated with each dump level specified by the <B>-dump</B>
+argument.
+</TD></TR></TABLE>
+</DL>
+</OL>
+<A NAME="IDX6930"></A>
+<A NAME="IDX6931"></A>
+<A NAME="IDX6932"></A>
+<A NAME="IDX6933"></A>
+<A NAME="IDX6934"></A>
+<P><H3><A NAME="Header_302" HREF="auagd002.htm#ToC_302">To delete a dump level from the dump hierarchy</A></H3>
+<OL TYPE=1>
+<P><LI>Verify that you are authenticated as a user listed in the
+<B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
+listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
+<PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
+</PRE>
+<P><LI><B>Optional</B>. Issue the <B>backup</B> command to enter
+interactive mode.
+<PRE> % <B>backup</B>
+</PRE>
+<P><LI>Issue the <B>(backup) deldump</B> command to delete the dump
+level. Note that the command automatically removes all incremental dump
+levels for which the specified level serves as parent, either directly or
+indirectly.
+<PRE> backup> <B>deldump</B> <<VAR>dump level name</VAR>>
+</PRE>
+<P>where
+<DL>
+<P><DT><B>deld
+</B><DD>Is the shortest acceptable abbreviation of <B>deldump</B>.
+<P><DT><B><VAR>dump level name</VAR>
+</B><DD>Specifies the complete pathname of the dump level to delete.
+</DL>
+</OL>
+<A NAME="IDX6935"></A>
+<A NAME="IDX6936"></A>
+<A NAME="IDX6937"></A>
+<A NAME="IDX6938"></A>
+<A NAME="IDX6939"></A>
+<A NAME="IDX6940"></A>
+<P><H3><A NAME="HDRWQ271" HREF="auagd002.htm#ToC_303">To display the dump hierarchy</A></H3>
+<OL TYPE=1>
+<P><LI>Issue the <B>backup listdumps</B> command to display the dump
+hierarchy.
+<PRE> % <B>backup listdumps</B>
+</PRE>
+<P>where <B>listd</B> is the shortest acceptable abbreviation of
+<B>listdumps</B>.
+<P>The output from this command displays the dump hierarchy, reporting the
+expiration date associated with each dump level, as in the following
+example.
+<PRE> % <B>backup listdumps</B>
+ /week1 expires in 27d
+ /tuesday expires in 13d
+ /thursday expires in 13d
+ /sunday expires in 13d
+ /tuesday expires in 13d
+ /thursday expires in 13d
+ /week3 expires in 27d
+ /tuesday expires in 13d
+ /thursday expires in 13d
+ /sunday expires in 13d
+ /tuesday expires in 13d
+ /thursday expires in 13d
+ sunday1 expires in 27d
+ /monday1 expires in 13d
+ /tuesday1 expires in 13d
+ /wednesday1 expires in 13d
+ /thursday1 expires in 13d
+ /friday1 expires in 13d
+ sunday2 expires in 27d
+ /monday2 expires in 13d
+ /tuesday2 expires in 13d
+ /wednesday2 expires in 13d
+ /thursday2 expires in 13d
+ /friday2 expires in 13d
+ sunday3 expires in 27d
+ /monday1 expires in 13d
+ /tuesday1 expires in 13d
+ /wednesday1 expires in 13d
+ /thursday1 expires in 13d
+ /friday1 expires in 13d
+ sunday4 expires in 27d
+ /monday2 expires in 13d
+ /tuesday2 expires in 13d
+ /wednesday2 expires in 13d
+ /thursday2 expires in 13d
+ /friday2 expires in 13d
+</PRE>
+</OL>
+<HR><H2><A NAME="HDRWQ272" HREF="auagd002.htm#ToC_304">Writing and Reading Tape Labels</A></H2>
+<A NAME="IDX6941"></A>
+<A NAME="IDX6942"></A>
+<A NAME="IDX6943"></A>
+<A NAME="IDX6944"></A>
+<A NAME="IDX6945"></A>
+<A NAME="IDX6946"></A>
+<P>As described in <A HREF="#HDRWQ253">Dump Names and Tape Names</A> and <A HREF="#HDRWQ254">Tape Labels, Dump Labels, and EOF Markers</A>, you can assign either a permanent name or
+an AFS tape name to a tape that you use in the Backup System. The names
+are recorded on the tape's magnetic label, along with an indication of
+the tape's capacity (size).
+<P>You can assign either a permanent name or an AFS tape name, but not
+both. In general, assigning permanent names rather than AFS tape names
+simplifies the backup process, because the Backup System does not dictate the
+format of permanent names. If a tape does not have a permanent name,
+then by default the Backup System accepts only three strictly defined values
+in the AFS tape name field, and refuses to write a dump to a tape with an
+inappropriate AFS tape name. The acceptable values are a name that
+matches the volume set and dump level of the initial dump, the value
+<TT><NULL></TT>, and no value in the field at all.
+<P>If a tape has a permanent name, the Backup System does not check the AFS
+tape name, and as part of the dump operation constructs the appropriate AFS
+tape name itself and records it on the label. This means that if you
+assign a permanent name, the Backup System assigns an AFS tape name itself and
+the tape has both types of name. In contrast, if a tape has an AFS tape
+name but not a permanent name, you cannot assign a permanent name without
+first erasing the AFS tape name.
+<P>(You can also suppress the Backup System's check of a tape's AFS
+tape name, even it does not have a permanent name, by assigning the value
+<B>NO</B> to the <B>NAME_CHECK</B> instruction in the device
+configuration file. See <A HREF="#HDRWQ280">Eliminating the AFS Tape Name Check</A>.)
+<P>Because the Backup System accepts unlabeled tapes, you do not have to label
+a tape before using it for the first time. After the first use, there
+are a couple of cases in which you must relabel a tape in order to write a
+dump to it:
+<UL>
+<P><LI>The tape does not have a permanent name, and the AFS tape name on it does
+not match the new initial dump set you want to create (the volume set and dump
+level names are different, or the index is incorrect).
+<P><LI>You want to recycle a tape before all of the dumps on it have
+expired. The Backup System does not overwrite a tape with any unexpired
+dumps. Keep in mind, though, that if you relabel the tape to making
+recycling possible, you erase all the dump records for the tape from the
+Backup Database, which makes it impossible to restore any data from the
+tape.
+</UL>
+<TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Labeling a tape that contains dump data makes it impossible to use that data
+in a restore operation, because the labeling operation removes the dump's
+records from the Backup Database. If you want to record a permanent
+name on a tape label, you must do it before dumping any data to the
+tape.
+</TD></TR></TABLE>
+<P><H3><A NAME="Header_305" HREF="auagd002.htm#ToC_305">Recording a Name on the Label</A></H3>
+<P>To write a permanent name on a tape's label, include the
+<B>-pname</B> argument to specify a string of up to 32 characters.
+Check that no other tape used with the Backup System in your cell already has
+the permanent name you are assigning, because the Backup System does not
+prevent you from assigning the same name to multiple tapes. The Backup
+System overwrites the existing AFS tape name, if any, with the value
+<TT><NULL></TT>. When a tape has a permanent name, the Backup
+System uses it instead of the AFS tape name in most prompts and when referring
+to the tape in output from <B>backup</B> commands. The permanent
+name persists until you again include the <B>-pname</B> argument to the
+<B>backup labeltape</B> command, regardless of the tape's contents
+and of how often you recycle the tape or use the <B>backup labeltape</B>
+command without the <B>-pname</B> argument.
+<P>To write an AFS tape name on the label, provide a value for the
+<B>-name</B> argument that matches the volume set name and the final
+element in the dump level pathname of the initial dump that you plan to write
+to the tape, and an index that indicates the tape's place in the sequence
+of tapes for the dump set. The format is as follows:
+<PRE> <VAR>volume_set_name</VAR><B>.</B><VAR>dump_level_name</VAR><B>.</B><VAR>tape_index</VAR>
+</PRE>
+<P>If you omit the <B>-name</B> argument, the Backup System sets the AFS
+tape name to <TT><NULL></TT>. The Backup System automatically
+constructs and records the appropriate name when you later write an initial
+dump to the tape by using the <B>backup dump</B> or <B>backup
+savedb</B> command.
+<P>You cannot use the <B>-name</B> argument if the tape already has a
+permanent name. To erase a tape's permanent name, provide a null
+value to the <B>-pname</B> argument by issuing the following
+command:
+<PRE> % <B>backup labeltape -pname ""</B>
+</PRE>
+<P><H3><A NAME="Header_306" HREF="auagd002.htm#ToC_306">Recording a Capacity on the Label</A></H3>
+<P>To record the tape's capacity on the label, specify a number of
+kilobytes as the <B>-size</B> argument. If you omit this argument
+the first time you label a tape, the Backup System records the default tape
+capacity associated with the specified port offset in the
+<B>/usr/afs/backup/tapeconfig</B> file on the Tape Coordinator
+machine. If the tape's capacity is different (in particular,
+larger) than the capacity recorded in the <B>tapeconfig</B> file, it is
+best to record a capacity on the label before using the tape. Once set,
+the value in the label's capacity field persists until you again use the
+<B>-size</B> argument to the <B>backup labeltape</B> command.
+For a discussion of the appropriate capacity to record for tapes, see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>.
+<P>To read a tape's label, use the <B>backup readlabel</B>
+command.
+<P>Most tapes also come with an adhesive label you can apply to the exterior
+casing. To help you easily identify a tape, record at least the
+tape's permanent and AFS tape names on the adhesive label.
+Depending on the recycling scheme you use, it can be useful to record other
+information, such as the dump ID, dump creation date, and expiration date of
+each dump you write to the tape.
+<A NAME="IDX6947"></A>
+<A NAME="IDX6948"></A>
+<P><H3><A NAME="HDRWQ273" HREF="auagd002.htm#ToC_307">To label a tape</A></H3>
+<OL TYPE=1>
+<P><LI>Verify that you are authenticated as a user listed in the
+<B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
+listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
+<PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
+</PRE>
+<P><LI>If the Tape Coordinator for the tape device that is to perform the
+operation is not already running, open a connection to the appropriate Tape
+Coordinator machine and issue the <B>butc</B> command, for which complete
+instructions appear in <A HREF="auagd012.htm#HDRWQ292">To start a Tape Coordinator process</A>.
+<PRE> % <B>butc</B> [<<VAR>port offset</VAR>>] [<B>-noautoquery</B>]
+</PRE>
+<P><LI>Place the tape in the device.
+<P><LI><B>Optional</B>. Issue the <B>backup</B> command to enter
+interactive mode, if you want to label multiple tapes or issue additional
+commands after labeling the tape. The interactive prompt appears in the
+following step.
+<PRE> % <B>backup</B>
+</PRE>
+<P><LI>Issue the <B>(backup) labeltape</B> command to label the tape.
+<PRE> backup> <B>labeltape</B> [<B>-name</B> <<VAR>tape name, defaults to NULL</VAR>>] \
+ [<B>-size</B> <<VAR>tape size in Kbytes, defaults to size in tapeconfig</VAR>>] \
+ [<B>-portoffset</B> <<VAR>TC port offset</VAR>>] [<B>-pname</B> <<VAR>permanent tape name</VAR>>]
+</PRE>
+<P>where
+<DL>
+<P><DT><B>la
+</B><DD>Is the shortest acceptable abbreviation of <B>labeltape</B>.
+<P><DT><B>-name
+</B><DD>Specifies the AFS tape name to record on the label. Include this
+argument or the <B>-pname</B> argument, but not both. If you omit
+this argument, the AFS tape name is set to <TT><NULL></TT>. If you
+provide it, it must have the following format.
+<PRE><VAR>volume_set_name</VAR><B>.</B><VAR>dump_level_name</VAR><B>.</B><VAR>tape_index</VAR>
+</PRE>
+<P>
+<P>for the tape to be acceptable for use in a future <B>backup dump</B>
+operation. The <VAR>volume_set_name</VAR> must match the volume set name
+of the initial dump to be written to the tape, <VAR>dump_level_name</VAR> must
+match the last element of the dump level pathname at which the volume set is
+to be dumped, and <VAR>tape_index</VAR> must correctly indicate the tape's
+place in the sequence of tapes that house the dump set; indexing begins
+with the number 1 (one).
+<P><DT><B>-size
+</B><DD>Specifies the tape capacity to record on the label. If you are
+labeling the tape for the first time, you need to include this argument only
+if the tape's capacity differs from the capacity associated with the
+specified port offset in the <B>/usr/afs/backup/tapeconfig</B> file on the
+Tape Coordinator machine.
+<P>If you provide a value, it is an integer value followed by a letter that
+indicates units, with no intervening space. A unit value of
+<B>k</B> or <B>K</B> indicates kilobytes, <B>m</B> or <B>M</B>
+indicates megabytes, and <B>g</B> or <B>G</B> indicates
+gigabytes. If you omit the units letter, the default is
+kilobytes.
+<P><DT><B>-portoffset
+</B><DD>Specifies the port offset number of the Tape Coordinator handling the tape
+or backup data file for this operation. You must provide this argument
+unless the default value of <B>0</B> (zero) is appropriate.
+<P><DT><B>-pname
+</B><DD>Specifies the permanent name to record on the label. It can be up
+to 32 characters in length, and include any alphanumeric characters.
+Avoid metacharacters that have a special meaning to the shell, to avoid having
+to mark them as literal in commands issued at the shell prompt.
+<P>Include this argument or the <B>-name</B> argument, but not
+both. When you provide this argument, the AFS tape name is set to
+<TT><NULL></TT>. If you omit this argument, any existing permanent
+name is retained.
+</DL>
+<P><LI>If you did not include the <B>-noautoquery</B> flag when you issued
+the <B>butc</B> command, or if the device's device configuration file
+includes the instruction <B>AUTOQUERY YES</B>, then the Tape Coordinator
+prompts you to place the tape in the device's drive. You have
+already done so, but you must now press <B><Return></B> to indicate
+that the tape is ready for labeling.
+</OL>
+<A NAME="IDX6949"></A>
+<A NAME="IDX6950"></A>
+<P><H3><A NAME="HDRWQ274" HREF="auagd002.htm#ToC_308">To read the label on a tape</A></H3>
+<OL TYPE=1>
+<P><LI>Verify that you are authenticated as a user listed in the
+<B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
+listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
+<PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
+</PRE>
+<P><LI>If the Tape Coordinator for the tape device that is to perform the
+operation is not already running, open a connection to the appropriate Tape
+Coordinator machine and issue the <B>butc</B> command, for which complete
+instructions appear in <A HREF="auagd012.htm#HDRWQ292">To start a Tape Coordinator process</A>.
+<PRE> % <B>butc</B> [<<VAR>port offset</VAR>>] [<B>-noautoquery</B>]
+</PRE>
+<P><LI>Place the tape in the device.
+<P><LI><B>Optional</B>. Issue the <B>backup</B> command to enter
+interactive mode, if you want to label multiple tapes or issue additional
+commands after labeling the tape. The interactive prompt appears in the
+following step.
+<PRE> % <B>backup</B>
+</PRE>
+<P><LI>Issue the <B>(backup) readlabel</B> command to read the label on the
+tape.
+<PRE> backup> <B>readlabel</B> [<<VAR>TC port offset</VAR>>]
+</PRE>
+<P>where
+<DL>
+<P><DT><B>rea
+</B><DD>Is the shortest acceptable abbreviation of <B>readlabel</B>.
+<P><DT><B><VAR>TC port offset</VAR>
+</B><DD>Specifies the port offset number of Tape Coordinator handling the tape or
+backup data file for this operation. You must provide this argument
+unless the default value of <B>0</B> (zero) is appropriate.
+</DL>
+<P><LI>If you did not include the <B>-noautoquery</B> flag when you issued
+the <B>butc</B> command, or the device's device configuration file
+includes the instruction <B>AUTOQUERY YES</B> instruction, then the Tape
+Coordinator prompts you to place the tape in the device's drive.
+You have already done so, but you must now press <B><Return></B> to
+indicate that the tape is ready for reading.
+</OL>
+<P>Information from the tape label appears both in the <B>backup</B>
+command window and in the Tape Coordinator window. The output in the
+command window has the following format:
+<PRE> Tape read was labelled: <VAR>tape_name</VAR> (<VAR>initial_dump_ID</VAR>)
+ size: <VAR>size</VAR> KBytes
+</PRE>
+<P>where <VAR>tape_name</VAR> is the tape's permanent name (if it has one)
+or AFS tape name, <VAR>initial_dump_ID</VAR> is the dump ID of the initial dump
+on the tape, and <VAR>size</VAR> is the capacity recorded on the label, in
+kilobytes.
+<P>The information in the Tape Coordinator window is more extensive.
+The tape's permanent name appears in the <TT>tape name</TT> field and
+its AFS tape name in the <TT>AFS tape name</TT> field. If either name
+is undefined, a value of <TT><NULL></TT> appears in the field
+instead. The capacity recorded on the label appears in the
+<TT>size</TT> field. Other fields in the output report the creation
+time, dump level name, and dump ID of the initial dump on the tape
+(<TT>creationTime</TT>, <TT>dump path</TT>, and <TT>dump id</TT>
+respectively). The <TT>cell</TT> field reports the cell in which the
+dump operation was performed, and the <TT>useCount</TT> field reports the
+number of times the tape has been relabeled, either with the <B>backup
+labeltape</B> command or during a dump operation. For further
+details, see the command's reference page in the <I>IBM AFS
+Administration Reference</I>.
+<P>If the tape has no label, or if the drive is empty, the following message
+appears at the command shell:
+<PRE> Failed to read tape label.
+</PRE>
+<P>The following example illustrates the output in the command shell for a
+tape in the device with port offset 1:
+<PRE> % <B>backup readlabel 1</B>
+ Tape read was labelled: monthly_guest (917860000)
+ size: 2150000 KBytes
+</PRE>
+<P>The following output appears in the Tape Coordinator window at the same
+time:
+<PRE> Tape label
+ ----------
+ tape name = monthly_guest
+ AFS tape name = guests.monthly.3
+ creationTime = Mon Feb 1 04:06:40 1999
+ cell = abc.com
+ size = 2150000 Kbytes
+ dump path = /monthly
+ dump id = 917860000
+ useCount = 44
+ -- End of tape label --
+</PRE>
+<HR><H2><A NAME="HDRWQ275" HREF="auagd002.htm#ToC_309">Automating and Increasing the Efficiency of the Backup Process</A></H2>
+<A NAME="IDX6951"></A>
+<A NAME="IDX6952"></A>
+<P>The Backup System includes several optional features to help you automate
+the backup process in your cell and make it more efficient. By
+combining several of the features, you can dump volume data to tape with
+minimal human intervention in most cases. To take advantage of many of
+the features, you create a <I>device configuration file</I> in the
+<B>/usr/afs/backup</B> directory for each tape device that participates in
+automated operations. For general instructions on creating the device
+configuration file, see <A HREF="#HDRWQ276">Creating a Device Configuration File</A>. The following list refers you to sections that
+describe each feature in greater detail.
+<UL>
+<P><LI>You can use tape stackers and jukeboxes to perform backup
+operations. These are tape drives with an attached unit that stores
+several tapes and can physically insert and remove them from the tape reader
+(tape drive) without human intervention, meaning that no operator has to be
+present even for backup operations that require several tapes. To use a
+stacker or jukebox with the Backup System, include the <B>MOUNT</B> and
+<B>UNMOUNT</B> instructions in its device configuration file. See <A HREF="#HDRWQ277">Invoking a Device's Tape Mounting and Unmounting Routines</A>.
+<P><LI>You can suppress the Tape Coordinator's default prompt for the
+initial tape that it needs for a backup operation, again eliminating the need
+for a human operator to be present when a backup operation begins. (You
+must still insert the correct tape in the drive at some point before the
+operation begins.) To suppress the initial prompt, include the
+<B>-noautoquery</B> flag on the <B>butc</B> command, or assign the
+value <B>NO</B> to the <B>AUTOQUERY</B> instruction in the device
+configuration file. See <A HREF="#HDRWQ278">Eliminating the Search or Prompt for the Initial Tape</A>.
+<P><LI>You can suppress the prompts that the Tape Coordinator otherwise generates
+when it encounters several types of errors. When you use this feature,
+the Tape Coordinator instead responds to the errors in a default manner, which
+generally allows the operation to continue without human intervention.
+To suppress prompts about error conditions, assign the value <B>NO</B> to
+the <B>ASK</B> instruction in the device configuration file. See <A HREF="#HDRWQ279">Enabling Default Responses to Error Conditions</A>.
+<P><LI>You can suppress the Backup System's default verification that the
+AFS tape name on a tape that has no permanent name matches the name derived
+from the volume set and dump level names of the initial dump the Backup System
+is writing to the tape. This enables you to recycle a tape without
+first relabeling it, as long as all dumps on it are expired. To
+suppress name checking, assign the value <B>NO</B> to the
+<B>NAME_CHECK</B> instruction in the device configuration file. See
+<A HREF="#HDRWQ280">Eliminating the AFS Tape Name Check</A>.
+<P><LI>You can promote tape streaming (the most efficient way for a tape device
+to operate) by setting the size of the memory buffer the Tape Coordinator uses
+when transferring volume data between the file system and the device.
+To set the buffer size, include the <B>BUFFERSIZE</B> instruction in the
+device configuration file. See <A HREF="#HDRWQ281">Setting the Memory Buffer Size to Promote Tape Streaming</A>.
+<P><LI>You can write dumps to a <I>backup data file</I> on the local disk of
+the Tape Coordinator machine, rather than to tape. You can then
+transfer the backup data file to a data-archiving system, such as a
+hierarchical storage management (HSM) system, that you use in conjunction with
+AFS and the Backup System. Writing a dump to a file is usually more
+efficient that issuing the equivalent <B>vos dump</B> commands
+individually. To write dumps to a file, include the <B>FILE</B>
+instruction in the device configuration file. See <A HREF="#HDRWQ282">Dumping Data to a Backup Data File</A>.
+</UL>
+<P>There are two additional ways to increase backup automation and efficiency
+that do not involve the device configuration file:
+<UL>
+<P><LI>You can schedule one or more <B>backup dump</B> commands to run at
+specified times. This enables you to create backups at times of low
+system usage, without requiring a human operator to be present. You can
+schedule a single dump operation for a future time, or multiple operations to
+run at various future times. See <A HREF="auagd012.htm#HDRWQ300">Scheduling Dumps</A>.
+<P><LI>You can append dumps to a tape that already has other dumps on it.
+This enables you to use as much of a tape's capacity as possible.
+The appended dumps do not have be related in any way to one another or to the
+initial dump on the tape, but grouping dumps appropriately can reduce the
+number of necessary tape changes during a restore operation. To append
+a dump, include the <B>-append</B> argument to the <B>backup dump</B>
+command. See <A HREF="auagd012.htm#HDRWQ299">Appending Dumps to an Existing Dump Set</A>.
+</UL>
+<P><H3><A NAME="HDRWQ276" HREF="auagd002.htm#ToC_310">Creating a Device Configuration File</A></H3>
+<A NAME="IDX6953"></A>
+<A NAME="IDX6954"></A>
+<A NAME="IDX6955"></A>
+<A NAME="IDX6956"></A>
+<P>To use many of the features that automate backup operations, create a
+configuration file for each tape device in the <B>/usr/afs/backup</B>
+directory on the local disk of the Tape Coordinator machine that drives the
+device. The filename has the following form:
+<P><B>CFG_</B><VAR>device_name</VAR>
+<P>where <VAR>device_name</VAR> represents the name of the tape device or backup
+data file (see <A HREF="#HDRWQ282">Dumping Data to a Backup Data File</A> to learn about writing dumps to a file rather than to
+tape).
+<P>For a tape device, construct the <VAR>device_name</VAR> portion of the name
+by stripping off the initial <B>/dev/</B> string with which all UNIX
+device names conventionally begin, and replacing any other slashes in the name
+with underscores. For example, <B>CFG_rmt_4m</B> is the appropriate
+filename for a device called <B>/dev/rmt/4m</B>.
+<P>For a backup data file, construct the <VAR>device_name</VAR> portion by
+stripping off the initial slash (<B>/</B>) and replacing any other slashes
+(<B>/</B>) in the name with underscores. For example,
+<B>CFG_var_tmp_FILE</B> is the appropriate filename for a backup data file
+called <B>/var/tmp/FILE</B>.
+<P>Creating a device configuration file is optional. If you do not want
+to take advantage of any of the features that the file provides, you do not
+have to create it.
+<P>You can include one of each of the following instructions in any order in a
+device configuration file. All are optional. Place each
+instruction on its own line, but do not include any newline
+(<B><Return></B>) characters within an instruction.
+<DL>
+<P><DT><B>MOUNT and UNMOUNT
+</B><DD>Identify a script of routines for mounting and unmounting tapes in a tape
+stacker or jukebox's drive as needed. See <A HREF="#HDRWQ277">Invoking a Device's Tape Mounting and Unmounting Routines</A>.
+<P><DT><B>AUTOQUERY
+</B><DD>Controls whether the Tape Coordinator prompts for the first tape it needs
+for a backup operation. See <A HREF="#HDRWQ278">Eliminating the Search or Prompt for the Initial Tape</A>.
+<P><DT><B>ASK
+</B><DD>Controls whether the Tape Coordinator asks you how to respond to certain
+error conditions. See <A HREF="#HDRWQ279">Enabling Default Responses to Error Conditions</A>.
+<P><DT><B>NAME_CHECK
+</B><DD>Controls whether the Tape Coordinator verifies that an AFS tape name
+matches the initial dump you are writing to the tape. See <A HREF="#HDRWQ280">Eliminating the AFS Tape Name Check</A>.
+<P><DT><B>BUFFERSIZE
+</B><DD>Sets the size of the memory buffer the Tape Coordinator uses when
+transferring data between a tape device and a volume. See <A HREF="#HDRWQ281">Setting the Memory Buffer Size to Promote Tape Streaming</A>.
+<P><DT><B>FILE
+</B><DD>Controls whether the Tape Coordinator writes dumps to, and restores data
+from, a tape device or a backup data file. See <A HREF="#HDRWQ282">Dumping Data to a Backup Data File</A>.
+</DL>
+<A NAME="IDX6957"></A>
+<A NAME="IDX6958"></A>
+<A NAME="IDX6959"></A>
+<A NAME="IDX6960"></A>
+<A NAME="IDX6961"></A>
+<A NAME="IDX6962"></A>
+<P><H3><A NAME="HDRWQ277" HREF="auagd002.htm#ToC_311">Invoking a Device's Tape Mounting and Unmounting Routines</A></H3>
+<P>A tape stacker or jukebox helps you automate backup
+operations because it can switch between multiple tapes during an operation
+without human intervention. To take advantage of this feature, include
+the <B>MOUNT</B> and optionally <B>UNMOUNT</B> instructions in the
+device configuration file that you write for the stacker or jukebox.
+The instructions share the same syntax:
+<PRE> <B>MOUNT</B> <VAR>filename</VAR>
+ <B>UNMOUNT</B> <VAR>filename</VAR>
+</PRE>
+<P>where <VAR>filename</VAR> is the pathname on the local disk of a script or
+program you have written that invokes the routines defined by the
+device's manufacturer for mounting or unmounting a tape in the
+device's tape drive. (For convenience, the following discussion
+uses the term <I>script</I> to refers to both scripts and
+programs.) The script usually also contains additional logic that
+handles error conditions or modifies the script's behavior depending on
+which backup operation is being performed.
+<P>You can refer to different scripts with the <B>MOUNT</B> or
+<B>UNMOUNT</B> instructions, or to a single script that invokes both
+mounting and unmounting routines. The scripts inherit the local
+identity and AFS tokens associated with to the issuer of the <B>butc</B>
+command.
+<P>You need to include a <B>MOUNT</B> instruction in the device
+configuration file for all tape devices, but the need for an
+<B>UNMOUNT</B> instruction depends on the tape-handling routines that the
+device's manufacturer provides. Some devices, usually stackers,
+have only a single routine for mounting tapes, which also automatically
+unmounts a tape whose presence prevents insertion of the required new
+tape. In this case, an <B>UNMOUNT</B> instruction is not
+necessary. For devices that have separate mounting and unmounting
+routines, you must include an <B>UNMOUNT</B> instruction to remove a tape
+when the Tape Coordinator is finished with it; otherwise, subsequent
+attempts to run the <B>MOUNT</B> instruction fail with an error.
+<P>When the device configuration file includes a <B>MOUNT</B> instruction,
+you must stock the stacker or jukebox with the necessary tapes before running
+a backup operation. Many jukeboxes are able to search for the required
+tape by reading external labels (such as barcodes) on the tapes, but many
+stackers can only switch between tapes in sequence and sometimes only in one
+direction. In the latter case, you must also stock the tapes in the
+correct order.
+<P>To obtain a list of the tapes required for a restore operation so that you
+can prestock them in the tape device, include the <B>-n</B> flag on the
+appropriate <B>backup</B> command (<B>backup diskrestore</B>,
+<B>backup volrestore</B>, or <B>backup volsetrestore</B>). For
+a dump operation, it is generally sufficient to stock the device with more
+tapes than the operation is likely to require. You can prelabel the
+tapes with permanent names or AFS tape names, or not prelabel them at
+all. If you prelabel the tapes for a dump operation with AFS tape
+names, then it is simplest to load them into the stacker in sequential order
+by tape index. But it is probably simpler still to prelabel tapes with
+permanent tape names or use unlabeled tapes, in which case the Backup System
+generates and applies the appropriately indexed AFS tape name itself during
+the dump operation.
+<P><H4><A NAME="Header_312">How the Tape Coordinator Uses the MOUNT and UNMOUNT Instructions</A></H4>
+<P>When you issue the <B>butc</B> command to initialize the Tape
+Coordinator for a given tape device, the Tape Coordinator looks for the device
+configuration file called <B>/usr/afs/backup/CFG_</B><VAR>device_name</VAR>
+on its local disk, where <VAR>device_name</VAR> has the format described in <A HREF="#HDRWQ276">Creating a Device Configuration File</A>. If the file exists and contains a <B>MOUNT</B>
+instruction, then whenever the Tape Coordinator needs a tape, it executes the
+script named by the instruction's <VAR>filename</VAR> argument.
+<P>If the device configuration file does not exist, or does not include a
+<B>MOUNT</B> instruction, then whenever the Tape Coordinator needs a tape,
+it generates a prompt in its window instructing the operator to insert the
+necessary tape. The operator must insert the tape and press
+<B><Return></B> before the Tape Coordinator continues the backup
+operation.
+<P>Note, however, that you can modify the Tape Coordinator's behavior
+with respect to the first tape needed for an operation, by setting the
+<B>AUTOQUERY</B> instruction in the device configuration file to
+<B>NO</B>, or including the <B>-noautoquery</B> flag to the
+<B>butc</B> command. In this case, the Tape Coordinator does not
+execute the <B>MOUNT</B> instruction or prompt for a tape at the start of
+an operation, because it expects to find the required first tape in the
+drive. See <A HREF="#HDRWQ278">Eliminating the Search or Prompt for the Initial Tape</A>.
+<P>If there is an <B>UNMOUNT</B> instruction in the device configuration
+file, then whenever the Tape Coordinator closes the tape device, it executes
+the script named by the instruction's <VAR>filename</VAR> argument.
+It executes the script only once, and regardless of whether the
+<B>close</B> operation on the device succeeded or not. If the
+device configuration file does not include an <B>UNMOUNT</B> instruction,
+then the Tape Coordinator takes no action.
+<P><H4><A NAME="Header_313">The Available Parameters and Required Exit Codes</A></H4>
+<P>When the Tape Coordinator executes the <B>MOUNT</B> script, it
+passes in five parameters, ordered as follows. You can use the
+parameters in your script to refine its response to varying circumstances that
+can arise during a backup operation.
+<OL TYPE=1>
+<P><LI>The tape device or backup data file's pathname, as recorded in the
+<B>/usr/afs/backup/tapeconfig</B> file.
+<P><LI>The tape operation, which (except for the exceptions noted in the
+following list) matches the <B>backup</B> command operation code used to
+initiate the operation:
+<UL>
+<P><LI><B>appenddump</B> (when a <B>backup dump</B> command includes the
+<B>-append</B> flag)
+<P><LI><B>dump</B> (when a <B>backup dump</B> command does not include
+the <B>-append</B> flag)
+<P><LI><B>labeltape</B>
+<P><LI><B>readlabel</B>
+<P><LI><B>restore</B> (for a <B>backup diskrestore</B>, <B>backup
+volrestore</B>, or <B>backup volsetrestore</B> command)
+<P><LI><B>restoredb</B>
+<P><LI><B>savedb</B>
+<P><LI><B>scantape</B>
+</UL>
+<P><LI>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
+<B>MOUNT</B> instruction.
+<P><LI>The tape name. For some operations, the Tape Coordinator passes the
+string <TT>none</TT>, because it does not know the tape name (when running
+the <B>backup scantape</B> or <B>backup readlabel</B>, for example),
+or because the tape does not necessarily have a name (when running the
+<B>backup labeltape</B> command, for example).
+<P><LI>The tape ID recorded in the Backup Database. As with the tape name,
+the Backup System passes the string <TT>none</TT> for operations where it
+does not know the tape ID or the tape does not necessarily have an ID.
+</OL>
+<P>Your <B>MOUNT</B> script must return one of the following exit codes to
+tell the Tape Coordinator whether or not it mounted the tape
+successfully:
+<UL>
+<P><LI>Code <B>0</B> (zero) indicates a successful mount, and the Tape
+Coordinator continues the backup operation. If the script or program
+called by the <B>MOUNT</B> instruction does not return this exit code, the
+Tape Coordinator never calls the <B>UNMOUNT</B> instruction.
+<P><LI>Code <B>1</B> indicates that mount attempt failed. The Tape
+Coordinator terminates the backup operation.
+<P><LI>Any other code indicates that the script was unable to access the correct
+tape. The Tape Coordinator prompts the operator to insert it.
+</UL>
+<P>When the Tape Coordinator executes the <B>UNMOUNT</B> script, it passes
+in two parameters in the following order.
+<OL TYPE=1>
+<P><LI>The tape device's pathname (as specified in the
+<B>/usr/afs/backup/tapeconfig</B> file)
+<P><LI>The tape operation, which is always <B>unmount</B>.
+</OL>
+<P>The following example script uses two of the parameters passed to it by the
+Backup System: <TT>tries</TT> and <TT>operation</TT>. It
+follows the recommended practice of exiting if the value of the
+<TT>tries</TT> parameter exceeds one, because that implies that the stacker
+is out of tapes.
+<P>For a <B>backup dump</B> or <B>backup savedb</B> operation, the
+routine calls the example <B>stackerCmd_NextTape</B> 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
+(is a restore operation, for example).
+<PRE> #! /bin/csh -f
+
+ set devicefile = $1
+ set operation = $2
+ set tries = $3
+ set tapename = $4
+ set tapeid = $5
+ set exit_continue = 0
+ set exit_abort = 1
+ set exit_interactive = 2
+ #--------------------------------------------
+ if (${tries} > 1) then
+ echo "Too many tries"
+ exit ${exit_interactive}
+ endif
+ if (${operation} == "unmount") then
+ echo "UnMount: Will leave tape in drive"
+ exit ${exit_continue}
+ endif
+ if ((${operation} == "dump") |\
+ (${operation} == "appenddump") |\
+ (${operation} == "savedb")) then
+
+ stackerCmd_NextTape ${devicefile}
+ if (${status} != 0)exit${exit_interactive}
+ echo "Will continue"
+ exit ${exit_continue}
+ endif
+
+ if ((${operation} == "labeltape") |\
+ (${operation} == "readlabel")) then
+ echo "Will continue"
+ exit ${exit_continue}
+ endif
+
+ echo "Prompt for tape"
+ exit ${exit_interactive}
+</PRE>
+<A NAME="IDX6963"></A>
+<A NAME="IDX6964"></A>
+<A NAME="IDX6965"></A>
+<A NAME="IDX6966"></A>
+<P><H3><A NAME="HDRWQ278" HREF="auagd002.htm#ToC_314">Eliminating the Search or Prompt for the Initial Tape</A></H3>
+<P>By default, the Tape Coordinator obtains the first tape it
+needs for a backup operation by reading the device configuration file for the
+appropriate tape device. If there is a <B>MOUNT</B> instruction in
+the file, the Tape Coordinator executes the referenced script. If the
+device configuration file does not exist or does not have a <B>MOUNT</B>
+instruction in it, the Tape Coordinator prompts you to insert the correct tape
+and press <B><Return></B>.
+<P>If you know in advance that an operation requires a tape, you can increase
+efficiency by placing the required tape in the drive before issuing the
+<B>backup</B> command and telling the Tape Coordinator's to skip its
+initial tape-acquisition steps. This both enables the operation to
+begin more quickly and eliminates that need for you to be present to insert a
+tape.
+<P>There are two ways to bypass the Tape Coordinator's initial
+tape-acquisition steps:
+<OL TYPE=1>
+<P><LI>Include the instruction <B>AUTOQUERY NO</B> in the device
+configuration file
+<P><LI>Include the <B>-noautoquery</B> flag to the <B>butc</B> command
+</OL>
+<P>To avoid any error conditions that require operator attention, be sure that
+the tape you are placing in the drive does not contain any unexpired dumps and
+is not write protected. If there is no permanent name on the
+tape's label and you are creating an initial dump, make sure that the AFS
+tape name either matches the volume set and dump set names or is
+<TT><NULL></TT>. Alternatively, suppress the Tape
+Coordinator's name verification step by assigning the value <B>NO</B>
+to the <B>NAME_CHECK</B> instruction in the device configuration file, as
+described in <A HREF="#HDRWQ280">Eliminating the AFS Tape Name Check</A>.
+<A NAME="IDX6967"></A>
+<A NAME="IDX6968"></A>
+<A NAME="IDX6969"></A>
+<P><H3><A NAME="HDRWQ279" HREF="auagd002.htm#ToC_315">Enabling Default Responses to Error Conditions</A></H3>
+<P>By default, the Tape Coordinator asks you how to respond
+when it encounters certain error conditions. To suppress the prompts
+and cause the Tape Coordinator to handle the errors in a predetermined manner,
+include the instruction <B>ASK NO</B> in the device configuration
+file. If you assign the value <B>YES</B>, or omit the
+<B>ASK</B> instruction completely, the Tape Coordinator prompts you for
+direction when it encounters one of the errors.
+<P>The following list describes the error conditions and the Tape
+Coordinator's response to them.
+<UL>
+<P><LI>The Backup System is unable to dump a volume while running the <B>backup
+dump</B> command. When you assign the value <B>NO</B>, the Tape
+Coordinator omits the volume from the dump and continues the operation.
+When you assign the value <B>YES</B>, it prompts to ask if you want to try
+to dump the volume again immediately, to omit the volume from the dump but
+continue the operation, or to terminate the operation.
+<P><LI>The Backup System is unable to restore a volume while running the
+<B>backup diskrestore</B>, <B>backup volrestore</B>, or <B>backup
+volsetrestore</B> command. When you assign the value <B>NO</B>,
+the Tape Coordinator continues the operation, omitting the problematic volume
+but restoring the remaining ones. When you assign the value
+<B>YES</B>, it prompts to ask if you want to omit the volume and continue
+the operation, or to terminate the operation.
+<P><LI>The Backup System cannot determine if the dump set includes any more tapes
+while running the <B>backup scantape</B> command (the command's
+reference page in the <I>IBM AFS Administration Reference</I> discusses
+possible reasons for this problem). When you assign the value
+<B>NO</B>, the Tape Coordinator proceeds as though there are more tapes
+and invokes the <B>MOUNT</B> script named in the device configuration
+file, or prompts the operator to insert the next tape. When you assign
+the value <B>YES</B>, it prompts to ask if there are more tapes to
+scan.
+<P><LI>The Backup System determines that the tape contains an unexpired dump
+while running the <B>backup labeltape</B> command. When you assign
+the value <B>NO</B>, it terminates the operation without relabeling the
+tape. With a <B>YES</B> value, the Tape Coordinator prompts to ask
+if you want to relabel the tape anyway.
+</UL>
+<A NAME="IDX6970"></A>
+<A NAME="IDX6971"></A>
+<A NAME="IDX6972"></A>
+<A NAME="IDX6973"></A>
+<P><H3><A NAME="HDRWQ280" HREF="auagd002.htm#ToC_316">Eliminating the AFS Tape Name Check</A></H3>
+<P>If a tape does not have a permanent name and you are writing
+an initial dump to it, then by default the Backup System verifies that the
+tape's AFS tape name is acceptable. It accepts three types of
+values:
+<UL>
+<P><LI>A name that reflects the volume set and dump level of the initial dump and
+the tape's place in the sequence of tapes for the dump set, as described
+in <A HREF="#HDRWQ253">Dump Names and Tape Names</A>. If the tape does not already have a permanent name,
+you can assign the AFS tape name by using the <B>-name</B> argument to the
+<B>backup labeltape</B> command.
+<P><LI>A <TT><NULL></TT> value, which results when you assign a permanent
+name, or provide no value for the <B>backup labeltape</B> command's
+<B>-name</B> argument.
+<P><LI>No AFS tape name at all, indicating that you have never labeled the tape
+or written a dump to it.
+</UL>
+<P>To bypass the name check, include the <B>NAME_CHECK NO</B> instruction
+in the device configuration file. This enables you to recycle a tape
+without first relabeling it, as long as all dumps on it are expired.
+(If a tape has unexpired dumps on it but you want to recycle it anyway, you
+must use the <B>backup labeltape</B> command to relabel it first.
+For this to work, the <B>ASK NO</B> instruction cannot appear in the
+device configuration file.)
+<P><H3><A NAME="HDRWQ281" HREF="auagd002.htm#ToC_317">Setting the Memory Buffer Size to Promote Tape Streaming</A></H3>
+<P>By default, the Tape Coordinator uses a 16-KB memory 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. Similarly, during a
+restore operation the Tape Coordinator by default buffers 32 KB of data from
+the tape device 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.
+<P>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.
+<P>To determine if altering the buffer size is helpful for your configuration,
+observe the tape device in operation to see if it is streaming, or consult the
+manufacturer. To set the buffer size, include the <B>BUFFERSIZE</B>
+instruction in the device configuration file. It takes an integer
+value, and optionally units, in the following format:
+<PRE> <B>BUFFERSIZE</B> <VAR>size</VAR>[{<B>k</B> | <B>K</B> | <B>m</B> | <B>M</B> | <B>g</B> | <B>G</B>}]
+</PRE>
+<P>where <VAR>size</VAR> 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 <B>k</B> or <B>K</B> to specify
+kilobytes, <B>m</B> or <B>M</B> for megabytes, and <B>g</B> or
+<B>G</B> for gigabytes. There is no space between the <VAR>size</VAR>
+value and the units letter.
+<P><H3><A NAME="HDRWQ282" HREF="auagd002.htm#ToC_318">Dumping Data to a Backup Data File</A></H3>
+<P>You can write dumps to a <I>backup data file</I> rather
+than to tape. This is useful if, for example, you want to transfer the
+data to a data-archiving system, such as a hierarchical storage management
+(HSM) system, that you use in conjunction with AFS and the Backup
+System. You can restore data from a backup data file into the file
+system as well. Using a backup data file is usually more efficient than
+issuing the equivalent <B>vos dump</B> and <B>vos restore</B> commands
+individually for multiple volumes.
+<P>Writing to a backup data file is simplest if it is on the local disk of the
+Tape Coordinator machine, but you can also write the file to an NFS-mounted
+partition that resides on a remote machine. It is even acceptable to
+write to a file in AFS, provided that the access control list (ACL) on its
+parent directory grants the necessary permissions, but it is somewhat circular
+to back up AFS data into AFS itself.
+<P>If the backup data file does not already exist when the Tape Coordinator
+attempts to write a dump to it, the Tape Coordinator creates it. For a
+restore operation to succeed, the file must exist and contain volume data
+previously written to it during a <B>backup dump</B> operation.
+<P>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 <B>backup dumpinfo</B> command issued
+with the <B>-id</B> option, the value in the <TT>Pos</TT> 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.
+<P>Before writing to a backup data file, you need to configure the file as
+though it were a tape device.
+<TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">A file pathname, rather than a tape device name, must appear in the third
+field of the <B>/usr/afs/backup/tapeconfig</B> file when the <B>FILE
+YES</B> instruction appears in the device configuration file, and vice
+versa. If the <B>tapeconfig</B> file instead refers to a tape
+device, dump operations appear to succeed but are inoperative. You
+cannot restore data that you accidently dumped to a tape device while the
+<B>FILE</B> instruction was set to <B>YES</B>. In the same way,
+if the <B>FILE</B> instruction is set to <B>NO</B>, the
+<B>tapeconfig</B> entry must refer to an actual tape device.
+</TD></TR></TABLE>
+<P><H3><A NAME="Header_319" HREF="auagd002.htm#ToC_319">To configure a backup data file</A></H3>
+<OL TYPE=1>
+<P><LI>Verify that you are authenticated as a user listed in the
+<B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
+listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
+<PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
+</PRE>
+<P><LI>Become the local superuser <B>root</B> on the machine, if you are not
+already, by issuing the <B>su</B> command.
+<PRE> % <B>su root</B>
+ Password: <VAR>root_password</VAR>
+</PRE>
+<P><LI><B>Optional</B>. Issue the <B>backup</B> command to enter
+interactive mode.
+<PRE> # <B>backup</B>
+</PRE>
+<P><LI>Choose the port offset number to assign to the file. If necessary,
+display previously assigned port offsets by issuing the <B>(backup)
+listhosts</B> command, which is fully described in <A HREF="#HDRWQ264">To display the list of configured Tape Coordinators</A>.
+<PRE> backup> <B>listhosts</B>
+</PRE>
+<P>As for a tape device, acceptable values are the integers <B>0</B>
+(zero) through <B>58510</B> (the Backup System can track a maximum of
+58,511 port offset numbers). Each port offset must be unique in the
+cell, but you can associate any number them with a single Tape Coordinator
+machine. You do not have to assign port offset numbers
+sequentially.
+<P><LI>Issue the <B>(backup) addhost</B> command to register the backup data
+file's port offset in the Backup Database.
+<PRE> backup> <B>addhost</B> <<VAR>tape machine name</VAR>> [<<VAR>TC port offset</VAR>>]
+</PRE>
+<P>where
+<DL>
+<P><DT><B>addh
+</B><DD>Is the shortest acceptable abbreviation of <B>addhost</B>.
+<P><DT><B><VAR>tape machine name</VAR>
+</B><DD>Specifies the fully qualified hostname of the Tape Coordinator machine you
+invoke to write to the backup data file.
+<P><DT><B><VAR>TC port offset</VAR>
+</B><DD>Specifies the file's port offset number. You must provide this
+argument unless the default value of <B>0</B> (zero) is
+appropriate.
+</DL>
+<P><LI><A NAME="LITAPECONFIG-FILE"></A>Using a text editor, create an entry for the backup
+data file in the local <B>/usr/afs/backup/tapeconfig</B> file, using the
+standard syntax:
+<PRE> [<VAR>capacity</VAR> <VAR>filemark_size</VAR>] <VAR>device_name</VAR> <VAR>port_offset</VAR>
+</PRE>
+<P>where
+<DL>
+<P><DT><B><VAR>capacity</VAR>
+</B><DD>Specifies the amount of space on the partition that houses the backup data
+file that you want to make available for the file. To avoid the
+complications that arise from filling up the partition, it is best to provide
+a value somewhat smaller than the actual amount of space you expect to be
+available when the dump operation runs, and never larger than the maximum file
+size allowed by the operating system.
+<P>Specify a numerical value followed by a letter that indicates units, with
+no intervening space. The letter <B>k</B> or <B>K</B> indicates
+kilobytes, <B>m</B> or <B>M</B> indicates megabytes, and <B>g</B>
+or <B>G</B> indicates gigabytes. If you omit the units letter, the
+default is kilobytes. If you leave this field empty, the Tape
+Coordinator uses the maximum acceptable value (2048 GB or 2 TB). Also
+leave the <VAR>filemark_size</VAR> field empty in that case.
+<P><DT><B><VAR>filemark_size</VAR>
+</B><DD>Specify the value <B>0</B> (zero) or leave both this field and the
+<VAR>capacity</VAR> field empty. In the latter case, the Tape Coordinator
+also uses the value zero.
+<P><DT><B><VAR>device_name</VAR>
+</B><DD>Specifies the complete pathname of the backup data file. Rather
+than specifying an actual file pathname, however, the recommended
+configuration is to create a symbolic link in the <B>/dev</B> directory
+that points to the actual file pathname, and record the symbolic link in this
+field. This configuration provides these advantages:
+<UL>
+<P><LI>It makes the <VAR>device_name</VAR> portion of the
+<B>CFG_</B><VAR>device_name</VAR>, of the
+<B>TE_</B><VAR>device_name</VAR>, and of the
+<B>TL_</B><VAR>device_name</VAR> filenames as short as possible.
+Because the symbolic link is in the <B>/dev</B> directory as though it is
+a tape device, you strip off the entire <B>/dev/</B> prefix when forming
+the filename, instead of just the initial slash (<B>/</B>). If, for
+example, the symbolic link is called <B>/dev/FILE</B>, the device
+configuration file's name is <B>CFG_FILE</B>, whereas if the actual
+pathname /<B>var/tmp/FILE</B> appears in the <B>tapeconfig</B> file,
+the configuration file's name must be <B>CFG_var_tmp_FILE</B>.
+<P><LI>It provides for a more graceful, and potentially automated, recovery if
+the Tape Coordinator cannot write a complete dump into the backup data file
+(for example, because the partition housing the backup data file becomes
+full). The Tape Coordinator's reaction to this problem is to
+invoke the <B>MOUNT</B> script, or to prompt you if the <B>MOUNT</B>
+instruction does not appear in the configuration file.
+<UL>
+<P><LI>If there is a <B>MOUNT</B> script, you can prepare for this situation
+by adding a subroutine to the script that changes the symbolic link to point
+to another backup data file on a partition where there is space
+available.
+<P><LI>If there is no <B>MOUNT</B> instruction, the prompt enables you
+manually to change the symbolic link to point to another backup data file and
+then press <<B>Return</B>> to signal that the Tape Coordinator can
+continue the operation.
+</UL>
+<P>If this field names the actual file, there is no way to recover from
+exhausting the space on the partition. You cannot change the
+<B>tapeconfig</B> file in the middle of an operation.
+</UL>
+<P><DT><B><VAR>port_offset</VAR>
+</B><DD>Specifies the port offset number that you chose for the backup data
+file.
+</DL>
+<P><LI>Create the device configuration file <B>CFG_</B><VAR>device_name</VAR>
+in the Tape Coordinator machine's <B>/usr/afs/backup</B>
+directory. Include the <B>FILE YES</B> instruction in the
+file.
+<P>Construct the <VAR>device_name</VAR> portion of the name based on the device
+name you recorded in the <B>tapeconfig</B> file in Step <A HREF="#LITAPECONFIG-FILE">6</A>. If, as recommended, you recorded a symbolic link
+name, strip off the <B>/dev/</B> string and replace any other slashes
+(<B>/</B>) in the name with underscores (<B>_</B>). For
+example, <B>CFG_FILE</B> is the appropriate name if the symbolic link is
+<B>/dev/FILE</B>. If you recorded the name of an actual file, then
+strip off the initial slash only and replace any other slashes in the name
+with underscores. For a backup data file called
+<B>/var/tmp/FILE</B>, the appropriate device configuration filename is
+<B>CFG_var_tmp_FILE</B>.
+<P><LI>If you chose in Step <A HREF="#LITAPECONFIG-FILE">6</A> to record a symbolic link name in the <VAR>device_name</VAR>
+field of the <B>tapeconfig</B> entry, then you must do one of the
+following:
+<UL>
+<P><LI>Use the <B>ln -s</B> command to create the appropriate symbolic link
+in the <B>/dev</B> directory
+<P><LI>Write a script that initializes the backup data file in this way, and
+include a <B>MOUNT</B> instruction in the device configuration file to
+invoke the script. An example script appears following these
+instructions.
+</UL>
+</OL>
+<P>You do not need to create the backup data file itself, because the Tape
+Coordinator does so if the file does not exist when the dump operation
+begins.
+<P>The following example script illustrates how you can automatically create a
+symbolic link to the backup data file during the preparation phase for writing
+to the file. When the Tape Coordinator is executing a <B>backup
+dump</B>, <B>backup restore</B>, <B>backup savedb</B>, or
+<B>backup restoredb</B> operation, the routine invokes the UNIX <B>ln
+-s</B> command to create a symbolic link from the backup data file named in
+the <B>tapeconfig</B> file to the actual file to use (this is the
+recommended method). It uses the values of the <TT>tapename</TT> and
+<TT>tapeid</TT> parameters passed to it by the Backup System when
+constructing the filename.
+<P>The routine makes use of two other parameters as well:
+<TT>tries</TT> and <TT>operation</TT>. The <TT>tries</TT>
+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
+(<TT>exit_interactive</TT>), 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 <B>tapeconfig</B> file.
+<PRE> #! /bin/csh -f
+ set devicefile = $1
+ set operation = $2
+ set tries = $3
+ set tapename = $4
+ set tapeid = $5
+ set exit_continue = 0
+ set exit_abort = 1
+ set exit_interactive = 2
+ #--------------------------------------------
+ if (${tries} > 1) then
+ echo "Too many tries"
+ exit ${exit_interactive}
+ endif
+ if (${operation} == "labeltape") then
+ echo "Won't label a tape/file"
+ exit ${exit_abort}
+ endif
+ if ((${operation} == "dump") |\
+ (${operation} == "appenddump") |\
+ (${operation} == "restore") |\
+ (${operation} == "savedb") |\
+ (${operation} == "restoredb")) then
+
+ /bin/rm -f ${devicefile}
+ /bin/ln -s /hsm/${tapename}_${tapeid} ${devicefile}
+ if (${status} != 0) exit ${exit_abort}
+ endif
+
+ exit ${exit_continue}
+</PRE>
+<HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd010.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auagd012.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
+<!-- Begin Footer Records ========================================== -->
+<P><HR><B>
+<br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
+</B>
+<!-- End Footer Records ============================================ -->
+<A NAME="Bot_Of_Page"></A>
+</BODY></HTML>
git://git.openafs.org / openafs.git / blobdiff