Writing and Reading Tape Labels

Writing and Reading Tape Labels
	Chapter 6. Configuring the AFS Backup System

As described in Dump Names and Tape Names and Tape Labels, Dump Labels, and EOF Markers, you can assign either a permanent name or an AFS tape name to a tape that you use in the Backup System. The names are recorded on the tape's magnetic label, along with an indication of the tape's capacity (size).

You can assign either a permanent name or an AFS tape name, but not both. In general, assigning permanent names rather than AFS tape names simplifies the backup process, because the Backup System does not dictate the format of permanent names. If a tape does not have a permanent name, then by default the Backup System accepts only three strictly defined values in the AFS tape name field, and refuses to write a dump to a tape with an inappropriate AFS tape name. The acceptable values are a name that matches the volume set and dump level of the initial dump, the value <NULL>, and no value in the field at all.

If a tape has a permanent name, the Backup System does not check the AFS tape name, and as part of the dump operation constructs the appropriate AFS tape name itself and records it on the label. This means that if you assign a permanent name, the Backup System assigns an AFS tape name itself and the tape has both types of name. In contrast, if a tape has an AFS tape name but not a permanent name, you cannot assign a permanent name without first erasing the AFS tape name.

(You can also suppress the Backup System's check of a tape's AFS tape name, even it does not have a permanent name, by assigning the value NO to the NAME_CHECK instruction in the device configuration file. See Eliminating the AFS Tape Name Check.)

Because the Backup System accepts unlabeled tapes, you do not have to label a tape before using it for the first time. After the first use, there are a couple of cases in which you must relabel a tape in order to write a dump to it:

The tape does not have a permanent name, and the AFS tape name on it does not match the new initial dump set you want to create (the volume set and dump level names are different, or the index is incorrect).
You want to recycle a tape before all of the dumps on it have expired. The Backup System does not overwrite a tape with any unexpired dumps. Keep in mind, though, that if you relabel the tape to making recycling possible, you erase all the dump records for the tape from the Backup Database, which makes it impossible to restore any data from the tape.

Note

Labeling a tape that contains dump data makes it impossible to use that data in a restore operation, because the labeling operation removes the dump's records from the Backup Database. If you want to record a permanent name on a tape label, you must do it before dumping any data to the tape.

Recording a Name on the Label

To write a permanent name on a tape's label, include the -pname argument to specify a string of up to 32 characters. Check that no other tape used with the Backup System in your cell already has the permanent name you are assigning, because the Backup System does not prevent you from assigning the same name to multiple tapes. The Backup System overwrites the existing AFS tape name, if any, with the value <NULL>. When a tape has a permanent name, the Backup System uses it instead of the AFS tape name in most prompts and when referring to the tape in output from backup commands. The permanent name persists until you again include the -pname argument to the backup labeltape command, regardless of the tape's contents and of how often you recycle the tape or use the backup labeltape command without the -pname argument.

To write an AFS tape name on the label, provide a value for the -name argument that matches the volume set name and the final element in the dump level pathname of the initial dump that you plan to write to the tape, and an index that indicates the tape's place in the sequence of tapes for the dump set. The format is as follows:

   volume_set_name.dump_level_name.tape_index

If you omit the -name argument, the Backup System sets the AFS tape name to <NULL>. The Backup System automatically constructs and records the appropriate name when you later write an initial dump to the tape by using the backup dump or backup savedb command.

You cannot use the -name argument if the tape already has a permanent name. To erase a tape's permanent name, provide a null value to the -pname argument by issuing the following command:

   % backup labeltape -pname ""

Recording a Capacity on the Label

To record the tape's capacity on the label, specify a number of kilobytes as the -size argument. If you omit this argument the first time you label a tape, the Backup System records the default tape capacity associated with the specified port offset in the /usr/afs/backup/tapeconfig file on the Tape Coordinator machine. If the tape's capacity is different (in particular, larger) than the capacity recorded in the tapeconfig file, it is best to record a capacity on the label before using the tape. Once set, the value in the label's capacity field persists until you again use the -size argument to the backup labeltape command. For a discussion of the appropriate capacity to record for tapes, see Configuring the tapeconfig File.

To read a tape's label, use the backup readlabel command.

Most tapes also come with an adhesive label you can apply to the exterior casing. To help you easily identify a tape, record at least the tape's permanent and AFS tape names on the adhesive label. Depending on the recycling scheme you use, it can be useful to record other information, such as the dump ID, dump creation date, and expiration date of each dump you write to the tape.

