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