man5-editing-pass-20051213
[openafs.git] / 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<IBM AFS
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<IBM AFS 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.