To label a tape

Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a connection to the appropriate Tape Coordinator machine and issue the butc command, for which complete instructions appear in To start a Tape Coordinator process.
```
   % butc [<port offset>] [-noautoquery]
```
Place the tape in the device.
Optional. Issue the backup command to enter interactive mode, if you want to label multiple tapes or issue additional commands after labeling the tape. The interactive prompt appears in the following step.
```
   % backup
```
Issue the (backup) labeltape command to label the tape.
```
   backup> labeltape [-name <tape name, defaults to NULL>]  \
      [-size <tape size in Kbytes, defaults to size in tapeconfig>]  \
      [-portoffset <TC port offset>] [-pname <permanent tape name>]
```
where
la
Is the shortest acceptable abbreviation of labeltape.
-name
Specifies the AFS tape name to record on the label. Include this argument or the -pname argument, but not both. If you omit this argument, the AFS tape name is set to <NULL>. If you provide it, it must have the following format.
```
volume_set_name.dump_level_name.tape_index
```
for the tape to be acceptable for use in a future backup dump operation. The volume_set_name must match the volume set name of the initial dump to be written to the tape, dump_level_name must match the last element of the dump level pathname at which the volume set is to be dumped, and tape_index must correctly indicate the tape's place in the sequence of tapes that house the dump set; indexing begins with the number 1 (one).
-size
Specifies the tape capacity to record on the label. If you are labeling the tape for the first time, you need to include this argument only if the tape's capacity differs from the capacity associated with the specified port offset in the /usr/afs/backup/tapeconfig file on the Tape Coordinator machine.
If you provide a value, it is an integer value followed by a letter that indicates units, with no intervening space. A unit value of k or K indicates kilobytes, m or M indicates megabytes, and g or G indicates gigabytes. If you omit the units letter, the default is kilobytes.
-portoffset
Specifies the port offset number of the Tape Coordinator handling the tape or backup data file for this operation. You must provide this argument unless the default value of 0 (zero) is appropriate.
-pname
Specifies the permanent name to record on the label. It can be up to 32 characters in length, and include any alphanumeric characters. Avoid metacharacters that have a special meaning to the shell, to avoid having to mark them as literal in commands issued at the shell prompt.
Include this argument or the -name argument, but not both. When you provide this argument, the AFS tape name is set to <NULL>. If you omit this argument, any existing permanent name is retained.
If you did not include the -noautoquery flag when you issued the butc command, or if the device's device configuration file includes the instruction AUTOQUERY YES, then the Tape Coordinator prompts you to place the tape in the device's drive. You have already done so, but you must now press <Return> to indicate that the tape is ready for labeling.

To read the label on a tape

Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a connection to the appropriate Tape Coordinator machine and issue the butc command, for which complete instructions appear in To start a Tape Coordinator process.
```
   % butc [<port offset>] [-noautoquery]
```
Place the tape in the device.
Optional. Issue the backup command to enter interactive mode, if you want to label multiple tapes or issue additional commands after labeling the tape. The interactive prompt appears in the following step.
```
   % backup
```
Issue the (backup) readlabel command to read the label on the tape.
```
   backup> readlabel [<TC port offset>]
```
where
rea
Is the shortest acceptable abbreviation of readlabel.
TC port offset
Specifies the port offset number of Tape Coordinator handling the tape or backup data file for this operation. You must provide this argument unless the default value of 0 (zero) is appropriate.
If you did not include the -noautoquery flag when you issued the butc command, or the device's device configuration file includes the instruction AUTOQUERY YES instruction, then the Tape Coordinator prompts you to place the tape in the device's drive. You have already done so, but you must now press <Return> to indicate that the tape is ready for reading.

Information from the tape label appears both in the backup command window and in the Tape Coordinator window. The output in the command window has the following format:

   Tape read was labelled: tape_name (initial_dump_ID)
        size: size KBytes

where tape_name is the tape's permanent name (if it has one) or AFS tape name, initial_dump_ID is the dump ID of the initial dump on the tape, and size is the capacity recorded on the label, in kilobytes.

The information in the Tape Coordinator window is more extensive. The tape's permanent name appears in the tape name field and its AFS tape name in the AFS tape name field. If either name is undefined, a value of <NULL> appears in the field instead. The capacity recorded on the label appears in the size field. Other fields in the output report the creation time, dump level name, and dump ID of the initial dump on the tape (creationTime, dump path, and dump id respectively). The cell field reports the cell in which the dump operation was performed, and the useCount field reports the number of times the tape has been relabeled, either with the backup labeltape command or during a dump operation. For further details, see the command's reference page in the OpenAFS Administration Reference.

If the tape has no label, or if the drive is empty, the following message appears at the command shell:

   Failed to read tape label.

The following example illustrates the output in the command shell for a tape in the device with port offset 1:

   % backup readlabel 1
   Tape read was labelled: monthly_guest (917860000)
        size: 2150000 KBytes

The following output appears in the Tape Coordinator window at the same time:

   Tape label
   ----------
   tape name = monthly_guest
   AFS tape name = guests.monthly.3
   creationTime =  Mon Feb  1 04:06:40 1999
   cell = example.com
   size = 2150000 Kbytes
   dump path = /monthly
   dump id = 917860000
   useCount = 44
   -- End of tape label --


Defining and Displaying the Dump Hierarchy		Automating and Increasing the Efficiency of the Backup Process