Defining and Displaying the Dump Hierarchy
| Chapter 6. Configuring the AFS Backup System |

## Defining and Displaying the Dump Hierarchy

A dump hierarchy is a logical structure in the Backup Database that defines the relationship between full and incremental dumps; that is, it defines which dump serves as the parent for an incremental dump. Each individual component of a hierarchy is a dump level.

As you define dump levels with the backup adddump command, keep the following rules and suggestions in mind:

- Each full dump level is the top level of a hierarchy. You can create as many hierarchies as you need to dump different volume sets on different schedules.

- The name of a full dump level consists of an initial slash (/), followed by a string of up to 28 alphanumeric characters.

- The name of an incremental dump level resembles a pathname, starting with the name of a full dump level, then the first incremental level, and so on, down to the final incremental level. Precede each level name with a slash to separate it from the preceding level. Like the full level, each component level in the name can have up to 28 alphanumeric characters, not including the slash.

- A hierarchy can have any have any number of levels, but the maximum length of a complete dump level name is 256 characters, including the slashes.

- Before defining a given incremental level, you must define all of the levels above it in the hierarchy.

- Do not use the period (.) in dump level names. The Backup System uses the period as the separator between a dump's volume set name and dump level name when it creates the dump name and AFS tape name. Any other alphanumeric and punctuation characters are allowed, but it is best to avoid metacharacters. If you include a metacharacter, you must precede it with a backslash (\) or surround the entire dump level name with double quotes (" ").

- Naming dump levels for days or other actual time points reminds you when to perform dumps, and makes it easier to track the relationship between dumps performed at different levels. However, the names have no meaning to the Backup System: it does not automatically create dumps according to the names, and does not prevent you from, for example, using the /sunday level when creating a dump on a Tuesday.

- It is best not to use the same name for more than one component level in a hierarchy, because it means the resulting dump name no longer indicates which level was used. For example, if you name a dump level /full/incr/incr, then the dump name and AFS tape name that result from dumping a volume set at the first incremental level (/full/incr) look the same as the names that result from dumping at the second incremental level (/full/incr/incr).

- Individual levels in different hierarchies can have the same name, but the complete pathnames must be unique. For example, /sunday1/monday and /sunday2/monday share the same name at the final level, but are unique because they have different names at the full level (belong to different hierarchies). However, using the same name in multiple hierarchies means that dump and AFS tape names do not unambiguously indicate which hierarchy was used.

The following example shows three hierarchies. Each begins with a full dump at the top: sunday1 for the first hierarchy, sunday2 for the second hierarchy, and sunday_bin for the third hierarchy. In all three hierarchies, each of the other dump levels is an incremental level.

       /sunday1
               /monday
               /tuesday
               /wednesday
               /thursday
               /friday
       /sunday2
               /monday
                      /tuesday
                              /wednesday
                                        /thursday
                                                 /friday
        /sunday_bin
                   /monday
                          /wednesday
                                    /friday

In the first hierarchy, each incremental dump level refers to the full level /sunday1 as its parent. When (for example) you dump a volume set at the /sunday1/wednesday level, it includes data that has changed since the volume set was dumped at the /sunday1 level.

In contrast, each incremental dump level in the second hierarchy refers to the immediately preceding dump level as its parent. When you dump a volume set at the corresponding level in the second hierarchy (/sunday2/monday/tuesday/wednesday), the dump includes only data that has changed since the volume set was dumped at the /sunday2/monday/tuesday level (presumably the day before). Assuming you create dumps on the indicated days, an incremental dump made using this hierarchy contains less data than an incremental dump made at the corresponding level in the first hierarchy.

The third hierarchy is more appropriate for dumping volumes for which a daily backup is excessive because the data does not change often (for example, system binaries).

### Creating a Tape Recycling Schedule

If your cell is like most cells, you have a limited amount of room for storing backup tapes and a limited budget for new tapes. The easiest solution is to recycle tapes by overwriting them when you no longer need the backup data on them. The Backup System helps you implement a recycling schedule by enabling you to associate an expiration date with each dump level. The expiration date defines when a dump created at that level expires. Until that time the Backup System refuses to overwrite a tape that contains the dump. Thus, assigning expiration dates automatically determines how you recycle tapes.

When designing a tape-recycling schedule, you must decide how far in the past and to what level of precision you want to guarantee access to backed up data. For instance, if you decide to guarantee that you can restore a user's home volume to its 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 weeks after you create it. Similarly, if you decide to guarantee that you can restore home volumes to their state at the beginning of any given week in the last month, you cannot recycle the tapes in a dump set containing a weekly dump for at least four weeks. The following example dump hierarchy implements this recycling schedule by setting the expiration date for each daily incremental dump to 13 days and the expiration date of the weekly full dumps to 27 days.

