[hcoop/debian/openafs.git] / doc / man-pages / pod5 / tapeconfig.pod

=head1 NAME

tapeconfig - Defines parameters for tape devices and backup data files

=head1 DESCRIPTION

The F<tapeconfig> file defines basic configuration parameters for all of
the tape devices or backup data files available for backup operations on a
Tape Coordinator machine. The file is in ASCII format and must reside in
the local F</usr/afs/backup> directory. The instruction for each tape
device or backup data file appears on its own line and each has the
following format:

   [<capacity> <filemark_size>] <device_name> <port_offset>

where

=over 4

=item <capacity>

Specifies the capacity of the tapes used with a tape device, or the amount
of data to write into a backup data file. The Tape Coordinator refers to
this value in two circumstances:

=over 4

=item *

When the capacity field of a tape or backup data file's label is empty
(because the tape has never been labeled). The Tape Coordinator records
this value on the label and uses it when determining how much data it can
write to the tape or file during a B<backup dump> or B<backup savedb>
operation. If there is already a capacity value on the label, the Tape
Coordinator uses it instead.

=item *

When the B<-size> argument is omitted the first time the B<backup
labeltape> command is used on a given tape or file.  The Tape Coordinator
copies this value into the label's capacity field.

=back

The Tape Coordinator uses this capacity value or the one on the Backup
System tape label to track how much space remains as it writes data to a
tape or backup data file. The appropriate value to record for a tape
depends on the size of the tapes usually used in the device and whether it
has a compression mode; for suggested values, see the I<OpenAFS
Administration Guide> chapter on configuring the Backup System. If using a
value obtained from the B<fms> command, reduce it by 10% to 15% before
recording it in the file.

For a backup data file, it is best to provide a value that helps the Tape
Coordinator avoid reaching the end-of-file (EOF) unexpectedly. Make it at
least somewhat smaller than the amount of space available on the partition
housing the file when the dump operation begins, and never larger than the
maximum file size allowed by the operating system.

Specify a (positive) integer or decimal value followed by a letter than
indicates units, with no intervening space. In a decimal number, the
number of digits after the decimal point must not translate to fractions
of bytes. The maximum acceptable value is 2048 GB (2 TB). The acceptable
units letters are as follows; if the letter is omitted, the default is
kilobytes.

=over 4

=item *

C<k> or C<K> for kilobytes (KB).

=item *

C<m> or C<M> for megabytes (MB).

=item *

C<g> or C<G> for gigabytes (GB).

=item *

C<t> or C<T> for terabytes (TB).

=back

If this field is omitted, 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.

=item <filemark_size>

Specifies the size of a tape device's filemarks (also called end-of-file
or EOF marks), which is set by the device's manufacturer. In a dump to
tape, the Tape Coordinator inserts filemarks at the boundary between the
data from each volume, so the filemark size affects how much space is
available for actual data.

The appropriate value to record for a tape depends on the size of the
tapes usually used in the device and whether it has a compression mode;
for suggested values, see the I<OpenAFS Administration Guide> chapter on
configuring the Backup System. If using a value obtained from the B<fms>
command, increase it by 10% to 15% before recording it in the file.

For backup data files, record a value of 0 (zero). The Tape Coordinator
actually ignores this field for backup data files, because it does not use
filemarks when writing to a file.

Use the same notation as for the <capacity> field, but note that the
default units is bytes rather than kilobytes. The maximum acceptable value
is 2048 GB.

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.

=item <device_name>

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 F</dev/>. For
a backup data file, this field defines the complete pathname; for a
discussion of suggested naming conventions see the description of the
C<FILE> instruction in L<butc(5)>.

=item <port_offset>

Specifies the port offset number associated with this combination of Tape
Coordinator and tape device or backup data file.

Acceptable values are the integers C<0> through C<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 any number of them
can be associated with a single machine. Port offset numbers need not be
assigned sequentially, and can appear in any order in the F<tapeconfig>
file. Assign port offset C<0> to the Tape Coordinator for the tape device
or backup data file used most often for backup operations; doing so will
allow the operator to omit the B<-portoffset> argument from the largest
possible number of B<backup> commands.

=back

=head1 PRIVILEGE REQUIRED

Creating the file requires UNIX C<w> (write) and C<x> (execute)
permissions on the F</usr/afs/backup> directory. Editing the file requires
UNIX C<w> (write) permission on the file.

=head1 EXAMPLES

The following example tapeconfig file configures three tape devices and a
backup data file. The first device has device name F</dev/rmt/0h>, and is
assigned port offset C<0> because it will be the most frequently used
device for all backup operations in the cell. Its default tape capacity is
2 GB and filemark size is 1 MB. The F</dev/rmt/3h> drive has half the
capacity but a much smaller filemark size; its port offset is C<3>. The
third device listed, F</dev/rmt/4h>, has the same capacity and filemark
size as the first device and is assigned port offset C<2>. Port offset
C<4> is assigned to the backup data file F</dev/FILE>, which is actually a
symbolic link to the actual file located elsewhere on the local disk. The
Tape Coordinator writes up to 1.5 GB into the file; as recommended, the
filemark size is set to zero.

   2G 1M /dev/rmt/0h 0
   1g 4k /dev/rmt/3h 3
   2G 1m /dev/rmt/4h 2
   1.5G 0 /dev/FILE 4

=head1 SEE ALSO

L<backup_addhost(8)>,
L<backup_dump(8)>,
L<backup_labeltape(8)>,
L<backup_savedb(8)>,
L<butc(8)>,
L<fms(8)>

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0.  It was
converted from HTML to POD by software written by Chas Williams and Russ
Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
Commit	Line	Data
805e021f CE	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.