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