doc/html/AdminReference/auarf087.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="auarf086.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="auarf088.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="HDRBK_SCANTAPE" HREF="auarf002.htm#ToC_101">backup scantape</A></H2>
  19 <A NAME="IDX4400"></A>
  20 <A NAME="IDX4401"></A>
  21 <A NAME="IDX4402"></A>
  22 <A NAME="IDX4403"></A>
  23 <A NAME="IDX4404"></A>
  24 <A NAME="IDX4405"></A>
  25 <P><STRONG>Purpose</STRONG>
  26 <P>Extracts dump information from a tape
  27 <P><STRONG>Synopsis</STRONG>
  28 <PRE><B>backup scantape</B> [<B>-dbadd</B>]  [<B>-portoffset</B> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]
  29                 [<B>-localauth</B>]  [<B>-cell</B> &lt;<VAR>cell&nbsp;name</VAR>>]  [<B>-help</B>]
  30
  31 <B>backup sc</B> [<B>-d</B>]  [<B>-p</B> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]  [<B>-l</B>]  [<B>-c</B> &lt;<VAR>cell&nbsp;name</VAR>>]  [<B>-help</B>]
  32 </PRE>
  33 <P><STRONG>Description</STRONG>
  34 <P>The <B>backup scantape</B> command extracts information from the dump
  35 labels and volume headers on the tape in the device controlled by the Tape
  36 Coordinator indicated by the <B>-portoffset</B> argument. The Tape
  37 Coordinator displays the information for each volume in its window as soon as
  38 it extracts it (rather than waiting until it has scanned the entire
  39 tape).
  40 <P>(If the <B>FILE YES</B> instruction appears in the
  41 <B>/usr/afs/backup/CFG_</B><VAR>device_name</VAR> file associated with the
  42 specified port offset, then the <B>backup scantape</B> command extracts
  43 dump information from the backup data file named in that port offset's
  44 entry in the <B>/usr/afs/backup/tapeconfig</B> file on the Tape
  45 Coordinator machine, rather than from a tape. For the sake of clarity,
  46 the following text refers to tapes only, but the Backup System handles backup
  47 data files in much the same way.)
  48 <P>If the <B>-dbadd</B> flag is provided, the <B>backup scantape</B>
  49 command creates new dump and volume records in the Backup Database for the
  50 scanned information. However, if it finds that a record already exists
  51 in the database for the same dump, it terminates the scanning
  52 operation.
  53 <P>The scanning operation works only on tapes containing volume data.
  54 The command fails with an error message if the tape contains a copy of the
  55 Backup Database (was created with the <B>backup savedb</B> command, or has
  56 the AFS tape name <B>Ubik_db_dump.1</B>).
  57 <P>The Tape Coordinator's default response to this command is to access
  58 the tape by invoking the <B>MOUNT</B> instruction in the
  59 <B>CFG_</B><VAR>device_name</VAR> file, or by prompting the backup operator
  60 to insert the tape if there is no <B>MOUNT</B> instruction.
  61 However, if the <B>AUTOQUERY NO</B> instruction appears in the
  62 <B>CFG_</B><VAR>device_name</VAR> file, or if the issuer of the
  63 <B>butc</B> command included the <B>-noautoquery</B> flag, the Tape
  64 Coordinator instead expects the tape to be in the device already. If it
  65 is not, the Tape Coordinator invokes the <B>MOUNT</B> instruction or
  66 prompts the operator.
  67 <P>To terminate a tape scanning operation in interactive mode, issue the
  68 <B>(backup) kill</B> command. In noninteractive mode, the only
  69 choice is to use a termination signal such as &lt;<B>Ctrl-c</B>> to halt
  70 the Tape Coordinator completely.
  71 <P><STRONG>Cautions</STRONG>
  72 <P>A scanning operation does not have to begin with the first tape in a dump
  73 set, but the Backup System can process tapes only in sequential order after
  74 the initial tape provided. The Tape Coordinator automatically requests
  75 any subsequent tapes by invoking the <B>MOUNT</B> instruction in the local
  76 <B>/usr/afs/backup/CFG_</B><VAR>device_name</VAR> file, or by prompting the
  77 operator if there is no <B>MOUNT</B> instruction.
  78 <P>The Tape Coordinator's success in scanning a tape that is corrupted or
  79 damaged depends on the extent of the damage and what type of data is
  80 corrupted. It can almost always scan the tape successfully up to the
  81 point of damage. If the damage is minor, the Tape Coordinator can
  82 usually skip over it and scan the rest of the tape, but more major damage can
  83 prevent further scanning. Because a scanning operation can start on any
  84 tape in a dump set, damage on one tape does not prevent scanning of the others
  85 in the dump set. However, it is possible to scan either the tapes that
  86 precede the damaged one or the ones that follow it, but not both.
  87 <P>If a tape is relabeled with the <B>backup labeltape</B> command, it is
  88 not possible to recover data from it for the purposes of rebuilding the Backup
  89 Database.
  90 <P>If the <B>-dbadd</B> flag is included on the command, it is best not to
  91 terminate the tape scanning operation before it completes (for example, by
  92 issuing the <B>(backup) kill</B> command in interactive mode). The
  93 Backup System writes a new record in the Backup Database for each dump as soon
  94 as it scans the relevant information on the tape, and so it possibly has
  95 already written new records. If the operator wants to rerun the
  96 scanning operation, he or she must locate and remove the records created
  97 during the terminated operation: the second operation exits
  98 automatically if it finds that a record that it needs to create already
  99 exists.
 100 <P>If the <B>-dbadd</B> flag is included and the first tape provided is
 101 not the first tape in the dump set, the following restrictions apply:
 102 <UL>
 103 <P><LI>If the first data on the tape is a continuation of a volume that begins on
 104 the previous (unscanned) tape in the dump set, the Backup System does not add
 105 a record for that volume to the Backup Database.
 106 <P><LI>The Backup System must read the marker that indicates the start of an
 107 appended dump to add database records for the volumes in it. If the
 108 first volume on the tape belongs to an appended dump, but is not immediately
 109 preceded by the appended-dump marker, the Backup System does not create a
 110 Backup Database record for it or any subsequent volumes that belong to that
 111 appended dump.
 112 </UL>
 113 <P><STRONG>Options</STRONG>
 114 <DL>
 115 <P><DT><B>-dbadd
 116 </B><DD>Adds the information extracted from the tape to the Backup Database (but
 117 only if the database does not already contain an entry with the same dump ID
 118 number).
 119 <P><DT><B>-portoffset
 120 </B><DD>Specifies the port offset number of the Tape Coordinator handling the
 121 tapes for this operation.
 122 <P><DT><B>-localauth
 123 </B><DD>Constructs a server ticket using a key from the local
 124 <B>/usr/afs/etc/KeyFile</B> file. The <B>backup</B> command
 125 interpreter presents it to the Backup Server, Volume Server and VL Server
 126 during mutual authentication. Do not combine this flag with the
 127 <B>-cell</B> argument. For more details, see the introductory
 128 <B>backup</B> reference page.
 129 <P><DT><B>-cell
 130 </B><DD>Names the cell in which to run the command. Do not combine this
 131 argument with the <B>-localauth</B> flag. For more details, see the
 132 introductory <B>backup</B> reference page.
 133 <P><DT><B>-help
 134 </B><DD>Prints the online help for this command. All other valid options
 135 are ignored.
 136 </DL>
 137 <P><STRONG>Output</STRONG>
 138 <P>For every dump on a tape, the <B>backup scantape</B> command displays
 139 in the Tape Coordinator window the dump label and the volume header of each
 140 volume in the dump. If a dump spans more than one tape, the dump label
 141 does not repeat at the beginning of subsequent tapes.
 142 <P>A dump label contains the following fields, which are the same as in the
 143 output from the <B>backup readlabel</B> command:
 144 <DL>
 145 <P><DT><B><TT>tape name</TT><TT></TT>
 146 </B><DD>The permanent name assigned by using the <B>-pname</B> argument of the
 147 <B>backup labeltape</B> command. This name remains on the tape
 148 until that argument is used again, no matter how many times the tape is
 149 recycled or otherwise relabeled. If the tape does not have a permanent
 150 name, the value <TT>&lt;NULL></TT> appears in this field.
 151 <P><DT><B><TT>AFS tape name</TT>
 152 </B><DD>A tape name in one of the following prescribed formats. The Backup
 153 System automatically writes the appropriate AFS tape name to the label as part
 154 of a <B>backup dump</B> operation, or the operator can assign it with the
 155 <B>-name</B> argument to the <B>backup labeltape</B> command.
 156 <UL>
 157 <P><LI><VAR>volume_set_name</VAR>.<VAR>dump_level_name</VAR>.<VAR>tape
 158 _index</VAR>, if the tape contains volume data. The
 159 <VAR>volume_set_name</VAR> is the name of the volume set that was dumped to
 160 create the initial dump in the dump set of which this tape is a part;
 161 <VAR>dump_level_name</VAR> is the last pathname element of the dump level at
 162 which the initial dump was backed up; and <VAR>tape_index</VAR> is the
 163 numerical position of the tape in the dump set.
 164 <P><LI><TT>&lt;NULL></TT> if the tape has no AFS tape name. This is
 165 normally the case if the <B>-name</B> argument was not included the last
 166 time the <B>backup labeltape</B> command was used on this tape, and no
 167 data has been written to it since.
 168 </UL>
 169 <P><DT><B><TT>creationTime</TT>
 170 </B><DD>The date and time at which the Backup System started performing the dump
 171 operation that created the initial dump.
 172 <P><DT><B><TT>cell</TT>
 173 </B><DD>The cell in which the dump set was created. This is the cell whose
 174 Backup Database contains a record of the dump set.
 175 <P><DT><B><TT>size</TT>
 176 </B><DD>The tape's capacity (in kilobytes) as recorded on the label, rather
 177 than the amount of data on the tape. The value is assigned by the
 178 <B>-size</B> argument to the <B>backup labeltape</B> command or
 179 derived from the <B>/usr/afs/backup/tapeconfig</B> file on the Tape
 180 Coordinator machine, not from a measurement of the tape.
 181 <P><DT><B><TT>dump</TT> <TT>path</TT>
 182 </B><DD>The dump level of the initial dump in the dump set.
 183 <P><DT><B><TT>dump</TT> <TT>id</TT>
 184 </B><DD>The dump ID number of the initial dump in the dump set, as recorded in the
 185 Backup Database.
 186 <P><DT><B><TT>useCount</TT>
 187 </B><DD>The number of times a dump has been written to the tape, or it has been
 188 relabeled.
 189 </DL>
 190 <P>The volume header contains the following fields:
 191 <DL>
 192 <P><DT><B><TT>volume</TT> <TT>name</TT>
 193 </B><DD>The volume name, complete with a <TT>.backup</TT> or
 194 <TT>.readonly</TT> extension, if appropriate.
 195 <P><DT><B><TT>volume</TT> <TT>ID</TT>
 196 </B><DD>The volume's volume ID.
 197 <P><DT><B><TT>dumpSetName</TT>
 198 </B><DD>The dump to which the volume belongs. The dump name is of the form
 199 <VAR>volume_set_name</VAR><B>.</B><VAR>dump_level_name</VAR> and
 200 matches the name displayed in the dump label.
 201 <P><DT><B><TT>dumpID</TT>
 202 </B><DD>The dump ID of the dump named in the <TT>dumpSetName</TT> field.
 203 <P><DT><B><TT>level</TT>
 204 </B><DD>The depth in the dump hierarchy of the dump level used in creating the
 205 dump. A value of <TT>0</TT> indicates a full dump. A value of
 206 <TT>1</TT> or greater indicates an incremental dump made at the indicated
 207 depth in the hierarchy. The value reported is for the entire dump, not
 208 necessarily for the volume itself; for example, it is possible for a dump
 209 performed at an incremental level to include a full dump of an individual
 210 volume if the volume was omitted from previous dumps.
 211 <P><DT><B><TT>parentID</TT>
 212 </B><DD>The dump ID number of <TT>dumpSetName</TT>'s parent dump. It
 213 is <TT>0</TT> if the value in the <TT>level</TT> field is
 214 <TT>0</TT>.
 215 <P><DT><B><TT>endTime</TT>
 216 </B><DD>Is always <TT>0</TT>; it is reserved for internal use.
 217 <P><DT><B><TT>cloneDate</TT>
 218 </B><DD>The date and time at which the volume was created. For a backup or
 219 read-only volume, this represents the time at which it was cloned from its
 220 read/write source. For a read/write volume, it indicates the time at
 221 which the Backup System locked the volume for purposes of including it in the
 222 dump named in the <TT>dumpSetName</TT> field.
 223 </DL>
 224 <P>The message <TT>Scantape: Finished</TT> indicates the completion of
 225 the output.
 226 <P>In normal circumstances, the Backup System writes a marker to indicate that
 227 a volume is the last one on a tape, or that the volume continues on the next
 228 tape. However, if a backup operation terminated abnormally (for
 229 example, because the operator terminated the Tape Coordinator by issuing the
 230 &lt;<B>Ctrl-c</B>> command during the operation), then there is no such
 231 marker. Some very early versions of the Backup System also did not
 232 write these markers. If a tape does not conclude with one of the
 233 expected markers, the Tape Coordinator cannot determine if there is a
 234 subsequent tape in the dump set and so generates the following message in its
 235 window:
 236 <PRE>   Are there more tapes? (y/n)
 237
 238 </PRE>
 239 <P><STRONG>Examples</STRONG>
 240 <P>The following example shows the output for the first two volumes on a tape
 241 in the device with port offset 0:
 242 <PRE>   % <B>backup scantape</B>
 243    Dump label
 244    ----------
 245    tape name = monthly_guest
 246    AFS tape name = guests.monthly.3
 247    creationTime =  Mon Feb  1 04:06:40 1999
 248    cell = abc.com
 249    size = 2150000 Kbytes
 250    dump path = /monthly
 251    dump id = 917860000
 252    useCount = 44
 253    -- End of dump label --
 254    -- volume --
 255    volume name: user.guest10.backup
 256    volume ID 1937573829
 257    dumpSetName: guests.monthly
 258    dumpID 917860000
 259    level 0
 260    parentID 0
 261    endTime 0
 262    clonedate Mon Feb  1 03:03:23 1999
 263    -- volume --
 264    volume name: user.guest11.backup
 265    volume ID 1938519386
 266    dumpSetName: guests.monthly
 267    dumpID 917860000
 268    level 0
 269    parentID 0
 270    endTime 0
 271    clonedate Mon Feb  1 03:05:15 1999
 272
 273 </PRE>
 274 <P><STRONG>Privilege Required</STRONG>
 275 <P>The issuer must be listed in the <B>/usr/afs/etc/UserList</B> file on
 276 every machine where the Backup Server is running, or must be logged onto a
 277 server machine as the local superuser <B>root</B> if the
 278 <B>-localauth</B> flag is included.
 279 <P><STRONG>Related Information</STRONG>
 280 <P><A HREF="auarf060.htm#HDRBK_INTRO">backup</A>
 281 <P><A HREF="auarf073.htm#HDRBK_DUMP">backup dump</A>
 282 <P><A HREF="auarf074.htm#HDRBK_DUMPINFO">backup dumpinfo</A>
 283 <P><A HREF="auarf126.htm#HDRBUTC">butc</A>
 284 <P>
 285 <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="auarf086.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="auarf088.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>
 286 <!-- Begin Footer Records  ========================================== -->
 287 <P><HR><B>
 288 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
 289 </B>
 290 <!-- End Footer Records  ============================================ -->
 291 <A NAME="Bot_Of_Page"></A>
 292 </BODY></HTML>