1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
5 >Configuring the AFS Backup System</TITLE
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
10 TITLE="AFS Administration Guide"
11 HREF="book1.html"><LINK
13 TITLE="Managing File Server Machines"
14 HREF="p3023.html"><LINK
16 TITLE="Managing Volumes"
17 HREF="c8420.html"><LINK
19 TITLE="Backing Up and Restoring AFS Data"
20 HREF="c15383.html"></HEAD
31 SUMMARY="Header navigation table"
40 >AFS Administration Guide: Version 3.6</TH
77 >Chapter 6. Configuring the AFS Backup System</H1
79 >The AFS Backup System helps you to create backup copies of data from AFS volumes and to restore data to the file system if
80 it is lost or corrupted. This chapter explains how to configure the Backup System. For instructions on backing up and restoring
81 data and displaying dump records, see <A
83 >Backing Up and Restoring AFS Data</A
91 >Summary of Instructions</A
94 >This chapter explains how to perform the following tasks by using the indicated commands:</P
109 >Determine tape capacity and filemark size</TD
121 >Define Tape Coordinator entry in Backup Database</TD
133 >Remove Tape Coordinator entry from Backup Database</TD
145 >Display Tape Coordinator entries from Backup Database</TD
157 >Create volume set</TD
169 >Add volume entry to volume set</TD
175 >backup addvolentry</B
181 >List volume sets and entries</TD
187 >backup listvolsets</B
193 >Delete volume set from Backup Database</TD
205 >Delete volume entry from volume set</TD
211 >backup delvolentry</B
217 >Define dump level</TD
229 >Change expiration date on existing dump level</TD
241 >Delete dump level from dump hierarchy</TD
253 >Display dump hierarchy</TD
277 >Read label on tape</TD
297 >Introduction to Backup System Features</A
300 >The AFS Backup System is highly flexible, enabling you to control most aspects of the backup process, including how often
301 backups are performed, which volumes are backed up, and whether to dump all of the data in a volume or just the data that has
302 changed since the last dump operation. You can also take advantage of several features that automate much of the backup
305 >To administer and use the Backup System most efficiently, it helps to be familiar with its basic features, which are
306 described in the following sections. For pointers to instructions for implementing the features as you configure the Backup
307 System in your cell, see <A
308 HREF="c12776.html#HDRWQ257"
309 >Overview of Backup System Configuration</A
317 >Volume Sets and Volume Entries</A
320 >When you back up AFS data, you specify which data to include in terms of complete volumes rather than individual files.
321 More precisely, you define groups of volumes called <SPAN
327 >, each of which includes one or more
328 volumes that you want to back up in a single operation. You must include a volume in a volume set to back it up, because the
329 command that backs up data (the <SPAN
335 > command) does not accept individual volume
338 >A volume set consists of one or more <SPAN
344 >, each of which specifies which volumes to back
345 up based on their location (file server machine and partition) and volume name. You can use a wildcard notation to include all
346 volumes that share a location, a common character string in their names, or both.</P
348 >For instructions on creating and removing volume sets and volume entries, see <A
349 HREF="c12776.html#HDRWQ265"
351 Displaying Volume Sets and Volume Entries</A
360 >Dumps and Dump Sets</A
369 > is the collection of data that results from backing up a volume set. A <SPAN
376 > includes all of the data in every volume in the volume set, as it exists at the time of the dump operation. An
383 > includes only some of the data from the volumes in the volume set, namely those files
384 and directory structures that have changed since a specified previous dump operation was performed. The previous dump is
385 referred to as the incremental dump's <SPAN
391 >, and it can be either a full dump or an incremental
400 > is a collection of one or more dumps stored together on one or more tapes. The first
401 dump in the dump set is the <SPAN
407 >, and any subsequent dump added onto the end of an existing dump
414 >. Appending dumps is always optional, but maximizes use of a tape's capacity. In
415 contrast, creating only initial dumps can result in many partially filled tapes, because an initial dump must always start on
416 a new tape, but does not necessarily extend to the end of the tape. Appended dumps do not have to be related to one another or
417 to the initial dump (they do not have to be dumps of the same or related volume sets), but well-planned appending can reduce
418 the number of times you have to change tapes during a restore operation. For example, it can make sense to append incremental
419 dumps of a volume set together in a single dump set.</P
421 >All the records for a dump set are indexed together in the Backup Database based on the initial dump (for more on the
422 Backup Database, see <A
423 HREF="c12776.html#HDRWQ256"
424 >The Backup Database and Backup Server Process</A
425 >). To delete the database
426 record of an appended dump, you must delete the initial dump record, and doing so deletes the records for all dumps in the
427 dump set. Similarly, you cannot recycle just one tape in a dump set without deleting the database records of all tapes in the
430 >For instructions on creating an initial dump, see <A
431 HREF="c15383.html#HDRWQ296"
433 >, and to learn how to
435 HREF="c15383.html#HDRWQ299"
436 >Appending Dumps to an Existing Dump Set</A
445 >Dump Hierarchies, Dump Levels and Expiration Dates</A
454 > is a logical structure that defines the relationship between full and incremental
455 dumps; that is, it defines which dump serves as the parent for an incremental dump. Each individual component of a hierarchy
462 >. When you create a dump by issuing the <SPAN
469 command, you specify a volume set name and a dump level name. The Backup System uses the dump level to determine whether the
470 dump is full or incremental, and if incremental, which dump level to use as the parent.</P
472 >You can associate an <SPAN
478 > with a dump level, to define when a dump created at that level
479 expires. The Backup System refuses to overwrite a tape until all dumps in the dump set to which the tape belongs have expired,
480 so assigning expiration dates automatically determines how you recycle tapes. You can define an expiration date either in
481 absolute terms (for example, 13 January 2000) or relative terms (for example, 30 days from when the dump is created). You can
482 also change the expiration date associated with a dump level (but not with an actual dump that has already been created at
485 >For instructions on creating dump hierarchies, assigning expiration dates, and establishing a tape recycling schedule,
487 HREF="c12776.html#HDRWQ267"
488 >Defining and Displaying the Dump Hierarchy</A
497 >Dump Names and Tape Names</A
500 >When you create a dump, the Backup System creates a Backup Database record for it, assigning a name comprising the
501 volume set name and the last element in the dump level pathname:</P
503 CLASS="programlisting"
504 > volume_set_name<SPAN
513 >For example, a dump of the volume set <SPAN
519 > at the dump level <SPAN
531 >. The Backup System also assigns a
538 > number to the dump to distinguish it from other dumps with the same name that possibly
541 >The Backup System assigns a similar <SPAN
547 > to each tape that contains a dump set, reflecting
548 the volume set and dump level of the dump set's initial dump, plus a numerical index of the tape's position in the dump set,
549 and a unique dump ID number:</P
551 CLASS="programlisting"
552 > volume_set_name<SPAN
558 >dump_level_name<SPAN
564 >tape_index (dump ID)
567 >For example, the second tape in a dump set whose initial dump is of the volume set <SPAN
573 > at the dump level <SPAN
579 > has AFS tape name like
594 >In addition to its AFS tape name, a tape can have an optional <SPAN
601 Unlike the AFS tape name, the permanent name does not have to indicate the volume set and dump level of the initial (or any
602 other) dump, and so does not change depending on the contents of the tape. The Backup System does not require a certain format
603 for permanent names, so you need to make sure that each tape's name is unique. If a tape has a permanent name, the Backup
604 System uses it rather than the AFS tape name when referring to the tape in prompts and the output from most <SPAN
610 > commands, but still tracks the AFS tape name internally.</P
618 >Tape Labels, Dump Labels, and EOF Markers</A
621 >Every tape used in the Backup System has a magnetic label at the beginning that records the tape's name, capacity, and
622 other information. You can use the <SPAN
628 > command to write a label, or the
635 > command creates one automatically if you use an unlabeled tape. The label records
636 the following information: <UL
639 >The tape's permanent name, which you can assign by using the <SPAN
652 > command. It can be any string of up to 32 characters. If you do
653 not assign a permanent name, the Backup System records the value <SAMP
654 CLASS="computeroutput"
655 ><NULL></SAMP
663 > command to assign an AFS tape name, or when you use the
670 > command to write a dump to the tape.</P
674 >The tape's AFS <SPAN
680 >, which can be one of three types of values: <UL
683 >A name that reflects the volume set and dump level of the dump set's initial dump and the tape's place in
684 the sequence of tapes for the dump set, as described in <A
685 HREF="c12776.html#HDRWQ253"
686 >Dump Names and Tape Names</A
688 If the tape does not have a permanent name, you can assign the AFS tape name by using the <SPAN
694 > argument to the <SPAN
705 CLASS="computeroutput"
706 ><NULL></SAMP
707 >, which results when you assign a permanent name, or
708 provide no value for the <SPAN
724 >No AFS tape name at all, indicating that you have never labeled the tape or written a dump to it.</P
729 >If a tape does not already have an actual AFS tape name when you write a dump to it, the Backup System constructs
730 and records the appropriate AFS tape name. If the tape does have an AFS tape name and you are writing an initial dump,
731 then the name must correctly reflect the dump's volume set and dump level.</P
735 >The capacity, or <SPAN
741 >, of the tape, followed by a letter that indicates the unit of measure
743 CLASS="computeroutput"
746 CLASS="computeroutput"
750 CLASS="computeroutput"
753 CLASS="computeroutput"
757 CLASS="computeroutput"
760 CLASS="computeroutput"
764 CLASS="computeroutput"
767 CLASS="computeroutput"
769 > for terabytes). The tape's manufacturer
770 determines the tape's capacity. For further discussion of how the Backup System uses the value in the capacity field,
772 HREF="c12776.html#HDRWQ258"
773 >Configuring the tapeconfig File</A
779 >For information about labeling tapes, see <A
780 HREF="c12776.html#HDRWQ272"
781 >Writing and Reading Tape Labels</A
784 >In addition to the tape label, the Backup System writes a <SPAN
790 > on the tape for every appended
791 dump (the tape label and dump label are the same for the initial dump). A dump label records the following information:
795 >The name of the tape containing the dump</P
799 >The date and time that the dump operation began</P
803 >The cell to which the volumes in the dump belong</P
807 >The dump's size in kilobytes</P
811 >The dump's dump level</P
815 >The dump's dump ID</P
820 >The Backup System writes a <SPAN
826 > (also called an End-of-File or EOF marker) between the data
827 from each volume in a dump. The tape device's manufacturer determines the filemark size, which is typically between 2 KB and 2
828 MB; in general, the larger the usual capacity of the tapes that the device uses, the larger the filemark size. If a dump
829 contains a small amount of data from each of a large number of volumes, as incremental dumps often do, then the filemark size
830 can significantly affect how much volume data fits on the tape. To enable the Backup System to factor in filemark size as it
831 writes a dump, you can record the filemark size in a configuration file; see <A
832 HREF="c12776.html#HDRWQ258"
843 >Tape Coordinator Machines, Port Offsets, and Backup Data Files</A
850 >Tape Coordinator machine</I
852 > is a machine that drives one or more attached tape devices used for
853 backup operations. It must run the AFS client software (the Cache Manager) but reside in a physically secure location to
854 prevent unauthorized access to its console. Before backup operations can run on a Tape Coordinator machine, each tape device
855 on the machine must be registered in the Backup Database, and certain files and directories must exist on the machine's local
856 disk; for instructions, see <A
857 HREF="c12776.html#HDRWQ262"
858 >To configure a Tape Coordinator machine</A
861 >Each tape device on a Tape Coordinator machine listens for backup requests on a different UNIX port. You pick the port
862 indirectly by assigning a <SPAN
866 >port offset number</I
868 > to the tape device. The Backup System sets the device's
869 actual port by adding the port offset to a base port number that it determines internally. For instructions on assigning port
870 offset numbers, see <A
871 HREF="c12776.html#HDRWQ258"
872 >Configuring the tapeconfig File</A
875 >For a tape device to perform backup operations, a Backup Tape Coordinator (<SPAN
882 process dedicated to the device must be running actively on the Tape Coordinator machine. You then direct backup requests to
883 the device's Tape Coordinator by specifying its port offset number with the <SPAN
890 argument to the <SPAN
898 >In addition to writing backup data to tape, you can direct it to a <SPAN
905 disk of a Tape Coordinator machine. You can then to transfer the data to a data-archiving system, such as a hierarchical
906 storage management (HSM) system, that you use in conjunction with AFS and the Backup System. A backup data file has a port
907 offset like a tape device. For instructions on configuring backup data files, see <A
908 HREF="c12776.html#HDRWQ282"
919 >The Backup Database and Backup Server Process</A
928 > is a replicated administrative database maintained by the Backup Server process
929 on the cell's database server machines. Like the other AFS database server processes, the <SPAN
936 uses the Ubik utility to keep the various copies of the database synchronized (for a discussion of Ubik, see <A
937 HREF="c667.html#HDRWQ52"
938 >Replicating the AFS Administrative Databases</A
941 >The Backup Database records the following information: <UL
944 >The Tape Coordinator machine's hostname and the port offset number for each tape device used for backup
949 >The dump hierarchy, which consists of its component dump levels and their associated expiration dates</P
953 >The volume sets and their component volume entries</P
957 >A record for each dump, which includes the name of each tape it appears on, a list of the volumes from which data
958 is included, the dump level, the expiration date, and the dump ID of the initial dump with which the dump is
963 >A record for each tape that houses dumped data</P
974 >Interfaces to the Backup System</A
983 > suite of commands is the administrative interface to the Backup System. You
984 can issue the commands in a command shell (or invoke them in a shell script) on any AFS client or server machine from which
985 you can access the <SPAN
991 > binary. In the conventional configuration, the binary resides on
1000 > command suite provides an <SPAN
1004 >interactive mode</I
1007 you can issue multiple commands over a persistent connection to the Backup Server and the Volume Location (VL) Server.
1008 Interactive mode has several convenient features, including the following: <UL
1011 >You need to type only the operation code, omitting the initial <SPAN
1022 >If you assume another AFS identity or specify a foreign cell as you enter interactive mode, it applies to all
1023 subsequent commands.</P
1027 >You do not need to enclose shell metacharacters in double quotes.</P
1031 >You can track current and pending operations with the <SPAN
1038 which is available only in this mode.</P
1042 >You can cancel current and pending operations with the <SPAN
1049 which is available only in this mode.</P
1054 >Before issuing a command that requires reading or writing a tape (or backup data file), you must also open a connection
1055 to the Tape Coordinator machine that is attached to the relevant tape device (or that has the backup data file on its local
1056 disk), and issue the <SPAN
1062 > command to initialize the Tape Coordinator process. The process
1063 must continue to run and the connection remain open as long as you need to use the tape device or file for backup
1066 >For further discussion and instructions, see <A
1067 HREF="c15383.html#HDRWQ286"
1068 >Using the Backup System's
1079 >Overview of Backup System Configuration</A
1082 >Before you can use the Backup System to back up and restore data, you must configure several of its basic components. The
1083 indicated sections of this chapter explain how to perform the following configuration tasks: <UL
1086 >Determining a tape's capacity and a tape device's filemark size, and recording them in the <SPAN
1090 >/usr/afs/backup/tapeconfig</B
1093 HREF="c12776.html#HDRWQ258"
1094 >Configuring the tapeconfig
1100 >Determining how to grant administrative privilege to backup operators (see <A
1101 HREF="c12776.html#HDRWQ260"
1103 Administrative Privilege to Backup Operators</A
1108 >Configuring Tape Coordinator machines, tape devices, and backup data files (see <A
1109 HREF="c12776.html#HDRWQ261"
1111 Tape Coordinator Machines and Tape Devices</A
1116 >Defining volume sets and volume entries (see <A
1117 HREF="c12776.html#HDRWQ265"
1118 >Defining and Displaying Volume Sets and Volume
1124 >Defining dump levels to create a dump hierarchy (see <A
1125 HREF="c12776.html#HDRWQ267"
1126 >Defining and Displaying the Dump
1132 >Labeling tapes (see <A
1133 HREF="c12776.html#HDRWQ272"
1134 >Writing and Reading Tape Labels</A
1139 >Creating a device configuration file to automate the backup process (see <A
1140 HREF="c12776.html#HDRWQ275"
1142 Increasing the Efficiency of the Backup Process</A
1148 >If you have already configured all of the components required for performing a backup dump or restore operation, you can
1149 proceed to the instructions in <A
1150 HREF="c15383.html#HDRWQ296"
1153 HREF="c15383.html#HDRWQ306"
1164 >Configuring the tapeconfig File</A
1167 >Several factors interact to determine how much data the Tape Coordinator can fit on a tape: <UL
1170 >The tape's capacity (size), as set by the tape manufacturer.</P
1174 >The tape device's filemark size, as set by the tape device's manufacturer. Recall from <A
1175 HREF="c12776.html#HDRWQ254"
1177 Labels, Dump Labels, and EOF Markers</A
1178 > that the Tape Coordinator writes a filemark between the data from each volume
1179 in a dump. If a dump contains a small amount of data from each of a large number of volumes, as incremental dumps often
1180 do, then the filemark size can significantly affect how much volume data fits on the tape.</P
1184 >Whether or not you use the tape device's compression mode.</P
1189 >(The amount of data that can fit in a backup data file is determined by amount of space available on the partition, and
1190 the operating system's maximum file size. The Tape Coordinator does not write filemarks when writing to a backup data file. For
1191 further information about configuring a Tape Coordinator to write to a backup data file, see <A
1192 HREF="c12776.html#HDRWQ282"
1194 Data to a Backup Data File</A
1197 >As the Tape Coordinator (<SPAN
1203 >) process initializes, it reads the <SPAN
1207 >/usr/afs/backup/tapeconfig</B
1209 > file on its local disk to learn the tape capacity and filemark size (for a
1210 tape device) or the file size (for a backup data file) to use for dump operations. When you begin a dump operation, the Tape
1211 Coordinator also reads the tape or backup data file's label to see if you have recorded a different tape capacity or file size.
1212 If you have, the value on the label overrides the default value from the <SPAN
1221 >As the Tape Coordinator writes data to a tape during a dump operation, it uses the capacity and filemark information to
1222 track how much tape it has used and how much remains before the physical end-of-tape (EOT). Shortly before reaching EOT, the
1223 Tape Coordinator stops writing and requests a new tape. Similarly, it uses a backup data file's size to know when it is about to
1224 exhaust the space in the file. If the Tape Coordinator reaches the EOT unexpectedly, it recovers by obtaining a new tape and
1225 writing to it the entire contents of the volume it was writing when it reached EOT. The interrupted volume remains on the first
1226 tape, but is never used.</P
1228 >Many tape devices use tapes that can accommodate multiple gigabytes, or even multiple terabytes, of backup data,
1229 especially if you use the device's compression mode. When writing to such devices and tapes, allowing the Tape Coordinator to
1230 hit the EOT unexpectedly is generally recommended. The devices write data so quickly that it usually does not take much extra
1231 time to rewrite the interrupted volume on the new tape. Similarly, they compress data so well that the data abandoned on the
1232 first tape from the interrupted volume does not constitute a waste of much tape.</P
1234 >When writing to tapes that accommodate a smaller amount of data (say, less than two GB), it is better to avoid having the
1235 Tape Coordinator hit EOT unexpectedly. AFS supports volumes up to 2 GB in size, so an interrupted volume can in fact take up
1236 most of the tape. For such tapes, recording accurate values for tape capacity and filemark size, if possible, helps to maximize
1237 both use of tape and the efficiency of dump operations. The following discussion of the fields in the <SPAN
1243 > file explains how to determine the appropriate values.</P
1245 >Use a text editor to create an entry in a Tape Coordinator's <SPAN
1252 tape device or backup data file that it uses. Each device or file's entry is on its own line and has the following
1255 CLASS="programlisting"
1256 > [capacity filemark_size] device_name port_offset
1260 CLASS="variablelist"
1272 >Specifies the capacity of the tapes used with a tape device, or the amount of data to write into a backup data
1273 file. Specify an integer value followed by a letter that indicates units, with no intervening space. The letter
1286 > indicates kilobytes, <SPAN
1298 > indicates megabytes, <SPAN
1311 > indicates gigabytes, and <SPAN
1323 > indicates terabytes. If the units letter is omitted, the default is kilobytes.</P
1325 >To determine the capacity of a tape under two GB in size that you are going to use in regular (noncompression)
1326 mode, you can either use the value that the tape's manufacturer specifies on the tape's packaging or use the <SPAN
1332 > command to calculate the capacity, as described later in this section. To avoid having the
1333 Tape Coordinator reach the EOT unexpectedly, it is best to record in the <SPAN
1340 file or on the label a capacity that is about 10% smaller than the actual capacity of the tape. To calculate the
1341 appropriate value for a small tape used in compression mode, one method is to multiply the tape capacity (as recorded by
1342 the manufacturer) by the device's compression ratio.</P
1344 >For tapes that hold multiple gigabytes or terabytes of data, or if using a tape drive's compression mode, the
1345 recommended configuration is to record a value quite a bit (for instance, two times) larger than the maximum amount you
1346 believe can fit on the tape. It is not generally worthwhile to run the <SPAN
1353 large tapes, even in noncompression mode. The command definitely does not yield accurate results in compression mode.
1354 The Tape Coordinator is likely to reach the EOT unexpectedly, but compression mode fits so much data on the tape that
1355 the data abandoned from an interrupted volume does not represent much of the tape's capacity.</P
1357 >For a backup data file, record a value slightly smaller than the amount of space available on the partition, and
1358 definitely smaller than the operating system's maximum file size. It is also best to limit the ability of other
1359 processes to write to the partition, to prevent them from using up the space in the partition.</P
1361 >If this field is empty, the Tape Coordinator uses the maximum acceptable value (2048 GB or 2 TB). Either leave
1362 both this field and the filemark_size field empty, or provide a value in both of them.</P
1374 >Specifies the tape device's filemark size, which usually falls between 2 KB and 2 MB. Use the same notation as for
1375 the capacity field, but note that if you omit the units letter, the default unit is bytes rather than kilobytes.</P
1377 >For a tape device in regular (noncompression) mode, you can use the <SPAN
1384 to determine filemark size, or use the value reported by the device's manufacturer. To help the Tape Coordinator avoid
1385 reaching EOT unexpectedly, increase the value by about 10% when recording it in the <SPAN
1393 >The recommended value for a tape device in compression mode is <SPAN
1406 > command does not yield accurate results in compression mode, so you cannot use it
1407 to determine the filemark size.</P
1409 >The recommended value for a backup data file is also <SPAN
1416 Coordinator does not use filemarks when writing to a file, but a value must appear in this field nevertheless if there
1417 is also a value in the capacity field.</P
1419 >If this field is empty, the Tape Coordinator uses the value <SPAN
1426 leave both this field and the capacity field empty, or provide a value in both of them.</P
1438 >Specifies the complete pathname of the tape device or backup data file. The format of tape device names depends on
1439 the operating system, but on UNIX systems, device names generally begin with the string <SPAN
1445 >. For a backup data file, this field defines the complete pathname, but for suggestions on
1446 how to name a backup data file, see <A
1447 HREF="c12776.html#HDRWQ282"
1448 >Dumping Data to a Backup Data File</A
1461 >Specifies the port offset number for a specific tape device or backup data file. Each tape device listens for
1462 backup requests on a different UNIX port. You pick the port indirectly by recording a value in this field. The Backup
1463 System sets the device's actual port by adding the port offset to a base port number that it determines
1466 >Legal values are the integers <SPAN
1479 (the Backup System can track a maximum of 58,511 port offset numbers). Each value must be unique among the cell's Tape
1480 Coordinators, but you do not have to assign port offset numbers sequentially, and you can associate any number of them
1481 with a single machine or even tape device. For example, if you plan to use a device in both compression and
1482 noncompression mode, assign it two different port offsets with appropriate tape capacity and filemark values for the
1485 >Assign port offset <SPAN
1491 > (zero) to the Tape Coordinator for the tape device or backup
1492 data file that you use most often for backup operations; doing so enables you to omit the <SPAN
1498 > argument from the largest possible number of <SPAN
1511 >The following example <SPAN
1517 > file includes entries for two tape devices, <SPAN
1529 >. Each one uses tapes with a capacity of 2 GB
1530 and has a filemark size of 1 MB. Their port offset numbers are <SAMP
1531 CLASS="computeroutput"
1535 CLASS="computeroutput"
1539 CLASS="programlisting"
1540 > 2g 1m /dev/rmt0h 0
1550 > command reports the capacity of the tape you have inserted and the tape device's
1551 filemark size, both on the standard output stream (stdout) and in its <SPAN
1558 writes in the current working directory. The command interpreter must write data to the entire tape, so running the command can
1559 take from several hours to more than a day, depending on the size of the tape.</P
1566 >To run the fms command on a noncompressing tape device</A
1578 > file does not already exist in the current directory, verify that you
1579 can insert and write to files in the current directory. If the log file already exists, you must be able to write to the
1584 >Insert a tape into the drive. Running the command completely overwrites the tape, so use a blank tape or one that
1585 you want to recycle.</P
1596 CLASS="programlisting"
1605 >tape special file</VAR
1611 CLASS="variablelist"
1623 >Must be typed in full.</P
1630 >tape special file</B
1635 >Specifies the tape device's UNIX device name, such as <SPAN
1649 >The following example output reports that the tape in the device with device name <SPAN
1655 > has a capacity of 2136604672 bytes (about 2 GB), and that the device's filemark size is
1656 1910205 bytes (close to 2 MB).</P
1658 CLASS="programlisting"
1667 Finished data capacity test - rewinding
1668 wrote 1109 blocks, 1109 file marks
1669 Finished file mark test
1670 Tape capacity is 2136604672 bytes
1671 File marks are 1910205 bytes
1681 >Granting Administrative Privilege to Backup Operators</A
1684 >Each person who issues the <SPAN
1697 your cell must be listed in the <SPAN
1701 >/usr/afs/etc/UserList</B
1703 > file on every database server machine
1704 that stores the Backup Database and Volume Location Database (VLDB), and every machine that houses a volume included in a volume
1705 set. By convention, the <SPAN
1711 > file is the same on every server machine in the cell; the
1712 instructions in this document assume that your cell is configured in this way. To edit the <SPAN
1718 > file, use the <SPAN
1731 > commands as described in <A
1732 HREF="c32432.html#HDRWQ592"
1733 >Administering the UserList File</A
1736 >In addition to being listed in the <SPAN
1742 > file, backup operators who issue the
1749 > command must be able to write to the files stored in each Tape Coordinator machine's local
1756 > directory, which are protected by UNIX mode bits. Before configuring your
1757 cell's first Tape Coordinator machine, decide which local user and group to designate as the owner of the directory and the
1758 files in it. Among the possible ownership options are the following: <UL
1761 >The local superuser <SPAN
1767 >. With this option, the issuer of the <SPAN
1773 > command must log onto the local file system as the local superuser <SPAN
1779 >. If the Tape Coordinator is also a server machine, the <SPAN
1785 > flag is used on the <SPAN
1791 > command to construct a server
1792 ticket from the local <SPAN
1796 >/usr/afs/etc/KeyFile</B
1798 > file. On non-server machine, the issuer must
1805 > command to authenticate as an AFS administrator while logged in as
1816 >A single AFS administrator. Logging in and authenticating are a single step if an AFS-modified login utility is
1817 used. The administrator is the only user who can start the Tape Coordinator.</P
1821 >An administrative account for which several operators know the password. This allows them all to start the Tape
1827 >Another option is to define a group in the local group file (<SPAN
1834 which all backup operators belong. Then turn on the <SPAN
1846 > permission) in the group mode bits rather than the user mode bits of the <SPAN
1852 > directory and files in it. An advantage over the methods listed previously is that each
1853 operator can retain an individual administrative account for finer granularity in auditing.</P
1855 >For instructions on implementing your choice of protection methods, see <A
1856 HREF="c12776.html#HDRWQ261"
1858 Coordinator Machines and Tape Devices</A
1867 >Configuring Tape Coordinator Machines and Tape Devices</A
1870 >This section explains how to configure a machine as a Tape Coordinator machine, and how to configure or remove the Tape
1871 Coordinator associated with a single tape device or backup data file.</P
1879 >When configuring a tape device attached to an AIX system, you must set the device's tape block size to <SPAN
1885 > (zero) to indicate variable block size. If you do not, it is possible that devices attached to
1886 machines of other system types cannot read the tapes made on the AIX system. Use the AIX <SPAN
1893 program to verify or change the value of the tape block size for a tape device, as instructed in Sep <A
1894 HREF="c12776.html#LIWQ263"
1905 >To configure a Tape Coordinator machine</A
1911 >Verify that you are authenticated as a user listed in the <SPAN
1915 >/usr/afs/etc/UserList</B
1918 file. If necessary, issue the <SPAN
1924 > command, which is fully described in <A
1925 HREF="c32432.html#HDRWQ593"
1926 >To display the users in the UserList file</A
1928 CLASS="programlisting"
1944 >Become the local superuser <SPAN
1950 > on the machine, if you are not already, by issuing
1958 CLASS="programlisting"
1978 >Install one or more tape devices on the Tape Coordinator machine according to the
1979 manufacturer's instructions. The Backup System can track a maximum of 58,511 tape devices or backup data files per
1982 >If the Tape Coordinator machine is an AIX system, issue the following command to change the tape device's tape block
1989 > (zero), which indicates variable block size. Repeat for each tape
1992 CLASS="programlisting"
2003 >' -a block_size='0'</B
2008 >where device_name is the tape device's device name (for example, <SPAN
2018 >Verify that the binary files for the <SPAN
2037 > commands are available on the local disk. If the machine is an AFS client, the
2038 conventional location is the <SPAN
2045 CLASS="programlisting"
2050 >ls /usr/afsws/etc</B
2064 > directory. (If the Tape Coordinator machine is also configured
2065 as a file server machine, this directory already exists.) Then create the <SPAN
2073 CLASS="programlisting"
2085 >mkdir /usr/afs/backup</B
2093 >Use a text editor to create the <SPAN
2097 >/usr/afs/backup/tapeconfig</B
2099 > file. Include a single
2100 line for each tape device or backup data file, specifying the following information in the indicated order. For syntax
2101 details and suggestions on the values to use in each field, see <A
2102 HREF="c12776.html#HDRWQ258"
2103 >Configuring the tapeconfig
2108 >The capacity of tapes to be used in the device, or the size of the backup data file</P
2112 >The device's filemark size</P
2116 >The device's device name, starting with the string <SPAN
2126 >The device's port offset number</P
2133 >Decide which user and group are to own the <SPAN
2139 > directory and <SPAN
2143 >/usr/afs/backup/tapeconfig</B
2145 > file, based on the suggestions in <A
2146 HREF="c12776.html#HDRWQ260"
2148 Administrative Privilege to Backup Operators</A
2149 >. Correct the UNIX mode bits on the directory and file, if necessary.
2151 CLASS="programlisting"
2175 >/usr/afs/backup/tapeconfig</B
2201 >/usr/afs/backup/tapeconfig</B
2208 >chmod 774 /usr/afs/backup</B
2215 >chmod 664 /usr/afs/backup/tapeconfig</B
2224 NAME="LICONFTC-ADDHOST"
2232 > command to create a Tape
2233 Coordinator entry in the Backup Database. Repeat the command for each Tape Coordinator. <PRE
2234 CLASS="programlisting"
2243 >tape machine name</VAR
2246 >TC port offset</VAR
2252 CLASS="variablelist"
2264 >Is the shortest acceptable abbreviation of <SPAN
2277 >tape machine name</B
2282 >Specifies the Tape Coordinator machine's fully qualified hostname.</P
2294 >Specifies the tape device's port offset number. Provide the same value as you specified for the device in
2301 > file. You must provide this argument unless the default value of 0
2302 (zero) is appropriate.</P
2316 >To configure an additional Tape Coordinator on an existing Tape Coordinator machine</A
2322 >Verify that you are authenticated as a user listed in the <SPAN
2326 >/usr/afs/etc/UserList</B
2329 file. If necessary, issue the <SPAN
2335 > command, which is fully described in <A
2336 HREF="c32432.html#HDRWQ593"
2337 >To display the users in the UserList file</A
2339 CLASS="programlisting"
2355 >Become the local superuser <SPAN
2361 > on the machine, if you are not already, by issuing
2369 CLASS="programlisting"
2386 >Install the tape device on the Tape Coordinator machine according to the manufacturer's instructions.</P
2388 >If the Tape Coordinator machine is an AIX system, issue the following command to change the tape device's tape block
2395 > (zero), which indicates variable block size.</P
2397 CLASS="programlisting"
2408 >' -a block_size='0'</B
2415 >Choose the port offset number to assign to the tape device. If necessary, use the <SPAN
2422 > command to display the port offset numbers that are already used; for a discussion of the output, see
2424 HREF="c12776.html#HDRWQ264"
2425 >To display the list of configured Tape Coordinators</A
2427 CLASS="programlisting"
2432 >backup listhosts</B
2444 > is the shortest acceptable abbreviation of <SPAN
2454 >Use a text editor to add one or more entries for the device to the <SPAN
2458 >/usr/afs/backup/tapeconfig</B
2460 > file. Specify the following information in the indicated order. For
2461 syntax details and suggestions on the values to use in each field, see <A
2462 HREF="c12776.html#HDRWQ258"
2463 >Configuring the tapeconfig
2468 >The capacity of tapes to be used in the device, or the size of the backup data file</P
2472 >The device's filemark size</P
2476 >The device's device name, starting with the string <SPAN
2486 >The device's port offset number</P
2499 > command to create an entry in the Backup Database for the
2500 Tape Coordinator. For complete syntax, see Step <A
2501 HREF="c12776.html#LICONFTC-ADDHOST"
2504 HREF="c12776.html#HDRWQ262"
2506 configure a Tape Coordinator machine</A
2508 CLASS="programlisting"
2517 >tape machine name</VAR
2520 >TC port offset</VAR
2533 >To unconfigure a Tape Coordinator</A
2539 >Verify that you are authenticated as a user listed in the <SPAN
2543 >/usr/afs/etc/UserList</B
2546 file. If necessary, issue the <SPAN
2552 > command, which is fully described in <A
2553 HREF="c32432.html#HDRWQ593"
2554 >To display the users in the UserList file</A
2556 CLASS="programlisting"
2572 >Using a text editor, remove each of the Tape Coordinator's entries from the <SPAN
2576 >/usr/afs/backup/tapeconfig</B
2588 > command to delete the Tape Coordinator's Backup Database
2590 CLASS="programlisting"
2599 >tape machine name</VAR
2602 >TC port offset</VAR
2608 CLASS="variablelist"
2620 >Is the shortest acceptable abbreviation of <SPAN
2633 >tape machine name</B
2638 >Is the complete Internet host name of the Tape Coordinator machine.</P
2650 >Is the same port offset number removed from the <SPAN
2657 provide this argument unless the default value of <SPAN
2663 > (zero) is appropriate.</P
2677 >To display the list of configured Tape Coordinators</A
2687 >backup listhosts</B
2689 > command to list the Tape Coordinators and port offset
2690 numbers currently configured in the Backup Database. <PRE
2691 CLASS="programlisting"
2696 >backup listhosts</B
2703 CLASS="variablelist"
2715 >Is the shortest acceptable abbreviation of <SPAN
2729 >The output lists each Tape Coordinator machine and the port offset numbers currently allocated to it in the Backup
2730 Database. The appearance of a port offset number does not imply that the associated Tape Coordinator is actually running.
2731 Machine names appear in the format in which they were specified with the <SPAN
2740 >The following example output lists the Tape Coordinators currently defined in the Backup Database of the ABC Corporation
2743 CLASS="programlisting"
2748 >backup listhosts</B
2752 Host backup1.abc.com, port offset 0
2753 Host backup1.abc.com, port offset 2
2754 Host backup2.abc.com, port offset 1
2755 Host backup2.abc.com, port offset 3
2765 >Defining and Displaying Volume Sets and Volume Entries</A
2768 >The Backup System handles data at the level of volumes rather than individual files. You must define groups of volumes
2775 > before performing backup operations, by using the <SPAN
2782 > command. A volume set name can be up to 31 characters long and can include any character other than the
2789 >), but avoid using metacharacters that have special meanings to the shell.</P
2791 >After creating a volume set, use the <SPAN
2795 >backup addvolentry</B
2797 > command to place one or more
2804 > in it. They define the volumes that belong to it in terms of their location (file server
2805 machine and partition) and name. Use the command's required <SPAN
2811 > argument to designate the
2812 file server machine that houses the volumes of interest and its required <SPAN
2819 designate the partition. Two types of values are acceptable: <UL
2822 >The fully qualified hostname of one machine or full name of one partition (such as <SPAN
2832 >The regular expression <SPAN
2838 > (period and asterisk), which matches every machine name
2839 or partition name in the VLDB</P
2844 >For the volume name (the required <SPAN
2850 > argument), specify a combination of
2851 alphanumeric characters and one or more metacharacters to specify part or all of the volume name with a wildcard. You can use
2852 any of the following metacharacters in the volume name field: <DIV
2853 CLASS="variablelist"
2865 >The period matches any single character.</P
2877 >The asterisk matches zero or more instances of the preceding character. Combine it with any other alphanumeric
2878 character or metacharacter.</P
2890 >Square brackets around a list of characters match a single instance of any of the characters, but no other
2891 characters; for example, <SPAN
2897 > matches a single <SPAN
2929 >. You can combine this expression with the asterisk.</P
2941 >The caret, when used as the first character in a square-bracketed set, designates a match with any single
2942 character other than the characters that follow it; for example, <SPAN
2949 single character except lowercase <SPAN
2955 >. You can combine this expression with the
2968 >A backslash preceding any of the metacharacters in this list makes it match its literal value only. For example,
2969 the expression <SPAN
2975 > (backslash and period) matches a single period, <SPAN
2981 > matches a single asterisk, and <SPAN
2987 > matches a single backslash.
2988 You can combine such expressions with the asterisk (for example, <SPAN
2994 > matches any number
3001 >Perhaps the most common regular expression is the period followed by an asterisk (<SPAN
3008 This expression matches any string of any length, because the period matches any character and the asterisk means any number of
3009 that character. As mentioned, it is the only acceptable regular expression in the file server and partition fields of a volume
3010 entry. In the volume name field, it can stand alone (in which case it matches every volume listed in the VLDB), or can combine
3011 with alphanumeric characters. For example, the string <SPAN
3017 > matches any volume name
3018 that begins with the string <SPAN
3024 > and ends with <SPAN
3036 >backup addvolentry</B
3038 > command in interactive mode is simplest. If you issue it
3039 at the shell prompt, you must surround any string that includes a regular expression with double quotes (<SPAN
3046 >) so that the shell passes them uninterpreted to the <SPAN
3052 > command interpreter
3053 rather than resolving them.</P
3055 >To define various combinations of volumes, provide the following types of values for the <SPAN
3062 > command's three arguments. The list uses the notation appropriate for interactive mode; if you issue the
3063 command at the shell prompt instead, place double quotes around any string that includes a regular expression. To create a
3064 volume entry that includes: <UL
3067 >All volumes listed in the VLDB, use the regular expression <SPAN
3078 >-server .* -partition .* -volume .*</B
3084 >Every volume on a specific file server machine, specify its fully qualified hostname as the <SPAN
3090 > argument and use the regular expression <SPAN
3109 > arguments (for example: <SPAN
3113 >-server fs1.abc.com -partition .* -volume .*</B
3119 >All volumes that reside on a partition with the same name on various file server machines, specify the complete
3120 partition name as the <SPAN
3126 > argument and use the regular expression <SPAN
3145 arguments (for example: <SPAN
3149 >-server .* -partition /vicepd -volume .*</B
3155 >Every volume with a common string in its name, use the regular expression <SPAN
3174 > arguments, and provide a
3175 combination of alphanumeric characters and metacharacters as the <SPAN
3186 >-server .* -partition .* -volume .*\.backup</B
3188 > includes all volumes whose names end
3199 >All volumes on one partition, specify the machine's fully qualified hostname as the <SPAN
3205 > argument and the full partition name as the <SPAN
3212 argument, and use the regular expression <SPAN
3224 > argument (for example: <SPAN
3228 >-server fs2.abc.com -partition /vicepb -volume
3235 >A single volume, specify its complete name as the <SPAN
3241 > argument. To bypass the
3242 potentially time-consuming search through the VLDB for matching entries, you can specify an actual machine and partition
3256 respectively. However, if it is possible that you need to move the volume in future, it is best to use the regular
3263 > for the machine and partition name.</P
3268 >As you create volume sets, define groups of volumes you want to dump to the same tape at the same time (for example,
3269 weekly or daily) and in the same manner (fully or incrementally). In general, a volume set that includes volumes with similar
3270 contents (as indicated by similar names) is more useful than one that includes volumes that share a common location, especially
3271 if you often move volumes for load-balancing or space reasons. Most often, then, it is appropriate to use the regular expression
3278 > (period followed by a backslash) for the <SPAN
3291 > arguments to the <SPAN
3295 >backup addvolentry</B
3299 >It is generally more efficient to include a limited number of volumes in a volume entry. Dumps of a volume set that
3300 includes a large number of volume can take a long time to complete, increasing the possibility that the operation fails due to a
3301 service interruption or outage.</P
3303 >To remove a volume entry from a volume set, use the <SPAN
3307 >backup delvolentry</B
3309 > command. To remove
3310 a volume set and all of its component volume entries from the Backup Database, use the <SPAN
3317 > command. To display the volume entries in a volume set, use the <SPAN
3326 >By default, a Backup Database record is created for the new volume set. Sometimes it is convenient to create volume sets
3327 without recording them permanently in the Backup Database, for example when using the <SPAN
3334 > command to restore a group of volumes that were not necessarily backed up together (for further
3336 HREF="c15383.html#HDRWQ312"
3337 >Using the backup volsetrestore Command</A
3345 > volume set, include the <SPAN
3355 >backup addvolset</B
3357 > command. A temporary volume set exists only during the lifetime of the current
3358 interactive session, so the flag is effective only when used during an interactive session (opened by issuing the <SPAN
3362 >backup (interactive)</B
3364 > command). You can use the <SPAN
3368 >backup delvolset</B
3371 to delete a temporary volume set before the interactive session ends, if you wish, but as noted it is automatically deleted when
3372 you end the session. One advantage of temporary volume sets is that the <SPAN
3376 >backup addvolset</B
3379 command, and any <SPAN
3383 >backup addvolentry</B
3385 > commands subsequently used to add volume entries to it,
3386 complete more quickly than for regular volume sets, because you are not creating any Backup Database records.</P
3393 >To create a volume set</A
3399 >Verify that you are authenticated as a user listed in the <SPAN
3403 >/usr/afs/etc/UserList</B
3406 file. If necessary, issue the <SPAN
3412 > command, which is fully described in <A
3413 HREF="c32432.html#HDRWQ593"
3414 >To display the users in the UserList file</A
3416 CLASS="programlisting"
3445 interactive mode. If you are going to define volume entries right away with the <SPAN
3452 > command, this eliminates the need to surround metacharacter expressions with double quotes. You
3453 must enter interactive mode if creating a temporary volume set. <PRE
3454 CLASS="programlisting"
3471 >(backup) addvolset</B
3473 > command to create the volume set. You must then issue
3478 >(backup) addvolentry</B
3480 > command to define volume entries in it. <PRE
3481 CLASS="programlisting"
3482 > backup> <SPAN
3490 >volume set name</VAR
3502 CLASS="variablelist"
3514 >Is the shortest acceptable abbreviation of <SPAN
3532 >Names the volume set. The name can include no more than 31 characters, cannot include periods, and must be
3533 unique within the Backup Database. (A temporary volume set can have the same name as an existing permanent volume
3534 set, but this is not recommended because of the confusion it can cause.)</P
3546 >Creates a temporary volume set, which exists only during the current interactive session.</P
3560 >To add a volume entry to a volume set</A
3566 >Verify that you are authenticated as a user listed in the <SPAN
3570 >/usr/afs/etc/UserList</B
3573 file. If necessary, issue the <SPAN
3579 > command, which is fully described in <A
3580 HREF="c32432.html#HDRWQ593"
3581 >To display the users in the UserList file</A
3583 CLASS="programlisting"
3612 interactive mode if you have not already. This makes it simpler to use metacharacter expressions, because you do not need
3613 to surround them with double quotes. If you are adding entries to a temporary volume set, you must already have entered
3614 interactive mode before creating the volume set. <PRE
3615 CLASS="programlisting"
3632 >(backup) addvolentry</B
3634 > command to define volume entries in an existing
3635 volume set. The Backup System assigns each volume entry an index within the volume set, starting with 1 (one).
3637 CLASS="programlisting"
3638 > backup> <SPAN
3642 >addvolentry -name</B
3646 >volume set name</VAR
3666 >partition name</VAR
3676 >volume name (regular expression)</VAR
3682 CLASS="variablelist"
3694 >Is the shortest acceptable abbreviation of <SPAN
3712 >Names the volume set to which to add the volume entry. It must already exist (use the <SPAN
3716 >backup addvolset</B
3718 > command to create it).</P
3730 >Defines the set of one or more file server machines that house the volumes in the volume entry. Provide
3731 either one fully-qualified hostname (such as <SPAN
3737 >) or the metacharacter
3744 > (period and asterisk), which matches all machine names in the
3757 >Defines the set of one or more partitions that house the volumes in the volume entry. Provide either one
3758 complete partition name (such as <SPAN
3764 >) or the metacharacter expression
3771 > (period and asterisk), which matches all partition names.</P
3783 >Defines the set of one or more volumes included in the volume entry, identifying them by name. This argument
3784 can include a combination of alphanumeric characters and one or more of the metacharacter expressions discussed in
3785 the introductory material in this section.</P
3799 >To display volume sets and volume entries</A
3809 >backup listvolsets</B
3811 > command to display the volume entries in a specific
3812 volume set or all of them. If you are displaying a temporary volume set, you must still be in the interactive session in
3813 which you created it. <PRE
3814 CLASS="programlisting"
3819 >backup listvolsets</B
3823 >volume set name</VAR
3829 CLASS="variablelist"
3841 >Is the shortest acceptable abbreviation of <SPAN
3859 >Names the volume set to display. Omit this argument to display all defined volume sets.</P
3865 >The output from the command uses the wildcard notation used when the volume entries were created. The string
3867 CLASS="computeroutput"
3869 > marks a temporary volume set. The following example displays all three of the
3870 volume sets defined in a cell's Backup Database, plus a temporary volume set <SPAN
3877 created during the current interactive session:</P
3879 CLASS="programlisting"
3880 > backup> <SPAN
3887 Volume set pat+jones (temporary):
3888 Entry 1: server fs1.abc.com, partition /vicepe, volumes: user.pat.backup
3889 Entry 2: server fs5.abc.com, partition /viceph, volumes: user.jones.backup
3891 Entry 1: server .*, partition .*, volumes: user.*\.backup
3893 Entry 1: server .*, partition .*, volumes: sun4x_55\..*
3894 Entry 2: server .*, partition .*, volumes: sun4x_56\..*
3896 Entry 1: server .*, partition .*, volumes: rs_aix42\..*
3907 >To delete a volume set</A
3913 >Verify that you are authenticated as a user listed in the <SPAN
3917 >/usr/afs/etc/UserList</B
3920 file. If necessary, issue the <SPAN
3926 > command, which is fully described in <A
3927 HREF="c32432.html#HDRWQ593"
3928 >To display the users in the UserList file</A
3930 CLASS="programlisting"
3950 >backup delvolset</B
3952 > command to delete one or more volume sets and all of the
3953 component volume entries in them. If you are deleting a temporary volume set, you must still be in the interactive session
3954 in which you created it. <PRE
3955 CLASS="programlisting"
3960 >backup delvolset</B
3964 >volume set name</VAR
3970 CLASS="variablelist"
3982 >Is the shortest acceptable abbreviation of <SPAN
4000 >Names each volume set to delete.</P
4014 >To delete a volume entry from a volume set</A
4020 >Verify that you are authenticated as a user listed in the <SPAN
4024 >/usr/afs/etc/UserList</B
4027 file. If necessary, issue the <SPAN
4033 > command, which is fully described in <A
4034 HREF="c32432.html#HDRWQ593"
4035 >To display the users in the UserList file</A
4037 CLASS="programlisting"
4059 > command to enter interactive mode. <PRE
4060 CLASS="programlisting"
4073 >If the volume set includes more than one volume entry, issue the <SPAN
4080 > command to display the index number associated with each one (if there is only one volume entry,
4081 its index is 1). For a more detailed description of the command's output, see <A
4082 HREF="c12776.html#HDRWQ266"
4084 sets and volume entries</A
4086 CLASS="programlisting"
4087 > backup> <SPAN
4095 >volume set name</VAR
4101 CLASS="variablelist"
4113 >Is the shortest acceptable abbreviation of <SPAN
4131 >Names the volume set for which to display volume entries.</P
4143 >(backup) delvolentry</B
4145 > command to delete the volume entry. <PRE
4146 CLASS="programlisting"
4147 > backup> <SPAN
4155 >volume set name</VAR
4158 >volume entry index</VAR
4164 CLASS="variablelist"
4176 >Is the shortest acceptable abbreviation of <SPAN
4194 >Names the volume set from which to delete a volume entry.</P
4201 >volume entry index</B
4206 >Specifies the index number of the volume entry to delete.</P
4221 >Defining and Displaying the Dump Hierarchy</A
4224 >A dump hierarchy is a logical structure in the Backup Database that defines the relationship between full and incremental
4225 dumps; that is, it defines which dump serves as the parent for an incremental dump. Each individual component of a hierarchy is
4228 >As you define dump levels with the <SPAN
4234 > command, keep the following rules and
4235 suggestions in mind: <UL
4238 >Each full dump level is the top level of a hierarchy. You can create as many hierarchies as you need to dump
4239 different volume sets on different schedules.</P
4243 >The name of a full dump level consists of an initial slash (<SPAN
4250 string of up to 28 alphanumeric characters.</P
4254 >The name of an incremental dump level resembles a pathname, starting with the name of a full dump level, then the
4255 first incremental level, and so on, down to the final incremental level. Precede each level name with a slash to separate
4256 it from the preceding level. Like the full level, each component level in the name can have up to 28 alphanumeric
4257 characters, not including the slash.</P
4261 >A hierarchy can have any have any number of levels, but the maximum length of a complete dump level name is 256
4262 characters, including the slashes.</P
4266 >Before defining a given incremental level, you must define all of the levels above it in the hierarchy.</P
4270 >Do not use the period (<SPAN
4276 >) in dump level names. The Backup System uses the period as
4277 the separator between a dump's volume set name and dump level name when it creates the dump name and AFS tape name. Any
4278 other alphanumeric and punctuation characters are allowed, but it is best to avoid metacharacters. If you include a
4279 metacharacter, you must precede it with a backslash (<SPAN
4285 >) or surround the entire dump level
4286 name with double quotes (<SPAN
4296 >Naming dump levels for days or other actual time points reminds you when to perform dumps, and makes it easier to
4297 track the relationship between dumps performed at different levels. However, the names have no meaning to the Backup
4298 System: it does not automatically create dumps according to the names, and does not prevent you from, for example, using
4305 > level when creating a dump on a Tuesday.</P
4309 >It is best not to use the same name for more than one component level in a hierarchy, because it means the resulting
4310 dump name no longer indicates which level was used. For example, if you name a dump level <SPAN
4316 >, then the dump name and AFS tape name that result from dumping a volume set at the
4317 first incremental level (<SPAN
4323 >) look the same as the names that result from dumping
4324 at the second incremental level (<SPAN
4334 >Individual levels in different hierarchies can have the same name, but the complete pathnames must be unique. For
4348 same name at the final level, but are unique because they have different names at the full level (belong to different
4349 hierarchies). However, using the same name in multiple hierarchies means that dump and AFS tape names do not unambiguously
4350 indicate which hierarchy was used.</P
4355 >The following example shows three hierarchies. Each begins with a full dump at the top: <SPAN
4361 > for the first hierarchy, <SPAN
4367 > for the second hierarchy, and
4374 > for the third hierarchy. In all three hierarchies, each of the other dump levels is
4375 an incremental level.</P
4377 CLASS="programlisting"
4396 >In the first hierarchy, each incremental dump level refers to the full level <SPAN
4403 its parent. When (for example) you dump a volume set at the <SPAN
4407 >/sunday1/wednesday</B
4410 includes data that has changed since the volume set was dumped at the <SPAN
4418 >In contrast, each incremental dump level in the second hierarchy refers to the immediately preceding dump level as its
4419 parent. When you dump a volume set at the corresponding level in the second hierarchy (<SPAN
4423 >/sunday2/monday/tuesday/wednesday</B
4425 >), the dump includes only data that has changed since the volume set was
4430 >/sunday2/monday/tuesday</B
4432 > level (presumably the day before). Assuming you create
4433 dumps on the indicated days, an incremental dump made using this hierarchy contains less data than an incremental dump made at
4434 the corresponding level in the first hierarchy.</P
4436 >The third hierarchy is more appropriate for dumping volumes for which a daily backup is excessive because the data does
4437 not change often (for example, system binaries).</P
4444 >Creating a Tape Recycling Schedule</A
4447 >If your cell is like most cells, you have a limited amount of room for storing backup tapes and a limited budget for new
4448 tapes. The easiest solution is to recycle tapes by overwriting them when you no longer need the backup data on them. The
4449 Backup System helps you implement a recycling schedule by enabling you to associate an expiration date with each dump level.
4450 The expiration date defines when a dump created at that level expires. Until that time the Backup System refuses to overwrite
4451 a tape that contains the dump. Thus, assigning expiration dates automatically determines how you recycle tapes.</P
4453 >When designing a tape-recycling schedule, you must decide how far in the past and to what level of precision you want to
4454 guarantee access to backed up data. For instance, if you decide to guarantee that you can restore a user's home volume to its
4455 state on any given day in the last two weeks, you cannot recycle the tape that contains a given daily dump for at least two
4456 weeks after you create it. Similarly, if you decide to guarantee that you can restore home volumes to their state at the
4457 beginning of any given week in the last month, you cannot recycle the tapes in a dump set containing a weekly dump for at
4458 least four weeks. The following example dump hierarchy implements this recycling schedule by setting the expiration date for
4459 each daily incremental dump to 13 days and the expiration date of the weekly full dumps to 27 days.</P
4461 >The tapes used to store dumps created at the daily incremental levels in the <SPAN
4468 hierarchy expire just in time to be recycled for daily dumps in the <SPAN
4475 vice versa), and there is a similar relationship between the <SPAN
4487 > hierarchies. Similarly, the tape that houses a full dump at the <SPAN
4493 > level expires just in time to be used for a full dump on the first Sunday of the following
4496 CLASS="programlisting"
4497 > /sunday1 expires in 27d
4498 /monday1 expires in 13d
4499 /tuesday1 expires in 13d
4500 /wednesday1 expires in 13d
4501 /thursday1 expires in 13d
4502 /friday1 expires in 13d
4503 /sunday2 expires in 27d
4504 /monday2 expires in 13d
4505 /tuesday2 expires in 13d
4506 /wednesday2 expires in 13d
4507 /thursday2 expires in 13d
4508 /friday2 expires in 13d
4509 /sunday3 expires in 27d
4510 /monday1 expires in 13d
4511 /tuesday1 expires in 13d
4512 /wednesday1 expires in 13d
4513 /thursday1 expires in 13d
4514 /friday1 expires in 13d
4515 /sunday4 expires in 27d
4516 /monday2 expires in 13d
4517 /tuesday2 expires in 13d
4518 /wednesday2 expires in 13d
4519 /thursday2 expires in 13d
4520 /friday2 expires in 13d
4523 >If you use appended dumps in your cell, keep in mind that all dumps in a dump set are subject to the latest (furthest
4524 into the future) expiration date associated with any of the constituent dumps. You cannot recycle any of the tapes that
4525 contain a dump set until all of the dumps have reached their expiration date. See also <A
4526 HREF="c15383.html#HDRWQ299"
4528 Dumps to an Existing Dump Set</A
4531 >Most tape manufacturers recommend that you write to a tape a limited number of times, and it is best not to exceed this
4532 limit when recycling tapes. To help you track tape usage, the Backup System records a
4534 CLASS="computeroutput"
4536 > counter on the tape's label. It increments the counter each time the tape's label is
4537 rewritten (each time you use the <SPAN
4541 >backup labeltape</B
4550 > command). To display the <SAMP
4551 CLASS="computeroutput"
4553 > counter, use the <SPAN
4557 >backup readlabel</B
4565 > command or include the <SPAN
4577 > options when you issue the <SPAN
4583 > command. For instructions see <A
4584 HREF="c12776.html#HDRWQ272"
4585 >Writing and Reading Tape
4588 HREF="c15383.html#HDRWQ302"
4589 >Displaying Backup Dump Records</A
4601 >Even if you make extensive use of tape recycling, there is probably some backup data that you need to archive for a long
4602 (or even an indefinite) period of time. You can use the Backup System to archive data on a regular schedule, and you can also
4603 choose to archive data on tapes that you previously expected to recycle.</P
4605 >If you want to archive data on a regular basis, you can create date-specific dump levels in the dump hierarchy. For
4606 example, if you decide to archive a full dump of all data in your cell at the beginning of each quarter in the year 2000, you
4607 can define the following levels in the dump hierarchy:</P
4609 CLASS="programlisting"
4616 >If you decide to archive data that is on tapes you previously planned to recycle, you must gather all of the tapes that
4617 contain the relevant dumps, both full and incremental. To avoid accidental erasure, it is best to set the switch on the tapes
4618 that makes them read-only, before placing them in your archive storage area. If the tapes also contain a large amount of
4619 extraneous data that you do not want to archive, you can restore just the relevant data into a new temporary volume, and back
4620 up that volume to the smallest number of tapes possible. One reason to keep a dump set small is to minimize the amount of
4621 irrelevant data in a dump set you end up needing to archive.</P
4623 >If you do not expect to restore archived data to the file system, you can consider using the <SPAN
4627 >backup deletedump</B
4629 > command to remove the associated dump records from the Backup Database, which helps
4630 keep it to an efficient size. If you ever need to restore the data, you can use the <SPAN
4643 > command to reinsert the dump records into the database. For
4644 instructions, see <A
4645 HREF="c15383.html#HDRWQ305"
4646 >To scan the contents of a tape</A
4655 >Defining Expiration Dates</A
4658 >To associate an expiration date with a dump level as you create it, use the <SPAN
4665 argument to the <SPAN
4671 > command. To change an existing dump level's expiration date,
4678 > argument to the <SPAN
4685 (Note that it is not possible to change the expiration date of an actual dump that has already been created at that level).
4686 With both commands, you can define an expiration date either in absolute terms (for example, 13 January 2000) or relative
4687 terms (for example, 30 days from when the dump is created). <UL
4690 >To define an absolute expiration date, provide a value for the <SPAN
4697 with the following format: <PRE
4698 CLASS="programlisting"
4727 >where mm indicates the month, dd the day, and yyyy the year when the dump expires. Valid values for the year fall
4740 > (the latest possible
4741 date that the UNIX time representation can express is in early 2038). If you provide a time, it must be in 24-hour
4742 format with hh the hours and MM the minutes (for example, <SPAN
4748 > is 9:50 p.m.). If you
4749 omit the time, the default is 00:00 hours (12:00 midnight) on the indicated date.</P
4753 >To define a relative expiration date, provide a value for the <SPAN
4760 with the following format: <PRE
4761 CLASS="programlisting"
4790 >where each of years, months, and days is an integer. Provide at least one of them together with the corresponding
4809 > respectively), with no intervening space. If you provide more than one of the three, list them
4810 in the indicated order.</P
4812 >The Backup System calculates a dump's actual expiration date by adding the indicated relative value to the start
4813 time of the dump operation. For example, it assigns an expiration date 1 year, 6 months, and 2 days in the future to a
4814 dump created at a dump level with associated expiration date <SPAN
4824 >To indicate that a dump backed up at the corresponding dump level never expires, provide the value <SPAN
4830 > instead of a date and time. To recycle tapes that contain dumps created at such a level,
4831 you must use the <SPAN
4835 >backup readlabel</B
4837 > command to overwrite the tape's label.</P
4842 >If you omit the <SPAN
4848 > argument to the <SPAN
4855 > command, then the expiration date is set to UNIX time zero (00:00 hours on 1 January 1970). The Backup
4856 System considers dumps created at such a dump level to expire at their creation time. If no dumps in a dump set have an
4857 expiration date, then the Backup System does not impose any restriction on recycling the tapes that contain the dump set. If
4858 you need to prevent premature recycling of the tapes that contain the dump set, you must use a manual tracking system.</P
4866 >To add a dump level to the dump hierarchy</A
4872 >Verify that you are authenticated as a user listed in the <SPAN
4876 >/usr/afs/etc/UserList</B
4879 file. If necessary, issue the <SPAN
4885 > command, which is fully described in <A
4886 HREF="c32432.html#HDRWQ593"
4887 >To display the users in the UserList file</A
4889 CLASS="programlisting"
4918 interactive mode. <PRE
4919 CLASS="programlisting"
4938 > command to define one or more dump levels. If you are
4939 defining an incremental level, then all of the parent levels that precede it in its pathname must either already exist or
4940 precede it on the command line. <PRE
4941 CLASS="programlisting"
4942 > backup> <SPAN
4950 >dump level name</VAR
4959 >expiration date</VAR
4965 CLASS="variablelist"
4977 >Is the shortest acceptable abbreviation of <SPAN
4995 >Names each dump level to added. If you specify more than one dump level name, you must include the <SPAN
5003 >Provide the entire pathname of the dump level, preceding each level in the pathname with a slash (<SPAN
5009 >). Each component level can be up to 28 characters in length, and the pathname can include
5010 up to 256 characters including the slashes.</P
5022 >Sets the expiration date associated with each dump level. Specify either a relative or absolute expiration
5023 date, as described in <A
5024 HREF="c12776.html#HDRWQ270"
5025 >Defining Expiration Dates</A
5026 >, or omit this argument to assign
5027 no expiration date to the dump levels.</P
5035 >A plus sign follows this argument in the command's syntax statement because it accepts a multiword value
5036 which does not need to be enclosed in double quotes or other delimiters, not because it accepts multiple dates.
5037 Provide only one date (and optionally, time) definition to be associated with each dump level specified by the
5060 >To change a dump level's expiration date</A
5066 >Verify that you are authenticated as a user listed in the <SPAN
5070 >/usr/afs/etc/UserList</B
5073 file. If necessary, issue the <SPAN
5079 > command, which is fully described in <A
5080 HREF="c32432.html#HDRWQ593"
5081 >To display the users in the UserList file</A
5083 CLASS="programlisting"
5112 interactive mode. <PRE
5113 CLASS="programlisting"
5132 > command to change the expiration date associated with one
5133 or more dump levels. <PRE
5134 CLASS="programlisting"
5135 > backup> <SPAN
5143 >dump level name</VAR
5152 >expiration date</VAR
5158 CLASS="variablelist"
5170 >Is the shortest acceptable abbreviation of <SPAN
5188 >Names each existing dump level for which to change the expiration date.</P
5200 >Sets the expiration date associated with each dump level. Specify either a relative or absolute expiration
5201 date, as described in <A
5202 HREF="c12776.html#HDRWQ270"
5203 >Defining Expiration Dates</A
5204 >; omit this argument to remove the
5205 expiration date currently associated with each dump level.</P
5213 >A plus sign follows this argument in the command's syntax statement because it accepts a multiword value
5214 which does not need to be enclosed in double quotes or other delimiters, not because it accepts multiple dates.
5215 Provide only one date (and optionally, time) definition to be associated with each dump level specified by the
5238 >To delete a dump level from the dump hierarchy</A
5244 >Verify that you are authenticated as a user listed in the <SPAN
5248 >/usr/afs/etc/UserList</B
5251 file. If necessary, issue the <SPAN
5257 > command, which is fully described in <A
5258 HREF="c32432.html#HDRWQ593"
5259 >To display the users in the UserList file</A
5261 CLASS="programlisting"
5290 interactive mode. <PRE
5291 CLASS="programlisting"
5308 >(backup) deldump</B
5310 > command to delete the dump level. Note that the command
5311 automatically removes all incremental dump levels for which the specified level serves as parent, either directly or
5313 CLASS="programlisting"
5314 > backup> <SPAN
5322 >dump level name</VAR
5328 CLASS="variablelist"
5340 >Is the shortest acceptable abbreviation of <SPAN
5358 >Specifies the complete pathname of the dump level to delete.</P
5372 >To display the dump hierarchy</A
5382 >backup listdumps</B
5384 > command to display the dump hierarchy. <PRE
5385 CLASS="programlisting"
5390 >backup listdumps</B
5402 > is the shortest acceptable abbreviation of <SPAN
5410 >The output from this command displays the dump hierarchy, reporting the expiration date associated with each dump
5411 level, as in the following example.</P
5413 CLASS="programlisting"
5418 >backup listdumps</B
5421 /week1 expires in 27d
5422 /tuesday expires in 13d
5423 /thursday expires in 13d
5424 /sunday expires in 13d
5425 /tuesday expires in 13d
5426 /thursday expires in 13d
5427 /week3 expires in 27d
5428 /tuesday expires in 13d
5429 /thursday expires in 13d
5430 /sunday expires in 13d
5431 /tuesday expires in 13d
5432 /thursday expires in 13d
5433 sunday1 expires in 27d
5434 /monday1 expires in 13d
5435 /tuesday1 expires in 13d
5436 /wednesday1 expires in 13d
5437 /thursday1 expires in 13d
5438 /friday1 expires in 13d
5439 sunday2 expires in 27d
5440 /monday2 expires in 13d
5441 /tuesday2 expires in 13d
5442 /wednesday2 expires in 13d
5443 /thursday2 expires in 13d
5444 /friday2 expires in 13d
5445 sunday3 expires in 27d
5446 /monday1 expires in 13d
5447 /tuesday1 expires in 13d
5448 /wednesday1 expires in 13d
5449 /thursday1 expires in 13d
5450 /friday1 expires in 13d
5451 sunday4 expires in 27d
5452 /monday2 expires in 13d
5453 /tuesday2 expires in 13d
5454 /wednesday2 expires in 13d
5455 /thursday2 expires in 13d
5456 /friday2 expires in 13d
5468 >Writing and Reading Tape Labels</A
5472 HREF="c12776.html#HDRWQ253"
5473 >Dump Names and Tape Names</A
5475 HREF="c12776.html#HDRWQ254"
5477 Labels, and EOF Markers</A
5478 >, you can assign either a permanent name or an AFS tape name to a tape that you use in the Backup
5479 System. The names are recorded on the tape's magnetic label, along with an indication of the tape's capacity (size).</P
5481 >You can assign either a permanent name or an AFS tape name, but not both. In general, assigning permanent names rather
5482 than AFS tape names simplifies the backup process, because the Backup System does not dictate the format of permanent names. If
5483 a tape does not have a permanent name, then by default the Backup System accepts only three strictly defined values in the AFS
5484 tape name field, and refuses to write a dump to a tape with an inappropriate AFS tape name. The acceptable values are a name
5485 that matches the volume set and dump level of the initial dump, the value <SAMP
5486 CLASS="computeroutput"
5487 ><NULL></SAMP
5489 value in the field at all.</P
5491 >If a tape has a permanent name, the Backup System does not check the AFS tape name, and as part of the dump operation
5492 constructs the appropriate AFS tape name itself and records it on the label. This means that if you assign a permanent name, the
5493 Backup System assigns an AFS tape name itself and the tape has both types of name. In contrast, if a tape has an AFS tape name
5494 but not a permanent name, you cannot assign a permanent name without first erasing the AFS tape name.</P
5496 >(You can also suppress the Backup System's check of a tape's AFS tape name, even it does not have a permanent name, by
5497 assigning the value <SPAN
5509 > instruction in the
5514 >device configuration file</I
5517 HREF="c12776.html#HDRWQ280"
5518 >Eliminating the AFS Tape Name Check</A
5521 >Because the Backup System accepts unlabeled tapes, you do not have to label a tape before using it for the first time.
5522 After the first use, there are a couple of cases in which you must relabel a tape in order to write a dump to it: <UL
5525 >The tape does not have a permanent name, and the AFS tape name on it does not match the new initial dump set you
5526 want to create (the volume set and dump level names are different, or the index is incorrect).</P
5530 >You want to recycle a tape before all of the dumps on it have expired. The Backup System does not overwrite a tape
5531 with any unexpired dumps. Keep in mind, though, that if you relabel the tape to making recycling possible, you erase all
5532 the dump records for the tape from the Backup Database, which makes it impossible to restore any data from the
5544 >Labeling a tape that contains dump data makes it impossible to use that data in a restore operation, because the
5545 labeling operation removes the dump's records from the Backup Database. If you want to record a permanent name on a tape
5546 label, you must do it before dumping any data to the tape.</P
5555 >Recording a Name on the Label</A
5558 >To write a permanent name on a tape's label, include the <SPAN
5564 > argument to specify a
5565 string of up to 32 characters. Check that no other tape used with the Backup System in your cell already has the permanent
5566 name you are assigning, because the Backup System does not prevent you from assigning the same name to multiple tapes. The
5567 Backup System overwrites the existing AFS tape name, if any, with the value <SAMP
5568 CLASS="computeroutput"
5569 ><NULL></SAMP
5571 When a tape has a permanent name, the Backup System uses it instead of the AFS tape name in most prompts and when referring to
5572 the tape in output from <SPAN
5578 > commands. The permanent name persists until you again include
5585 > argument to the <SPAN
5589 >backup labeltape</B
5592 regardless of the tape's contents and of how often you recycle the tape or use the <SPAN
5599 > command without the <SPAN
5607 >To write an AFS tape name on the label, provide a value for the <SPAN
5614 matches the volume set name and the final element in the dump level pathname of the initial dump that you plan to write to the
5615 tape, and an index that indicates the tape's place in the sequence of tapes for the dump set. The format is as follows:</P
5617 CLASS="programlisting"
5618 > volume_set_name<SPAN
5624 >dump_level_name<SPAN
5633 >If you omit the <SPAN
5639 > argument, the Backup System sets the AFS tape name to
5641 CLASS="computeroutput"
5642 ><NULL></SAMP
5643 >. The Backup System automatically constructs and records the appropriate name
5644 when you later write an initial dump to the tape by using the <SPAN
5658 >You cannot use the <SPAN
5664 > argument if the tape already has a permanent name. To erase a
5665 tape's permanent name, provide a null value to the <SPAN
5671 > argument by issuing the following
5674 CLASS="programlisting"
5679 >backup labeltape -pname ""</B
5690 >Recording a Capacity on the Label</A
5693 >To record the tape's capacity on the label, specify a number of kilobytes as the <SPAN
5700 argument. If you omit this argument the first time you label a tape, the Backup System records the default tape capacity
5701 associated with the specified port offset in the <SPAN
5705 >/usr/afs/backup/tapeconfig</B
5708 Coordinator machine. If the tape's capacity is different (in particular, larger) than the capacity recorded in the <SPAN
5714 > file, it is best to record a capacity on the label before using the tape. Once set, the
5715 value in the label's capacity field persists until you again use the <SPAN
5726 >backup labeltape</B
5728 > command. For a discussion of the appropriate capacity to record for tapes,
5730 HREF="c12776.html#HDRWQ258"
5731 >Configuring the tapeconfig File</A
5734 >To read a tape's label, use the <SPAN
5738 >backup readlabel</B
5742 >Most tapes also come with an adhesive label you can apply to the exterior casing. To help you easily identify a tape,
5743 record at least the tape's permanent and AFS tape names on the adhesive label. Depending on the recycling scheme you use, it
5744 can be useful to record other information, such as the dump ID, dump creation date, and expiration date of each dump you write
5759 >Verify that you are authenticated as a user listed in the <SPAN
5763 >/usr/afs/etc/UserList</B
5766 file. If necessary, issue the <SPAN
5772 > command, which is fully described in <A
5773 HREF="c32432.html#HDRWQ593"
5774 >To display the users in the UserList file</A
5776 CLASS="programlisting"
5792 >If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a
5793 connection to the appropriate Tape Coordinator machine and issue the <SPAN
5800 which complete instructions appear in <A
5801 HREF="c15383.html#HDRWQ292"
5802 >To start a Tape Coordinator process</A
5805 CLASS="programlisting"
5827 >Place the tape in the device.</P
5844 interactive mode, if you want to label multiple tapes or issue additional commands after labeling the tape. The
5845 interactive prompt appears in the following step. <PRE
5846 CLASS="programlisting"
5863 >(backup) labeltape</B
5865 > command to label the tape. <PRE
5866 CLASS="programlisting"
5867 > backup> <SPAN
5881 >tape name, defaults to NULL</VAR
5891 >tape size in Kbytes, defaults to size in tapeconfig</VAR
5901 >TC port offset</VAR
5910 >permanent tape name</VAR
5916 CLASS="variablelist"
5928 >Is the shortest acceptable abbreviation of <SPAN
5946 >Specifies the AFS tape name to record on the label. Include this argument or the <SPAN
5952 > argument, but not both. If you omit this argument, the AFS tape name is set to
5956 >>. If you provide it, it must have the following format. <PRE
5957 CLASS="programlisting"
5958 > volume_set_name<SPAN
5964 >dump_level_name<SPAN
5974 >for the tape to be acceptable for use in a future <SPAN
5981 The volume_set_name must match the volume set name of the initial dump to be written to the tape, dump_level_name
5982 must match the last element of the dump level pathname at which the volume set is to be dumped, and tape_index
5983 must correctly indicate the tape's place in the sequence of tapes that house the dump set; indexing begins with
5984 the number 1 (one).</P
5996 >Specifies the tape capacity to record on the label. If you are labeling the tape for the first time, you
5997 need to include this argument only if the tape's capacity differs from the capacity associated with the specified
5998 port offset in the <SPAN
6002 >/usr/afs/backup/tapeconfig</B
6004 > file on the Tape Coordinator
6007 >If you provide a value, it is an integer value followed by a letter that indicates units, with no
6008 intervening space. A unit value of <SPAN
6021 indicates kilobytes, <SPAN
6033 > indicates megabytes,
6046 > indicates gigabytes. If you omit the
6047 units letter, the default is kilobytes.</P
6059 >Specifies the port offset number of the Tape Coordinator handling the tape or backup data file for this
6060 operation. You must provide this argument unless the default value of <SPAN
6079 >Specifies the permanent name to record on the label. It can be up to 32 characters in length, and include
6080 any alphanumeric characters. Avoid metacharacters that have a special meaning to the shell, to avoid having to
6081 mark them as literal in commands issued at the shell prompt.</P
6083 >Include this argument or the <SPAN
6089 > argument, but not both. When you provide
6090 this argument, the AFS tape name is set to <SAMP
6091 CLASS="computeroutput"
6092 ><NULL></SAMP
6094 argument, any existing permanent name is retained.</P
6102 >If you did not include the <SPAN
6108 > flag when you issued the <SPAN
6114 > command, or if the device's device configuration file includes the instruction <SPAN
6120 >, then the Tape Coordinator prompts you to place the tape in the device's drive. You
6121 have already done so, but you must now press <SPAN
6125 ><Return></B
6127 > to indicate that the tape is
6128 ready for labeling.</P
6138 >To read the label on a tape</A
6144 >Verify that you are authenticated as a user listed in the <SPAN
6148 >/usr/afs/etc/UserList</B
6151 file. If necessary, issue the <SPAN
6157 > command, which is fully described in <A
6158 HREF="c32432.html#HDRWQ593"
6159 >To display the users in the UserList file</A
6161 CLASS="programlisting"
6177 >If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a
6178 connection to the appropriate Tape Coordinator machine and issue the <SPAN
6185 which complete instructions appear in <A
6186 HREF="c15383.html#HDRWQ292"
6187 >To start a Tape Coordinator process</A
6190 CLASS="programlisting"
6212 >Place the tape in the device.</P
6229 interactive mode, if you want to label multiple tapes or issue additional commands after labeling the tape. The
6230 interactive prompt appears in the following step. <PRE
6231 CLASS="programlisting"
6248 >(backup) readlabel</B
6250 > command to read the label on the tape.
6252 CLASS="programlisting"
6253 > backup> <SPAN
6261 >TC port offset</VAR
6267 CLASS="variablelist"
6279 >Is the shortest acceptable abbreviation of <SPAN
6297 >Specifies the port offset number of Tape Coordinator handling the tape or backup data file for this
6298 operation. You must provide this argument unless the default value of <SPAN
6313 >If you did not include the <SPAN
6319 > flag when you issued the <SPAN
6325 > command, or the device's device configuration file includes the instruction <SPAN
6331 > instruction, then the Tape Coordinator prompts you to place the tape in the device's
6332 drive. You have already done so, but you must now press <SPAN
6336 ><Return></B
6339 the tape is ready for reading.</P
6343 >Information from the tape label appears both in the <SPAN
6349 > command window and in the
6350 Tape Coordinator window. The output in the command window has the following format:</P
6352 CLASS="programlisting"
6353 > Tape read was labelled: tape_name (initial_dump_ID)
6357 >where tape_name is the tape's permanent name (if it has one) or AFS tape name, initial_dump_ID is the dump ID of the
6358 initial dump on the tape, and size is the capacity recorded on the label, in kilobytes.</P
6360 >The information in the Tape Coordinator window is more extensive. The tape's permanent name appears in the
6362 CLASS="computeroutput"
6364 > field and its AFS tape name in the <SAMP
6365 CLASS="computeroutput"
6366 >AFS tape name</SAMP
6368 field. If either name is undefined, a value of <SAMP
6369 CLASS="computeroutput"
6370 ><NULL></SAMP
6371 > appears in the field instead. The
6372 capacity recorded on the label appears in the <SAMP
6373 CLASS="computeroutput"
6375 > field. Other fields in the output report
6376 the creation time, dump level name, and dump ID of the initial dump on the tape
6378 CLASS="computeroutput"
6381 CLASS="computeroutput"
6384 CLASS="computeroutput"
6387 > respectively). The <SAMP
6388 CLASS="computeroutput"
6390 > field reports the cell in which the dump
6391 operation was performed, and the <SAMP
6392 CLASS="computeroutput"
6394 > field reports the number of times the tape has been
6395 relabeled, either with the <SPAN
6399 >backup labeltape</B
6401 > command or during a dump operation. For further
6402 details, see the command's reference page in the <SPAN
6406 >IBM AFS Administration Reference</I
6410 >If the tape has no label, or if the drive is empty, the following message appears at the command shell:</P
6412 CLASS="programlisting"
6413 > Failed to read tape label.
6416 >The following example illustrates the output in the command shell for a tape in the device with port offset 1:</P
6418 CLASS="programlisting"
6423 >backup readlabel 1</B
6426 Tape read was labelled: monthly_guest (917860000)
6427 size: 2150000 KBytes
6430 >The following output appears in the Tape Coordinator window at the same time:</P
6432 CLASS="programlisting"
6435 tape name = monthly_guest
6436 AFS tape name = guests.monthly.3
6437 creationTime = Mon Feb 1 04:06:40 1999
6439 size = 2150000 Kbytes
6440 dump path = /monthly
6443 -- End of tape label --
6453 >Automating and Increasing the Efficiency of the Backup Process</A
6456 >The Backup System includes several optional features to help you automate the backup process in your cell and make it more
6457 efficient. By combining several of the features, you can dump volume data to tape with minimal human intervention in most cases.
6458 To take advantage of many of the features, you create a device configuration file in the <SPAN
6464 > directory for each tape device that participates in automated operations. For general
6465 instructions on creating the device configuration file, see <A
6466 HREF="c12776.html#HDRWQ276"
6467 >Creating a Device Configuration
6469 >. The following list refers you to sections that describe each feature in greater detail. <UL
6472 >You can use tape stackers and jukeboxes to perform backup operations. These are tape drives with an attached unit
6473 that stores several tapes and can physically insert and remove them from the tape reader (tape drive) without human
6474 intervention, meaning that no operator has to be present even for backup operations that require several tapes. To use a
6475 stacker or jukebox with the Backup System, include the <SPAN
6487 > instructions in its device configuration file. See <A
6488 HREF="c12776.html#HDRWQ277"
6490 Device's Tape Mounting and Unmounting Routines</A
6495 >You can suppress the Tape Coordinator's default prompt for the initial tape that it needs for a backup operation,
6496 again eliminating the need for a human operator to be present when a backup operation begins. (You must still insert the
6497 correct tape in the drive at some point before the operation begins.) To suppress the initial prompt, include the
6510 > command, or assign the
6523 > instruction in the device
6524 configuration file. See <A
6525 HREF="c12776.html#HDRWQ278"
6526 >Eliminating the Search or Prompt for the Initial Tape</A
6531 >You can suppress the prompts that the Tape Coordinator otherwise generates when it encounters several types of
6532 errors. When you use this feature, the Tape Coordinator instead responds to the errors in a default manner, which
6533 generally allows the operation to continue without human intervention. To suppress prompts about error conditions, assign
6546 > instruction in the device
6547 configuration file. See <A
6548 HREF="c12776.html#HDRWQ279"
6549 >Enabling Default Responses to Error Conditions</A
6554 >You can suppress the Backup System's default verification that the AFS tape name on a tape that has no permanent
6555 name matches the name derived from the volume set and dump level names of the initial dump the Backup System is writing to
6556 the tape. This enables you to recycle a tape without first relabeling it, as long as all dumps on it are expired. To
6557 suppress name checking, assign the value <SPAN
6569 > instruction in the device configuration file. See <A
6570 HREF="c12776.html#HDRWQ280"
6572 the AFS Tape Name Check</A
6577 >You can promote tape streaming (the most efficient way for a tape device to operate) by setting the size of the
6578 memory buffer the Tape Coordinator uses when transferring volume data between the file system and the device. To set the
6579 buffer size, include the <SPAN
6585 > instruction in the device configuration file. See
6587 HREF="c12776.html#HDRWQ281"
6588 >Setting the Memory Buffer Size to Promote Tape Streaming</A
6593 >You can write dumps to a <SPAN
6597 >backup data file</I
6599 > on the local disk of the Tape Coordinator machine,
6600 rather than to tape. You can then transfer the backup data file to a data-archiving system, such as a hierarchical storage
6601 management (HSM) system, that you use in conjunction with AFS and the Backup System. Writing a dump to a file is usually
6602 more efficient that issuing the equivalent <SPAN
6608 > commands individually. To write dumps
6609 to a file, include the <SPAN
6615 > instruction in the device configuration file. See <A
6616 HREF="c12776.html#HDRWQ282"
6617 >Dumping Data to a Backup Data File</A
6623 >There are two additional ways to increase backup automation and efficiency that do not involve the device configuration
6627 >You can schedule one or more <SPAN
6633 > commands to run at specified times. This
6634 enables you to create backups at times of low system usage, without requiring a human operator to be present. You can
6635 schedule a single dump operation for a future time, or multiple operations to run at various future times. See <A
6636 HREF="c15383.html#HDRWQ300"
6637 >Scheduling Dumps</A
6642 >You can append dumps to a tape that already has other dumps on it. This enables you to use as much of a tape's
6643 capacity as possible. The appended dumps do not have be related in any way to one another or to the initial dump on the
6644 tape, but grouping dumps appropriately can reduce the number of necessary tape changes during a restore operation. To
6645 append a dump, include the <SPAN
6651 > argument to the <SPAN
6659 HREF="c15383.html#HDRWQ299"
6660 >Appending Dumps to an Existing Dump Set</A
6671 >Creating a Device Configuration File</A
6674 >To use many of the features that automate backup operations, create a configuration file for each tape device in the
6681 > directory on the local disk of the Tape Coordinator machine that drives the
6682 device. The filename has the following form:</P
6692 >where device_name represents the name of the tape device or backup data file (see <A
6693 HREF="c12776.html#HDRWQ282"
6695 to a Backup Data File</A
6696 > to learn about writing dumps to a file rather than to tape).</P
6698 >For a tape device, construct the device_name portion of the name by stripping off the initial <SPAN
6704 > string with which all UNIX device names conventionally begin, and replacing any other slashes in
6705 the name with underscores. For example, <SPAN
6711 > is the appropriate filename for a device
6720 >For a backup data file, construct the device_name portion by stripping off the initial slash (<SPAN
6726 >) and replacing any other slashes (<SPAN
6732 >) in the name with underscores.
6737 >CFG_var_tmp_FILE</B
6739 > is the appropriate filename for a backup data file called
6748 >Creating a device configuration file is optional. If you do not want to take advantage of any of the features that the
6749 file provides, you do not have to create it.</P
6751 >You can include one of each of the following instructions in any order in a device configuration file. All are optional.
6752 Place each instruction on its own line, but do not include any newline (<SPAN
6756 ><Return></B
6759 characters within an instruction. <DIV
6760 CLASS="variablelist"
6767 >MOUNT and UNMOUNT</B
6772 >Identify a script of routines for mounting and unmounting tapes in a tape stacker or jukebox's drive as needed.
6774 HREF="c12776.html#HDRWQ277"
6775 >Invoking a Device's Tape Mounting and Unmounting Routines</A
6788 >Controls whether the Tape Coordinator prompts for the first tape it needs for a backup operation. See <A
6789 HREF="c12776.html#HDRWQ278"
6790 >Eliminating the Search or Prompt for the Initial Tape</A
6803 >Controls whether the Tape Coordinator asks you how to respond to certain error conditions. See <A
6804 HREF="c12776.html#HDRWQ279"
6805 >Enabling Default Responses to Error Conditions</A
6818 >Controls whether the Tape Coordinator verifies that an AFS tape name matches the initial dump you are writing to
6820 HREF="c12776.html#HDRWQ280"
6821 >Eliminating the AFS Tape Name Check</A
6834 >Sets the size of the memory buffer the Tape Coordinator uses when transferring data between a tape device and a
6836 HREF="c12776.html#HDRWQ281"
6837 >Setting the Memory Buffer Size to Promote Tape Streaming</A
6850 >Controls whether the Tape Coordinator writes dumps to, and restores data from, a tape device or a backup data
6852 HREF="c12776.html#HDRWQ282"
6853 >Dumping Data to a Backup Data File</A
6866 >Invoking a Device's Tape Mounting and Unmounting Routines</A
6869 >A tape stacker or jukebox helps you automate backup operations because it can switch between multiple tapes during an
6870 operation without human intervention. To take advantage of this feature, include the <SPAN
6877 and optionally <SPAN
6883 > instructions in the device configuration file that you write for the
6884 stacker or jukebox. The instructions share the same syntax:</P
6886 CLASS="programlisting"
6903 >where filename is the pathname on the local disk of a script or program you have written that invokes the routines
6904 defined by the device's manufacturer for mounting or unmounting a tape in the device's tape drive. (For convenience, the
6905 following discussion uses the term <SPAN
6911 > to refers to both scripts and programs.) The script usually
6912 also contains additional logic that handles error conditions or modifies the script's behavior depending on which backup
6913 operation is being performed.</P
6915 >You can refer to different scripts with the <SPAN
6927 > instructions, or to a single script that invokes both mounting and unmounting routines. The
6928 scripts inherit the local identity and AFS tokens associated with to the issuer of the <SPAN
6937 >You need to include a <SPAN
6943 > instruction in the device configuration file for all tape
6944 devices, but the need for an <SPAN
6950 > instruction depends on the tape-handling routines that
6951 the device's manufacturer provides. Some devices, usually stackers, have only a single routine for mounting tapes, which also
6952 automatically unmounts a tape whose presence prevents insertion of the required new tape. In this case, an <SPAN
6958 > instruction is not necessary. For devices that have separate mounting and unmounting routines,
6959 you must include an <SPAN
6965 > instruction to remove a tape when the Tape Coordinator is
6966 finished with it; otherwise, subsequent attempts to run the <SPAN
6972 > instruction fail with an
6975 >When the device configuration file includes a <SPAN
6981 > instruction, you must stock the
6982 stacker or jukebox with the necessary tapes before running a backup operation. Many jukeboxes are able to search for the
6983 required tape by reading external labels (such as barcodes) on the tapes, but many stackers can only switch between tapes in
6984 sequence and sometimes only in one direction. In the latter case, you must also stock the tapes in the correct order.</P
6986 >To obtain a list of the tapes required for a restore operation so that you can prestock them in the tape device, include
6993 > flag on the appropriate <SPAN
7003 >backup diskrestore</B
7009 >backup volrestore</B
7018 >). For a dump operation, it is generally sufficient to stock the device with more tapes than the
7019 operation is likely to require. You can prelabel the tapes with permanent names or AFS tape names, or not prelabel them at
7020 all. If you prelabel the tapes for a dump operation with AFS tape names, then it is simplest to load them into the stacker in
7021 sequential order by tape index. But it is probably simpler still to prelabel tapes with permanent tape names or use unlabeled
7022 tapes, in which case the Backup System generates and applies the appropriately indexed AFS tape name itself during the dump
7030 >How the Tape Coordinator Uses the MOUNT and UNMOUNT Instructions</A
7033 >When you issue the <SPAN
7039 > command to initialize the Tape Coordinator for a given tape
7040 device, the Tape Coordinator looks for the device configuration file called <SPAN
7044 >/usr/afs/backup/CFG_</B
7046 >device_name on its local disk, where device_name has the format described in
7048 HREF="c12776.html#HDRWQ276"
7049 >Creating a Device Configuration File</A
7050 >. If the file exists and contains a <SPAN
7056 > instruction, then whenever the Tape Coordinator needs a tape, it executes the script named by
7057 the instruction's filename argument.</P
7059 >If the device configuration file does not exist, or does not include a <SPAN
7066 instruction, then whenever the Tape Coordinator needs a tape, it generates a prompt in its window instructing the operator
7067 to insert the necessary tape. The operator must insert the tape and press <SPAN
7071 ><Return></B
7074 before the Tape Coordinator continues the backup operation.</P
7076 >Note, however, that you can modify the Tape Coordinator's behavior with respect to the first tape needed for an
7077 operation, by setting the <SPAN
7083 > instruction in the device configuration file to
7090 >, or including the <SPAN
7102 > command. In this case, the Tape Coordinator does not execute the <SPAN
7108 > instruction or prompt for a tape at the start of an operation, because it expects to find the
7109 required first tape in the drive. See <A
7110 HREF="c12776.html#HDRWQ278"
7111 >Eliminating the Search or Prompt for the Initial
7115 >If there is an <SPAN
7121 > instruction in the device configuration file, then whenever
7122 the Tape Coordinator closes the tape device, it executes the script named by the instruction's filename argument. It
7123 executes the script only once, and regardless of whether the <SPAN
7129 > operation on the device
7130 succeeded or not. If the device configuration file does not include an <SPAN
7137 then the Tape Coordinator takes no action.</P
7145 >The Available Parameters and Required Exit Codes</A
7148 >When the Tape Coordinator executes the <SPAN
7154 > script, it passes in five parameters,
7155 ordered as follows. You can use the parameters in your script to refine its response to varying circumstances that can arise
7156 during a backup operation. <OL
7160 >The tape device or backup data file's pathname, as recorded in the <SPAN
7164 >/usr/afs/backup/tapeconfig</B
7170 >The tape operation, which (except for the exceptions noted in the following list) matches the <SPAN
7176 > command operation code used to initiate the operation: <UL
7215 not include the <SPAN
7255 >backup diskrestore</B
7262 >backup volrestore</B
7268 >backup volsetrestore</B
7308 >The number of times the Tape Coordinator has attempted to open the tape device or backup data file. If the open
7309 attempt returns an error, the Tape Coordinator increments this value by one and again invokes the <SPAN
7319 >The tape name. For some operations, the Tape Coordinator passes the string
7321 CLASS="computeroutput"
7323 >, because it does not know the tape name (when running the <SPAN
7333 >backup readlabel</B
7335 >, for example), or because
7336 the tape does not necessarily have a name (when running the <SPAN
7340 >backup labeltape</B
7347 >The tape ID recorded in the Backup Database. As with the tape name, the Backup System passes the string
7349 CLASS="computeroutput"
7351 > for operations where it does not know the tape ID or the tape does not
7352 necessarily have an ID.</P
7363 > script must return one of the following exit codes to tell the Tape
7364 Coordinator whether or not it mounted the tape successfully: <UL
7373 > (zero) indicates a successful mount, and the Tape Coordinator continues
7374 the backup operation. If the script or program called by the <SPAN
7381 not return this exit code, the Tape Coordinator never calls the <SPAN
7398 > indicates that mount attempt failed. The Tape Coordinator terminates the
7399 backup operation.</P
7403 >Any other code indicates that the script was unable to access the correct tape. The Tape Coordinator prompts the
7404 operator to insert it.</P
7409 >When the Tape Coordinator executes the <SPAN
7415 > script, it passes in two parameters in
7416 the following order. <OL
7420 >The tape device's pathname (as specified in the <SPAN
7424 >/usr/afs/backup/tapeconfig</B
7431 >The tape operation, which is always <SPAN
7442 >The following example script uses two of the parameters passed to it by the Backup System:
7444 CLASS="computeroutput"
7447 CLASS="computeroutput"
7449 >. It follows the recommended practice
7450 of exiting if the value of the <SAMP
7451 CLASS="computeroutput"
7453 > parameter exceeds one, because that implies that the
7454 stacker is out of tapes.</P
7469 routine calls the example <SPAN
7473 >stackerCmd_NextTape</B
7475 > function provided by the stacker's
7476 manufacturer. Note that the final lines in the file return the exit code that prompts the operator to insert a tape; these
7477 lines are invoked when either the stacker cannot load a tape or a the operation being performed is not one of those
7478 explicitly mentioned in the file (is a restore operation, for example).</P
7480 CLASS="programlisting"
7481 > #! /bin/csh -f
7487 set exit_continue = 0
7489 set exit_interactive = 2
7490 #--------------------------------------------
7491 if (${tries} > 1) then
7492 echo "Too many tries"
7493 exit ${exit_interactive}
7495 if (${operation} == "unmount") then
7496 echo "UnMount: Will leave tape in drive"
7497 exit ${exit_continue}
7499 if ((${operation} == "dump") |\
7500 (${operation} == "appenddump") |\
7501 (${operation} == "savedb")) then
7502 stackerCmd_NextTape ${devicefile}
7503 if (${status} != 0)exit${exit_interactive}
7504 echo "Will continue"
7505 exit ${exit_continue}
7507 if ((${operation} == "labeltape") |\
7508 (${operation} == "readlabel")) then
7509 echo "Will continue"
7510 exit ${exit_continue}
7512 echo "Prompt for tape"
7513 exit ${exit_interactive}
7523 >Eliminating the Search or Prompt for the Initial Tape</A
7526 >By default, the Tape Coordinator obtains the first tape it needs for a backup operation by reading the device
7527 configuration file for the appropriate tape device. If there is a <SPAN
7533 > instruction in the
7534 file, the Tape Coordinator executes the referenced script. If the device configuration file does not exist or does not have a
7541 > instruction in it, the Tape Coordinator prompts you to insert the correct tape and
7546 ><Return></B
7550 >If you know in advance that an operation requires a tape, you can increase efficiency by placing the required tape in
7551 the drive before issuing the <SPAN
7557 > command and telling the Tape Coordinator's to skip its
7558 initial tape-acquisition steps. This both enables the operation to begin more quickly and eliminates that need for you to be
7559 present to insert a tape.</P
7561 >There are two ways to bypass the Tape Coordinator's initial tape-acquisition steps: <OL
7565 >Include the instruction <SPAN
7571 > in the device configuration file</P
7593 >To avoid any error conditions that require operator attention, be sure that the tape you are placing in the drive does
7594 not contain any unexpired dumps and is not write protected. If there is no permanent name on the tape's label and you are
7595 creating an initial dump, make sure that the AFS tape name either matches the volume set and dump set names or is
7597 CLASS="computeroutput"
7598 ><NULL></SAMP
7599 >. Alternatively, suppress the Tape Coordinator's name verification step by
7600 assigning the value <SPAN
7612 > instruction in the
7613 device configuration file, as described in <A
7614 HREF="c12776.html#HDRWQ280"
7615 >Eliminating the AFS Tape Name Check</A
7624 >Enabling Default Responses to Error Conditions</A
7627 >By default, the Tape Coordinator asks you how to respond when it encounters certain error conditions. To suppress the
7628 prompts and cause the Tape Coordinator to handle the errors in a predetermined manner, include the instruction <SPAN
7634 > in the device configuration file. If you assign the value <SPAN
7647 > instruction completely, the Tape Coordinator prompts you for direction when
7648 it encounters one of the errors.</P
7650 >The following list describes the error conditions and the Tape Coordinator's response to them. <UL
7653 >The Backup System is unable to dump a volume while running the <SPAN
7660 command. When you assign the value <SPAN
7666 >, the Tape Coordinator omits the volume from the
7667 dump and continues the operation. When you assign the value <SPAN
7673 >, it prompts to ask if
7674 you want to try to dump the volume again immediately, to omit the volume from the dump but continue the operation, or to
7675 terminate the operation.</P
7679 >The Backup System is unable to restore a volume while running the <SPAN
7690 >backup volrestore</B
7699 > command. When you assign the value <SPAN
7705 >, the Tape Coordinator
7706 continues the operation, omitting the problematic volume but restoring the remaining ones. When you assign the value
7713 >, it prompts to ask if you want to omit the volume and continue the operation, or to
7714 terminate the operation.</P
7718 >The Backup System cannot determine if the dump set includes any more tapes while running the <SPAN
7724 > command (the command's reference page in the <SPAN
7728 >IBM AFS Administration
7731 > discusses possible reasons for this problem). When you assign the value <SPAN
7737 >, the Tape Coordinator proceeds as though there are more tapes and invokes the <SPAN
7743 > script named in the device configuration file, or prompts the operator to insert the next
7744 tape. When you assign the value <SPAN
7750 >, it prompts to ask if there are more tapes to
7755 >The Backup System determines that the tape contains an unexpired dump while running the <SPAN
7759 >backup labeltape</B
7761 > command. When you assign the value <SPAN
7768 terminates the operation without relabeling the tape. With a <SPAN
7775 Coordinator prompts to ask if you want to relabel the tape anyway.</P
7786 >Eliminating the AFS Tape Name Check</A
7789 >If a tape does not have a permanent name and you are writing an initial dump to it, then by default the Backup System
7790 verifies that the tape's AFS tape name is acceptable. It accepts three types of values: <UL
7793 >A name that reflects the volume set and dump level of the initial dump and the tape's place in the sequence of
7794 tapes for the dump set, as described in <A
7795 HREF="c12776.html#HDRWQ253"
7796 >Dump Names and Tape Names</A
7797 >. If the tape does not
7798 already have a permanent name, you can assign the AFS tape name by using the <SPAN
7805 argument to the <SPAN
7809 >backup labeltape</B
7816 CLASS="computeroutput"
7817 ><NULL></SAMP
7818 > value, which results when you assign a permanent name, or provide
7819 no value for the <SPAN
7823 >backup labeltape</B
7836 >No AFS tape name at all, indicating that you have never labeled the tape or written a dump to it.</P
7841 >To bypass the name check, include the <SPAN
7847 > instruction in the device
7848 configuration file. This enables you to recycle a tape without first relabeling it, as long as all dumps on it are expired.
7849 (If a tape has unexpired dumps on it but you want to recycle it anyway, you must use the <SPAN
7856 > command to relabel it first. For this to work, the <SPAN
7863 cannot appear in the device configuration file.)</P
7871 >Setting the Memory Buffer Size to Promote Tape Streaming</A
7874 >By default, the Tape Coordinator uses a 16-KB memory buffer during dump operations. As it receives volume data from the
7875 Volume Server, the Tape Coordinator gathers 16 KB of data in the buffer before transferring the entire 16 KB to the tape
7876 device. Similarly, during a restore operation the Tape Coordinator by default buffers 32 KB of data from the tape device
7877 before transferring the entire 32 KB to the Volume Server for restoration into the file system. Buffering makes the volume of
7878 data flowing to and from a tape device more even and so promotes tape streaming, which is the most efficient way for a tape
7879 device to operate.</P
7881 >In a normal network configuration, the default buffer sizes are usually large enough to promote tape streaming. If the
7882 network between the Tape Coordinator machine and file server machines is slow, it can help to increase the buffer size.</P
7884 >To determine if altering the buffer size is helpful for your configuration, observe the tape device in operation to see
7885 if it is streaming, or consult the manufacturer. To set the buffer size, include the <SPAN
7891 > instruction in the device configuration file. It takes an integer value, and optionally
7892 units, in the following format:</P
7894 CLASS="programlisting"
7940 >where size specifies the amount of memory the Tape Coordinator allocates to use as a buffer during both dump and restore
7941 operations. The default unit is bytes, but use <SPAN
7954 specify kilobytes, <SPAN
7966 > for megabytes, and <SPAN
7978 > for gigabytes. There is no space between the size value and the
7987 >Dumping Data to a Backup Data File</A
7990 >You can write dumps to a <SPAN
7994 >backup data file</I
7996 > rather than to tape. This is useful if, for example, you
7997 want to transfer the data to a data-archiving system, such as a hierarchical storage management (HSM) system, that you use in
7998 conjunction with AFS and the Backup System. You can restore data from a backup data file into the file system as well. Using a
7999 backup data file is usually more efficient than issuing the equivalent <SPAN
8011 > commands individually for multiple volumes.</P
8013 >Writing to a backup data file is simplest if it is on the local disk of the Tape Coordinator machine, but you can also
8014 write the file to an NFS-mounted partition that resides on a remote machine. It is even acceptable to write to a file in AFS,
8015 provided that the access control list (ACL) on its parent directory grants the necessary permissions, but it is somewhat
8016 circular to back up AFS data into AFS itself.</P
8018 >If the backup data file does not already exist when the Tape Coordinator attempts to write a dump to it, the Tape
8019 Coordinator creates it. For a restore operation to succeed, the file must exist and contain volume data previously written to
8028 >When writing to a backup data file, the Tape Coordinator writes data at 16 KB offsets. If a given block of data (such as
8029 the marker that signals the beginning or end of a volume) does not fill the entire 16 KB, the Tape Coordinator still skips to
8030 the next offset before writing the next block. In the output of a <SPAN
8037 issued with the <SPAN
8043 > option, the value in the <SAMP
8044 CLASS="computeroutput"
8047 the ordinal of the 16-KB offset at which the volume data begins, and so is not generally only one higher than the position
8048 number on the previous line, as it is for dumps to tape.</P
8050 >Before writing to a backup data file, you need to configure the file as though it were a tape device.</P
8058 >A file pathname, rather than a tape device name, must appear in the third field of the <SPAN
8062 >/usr/afs/backup/tapeconfig</B
8064 > file when the <SPAN
8071 appears in the device configuration file, and vice versa. If the <SPAN
8078 refers to a tape device, dump operations appear to succeed but are inoperative. You cannot restore data that you accidently
8079 dumped to a tape device while the <SPAN
8085 > instruction was set to <SPAN
8091 >. In the same way, if the <SPAN
8097 > instruction is set to <SPAN
8109 > entry must refer to an actual tape device.</P
8119 >To configure a backup data file</A
8125 >Verify that you are authenticated as a user listed in the <SPAN
8129 >/usr/afs/etc/UserList</B
8132 file. If necessary, issue the <SPAN
8138 > command, which is fully described in <A
8139 HREF="c32432.html#HDRWQ593"
8140 >To display the users in the UserList file</A
8142 CLASS="programlisting"
8158 >Become the local superuser <SPAN
8164 > on the machine, if you are not already, by issuing
8172 CLASS="programlisting"
8202 interactive mode. <PRE
8203 CLASS="programlisting"
8216 >Choose the port offset number to assign to the file. If necessary, display previously assigned port offsets by
8221 >(backup) listhosts</B
8223 > command, which is fully described in <A
8224 HREF="c12776.html#HDRWQ264"
8225 >To display the list of configured Tape Coordinators</A
8227 CLASS="programlisting"
8228 > backup> <SPAN
8238 >As for a tape device, acceptable values are the integers <SPAN
8244 > (zero) through <SPAN
8250 > (the Backup System can track a maximum of 58,511 port offset numbers). Each port offset must
8251 be unique in the cell, but you can associate any number them with a single Tape Coordinator machine. You do not have to
8252 assign port offset numbers sequentially.</P
8260 >(backup) addhost</B
8262 > command to register the backup data file's port offset
8263 in the Backup Database. <PRE
8264 CLASS="programlisting"
8265 > backup> <SPAN
8273 >tape machine name</VAR
8276 >TC port offset</VAR
8282 CLASS="variablelist"
8294 >Is the shortest acceptable abbreviation of <SPAN
8307 >tape machine name</B
8312 >Specifies the fully qualified hostname of the Tape Coordinator machine you invoke to write to the backup
8325 >Specifies the file's port offset number. You must provide this argument unless the default value of
8332 > (zero) is appropriate.</P
8341 NAME="LITAPECONFIG-FILE"
8343 >Using a text editor, create an entry for the backup data file in the local
8348 >/usr/afs/backup/tapeconfig</B
8350 > file, using the standard syntax: <PRE
8351 CLASS="programlisting"
8352 > [capacity filemark_size] device_name port_offset
8357 CLASS="variablelist"
8369 >Specifies the amount of space on the partition that houses the backup data file that you want to make
8370 available for the file. To avoid the complications that arise from filling up the partition, it is best to provide
8371 a value somewhat smaller than the actual amount of space you expect to be available when the dump operation runs,
8372 and never larger than the maximum file size allowed by the operating system.</P
8374 >Specify a numerical value followed by a letter that indicates units, with no intervening space. The letter
8387 > indicates kilobytes, <SPAN
8399 > indicates megabytes, and <SPAN
8411 > indicates gigabytes. If you omit the units letter,
8412 the default is kilobytes. If you leave this field empty, the Tape Coordinator uses the maximum acceptable value
8413 (2048 GB or 2 TB). Also leave the filemark_size field empty in that case.</P
8425 >Specify the value <SPAN
8431 > (zero) or leave both this field and the capacity field
8432 empty. In the latter case, the Tape Coordinator also uses the value zero.</P
8444 >Specifies the complete pathname of the backup data file. Rather than specifying an actual file pathname,
8445 however, the recommended configuration is to create a symbolic link in the <SPAN
8452 directory that points to the actual file pathname, and record the symbolic link in this field. This configuration
8453 provides these advantages: <UL
8456 >It makes the device_name portion of the <SPAN
8462 >device_name, of the
8469 >device_name, and of the <SPAN
8476 filenames as short as possible. Because the symbolic link is in the <SPAN
8483 directory as though it is a tape device, you strip off the entire <SPAN
8490 prefix when forming the filename, instead of just the initial slash (<SPAN
8497 If, for example, the symbolic link is called <SPAN
8504 configuration file's name is <SPAN
8510 >, whereas if the actual pathname
8517 > appears in the <SPAN
8524 file, the configuration file's name must be <SPAN
8528 >CFG_var_tmp_FILE</B
8534 >It provides for a more graceful, and potentially automated, recovery if the Tape Coordinator cannot
8535 write a complete dump into the backup data file (for example, because the partition housing the backup data
8536 file becomes full). The Tape Coordinator's reaction to this problem is to invoke the <SPAN
8542 > script, or to prompt you if the <SPAN
8549 instruction does not appear in the configuration file. <UL
8552 >If there is a <SPAN
8558 > script, you can prepare for this situation
8559 by adding a subroutine to the script that changes the symbolic link to point to another backup data
8560 file on a partition where there is space available.</P
8564 >If there is no <SPAN
8570 > instruction, the prompt enables you
8571 manually to change the symbolic link to point to another backup data file and then press <<SPAN
8577 >> to signal that the Tape Coordinator can continue the
8583 >If this field names the actual file, there is no way to recover from exhausting the space on the
8584 partition. You cannot change the <SPAN
8590 > file in the middle of an
8606 >Specifies the port offset number that you chose for the backup data file.</P
8614 >Create the device configuration file <SPAN
8620 >device_name in the Tape Coordinator
8627 > directory. Include the <SPAN
8634 > instruction in the file.</P
8636 >Construct the device_name portion of the name based on the device name you recorded in the <SPAN
8643 HREF="c12776.html#LITAPECONFIG-FILE"
8645 >. If, as recommended, you
8646 recorded a symbolic link name, strip off the <SPAN
8652 > string and replace any other slashes
8659 >) in the name with underscores (<SPAN
8672 > is the appropriate name if the symbolic link is <SPAN
8678 >. If you recorded the name of an actual file, then strip off the initial slash only and
8679 replace any other slashes in the name with underscores. For a backup data file called <SPAN
8685 >, the appropriate device configuration filename is <SPAN
8689 >CFG_var_tmp_FILE</B
8695 >If you chose in Step <A
8696 HREF="c12776.html#LITAPECONFIG-FILE"
8698 > to record a symbolic link name in the device_name
8705 > entry, then you must do one of the following: <UL
8714 > command to create the appropriate symbolic link in the
8725 >Write a script that initializes the backup data file in this way, and include a <SPAN
8731 > instruction in the device configuration file to invoke the script. An example script
8732 appears following these instructions.</P
8739 >You do not need to create the backup data file itself, because the Tape Coordinator does so if the file does not exist
8740 when the dump operation begins.</P
8742 >The following example script illustrates how you can automatically create a symbolic link to the backup data file during
8743 the preparation phase for writing to the file. When the Tape Coordinator is executing a <SPAN
8766 >backup restoredb</B
8768 > operation, the routine invokes the UNIX <SPAN
8775 to create a symbolic link from the backup data file named in the <SPAN
8782 actual file to use (this is the recommended method). It uses the values of the <SAMP
8783 CLASS="computeroutput"
8787 CLASS="computeroutput"
8789 > parameters passed to it by the Backup System when constructing the filename.</P
8791 >The routine makes use of two other parameters as well: <SAMP
8792 CLASS="computeroutput"
8796 CLASS="computeroutput"
8799 CLASS="computeroutput"
8801 > parameter tracks how many times the
8802 Tape Coordinator has attempted to access the file. A value greater than one indicates that the Tape Coordinator cannot access
8803 it, and the routine returns exit code 2 (<SAMP
8804 CLASS="computeroutput"
8805 >exit_interactive</SAMP
8806 >), which results in a prompt for the
8807 operator to load a tape. The operator can use this opportunity to change the name of the backup data file specified in the
8816 CLASS="programlisting"
8817 > #! /bin/csh -f
8823 set exit_continue = 0
8825 set exit_interactive = 2
8826 #--------------------------------------------
8827 if (${tries} > 1) then
8828 echo "Too many tries"
8829 exit ${exit_interactive}
8831 if (${operation} == "labeltape") then
8832 echo "Won't label a tape/file"
8835 if ((${operation} == "dump") |\
8836 (${operation} == "appenddump") |\
8837 (${operation} == "restore") |\
8838 (${operation} == "savedb") |\
8839 (${operation} == "restoredb")) then
8840 /bin/rm -f ${devicefile}
8841 /bin/ln -s /hsm/${tapename}_${tapeid} ${devicefile}
8842 if (${status} != 0) exit ${exit_abort}
8844 exit ${exit_continue}
8854 SUMMARY="Footer navigation table"
8893 >Managing Volumes</TD
8907 >Backing Up and Restoring AFS Data</TD
git://git.openafs.org / openafs.git / blob