Configuring the tapeconfig File

Several factors interact to determine how much data the Tape Coordinator can fit on a tape:

(The amount of data that can fit in a backup data file is determined by amount of space available on the partition, and the operating system's maximum file size. The Tape Coordinator does not write filemarks when writing to a backup data file. For further information about configuring a Tape Coordinator to write to a backup data file, see Dumping Data to a Backup Data File.)

As the Tape Coordinator (butc) process initializes, it reads the /usr/afs/backup/tapeconfig file on its local disk to learn the tape capacity and filemark size (for a tape device) or the file size (for a backup data file) to use for dump operations. When you begin a dump operation, the Tape Coordinator also reads the tape or backup data file's label to see if you have recorded a different tape capacity or file size. If you have, the value on the label overrides the default value from the tapeconfig file.

As the Tape Coordinator writes data to a tape during a dump operation, it uses the capacity and filemark information to track how much tape it has used and how much remains before the physical end-of-tape (EOT). Shortly before reaching EOT, the Tape Coordinator stops writing and requests a new tape. Similarly, it uses a backup data file's size to know when it is about to exhaust the space in the file. If the Tape Coordinator reaches the EOT unexpectedly, it recovers by obtaining a new tape and writing to it the entire contents of the volume it was writing when it reached EOT. The interrupted volume remains on the first tape, but is never used.

Many tape devices use tapes that can accommodate multiple gigabytes, or even multiple terabytes, of backup data, especially if you use the device's compression mode. When writing to such devices and tapes, allowing the Tape Coordinator to hit the EOT unexpectedly is generally recommended. The devices write data so quickly that it usually does not take much extra time to rewrite the interrupted volume on the new tape. Similarly, they compress data so well that the data abandoned on the first tape from the interrupted volume does not constitute a waste of much tape.

When writing to tapes that accommodate a smaller amount of data (say, less than two GB), it is better to avoid having the Tape Coordinator hit EOT unexpectedly. AFS supports volumes up to 2 GB in size, so an interrupted volume can in fact take up most of the tape. For such tapes, recording accurate values for tape capacity and filemark size, if possible, helps to maximize both use of tape and the efficiency of dump operations. The following discussion of the fields in the tapeconfig file explains how to determine the appropriate values.

Use a text editor to create an entry in a Tape Coordinator's tapeconfig file for each tape device or backup data file that it uses. Each device or file's entry is on its own line and has the following format:

   [capacity   filemark_size]    device_name    port_offset



Specifies the capacity of the tapes used with a tape device, or the amount of data to write into a backup data file. Specify an integer value followed by a letter that indicates units, with no intervening space. The letter k or K indicates kilobytes, m or M indicates megabytes, g or G indicates gigabytes, and t or T indicates terabytes. If the units letter is omitted, the default is kilobytes.

To determine the capacity of a tape under two GB in size that you are going to use in regular (noncompression) mode, you can either use the value that the tape's manufacturer specifies on the tape's packaging or use the fms command to calculate the capacity, as described later in this section. To avoid having the Tape Coordinator reach the EOT unexpectedly, it is best to record in the tapeconfig file or on the label a capacity that is about 10% smaller than the actual capacity of the tape. To calculate the appropriate value for a small tape used in compression mode, one method is to multiply the tape capacity (as recorded by the manufacturer) by the device's compression ratio.

For tapes that hold multiple gigabytes or terabytes of data, or if using a tape drive's compression mode, the recommended configuration is to record a value quite a bit (for instance, two times) larger than the maximum amount you believe can fit on the tape. It is not generally worthwhile to run the fms command on large tapes, even in noncompression mode. The command definitely does not yield accurate results in compression mode. The Tape Coordinator is likely to reach the EOT unexpectedly, but compression mode fits so much data on the tape that the data abandoned from an interrupted volume does not represent much of the tape's capacity.

For a backup data file, record a value slightly smaller than the amount of space available on the partition, and definitely smaller than the operating system's maximum file size. It is also best to limit the ability of other processes to write to the partition, to prevent them from using up the space in the partition.

If this field is empty, the Tape Coordinator uses the maximum acceptable value (2048 GB or 2 TB). Either leave both this field and the filemark_size field empty, or provide a value in both of them.


Specifies the tape device's filemark size, which usually falls between 2 KB and 2 MB. Use the same notation as for the capacity field, but note that if you omit the units letter, the default unit is bytes rather than kilobytes.

For a tape device in regular (noncompression) mode, you can use the fms command to determine filemark size, or use the value reported by the device's manufacturer. To help the Tape Coordinator avoid reaching EOT unexpectedly, increase the value by about 10% when recording it in the tapeconfig file.

The recommended value for a tape device in compression mode is 0 (zero). The fms command does not yield accurate results in compression mode, so you cannot use it to determine the filemark size.

The recommended value for a backup data file is also 0 (zero). The Tape Coordinator does not use filemarks when writing to a file, but a value must appear in this field nevertheless if there is also a value in the capacity field.

If this field is empty, the Tape Coordinator uses the value 0 (zero). Either leave both this field and the capacity field empty, or provide a value in both of them.


Specifies the complete pathname of the tape device or backup data file. The format of tape device names depends on the operating system, but on UNIX systems, device names generally begin with the string /dev/. For a backup data file, this field defines the complete pathname, but for suggestions on how to name a backup data file, see Dumping Data to a Backup Data File.


Specifies the port offset number for a specific tape device or backup data file. Each tape device listens for backup requests on a different UNIX port. You pick the port indirectly by recording a value in this field. The Backup System sets the device's actual port by adding the port offset to a base port number that it determines internally.

Legal values are the integers 0 through 58510 (the Backup System can track a maximum of 58,511 port offset numbers). Each value must be unique among the cell's Tape Coordinators, but you do not have to assign port offset numbers sequentially, and you can associate any number of them with a single machine or even tape device. For example, if you plan to use a device in both compression and noncompression mode, assign it two different port offsets with appropriate tape capacity and filemark values for the different modes.

Assign port offset 0 (zero) to the Tape Coordinator for the tape device or backup data file that you use most often for backup operations; doing so enables you to omit the -portoffset argument from the largest possible number of backup commands.

The following example tapeconfig file includes entries for two tape devices, /dev/rmt0h and /dev/rmt1h. Each one uses tapes with a capacity of 2 GB and has a filemark size of 1 MB. Their port offset numbers are 0 and 1.

   2g 1m /dev/rmt0h 0
   2G 1M /dev/rmt1h 1

The fms command reports the capacity of the tape you have inserted and the tape device's filemark size, both on the standard output stream (stdout) and in its fms.log file, which it writes in the current working directory. The command interpreter must write data to the entire tape, so running the command can take from several hours to more than a day, depending on the size of the tape.

To run the fms command on a noncompressing tape device

  1. If an fms.log file does not already exist in the current directory, verify that you can insert and write to files in the current directory. If the log file already exists, you must be able to write to the file.

  2. Insert a tape into the drive. Running the command completely overwrites the tape, so use a blank tape or one that you want to recycle.

  3. Issue the fms command.

       % fms <tape special file>



    Must be typed in full.

    tape special file

    Specifies the tape device's UNIX device name, such as /dev/rmt0h.

The following example output reports that the tape in the device with device name /dev/rmt0h has a capacity of 2136604672 bytes (about 2 GB), and that the device's filemark size is 1910205 bytes (close to 2 MB).

   % fms /dev/rmt0h
   wrote block: 130408
   Finished data capacity test - rewinding
   wrote 1109 blocks, 1109 file marks
   Finished file mark test
   Tape capacity is 2136604672 bytes
   File marks are 1910205 bytes