doc/html/AdminGuide/auagd011.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
   2 <HTML><HEAD>
   3 <TITLE>Administration Guide</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3570/auagd000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 2 Oct 2000 at 11:42:14                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 11:42:13">
   8 <META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 11:42:13">
   9 <META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 11:42:13">
  10 </HEAD><BODY>
  11 <!-- (C) IBM Corporation 2000. All Rights Reserved    -->
  12 <BODY bgcolor="ffffff">
  13 <!-- End Header Records  ============================================ -->
  14 <A NAME="Top_Of_Page"></A>
  15 <H1>Administration Guide</H1>
  16 <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>
  17 <HR><H1><A NAME="HDRWQ248" HREF="auagd002.htm#ToC_270">Configuring the AFS Backup System</A></H1>
  18 <P>The AFS Backup System helps you to create backup copies of
  19 data from AFS volumes and to restore data to the file system if it is lost or
  20 corrupted. This chapter explains how to configure the Backup
  21 System. For instructions on backing up and restoring data and
  22 displaying dump records, see <A HREF="auagd012.htm#HDRWQ283">Backing Up and Restoring AFS Data</A>.
  23 <HR><H2><A NAME="HDRWQ249" HREF="auagd002.htm#ToC_271">Summary of Instructions</A></H2>
  24 <P>This chapter explains how to perform the following tasks by
  25 using the indicated commands:
  26 <BR>
  27 <TABLE WIDTH="100%">
  28 <TR>
  29 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Determine tape capacity and filemark size
  30 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fms</B>
  31 </TD></TR><TR>
  32 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Define Tape Coordinator entry in Backup Database
  33 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup addhost</B>
  34 </TD></TR><TR>
  35 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Remove Tape Coordinator entry from Backup Database
  36 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup delhost</B>
  37 </TD></TR><TR>
  38 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Display Tape Coordinator entries from Backup Database
  39 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup listhosts</B>
  40 </TD></TR><TR>
  41 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Create volume set
  42 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup addvolset</B>
  43 </TD></TR><TR>
  44 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Add volume entry to volume set
  45 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup addvolentry</B>
  46 </TD></TR><TR>
  47 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">List volume sets and entries
  48 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup listvolsets</B>
  49 </TD></TR><TR>
  50 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Delete volume set from Backup Database
  51 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup delvolset</B>
  52 </TD></TR><TR>
  53 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Delete volume entry from volume set
  54 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup delvolentry</B>
  55 </TD></TR><TR>
  56 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Define dump level
  57 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup adddump</B>
  58 </TD></TR><TR>
  59 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Change expiration date on existing dump level
  60 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup setexp</B>
  61 </TD></TR><TR>
  62 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Delete dump level from dump hierarchy
  63 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup deldump</B>
  64 </TD></TR><TR>
  65 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Display dump hierarchy
  66 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup listdumps</B>
  67 </TD></TR><TR>
  68 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Label tape
  69 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup labeltape</B>
  70 </TD></TR><TR>
  71 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Read label on tape
  72 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup readlabel</B>
  73 </TD></TR></TABLE>
  74 <HR><H2><A NAME="HDRWQ251" HREF="auagd002.htm#ToC_272">Introduction to Backup System Features</A></H2>
  75 <A NAME="IDX6805"></A>
  76 <P>The AFS Backup System is highly flexible, enabling you to control most
  77 aspects of the backup process, including how often backups are performed,
  78 which volumes are backed up, and whether to dump all of the data in a volume
  79 or just the data that has changed since the last dump operation. You
  80 can also take advantage of several features that automate much of the backup
  81 process.
  82 <P>To administer and use the Backup System most efficiently, it helps to be
  83 familiar with its basic features, which are described in the following
  84 sections. For pointers to instructions for implementing the features as
  85 you configure the Backup System in your cell, see <A HREF="#HDRWQ257">Overview of Backup System Configuration</A>.
  86 <P><H3><A NAME="HDRWQ252" HREF="auagd002.htm#ToC_273">Volume Sets and Volume Entries</A></H3>
  87 <A NAME="IDX6806"></A>
  88 <A NAME="IDX6807"></A>
  89 <A NAME="IDX6808"></A>
  90 <A NAME="IDX6809"></A>
  91 <A NAME="IDX6810"></A>
  92 <P>When you back up AFS data, you specify which data to include in terms of
  93 complete volumes rather than individual files. More precisely, you
  94 define groups of volumes called <I>volume sets</I>, each of which includes
  95 one or more volumes that you want to back up in a single operation. You
  96 must include a volume in a volume set to back it up, because the command that
  97 backs up data (the <B>backup dump</B> command) does not accept individual
  98 volume names.
  99 <P>A volume set consists of one or more <I>volume entries</I>, each of
 100 which specifies which volumes to back up based on their location (file server
 101 machine and partition) and volume name. You can use a wildcard notation
 102 to include all volumes that share a location, a common character string in
 103 their names, or both.
 104 <P>For instructions on creating and removing volume sets and volume entries,
 105 see <A HREF="#HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</A>.
 106 <P><H3><A NAME="Header_274" HREF="auagd002.htm#ToC_274">Dumps and Dump Sets</A></H3>
 107 <A NAME="IDX6811"></A>
 108 <A NAME="IDX6812"></A>
 109 <A NAME="IDX6813"></A>
 110 <A NAME="IDX6814"></A>
 111 <A NAME="IDX6815"></A>
 112 <A NAME="IDX6816"></A>
 113 <A NAME="IDX6817"></A>
 114 <A NAME="IDX6818"></A>
 115 <A NAME="IDX6819"></A>
 116 <A NAME="IDX6820"></A>
 117 <P>A <I>dump</I> is the collection of data that results from backing up a
 118 volume set. A <I>full dump</I> includes all of the data in every
 119 volume in the volume set, as it exists at the time of the dump
 120 operation. An <I>incremental dump</I> includes only some of the
 121 data from the volumes in the volume set, namely those files and directory
 122 structures that have changed since a specified previous dump operation was
 123 performed. The previous dump is referred to as the incremental
 124 dump's <I>parent dump</I>, and it can be either a full dump or an
 125 incremental dump itself.
 126 <P>A <I>dump set</I> is a collection of one or more dumps stored together
 127 on one or more tapes. The first dump in the dump set is the
 128 <I>initial dump</I>, and any subsequent dump added onto the end of an
 129 existing dump set is an <I>appended dump</I>. Appending dumps is
 130 always optional, but maximizes use of a tape's capacity. In
 131 contrast, creating only initial dumps can result in many partially filled
 132 tapes, because an initial dump must always start on a new tape, but does not
 133 necessarily extend to the end of the tape. Appended dumps do not have
 134 to be related to one another or to the initial dump (they do not have to be
 135 dumps of the same or related volume sets), but well-planned appending can
 136 reduce the number of times you have to change tapes during a restore
 137 operation. For example, it can make sense to append incremental dumps
 138 of a volume set together in a single dump set.
 139 <P>All the records for a dump set are indexed together in the Backup Database
 140 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,
 141 you must delete the initial dump record, and doing so deletes the records for
 142 all dumps in the dump set. Similarly, you cannot recycle just one tape
 143 in a dump set without deleting the database records of all tapes in the dump
 144 set.
 145 <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>.
 146 <P><H3><A NAME="Header_275" HREF="auagd002.htm#ToC_275">Dump Hierarchies, Dump Levels and Expiration Dates</A></H3>
 147 <A NAME="IDX6821"></A>
 148 <A NAME="IDX6822"></A>
 149 <A NAME="IDX6823"></A>
 150 <A NAME="IDX6824"></A>
 151 <A NAME="IDX6825"></A>
 152 <A NAME="IDX6826"></A>
 153 <P>A <I>dump hierarchy</I> is a logical structure that defines the
 154 relationship between full and incremental dumps; that is, it defines
 155 which dump serves as the parent for an incremental dump. Each
 156 individual component of a hierarchy is a <I>dump level</I>. When
 157 you create a dump by issuing the <B>backup dump</B> command, you specify a
 158 volume set name and a dump level name. The Backup System uses the dump
 159 level to determine whether the dump is full or incremental, and if
 160 incremental, which dump level to use as the parent.
 161 <P>You can associate an <I>expiration date</I> with a dump level, to
 162 define when a dump created at that level expires. The Backup System
 163 refuses to overwrite a tape until all dumps in the dump set to which the tape
 164 belongs have expired, so assigning expiration dates automatically determines
 165 how you recycle tapes. You can define an expiration date either in
 166 absolute terms (for example, 13 January 2000) or relative terms (for example,
 167 30 days from when the dump is created). You can also change the
 168 expiration date associated with a dump level (but not with an actual dump that
 169 has already been created at that level).
 170 <P>For instructions on creating dump hierarchies, assigning expiration dates,
 171 and establishing a tape recycling schedule, see <A HREF="#HDRWQ267">Defining and Displaying the Dump Hierarchy</A>.
 172 <A NAME="IDX6827"></A>
 173 <A NAME="IDX6828"></A>
 174 <A NAME="IDX6829"></A>
 175 <A NAME="IDX6830"></A>
 176 <A NAME="IDX6831"></A>
 177 <A NAME="IDX6832"></A>
 178 <P><H3><A NAME="HDRWQ253" HREF="auagd002.htm#ToC_276">Dump Names and Tape Names</A></H3>
 179 <P>When you create a dump, the Backup System creates a Backup
 180 Database record for it, assigning a name comprising the volume set name and
 181 the last element in the dump level pathname:
 182 <PRE>   <VAR>volume_set_name</VAR><B>.</B><VAR>dump_level_name</VAR>
 183 </PRE>
 184 <P>For example, a dump of the volume set <B>user</B> at the dump level
 185 <B>/sunday/friday</B> is called <B>user.friday</B>. The
 186 Backup System also assigns a unique <I>dump ID</I> number to the dump to
 187 distinguish it from other dumps with the same name that possibly exist.
 188 <P>The Backup System assigns a similar <I>AFS tape name</I> to each tape
 189 that contains a dump set, reflecting the volume set and dump level of the dump
 190 set's initial dump, plus a numerical index of the tape's position in
 191 the dump set, and a unique dump ID number:
 192 <PRE>   <VAR>volume_set_name</VAR><B>.</B><VAR>dump_level_name</VAR><B>.</B><VAR>tape_index</VAR> (<VAR>dump ID</VAR>)
 193 </PRE>
 194 <P>For example, the second tape in a dump set whose initial dump is of the
 195 volume set <B>uservol</B> at the dump level <B>/sunday/friday</B> has
 196 AFS tape name like <B>uservol.friday.2</B>
 197 (<B>914382400</B>).
 198 <P>In addition to its AFS tape name, a tape can have an optional
 199 <I>permanent name</I> that you assign. Unlike the AFS tape name,
 200 the permanent name does not have to indicate the volume set and dump level of
 201 the initial (or any other) dump, and so does not change depending on the
 202 contents of the tape. The Backup System does not require a certain
 203 format for permanent names, so you need to make sure that each tape's
 204 name is unique. If a tape has a permanent name, the Backup System uses
 205 it rather than the AFS tape name when referring to the tape in prompts and the
 206 output from most <B>backup</B> commands, but still tracks the AFS tape
 207 name internally.
 208 <P><H3><A NAME="HDRWQ254" HREF="auagd002.htm#ToC_277">Tape Labels, Dump Labels, and EOF Markers</A></H3>
 209 <A NAME="IDX6833"></A>
 210 <A NAME="IDX6834"></A>
 211 <A NAME="IDX6835"></A>
 212 <A NAME="IDX6836"></A>
 213 <P>Every tape used in the Backup System has a magnetic label at the beginning
 214 that records the tape's name, capacity, and other information. You
 215 can use the <B>backup labeltape</B> command to write a label, or the
 216 <B>backup dump</B> command creates one automatically if you use an
 217 unlabeled tape. The label records the following information:
 218 <UL>
 219 <P><LI>The tape's permanent name, which you can assign by using the
 220 <B>-pname</B> argument to the <B>backup labeltape</B> command.
 221 It can be any string of up to 32 characters. If you do not assign a
 222 permanent name, the Backup System records the value <TT>&lt;NULL></TT> when
 223 you use the <B>backup labeltape</B> command to assign an AFS tape name, or
 224 when you use the <B>backup dump</B> command to write a dump to the
 225 tape.
 226 <P><LI>The tape's AFS <I>tape name</I>, which can be one of three types
 227 of values:
 228 <UL>
 229 <P><LI>A name that reflects the volume set and dump level of the dump set's
 230 initial dump and the tape's place in the sequence of tapes for the dump
 231 set, as described in <A HREF="#HDRWQ253">Dump Names and Tape Names</A>. If the tape does not have a permanent name, you can
 232 assign the AFS tape name by using the <B>-name</B> argument to the
 233 <B>backup labeltape</B> command.
 234 <P><LI>The value <TT>&lt;NULL></TT>, which results when you assign a permanent
 235 name, or provide no value for the <B>backup labeltape</B> command's
 236 <B>-name</B> argument.
 237 <P><LI>No AFS tape name at all, indicating that you have never labeled the tape
 238 or written a dump to it.
 239 </UL>
 240 <P>If a tape does not already have an actual AFS tape name when you write a
 241 dump to it, the Backup System constructs and records the appropriate AFS tape
 242 name. If the tape does have an AFS tape name and you are writing an
 243 initial dump, then the name must correctly reflect the dump's volume set
 244 and dump level.
 245 <P><LI>The capacity, or <I>size</I>, of the tape, followed by a letter that
 246 indicates the unit of measure (<TT>k</TT> or <TT>K</TT> for kilobytes,
 247 <TT>m</TT> or <TT>M</TT> for megabytes, <TT>g</TT> or <TT>G</TT> for
 248 gigabytes, or <TT>t</TT> or <TT>T</TT> for terabytes). The
 249 tape's manufacturer determines the tape's capacity. For
 250 further discussion of how the Backup System uses the value in the capacity
 251 field, see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>.
 252 </UL>
 253 <P>For information about labeling tapes, see <A HREF="#HDRWQ272">Writing and Reading Tape Labels</A>.
 254 <P>In addition to the tape label, the Backup System writes a <I>dump
 255 label</I> on the tape for every appended dump (the tape label and dump label
 256 are the same for the initial dump). A dump label records the following
 257 information:
 258 <UL>
 259 <P><LI>The name of the tape containing the dump
 260 <P><LI>The date and time that the dump operation began
 261 <P><LI>The cell to which the volumes in the dump belong
 262 <P><LI>The dump's size in kilobytes
 263 <P><LI>The dump's dump level
 264 <P><LI>The dump's dump ID
 265 </UL>
 266 <P>The Backup System writes a <I>filemark</I> (also called an End-of-File
 267 or EOF marker) between the data from each volume in a dump. The tape
 268 device's manufacturer determines the filemark size, which is typically
 269 between 2 KB and 2 MB; in general, the larger the usual capacity of the
 270 tapes that the device uses, the larger the filemark size. If a dump
 271 contains a small amount of data from each of a large number of volumes, as
 272 incremental dumps often do, then the filemark size can significantly affect
 273 how much volume data fits on the tape. To enable the Backup System to
 274 factor in filemark size as it writes a dump, you can record the filemark size
 275 in a configuration file; see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>.
 276 <P><H3><A NAME="HDRWQ255" HREF="auagd002.htm#ToC_278">Tape Coordinator Machines, Port Offsets, and Backup Data Files</A></H3>
 277 <A NAME="IDX6837"></A>
 278 <A NAME="IDX6838"></A>
 279 <A NAME="IDX6839"></A>
 280 <A NAME="IDX6840"></A>
 281 <P>A <I>Tape Coordinator machine</I> is a machine that drives one or more
 282 attached tape devices used for backup operations. It must run the AFS
 283 client software (the Cache Manager) but reside in a physically secure location
 284 to prevent unauthorized access to its console. Before backup operations
 285 can run on a Tape Coordinator machine, each tape device on the machine must be
 286 registered in the Backup Database, and certain files and directories must
 287 exist on the machine's local disk; for instructions, see <A HREF="#HDRWQ262">To configure a Tape Coordinator machine</A>.
 288 <P>Each tape device on a Tape Coordinator machine listens for backup requests
 289 on a different UNIX port. You pick the port indirectly by assigning a
 290 <I>port offset number</I> to the tape device. The Backup System
 291 sets the device's actual port by adding the port offset to a base port
 292 number that it determines internally. For instructions on assigning
 293 port offset numbers, see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>.
 294 <P>For a tape device to perform backup operations, a Backup Tape Coordinator
 295 (<B>butc</B>) process dedicated to the device must be running actively on
 296 the Tape Coordinator machine. You then direct backup requests to the
 297 device's Tape Coordinator by specifying its port offset number with the
 298 <B>-portoffset</B> argument to the <B>backup</B> command.
 299 <P>In addition to writing backup data to tape, you can direct it to a
 300 <I>backup data file</I> on the local disk of a Tape Coordinator
 301 machine. You can then to transfer the data to a data-archiving system,
 302 such as a hierarchical storage management (HSM) system, that you use in
 303 conjunction with AFS and the Backup System. A backup data file has a
 304 port offset like a tape device. For instructions on configuring backup
 305 data files, see <A HREF="#HDRWQ282">Dumping Data to a Backup Data File</A>.
 306 <P><H3><A NAME="HDRWQ256" HREF="auagd002.htm#ToC_279">The Backup Database and Backup Server Process</A></H3>
 307 <A NAME="IDX6841"></A>
 308 <A NAME="IDX6842"></A>
 309 <P>The <I>Backup Database</I> is a replicated administrative database
 310 maintained by the <I>Backup Server</I> process on the cell's database
 311 server machines. Like the other AFS database server processes, the
 312 Backup Server uses the Ubik utility to keep the various copies of the database
 313 synchronized (for a discussion of Ubik, see <A HREF="auagd007.htm#HDRWQ52">Replicating the AFS Administrative Databases</A>).
 314 <P>The Backup Database records the following information:
 315 <UL>
 316 <P><LI>The Tape Coordinator machine's hostname and the port offset number
 317 for each tape device used for backup operations
 318 <P><LI>The dump hierarchy, which consists of its component dump levels and their
 319 associated expiration dates
 320 <P><LI>The volume sets and their component volume entries
 321 <P><LI>A record for each dump, which includes the name of each tape it appears
 322 on, a list of the volumes from which data is included, the dump level, the
 323 expiration date, and the dump ID of the initial dump with which the dump is
 324 associated
 325 <P><LI>A record for each tape that houses dumped data
 326 </UL>
 327 <P><H3><A NAME="Header_280" HREF="auagd002.htm#ToC_280">Interfaces to the Backup System</A></H3>
 328 <P>The <B>backup</B> suite of commands is the administrative interface
 329 to the Backup System. You can issue the commands in a command shell (or
 330 invoke them in a shell script) on any AFS client or server machine from which
 331 you can access the <B>backup</B> binary. In the conventional
 332 configuration, the binary resides on the local disk.
 333 <P>The <B>backup</B> command suite provides an <I>interactive
 334 mode</I>, in which you can issue multiple commands over a persistent
 335 connection to the Backup Server and the Volume Location (VL) Server.
 336 Interactive mode has several convenient features, including the
 337 following:
 338 <UL>
 339 <P><LI>You need to type only the operation code, omitting the initial
 340 <B>backup</B> string.
 341 <P><LI>If you assume another AFS identity or specify a foreign cell as you enter
 342 interactive mode, it applies to all subsequent commands.
 343 <P><LI>You do not need to enclose shell metacharacters in double quotes.
 344 <P><LI>You can track current and pending operations with the <B>(backup)
 345 jobs</B> command, which is available only in this mode.
 346 <P><LI>You can cancel current and pending operations with the <B>(backup)
 347 kill</B> command, which is available only in this mode.
 348 </UL>
 349 <P>Before issuing a command that requires reading or writing a tape (or backup
 350 data file), you must also open a connection to the Tape Coordinator machine
 351 that is attached to the relevant tape device (or that has the backup data file
 352 on its local disk), and issue the <B>butc</B> command to initialize the
 353 Tape Coordinator process. The process must continue to run and the
 354 connection remain open as long as you need to use the tape device or file for
 355 backup operations.
 356 <P>For further discussion and instructions, see <A HREF="auagd012.htm#HDRWQ286">Using the Backup System's Interfaces</A>.
 357 <HR><H2><A NAME="HDRWQ257" HREF="auagd002.htm#ToC_281">Overview of Backup System Configuration</A></H2>
 358 <A NAME="IDX6843"></A>
 359 <P>Before you can use the Backup System to back up and restore data, you must
 360 configure several of its basic components. The indicated sections of
 361 this chapter explain how to perform the following configuration tasks:
 362 <UL>
 363 <P><LI>Determining a tape's capacity and a tape device's filemark size,
 364 and recording them in the <B>/usr/afs/backup/tapeconfig</B> file (see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>)
 365 <P><LI>Determining how to grant administrative privilege to backup operators (see
 366 <A HREF="#HDRWQ260">Granting Administrative Privilege to Backup Operators</A>)
 367 <P><LI>Configuring Tape Coordinator machines, tape devices, and backup data files
 368 (see <A HREF="#HDRWQ261">Configuring Tape Coordinator Machines and Tape Devices</A>)
 369 <P><LI>Defining volume sets and volume entries (see <A HREF="#HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</A>)
 370 <P><LI>Defining dump levels to create a dump hierarchy (see <A HREF="#HDRWQ267">Defining and Displaying the Dump Hierarchy</A>)
 371 <P><LI>Labeling tapes (see <A HREF="#HDRWQ272">Writing and Reading Tape Labels</A>)
 372 <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>)
 373 </UL>
 374 <P>If you have already configured all of the components required for
 375 performing a backup dump or restore operation, you can proceed to the
 376 instructions in <A HREF="auagd012.htm#HDRWQ296">Backing Up Data</A> and <A HREF="auagd012.htm#HDRWQ306">Restoring and Recovering Data</A>.
 377 <HR><H2><A NAME="HDRWQ258" HREF="auagd002.htm#ToC_282">Configuring the tapeconfig File</A></H2>
 378 <A NAME="IDX6844"></A>
 379 <A NAME="IDX6845"></A>
 380 <A NAME="IDX6846"></A>
 381 <A NAME="IDX6847"></A>
 382 <A NAME="IDX6848"></A>
 383 <P>Several factors interact to determine how much data the Tape Coordinator
 384 can fit on a tape:
 385 <UL>
 386 <P><LI>The tape's capacity (size), as set by the tape manufacturer.
 387 <P><LI>The tape device's filemark size, as set by the tape device's
 388 manufacturer. Recall from <A HREF="#HDRWQ254">Tape Labels, Dump Labels, and EOF Markers</A> that the Tape Coordinator writes a filemark between the data
 389 from each volume in a dump. If a dump contains a small amount of data
 390 from each of a large number of volumes, as incremental dumps often do, then
 391 the filemark size can significantly affect how much volume data fits on the
 392 tape.
 393 <P><LI>Whether or not you use the tape device's compression mode.
 394 </UL>
 395 <P>(The amount of data that can fit in a backup data file is determined by
 396 amount of space available on the partition, and the operating system's
 397 maximum file size. The Tape Coordinator does not write filemarks when
 398 writing to a backup data file. For further information about
 399 configuring a Tape Coordinator to write to a backup data file, see <A HREF="#HDRWQ282">Dumping Data to a Backup Data File</A>.)
 400 <P>As the Tape Coordinator (<B>butc</B>) process initializes, it reads the
 401 <B>/usr/afs/backup/tapeconfig</B> file on its local disk to learn the tape
 402 capacity and filemark size (for a tape device) or the file size (for a backup
 403 data file) to use for dump operations. When you begin a dump operation,
 404 the Tape Coordinator also reads the tape or backup data file's label to
 405 see if you have recorded a different tape capacity or file size. If you
 406 have, the value on the label overrides the default value from the
 407 <B>tapeconfig</B> file.
 408 <P>As the Tape Coordinator writes data to a tape during a dump operation, it
 409 uses the capacity and filemark information to track how much tape it has used
 410 and how much remains before the physical end-of-tape (EOT). Shortly
 411 before reaching EOT, the Tape Coordinator stops writing and requests a new
 412 tape. Similarly, it uses a backup data file's size to know when it
 413 is about to exhaust the space in the file. If the Tape Coordinator
 414 reaches the EOT unexpectedly, it recovers by obtaining a new tape and writing
 415 to it the entire contents of the volume it was writing when it reached
 416 EOT. The interrupted volume remains on the first tape, but is never
 417 used.
 418 <P>Many tape devices use tapes that can accommodate multiple gigabytes, or
 419 even multiple terabytes, of backup data, especially if you use the
 420 device's compression mode. When writing to such devices and tapes,
 421 allowing the Tape Coordinator to hit the EOT unexpectedly is generally
 422 recommended. The devices write data so quickly that it usually does not
 423 take much extra time to rewrite the interrupted volume on the new tape.
 424 Similarly, they compress data so well that the data abandoned on the first
 425 tape from the interrupted volume does not constitute a waste of much
 426 tape.
 427 <P>When writing to tapes that accommodate a smaller amount of data (say, less
 428 than two GB), it is better to avoid having the Tape Coordinator hit EOT
 429 unexpectedly. AFS supports volumes up to 2 GB in size, so an
 430 interrupted volume can in fact take up most of the tape. For such
 431 tapes, recording accurate values for tape capacity and filemark size, if
 432 possible, helps to maximize both use of tape and the efficiency of dump
 433 operations. The following discussion of the fields in the
 434 <B>tapeconfig</B> file explains how to determine the appropriate
 435 values.
 436 <P>Use a text editor to create an entry in a Tape Coordinator's
 437 <B>tapeconfig</B> file for each tape device or backup data file that it
 438 uses. Each device or file's entry is on its own line and has the
 439 following format:
 440 <PRE>   [<VAR>capacity</VAR>   <VAR>filemark_size</VAR>]    <VAR>device_name</VAR>    <VAR>port_offset</VAR>
 441 </PRE>
 442 <P>where
 443 <DL>
 444 <P><DT><B><VAR>capacity</VAR>
 445 </B><DD>Specifies the capacity of the tapes used with a tape device, or the amount
 446 of data to write into a backup data file. Specify an integer value
 447 followed by a letter that indicates units, with no intervening space.
 448 The letter <B>k</B> or <B>K</B> indicates kilobytes, <B>m</B> or
 449 <B>M</B> indicates megabytes, <B>g</B> or <B>G</B> indicates
 450 gigabytes, and <B>t</B> or <B>T</B> indicates terabytes. If the
 451 units letter is omitted, the default is kilobytes.
 452 <P>To determine the capacity of a tape under two GB in size that you are going
 453 to use in regular (noncompression) mode, you can either use the value that the
 454 tape's manufacturer specifies on the tape's packaging or use the
 455 <B>fms</B> command to calculate the capacity, as described later in this
 456 section. To avoid having the Tape Coordinator reach the EOT
 457 unexpectedly, it is best to record in the <B>tapeconfig</B> file or on the
 458 label a capacity that is about 10% smaller than the actual capacity of the
 459 tape. To calculate the appropriate value for a small tape used in
 460 compression mode, one method is to multiply the tape capacity (as recorded by
 461 the manufacturer) by the device's compression ratio.
 462 <P>For tapes that hold multiple gigabytes or terabytes of data, or if using a
 463 tape drive's compression mode, the recommended configuration is to record
 464 a value quite a bit (for instance, two times) larger than the maximum amount
 465 you believe can fit on the tape. It is not generally worthwhile to run
 466 the <B>fms</B> command on large tapes, even in noncompression mode.
 467 The command definitely does not yield accurate results in compression
 468 mode. The Tape Coordinator is likely to reach the EOT unexpectedly, but
 469 compression mode fits so much data on the tape that the data abandoned from an
 470 interrupted volume does not represent much of the tape's capacity.
 471 <P>For a backup data file, record a value slightly smaller than the amount of
 472 space available on the partition, and definitely smaller than the operating
 473 system's maximum file size. It is also best to limit the ability
 474 of other processes to write to the partition, to prevent them from using up
 475 the space in the partition.
 476 <P>If this field is empty, the Tape Coordinator uses the maximum acceptable
 477 value (2048 GB or 2 TB). Either leave both this field and the
 478 <VAR>filemark_size</VAR> field empty, or provide a value in both of them.
 479 <P><DT><B><VAR>filemark_size</VAR>
 480 </B><DD>Specifies the tape device's filemark size, which usually falls
 481 between 2 KB and 2 MB. Use the same notation as for the
 482 <VAR>capacity</VAR> field, but note that if you omit the units letter, the
 483 default unit is bytes rather than kilobytes.
 484 <P>For a tape device in regular (noncompression) mode, you can use the
 485 <B>fms</B> command to determine filemark size, or use the value reported
 486 by the device's manufacturer. To help the Tape Coordinator avoid
 487 reaching EOT unexpectedly, increase the value by about 10% when recording it
 488 in the <B>tapeconfig</B> file.
 489 <P>The recommended value for a tape device in compression mode is <B>0</B>
 490 (zero). The <B>fms</B> command does not yield accurate results in
 491 compression mode, so you cannot use it to determine the filemark size.
 492 <P>The recommended value for a backup data file is also <B>0</B>
 493 (zero). The Tape Coordinator does not use filemarks when writing to a
 494 file, but a value must appear in this field nevertheless if there is also a
 495 value in the <VAR>capacity</VAR> field.
 496 <P>If this field is empty, the Tape Coordinator uses the value <B>0</B>
 497 (zero). Either leave both this field and the <VAR>capacity</VAR> field
 498 empty, or provide a value in both of them.
 499 <P><DT><B><VAR>device_name</VAR>
 500 </B><DD>Specifies the complete pathname of the tape device or backup data
 501 file. The format of tape device names depends on the operating system,
 502 but on UNIX systems, device names generally begin with the string
 503 <B>/dev/</B>. For a backup data file, this field defines the
 504 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>.
 505 <P><DT><B><VAR>port_offset</VAR>
 506 </B><DD>Specifies the port offset number for a specific tape device or backup data
 507 file. Each tape device listens for backup requests on a different UNIX
 508 port. You pick the port indirectly by recording a value in this
 509 field. The Backup System sets the device's actual port by adding
 510 the port offset to a base port number that it determines internally.
 511 <P>Legal values are the integers <B>0</B> through <B>58510</B> (the
 512 Backup System can track a maximum of 58,511 port offset numbers). Each
 513 value must be unique among the cell's Tape Coordinators, but you do not
 514 have to assign port offset numbers sequentially, and you can associate any
 515 number of them with a single machine or even tape device. For example,
 516 if you plan to use a device in both compression and noncompression mode,
 517 assign it two different port offsets with appropriate tape capacity and
 518 filemark values for the different modes.
 519 <P>Assign port offset <B>0</B> (zero) to the Tape Coordinator for the tape
 520 device or backup data file that you use most often for backup operations;
 521 doing so enables you to omit the <B>-portoffset</B> argument from the
 522 largest possible number of <B>backup</B> commands.
 523 </DL>
 524 <P>The following example <B>tapeconfig</B> file includes entries for two
 525 tape devices, <B>/dev/rmt0h</B> and <B>/dev/rmt1h</B>. Each one
 526 uses tapes with a capacity of 2 GB and has a filemark size of 1 MB.
 527 Their port offset numbers are <TT>0</TT> and <TT>1</TT>.
 528 <PRE>   2g 1m /dev/rmt0h 0
 529    2G 1M /dev/rmt1h 1
 530 </PRE>
 531 <P>The <B>fms</B> command reports the capacity of the tape you have
 532 inserted and the tape device's filemark size, both on the standard output
 533 stream (stdout) and in its <B>fms.log</B> file, which it writes in
 534 the current working directory. The command interpreter must write data
 535 to the entire tape, so running the command can take from several hours to more
 536 than a day, depending on the size of the tape.
 537 <P><H3><A NAME="HDRWQ259" HREF="auagd002.htm#ToC_283">To run the fms command on a noncompressing tape device</A></H3>
 538 <A NAME="IDX6849"></A>
 539 <A NAME="IDX6850"></A>
 540 <A NAME="IDX6851"></A>
 541 <A NAME="IDX6852"></A>
 542 <A NAME="IDX6853"></A>
 543 <OL TYPE=1>
 544 <P><LI>If an <B>fms.log</B> file does not already exist in the current
 545 directory, verify that you can insert and write to files in the current
 546 directory. If the log file already exists, you must be able to write to
 547 the file.
 548 <P><LI>Insert a tape into the drive. Running the command completely
 549 overwrites the tape, so use a blank tape or one that you want to
 550 recycle.
 551 <P><LI>Issue the <B>fms</B> command.
 552 <PRE>   % <B>fms</B> &lt;<VAR>tape&nbsp;special&nbsp;file</VAR>>
 553 </PRE>
 554 <P>where
 555 <DL>
 556 <P><DT><B>fms
 557 </B><DD>Must be typed in full.
 558 <P><DT><B><VAR>tape special file</VAR>
 559 </B><DD>Specifies the tape device's UNIX device name, such as
 560 <B>/dev/rmt0h</B>.
 561 </DL>
 562 </OL>
 563 <P>The following example output reports that the tape in the device with
 564 device name <B>/dev/rmt0h</B> has a capacity of 2136604672 bytes (about 2
 565 GB), and that the device's filemark size is 1910205 bytes (close to 2
 566 MB).
 567 <PRE>   % <B>fms /dev/rmt0h</B>
 568    wrote block: 130408
 569    Finished data capacity test - rewinding
 570    wrote 1109 blocks, 1109 file marks
 571    Finished file mark test
 572    Tape capacity is 2136604672 bytes
 573    File marks are 1910205 bytes
 574 </PRE>
 575 <HR><H2><A NAME="HDRWQ260" HREF="auagd002.htm#ToC_284">Granting Administrative Privilege to Backup Operators</A></H2>
 576 <P>Each person who issues the <B>backup</B> and
 577 <B>butc</B> commands in your cell must be listed in the
 578 <B>/usr/afs/etc/UserList</B> file on every database server machine that
 579 stores the Backup Database and Volume Location Database (VLDB), and every
 580 machine that houses a volume included in a volume set. By convention,
 581 the <B>UserList</B> file is the same on every server machine in the
 582 cell; the instructions in this document assume that your cell is
 583 configured in this way. To edit the <B>UserList</B> file, use the
 584 <B>bos adduser</B> and <B>bos removeuser</B> commands as described in <A HREF="auagd021.htm#HDRWQ592">Administering the UserList File</A>.
 585 <P>In addition to being listed in the <B>UserList</B> file, backup
 586 operators who issue the <B>butc</B> command must be able to write to the
 587 files stored in each Tape Coordinator machine's local
 588 <B>/usr/afs/backup</B> directory, which are protected by UNIX mode
 589 bits. Before configuring your cell's first Tape Coordinator
 590 machine, decide which local user and group to designate as the owner of the
 591 directory and the files in it. Among the possible ownership options are
 592 the following:
 593 <UL>
 594 <P><LI>The local superuser <B>root</B>. With this option, the issuer
 595 of the <B>butc</B> command must log onto the local file system as the
 596 local superuser <B>root</B>. If the Tape Coordinator is also a
 597 server machine, the <B>-localauth</B> flag is used on the <B>butc</B>
 598 command to construct a server ticket from the local
 599 <B>/usr/afs/etc/KeyFile</B> file. On non-server machine, the issuer
 600 must issue the <B>klog</B> command to authenticate as an AFS administrator
 601 while logged in as <B>root</B>.
 602 <P><LI>A single AFS administrator. Logging in and authenticating are a
 603 single step if an AFS-modified login utility is used. The administrator
 604 is the only user who can start the Tape Coordinator.
 605 <P><LI>An administrative account for which several operators know the
 606 password. This allows them all to start the Tape Coordinator.
 607 </UL>
 608 <P>Another option is to define a group in the local group file
 609 (<B>/etc/group</B> or equivalent) to which all backup operators
 610 belong. Then turn on the <B>w</B> mode bit (<B>write</B>
 611 permission) in the group mode bits rather than the user mode bits of the
 612 <B>/usr/afs/backup</B> directory and files in it. An advantage over
 613 the methods listed previously is that each operator can retain an individual
 614 administrative account for finer granularity in auditing.
 615 <P>For instructions on implementing your choice of protection methods, see <A HREF="#HDRWQ261">Configuring Tape Coordinator Machines and Tape Devices</A>.
 616 <HR><H2><A NAME="HDRWQ261" HREF="auagd002.htm#ToC_285">Configuring Tape Coordinator Machines and Tape Devices</A></H2>
 617 <A NAME="IDX6854"></A>
 618 <A NAME="IDX6855"></A>
 619 <A NAME="IDX6856"></A>
 620 <A NAME="IDX6857"></A>
 621 <P>This section explains how to configure a machine as a Tape Coordinator
 622 machine, and how to configure or remove the Tape Coordinator associated with a
 623 single tape device or backup data file.
 624 <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
 625 device's tape block size to <B> 0</B> (zero) to indicate variable
 626 block size. If you do not, it is possible that devices attached to
 627 machines of other system types cannot read the tapes made on the AIX
 628 system. Use the AIX <B>smit</B> program to verify or change the
 629 value of the tape block size for a tape device, as instructed in Sep <A HREF="#LIWQ263">3</A>.
 630 </TD></TR></TABLE>
 631 <P><H3><A NAME="HDRWQ262" HREF="auagd002.htm#ToC_286">To configure a Tape Coordinator machine</A></H3>
 632 <OL TYPE=1>
 633 <P><LI>Verify that you are authenticated as a user listed in the
 634 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
 635 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
 636 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
 637 </PRE>
 638 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
 639 already, by issuing the <B>su</B> command.
 640 <PRE>   % <B>su root</B>
 641    Password: <VAR>root_password</VAR>
 642 </PRE>
 643 <P><LI><A NAME="LIWQ263"></A>Install one or more tape devices on the Tape Coordinator
 644 machine according to the manufacturer's instructions. The Backup
 645 System can track a maximum of 58,511 tape devices or backup data files per
 646 cell.
 647 <P>If the Tape Coordinator machine is an AIX system, issue the following
 648 command to change the tape device's tape block size to <B>0</B>
 649 (zero), which indicates variable block size. Repeat for each tape
 650 device.
 651 <PRE>   # <B>chdev -l '</B><VAR>device_name</VAR><B>' -a block_size='0'</B>
 652 </PRE>
 653 <P>where <VAR>device_name</VAR> is the tape device's device name (for
 654 example, <B>/dev/rmt0h</B>).
 655 <P><LI>Verify that the binary files for the <B>backup</B>, <B>butc</B>,
 656 and <B>fms</B> commands are available on the local disk. If the
 657 machine is an AFS client, the conventional location is the
 658 <B>/usr/afsws/etc</B> directory.
 659 <PRE>   # <B>ls /usr/afsws/etc</B>
 660 </PRE>
 661 <P><LI>Create the <B>/usr/afs</B> directory. (If the Tape Coordinator
 662 machine is also configured as a file server machine, this directory already
 663 exists.) Then create the <B>/usr/afs/backup</B> directory.
 664 <PRE>   # <B>mkdir /usr/afs</B>
 665    # <B>mkdir /usr/afs/backup</B>
 666 </PRE>
 667 <P><LI>Use a text editor to create the <B>/usr/afs/backup/tapeconfig</B>
 668 file. Include a single line for each tape device or backup data file,
 669 specifying the following information in the indicated order. For syntax
 670 details and suggestions on the values to use in each field, see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>.
 671 <UL>
 672 <P><LI>The capacity of tapes to be used in the device, or the size of the backup
 673 data file
 674 <P><LI>The device's filemark size
 675 <P><LI>The device's device name, starting with the string <B>/dev/</B>
 676 <P><LI>The device's port offset number
 677 </UL>
 678 <A NAME="IDX6858"></A>
 679 <A NAME="IDX6859"></A>
 680 <A NAME="IDX6860"></A>
 681 <A NAME="IDX6861"></A>
 682 <P><LI>Decide which user and group are to own the <B>/usr/afs/backup</B>
 683 directory and <B>/usr/afs/backup/tapeconfig</B> file, based on the
 684 suggestions in <A HREF="#HDRWQ260">Granting Administrative Privilege to Backup Operators</A>. Correct the UNIX mode bits on the directory and
 685 file, if necessary.
 686 <PRE>   # <B>chown</B> <VAR>admin_owner</VAR> <B>/usr/afs/backup</B>
 687    # <B>chown</B> <VAR>admin_owner</VAR> <B>/usr/afs/backup/tapeconfig</B>
 688    # <B>chgrp</B> <VAR>admin_group</VAR> <B>/usr/afs/backup</B>
 689    # <B>chgrp</B> <VAR>admin_group</VAR> <B>/usr/afs/backup/tapeconfig</B>
 690    # <B>chmod 774 /usr/afs/backup</B>
 691    # <B>chmod 664 /usr/afs/backup/tapeconfig</B>
 692 </PRE>
 693 <A NAME="IDX6862"></A>
 694 <A NAME="IDX6863"></A>
 695 <A NAME="IDX6864"></A>
 696 <A NAME="IDX6865"></A>
 697 <P><LI><A NAME="LICONFTC-ADDHOST"></A>Issue the <B>backup addhost</B> command to create
 698 a Tape Coordinator entry in the Backup Database. Repeat the command for
 699 each Tape Coordinator.
 700 <PRE>   # <B>backup addhost</B> &lt;<VAR>tape&nbsp;machine&nbsp;name</VAR>> [&lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]
 701 </PRE>
 702 <P>where
 703 <DL>
 704 <P><DT><B>addh
 705 </B><DD>Is the shortest acceptable abbreviation of <B>addhost</B>.
 706 <P><DT><B><VAR>tape machine name</VAR>
 707 </B><DD>Specifies the Tape Coordinator machine's fully qualified
 708 hostname.
 709 <P><DT><B><VAR>TC port offset</VAR>
 710 </B><DD>Specifies the tape device's port offset number. Provide the
 711 same value as you specified for the device in the <B>tapeconfig</B>
 712 file. You must provide this argument unless the default value of 0
 713 (zero) is appropriate.
 714 </DL>
 715 </OL>
 716 <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>
 717 <OL TYPE=1>
 718 <P><LI>Verify that you are authenticated as a user listed in the
 719 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
 720 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
 721 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
 722 </PRE>
 723 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
 724 already, by issuing the <B>su</B> command.
 725 <PRE>   % <B>su root</B>
 726    Password: <VAR>root_password</VAR>
 727 </PRE>
 728 <P><LI>Install the tape device on the Tape Coordinator machine according to the
 729 manufacturer's instructions.
 730 <P>If the Tape Coordinator machine is an AIX system, issue the following
 731 command to change the tape device's tape block size to <B>0</B>
 732 (zero), which indicates variable block size.
 733 <PRE>   # <B>chdev -l '</B><VAR>device_name</VAR><B>' -a block_size='0'</B>
 734 </PRE>
 735 <P><LI>Choose the port offset number to assign to the tape device. If
 736 necessary, use the <B>backup listhosts</B> command to display the port
 737 offset numbers that are already used; for a discussion of the output, see
 738 <A HREF="#HDRWQ264">To display the list of configured Tape Coordinators</A>.
 739 <PRE>   # <B>backup listhosts</B>
 740 </PRE>
 741 <P>where <B>listh</B> is the shortest acceptable abbreviation of
 742 <B>listhosts</B>.
 743 <P><LI>Use a text editor to add one or more entries for the device to the
 744 <B>/usr/afs/backup/tapeconfig</B> file. Specify the following
 745 information in the indicated order. For syntax details and suggestions
 746 on the values to use in each field, see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>.
 747 <UL>
 748 <P><LI>The capacity of tapes to be used in the device, or the size of the backup
 749 data file
 750 <P><LI>The device's filemark size
 751 <P><LI>The device's device name, starting with the string <B>/dev/</B>
 752 <P><LI>The device's port offset number
 753 </UL>
 754 <P><LI>Issue the <B>backup addhost</B> command to create an entry in the
 755 Backup Database for the Tape Coordinator. For complete syntax, see Step
 756 <A HREF="#LICONFTC-ADDHOST">8</A> in <A HREF="#HDRWQ262">To configure a Tape Coordinator machine</A>.
 757 <PRE>   # <B>backup addhost</B> &lt;<VAR>tape&nbsp;machine&nbsp;name</VAR>> [&lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]
 758 </PRE>
 759 </OL>
 760 <A NAME="IDX6866"></A>
 761 <A NAME="IDX6867"></A>
 762 <A NAME="IDX6868"></A>
 763 <A NAME="IDX6869"></A>
 764 <P><H3><A NAME="Header_288" HREF="auagd002.htm#ToC_288">To unconfigure a Tape Coordinator</A></H3>
 765 <OL TYPE=1>
 766 <P><LI>Verify that you are authenticated as a user listed in the
 767 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
 768 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
 769 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
 770 </PRE>
 771 <P><LI>Using a text editor, remove each of the Tape Coordinator's entries
 772 from the <B>/usr/afs/backup/tapeconfig</B> file.
 773 <P><LI>Issue the <B>backup delhost</B> command to delete the Tape
 774 Coordinator's Backup Database entry.
 775 <PRE>   % <B>backup delhost</B> &lt;<VAR>tape&nbsp;machine&nbsp;name</VAR>> [&lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]
 776 </PRE>
 777 <P>where
 778 <DL>
 779 <P><DT><B>delh
 780 </B><DD>Is the shortest acceptable abbreviation of <B>delhost</B>.
 781 <P><DT><B><VAR>tape machine name</VAR>
 782 </B><DD>Is the complete Internet host name of the Tape Coordinator machine.
 783 <P><DT><B><VAR>TC port offset</VAR>
 784 </B><DD>Is the same port offset number removed from the <B>tapeconfig</B>
 785 file. You must provide this argument unless the default value of
 786 <B>0</B> (zero) is appropriate.
 787 </DL>
 788 </OL>
 789 <A NAME="IDX6870"></A>
 790 <A NAME="IDX6871"></A>
 791 <A NAME="IDX6872"></A>
 792 <A NAME="IDX6873"></A>
 793 <P><H3><A NAME="HDRWQ264" HREF="auagd002.htm#ToC_289">To display the list of configured Tape Coordinators</A></H3>
 794 <OL TYPE=1>
 795 <P><LI>Issue the <B>backup listhosts</B> command to list the Tape
 796 Coordinators and port offset numbers currently configured in the Backup
 797 Database.
 798 <PRE>   % <B>backup listhosts</B>
 799 </PRE>
 800 <P>where
 801 <DL>
 802 <P><DT><B>listh
 803 </B><DD>Is the shortest acceptable abbreviation of <B>listhosts</B>.
 804 </DL>
 805 </OL>
 806 <P>The output lists each Tape Coordinator machine and the port offset numbers
 807 currently allocated to it in the Backup Database. The appearance of a
 808 port offset number does not imply that the associated Tape Coordinator is
 809 actually running. Machine names appear in the format in which they were
 810 specified with the <B>backup addhost</B> command.
 811 <P>The following example output lists the Tape Coordinators currently defined
 812 in the Backup Database of the ABC Corporation cell:
 813 <PRE>   % <B>backup listhosts</B>
 814    Tape hosts:
 815        Host backup1.abc.com, port offset 0
 816        Host backup1.abc.com, port offset 2
 817        Host backup2.abc.com, port offset 1
 818        Host backup2.abc.com, port offset 3
 819 </PRE>
 820 <HR><H2><A NAME="HDRWQ265" HREF="auagd002.htm#ToC_290">Defining and Displaying Volume Sets and Volume Entries</A></H2>
 821 <P>The Backup System handles data at the level of volumes
 822 rather than individual files. You must define groups of volumes called
 823 <I>volume sets</I> before performing backup operations, by using the
 824 <B>backup addvolset</B> command. A volume set name can be up to 31
 825 characters long and can include any character other than the period
 826 (<B>.</B>), but avoid using metacharacters that have special
 827 meanings to the shell.
 828 <P>After creating a volume set, use the <B>backup addvolentry</B> command
 829 to place one or more <I>volume entries</I> in it. They define the
 830 volumes that belong to it in terms of their location (file server machine and
 831 partition) and name. Use the command's required <B>-server</B>
 832 argument to designate the file server machine that houses the volumes of
 833 interest and its required <B>-partition</B> argument to designate the
 834 partition. Two types of values are acceptable:
 835 <UL>
 836 <P><LI>The fully qualified hostname of one machine or full name of one partition
 837 (such as <B>/vicepm</B>)
 838 <P><LI>The regular expression <B>.*</B> (period and asterisk), which
 839 matches every machine name or partition name in the VLDB
 840 </UL>
 841 <P>For the volume name (the required <B>-volume</B> argument), specify a
 842 combination of alphanumeric characters and one or more metacharacters to
 843 specify part or all of the volume name with a wildcard. You can use any
 844 of the following metacharacters in the volume name field:
 845 <A NAME="IDX6874"></A>
 846 <A NAME="IDX6875"></A>
 847 <DL>
 848 <P><DT><B>.
 849 </B><DD>The period matches any single character.
 850 <P><DT><B>*
 851 </B><DD>The asterisk matches zero or more instances of the preceding
 852 character. Combine it with any other alphanumeric character or
 853 metacharacter.
 854 <P><DT><B>[ ]
 855 </B><DD>Square brackets around a list of characters match a single instance of any
 856 of the characters, but no other characters; for example, <B>[abc]</B>
 857 matches a single <B>a</B> or <B>b</B> or <B>c</B>, but not
 858 <B>d</B> or <B>A</B>. You can combine this expression with the
 859 asterisk.
 860 <P><DT><B>^
 861 </B><DD>The caret, when used as the first character in a square-bracketed set,
 862 designates a match with any single character other than the characters that
 863 follow it; for example, <B>[^a]</B> matches any single character
 864 except lowercase <B>a</B>. You can combine this expression with the
 865 asterisk.
 866 <P><DT><B>\
 867 </B><DD>A backslash preceding any of the metacharacters in this list makes it
 868 match its literal value only. For example, the expression
 869 <B>\.</B> (backslash and period) matches a single period,
 870 <B>\*</B> matches a single asterisk, and <B>\\</B> matches a single
 871 backslash. You can combine such expressions with the asterisk (for
 872 example, <B>\.*</B> matches any number of periods).
 873 </DL>
 874 <P>Perhaps the most common regular expression is the period followed by an
 875 asterisk (<B>.*</B>). This expression matches any string of
 876 any length, because the period matches any character and the asterisk means
 877 any number of that character. As mentioned, it is the only acceptable
 878 regular expression in the file server and partition fields of a volume
 879 entry. In the volume name field, it can stand alone (in which case it
 880 matches every volume listed in the VLDB), or can combine with alphanumeric
 881 characters. For example, the string
 882 <B>user.*\.backup</B> matches any volume name that begins
 883 with the string <B>user</B> and ends with
 884 <B>.backup</B>.
 885 <P>Issuing the <B>backup addvolentry</B> command in interactive mode is
 886 simplest. If you issue it at the shell prompt, you must surround any
 887 string that includes a regular expression with double quotes (<B>" "</B>)
 888 so that the shell passes them uninterpreted to the <B>backup</B> command
 889 interpreter rather than resolving them.
 890 <P>To define various combinations of volumes, provide the following types of
 891 values for the <B>backup addvolentry</B> command's three
 892 arguments. The list uses the notation appropriate for interactive
 893 mode; if you issue the command at the shell prompt instead, place double
 894 quotes around any string that includes a regular expression. To create
 895 a volume entry that includes:
 896 <UL>
 897 <P><LI>All volumes listed in the VLDB, use the regular expression
 898 <B>.*</B> for all three arguments (<B>-server .*
 899 -partition .* -volume .*</B>)
 900 <P><LI>Every volume on a specific file server machine, specify its fully
 901 qualified hostname as the <B>-server</B> argument and use the regular
 902 expression <B>.*</B> for the <B>-partition</B> and
 903 -<B>volume</B> arguments (for example: <B>-server
 904 fs1.abc.com -partition .* -volume .*</B>)
 905 <P><LI>All volumes that reside on a partition with the same name on various file
 906 server machines, specify the complete partition name as the
 907 <B>-partition</B> argument and use the regular expression
 908 <B>.*</B> for the <B>-server</B> and <B>-volume</B>
 909 arguments (for example: <B>-server .* -partition /vicepd
 910 -volume .*</B>)
 911 <P><LI>Every volume with a common string in its name, use the regular expression
 912 <B>.*</B> for the <B>-server</B> and <B>-partition</B>
 913 arguments, and provide a combination of alphanumeric characters and
 914 metacharacters as the <B>-volume</B> argument (for example:
 915 <B>-server .* -partition .* -volume
 916 .*\.backup</B> includes all volumes whose names end in the
 917 string <B>.backup</B>).
 918 <P><LI>All volumes on one partition, specify the machine's fully qualified
 919 hostname as the <B>-server</B> argument and the full partition name as the
 920 <B>-partition</B> argument, and use the regular expression
 921 <B>.*</B> for the <B>-volume</B> argument (for example:
 922 <B>-server fs2.abc.com -partition /vicepb -volume
 923 .*</B>).
 924 <P><LI>A single volume, specify its complete name as the <B>-volume</B>
 925 argument. To bypass the potentially time-consuming search through the
 926 VLDB for matching entries, you can specify an actual machine and partition
 927 name for the <B>-server</B> and <B>-partition</B> arguments
 928 respectively. However, if it is possible that you need to move the
 929 volume in future, it is best to use the regular expression
 930 <B>.*</B> for the machine and partition name.
 931 </UL>
 932 <P>As you create volume sets, define groups of volumes you want to dump to the
 933 same tape at the same time (for example, weekly or daily) and in the same
 934 manner (fully or incrementally). In general, a volume set that includes
 935 volumes with similar contents (as indicated by similar names) is more useful
 936 than one that includes volumes that share a common location, especially if you
 937 often move volumes for load-balancing or space reasons. Most often,
 938 then, it is appropriate to use the regular expression <B>.*</B>
 939 (period followed by a backslash) for the <B>-server</B> and
 940 <B>-partition</B> arguments to the <B>backup addvolentry</B>
 941 command.
 942 <P>It is generally more efficient to include a limited number of volumes in a
 943 volume entry. Dumps of a volume set that includes a large number of
 944 volume can take a long time to complete, increasing the possibility that the
 945 operation fails due to a service interruption or outage.
 946 <P>To remove a volume entry from a volume set, use the <B>backup
 947 delvolentry</B> command. To remove a volume set and all of its
 948 component volume entries from the Backup Database, use the <B>backup
 949 delvolset</B> command. To display the volume entries in a volume set,
 950 use the <B>backup listvolsets</B> command.
 951 <P>By default, a Backup Database record is created for the new volume
 952 set. Sometimes it is convenient to create volume sets without recording
 953 them permanently in the Backup Database, for example when using the
 954 <B>backup volsetrestore</B> command to restore a group of volumes that
 955 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,
 956 include the <B>-temporary</B> flag to the <B>backup addvolset</B>
 957 command. A temporary volume set exists only during the lifetime of the
 958 current interactive session, so the flag is effective only when used during an
 959 interactive session (opened by issuing the <B>backup (interactive)</B>
 960 command). You can use the <B>backup delvolset</B> command to delete
 961 a temporary volume set before the interactive session ends, if you wish, but
 962 as noted it is automatically deleted when you end the session. One
 963 advantage of temporary volume sets is that the <B>backup addvolset</B>
 964 command, and any <B>backup addvolentry</B> commands subsequently used to
 965 add volume entries to it, complete more quickly than for regular volume sets,
 966 because you are not creating any Backup Database records.
 967 <A NAME="IDX6876"></A>
 968 <A NAME="IDX6877"></A>
 969 <A NAME="IDX6878"></A>
 970 <A NAME="IDX6879"></A>
 971 <P><H3><A NAME="Header_291" HREF="auagd002.htm#ToC_291">To create a volume set</A></H3>
 972 <OL TYPE=1>
 973 <P><LI>Verify that you are authenticated as a user listed in the
 974 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
 975 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
 976 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
 977 </PRE>
 978 <P><LI><B>(Optional)</B> Issue the <B>backup</B> command to enter
 979 interactive mode. If you are going to define volume entries right away
 980 with the <B>backup addvolentry</B> command, this eliminates the need to
 981 surround metacharacter expressions with double quotes. You must enter
 982 interactive mode if creating a temporary volume set.
 983 <PRE>   % <B>backup</B>
 984 </PRE>
 985 <P><LI>Issue the <B>(backup) addvolset</B> command to create the volume
 986 set. You must then issue the <B>(backup) addvolentry</B> command to
 987 define volume entries in it.
 988 <PRE>   backup>  <B>addvolset</B> &lt;<VAR>volume&nbsp;set&nbsp;name</VAR>> [<B>-temporary</B>]
 989 </PRE>
 990 <P>where
 991 <DL>
 992 <P><DT><B>addvols
 993 </B><DD>Is the shortest acceptable abbreviation of <B>addvolset</B>.
 994 <P><DT><B><VAR>volume set name</VAR>
 995 </B><DD>Names the volume set. The name can include no more than 31
 996 characters, cannot include periods, and must be unique within the Backup
 997 Database. (A temporary volume set can have the same name as an existing
 998 permanent volume set, but this is not recommended because of the confusion it
 999 can cause.)
