doc/html/AdminReference/auarf018.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
   2 <HTML><HEAD>
   3 <TITLE>Administration Reference</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3672/auarf000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 3 Oct 2000 at 16:18:30                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Tue, 03 Oct 2000 16:18:29">
   8 <META HTTP-EQUIV="review" CONTENT="Wed, 03 Oct 2001 16:18:29">
   9 <META HTTP-EQUIV="expires" CONTENT="Thu, 03 Oct 2002 16:18:29">
  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 Reference</H1>
  16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf017.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="auarf019.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
  17 <P>
  18 <H2><A NAME="HDRCFG" HREF="auarf002.htm#ToC_16">CFG_<I>device_name</I></A></H2>
  19 <P><STRONG>Purpose</STRONG>
  20 <A NAME="IDX3900"></A>
  21 <A NAME="IDX3901"></A>
  22 <A NAME="IDX3902"></A>
  23 <A NAME="IDX3903"></A>
  24 <A NAME="IDX3904"></A>
  25 <P>Defines Tape Coordinator configuration instructions for automated tape
  26 devices
  27 <P><STRONG>Description</STRONG>
  28 <P>The <B>CFG_</B><VAR>device_name</VAR> file includes instructions that
  29 configure a Tape Coordinator for use with automated backup devices such as
  30 tape stackers and jukeboxes, enable the Tape Coordinator to dump and restore
  31 data to a <I>backup data file</I> on a local disk device, and enable
  32 greater automation of other aspects of the backup process.
  33 <P>There is a separate configuration file for each tape device or backup data
  34 file. Creating the file is optional, and unnecessary if none of the
  35 instructions it can include pertain to a given tape device. The
  36 ASCII-format file must reside in the <B>/usr/afs/backup</B> directory on
  37 the Tape Coordinator machine if it exists.
  38 <P>The <B>CFG_</B><VAR>device_name</VAR> file does not replace the
  39 <B>/usr/afs/backup/tapeconfig</B> file, a single copy of which still must
  40 exist on every Tape Coordinator machine.
  41 <P>To enable the Tape Coordinator to locate the configuration file, construct
  42 the variable part of the filename, <VAR>device_name</VAR>, as follows:
  43 <UL>
  44 <P><LI>For a tape device, strip off the initial <B>/dev/</B> string from the
  45 device name, and replace any other slashes in the name with
  46 underscores. For example, <B>CFG_rmt_4m</B> is the appropriate
  47 filename for a device called <B>/dev/rmt/4m</B>.
  48 <P><LI>For a backup data file, strip off the initial slash (/) and replace any
  49 other slashes in the name with underscores. For example,
  50 <B>CFG_var_tmp_FILE</B> is the appropriate filename for a backup data file
  51 called <B>/var/tmp/FILE</B>.
  52 </UL>
  53 <P>The <B>CFG_</B><VAR>device_name</VAR> file lists one or more of the
  54 following instructions, each on its own line. All are optional, and
  55 they can appear in any order. A more detailed description of each
  56 instruction follows the list:
  57 <DL>
  58 <P><DT><B>ASK
  59 </B><DD>Controls whether the Tape Coordinator prompts for guidance when it
  60 encounters error conditions
  61 <P><DT><B>AUTOQUERY
  62 </B><DD>Controls whether the Tape Coordinator prompts for the first tape
  63 <P><DT><B>BUFFERSIZE
  64 </B><DD>Sets the size of the memory buffer the Tape Coordinator uses when
  65 transferring data
  66 <P><DT><B>FILE
  67 </B><DD>Controls whether the dump is written to a tape device or a file
  68 <P><DT><B>MOUNT
  69 </B><DD>Identifies the file that contains routines for inserting tapes into the
  70 device's drive
  71 <P><DT><B>NAME_CHECK
  72 </B><DD>Controls whether the Tape Coordinator verifies that a tape's AFS tape
  73 name matches the dump being written
  74 <P><DT><B>UNMOUNT
  75 </B><DD>Identifies the file that contains routines for removing tapes from the
  76 device's drive
  77 </DL>
  78 <A NAME="IDX3905"></A>
  79 <P><B>The ASK Instruction</B>
  80 <P>The <B>ASK</B> instruction takes a boolean value as its argument, in
  81 the following format:
  82 <PRE>   ASK {<B>YES</B> | <B>NO</B>}
  83
  84 </PRE>
  85 <P>When the value is <B>YES</B>, the Tape Coordinator generates a prompt
  86 in its window, requesting a response to the error cases described in the
  87 following list. This is the default behavior if the ASK instruction
  88 does not appear in the <B>CFG_</B><VAR>device_name</VAR> file.
  89 <P>When the value is <B>NO</B>, the Tape Coordinator does not prompt in
  90 error cases, but instead uses the automatic default responses described in the
  91 following list. The Tape Coordinator also logs the error in the
  92 <B>TE_</B><VAR>device_name</VAR> file. Suppressing the prompts
  93 enables the Tape Coordinator to run unattended, though it still prompts for
  94 insertion of tapes unless the <B>MOUNT</B> instruction is used.
  95 <P>The error cases controlled by this instruction are the following:
  96 <UL>
  97 <P><LI>The Backup System is unable to dump a volume while running the <B>backup
  98 dump</B> command. With a <B>YES</B> value, the Tape Coordinator
  99 prompts to offer three choices: try to dump the volume again
 100 immediately, omit the volume from the dump but continue the operation, or
 101 terminate the operation. With a <B>NO</B> value, the Tape
 102 Coordinator omits the volume from the dump and continues the operation.
 103 <P><LI>The Backup System is unable to restore a volume while running the
 104 <B>backup diskrestore</B>, <B>backup volrestore</B>, or <B>backup
 105 volsetrestore</B> command. With a <B>YES</B> value, the Tape
 106 Coordinator prompts to offer two choices: omit the volume and continue
 107 restoring the other volumes, or terminate the operation. With a
 108 <B>NO</B> value, it continues the operation without prompting, omitting
 109 the problematic volume but restoring the remaining ones.
 110 <P><LI>The Backup System cannot determine if the dump set includes any more
 111 tapes, while running the <B>backup scantape</B> command (the reference
 112 page for that command discusses possible reasons for this problem).
 113 With a <B>YES</B> value, the Tape Coordinator prompts to ask if there are
 114 more tapes to scan. With a <B>NO</B> value, it proceeds as though
 115 there are more tapes and invokes the routine named by the <B>MOUNT</B>
 116 instruction in the configuration file, or prompts the operator to insert the
 117 next tape.
 118 <P><LI>The Backup System determines that the tape contains an unexpired dump
 119 while running the <B>backup labeltape</B> command. With a
 120 <B>YES</B> value, the Tape Coordinator prompts to offer two choices:
 121 continue or terminate the labeling operation. With a <B>NO</B>
 122 value, it terminates the operation without relabeling the tape.
 123 </UL>
 124 <A NAME="IDX3906"></A>
 125 <P><B>The AUTOQUERY Instruction</B>
 126 <P>The <B>AUTOQUERY</B> instruction takes a boolean value as its argument,
 127 in the following format:
 128 <PRE>   AUTOQUERY {<B>YES</B> | <B>NO</B>}
 129
 130 </PRE>
 131 <P>When the value is <B>YES</B>, the Tape Coordinator checks for the
 132 <B>MOUNT</B> instruction in the configuration file when it needs to read
 133 the first tape involved in an operation. As described for that
 134 instruction, it then either prompts for the tape or invokes the specified
 135 routine to mount the tape. This is the default behavior if the
 136 <B>AUTOQUERY</B> instruction does not appear in the configuration
 137 file.
 138 <P>When the value is <B>NO</B>, the Tape Coordinator assumes that the
 139 first tape required for an operation is already in the drive. It does
 140 not prompt the operator or invoke the <B>MOUNT</B> routine unless there is
 141 an error in accessing the first tape. This setting is equivalent in
 142 effect to including the <B>-noautoquery</B> flag to the <B>butc</B>
 143 command.
 144 <P>Note that the setting of the <B>AUTOQUERY</B> instruction controls the
 145 Tape Coordinator's behavior only with respect to the first tape required
 146 for an operation. For subsequent tapes, the Tape Coordinator always
 147 checks for the <B>MOUNT</B> instruction. It also refers to the
 148 <B>MOUNT</B> instruction if it encounters an error while attempting to
 149 access the first tape.
 150 <A NAME="IDX3907"></A>
 151 <P><B>The BUFFERSIZE Instruction</B>
 152 <P>The <B>BUFFERSIZE</B> instruction takes an integer value, and
 153 optionally units, in the following format:
 154 <PRE>   BUFFERSIZE <VAR>size</VAR>[{<B>k</B> | <B>K</B> | <B>m</B> | <B>M</B> | <B>g</B> | <B>G</B>}]
 155
 156 </PRE>
 157 <P>where<VAR> size</VAR> specifies the amount of memory the Tape Coordinator
 158 allocates to use as a buffer during both dump and restore operations.
 159 The default unit is bytes, but use <B>k</B> or <B>K</B> to specify
 160 kilobytes, <B>m</B> or <B>M</B> for megabytes, and <B>g</B> or
 161 <B>G</B> for gigabytes. There is no space between the
 162 <VAR>size</VAR>value and the units letter.
 163 <P>By default, the Tape Coordinator uses a 16 KB buffer during dump
 164 operations. As it receives volume data from the Volume Server, the Tape
 165 Coordinator gathers 16 KB of data in the buffer before transferring the entire
 166 16 KB to the tape device or backup data file. Similarly, during a
 167 restore operation the Tape Coordinator by default buffers 32 KB of data from
 168 the tape device or backup data file before transferring the entire 32 KB to
 169 the Volume Server for restoration into the file system. Buffering makes
 170 the volume of data flowing to and from a tape device more even and so promotes
 171 tape streaming, which is the most efficient way for a tape device to
 172 operate.
 173 <P>In a normal network configuration, the default buffer sizes are usually
 174 large enough to promote tape streaming. If the network between the Tape
 175 Coordinator machine and file server machines is slow, it can help to increase
 176 the buffer size.
 177 <A NAME="IDX3908"></A>
 178 <P><B>The FILE Instruction</B>
 179 <P>The <B>FILE</B> instruction takes a boolean value as its argument, in
 180 the following format:
 181 <PRE>   FILE {<B>NO</B> | <B>YES</B>}
 182
 183 </PRE>
 184 <P>When the value is <B>NO</B>, the Tape Coordinator writes to a tape
 185 device during a dump operation and reads from one during a restore
 186 operation. This is the default behavior if the <B>FILE</B>
 187 instruction does not appear in the configuration file.
 188 <P>When the value is <B>YES</B>, the Tape Coordinator writes volume data
 189 to a backup data file on the local disk during a dump operation and reads
 190 volume data from a file during a restore operation. If the file does
 191 not exist when the Tape Coordinator attempts to access it to write a dump, the
 192 Tape Coordinator creates it. For a restore operation to succeed, the
 193 file must exist and contain volume data previously written to it by a
 194 <B>backup dump</B> operation.
 195 <P>When the value is <B>YES</B>, the backup data file's complete
 196 pathname must appear (instead of a tape drive device name) in the third field
 197 of the corresponding port offset entry in the local
 198 <B>/usr/afs/backup/tapeconfig</B> file. If the field instead refers
 199 to a tape device, dump operations appear to succeed but are
 200 inoperative. It is not possible to restore data that was accidently
 201 dumped to a tape device while the <B>FILE</B> instruction was set to
 202 <B>YES</B>. (In the same way, if the <B>FILE</B> instruction is
 203 set to <B>NO</B>, the <B>tapeconfig</B> entry must refer to an actual
 204 tape device.)
 205 <P>Rather than put an actual file pathname in the third field of the
 206 <B>tapeconfig</B> file, however, the recommended configuration is to
 207 create a symbolic link in the <B>/dev</B> directory that points to the
 208 actual file pathname, and record the symbolic link in this field. This
 209 configuration has a couple of advantages:
 210 <UL>
 211 <P><LI>It makes the <VAR>device_name</VAR> portion of the
 212 <B>CFG_</B><VAR>device_name</VAR>, <B>TE_</B><VAR>device_name</VAR>, and
 213 <B>TL_</B><VAR>device_name</VAR> names as short as possible. Because
 214 the symbolic link is in the <B>/dev</B> directory as though it were a tape
 215 device, the device configuration file's name is constructed by stripping
 216 off the entire <B>/dev/</B> prefix, instead of just the initial
 217 slash. If, for example, the symbolic link is called
 218 <B>/dev/FILE</B>, the device configuration file name is
 219 <B>CFG_FILE</B>, whereas if the actual pathname <B>/var/tmp/FILE</B>
 220 appears in the <B>tapeconfig</B> file, the file's name must be
 221 <B>CFG_var_tmp_FILE</B>.
 222 <P><LI>It provides for a more graceful, and potentially automated, recovery if
 223 the Tape Coordinator cannot write a complete dump into the backup data file
 224 (because the partition housing the backup data file becomes full, for
 225 example). The Tape Coordinator's reaction to this problem is to
 226 invoke the <B>MOUNT</B> script, or to prompt the operator if the
 227 <B>MOUNT</B> instruction does not appear in the configuration file.
 228 <UL>
 229 <P><LI>If there is a <B>MOUNT</B> routine, the operator can prepare for this
 230 situation by adding a subroutine that changes the symbolic link to point to
 231 another backup data file on a partition where there is space available.
 232 <P><LI>If there is no <B>MOUNT</B> instruction, the prompt enables the
 233 operator manually to change the symbolic link to point to another backup data
 234 file, then press &lt;<B>Return</B>> to signal that the Tape Coordinator
 235 can continue the operation.
 236 </UL>
 237 </UL>
 238 <P>If the third field in the <B>tapeconfig</B> file names the actual file,
 239 there is no way to recover from exhausting the space on the partition that
 240 houses the backup data file. It is not possible to change the
 241 <B>tapeconfig</B> file in the middle of an operation.
 242 <P>When writing to a backup data file, the Tape Coordinator writes data at 16
 243 KB offsets. If a given block of data (such as the marker that signals
 244 the beginning or end of a volume) does not fill the entire 16 KB, the Tape
 245 Coordinator still skips to the next offset before writing the next
 246 block. In the output of a <B>backup dumpinfo</B> command issued
 247 with the <B>-id</B> option, the value in the <TT>Pos</TT> column is the
 248 ordinal of the 16-KB offset at which the volume data begins, and so is not
 249 generally only one higher than the position number on the previous line, as it
 250 is for dumps to tape.
 251 <A NAME="IDX3909"></A>
 252 <P><B>The MOUNT Instruction</B>
 253 <P>The <B>MOUNT</B> instruction takes a pathname as its argument, in the
 254 following format:
 255 <PRE>
 256    MOUNT <VAR>filename</VAR>
 257
 258 </PRE>
 259 <P>The referenced executable file must reside on the local disk and contain a
 260 shell script or program that directs an automated tape device, such as a
 261 jukebox or stacker, to mount a tape (insert it into the tape reader).
 262 The operator must write the routine to invoke the mount command specified by
 263 the device's manufacturer; AFS does not include any scripts,
 264 although an example appears in the following <B>Examples</B>
 265 section. The script or program inherits the Tape Coordinator's AFS
 266 authentication status.
 267 <P>When the Tape Coordinator needs to mount a tape, it checks the
 268 configuration file for a <B>MOUNT</B> instruction. If there is no
 269 <B>MOUNT</B> instruction, the Tape Coordinator prompts the operator to
 270 insert a tape before it attempts to open the tape device. If there is a
 271 <B>MOUNT</B> instruction, the Tape Coordinator executes the routine in the
 272 referenced file. The routine invoked by the <B>MOUNT</B>
 273 instruction inherits the local identity (UNIX UID) and AFS tokens of the
 274 <B>butc</B> command's issuer.
 275 <P>There is an exception to this sequence: if the <B>AUTOQUERY
 276 NO</B> instruction appears in the configuration file, or the
 277 <B>-noautoquery</B> flag was included on the <B>butc</B> command, then
 278 the Tape Coordinator assumes that the operator has already inserted the first
 279 tape needed for a given operation. It attempts to read the tape
 280 immediately, and only checks for the <B>MOUNT</B> instruction or prompts
 281 the operator if the tape is missing or is not the required one.
 282 <P>When the Tape Coordinator invokes the routine indicated by the
 283 <B>MOUNT</B> instruction, it passes the following parameters to the
 284 routine in the indicated order:
 285 <OL TYPE=1>
 286 <P><LI>The tape device or backup data file's pathname, as recorded in the
 287 <B>/usr/afs/backup/tapeconfig</B> file.
 288 <P><LI>The tape operation, which (except for the exceptions noted in the
 289 following list) matches the <B>backup</B> command operation code used to
 290 initiate the operation:
 291 <UL>
 292 <P><LI><B>appenddump</B> (when a <B>backup dump</B> command includes the
 293 <B>-append</B> flag)
 294 <P><LI><B>dump</B> (when a <B>backup dump</B> command does not include
 295 the <B>-append</B> flag)
 296 <P><LI><B>labeltape</B>
 297 <P><LI><B>readlabel</B>
 298 <P><LI><B>restore</B> (for a <B>backup diskrestore</B>, <B>backup
 299 volrestore</B>, or <B>backup volsetrestore</B> command)
 300 <P><LI><B>restoredb</B>
 301 <P><LI><B>savedb</B>
 302 <P><LI><B>scantape</B>
 303 </UL>
 304 <P><LI>The number of times the Tape Coordinator has attempted to open the tape
 305 device or backup data file. If the open attempt returns an error, the
 306 Tape Coordinator increments this value by one and again invokes the
 307 <B>MOUNT</B> instruction.
 308 <P><LI>The tape name. For some operations, the Tape Coordinator passes the
 309 string <TT>none</TT>, because it does not know the tape name (when running
 310 the <B>backup scantape</B> or <B>backup readlabel</B>, for example),
 311 or because the tape does not necessarily have a name (when running the
 312 <B>backup labeltape</B> command, for example).
 313 <P><LI>The tape ID recorded in the Backup Database. As with the tape name,
 314 the Backup System passes the string <TT>none</TT> for operations where it
 315 does not know the tape ID or the tape does not necessarily have an ID.
 316 </OL>
 317 <P>The routine invoked by the <B>MOUNT</B> instruction must return an exit
 318 code to the Tape Coordinator:
 319 <UL>
 320 <P><LI>Code <B>0</B> (zero) indicates that the routine successfully mounted
 321 the tape. The Tape Coordinator continues the backup operation.
 322 If the routine invoked by the <B>MOUNT</B> instruction does not return
 323 this exit code, the Tape Coordinator never calls the <B>UNMOUNT</B>
 324 instruction.
 325 <P><LI>Code <B>1</B> (one) indicates that the routine failed to mount the
 326 tape. The Tape Coordinator terminates the operation.
 327 <P><LI>Any other code indicates that the routine was not able to access the
 328 correct tape. The Tape Coordinator prompts the operator to insert the
 329 correct tape.
 330 </UL>
 331 <P>If the <B>backup</B> command was issued in interactive mode and the
 332 operator issues the <B>(backup) kill</B> command while the
 333 <B>MOUNT</B> routine is running, the Tape Coordinator passes the
 334 termination signal to the routine; the entire operation
 335 terminates.
 336 <A NAME="IDX3910"></A>
 337 <P><B>The NAME_CHECK Instruction</B>
 338 <P>The <B>NAME_CHECK</B> instruction takes a boolean value as its
 339 argument, in the following format:
 340 <PRE>   NAME_CHECK {<B>YES</B> | <B>NO</B>}
 341
 342 </PRE>
 343 <P>When the value is <B>YES</B> and the tape does not have a permanent
 344 name, the Tape Coordinator checks the AFS tape name when dumping a volume in
 345 response to the <B>backup dump</B> command. The AFS tape name must
 346 be <TT>&lt;NULL></TT> or match the tape name that the <B>backup dump</B>
 347 operation assigns based on the volume set and dump level names. This is
 348 the default behavior if the <B>NAME_CHECK</B> instruction does not appear
 349 in the configuration file.
 350 <P>When the value is <B>NO</B>, the Tape Coordinator does not check the
 351 AFS tape name before writing to the tape.
 352 <P>The Tape Coordinator always checks that all dumps on the tape are expired,
 353 and refuses to write to a tape that contains unexpired dumps.
 354 <A NAME="IDX3911"></A>
 355 <P><B>The UNMOUNT Instruction</B>
 356 <P>The <B>UNMOUNT</B> instruction takes a pathname as its argument, in the
 357 following format:
 358 <PRE>   UNMOUNT <VAR>filename</VAR>
 359
 360 </PRE>
 361 <P>The referenced executable file must reside on the local disk and contain a
 362 shell script or program that directs an automated tape device, such as a
 363 jukebox or stacker, to unmount a tape (remove it from the tape reader).
 364 The operator must write the routine to invoke the unmount command specified by
 365 the device's manufacturer; AFS does not include any scripts,
 366 although an example appears in the following <B>Examples</B>
 367 section. The script or program inherits the Tape Coordinator's AFS
 368 authentication status.
 369 <P>After closing a tape device, the Tape Coordinator checks the configuration
 370 file for an <B>UNMOUNT</B> instruction, whether or not the
 371 <B>close</B> operation succeeds. If there is no <B>UNMOUNT</B>
 372 instruction, the Tape Coordinator takes no action, in which case the operator
 373 must take the action necessary to remove the current tape from the drive
 374 before another can be inserted. If there is an <B>UNMOUNT</B>
 375 instruction, the Tape Coordinator executes the referenced file. It
 376 invokes the routine only once, passing in the following parameters:
 377 <UL>
 378 <P><LI>The tape device pathname (as specified in the
 379 <B>/usr/afs/backup/tapeconfig</B> file)
 380 <P><LI>The tape operation (always <B>unmount</B>)
 381 </UL>
 382 <P><STRONG>Privilege Required</STRONG>
 383 <P>The file is protected by UNIX mode bits. Creating the file requires
 384 the <B>w</B> (<B>write</B>) and <B>x</B> (<B>execute</B>)
 385 permissions on the <B>/usr/afs/backup</B> directory. Editing the
 386 file requires the <B>w</B> (<B>write</B>) permission on the
 387 file.
 388 <P><STRONG>Examples</STRONG>
 389 <P>The following example configuration files demonstrate one way to structure
 390 a configuration file for a stacker or backup dump file. The examples
 391 are not necessarily appropriate for a specific cell; if using them as
 392 models, be sure to adapt them to the cell's needs and equipment.
 393 <P><B>Example</B> <B>CFG_</B><VAR>device_name</VAR> <B>File for
 394 Stackers</B>
 395 <P>In this example, the administrator creates the following entry for a tape
 396 stacker called <B>stacker0.1</B> in the
 397 <B>/usr/afs/backup/tapeconfig</B> file. It has port offset
 398 0.
 399 <PRE>   2G   5K   /dev/stacker0.1   0
 400
 401 </PRE>
 402 <P>The administrator includes the following five lines in the
 403 <B>/usr/afs/backup/CFG_stacker0.1</B> file. To review the
 404 meaning of each instruction, see the preceding <B>Description</B>
 405 section.
 406 <PRE>   MOUNT /usr/afs/backup/stacker0.1
 407    UNMOUNT /usr/afs/backup/stacker0.1
 408    AUTOQUERY NO
 409    ASK NO
 410    NAME_CHECK NO
 411
 412 </PRE>
 413 <P>Finally, the administrator writes the following executable routine in the
 414 <B>/usr/afs/backup/stacker0.1</B> file referenced by the
 415 <B>MOUNT</B> and <B>UNMOUNT</B> instructions in the
 416 <B>CFG_stacker0.1</B> file.
 417 <PRE>   #! /bin/csh -f
 418
 419    set devicefile = $1
 420    set operation = $2
 421    set tries = $3
 422    set tapename = $4
 423    set tapeid = $5
 424
 425    set exit_continue = 0
 426    set exit_abort = 1
 427    set exit_interactive = 2
 428
 429    #--------------------------------------------
 430
 431    if (${tries} > 1) then
 432       echo "Too many tries"
 433       exit ${exit_interactive}
 434    endif
 435
 436    if (${operation} == "unmount") then
 437       echo "UnMount: Will leave tape in drive"
 438       exit ${exit_continue}
 439    endif
 440
 441    if ((${operation} == "dump")     |\
 442        (${operation} == "appenddump")     |\
 443        (${operation} == "savedb"))  then
 444
 445        stackerCmd_NextTape ${devicefile}
 446        if (${status} != 0)exit${exit_interactive}
 447        echo "Will continue"
 448        exit ${exit_continue}
 449    endif
 450
 451    if ((${operation} == "labeltape")    |\
 452        (${operation} == "readlabel")) then
 453       echo "Will continue"
 454       exit ${exit_continue}
 455    endif
 456
 457    echo "Prompt for tape"
 458    exit ${exit_interactive}
 459
 460 </PRE>
 461 <P>This routine uses two of the parameters passed to it by the Backup
 462 System: <TT>tries</TT> and <TT>operation</TT>. It follows the
 463 recommended practice of prompting for a tape if the value of the
 464 <TT>tries</TT> parameter exceeds one, because that implies that the stacker
 465 is out of tapes.
 466 <P>For a <B>backup dump</B> or <B>backup savedb</B> operation, the
 467 routine calls the example <B>stackerCmd_NextTape</B> function provided by
 468 the stacker's manufacturer. Note that the final lines in the file
 469 return the exit code that prompts the operator to insert a tape; these
 470 lines are invoked when either the stacker cannot load a tape or a the
 471 operation being performed is not one of those explicitly mentioned in the file
 472 (such as a restore operation).
 473 <P><B>Example CFG_</B><VAR>device_name</VAR> <B>File for Dumping to a
 474 Backup Data File</B>
 475 <P>In this example, the administrator creates the following entry for a backup
 476 data file called <B>HSM_device</B> in the
 477 <B>/usr/afs/backup/tapeconfig</B> file. It has port offset
 478 20.
 479 <PRE>   1G   0K   /dev/HSM_device   20
 480
 481 </PRE>
 482 <P>The administrator includes the following lines in the
 483 <B>/usr/afs/backup/CFG_HSM_device</B> file. To review the meaning
 484 of each instruction, see the preceding <B>Description</B> section.
 485 <PRE>   MOUNT /usr/afs/backup/file
 486    FILE YES
 487    ASK NO
 488
 489 </PRE>
 490 <P>Finally, the administrator writes the following executable routine in the
 491 <B>/usr/afs/backup/file</B> file referenced by the <B>MOUNT</B>
 492 instruction in the <B>CFG_HSM_device</B> file, to control how the Tape
 493 Coordinator handles the file.
 494 <PRE>   #! /bin/csh -f
 495    set devicefile = $1
 496    set operation = $2
 497    set tries = $3
 498    set tapename = $4
 499    set tapeid = $5
 500
 501    set exit_continue = 0
 502    set exit_abort = 1
 503    set exit_interactive = 2
 504
 505    #--------------------------------------------
 506
 507    if (${tries} > 1) then
 508       echo "Too many tries"
 509       exit ${exit_interactive}
 510    endif
 511
 512    if (${operation} == "labeltape") then
 513       echo "Won't label a tape/file"
 514       exit ${exit_abort}
 515    endif
 516
 517    if ((${operation} == "dump")   |\
 518        (${operation} == "appenddump")   |\
 519        (${operation} == "restore")   |\
 520        (${operation} == "savedb")    |\
 521        (${operation} == "restoredb")) then
 522
 523       /bin/rm -f ${devicefile}
 524       /bin/ln -s /hsm/${tapename}_${tapeid} ${devicefile}
 525       if (${status} != 0) exit ${exit_abort}
 526    endif
 527
 528    exit ${exit_continue}
 529
 530 </PRE>
 531 <P>Like the example routine for a tape stacker, this routine uses the
 532 <TT>tries</TT> and <TT>operation</TT> parameters passed to it by the
 533 Backup System. The <TT>tries</TT> parameter tracks how many times the
 534 Tape Coordinator has attempted to access the file. A value greater than
 535 one indicates that the Tape Coordinator cannot access it, and the routine
 536 returns exit code 2 (<TT>exit_interactive</TT>), which results in a prompt
 537 for the operator to load a tape. The operator can use this opportunity
 538 to change the name of the backup data file specified in the
 539 <B>tapeconfig</B> file.
 540 <P>The primary function of this routine is to establish a link between the
 541 device file and the file to be dumped or restored. When the Tape
 542 Coordinator is executing a <B>backup dump</B>, <B>backup restore</B>,
 543 <B>backup savedb</B>, or <B>backup restoredb</B> operation, the
 544 routine invokes the UNIX <B>ln -s</B> command to create a symbolic link
 545 from the backup data file named in the <B>tapeconfig</B> file to the
 546 actual file to use (this is the recommended method). It uses the value
 547 of the <TT>tapename</TT> and <TT>tapeid</TT> parameters to construct the
 548 file name.
 549 <P><STRONG>Related Information</STRONG>
 550 <P><A HREF="auarf050.htm#HDRTAPECONFIG">tapeconfig</A>
 551 <P><A HREF="auarf072.htm#HDRBK_DISKRESTORE">backup diskrestore</A>
 552 <P><A HREF="auarf073.htm#HDRBK_DUMP">backup dump</A>
 553 <P><A HREF="auarf085.htm#HDRBK_RESTOREDB">backup restoredb</A>
 554 <P><A HREF="auarf086.htm#HDRBK_SAVEDB">backup savedb</A>
 555 <P><A HREF="auarf091.htm#HDRBK_VOLRESTORE">backup volrestore</A>
 556 <P><A HREF="auarf092.htm#HDRBK_VOLSETRESTORE">backup volsetrestore</A>
 557 <P>
 558 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf017.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="auarf019.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
 559 <!-- Begin Footer Records  ========================================== -->
 560 <P><HR><B>
 561 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
 562 </B>
 563 <!-- End Footer Records  ============================================ -->
 564 <A NAME="Bot_Of_Page"></A>
 565 </BODY></HTML>