doc/man-pages/pod5/tapeconfig.pod

   1 =head1 NAME
   2
   3 tapeconfig - Defines parameters for tape devices and backup data files
   4
   5 =head1 DESCRIPTION
   6
   7 The F<tapeconfig> file defines basic configuration parameters for all of
   8 the tape devices or backup data files available for backup operations on a
   9 Tape Coordinator machine. The file is in ASCII format and must reside in
  10 the local F</usr/afs/backup> directory. The instruction for each tape
  11 device or backup data file appears on its own line and each has the
  12 following format:
  13
  14    [<capacity> <filemark_size>] <device_name> <port_offset>
  15
  16 where
  17
  18 =over 4
  19
  20 =item <capacity>
  21
  22 Specifies the capacity of the tapes used with a tape device, or the amount
  23 of data to write into a backup data file. The Tape Coordinator refers to
  24 this value in two circumstances:
  25
  26 =over 4
  27
  28 =item *
  29
  30 When the capacity field of a tape or backup data file's label is empty
  31 (because the tape has never been labeled). The Tape Coordinator records
  32 this value on the label and uses it when determining how much data it can
  33 write to the tape or file during a B<backup dump> or B<backup savedb>
  34 operation. If there is already a capacity value on the label, the Tape
  35 Coordinator uses it instead.
  36
  37 =item *
  38
  39 When the B<-size> argument is omitted the first time the B<backup
  40 labeltape> command is used on a given tape or file.  The Tape Coordinator
  41 copies this value into the label's capacity field.
  42
  43 =back
  44
  45 The Tape Coordinator uses this capacity value or the one on the Backup
  46 System tape label to track how much space remains as it writes data to a
  47 tape or backup data file. The appropriate value to record for a tape
  48 depends on the size of the tapes usually used in the device and whether it
  49 has a compression mode; for suggested values, see the I<OpenAFS
  50 Administration Guide> chapter on configuring the Backup System. If using a
  51 value obtained from the B<fms> command, reduce it by 10% to 15% before
  52 recording it in the file.
  53
  54 For a backup data file, it is best to provide a value that helps the Tape
  55 Coordinator avoid reaching the end-of-file (EOF) unexpectedly. Make it at
  56 least somewhat smaller than the amount of space available on the partition
  57 housing the file when the dump operation begins, and never larger than the
  58 maximum file size allowed by the operating system.
  59
  60 Specify a (positive) integer or decimal value followed by a letter than
  61 indicates units, with no intervening space. In a decimal number, the
  62 number of digits after the decimal point must not translate to fractions
  63 of bytes. The maximum acceptable value is 2048 GB (2 TB). The acceptable
  64 units letters are as follows; if the letter is omitted, the default is
  65 kilobytes.
  66
  67 =over 4
  68
  69 =item *
  70
  71 C<k> or C<K> for kilobytes (KB).
  72
  73 =item *
  74
  75 C<m> or C<M> for megabytes (MB).
  76
  77 =item *
  78
  79 C<g> or C<G> for gigabytes (GB).
  80
  81 =item *
  82
  83 C<t> or C<T> for terabytes (TB).
  84
  85 =back
  86
  87 If this field is omitted, the Tape Coordinator uses the maximum acceptable
  88 value (2048 GB or 2 TB). Either leave both this field and the
  89 <filemark_size> field empty, or provide a value in both of them.
  90
  91 =item <filemark_size>
  92
  93 Specifies the size of a tape device's filemarks (also called end-of-file
  94 or EOF marks), which is set by the device's manufacturer. In a dump to
  95 tape, the Tape Coordinator inserts filemarks at the boundary between the
  96 data from each volume, so the filemark size affects how much space is
  97 available for actual data.
  98
  99 The appropriate value to record for a tape depends on the size of the
 100 tapes usually used in the device and whether it has a compression mode;
 101 for suggested values, see the I<OpenAFS Administration Guide> chapter on
 102 configuring the Backup System. If using a value obtained from the B<fms>
 103 command, increase it by 10% to 15% before recording it in the file.
 104
 105 For backup data files, record a value of 0 (zero). The Tape Coordinator
 106 actually ignores this field for backup data files, because it does not use
 107 filemarks when writing to a file.
 108
 109 Use the same notation as for the <capacity> field, but note that the
 110 default units is bytes rather than kilobytes. The maximum acceptable value
 111 is 2048 GB.
 112
 113 If this field is empty, the Tape Coordinator uses the value 0
 114 (zero). Either leave both this field and the <capacity> field empty, or
 115 provide a value in both of them.
 116
 117 =item <device_name>
 118
 119 Specifies the complete pathname of the tape device or backup data
 120 file. The format of tape device names depends on the operating system, but
 121 on UNIX systems device names generally begin with the string F</dev/>. For
 122 a backup data file, this field defines the complete pathname; for a
 123 discussion of suggested naming conventions see the description of the
 124 C<FILE> instruction in L<butc(5)>.
 125
 126 =item <port_offset>
 127
 128 Specifies the port offset number associated with this combination of Tape
 129 Coordinator and tape device or backup data file.
 130
 131 Acceptable values are the integers C<0> through C<58510> (the Backup
 132 System can track a maximum of 58,511 port offset numbers).  Each value
 133 must be unique among the cell's Tape Coordinators, but any number of them
 134 can be associated with a single machine. Port offset numbers need not be
 135 assigned sequentially, and can appear in any order in the F<tapeconfig>
 136 file. Assign port offset C<0> to the Tape Coordinator for the tape device
 137 or backup data file used most often for backup operations; doing so will
 138 allow the operator to omit the B<-portoffset> argument from the largest
 139 possible number of B<backup> commands.
 140
 141 =back
 142
 143 =head1 PRIVILEGE REQUIRED
 144
 145 Creating the file requires UNIX C<w> (write) and C<x> (execute)
 146 permissions on the F</usr/afs/backup> directory. Editing the file requires
 147 UNIX C<w> (write) permission on the file.
 148
 149 =head1 EXAMPLES
 150
 151 The following example tapeconfig file configures three tape devices and a
 152 backup data file. The first device has device name F</dev/rmt/0h>, and is
 153 assigned port offset C<0> because it will be the most frequently used
 154 device for all backup operations in the cell. Its default tape capacity is
 155 2 GB and filemark size is 1 MB. The F</dev/rmt/3h> drive has half the
 156 capacity but a much smaller filemark size; its port offset is C<3>. The
 157 third device listed, F</dev/rmt/4h>, has the same capacity and filemark
 158 size as the first device and is assigned port offset C<2>. Port offset
 159 C<4> is assigned to the backup data file F</dev/FILE>, which is actually a
 160 symbolic link to the actual file located elsewhere on the local disk. The
 161 Tape Coordinator writes up to 1.5 GB into the file; as recommended, the
 162 filemark size is set to zero.
 163
 164    2G 1M /dev/rmt/0h 0
 165    1g 4k /dev/rmt/3h 3
 166    2G 1m /dev/rmt/4h 2
 167    1.5G 0 /dev/FILE 4
 168
 169 =head1 SEE ALSO
 170
 171 L<backup_addhost(8)>,
 172 L<backup_dump(8)>,
 173 L<backup_labeltape(8)>,
 174 L<backup_savedb(8)>,
 175 L<butc(8)>,
 176 L<fms(8)>
 177
 178 =head1 COPYRIGHT
 179
 180 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 181
 182 This documentation is covered by the IBM Public License Version 1.0.  It was
 183 converted from HTML to POD by software written by Chas Williams and Russ
 184 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.