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