The tapes used to store dumps created at the daily incremental levels in the /sunday1 hierarchy expire just in time to be recycled for daily dumps in the /sunday3 hierarchy (and vice versa), and there is a similar relationship between the /sunday2 and /sunday4 hierarchies. Similarly, the tape that houses a full dump at the /sunday1 level expires just in time to be used for a full dump on the first Sunday of the following month.

       /sunday1   expires in 27d
               /monday1  expires in 13d
               /tuesday1  expires in 13d
               /wednesday1  expires in 13d
               /thursday1  expires in 13d
               /friday1  expires in 13d
       /sunday2   expires in 27d
               /monday2  expires in 13d
               /tuesday2  expires in 13d
               /wednesday2  expires in 13d
               /thursday2  expires in 13d
               /friday2  expires in 13d
       /sunday3   expires in 27d
               /monday1  expires in 13d
               /tuesday1  expires in 13d
               /wednesday1  expires in 13d
               /thursday1  expires in 13d
               /friday1  expires in 13d
       /sunday4   expires in 27d
               /monday2  expires in 13d
               /tuesday2  expires in 13d
               /wednesday2  expires in 13d
               /thursday2  expires in 13d
               /friday2  expires in 13d

If you use appended dumps in your cell, keep in mind that all dumps in a dump set are subject to the latest (furthest into the future) expiration date associated with any of the constituent dumps. You cannot recycle any of the tapes that contain a dump set until all of the dumps have reached their expiration date. See also Appending Dumps to an Existing Dump Set.

Most tape manufacturers recommend that you write to a tape a limited number of times, and it is best not to exceed this limit when recycling tapes. To help you track tape usage, the Backup System records a `useCount` counter on the tape's label. It increments the counter each time the tape's label is rewritten (each time you use the backup labeltape or backup dump command). To display the `useCount` counter, use the backup readlabel or backup scantape command or include the -id and -verbose options when you issue the backup dumpinfo command. For instructions see Writing and Reading Tape Labels or Displaying Backup Dump Records.

### Archiving Tapes

Even if you make extensive use of tape recycling, there is probably some backup data that you need to archive for a long (or even an indefinite) period of time. You can use the Backup System to archive data on a regular schedule, and you can also choose to archive data on tapes that you previously expected to recycle.

If you want to archive data on a regular basis, you can create date-specific dump levels in the dump hierarchy. For 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 can define the following levels in the dump hierarchy:

       /1Q2000
       /2Q2000
       /3Q2000
       /4Q2000

If you decide to archive data that is on tapes you previously planned to recycle, you must gather all of the tapes that contain the relevant dumps, both full and incremental. To avoid accidental erasure, it is best to set the switch on the tapes that makes them read-only, before placing them in your archive storage area. If the tapes also contain a large amount of extraneous data that you do not want to archive, you can restore just the relevant data into a new temporary volume, and back up that volume to the smallest number of tapes possible. One reason to keep a dump set small is to minimize the amount of irrelevant data in a dump set you end up needing to archive.

If you do not expect to restore archived data to the file system, you can consider using the backup deletedump command to remove the associated dump records from the Backup Database, which helps keep it to an efficient size. If you ever need to restore the data, you can use the -dbadd flag to the backup scantape command to reinsert the dump records into the database. For instructions, see To scan the contents of a tape.

### Defining Expiration Dates

To associate an expiration date with a dump level as you create it, use the -expires argument to the backup adddump command. To change an existing dump level's expiration date, use the -expires argument to the backup setexp command. (Note that it is not possible to change the expiration date of an actual dump that has already been created at that level). With both commands, you can define an expiration date either in absolute terms (for example, 13 January 2000) or relative terms (for example, 30 days from when the dump is created).

- To define an absolute expiration date, provide a value for the -expires argument with the following format:

         [at] mm/dd/yyyy [hh:MM]

  where mm indicates the month, dd the day, and yyyy the year when the dump expires. Valid values for the year fall in the range 1970 through 2037 (the latest possible date that the UNIX time representation can express is in early 2038). If you provide a time, it must be in 24-hour format with hh the hours and MM the minutes (for example, 21:50 is 9:50 p.m.). If you omit the time, the default is 00:00 hours (12:00 midnight) on the indicated date.

- To define a relative expiration date, provide a value for the -expires argument with the following format:

         [in] [yearsy] [monthsm] [daysd]

  where each of years, months, and days is an integer. Provide at least one of them together with the corresponding units letter (y, m, or d respectively), with no intervening space. If you provide more than one of the three, list them in the indicated order.

  The Backup System calculates a dump's actual expiration date by adding the indicated relative value to the start time of the dump operation. For example, it assigns an expiration date 1 year, 6 months, and 2 days in the future to a dump created at a dump level with associated expiration date in 1y 6m 2d.

