doc/man-pages/pod8/backup_labeltape.pod

   1 =head1 NAME
   2
   3 backup labeltape - Creates the magnetic label on a tape
   4
   5 =head1 SYNOPSIS
   6
   7 B<backup labeltape> [B<-name> <I<AFS tape name, defaults to NULL>>]
   8     [B<-size> <I<tape size in Kbytes, defaults to size in tapeconfig>>]
   9     [B<-portoffset> <I<TC port offset>>] [B<-pname> <I<permanent tape name>>]
  10     [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
  11
  12 B<backup la> [B<-n> <I<AFS tape name, defaults to NULL>>]
  13     [B<-s> <I<tape size in Kbytes, defaults to size in tapeconfig>>]
  14     [B<-po> <I<TC port offset>>] [B<-pn> <I<permanent tape name>>]
  15     [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
  16
  17 =head1 DESCRIPTION
  18
  19 The B<backup labeltape> command creates a magnetic label, readable by the
  20 Backup System, at the beginning of a tape. The label records the tape's
  21 name (either a I<permanent name>, or an I<AFS tape name> that reflects the
  22 tape's contents in a prescribed format) and its capacity.
  23
  24 (If the C<FILE YES> instruction appears in the
  25 F</usr/afs/backup/CFG_I<device_name>> file on the Tape Coordinator machine
  26 associated with the specified port offset, then the B<backup> command
  27 writes label information to the first 16 KB block in the backup data file
  28 listed for that port offset in the Tape Coordinator's
  29 F</usr/afs/backup/tapeconfig> file, rather than at the beginning of a
  30 tape. For the sake of clarity, the following text refers to tapes only,
  31 but the Backup System handles backup data files in much the same way.)
  32
  33 Relabeling a tape that already contains AFS backup data effectively makes
  34 the data unusable, because the command removes the Backup Database record
  35 of the complete dump set of which the tape is a part. Use this command to
  36 enable recycling of a tape that contains unexpired dumps that are not
  37 actually still needed.
  38
  39 To write a permanent name on the label, include the B<-pname> argument to
  40 specify a string of up to 32 characters. The permanent name persists until
  41 the B<-pname> argument is again included on the B<backup labeltape>
  42 command, regardless of the tape's contents and of how often the tape is
  43 otherwise relabeled or recycled. Include this argument or the B<-name>
  44 argument, but not both. If this argument is included, the AFS tape name is
  45 set to C<< <NULL> >>.  The permanent name is set to C<< <NULL> >> if this
  46 argument is omitted and no permanent name already exists.
  47
  48 The issuer must ensure that a permanent name is unique among the tapes
  49 used for AFS backup in the cell, because the B<backup> command interpreter
  50 does not verify that another tape does not already have the same permanent
  51 name. When a tape has a permanent name, the Backup System uses it instead
  52 of the AFS tape name in most prompts and when referring to the tape in
  53 output from B<backup> commands. The permanent name appears in the C<tape
  54 name> field of the output from the B<backup readlabel> command.
  55
  56 To write an AFS tape name on the label, provide a value for the B<-name>
  57 argument in the required format described in L<OPTIONS>.  Include the
  58 B<-name> argument or the B<-pname> argument, but not both. If this
  59 argument is omitted, the AFS tape name is set to C<< <NULL> >>, but the
  60 Backup System automatically assigns the appropriate name when the tape is
  61 used in a future B<backup dump> or B<backup savedb> operation.  The AFS
  62 tape name appears in the C<AFS tape name> field of the output from the
  63 B<backup readlabel> and B<backup scantape> commands.
  64
  65 The backup command interpreter does not accept the B<-name> argument if
  66 the tape already has a permanent name. To erase a tape's permanent name,
  67 provide a null value to the B<-pname> argument by issuing the following
  68 command:
  69
  70    % backup labeltape -pname ""
  71
  72 To record the tape's capacity on the label, specify a number of kilobytes
  73 as the B<-size> argument. If the argument is omitted the first time a tape
  74 is labeled, the Backup System records the default tape capacity recorded
  75 for the specified port offset in the F</usr/afs/backup/tapeconfig> file on
  76 the Tape Coordinator machine. Subsequently, the value in the size field
  77 persists until the B<-size> argument is again included on the B<backup
  78 labeltape> command.
  79
  80 To determine how much data can be written to a tape during a backup dump
  81 or B<backup savedb> operation, the Tape Coordinator reads the capacity
  82 recorded on the tape's label (or uses the value associated with its port
  83 offset in the F</usr/afs/backup/tapeconfig> file, if the tape was never
  84 labeled). For further description, see the B<backup dump> reference page.
  85
  86 The Tape Coordinator's default response to this command is to access the
  87 tape by invoking the C<MOUNT> instruction in the local
  88 F</usr/afs/backup/CFG_I<device_name>> file, or by prompting the backup
  89 operator to insert the tape if there is no C<MOUNT> instruction. However,
  90 if the C<AUTOQUERY NO> instruction appears in the F<CFG_I<device_name>>
  91 file, or if the issuer of the B<butc> command included the B<-noautoquery>
  92 flag, the Tape Coordinator instead expects the tape to be in the device
  93 already.  If it is not, the Tape Coordinator invokes the C<MOUNT>
  94 instruction or prompts the operator.
  95
  96 =head1 OPTIONS
  97
  98 =over 4
  99
 100 =item B<-name> <I<AFS tape name>>
 101
 102 Specifies the AFS tape name to record on the label. Include this argument
 103 or the B<-pname> argument, but not both. If this argument is omitted, the
 104 AFS tape name is set to C<< <NULL> >>.  If this argument is provided, it
 105 must have the following format:
 106
 107    <volume_set_name>.<dump_level_name>.<tape_index>
 108
 109 for the tape to be acceptable for use in a future backup dump
 110 operation. The <volume_set_name> must match the volume set name of the
 111 initial dump to be written to the tape, <dump_level_name> must match the
 112 last element of the dump level pathname at which the volume set will be
 113 dumped, and <tape_index> indicates the order of the tape in the dump set
 114 (indexing begins with C<1>). To disable this type of name checking,
 115 include the C<NAME_CHECK NO> instruction in the F<CFG_I<device_name>>
 116 file.
 117
 118 For the tape to be acceptable for use in a future backup savedb operation,
 119 the value specified for the B<-name> argument must have the following
 120 format:
 121
 122    Ubik_db_dump.<tape_index>
 123
 124 where <tape_index> indicates the order of the tape in the set of tapes
 125 that house the Backup Database dump; indexing begins with C<1> (one).
 126
 127 =item B<-size> <I<tape size>>
 128
 129 Specifies the tape capacity to record on the label. Provide an integer
 130 value followed by a letter that indicates units, with no intervening
 131 space. A unit value of C<k> or C<K> indicates kilobytes, C<m> or C<M>
 132 indicates megabytes, and C<g> or C<G> indicates gigabytes. If the units
 133 letter is omitted, the default is kilobytes.
 134
 135 If this argument is omitted the first time a tape is labeled, the Backup
 136 System records the capacity that is associated with the specified port
 137 offset in the F</usr/afs/backup/tapeconfig> file on the Tape Coordinator
 138 machine. The value recorded the first time then persists until the
 139 B<-size> argument is provided on a future issuance of the command.
 140
 141 =item B<-portoffset> <I<TC port offset>>
 142
 143 Specifies the port offset number of the Tape Coordinator handling the tape
 144 for this operation.
 145
 146 =item B<-pname> <I<permanent tape name>>
 147
 148 Specifies the permanent name to record on the label. It can be up to 32
 149 characters in length, and include any alphanumeric characters.  Avoid
 150 metacharacters that have a special meaning to the shell, to avoid having
 151 to mark them as literal in commands issued at the shell prompt.
 152
 153 Include this argument or the B<-name> argument, but not both. If this
 154 argument is provided, the AFS tape name is set to C<< <NULL> >>. If this
 155 argument is omitted, any existing permanent name is retained.
 156
 157 =item B<-localauth>
 158
 159 Constructs a server ticket using a key from the local
 160 F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
 161 it to the Backup Server, Volume Server and VL Server during mutual
 162 authentication. Do not combine this flag with the B<-cell> argument. For
 163 more details, see L<backup(8)>.
 164
 165 =item B<-cell> <I<cell name>>
 166
 167 Names the cell in which to run the command. Do not combine this argument
 168 with the B<-localauth> flag. For more details, see L<backup(8)>.
 169
 170 =item B<-help>
 171
 172 Prints the online help for this command. All other valid options are
 173 ignored.
 174
 175 =back
 176
 177 =head1 EXAMPLES
 178
 179 The following command records the AFS tape name C<user.monthly.1> on the
 180 label of the tape in the device with port offset 3:
 181
 182    % backup labeltape -name user.monthly.1 -portoffset 3
 183
 184 The following three commands are equivalent in effect: they all record a
 185 capacity of 2 GB on the label of the tape in the device with port offset
 186 4. They set the AFS tape name to C<< <NULL> >> and leave the permanent
 187 name unchanged.
 188
 189    % backup labeltape -size 2g -portoffset 4
 190    % backup labeltape -size 2048M -portoffset 4
 191    % backup labeltape -size 2097152 -portoffset 4
 192
 193 =head1 PRIVILEGE REQUIRED
 194
 195 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
 196 machine where the Backup Server is running, or must be logged onto a
 197 server machine as the local superuser C<root> if the B<-localauth> flag is
 198 included.
 199
 200 =head1 SEE ALSO
 201
 202 L<butc(5)>,
 203 L<backup(8)>,
 204 L<backup_readlabel(8)>,
 205 L<butc(8)>
 206
 207 =head1 COPYRIGHT
 208
 209 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 210
 211 This documentation is covered by the IBM Public License Version 1.0.  It was
 212 converted from HTML to POD by software written by Chas Williams and Russ
 213 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.