doc/man-pages/pod8/backup_scantape.pod

   1 =head1 NAME
   2
   3 backup_scantape - Extracts dump information from a tape
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<backup scantape> [B<-dbadd>] S<<< [B<-portoffset> <I<TC port offset>>] >>>
  11     [B<-localauth>] S<<< [B<-cell> <I<cell name>>] >>> [B<-help>]
  12
  13 B<backup sc> [B<-d>] S<<< [B<-p> <I<TC port offset>>] >>> [B<-l>]
  14     S<<< [B<-c> <I<cell name>>] >>> [B<-h>]
  15
  16 =for html
  17 </div>
  18
  19 =head1 DESCRIPTION
  20
  21 The B<backup scantape> command extracts information from the dump labels
  22 and volume headers on the tape in the device controlled by the Tape
  23 Coordinator indicated by the B<-portoffset> argument. The Tape Coordinator
  24 displays the information for each volume in its window as soon as it
  25 extracts it (rather than waiting until it has scanned the entire tape).
  26
  27 (If the C<FILE YES> instruction appears in the
  28 F</usr/afs/backup/CFG_I<device_name>> file associated with the specified
  29 port offset, then the B<backup scantape> command extracts dump information
  30 from the backup data file named in that port offset's entry in the
  31 F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, rather
  32 than from a tape. For the sake of clarity, the following text refers to
  33 tapes only, but the Backup System handles backup data files in much the
  34 same way.)
  35
  36 If the B<-dbadd> flag is provided, the backup scantape command creates new
  37 dump and volume records in the Backup Database for the scanned
  38 information. However, if it finds that a record already exists in the
  39 database for the same dump, it terminates the scanning operation.
  40
  41 The scanning operation works only on tapes containing volume data.  The
  42 command fails with an error message if the tape contains a copy of the
  43 Backup Database (was created with the B<backup savedb> command, or has the
  44 AFS tape name C<Ubik_db_dump.1>).
  45
  46 The Tape Coordinator's default response to this command is to access the
  47 tape by invoking the C<MOUNT> instruction in the F<CFG_I<device_name>>
  48 file, or by prompting the backup operator to insert the tape if there is
  49 no C<MOUNT> instruction.  However, if the C<AUTOQUERY NO> instruction
  50 appears in the F<CFG_I<device_name>> file, or if the issuer of the B<butc>
  51 command included the B<-noautoquery> flag, the Tape Coordinator instead
  52 expects the tape to be in the device already. If it is not, the Tape
  53 Coordinator invokes the C<MOUNT> instruction or prompts the operator.
  54
  55 To terminate a tape scanning operation in interactive mode, issue the
  56 B<backup kill> command. In noninteractive mode, the only choice is to use
  57 a termination signal such as Ctrl-C to halt the Tape Coordinator
  58 completely.
  59
  60 =head1 CAUTIONS
  61
  62 A scanning operation does not have to begin with the first tape in a dump
  63 set, but the Backup System can process tapes only in sequential order
  64 after the initial tape provided. The Tape Coordinator automatically
  65 requests any subsequent tapes by invoking the C<MOUNT> instruction in the
  66 local F</usr/afs/backup/CFG_I<device_name>> file, or by prompting the
  67 operator if there is no C<MOUNT> instruction.
  68
  69 The Tape Coordinator's success in scanning a tape that is corrupted or
  70 damaged depends on the extent of the damage and what type of data is
  71 corrupted. It can almost always scan the tape successfully up to the point
  72 of damage. If the damage is minor, the Tape Coordinator can usually skip
  73 over it and scan the rest of the tape, but more major damage can prevent
  74 further scanning. Because a scanning operation can start on any tape in a
  75 dump set, damage on one tape does not prevent scanning of the others in
  76 the dump set. However, it is possible to scan either the tapes that
  77 precede the damaged one or the ones that follow it, but not both.
  78
  79 If a tape is relabeled with the backup labeltape command, it is not
  80 possible to recover data from it for the purposes of rebuilding the Backup
  81 Database.
  82
  83 If the B<-dbadd> flag is included on the command, it is best not to
  84 terminate the tape scanning operation before it completes (for example, by
  85 issuing the B<backup kill> command in interactive mode). The Backup System
  86 writes a new record in the Backup Database for each dump as soon as it
  87 scans the relevant information on the tape, and so it possibly has already
  88 written new records. If the operator wants to rerun the scanning
  89 operation, he or she must locate and remove the records created during the
  90 terminated operation: the second operation exits automatically if it finds
  91 that a record that it needs to create already exists.
  92
  93 If the B<-dbadd> flag is included and the first tape provided is not the
  94 first tape in the dump set, the following restrictions apply:
  95
  96 =over 4
  97
  98 =item *
  99
 100 If the first data on the tape is a continuation of a volume that begins on
 101 the previous (unscanned) tape in the dump set, the Backup System does not
 102 add a record for that volume to the Backup Database.
 103
 104 =item *
 105
 106 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 first
 108 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
 111 that appended dump.
 112
 113 =back
 114
 115 =head1 OPTIONS
 116
 117 =over 4
 118
 119 =item B<-dbadd>
 120
 121 Adds the information extracted from the tape to the Backup Database (but
 122 only if the database does not already contain an entry with the same dump
 123 ID number).
 124
 125 =item B<-portoffset> <I<TC port offset>>
 126
 127 Specifies the port offset number of the Tape Coordinator handling the
 128 tapes for this operation.
 129
 130 =item B<-localauth>
 131
 132 Constructs a server ticket using a key from the local
 133 F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
 134 it to the Backup Server, Volume Server and VL Server during mutual
 135 authentication. Do not combine this flag with the B<-cell> argument. For
 136 more details, see L<backup(8)>.
 137
 138 =item B<-cell> <I<cell name>>
 139
 140 Names the cell in which to run the command. Do not combine this argument
 141 with the B<-localauth> flag. For more details, see L<backup(8)>.
 142
 143 =item B<-help>
 144
 145 Prints the online help for this command. All other valid options are
 146 ignored.
 147
 148 =back
 149
 150 =head1 OUTPUT
 151
 152 For every dump on a tape, the backup scantape command displays in the Tape
 153 Coordinator window the dump label and the volume header of each volume in
 154 the dump. If a dump spans more than one tape, the dump label does not
 155 repeat at the beginning of subsequent tapes.
 156
 157 A dump label contains the following fields, which are the same as in the
 158 output from the B<backup readlabel> command:
 159
 160 =over 4
 161
 162 =item tape name
 163
 164 The permanent name assigned by using the B<-pname> argument of the
 165 B<backup labeltape> command. This name remains on the tape until that
 166 argument is used again, no matter how many times the tape is recycled or
 167 otherwise relabeled. If the tape does not have a permanent name, the value
 168 C<< <NULL> >> appears in this field.
 169
 170 =item AFS tape name
 171
 172 A tape name in one of the following prescribed formats. The Backup System
 173 automatically writes the appropriate AFS tape name to the label as part of
 174 a B<backup dump> operation, or the operator can assign it with the
 175 B<-name> argument to the B<backup labeltape> command.
 176
 177 =over 4
 178
 179 =item *
 180
 181 I<volume_set_name>.I<dump_level_name>.I<tape_index>, if the tape contains
 182 volume data. The I<volume_set_name> is the name of the volume set that was
 183 dumped to create the initial dump in the dump set of which this tape is a
 184 part; I<dump_level_name> is the last pathname element of the dump level at
 185 which the initial dump was backed up; and I<tape_index> is the numerical
 186 position of the tape in the dump set.
 187
 188 =item *
 189
 190 C<< <NULL> >> if the tape has no AFS tape name. This is normally the case
 191 if the B<-name> argument was not included the last time the B<backup
 192 labeltape> command was used on this tape, and no data has been written to
 193 it since.
 194
 195 =back
 196
 197 =item creationTime
 198
 199 The date and time at which the Backup System started performing the dump
 200 operation that created the initial dump.
 201
 202 =item cell
 203
 204 The cell in which the dump set was created. This is the cell whose Backup
 205 Database contains a record of the dump set.
 206
 207 =item size
 208
 209 The tape's capacity (in kilobytes) as recorded on the label, rather than
 210 the amount of data on the tape. The value is assigned by the B<-size>
 211 argument to the B<backup labeltape> command or derived from the
 212 F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, not
 213 from a measurement of the tape.
 214
 215 =item dump path
 216
 217 The dump level of the initial dump in the dump set.
 218
 219 =item dump id
 220
 221 The dump ID number of the initial dump in the dump set, as recorded in the
 222 Backup Database.
 223
 224 =item useCount
 225
 226 The number of times a dump has been written to the tape, or it has been
 227 relabeled.
 228
 229 =back
 230
 231 The volume header contains the following fields:
 232
 233 =over 4
 234
 235 =item volume name
 236
 237 The volume name, complete with a C<.backup> or C<.readonly> extension, if
 238 appropriate.
 239
 240 =item volume ID
 241
 242 The volume's volume ID.
 243
 244 =item dumpSetName
 245
 246 The dump to which the volume belongs. The dump name is of the form
 247 I<volume_set_name>.I<dump_level_name> and matches the name displayed in
 248 the dump label.
 249
 250 =item dumpID
 251
 252 The dump ID of the dump named in the C<dumpSetName> field.
 253
 254 =item level
 255
 256 The depth in the dump hierarchy of the dump level used in creating the
 257 dump. A value of C<0> indicates a full dump. A value of C<1> or greater
 258 indicates an incremental dump made at the indicated depth in the
 259 hierarchy. The value reported is for the entire dump, not necessarily for
 260 the volume itself; for example, it is possible for a dump performed at an
 261 incremental level to include a full dump of an individual volume if the
 262 volume was omitted from previous dumps.
 263
 264 =item parentID
 265
 266 The dump ID number of C<dumpSetName>'s parent dump. It is C<0> if the
 267 value in the C<level> field is C<0>.
 268
 269 =item endTime
 270
 271 Is always C<0>; it is reserved for internal use.
 272
 273 =item cloneDate
 274
 275 The date and time at which the volume was created. For a backup or
 276 read-only volume, this represents the time at which it was cloned from its
 277 read/write source. For a read/write volume, it indicates the time at which
 278 the Backup System locked the volume for purposes of including it in the
 279 dump named in the C<dumpSetName> field.
 280
 281 =back
 282
 283 The message C<Scantape: Finished> indicates the completion of the output.
 284
 285 In normal circumstances, the Backup System writes a marker to indicate
 286 that a volume is the last one on a tape, or that the volume continues on
 287 the next tape. However, if a backup operation terminated abnormally (for
 288 example, because the operator terminated the Tape Coordinator by issuing
 289 the Ctrl-C command during the operation), then there is no such
 290 marker. Some very early versions of the Backup System also did not write
 291 these markers. If a tape does not conclude with one of the expected
 292 markers, the Tape Coordinator cannot determine if there is a subsequent
 293 tape in the dump set and so generates the following message in its window:
 294
 295    Are there more tapes? (y/n)
 296
 297 =head1 EXAMPLES
 298
 299 The following example shows the output for the first two volumes on a tape
 300 in the device with port offset 0:
 301
 302    % backup scantape
 303    Dump label
 304    ----------
 305    tape name = monthly_guest
 306    AFS tape name = guests.monthly.3
 307    creationTime =  Mon Feb  1 04:06:40 1999
 308    cell = abc.com
 309    size = 2150000 Kbytes
 310    dump path = /monthly
 311    dump id = 917860000
 312    useCount = 44
 313    -- End of dump label --
 314    -- volume --
 315    volume name: user.guest10.backup
 316    volume ID 1937573829
 317    dumpSetName: guests.monthly
 318    dumpID 917860000
 319    level 0
 320    parentID 0
 321    endTime 0
 322    clonedate Mon Feb  1 03:03:23 1999
 323    -- volume --
 324    volume name: user.guest11.backup
 325    volume ID 1938519386
 326    dumpSetName: guests.monthly
 327    dumpID 917860000
 328    level 0
 329    parentID 0
 330    endTime 0
 331    clonedate Mon Feb  1 03:05:15 1999
 332
 333 =head1 PRIVILEGE REQUIRED
 334
 335 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
 336 machine where the Backup Server is running, or must be logged onto a
 337 server machine as the local superuser C<root> if the B<-localauth> flag is
 338 included.
 339
 340 =head1 SEE ALSO
 341
 342 L<butc(5)>,
 343 L<backup(8)>,
 344 L<backup_dump(8)>,
 345 L<backup_dumpinfo(8)>,
 346 L<butc(8)>
 347
 348 =head1 COPYRIGHT
 349
 350 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 351
 352 This documentation is covered by the IBM Public License Version 1.0.  It was
 353 converted from HTML to POD by software written by Chas Williams and Russ
 354 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.