- To indicate that a dump backed up at the corresponding dump level never expires, provide the value NEVER instead of a date and time. To recycle tapes that contain dumps created at such a level, you must use the backup readlabel command to overwrite the tape's label.

If you omit the -expires argument to the backup adddump command, then the expiration date is set to UNIX time zero (00:00 hours on 1 January 1970). The Backup System considers dumps created at such a dump level to expire at their creation time. If no dumps in a dump set have an expiration date, then the Backup System does not impose any restriction on recycling the tapes that contain the dump set. If you need to prevent premature recycling of the tapes that contain the dump set, you must use a manual tracking system.

### To add a dump level to the dump hierarchy

1. Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Optional. Issue the backup command to enter interactive mode.

          % backup

3. Issue the backup adddump command to define one or more dump levels. If you are defining an incremental level, then all of the parent levels that precede it in its pathname must either already exist or precede it on the command line.

          backup> adddump -dump <dump level name>+ [-expires <expiration date>+]

   where

   addd

     Is the shortest acceptable abbreviation of adddump.

   -dump

     Names each dump level to added. If you specify more than one dump level name, you must include the -dump switch.

     Provide the entire pathname of the dump level, preceding each level in the pathname with a slash (/). Each component level can be up to 28 characters in length, and the pathname can include up to 256 characters including the slashes.

   -expires

     Sets the expiration date associated with each dump level. Specify either a relative or absolute expiration date, as described in Defining Expiration Dates, or omit this argument to assign no expiration date to the dump levels.

     ### Note

     A plus sign follows this argument in the command's syntax statement because it accepts a multiword value which does not need to be enclosed in double quotes or other delimiters, not because it accepts multiple dates. Provide only one date (and optionally, time) definition to be associated with each dump level specified by the -dump argument.

### To change a dump level's expiration date

1. Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Optional. Issue the backup command to enter interactive mode.

          % backup

3. Issue the (backup) setexp command to change the expiration date associated with one or more dump levels.

          backup> setexp -dump <dump level name>+ [-expires <expiration date>+]

   where

   se

     Is the shortest acceptable abbreviation of setexp.

   -dump

     Names each existing dump level for which to change the expiration date.

   -expires

     Sets the expiration date associated with each dump level. Specify either a relative or absolute expiration date, as described in Defining Expiration Dates; omit this argument to remove the expiration date currently associated with each dump level.

     ### Note

     A plus sign follows this argument in the command's syntax statement because it accepts a multiword value which does not need to be enclosed in double quotes or other delimiters, not because it accepts multiple dates. Provide only one date (and optionally, time) definition to be associated with each dump level specified by the -dump argument.

### To delete a dump level from the dump hierarchy

1. Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Optional. Issue the backup command to enter interactive mode.

          % backup

3. Issue the (backup) deldump command to delete the dump level. Note that the command automatically removes all incremental dump levels for which the specified level serves as parent, either directly or indirectly.

          backup> deldump <dump level name>

   where

   deld

     Is the shortest acceptable abbreviation of deldump.

   dump level name

     Specifies the complete pathname of the dump level to delete.

### To display the dump hierarchy

1. Issue the backup listdumps command to display the dump hierarchy.

          % backup listdumps

   where listd is the shortest acceptable abbreviation of listdumps.

   The output from this command displays the dump hierarchy, reporting the expiration date associated with each dump level, as in the following example.

           % backup listdumps
          /week1  expires in  27d
                /tuesday  expires in  13d
                        /thursday  expires in  13d
                /sunday  expires in  13d
                       /tuesday expires in  13d
                               /thursday expires in  13d
          /week3  expires in  27d
                /tuesday  expires in  13d
                        /thursday  expires in  13d
                /sunday  expires in  13d
                       /tuesday  expires in  13d
                               /thursday  expires in  13d
          sunday1   expires in  27d
                 /monday1  expires in  13d
                 /tuesday1  expires in  13d
                 /wednesday1  expires in  13d
                 /thursday1  expires in  13d
                 /friday1  expires in  13d
          sunday2   expires in  27d
                 /monday2  expires in  13d
                 /tuesday2  expires in  13d
                 /wednesday2  expires in  13d
                 /thursday2  expires in  13d
                 /friday2  expires in  13d
          sunday3   expires in  27d
                 /monday1  expires in  13d
                 /tuesday1  expires in  13d
                 /wednesday1  expires in  13d
                 /thursday1  expires in  13d
                 /friday1  expires in  13d
          sunday4   expires in  27d
                 /monday2  expires in  13d
                 /tuesday2  expires in  13d
                 /wednesday2  expires in  13d
                 /thursday2  expires in  13d
                 /friday2  expires in  13d

Defining and Displaying Volume Sets and Volume Entries |  | Writing and Reading Tape Labels