1000 <P><DT><B>-temporary
1001 </B><DD>Creates a temporary volume set, which exists only during the current
1002 interactive session.
1003 </DL>
1004 </OL>
1005 <A NAME="IDX6880"></A>
1006 <A NAME="IDX6881"></A>
1007 <A NAME="IDX6882"></A>
1008 <A NAME="IDX6883"></A>
1009 <P><H3><A NAME="Header_292" HREF="auagd002.htm#ToC_292">To add a volume entry to a volume set</A></H3>
1010 <OL TYPE=1>
1011 <P><LI>Verify that you are authenticated as a user listed in the
1012 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
1013 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1014 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1015 </PRE>
1016 <P><LI><B>(Optional)</B> Issue the <B>backup</B> command to enter
1017 interactive mode if you have not already. This makes it simpler to use
1018 metacharacter expressions, because you do not need to surround them with
1019 double quotes. If you are adding entries to a temporary volume set, you
1020 must already have entered interactive mode before creating the volume
1021 set.
1022 <PRE>   % <B>backup</B>
1023 </PRE>
1024 <P><LI>Issue the <B>(backup) addvolentry</B> command to define volume entries
1025 in an existing volume set. The Backup System assigns each volume entry
1026 an index within the volume set, starting with 1 (one).
1027 <PRE>   backup> <B>addvolentry  -name</B> &lt;<VAR>volume&nbsp;set&nbsp;name</VAR>>  \
1028                         <B>-server</B> &lt;<VAR>machine&nbsp;name</VAR>>  \
1029                         <B>-partition</B> &lt;<VAR>partition&nbsp;name</VAR>>  \
1030                         <B>-volumes</B> &lt;<VAR>volume&nbsp;name&nbsp;(regular&nbsp;expression)</VAR>>
1031 </PRE>
1032 <P>where
1033 <DL>
1034 <P><DT><B>addvole
1035 </B><DD>Is the shortest acceptable abbreviation of <B>addvolentry</B>.
1036 <P><DT><B>-name
1037 </B><DD>Names the volume set to which to add the volume entry. It must
1038 already exist (use the <B>backup addvolset</B> command to create
1039 it).
1040 <P><DT><B>-server
1041 </B><DD>Defines the set of one or more file server machines that house the volumes
1042 in the volume entry. Provide either one fully-qualified hostname (such
1043 as <B>fs1.abc.com</B>) or the metacharacter expression
1044 <B>.*</B> (period and asterisk), which matches all machine names in
1045 the VLDB.
1046 <P><DT><B>-partition
1047 </B><DD>Defines the set of one or more partitions that house the volumes in the
1048 volume entry. Provide either one complete partition name (such as
1049 <B>/vicepa</B>) or the metacharacter expression <B>.*</B>
1050 (period and asterisk), which matches all partition names.
1051 <P><DT><B>-volumes
1052 </B><DD>Defines the set of one or more volumes included in the volume entry,
1053 identifying them by name. This argument can include a combination of
1054 alphanumeric characters and one or more of the metacharacter expressions
1055 discussed in the introductory material in this section.
1056 </DL>
1057 </OL>
1058 <A NAME="IDX6884"></A>
1059 <A NAME="IDX6885"></A>
1060 <A NAME="IDX6886"></A>
1061 <A NAME="IDX6887"></A>
1062 <A NAME="IDX6888"></A>
1063 <A NAME="IDX6889"></A>
1064 <P><H3><A NAME="HDRWQ266" HREF="auagd002.htm#ToC_293">To display volume sets and volume entries</A></H3>
1065 <OL TYPE=1>
1066 <P><LI>Issue the <B>backup listvolsets</B> command to display the volume
1067 entries in a specific volume set or all of them. If you are displaying
1068 a temporary volume set, you must still be in the interactive session in which
1069 you created it.
1070 <PRE>   % <B>backup listvolsets</B> [&lt;<VAR>volume&nbsp;set&nbsp;name</VAR>>]
1071 </PRE>
1072 <P>where
1073 <DL>
1074 <P><DT><B>listv
1075 </B><DD>Is the shortest acceptable abbreviation of <B>listvolsets</B>.
1076 <P><DT><B><VAR>volume set name</VAR>
1077 </B><DD>Names the volume set to display. Omit this argument to display all
1078 defined volume sets.
1079 </DL>
1080 <P>The output from the command uses the wildcard notation used when the volume
1081 entries were created. The string <TT>(temporary)</TT> marks a
1082 temporary volume set. The following example displays all three of the
1083 volume sets defined in a cell's Backup Database, plus a temporary volume
1084 set <B>pat+jones</B> created during the current interactive session:
1085 <P>
1086 <PRE>   backup> <B>listv</B>
1087    Volume set pat+jones (temporary):
1088      Entry 1: server fs1.abc.com, partition /vicepe, volumes: user.pat.backup
1089      Entry 2: server fs5.abc.com, partition /viceph, volumes: user.jones.backup
1090    Volume set user:
1091      Entry 1: server .*, partition .*, volumes: user.*\.backup
1092    Volume set sun:
1093      Entry 1: server .*, partition .*, volumes: sun4x_55\..*
1094      Entry 2: server .*, partition .*, volumes: sun4x_56\..*
1095    Volume set rs:
1096      Entry 1: server .*, partition .*, volumes: rs_aix42\..*
1097 </PRE>
1098 </OL>
1099 <A NAME="IDX6890"></A>
1100 <A NAME="IDX6891"></A>
1101 <A NAME="IDX6892"></A>
1102 <A NAME="IDX6893"></A>
1103 <P><H3><A NAME="Header_294" HREF="auagd002.htm#ToC_294">To delete a volume set</A></H3>
1104 <OL TYPE=1>
1105 <P><LI>Verify that you are authenticated as a user listed in the
1106 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
1107 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1108 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1109 </PRE>
1110 <P><LI>Issue the <B>backup delvolset</B> command to delete one or more volume
1111 sets and all of the component volume entries in them. If you are
1112 deleting a temporary volume set, you must still be in the interactive session
1113 in which you created it.
1114 <PRE>   % <B>backup delvolset</B> &lt;<VAR>volume&nbsp;set&nbsp;name</VAR>><SUP>+</SUP>
1115 </PRE>
1116 <P>where
1117 <DL>
1118 <P><DT><B>delvols
1119 </B><DD>Is the shortest acceptable abbreviation of <B>delvolset</B>.
1120 <P><DT><B><VAR>volume set name</VAR>
1121 </B><DD>Names each volume set to delete.
1122 </DL>
1123 </OL>
1124 <A NAME="IDX6894"></A>
1125 <A NAME="IDX6895"></A>
1126 <A NAME="IDX6896"></A>
1127 <A NAME="IDX6897"></A>
1128 <A NAME="IDX6898"></A>
1129 <P><H3><A NAME="Header_295" HREF="auagd002.htm#ToC_295">To delete a volume entry from a volume set</A></H3>
1130 <OL TYPE=1>
1131 <P><LI>Verify that you are authenticated as a user listed in the
1132 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
1133 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1134 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1135 </PRE>
1136 <P><LI>Issue the <B>backup</B> command to enter interactive mode.
1137 <PRE>   % <B>backup</B>
1138 </PRE>
1139 <P><LI>If the volume set includes more than one volume entry, issue the
1140 <B>(backup) listvolsets</B> command to display the index number associated
1141 with each one (if there is only one volume entry, its index is 1). For
1142 a more detailed description of the command's output, see <A HREF="#HDRWQ266">To display volume sets and volume entries</A>.
1143 <PRE>   backup> <B>listvolsets</B> &lt;<VAR>volume&nbsp;set&nbsp;name</VAR>>
1144 </PRE>
1145 <P>where
1146 <DL>
1147 <P><DT><B>listv
1148 </B><DD>Is the shortest acceptable abbreviation of <B>listvolsets</B>.
1149 <P><DT><B><VAR>volume set name</VAR>
1150 </B><DD>Names the volume set for which to display volume entries.
1151 </DL>
1152 <P><LI>Issue the <B>(backup) delvolentry</B> command to delete the volume
1153 entry.
1154 <PRE>   backup> <B>delvolentry</B> &lt;<VAR>volume&nbsp;set&nbsp;name</VAR>>  &lt;<VAR>volume&nbsp;entry&nbsp;index</VAR>>
1155 </PRE>
1156 <P>where
1157 <DL>
1158 <P><DT><B>delvole
1159 </B><DD>Is the shortest acceptable abbreviation of <B>delvolentry</B>.
1160 <P><DT><B><VAR>volume set name</VAR>
1161 </B><DD>Names the volume set from which to delete a volume entry.
1162 <P><DT><B><VAR>volume entry index</VAR>
1163 </B><DD>Specifies the index number of the volume entry to delete.
1164 </DL>
1165 </OL>
1166 <HR><H2><A NAME="HDRWQ267" HREF="auagd002.htm#ToC_296">Defining and Displaying the Dump Hierarchy</A></H2>
1167 <A NAME="IDX6899"></A>
1168 <A NAME="IDX6900"></A>
1169 <P>A dump hierarchy is a logical structure in the Backup Database that defines
1170 the relationship between full and incremental dumps; that is, it defines
1171 which dump serves as the parent for an incremental dump. Each
1172 individual component of a hierarchy is a dump level.
1173 <P>As you define dump levels with the <B>backup adddump</B> command, keep
1174 the following rules and suggestions in mind:
1175 <UL>
1176 <P><LI>Each full dump level is the top level of a hierarchy. You can
1177 create as many hierarchies as you need to dump different volume sets on
1178 different schedules.
1179 <P><LI>The name of a full dump level consists of an initial slash (<B>/</B>),
1180 followed by a string of up to 28 alphanumeric characters.
1181 <P><LI>The name of an incremental dump level resembles a pathname, starting with
1182 the name of a full dump level, then the first incremental level, and so on,
1183 down to the final incremental level. Precede each level name with a
1184 slash to separate it from the preceding level. Like the full level,
1185 each component level in the name can have up to 28 alphanumeric characters,
1186 not including the slash.
1187 <P><LI>A hierarchy can have any have any number of levels, but the maximum length
1188 of a complete dump level name is 256 characters, including the slashes.
1189 <P><LI>Before defining a given incremental level, you must define all of the
1190 levels above it in the hierarchy.
1191 <P><LI>Do not use the period (<B>.</B>) in dump level names.
1192 The Backup System uses the period as the separator between a dump's
1193 volume set name and dump level name when it creates the dump name and AFS tape
1194 name. Any other alphanumeric and punctuation characters are allowed,
1195 but it is best to avoid metacharacters. If you include a metacharacter,
1196 you must precede it with a backslash (<B>\</B>) or surround the entire
1197 dump level name with double quotes (<B>" "</B>).
1198 <P><LI>Naming dump levels for days or other actual time points reminds you when
1199 to perform dumps, and makes it easier to track the relationship between dumps
1200 performed at different levels. However, the names have no meaning to
1201 the Backup System: it does not automatically create dumps according to
1202 the names, and does not prevent you from, for example, using the
1203 <B>/sunday</B> level when creating a dump on a Tuesday.
1204 <P><LI>It is best not to use the same name for more than one component level in a
1205 hierarchy, because it means the resulting dump name no longer indicates which
1206 level was used. For example, if you name a dump level
1207 <B>/full/incr/incr</B>, then the dump name and AFS tape name that result
1208 from dumping a volume set at the first incremental level
1209 (<B>/full/incr</B>) look the same as the names that result from dumping at
1210 the second incremental level (<B>/full/incr/incr</B>).
1211 <P><LI>Individual levels in different hierarchies can have the same name, but the
1212 complete pathnames must be unique. For example,
1213 <B>/sunday1/monday</B> and <B>/sunday2/monday</B> share the same name
1214 at the final level, but are unique because they have different names at the
1215 full level (belong to different hierarchies). However, using the same
1216 name in multiple hierarchies means that dump and AFS tape names do not
1217 unambiguously indicate which hierarchy was used.
1218 </UL>
1219 <P>The following example shows three hierarchies. Each begins with a
1220 full dump at the top: <B>sunday1</B> for the first hierarchy,
1221 <B>sunday2</B> for the second hierarchy, and <B>sunday_bin</B> for the
1222 third hierarchy. In all three hierarchies, each of the other dump
1223 levels is an incremental level.
1224 <PRE>   /sunday1
1225            /monday
1226            /tuesday
1227            /wednesday
1228            /thursday
1229            /friday
1230    /sunday2
1231            /monday
1232                   /tuesday
1233                           /wednesday
1234                                     /thursday
1235                                              /friday
1236     /sunday_bin
1237                /monday
1238                       /wednesday
1239                                 /friday
1240 </PRE>
1241 <P>In the first hierarchy, each incremental dump level refers to the full
1242 level <B>/sunday1</B> as its parent. When (for example) you dump a
1243 volume set at the <B>/sunday1/wednesday</B> level, it includes data that
1244 has changed since the volume set was dumped at the <B>/sunday1</B>
1245 level.
1246 <P>In contrast, each incremental dump level in the second hierarchy refers to
1247 the immediately preceding dump level as its parent. When you dump a
1248 volume set at the corresponding level in the second hierarchy
1249 (<B>/sunday2/monday/tuesday/wednesday</B>), the dump includes only data
1250 that has changed since the volume set was dumped at the
1251 <B>/sunday2/monday/tuesday</B> level (presumably the day before).
1252 Assuming you create dumps on the indicated days, an incremental dump made
1253 using this hierarchy contains less data than an incremental dump made at the
1254 corresponding level in the first hierarchy.
1255 <P>The third hierarchy is more appropriate for dumping volumes for which a
1256 daily backup is excessive because the data does not change often (for example,
1257 system binaries).
1258 <P><H3><A NAME="HDRWQ268" HREF="auagd002.htm#ToC_297">Creating a Tape Recycling Schedule</A></H3>
1259 <A NAME="IDX6901"></A>
1260 <A NAME="IDX6902"></A>
1261 <A NAME="IDX6903"></A>
1262 <A NAME="IDX6904"></A>
1263 <A NAME="IDX6905"></A>
1264 <A NAME="IDX6906"></A>
1265 <A NAME="IDX6907"></A>
1266 <A NAME="IDX6908"></A>
1267 <P>If your cell is like most cells, you have a limited amount of room for
1268 storing backup tapes and a limited budget for new tapes. The easiest
1269 solution is to recycle tapes by overwriting them when you no longer need the
1270 backup data on them. The Backup System helps you implement a recycling
1271 schedule by enabling you to associate an expiration date with each dump
1272 level. The expiration date defines when a dump created at that level
1273 expires. Until that time the Backup System refuses to overwrite a tape
1274 that contains the dump. Thus, assigning expiration dates automatically
1275 determines how you recycle tapes.
1276 <P>When designing a tape-recycling schedule, you must decide how far in the
1277 past and to what level of precision you want to guarantee access to backed up
1278 data. For instance, if you decide to guarantee that you can restore a
1279 user's home volume to its state on any given day in the last two weeks,
1280 you cannot recycle the tape that contains a given daily dump for at least two
1281 weeks after you create it. Similarly, if you decide to guarantee that
1282 you can restore home volumes to their state at the beginning of any given week
1283 in the last month, you cannot recycle the tapes in a dump set containing a
1284 weekly dump for at least four weeks. The following example dump
1285 hierarchy implements this recycling schedule by setting the expiration date
1286 for each daily incremental dump to 13 days and the expiration date of the
1287 weekly full dumps to 27 days.
1288 <P>The tapes used to store dumps created at the daily incremental levels in
1289 the <B>/sunday1</B> hierarchy expire just in time to be recycled for daily
1290 dumps in the <B>/sunday3</B> hierarchy (and vice versa), and there is a
1291 similar relationship between the <B>/sunday2</B> and <B>/sunday4</B>
1292 hierarchies. Similarly, the tape that houses a full dump at the
1293 <B>/sunday1</B> level expires just in time to be used for a full dump on
1294 the first Sunday of the following month.
1295 <PRE>
1296    /sunday1   expires in 27d
1297            /monday1  expires in 13d
1298            /tuesday1  expires in 13d
1299            /wednesday1  expires in 13d
1300            /thursday1  expires in 13d
1301            /friday1  expires in 13d
1302    /sunday2   expires in 27d
1303            /monday2  expires in 13d
1304            /tuesday2  expires in 13d
1305            /wednesday2  expires in 13d
1306            /thursday2  expires in 13d
1307            /friday2  expires in 13d
1308    /sunday3   expires in 27d
1309            /monday1  expires in 13d
1310            /tuesday1  expires in 13d
1311            /wednesday1  expires in 13d
1312            /thursday1  expires in 13d
1313            /friday1  expires in 13d
1314    /sunday4   expires in 27d
1315            /monday2  expires in 13d
1316            /tuesday2  expires in 13d
1317            /wednesday2  expires in 13d
1318            /thursday2  expires in 13d
1319            /friday2  expires in 13d
1320 </PRE>
1321 <P>If you use appended dumps in your cell, keep in mind that all dumps in a
1322 dump set are subject to the latest (furthest into the future) expiration date
1323 associated with any of the constituent dumps. You cannot recycle any of
1324 the tapes that contain a dump set until all of the dumps have reached their
1325 expiration date. See also <A HREF="auagd012.htm#HDRWQ299">Appending Dumps to an Existing Dump Set</A>.
1326 <P>Most tape manufacturers recommend that you write to a tape a limited number
1327 of times, and it is best not to exceed this limit when recycling tapes.
1328 To help you track tape usage, the Backup System records a <TT>useCount</TT>
1329 counter on the tape's label. It increments the counter each time
1330 the tape's label is rewritten (each time you use the <B>backup
1331 labeltape</B> or <B>backup dump</B> command). To display the
1332 <TT>useCount</TT> counter, use the <B>backup readlabel</B> or
1333 <B>backup scantape</B> command or include the <B>-id</B> and
1334 <B>-verbose</B> options when you issue the <B>backup dumpinfo</B>
1335 command. For instructions see <A HREF="#HDRWQ272">Writing and Reading Tape Labels</A> or <A HREF="auagd012.htm#HDRWQ302">Displaying Backup Dump Records</A>.
1336 <A NAME="IDX6909"></A>
1337 <A NAME="IDX6910"></A>
1338 <A NAME="IDX6911"></A>
1339 <A NAME="IDX6912"></A>
1340 <P><H3><A NAME="HDRWQ269" HREF="auagd002.htm#ToC_298">Archiving Tapes</A></H3>
1341 <A NAME="IDX6913"></A>
1342 <A NAME="IDX6914"></A>
1343 <P>Even if you make extensive use of tape recycling, there is probably some
1344 backup data that you need to archive for a long (or even an indefinite) period
1345 of time. You can use the Backup System to archive data on a regular
1346 schedule, and you can also choose to archive data on tapes that you previously
1347 expected to recycle.
1348 <P>If you want to archive data on a regular basis, you can create
1349 date-specific dump levels in the dump hierarchy. For example, if you
1350 decide to archive a full dump of all data in your cell at the beginning of
1351 each quarter in the year 2000, you can define the following levels in the dump
1352 hierarchy:
1353 <PRE>   /1Q2000
1354    /2Q2000
1355    /3Q2000
1356    /4Q2000
1357 </PRE>
1358 <P>If you decide to archive data that is on tapes you previously planned to
1359 recycle, you must gather all of the tapes that contain the relevant dumps,
1360 both full and incremental. To avoid accidental erasure, it is best to
1361 set the switch on the tapes that makes them read-only, before placing them in
1362 your archive storage area. If the tapes also contain a large amount of
1363 extraneous data that you do not want to archive, you can restore just the
1364 relevant data into a new temporary volume, and back up that volume to the
1365 smallest number of tapes possible. One reason to keep a dump set small
1366 is to minimize the amount of irrelevant data in a dump set you end up needing
1367 to archive.
1368 <P>If you do not expect to restore archived data to the file system, you can
1369 consider using the <B>backup deletedump</B> command to remove the
1370 associated dump records from the Backup Database, which helps keep it to an
1371 efficient size. If you ever need to restore the data, you can use the
1372 <B>-dbadd</B> flag to the <B>backup scantape</B> command to reinsert
1373 the dump records into the database. For instructions, see <A HREF="auagd012.htm#HDRWQ305">To scan the contents of a tape</A>.
1374 <P><H3><A NAME="HDRWQ270" HREF="auagd002.htm#ToC_299">Defining Expiration Dates</A></H3>
1375 <P>To associate an expiration date with a dump level as you
1376 create it, use the <B>-expires</B> argument to the <B>backup
1377 adddump</B> command. To change an existing dump level's
1378 expiration date, use the <B>-expires</B> argument to the <B>backup
1379 setexp</B> command. (Note that it is not possible to change the
1380 expiration date of an actual dump that has already been created at that
1381 level). With both commands, you can define an expiration date either in
1382 absolute terms (for example, 13 January 2000) or relative terms (for example,
1383 30 days from when the dump is created).
1384 <UL>
1385 <P><LI>To define an absolute expiration date, provide a value for the
1386 <B>-expires</B> argument with the following format:
1387 <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>]
1388 </PRE>
1389 <P>where <VAR>mm</VAR> indicates the month, <VAR>dd</VAR> the day, and
1390 <VAR>yyyy</VAR> the year when the dump expires. Valid values for the year
1391 fall in the range <B>1970</B> through <B>2037</B> (the latest possible
1392 date that the UNIX time representation can express is in early 2038).
1393 If you provide a time, it must be in 24-hour format with <VAR>hh</VAR> the hours
1394 and <VAR>MM</VAR> the minutes (for example, <B>21:50</B> is 9:50
1395 p.m.). If you omit the time, the default is 00:00
1396 hours (12:00 midnight) on the indicated date.
1397 <P><LI>To define a relative expiration date, provide a value for the
1398 <B>-expires</B> argument with the following format:
1399 <PRE>   [<B>in</B>] [<VAR>years</VAR><B>y</B>] [<VAR>months</VAR><B>m</B>] [<VAR>days</VAR><B>d</B>]
1400 </PRE>
1401 <P>where each of <VAR>years</VAR>, <VAR>months</VAR>, and <VAR>days</VAR> is an
1402 integer. Provide at least one of them together with the corresponding
1403 units letter (<B>y</B>, <B>m</B>, or <B>d</B> respectively), with
1404 no intervening space. If you provide more than one of the three, list
1405 them in the indicated order.
1406 <P>The Backup System calculates a dump's actual expiration date by adding
1407 the indicated relative value to the start time of the dump operation.
1408 For example, it assigns an expiration date 1 year, 6 months, and 2 days in the
1409 future to a dump created at a dump level with associated expiration date
1410 <B>in 1y 6m 2d</B>.
1411 <P><LI>To indicate that a dump backed up at the corresponding dump level never
1412 expires, provide the value <B>NEVER</B> instead of a date and time.
1413 To recycle tapes that contain dumps created at such a level, you must use the
1414 <B>backup readlabel</B> command to overwrite the tape's label.
1415 </UL>
1416 <P>If you omit the <B>-expires</B> argument to the <B>backup
1417 adddump</B> command, then the expiration date is set to UNIX time zero
1418 (00:00 hours on 1 January 1970). The Backup System considers
1419 dumps created at such a dump level to expire at their creation time. If
1420 no dumps in a dump set have an expiration date, then the Backup System does
1421 not impose any restriction on recycling the tapes that contain the dump
1422 set. If you need to prevent premature recycling of the tapes that
1423 contain the dump set, you must use a manual tracking system.
1424 <A NAME="IDX6915"></A>
1425 <A NAME="IDX6916"></A>
1426 <A NAME="IDX6917"></A>
1427 <A NAME="IDX6918"></A>
1428 <A NAME="IDX6919"></A>
1429 <A NAME="IDX6920"></A>
1430 <A NAME="IDX6921"></A>
1431 <A NAME="IDX6922"></A>
1432 <A NAME="IDX6923"></A>
1433 <P><H3><A NAME="Header_300" HREF="auagd002.htm#ToC_300">To add a dump level to the dump hierarchy</A></H3>
1434 <OL TYPE=1>
1435 <P><LI>Verify that you are authenticated as a user listed in the
1436 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
1437 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1438 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1439 </PRE>
1440 <P><LI><B>Optional</B>. Issue the <B>backup</B> command to enter
1441 interactive mode.
1442 <PRE>   % <B>backup</B>
1443 </PRE>
1444 <P><LI>Issue the <B>backup adddump</B> command to define one or more dump
1445 levels. If you are defining an incremental level, then all of the
1446 parent levels that precede it in its pathname must either already exist or
1447 precede it on the command line.
1448 <PRE>   backup> <B>adddump -dump</B> &lt;<VAR>dump&nbsp;level&nbsp;name</VAR>><SUP>+</SUP> [<B>-expires</B> &lt;<VAR>expiration&nbsp;date</VAR>><SUP>+</SUP>]
1449 </PRE>
1450 <P>where
1451 <DL>
1452 <P><DT><B>addd
1453 </B><DD>Is the shortest acceptable abbreviation of <B>adddump</B>.
1454 <P><DT><B>-dump
1455 </B><DD>Names each dump level to added. If you specify more than one dump
1456 level name, you must include the <B>-dump</B> switch.
1457 <P>Provide the entire pathname of the dump level, preceding each level in the
1458 pathname with a slash (<B>/</B>). Each component level can be up to
1459 28 characters in length, and the pathname can include up to 256 characters
1460 including the slashes.
1461 <P><DT><B>-expires
1462 </B><DD>Sets the expiration date associated with each dump level. Specify
1463 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
1464 dump levels.
1465 <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
1466 because it accepts a multiword value which does not need to be enclosed in
1467 double quotes or other delimiters, not because it accepts multiple
1468 dates. Provide only one date (and optionally, time) definition to be
1469 associated with each dump level specified by the <B>-dump</B>
1470 argument.
1471 </TD></TR></TABLE>
1472 </DL>
1473 </OL>
1474 <A NAME="IDX6924"></A>
1475 <A NAME="IDX6925"></A>
1476 <A NAME="IDX6926"></A>
1477 <A NAME="IDX6927"></A>
1478 <A NAME="IDX6928"></A>
1479 <A NAME="IDX6929"></A>
1480 <P><H3><A NAME="Header_301" HREF="auagd002.htm#ToC_301">To change a dump level's expiration date</A></H3>
1481 <OL TYPE=1>
1482 <P><LI>Verify that you are authenticated as a user listed in the
1483 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
1484 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1485 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1486 </PRE>
1487 <P><LI><B>Optional</B>. Issue the <B>backup</B> command to enter
1488 interactive mode.
1489 <PRE>   % <B>backup</B>
1490 </PRE>
1491 <P><LI>Issue the <B>(backup) setexp</B> command to change the expiration date
1492 associated with one or more dump levels.
1493 <PRE>   backup> <B>setexp -dump</B> &lt;<VAR>dump&nbsp;level&nbsp;name</VAR>><SUP>+</SUP> [<B>-expires</B> &lt;<VAR>expiration&nbsp;date</VAR>><SUP>+</SUP>]
1494 </PRE>
1495 <P>where
1496 <DL>
1497 <P><DT><B>se
1498 </B><DD>Is the shortest acceptable abbreviation of <B>setexp</B>.
1499 <P><DT><B>-dump
1500 </B><DD>Names each existing dump level for which to change the expiration
1501 date.
1502 <P><DT><B>-expires
1503 </B><DD>Sets the expiration date associated with each dump level. Specify
1504 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
1505 currently associated with each dump level.
1506 <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
1507 because it accepts a multiword value which does not need to be enclosed in
1508 double quotes or other delimiters, not because it accepts multiple
1509 dates. Provide only one date (and optionally, time) definition to be
1510 associated with each dump level specified by the <B>-dump</B>
1511 argument.
1512 </TD></TR></TABLE>
1513 </DL>
1514 </OL>
1515 <A NAME="IDX6930"></A>
1516 <A NAME="IDX6931"></A>
1517 <A NAME="IDX6932"></A>
1518 <A NAME="IDX6933"></A>
1519 <A NAME="IDX6934"></A>
1520 <P><H3><A NAME="Header_302" HREF="auagd002.htm#ToC_302">To delete a dump level from the dump hierarchy</A></H3>
1521 <OL TYPE=1>
1522 <P><LI>Verify that you are authenticated as a user listed in the
1523 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
1524 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1525 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1526 </PRE>
1527 <P><LI><B>Optional</B>. Issue the <B>backup</B> command to enter
1528 interactive mode.
1529 <PRE>   % <B>backup</B>
1530 </PRE>
1531 <P><LI>Issue the <B>(backup) deldump</B> command to delete the dump
1532 level. Note that the command automatically removes all incremental dump
1533 levels for which the specified level serves as parent, either directly or
1534 indirectly.
1535 <PRE>   backup> <B>deldump</B> &lt;<VAR>dump&nbsp;level&nbsp;name</VAR>>
1536 </PRE>
1537 <P>where
1538 <DL>
1539 <P><DT><B>deld
1540 </B><DD>Is the shortest acceptable abbreviation of <B>deldump</B>.
1541 <P><DT><B><VAR>dump level name</VAR>
1542 </B><DD>Specifies the complete pathname of the dump level to delete.
1543 </DL>
1544 </OL>
1545 <A NAME="IDX6935"></A>
1546 <A NAME="IDX6936"></A>
1547 <A NAME="IDX6937"></A>
1548 <A NAME="IDX6938"></A>
1549 <A NAME="IDX6939"></A>
1550 <A NAME="IDX6940"></A>
1551 <P><H3><A NAME="HDRWQ271" HREF="auagd002.htm#ToC_303">To display the dump hierarchy</A></H3>
1552 <OL TYPE=1>
1553 <P><LI>Issue the <B>backup listdumps</B> command to display the dump
1554 hierarchy.
1555 <PRE>   % <B>backup listdumps</B>
1556 </PRE>
1557 <P>where <B>listd</B> is the shortest acceptable abbreviation of
1558 <B>listdumps</B>.
1559 <P>The output from this command displays the dump hierarchy, reporting the
1560 expiration date associated with each dump level, as in the following
1561 example.
1562 <PRE>    % <B>backup listdumps</B>
1563    /week1  expires in  27d
1564          /tuesday  expires in  13d
1565                  /thursday  expires in  13d
1566          /sunday  expires in  13d
1567                 /tuesday expires in  13d
1568                         /thursday expires in  13d
1569    /week3  expires in  27d
1570          /tuesday  expires in  13d
1571                  /thursday  expires in  13d
1572          /sunday  expires in  13d
1573                 /tuesday  expires in  13d
1574                         /thursday  expires in  13d
1575    sunday1   expires in  27d
1576           /monday1  expires in  13d
1577           /tuesday1  expires in  13d
1578           /wednesday1  expires in  13d
1579           /thursday1  expires in  13d
1580           /friday1  expires in  13d
1581    sunday2   expires in  27d
1582           /monday2  expires in  13d
1583           /tuesday2  expires in  13d
1584           /wednesday2  expires in  13d
1585           /thursday2  expires in  13d
1586           /friday2  expires in  13d
1587    sunday3   expires in  27d
1588           /monday1  expires in  13d
1589           /tuesday1  expires in  13d
1590           /wednesday1  expires in  13d
1591           /thursday1  expires in  13d
1592           /friday1  expires in  13d
1593    sunday4   expires in  27d
1594           /monday2  expires in  13d
1595           /tuesday2  expires in  13d
1596           /wednesday2  expires in  13d
1597           /thursday2  expires in  13d
1598           /friday2  expires in  13d
1599 </PRE>
1600 </OL>
1601 <HR><H2><A NAME="HDRWQ272" HREF="auagd002.htm#ToC_304">Writing and Reading Tape Labels</A></H2>
1602 <A NAME="IDX6941"></A>
1603 <A NAME="IDX6942"></A>
1604 <A NAME="IDX6943"></A>
1605 <A NAME="IDX6944"></A>
1606 <A NAME="IDX6945"></A>
1607 <A NAME="IDX6946"></A>
1608 <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
1609 an AFS tape name to a tape that you use in the Backup System. The names
1610 are recorded on the tape's magnetic label, along with an indication of
1611 the tape's capacity (size).
1612 <P>You can assign either a permanent name or an AFS tape name, but not
1613 both. In general, assigning permanent names rather than AFS tape names
1614 simplifies the backup process, because the Backup System does not dictate the
1615 format of permanent names. If a tape does not have a permanent name,
1616 then by default the Backup System accepts only three strictly defined values
1617 in the AFS tape name field, and refuses to write a dump to a tape with an
1618 inappropriate AFS tape name. The acceptable values are a name that
1619 matches the volume set and dump level of the initial dump, the value
1620 <TT>&lt;NULL></TT>, and no value in the field at all.
1621 <P>If a tape has a permanent name, the Backup System does not check the AFS
1622 tape name, and as part of the dump operation constructs the appropriate AFS
1623 tape name itself and records it on the label. This means that if you
1624 assign a permanent name, the Backup System assigns an AFS tape name itself and
1625 the tape has both types of name. In contrast, if a tape has an AFS tape
1626 name but not a permanent name, you cannot assign a permanent name without
1627 first erasing the AFS tape name.
1628 <P>(You can also suppress the Backup System's check of a tape's AFS
1629 tape name, even it does not have a permanent name, by assigning the value
1630 <B>NO</B> to the <B>NAME_CHECK</B> instruction in the device
1631 configuration file. See <A HREF="#HDRWQ280">Eliminating the AFS Tape Name Check</A>.)
1632 <P>Because the Backup System accepts unlabeled tapes, you do not have to label
1633 a tape before using it for the first time. After the first use, there
1634 are a couple of cases in which you must relabel a tape in order to write a
1635 dump to it:
1636 <UL>
1637 <P><LI>The tape does not have a permanent name, and the AFS tape name on it does
1638 not match the new initial dump set you want to create (the volume set and dump
1639 level names are different, or the index is incorrect).
1640 <P><LI>You want to recycle a tape before all of the dumps on it have
1641 expired. The Backup System does not overwrite a tape with any unexpired
1642 dumps. Keep in mind, though, that if you relabel the tape to making
1643 recycling possible, you erase all the dump records for the tape from the
1644 Backup Database, which makes it impossible to restore any data from the
1645 tape.
1646 </UL>
1647 <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
1648 in a restore operation, because the labeling operation removes the dump's
1649 records from the Backup Database. If you want to record a permanent
1650 name on a tape label, you must do it before dumping any data to the
1651 tape.
1652 </TD></TR></TABLE>
1653 <P><H3><A NAME="Header_305" HREF="auagd002.htm#ToC_305">Recording a Name on the Label</A></H3>
1654 <P>To write a permanent name on a tape's label, include the
1655 <B>-pname</B> argument to specify a string of up to 32 characters.
1656 Check that no other tape used with the Backup System in your cell already has
1657 the permanent name you are assigning, because the Backup System does not
1658 prevent you from assigning the same name to multiple tapes. The Backup
1659 System overwrites the existing AFS tape name, if any, with the value
1660 <TT>&lt;NULL></TT>. When a tape has a permanent name, the Backup
1661 System uses it instead of the AFS tape name in most prompts and when referring
1662 to the tape in output from <B>backup</B> commands. The permanent
1663 name persists until you again include the <B>-pname</B> argument to the
1664 <B>backup labeltape</B> command, regardless of the tape's contents
1665 and of how often you recycle the tape or use the <B>backup labeltape</B>
1666 command without the <B>-pname</B> argument.
1667 <P>To write an AFS tape name on the label, provide a value for the
1668 <B>-name</B> argument that matches the volume set name and the final
1669 element in the dump level pathname of the initial dump that you plan to write
1670 to the tape, and an index that indicates the tape's place in the sequence
1671 of tapes for the dump set. The format is as follows:
1672 <PRE>   <VAR>volume_set_name</VAR><B>.</B><VAR>dump_level_name</VAR><B>.</B><VAR>tape_index</VAR>
1673 </PRE>
1674 <P>If you omit the <B>-name</B> argument, the Backup System sets the AFS
1675 tape name to <TT>&lt;NULL></TT>. The Backup System automatically
1676 constructs and records the appropriate name when you later write an initial
1677 dump to the tape by using the <B>backup dump</B> or <B>backup
1678 savedb</B> command.
1679 <P>You cannot use the <B>-name</B> argument if the tape already has a
1680 permanent name. To erase a tape's permanent name, provide a null
1681 value to the <B>-pname</B> argument by issuing the following
1682 command:
1683 <PRE>   % <B>backup labeltape -pname ""</B>
1684 </PRE>
1685 <P><H3><A NAME="Header_306" HREF="auagd002.htm#ToC_306">Recording a Capacity on the Label</A></H3>
1686 <P>To record the tape's capacity on the label, specify a number of
1687 kilobytes as the <B>-size</B> argument. If you omit this argument
1688 the first time you label a tape, the Backup System records the default tape
1689 capacity associated with the specified port offset in the
1690 <B>/usr/afs/backup/tapeconfig</B> file on the Tape Coordinator
1691 machine. If the tape's capacity is different (in particular,
1692 larger) than the capacity recorded in the <B>tapeconfig</B> file, it is
1693 best to record a capacity on the label before using the tape. Once set,
1694 the value in the label's capacity field persists until you again use the
1695 <B>-size</B> argument to the <B>backup labeltape</B> command.
1696 For a discussion of the appropriate capacity to record for tapes, see <A HREF="#HDRWQ258">Configuring the tapeconfig File</A>.
1697 <P>To read a tape's label, use the <B>backup readlabel</B>
1698 command.
1699 <P>Most tapes also come with an adhesive label you can apply to the exterior
1700 casing. To help you easily identify a tape, record at least the
1701 tape's permanent and AFS tape names on the adhesive label.
1702 Depending on the recycling scheme you use, it can be useful to record other
1703 information, such as the dump ID, dump creation date, and expiration date of
1704 each dump you write to the tape.
1705 <A NAME="IDX6947"></A>
1706 <A NAME="IDX6948"></A>
1707 <P><H3><A NAME="HDRWQ273" HREF="auagd002.htm#ToC_307">To label a tape</A></H3>
1708 <OL TYPE=1>
1709 <P><LI>Verify that you are authenticated as a user listed in the
1710 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
1711 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1712 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1713 </PRE>
1714 <P><LI>If the Tape Coordinator for the tape device that is to perform the
1715 operation is not already running, open a connection to the appropriate Tape
1716 Coordinator machine and issue the <B>butc</B> command, for which complete
1717 instructions appear in <A HREF="auagd012.htm#HDRWQ292">To start a Tape Coordinator process</A>.
1718 <PRE>   % <B>butc</B> [&lt;<VAR>port offset</VAR>>] [<B>-noautoquery</B>]
1719 </PRE>
1720 <P><LI>Place the tape in the device.
1721 <P><LI><B>Optional</B>. Issue the <B>backup</B> command to enter
1722 interactive mode, if you want to label multiple tapes or issue additional
1723 commands after labeling the tape. The interactive prompt appears in the
1724 following step.
1725 <PRE>   % <B>backup</B>
1726 </PRE>
1727 <P><LI>Issue the <B>(backup) labeltape</B> command to label the tape.
1728 <PRE>   backup> <B>labeltape</B> [<B>-name</B> &lt;<VAR>tape&nbsp;name,&nbsp;defaults&nbsp;to&nbsp;NULL</VAR>>]  \
1729       [<B>-size</B> &lt;<VAR>tape&nbsp;size&nbsp;in&nbsp;Kbytes,&nbsp;defaults&nbsp;to&nbsp;size&nbsp;in&nbsp;tapeconfig</VAR>>]  \
1730       [<B>-portoffset</B> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>] [<B>-pname</B> &lt;<VAR>permanent&nbsp;tape&nbsp;name</VAR>>]
1731 </PRE>
1732 <P>where
1733 <DL>
1734 <P><DT><B>la
1735 </B><DD>Is the shortest acceptable abbreviation of <B>labeltape</B>.
1736 <P><DT><B>-name
1737 </B><DD>Specifies the AFS tape name to record on the label. Include this
1738 argument or the <B>-pname</B> argument, but not both. If you omit
1739 this argument, the AFS tape name is set to <TT>&lt;NULL></TT>. If you
1740 provide it, it must have the following format.
1741 <PRE><VAR>volume_set_name</VAR><B>.</B><VAR>dump_level_name</VAR><B>.</B><VAR>tape_index</VAR>
1742 </PRE>
1743 <P>
1744 <P>for the tape to be acceptable for use in a future <B>backup dump</B>
1745 operation. The <VAR>volume_set_name</VAR> must match the volume set name
1746 of the initial dump to be written to the tape, <VAR>dump_level_name</VAR> must
1747 match the last element of the dump level pathname at which the volume set is
1748 to be dumped, and <VAR>tape_index</VAR> must correctly indicate the tape's
1749 place in the sequence of tapes that house the dump set; indexing begins
1750 with the number 1 (one).
1751 <P><DT><B>-size
1752 </B><DD>Specifies the tape capacity to record on the label. If you are
1753 labeling the tape for the first time, you need to include this argument only
1754 if the tape's capacity differs from the capacity associated with the
1755 specified port offset in the <B>/usr/afs/backup/tapeconfig</B> file on the
1756 Tape Coordinator machine.
1757 <P>If you provide a value, it is an integer value followed by a letter that
1758 indicates units, with no intervening space. A unit value of
1759 <B>k</B> or <B>K</B> indicates kilobytes, <B>m</B> or <B>M</B>
1760 indicates megabytes, and <B>g</B> or <B>G</B> indicates
1761 gigabytes. If you omit the units letter, the default is
1762 kilobytes.
1763 <P><DT><B>-portoffset
1764 </B><DD>Specifies the port offset number of the Tape Coordinator handling the tape
1765 or backup data file for this operation. You must provide this argument
1766 unless the default value of <B>0</B> (zero) is appropriate.
1767 <P><DT><B>-pname
1768 </B><DD>Specifies the permanent name to record on the label. It can be up
1769 to 32 characters in length, and include any alphanumeric characters.
1770 Avoid metacharacters that have a special meaning to the shell, to avoid having
1771 to mark them as literal in commands issued at the shell prompt.
1772 <P>Include this argument or the <B>-name</B> argument, but not
1773 both. When you provide this argument, the AFS tape name is set to
1774 <TT>&lt;NULL></TT>. If you omit this argument, any existing permanent
1775 name is retained.
1776 </DL>
1777 <P><LI>If you did not include the <B>-noautoquery</B> flag when you issued
1778 the <B>butc</B> command, or if the device's device configuration file
1779 includes the instruction <B>AUTOQUERY YES</B>, then the Tape Coordinator
1780 prompts you to place the tape in the device's drive. You have
1781 already done so, but you must now press <B>&lt;Return></B> to indicate
1782 that the tape is ready for labeling.
1783 </OL>
1784 <A NAME="IDX6949"></A>
1785 <A NAME="IDX6950"></A>
1786 <P><H3><A NAME="HDRWQ274" HREF="auagd002.htm#ToC_308">To read the label on a tape</A></H3>
1787 <OL TYPE=1>
1788 <P><LI>Verify that you are authenticated as a user listed in the
1789 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
1790 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1791 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1792 </PRE>
1793 <P><LI>If the Tape Coordinator for the tape device that is to perform the
1794 operation is not already running, open a connection to the appropriate Tape
1795 Coordinator machine and issue the <B>butc</B> command, for which complete
1796 instructions appear in <A HREF="auagd012.htm#HDRWQ292">To start a Tape Coordinator process</A>.
1797 <PRE>   % <B>butc</B> [&lt;<VAR>port offset</VAR>>] [<B>-noautoquery</B>]
1798 </PRE>
1799 <P><LI>Place the tape in the device.
1800 <P><LI><B>Optional</B>. Issue the <B>backup</B> command to enter
1801 interactive mode, if you want to label multiple tapes or issue additional
1802 commands after labeling the tape. The interactive prompt appears in the
1803 following step.
1804 <PRE>   % <B>backup</B>
1805 </PRE>
1806 <P><LI>Issue the <B>(backup) readlabel</B> command to read the label on the
1807 tape.
1808 <PRE>   backup> <B>readlabel</B> [&lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]
1809 </PRE>
1810 <P>where
1811 <DL>
1812 <P><DT><B>rea
1813 </B><DD>Is the shortest acceptable abbreviation of <B>readlabel</B>.
1814 <P><DT><B><VAR>TC port offset</VAR>
1815 </B><DD>Specifies the port offset number of Tape Coordinator handling the tape or
1816 backup data file for this operation. You must provide this argument
1817 unless the default value of <B>0</B> (zero) is appropriate.
1818 </DL>
1819 <P><LI>If you did not include the <B>-noautoquery</B> flag when you issued
1820 the <B>butc</B> command, or the device's device configuration file
1821 includes the instruction <B>AUTOQUERY YES</B> instruction, then the Tape
1822 Coordinator prompts you to place the tape in the device's drive.
1823 You have already done so, but you must now press <B>&lt;Return></B> to
1824 indicate that the tape is ready for reading.
1825 </OL>
1826 <P>Information from the tape label appears both in the <B>backup</B>
1827 command window and in the Tape Coordinator window. The output in the
1828 command window has the following format:
1829 <PRE>   Tape read was labelled: <VAR>tape_name</VAR> (<VAR>initial_dump_ID</VAR>)
1830         size: <VAR>size</VAR> KBytes
1831 </PRE>
1832 <P>where <VAR>tape_name</VAR> is the tape's permanent name (if it has one)
1833 or AFS tape name, <VAR>initial_dump_ID</VAR> is the dump ID of the initial dump
1834 on the tape, and <VAR>size</VAR> is the capacity recorded on the label, in
1835 kilobytes.
1836 <P>The information in the Tape Coordinator window is more extensive.
1837 The tape's permanent name appears in the <TT>tape name</TT> field and
1838 its AFS tape name in the <TT>AFS tape name</TT> field. If either name
1839 is undefined, a value of <TT>&lt;NULL></TT> appears in the field
1840 instead. The capacity recorded on the label appears in the
1841 <TT>size</TT> field. Other fields in the output report the creation
1842 time, dump level name, and dump ID of the initial dump on the tape
1843 (<TT>creationTime</TT>, <TT>dump path</TT>, and <TT>dump id</TT>
1844 respectively). The <TT>cell</TT> field reports the cell in which the
1845 dump operation was performed, and the <TT>useCount</TT> field reports the
1846 number of times the tape has been relabeled, either with the <B>backup
1847 labeltape</B> command or during a dump operation. For further
1848 details, see the command's reference page in the <I>IBM AFS
1849 Administration Reference</I>.
1850 <P>If the tape has no label, or if the drive is empty, the following message
1851 appears at the command shell:
1852 <PRE>   Failed to read tape label.
1853 </PRE>
1854 <P>The following example illustrates the output in the command shell for a
1855 tape in the device with port offset 1:
1856 <PRE>   % <B>backup readlabel 1</B>
1857    Tape read was labelled: monthly_guest (917860000)
1858         size: 2150000 KBytes
1859 </PRE>
1860 <P>The following output appears in the Tape Coordinator window at the same
1861 time:
1862 <PRE>   Tape label
1863    ----------
1864    tape name = monthly_guest
1865    AFS tape name = guests.monthly.3
1866    creationTime =  Mon Feb  1 04:06:40 1999
1867    cell = abc.com
1868    size = 2150000 Kbytes
1869    dump path = /monthly
1870    dump id = 917860000
1871    useCount = 44
1872    -- End of tape label --
1873 </PRE>
1874 <HR><H2><A NAME="HDRWQ275" HREF="auagd002.htm#ToC_309">Automating and Increasing the Efficiency of the Backup Process</A></H2>
1875 <A NAME="IDX6951"></A>
1876 <A NAME="IDX6952"></A>
1877 <P>The Backup System includes several optional features to help you automate
1878 the backup process in your cell and make it more efficient. By
1879 combining several of the features, you can dump volume data to tape with
1880 minimal human intervention in most cases. To take advantage of many of
1881 the features, you create a <I>device configuration file</I> in the
1882 <B>/usr/afs/backup</B> directory for each tape device that participates in
1883 automated operations. For general instructions on creating the device
1884 configuration file, see <A HREF="#HDRWQ276">Creating a Device Configuration File</A>. The following list refers you to sections that
1885 describe each feature in greater detail.
1886 <UL>
1887 <P><LI>You can use tape stackers and jukeboxes to perform backup
1888 operations. These are tape drives with an attached unit that stores
1889 several tapes and can physically insert and remove them from the tape reader
1890 (tape drive) without human intervention, meaning that no operator has to be
1891 present even for backup operations that require several tapes. To use a
1892 stacker or jukebox with the Backup System, include the <B>MOUNT</B> and
1893 <B>UNMOUNT</B> instructions in its device configuration file. See <A HREF="#HDRWQ277">Invoking a Device's Tape Mounting and Unmounting Routines</A>.
1894 <P><LI>You can suppress the Tape Coordinator's default prompt for the
1895 initial tape that it needs for a backup operation, again eliminating the need
1896 for a human operator to be present when a backup operation begins. (You
1897 must still insert the correct tape in the drive at some point before the
1898 operation begins.) To suppress the initial prompt, include the
1899 <B>-noautoquery</B> flag on the <B>butc</B> command, or assign the
1900 value <B>NO</B> to the <B>AUTOQUERY</B> instruction in the device
1901 configuration file. See <A HREF="#HDRWQ278">Eliminating the Search or Prompt for the Initial Tape</A>.
1902 <P><LI>You can suppress the prompts that the Tape Coordinator otherwise generates
1903 when it encounters several types of errors. When you use this feature,
1904 the Tape Coordinator instead responds to the errors in a default manner, which
1905 generally allows the operation to continue without human intervention.
1906 To suppress prompts about error conditions, assign the value <B>NO</B> to
1907 the <B>ASK</B> instruction in the device configuration file. See <A HREF="#HDRWQ279">Enabling Default Responses to Error Conditions</A>.
1908 <P><LI>You can suppress the Backup System's default verification that the
1909 AFS tape name on a tape that has no permanent name matches the name derived
1910 from the volume set and dump level names of the initial dump the Backup System
1911 is writing to the tape. This enables you to recycle a tape without
1912 first relabeling it, as long as all dumps on it are expired. To
1913 suppress name checking, assign the value <B>NO</B> to the
1914 <B>NAME_CHECK</B> instruction in the device configuration file. See
1915 <A HREF="#HDRWQ280">Eliminating the AFS Tape Name Check</A>.
1916 <P><LI>You can promote tape streaming (the most efficient way for a tape device
1917 to operate) by setting the size of the memory buffer the Tape Coordinator uses
1918 when transferring volume data between the file system and the device.
1919 To set the buffer size, include the <B>BUFFERSIZE</B> instruction in the
1920 device configuration file. See <A HREF="#HDRWQ281">Setting the Memory Buffer Size to Promote Tape Streaming</A>.
1921 <P><LI>You can write dumps to a <I>backup data file</I> on the local disk of
1922 the Tape Coordinator machine, rather than to tape. You can then
1923 transfer the backup data file to a data-archiving system, such as a
1924 hierarchical storage management (HSM) system, that you use in conjunction with
1925 AFS and the Backup System. Writing a dump to a file is usually more
1926 efficient that issuing the equivalent <B>vos dump</B> commands
1927 individually. To write dumps to a file, include the <B>FILE</B>
1928 instruction in the device configuration file. See <A HREF="#HDRWQ282">Dumping Data to a Backup Data File</A>.
1929 </UL>
1930 <P>There are two additional ways to increase backup automation and efficiency
1931 that do not involve the device configuration file:
1932 <UL>
1933 <P><LI>You can schedule one or more <B>backup dump</B> commands to run at
1934 specified times. This enables you to create backups at times of low
1935 system usage, without requiring a human operator to be present. You can
1936 schedule a single dump operation for a future time, or multiple operations to
1937 run at various future times. See <A HREF="auagd012.htm#HDRWQ300">Scheduling Dumps</A>.
1938 <P><LI>You can append dumps to a tape that already has other dumps on it.
1939 This enables you to use as much of a tape's capacity as possible.
1940 The appended dumps do not have be related in any way to one another or to the
1941 initial dump on the tape, but grouping dumps appropriately can reduce the
1942 number of necessary tape changes during a restore operation. To append
1943 a dump, include the <B>-append</B> argument to the <B>backup dump</B>
1944 command. See <A HREF="auagd012.htm#HDRWQ299">Appending Dumps to an Existing Dump Set</A>.
1945 </UL>
1946 <P><H3><A NAME="HDRWQ276" HREF="auagd002.htm#ToC_310">Creating a Device Configuration File</A></H3>
1947 <A NAME="IDX6953"></A>
1948 <A NAME="IDX6954"></A>
1949 <A NAME="IDX6955"></A>
1950 <A NAME="IDX6956"></A>
1951 <P>To use many of the features that automate backup operations, create a
1952 configuration file for each tape device in the <B>/usr/afs/backup</B>
1953 directory on the local disk of the Tape Coordinator machine that drives the
1954 device. The filename has the following form:
1955 <P><B>CFG_</B><VAR>device_name</VAR>
1956 <P>where <VAR>device_name</VAR> represents the name of the tape device or backup
1957 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
1958 tape).
1959 <P>For a tape device, construct the <VAR>device_name</VAR> portion of the name
1960 by stripping off the initial <B>/dev/</B> string with which all UNIX
1961 device names conventionally begin, and replacing any other slashes in the name
1962 with underscores. For example, <B>CFG_rmt_4m</B> is the appropriate
1963 filename for a device called <B>/dev/rmt/4m</B>.
1964 <P>For a backup data file, construct the <VAR>device_name</VAR> portion by
1965 stripping off the initial slash (<B>/</B>) and replacing any other slashes
1966 (<B>/</B>) in the name with underscores. For example,
1967 <B>CFG_var_tmp_FILE</B> is the appropriate filename for a backup data file
1968 called <B>/var/tmp/FILE</B>.
1969 <P>Creating a device configuration file is optional. If you do not want
1970 to take advantage of any of the features that the file provides, you do not
1971 have to create it.
1972 <P>You can include one of each of the following instructions in any order in a
1973 device configuration file. All are optional. Place each
1974 instruction on its own line, but do not include any newline
1975 (<B>&lt;Return></B>) characters within an instruction.
1976 <DL>
1977 <P><DT><B>MOUNT and UNMOUNT
1978 </B><DD>Identify a script of routines for mounting and unmounting tapes in a tape
1979 stacker or jukebox's drive as needed. See <A HREF="#HDRWQ277">Invoking a Device's Tape Mounting and Unmounting Routines</A>.
1980 <P><DT><B>AUTOQUERY
1981 </B><DD>Controls whether the Tape Coordinator prompts for the first tape it needs
1982 for a backup operation. See <A HREF="#HDRWQ278">Eliminating the Search or Prompt for the Initial Tape</A>.
1983 <P><DT><B>ASK
1984 </B><DD>Controls whether the Tape Coordinator asks you how to respond to certain
1985 error conditions. See <A HREF="#HDRWQ279">Enabling Default Responses to Error Conditions</A>.
1986 <P><DT><B>NAME_CHECK
1987 </B><DD>Controls whether the Tape Coordinator verifies that an AFS tape name
1988 matches the initial dump you are writing to the tape. See <A HREF="#HDRWQ280">Eliminating the AFS Tape Name Check</A>.
1989 <P><DT><B>BUFFERSIZE
1990 </B><DD>Sets the size of the memory buffer the Tape Coordinator uses when
1991 transferring data between a tape device and a volume. See <A HREF="#HDRWQ281">Setting the Memory Buffer Size to Promote Tape Streaming</A>.
1992 <P><DT><B>FILE
1993 </B><DD>Controls whether the Tape Coordinator writes dumps to, and restores data
1994 from, a tape device or a backup data file. See <A HREF="#HDRWQ282">Dumping Data to a Backup Data File</A>.
1995 </DL>
1996 <A NAME="IDX6957"></A>
1997 <A NAME="IDX6958"></A>
1998 <A NAME="IDX6959"></A>
1999 <A NAME="IDX6960"></A>
2000 <A NAME="IDX6961"></A>
2001 <A NAME="IDX6962"></A>
2002 <P><H3><A NAME="HDRWQ277" HREF="auagd002.htm#ToC_311">Invoking a Device's Tape Mounting and Unmounting Routines</A></H3>
2003 <P>A tape stacker or jukebox helps you automate backup
2004 operations because it can switch between multiple tapes during an operation
2005 without human intervention. To take advantage of this feature, include
2006 the <B>MOUNT</B> and optionally <B>UNMOUNT</B> instructions in the
2007 device configuration file that you write for the stacker or jukebox.
2008 The instructions share the same syntax:
2009 <PRE>   <B>MOUNT</B> <VAR>filename</VAR>
2010    <B>UNMOUNT</B> <VAR>filename</VAR>
2011 </PRE>
2012 <P>where <VAR>filename</VAR> is the pathname on the local disk of a script or
2013 program you have written that invokes the routines defined by the
2014 device's manufacturer for mounting or unmounting a tape in the
2015 device's tape drive. (For convenience, the following discussion
2016 uses the term <I>script</I> to refers to both scripts and
2017 programs.) The script usually also contains additional logic that
2018 handles error conditions or modifies the script's behavior depending on
2019 which backup operation is being performed.
2020 <P>You can refer to different scripts with the <B>MOUNT</B> or
2021 <B>UNMOUNT</B> instructions, or to a single script that invokes both
2022 mounting and unmounting routines. The scripts inherit the local
2023 identity and AFS tokens associated with to the issuer of the <B>butc</B>
2024 command.
2025 <P>You need to include a <B>MOUNT</B> instruction in the device
2026 configuration file for all tape devices, but the need for an
2027 <B>UNMOUNT</B> instruction depends on the tape-handling routines that the
2028 device's manufacturer provides. Some devices, usually stackers,
2029 have only a single routine for mounting tapes, which also automatically
2030 unmounts a tape whose presence prevents insertion of the required new
2031 tape. In this case, an <B>UNMOUNT</B> instruction is not
2032 necessary. For devices that have separate mounting and unmounting
2033 routines, you must include an <B>UNMOUNT</B> instruction to remove a tape
2034 when the Tape Coordinator is finished with it; otherwise, subsequent
2035 attempts to run the <B>MOUNT</B> instruction fail with an error.
2036 <P>When the device configuration file includes a <B>MOUNT</B> instruction,
2037 you must stock the stacker or jukebox with the necessary tapes before running
2038 a backup operation. Many jukeboxes are able to search for the required
2039 tape by reading external labels (such as barcodes) on the tapes, but many
2040 stackers can only switch between tapes in sequence and sometimes only in one
2041 direction. In the latter case, you must also stock the tapes in the
2042 correct order.
2043 <P>To obtain a list of the tapes required for a restore operation so that you
2044 can prestock them in the tape device, include the <B>-n</B> flag on the
2045 appropriate <B>backup</B> command (<B>backup diskrestore</B>,
2046 <B>backup volrestore</B>, or <B>backup volsetrestore</B>). For
2047 a dump operation, it is generally sufficient to stock the device with more
2048 tapes than the operation is likely to require. You can prelabel the
2049 tapes with permanent names or AFS tape names, or not prelabel them at
2050 all. If you prelabel the tapes for a dump operation with AFS tape
2051 names, then it is simplest to load them into the stacker in sequential order
2052 by tape index. But it is probably simpler still to prelabel tapes with
2053 permanent tape names or use unlabeled tapes, in which case the Backup System
2054 generates and applies the appropriately indexed AFS tape name itself during
2055 the dump operation.
2056 <P><H4><A NAME="Header_312">How the Tape Coordinator Uses the MOUNT and UNMOUNT Instructions</A></H4>
2057 <P>When you issue the <B>butc</B> command to initialize the Tape
2058 Coordinator for a given tape device, the Tape Coordinator looks for the device
2059 configuration file called <B>/usr/afs/backup/CFG_</B><VAR>device_name</VAR>
2060 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>
2061 instruction, then whenever the Tape Coordinator needs a tape, it executes the
2062 script named by the instruction's <VAR>filename</VAR> argument.
2063 <P>If the device configuration file does not exist, or does not include a
2064 <B>MOUNT</B> instruction, then whenever the Tape Coordinator needs a tape,
2065 it generates a prompt in its window instructing the operator to insert the
2066 necessary tape. The operator must insert the tape and press
2067 <B>&lt;Return></B> before the Tape Coordinator continues the backup
2068 operation.
2069 <P>Note, however, that you can modify the Tape Coordinator's behavior
2070 with respect to the first tape needed for an operation, by setting the
2071 <B>AUTOQUERY</B> instruction in the device configuration file to
2072 <B>NO</B>, or including the <B>-noautoquery</B> flag to the
2073 <B>butc</B> command. In this case, the Tape Coordinator does not
2074 execute the <B>MOUNT</B> instruction or prompt for a tape at the start of
2075 an operation, because it expects to find the required first tape in the
2076 drive. See <A HREF="#HDRWQ278">Eliminating the Search or Prompt for the Initial Tape</A>.
2077 <P>If there is an <B>UNMOUNT</B> instruction in the device configuration
2078 file, then whenever the Tape Coordinator closes the tape device, it executes
2079 the script named by the instruction's <VAR>filename</VAR> argument.
2080 It executes the script only once, and regardless of whether the
2081 <B>close</B> operation on the device succeeded or not. If the
2082 device configuration file does not include an <B>UNMOUNT</B> instruction,
2083 then the Tape Coordinator takes no action.
2084 <P><H4><A NAME="Header_313">The Available Parameters and Required Exit Codes</A></H4>
2085 <P>When the Tape Coordinator executes the <B>MOUNT</B> script, it
2086 passes in five parameters, ordered as follows. You can use the
2087 parameters in your script to refine its response to varying circumstances that
2088 can arise during a backup operation.
2089 <OL TYPE=1>
2090 <P><LI>The tape device or backup data file's pathname, as recorded in the
2091 <B>/usr/afs/backup/tapeconfig</B> file.
2092 <P><LI>The tape operation, which (except for the exceptions noted in the
2093 following list) matches the <B>backup</B> command operation code used to
2094 initiate the operation:
2095 <UL>
2096 <P><LI><B>appenddump</B> (when a <B>backup dump</B> command includes the
2097 <B>-append</B> flag)
2098 <P><LI><B>dump</B> (when a <B>backup dump</B> command does not include
2099 the <B>-append</B> flag)
2100 <P><LI><B>labeltape</B>
2101 <P><LI><B>readlabel</B>
2102 <P><LI><B>restore</B> (for a <B>backup diskrestore</B>, <B>backup
2103 volrestore</B>, or <B>backup volsetrestore</B> command)
2104 <P><LI><B>restoredb</B>
2105 <P><LI><B>savedb</B>
2106 <P><LI><B>scantape</B>
2107 </UL>
2108 <P><LI>The number of times the Tape Coordinator has attempted to open the tape
2109 device or backup data file. If the open attempt returns an error, the
2110 Tape Coordinator increments this value by one and again invokes the
2111 <B>MOUNT</B> instruction.
2112 <P><LI>The tape name. For some operations, the Tape Coordinator passes the
2113 string <TT>none</TT>, because it does not know the tape name (when running
2114 the <B>backup scantape</B> or <B>backup readlabel</B>, for example),
2115 or because the tape does not necessarily have a name (when running the
2116 <B>backup labeltape</B> command, for example).
2117 <P><LI>The tape ID recorded in the Backup Database. As with the tape name,
2118 the Backup System passes the string <TT>none</TT> for operations where it
2119 does not know the tape ID or the tape does not necessarily have an ID.
2120 </OL>
2121 <P>Your <B>MOUNT</B> script must return one of the following exit codes to
2122 tell the Tape Coordinator whether or not it mounted the tape
2123 successfully:
2124 <UL>
2125 <P><LI>Code <B>0</B> (zero) indicates a successful mount, and the Tape
2126 Coordinator continues the backup operation. If the script or program
2127 called by the <B>MOUNT</B> instruction does not return this exit code, the
2128 Tape Coordinator never calls the <B>UNMOUNT</B> instruction.
2129 <P><LI>Code <B>1</B> indicates that mount attempt failed. The Tape
2130 Coordinator terminates the backup operation.
2131 <P><LI>Any other code indicates that the script was unable to access the correct
2132 tape. The Tape Coordinator prompts the operator to insert it.
2133 </UL>
2134 <P>When the Tape Coordinator executes the <B>UNMOUNT</B> script, it passes
2135 in two parameters in the following order.
2136 <OL TYPE=1>
2137 <P><LI>The tape device's pathname (as specified in the
2138 <B>/usr/afs/backup/tapeconfig</B> file)
2139 <P><LI>The tape operation, which is always <B>unmount</B>.
2140 </OL>
2141 <P>The following example script uses two of the parameters passed to it by the
2142 Backup System: <TT>tries</TT> and <TT>operation</TT>. It
2143 follows the recommended practice of exiting if the value of the
2144 <TT>tries</TT> parameter exceeds one, because that implies that the stacker
2145 is out of tapes.
2146 <P>For a <B>backup dump</B> or <B>backup savedb</B> operation, the
2147 routine calls the example <B>stackerCmd_NextTape</B> function provided by
2148 the stacker's manufacturer. Note that the final lines in the file
2149 return the exit code that prompts the operator to insert a tape; these
2150 lines are invoked when either the stacker cannot load a tape or a the
2151 operation being performed is not one of those explicitly mentioned in the file
2152 (is a restore operation, for example).
2153 <PRE>   #! /bin/csh -f
2154
2155    set devicefile = $1
2156    set operation = $2
2157    set tries = $3
2158    set tapename = $4
2159    set tapeid = $5
2160    set exit_continue = 0
2161    set exit_abort = 1
2162    set exit_interactive = 2
2163    #--------------------------------------------
2164    if (${tries} > 1) then
2165       echo "Too many tries"
2166       exit ${exit_interactive}
2167    endif
2168    if (${operation} == "unmount") then
2169       echo "UnMount: Will leave tape in drive"
2170       exit ${exit_continue}
2171    endif
2172    if ((${operation} == "dump")     |\
2173        (${operation} == "appenddump")     |\
2174        (${operation} == "savedb"))  then
2175
2176        stackerCmd_NextTape ${devicefile}
2177        if (${status} != 0)exit${exit_interactive}
2178        echo "Will continue"
2179        exit ${exit_continue}
2180    endif
2181
2182    if ((${operation} == "labeltape")    |\
2183        (${operation} == "readlabel")) then
2184       echo "Will continue"
2185       exit ${exit_continue}
2186    endif
2187
2188    echo "Prompt for tape"
2189    exit ${exit_interactive}
2190 </PRE>
2191 <A NAME="IDX6963"></A>
2192 <A NAME="IDX6964"></A>
2193 <A NAME="IDX6965"></A>
2194 <A NAME="IDX6966"></A>
2195 <P><H3><A NAME="HDRWQ278" HREF="auagd002.htm#ToC_314">Eliminating the Search or Prompt for the Initial Tape</A></H3>
2196 <P>By default, the Tape Coordinator obtains the first tape it
2197 needs for a backup operation by reading the device configuration file for the
2198 appropriate tape device. If there is a <B>MOUNT</B> instruction in
2199 the file, the Tape Coordinator executes the referenced script. If the
2200 device configuration file does not exist or does not have a <B>MOUNT</B>
2201 instruction in it, the Tape Coordinator prompts you to insert the correct tape
2202 and press <B>&lt;Return></B>.
2203 <P>If you know in advance that an operation requires a tape, you can increase
2204 efficiency by placing the required tape in the drive before issuing the
2205 <B>backup</B> command and telling the Tape Coordinator's to skip its
2206 initial tape-acquisition steps. This both enables the operation to
2207 begin more quickly and eliminates that need for you to be present to insert a
2208 tape.
2209 <P>There are two ways to bypass the Tape Coordinator's initial
2210 tape-acquisition steps:
2211 <OL TYPE=1>
2212 <P><LI>Include the instruction <B>AUTOQUERY NO</B> in the device
2213 configuration file
2214 <P><LI>Include the <B>-noautoquery</B> flag to the <B>butc</B> command
2215 </OL>
2216 <P>To avoid any error conditions that require operator attention, be sure that
2217 the tape you are placing in the drive does not contain any unexpired dumps and
2218 is not write protected. If there is no permanent name on the
2219 tape's label and you are creating an initial dump, make sure that the AFS
2220 tape name either matches the volume set and dump set names or is
2221 <TT>&lt;NULL></TT>. Alternatively, suppress the Tape
2222 Coordinator's name verification step by assigning the value <B>NO</B>
2223 to the <B>NAME_CHECK</B> instruction in the device configuration file, as
2224 described in <A HREF="#HDRWQ280">Eliminating the AFS Tape Name Check</A>.
2225 <A NAME="IDX6967"></A>
2226 <A NAME="IDX6968"></A>
2227 <A NAME="IDX6969"></A>
2228 <P><H3><A NAME="HDRWQ279" HREF="auagd002.htm#ToC_315">Enabling Default Responses to Error Conditions</A></H3>
2229 <P>By default, the Tape Coordinator asks you how to respond
2230 when it encounters certain error conditions. To suppress the prompts
2231 and cause the Tape Coordinator to handle the errors in a predetermined manner,
2232 include the instruction <B>ASK NO</B> in the device configuration
2233 file. If you assign the value <B>YES</B>, or omit the
2234 <B>ASK</B> instruction completely, the Tape Coordinator prompts you for
2235 direction when it encounters one of the errors.
2236 <P>The following list describes the error conditions and the Tape
2237 Coordinator's response to them.
2238 <UL>
2239 <P><LI>The Backup System is unable to dump a volume while running the <B>backup
2240 dump</B> command. When you assign the value <B>NO</B>, the Tape
2241 Coordinator omits the volume from the dump and continues the operation.
2242 When you assign the value <B>YES</B>, it prompts to ask if you want to try
2243 to dump the volume again immediately, to omit the volume from the dump but
2244 continue the operation, or to terminate the operation.
2245 <P><LI>The Backup System is unable to restore a volume while running the
2246 <B>backup diskrestore</B>, <B>backup volrestore</B>, or <B>backup
2247 volsetrestore</B> command. When you assign the value <B>NO</B>,
2248 the Tape Coordinator continues the operation, omitting the problematic volume
2249 but restoring the remaining ones. When you assign the value
2250 <B>YES</B>, it prompts to ask if you want to omit the volume and continue
2251 the operation, or to terminate the operation.
2252 <P><LI>The Backup System cannot determine if the dump set includes any more tapes
2253 while running the <B>backup scantape</B> command (the command's
2254 reference page in the <I>IBM AFS Administration Reference</I> discusses
2255 possible reasons for this problem). When you assign the value
2256 <B>NO</B>, the Tape Coordinator proceeds as though there are more tapes
2257 and invokes the <B>MOUNT</B> script named in the device configuration
2258 file, or prompts the operator to insert the next tape. When you assign
2259 the value <B>YES</B>, it prompts to ask if there are more tapes to
2260 scan.
2261 <P><LI>The Backup System determines that the tape contains an unexpired dump
2262 while running the <B>backup labeltape</B> command. When you assign
2263 the value <B>NO</B>, it terminates the operation without relabeling the
2264 tape. With a <B>YES</B> value, the Tape Coordinator prompts to ask
2265 if you want to relabel the tape anyway.
2266 </UL>
2267 <A NAME="IDX6970"></A>
2268 <A NAME="IDX6971"></A>
2269 <A NAME="IDX6972"></A>
2270 <A NAME="IDX6973"></A>
2271 <P><H3><A NAME="HDRWQ280" HREF="auagd002.htm#ToC_316">Eliminating the AFS Tape Name Check</A></H3>
2272 <P>If a tape does not have a permanent name and you are writing
2273 an initial dump to it, then by default the Backup System verifies that the
2274 tape's AFS tape name is acceptable. It accepts three types of
2275 values:
2276 <UL>
2277 <P><LI>A name that reflects the volume set and dump level of the initial dump and
2278 the tape's place in the sequence of tapes for the dump set, as described
2279 in <A HREF="#HDRWQ253">Dump Names and Tape Names</A>. If the tape does not already have a permanent name,
2280 you can assign the AFS tape name by using the <B>-name</B> argument to the
2281 <B>backup labeltape</B> command.
2282 <P><LI>A <TT>&lt;NULL></TT> value, which results when you assign a permanent
2283 name, or provide no value for the <B>backup labeltape</B> command's
2284 <B>-name</B> argument.
2285 <P><LI>No AFS tape name at all, indicating that you have never labeled the tape
2286 or written a dump to it.
2287 </UL>
2288 <P>To bypass the name check, include the <B>NAME_CHECK NO</B> instruction
2289 in the device configuration file. This enables you to recycle a tape
2290 without first relabeling it, as long as all dumps on it are expired.
2291 (If a tape has unexpired dumps on it but you want to recycle it anyway, you
2292 must use the <B>backup labeltape</B> command to relabel it first.
2293 For this to work, the <B>ASK NO</B> instruction cannot appear in the
2294 device configuration file.)
2295 <P><H3><A NAME="HDRWQ281" HREF="auagd002.htm#ToC_317">Setting the Memory Buffer Size to Promote Tape Streaming</A></H3>
2296 <P>By default, the Tape Coordinator uses a 16-KB memory buffer
2297 during dump operations. As it receives volume data from the Volume
2298 Server, the Tape Coordinator gathers 16 KB of data in the buffer before
2299 transferring the entire 16 KB to the tape device. Similarly, during a
2300 restore operation the Tape Coordinator by default buffers 32 KB of data from
2301 the tape device before transferring the entire 32 KB to the Volume Server for
2302 restoration into the file system. Buffering makes the volume of data
2303 flowing to and from a tape device more even and so promotes tape streaming,
2304 which is the most efficient way for a tape device to operate.
2305 <P>In a normal network configuration, the default buffer sizes are usually
2306 large enough to promote tape streaming. If the network between the Tape
2307 Coordinator machine and file server machines is slow, it can help to increase
2308 the buffer size.
2309 <P>To determine if altering the buffer size is helpful for your configuration,
2310 observe the tape device in operation to see if it is streaming, or consult the
2311 manufacturer. To set the buffer size, include the <B>BUFFERSIZE</B>
2312 instruction in the device configuration file. It takes an integer
2313 value, and optionally units, in the following format:
2314 <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>}]
2315 </PRE>
2316 <P>where <VAR>size</VAR> specifies the amount of memory the Tape Coordinator
2317 allocates to use as a buffer during both dump and restore operations.
2318 The default unit is bytes, but use <B>k</B> or <B>K</B> to specify
2319 kilobytes, <B>m</B> or <B>M</B> for megabytes, and <B>g</B> or
2320 <B>G</B> for gigabytes. There is no space between the <VAR>size</VAR>
2321 value and the units letter.
2322 <P><H3><A NAME="HDRWQ282" HREF="auagd002.htm#ToC_318">Dumping Data to a Backup Data File</A></H3>
2323 <P>You can write dumps to a <I>backup data file</I> rather
2324 than to tape. This is useful if, for example, you want to transfer the
2325 data to a data-archiving system, such as a hierarchical storage management
2326 (HSM) system, that you use in conjunction with AFS and the Backup
2327 System. You can restore data from a backup data file into the file
2328 system as well. Using a backup data file is usually more efficient than
2329 issuing the equivalent <B>vos dump</B> and <B>vos restore</B> commands
2330 individually for multiple volumes.
2331 <P>Writing to a backup data file is simplest if it is on the local disk of the
2332 Tape Coordinator machine, but you can also write the file to an NFS-mounted
2333 partition that resides on a remote machine. It is even acceptable to
2334 write to a file in AFS, provided that the access control list (ACL) on its
2335 parent directory grants the necessary permissions, but it is somewhat circular
2336 to back up AFS data into AFS itself.
2337 <P>If the backup data file does not already exist when the Tape Coordinator
2338 attempts to write a dump to it, the Tape Coordinator creates it. For a
2339 restore operation to succeed, the file must exist and contain volume data
2340 previously written to it during a <B>backup dump</B> operation.
2341 <P>When writing to a backup data file, the Tape Coordinator writes data at 16
2342 KB offsets. If a given block of data (such as the marker that signals
2343 the beginning or end of a volume) does not fill the entire 16 KB, the Tape
2344 Coordinator still skips to the next offset before writing the next
2345 block. In the output of a <B>backup dumpinfo</B> command issued
2346 with the <B>-id</B> option, the value in the <TT>Pos</TT> column is the
2347 ordinal of the 16-KB offset at which the volume data begins, and so is not
2348 generally only one higher than the position number on the previous line, as it
2349 is for dumps to tape.
2350 <P>Before writing to a backup data file, you need to configure the file as
2351 though it were a tape device.
2352 <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
2353 field of the <B>/usr/afs/backup/tapeconfig</B> file when the <B>FILE
2354 YES</B> instruction appears in the device configuration file, and vice
2355 versa. If the <B>tapeconfig</B> file instead refers to a tape
2356 device, dump operations appear to succeed but are inoperative. You
2357 cannot restore data that you accidently dumped to a tape device while the
2358 <B>FILE</B> instruction was set to <B>YES</B>. In the same way,
2359 if the <B>FILE</B> instruction is set to <B>NO</B>, the
2360 <B>tapeconfig</B> entry must refer to an actual tape device.
2361 </TD></TR></TABLE>
2362 <P><H3><A NAME="Header_319" HREF="auagd002.htm#ToC_319">To configure a backup data file</A></H3>
2363 <OL TYPE=1>
2364 <P><LI>Verify that you are authenticated as a user listed in the
2365 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
2366 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
2367 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
2368 </PRE>
2369 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
2370 already, by issuing the <B>su</B> command.
2371 <PRE>   % <B>su root</B>
2372    Password: <VAR>root_password</VAR>
2373 </PRE>
2374 <P><LI><B>Optional</B>. Issue the <B>backup</B> command to enter
2375 interactive mode.
2376 <PRE>   # <B>backup</B>
2377 </PRE>
2378 <P><LI>Choose the port offset number to assign to the file. If necessary,
2379 display previously assigned port offsets by issuing the <B>(backup)
2380 listhosts</B> command, which is fully described in <A HREF="#HDRWQ264">To display the list of configured Tape Coordinators</A>.
2381 <PRE>   backup> <B>listhosts</B>
2382 </PRE>
2383 <P>As for a tape device, acceptable values are the integers <B>0</B>
2384 (zero) through <B>58510</B> (the Backup System can track a maximum of
2385 58,511 port offset numbers). Each port offset must be unique in the
2386 cell, but you can associate any number them with a single Tape Coordinator
2387 machine. You do not have to assign port offset numbers
2388 sequentially.
2389 <P><LI>Issue the <B>(backup) addhost</B> command to register the backup data
2390 file's port offset in the Backup Database.
2391 <PRE>   backup> <B>addhost</B> &lt;<VAR>tape&nbsp;machine&nbsp;name</VAR>> [&lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]
2392 </PRE>
2393 <P>where
2394 <DL>
2395 <P><DT><B>addh
2396 </B><DD>Is the shortest acceptable abbreviation of <B>addhost</B>.
2397 <P><DT><B><VAR>tape machine name</VAR>
2398 </B><DD>Specifies the fully qualified hostname of the Tape Coordinator machine you
2399 invoke to write to the backup data file.
2400 <P><DT><B><VAR>TC port offset</VAR>
2401 </B><DD>Specifies the file's port offset number. You must provide this
2402 argument unless the default value of <B>0</B> (zero) is
2403 appropriate.
2404 </DL>
2405 <P><LI><A NAME="LITAPECONFIG-FILE"></A>Using a text editor, create an entry for the backup
2406 data file in the local <B>/usr/afs/backup/tapeconfig</B> file, using the
2407 standard syntax:
2408 <PRE>   [<VAR>capacity</VAR>  <VAR>filemark_size</VAR>]  <VAR>device_name</VAR>   <VAR>port_offset</VAR>
2409 </PRE>
2410 <P>where
2411 <DL>
2412 <P><DT><B><VAR>capacity</VAR>
2413 </B><DD>Specifies the amount of space on the partition that houses the backup data
2414 file that you want to make available for the file. To avoid the
2415 complications that arise from filling up the partition, it is best to provide
2416 a value somewhat smaller than the actual amount of space you expect to be
2417 available when the dump operation runs, and never larger than the maximum file
2418 size allowed by the operating system.
2419 <P>Specify a numerical value followed by a letter that indicates units, with
2420 no intervening space. The letter <B>k</B> or <B>K</B> indicates
2421 kilobytes, <B>m</B> or <B>M</B> indicates megabytes, and <B>g</B>
2422 or <B>G</B> indicates gigabytes. If you omit the units letter, the
2423 default is kilobytes. If you leave this field empty, the Tape
2424 Coordinator uses the maximum acceptable value (2048 GB or 2 TB). Also
2425 leave the <VAR>filemark_size</VAR> field empty in that case.
2426 <P><DT><B><VAR>filemark_size</VAR>
2427 </B><DD>Specify the value <B>0</B> (zero) or leave both this field and the
2428 <VAR>capacity</VAR> field empty. In the latter case, the Tape Coordinator
2429 also uses the value zero.
2430 <P><DT><B><VAR>device_name</VAR>
2431 </B><DD>Specifies the complete pathname of the backup data file. Rather
2432 than specifying an actual file pathname, however, the recommended
2433 configuration is to create a symbolic link in the <B>/dev</B> directory
2434 that points to the actual file pathname, and record the symbolic link in this
2435 field. This configuration provides these advantages:
2436 <UL>
2437 <P><LI>It makes the <VAR>device_name</VAR> portion of the
2438 <B>CFG_</B><VAR>device_name</VAR>, of the
2439 <B>TE_</B><VAR>device_name</VAR>, and of the
2440 <B>TL_</B><VAR>device_name</VAR> filenames as short as possible.
2441 Because the symbolic link is in the <B>/dev</B> directory as though it is
2442 a tape device, you strip off the entire <B>/dev/</B> prefix when forming
2443 the filename, instead of just the initial slash (<B>/</B>). If, for
2444 example, the symbolic link is called <B>/dev/FILE</B>, the device
2445 configuration file's name is <B>CFG_FILE</B>, whereas if the actual
2446 pathname /<B>var/tmp/FILE</B> appears in the <B>tapeconfig</B> file,
2447 the configuration file's name must be <B>CFG_var_tmp_FILE</B>.
2448 <P><LI>It provides for a more graceful, and potentially automated, recovery if
2449 the Tape Coordinator cannot write a complete dump into the backup data file
2450 (for example, because the partition housing the backup data file becomes
2451 full). The Tape Coordinator's reaction to this problem is to
2452 invoke the <B>MOUNT</B> script, or to prompt you if the <B>MOUNT</B>
2453 instruction does not appear in the configuration file.
2454 <UL>
2455 <P><LI>If there is a <B>MOUNT</B> script, you can prepare for this situation
2456 by adding a subroutine to the script that changes the symbolic link to point
2457 to another backup data file on a partition where there is space
2458 available.
2459 <P><LI>If there is no <B>MOUNT</B> instruction, the prompt enables you
2460 manually to change the symbolic link to point to another backup data file and
2461 then press &lt;<B>Return</B>> to signal that the Tape Coordinator can
2462 continue the operation.
2463 </UL>
2464 <P>If this field names the actual file, there is no way to recover from
2465 exhausting the space on the partition. You cannot change the
2466 <B>tapeconfig</B> file in the middle of an operation.
2467 </UL>
2468 <P><DT><B><VAR>port_offset</VAR>
2469 </B><DD>Specifies the port offset number that you chose for the backup data
2470 file.
2471 </DL>
2472 <P><LI>Create the device configuration file <B>CFG_</B><VAR>device_name</VAR>
2473 in the Tape Coordinator machine's <B>/usr/afs/backup</B>
2474 directory. Include the <B>FILE YES</B> instruction in the
2475 file.
2476 <P>Construct the <VAR>device_name</VAR> portion of the name based on the device
2477 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
2478 name, strip off the <B>/dev/</B> string and replace any other slashes
2479 (<B>/</B>) in the name with underscores (<B>_</B>). For
2480 example, <B>CFG_FILE</B> is the appropriate name if the symbolic link is
2481 <B>/dev/FILE</B>. If you recorded the name of an actual file, then
2482 strip off the initial slash only and replace any other slashes in the name
2483 with underscores. For a backup data file called
2484 <B>/var/tmp/FILE</B>, the appropriate device configuration filename is
2485 <B>CFG_var_tmp_FILE</B>.
2486 <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>
2487 field of the <B>tapeconfig</B> entry, then you must do one of the
2488 following:
2489 <UL>
2490 <P><LI>Use the <B>ln -s</B> command to create the appropriate symbolic link
2491 in the <B>/dev</B> directory
2492 <P><LI>Write a script that initializes the backup data file in this way, and
2493 include a <B>MOUNT</B> instruction in the device configuration file to
2494 invoke the script. An example script appears following these
2495 instructions.
2496 </UL>
2497 </OL>
2498 <P>You do not need to create the backup data file itself, because the Tape
2499 Coordinator does so if the file does not exist when the dump operation
2500 begins.
2501 <P>The following example script illustrates how you can automatically create a
2502 symbolic link to the backup data file during the preparation phase for writing
2503 to the file. When the Tape Coordinator is executing a <B>backup
2504 dump</B>, <B>backup restore</B>, <B>backup savedb</B>, or
2505 <B>backup restoredb</B> operation, the routine invokes the UNIX <B>ln
2506 -s</B> command to create a symbolic link from the backup data file named in
2507 the <B>tapeconfig</B> file to the actual file to use (this is the
2508 recommended method). It uses the values of the <TT>tapename</TT> and
2509 <TT>tapeid</TT> parameters passed to it by the Backup System when
2510 constructing the filename.
2511 <P>The routine makes use of two other parameters as well:
2512 <TT>tries</TT> and <TT>operation</TT>. The <TT>tries</TT>
2513 parameter tracks how many times the Tape Coordinator has attempted to access
2514 the file. A value greater than one indicates that the Tape Coordinator
2515 cannot access it, and the routine returns exit code 2
2516 (<TT>exit_interactive</TT>), which results in a prompt for the operator to
2517 load a tape. The operator can use this opportunity to change the name
2518 of the backup data file specified in the <B>tapeconfig</B> file.
2519 <PRE>   #! /bin/csh -f
2520    set devicefile = $1
2521    set operation = $2
2522    set tries = $3
2523    set tapename = $4
2524    set tapeid = $5
2525    set exit_continue = 0
2526    set exit_abort = 1
2527    set exit_interactive = 2
2528    #--------------------------------------------
2529    if (${tries} > 1) then
2530       echo "Too many tries"
2531       exit ${exit_interactive}
2532    endif
2533    if (${operation} == "labeltape") then
2534       echo "Won't label a tape/file"
2535       exit ${exit_abort}
2536    endif
2537    if ((${operation} == "dump")   |\
2538        (${operation} == "appenddump")   |\
2539        (${operation} == "restore")   |\
2540        (${operation} == "savedb")    |\
2541        (${operation} == "restoredb")) then
2542
2543       /bin/rm -f ${devicefile}
2544       /bin/ln -s /hsm/${tapename}_${tapeid} ${devicefile}
2545       if (${status} != 0) exit ${exit_abort}
2546    endif
2547
2548    exit ${exit_continue}
2549 </PRE>
2550 <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>
2551 <!-- Begin Footer Records  ========================================== -->
2552 <P><HR><B>
2553 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
2554 </B>
2555 <!-- End Footer Records  ============================================ -->
2556 <A NAME="Bot_Of_Page"></A>
2557 </BODY></HTML>