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