Tivoli Storage Manager (Versions 6.2.1, 5.2.4, 5.2.3, 4.1.1.0)

The IBM Tivoli Storage Manager (TSM), formerly ADSTAR Distributed Storage Manager (ADSM), is a client/server program that provides storage management and data access services to customers in a multivendor computer environment.

The storage management services component of ADSM/TSM provides an automated, centrally-scheduled, policy-managed backup and archive facility for IBM and non-IBM file servers and workstations.

Using TSM, you can maintain backup versions of workstation files that can be restored quickly and easily if the original files are damaged or lost. You can also archive files that are not currently needed on a client workstation, and retrieve them when necessary.

TSM includes the following:

A server program that allows a supported host to act as a backup and archive server for client workstations. It also allows a supported host to act as a migration server for client workstations.
The server program manages backup versions of files, archived copies of files, and migrated files based on the storage management policies defined by an TSM administrator, and sends copies back whenever the user requests them.
An administrative client program that allows TSM administrators to control and monitor server activities, define storage management policies for backup, archive, and space management services, and set up schedules to provide those services at regular intervals.
A backup-archive client program that allows users to back up and archive files from their workstations or file servers to TSM storage, and restore and retrieve backup versions of files and archived copies of files to their local file systems.
A hierarchical storage management (HSM) client program that provides space management services. The HSM client program migrates eligible files to TSM storage to maintain specific levels of free space on local file systems, and automatically recalls migrated files when they are accessed. It also allows users to migrate and recall specific files. This client is not available on all TSM-supported platforms.
An application programming interface (API) that allows application programmers to enhance an existing application with storage management services. End users of such applications must install the API modules to enable the TSM functions.

Automating TSM Tasks: TSM provides central scheduling to automatically perform TSM tasks. Your TSM administrator defines schedules to perform tasks at regular intervals or on a one-time basis. For example, you might have files that you want backed up daily, weekly, or monthly.

Note: The files in the "/home" directory at our Alpha stations are backed up daily!

For more information about the ADSM/TSM server, see ADSM/TSM-Server (FABS: HSM, Backup).

Introducing the TSM Backup-Archive Clients

The Tivoli Storage Manager (TSM) is a client/server program that helps you protect information on your workstation. Using TSM, you can maintain backup versions of your workstation files that you can restore quickly and easily if the original files are damaged or lost. You can also archive files that you do not currently need on your workstation or that you want to preserve in their current state, and retrieve them when necessary.

The portion of TSM that provides these services is the backup-archive client, a program that allows you to request backup and archive services from an TSM server.

From the main window, you use the menus listed on the action bar to do your backup and archive tasks. The File System Information window is divided into two parts: File Systems for Backup/Archive and File Systems for Restore/Retrieve. Before you can perform an action, you must select the file systems you want to use from one of these lists. Then, you can select an action from one of the menus on the action bar.

You can use the graphical user interface, or you can use TSM commands. You can do most tasks with the graphical user interface.

Backing Up and Restoring Files

You request backup services when you want TSM to save copies of files that you can restore if your original files are damaged or lost. These copies are called backup versions or backups.

To back up files, you can choose one of the following:

Incremental backup: Backs up all files and directories in the file systems you specify that meet certain criteria.
Selective backup: Backs up only those files you specify.

Running incremental backups on a regular basis can ensure that you have recent backup versions of your current files available at all times. Selective backup is useful when you want to back up only a specific subset of your files.

A root user on your workstation can use incremental backup to perform system-wide backups and can selectively back up any file on your system. If you are a user, you can back up any file you own using incremental or selective backup.

TSM backs up regular files and directories. It does not back up character special files, block special files, or FIFO special files (named pipe files).

If you accidentally erase a file that you need, or if a file on your workstation is damaged or lost, you can restore a backup version of the file from the server.

You can restore a single file, a group of files, or all the files in a directory. You can also choose to restore files to the same directory from which you backed them up or to a different directory.

A root user on your workstation can restore a backup version of any file on your workstation. If you are a user, you can restore a backup version of any file you own and any other files to which another user grants you access.

Archiving and Retrieving Files

You request archive services when you want to save files at a specific point, or when you want to place copies of files on long-term TSM storage and erase them from your workstation disk. These copies are called archive copies or archives.

Archives are never replaced with more current versions, but are preserved exactly as you store them.

A root user can archive any file on your system. If you are a user, you can archive any file to which you have read access. You can archive a single file, a group of files, or all the files in a directory. When you archive a file, you can enter a description of the file that you can use later to retrieve it. You can return archive copies to the same directory from which you archived them or to a different directory.

If you find you need a copy of an archived file back on your workstation, you can retrieve the file from the server.

A root user can retrieve any file archived to TSM storage from your workstation. If you are a user, you can retrieve any file you archive and any other files to which another user grants you access.

Starting a Session

Starting an TSM GUI Session

You must start TSM using one of the following commands:

% dsm                Runs TSM in the foreground

% dsm &              Runs TSM in the background

Starting an TSM Command-Line Session

Use the dsmc command to start an TSM command-line session. If you intend to issue several TSM commands, use interactive mode:

% dsmc loop

If you only need to run one command, you can use batch mode. In this case, include the TSM command on dsmc:

% dsmc incremental

Displaying Online Help

You can display online help in one of three ways. First, you can click on the Help button that appears in many windows. The Help button displays online information about the current operation.

Second, you can select the Help menu from the action bar.

When you select Task List, TSM displays the Help Text Info window. On the right side of the window is the task list. When you select an entry from the list, the text for that entry appears on the left side of the window.

When you select Help for Help, TSM displays information about how to use online help.

When you select Glossary, TSM displays a glossary of TSM terms.

When you select Product information, TSM displays a window that contains information about TSM.

Third, you can use the HELP command to access help in an TSM Command-Line Session:

% dsmc help

Backing Up and Restoring Files

One of TSM's main uses is to maintain a set of backup versions of the files on your workstation. This allows you to recover older versions of your files if those files are lost or damaged.

Do You Want to Back Up or Archive Those Files?

When TSM backs up or archives a file, it sends a copy of the file and its associated attributes to the TSM server. Backups and archives, though, have different purposes.

Backups are used to protect against file damage. A sequence of backup versions are kept for each file on your workstation (the number of backup versions is set by your TSM administrator), and older versions are deleted as newer versions are made.

Archive copies, however, are more permanent. They are used to maintain a file in a particular state indefinitely (although your administrator also sets a limit on how long archives are kept). They are useful if you think you might need to go back to a particular version of your files, or if you want to delete a file from your workstation and still be able to retrieve it if necessary. For example, you might need to save some spreadsheets for tax purposes, but because you are not using them, you do not want them left on your workstation.

Use backups to protect against unforeseen damage to your files, and archives for maintainin more permanent versions of your files.

When you back up files, TSM also backs up all related directory information. When you archive a file, ADSM saves fully-qualified path information with the file. TSM also stores access permissions with backup versions of files and archived copies of files.

Backing Up Files and Directories

There are two types of backup using TSM: incremental and selective.

An incremental backup backs up all files that are new or that have changed since the last incremental backup.

A selective backup backs up the specific files you indicate.

Your administrator might have set up schedules to automatically back up files on your workstation. See Note above for information on the schedules. The following sections cover how to back up files without using a schedule.

Backing Up New and Changed Files

The most effective way of maintaining a complete set of backup versions for your most important files is to regularly run incremental backups. An incremental backup backs up the new or changed files on your workstation.

There are two types of incremental backup: full and partial. A full incremental is also referred to simply as an incremental backup.

Backing Up Specific Files or Directories

You can use TSM to back up specific files, a group of files with similar names, or entire directories. This is called a selective backup.

You can choose the files you want to back up either by using a file specification (the path, name, and extension of the file) or by choosing the files or directories from a directory list.

You cannot back up empty directories or empty subdirectories nested within another directory. If you attempt to back up an empty directory, TSM returns this message:

ANS4095I  No files matching search criteria were found.

Backing Up Specific Files Using File Specifications

To back up selected files using file specifications:

Choose the file systems that contain the files you want to back up from the File Systems for Backup/Archive section of the File System Information window by clicking on them.
Click on the Backup menu; Backup by file specification item.
Fill in the path, name, and extension of the file you want to back up. You can use the standard wildcard characters to back up a set of similarly named files (wildcard characters are explained in Using Wildcard Characters).
Click on Include subdirectories if you want TSM to search all subdirectories of the directory you specified in your path for files that match your file specification.
If the path you specified begins with a file system, TSM searches that file system regardless of the file systems you selected in the File Systems for Backup/Archive section of the File System Information window.

If the path you specified includes a subdirectory that is a mounted file system, TSM does not does not search that subdirectory.

If you did not specify a path, and you click on Include subdirectories, TSM searches the subdirectories of the file systems you selected in the File Systems for Backup/Archive section of the File System Information window.
Click on List files to see the list of files that match your specification. Select the files you want from this list. (Click on Select All to select all the files).
Click on Backup to back up the selected files. The Backup Status window displays TSM's processing.

Backing Up Specific Files Using Directory Trees

To back up specific files or entire directories using directory trees:

Choose the file systems that contain the files you want to back up from the File Systems for Backup/Archive section of the File System Information window by clicking on them.
Click on the Backup menu; Backup by directory tree item.
Select the files and directories you want to back up:
- To select or deselect all the files in a directory, double-click the right mouse button on the directory name. When all the files in a directory are selected, the letter F is displayed to the left of the directory name. Selecting a directory does not select the directory's subdirectories.
- To select or deselect some of the files in a directory, double-click the left mouse button on the directory name. Then select or deselect files from the list that displays on the right side of the window by clicking the left mouse button on the file name. When some of the files in a directory are selected, the letter P is displayed to the left of the directory name.
If TSM does not let you select a file or directory, it is because your include-exclude options file excludes them from backup.

To see a list of the files you selected, click on List Selections.
Click on Backup to back up the selected files and directories. The Backup Status window displays TSM's processing.

Restoring Files or Directories

You can use TSM to restore backup versions of specific files, a group of files with similar names, or entire directories.

You can choose the files you want to restore either by using a file specification (the path, name, and extension of the file) or choosing the files or directories from a directory list, or by using a subdirectory path to restore a directory and its subdirectories.

Do You Want To Restore an Active or Inactive Backup?

Your administrator determines how many backup versions TSM maintains for each file on your workstation. Frequently, the administrator has TSM maintain more than one version of each file. Having multiple versions of a file allows you to restore older versions in case the most recent backup is damaged.

TSM considers the most recent backup version to be the active version. Any other backup version is considered an inactive version.

Every time TSM backs up your files, it marks the new backup version the active backup, and it changes what used to be the active backup to an inactive backup. When the maximum number of inactive versions is reached, TSM deletes the oldest inactive version.

If you want to restore a backup version that is inactive, you need to tell TSM to show both active and inactive versions. Do this by clicking on the View menu; Show active and inactive files item. You can change back to showing only active versions using Show active files only from the same menu.

If you try to restore both an active and inactive version of a file at the same time, only the active version is restored.

Restoring Files Using a File Specification

If you know the name of the file you want to restore, or you know at least part of the name, you can use the name to restore the file. Restoring a file using a file specification is much like backing one up. The windows are similar, except you are choosing files to restore rather than to back up. To restore a file by its file specification:

Choose the file systems that contain the backups from the File Systems for Restore/Retrieve section of the File System Information window by clicking on them.
Click on the Restore menu; Restore by file specification item.
Fill in the path, name, and extension of the file you are restoring. You can use the standard wildcard characters to restore a set of similarly named files (wildcard characters are explained in Using Wildcard Characters).
Click on Include subdirectories if you want TSM to search all subdirectories of the directory you specified in your path for files that match your file specification.
If the path you specified begins with a file system, TSM searches that file system regardless of the file systems you selected in the File Systems for Restore/Retrieve section of the File System Information window.

If the path you specified includes a subdirectory that is a mounted file system, TSM does not does not search that subdirectory.

If you did not specify a path, and you click on Include subdirectories, TSM searches the subdirectories of the file systems you selected in the File Systems for Restore/Retrieve section of the File System Information window.
Click on List files to see the list of files that match your specification. Select the files you want from this list. (Click on Select All to select all the files.)
Click on Restore and fill in the Restore Parameters window.
The restore parameters are:
- Destination
  You can choose where you want to restore each file:
  - Restore to original location restores each file to the file system and directory from which they were backed up.
  - Prompt restore destination per file lets you choose a location for each file as it is restored.
  - Prompt restore destination per directory lets you choose a location for each directory of files as the directories are restored.
  - Restore to the following destination lets you indicate the path to which all files are to be restored.
- Action for files that already exist
  If you are restoring files that still reside on your file systems, you need to tell TSM how to handle them. You can:
  - Show a prompt: Have TSM ask you if you want to overwrite the existing file as each file is restored.
  - Leave the existing file intact: Have TSM bypass any files that are already on your file system.
  - Replace the existing file: Have TSM overwrite existing files without first asking your permission, unless the existing file is read-only.
  - Replace the existing file (include ReadOnly): Have TSM overwrite existing files, including read-only files, without first asking your permission.
Click on OK to restore the files. The Restore Status window displays TSM's processing. The transaction field (Txn) contains (R) if the file is restored, (F) if the restore fails.

Restoring Files Using a Directory Tree

You can use a directory tree to choose the files you want to restore. Restoring a file using a directory tree is much like backing one up. The windows are the same, except you are choosing files to restore rather than to back up. To restore a file using a directory tree:

Choose the file systems that contain the backups from the File Systems for Restore/Retrieve section of the File Systems Information window by clicking on them.
Click on the Restore menu; Restore by directory tree item.
Select the directories and files you want to restore from the Restore by Directory Tree window.
Click on Restore and fill in the Restore Parameters window.
Click on OK to restore the files.

Restoring Files Using a Subdirectory Path

If you want to restore a directory and all of its subdirectories and files, and you know the name of the directory you want to restore, you can use restore by subdirectory path.

To restore a directory and its subdirectories:

Choose the file systems that contain the backups from the File Systems for Restore/Retrieve section of the File System Information window by clicking on them.
Click on the Restore menu; Restore subdirectory path item.
Fill in the Restore Subdirectory Path window:
1. Source Path: This is the directory you are trying to restore.
2. Destination Path: This is the directory to which you want the restored files written. You must fill in this field. You can restore the directory to a directory of a different name.
3. Action for files that already exist: If you are restoring files that still reside on your file systems, you need to tell TSM how to handle them.
Click on OK to restore the files in the directory and its subdirectories.

Restoring Files Using Commands

You can use the RESTORE command to restore files. Indicate the file you want restored and where you want to restore it. If you do not indicate a destination, the files are restored to their original location.

For example, to restore the /home/jones/h1.doc file to its original directory, use:

% dsmc restore /home/jones/h1.doc

To restore it under a new name, use:

% dsmc restore /home/jones/h1.doc /home/jones/h2.doc

If the file you are restoring no longer resides on your workstation, and you have run an incremental backup since deleting the file, there is no active backup of the file on the server. In this case, you need to use the LATEST option to tell the server to restore the most recent backup version. If you do not want the most recent version, use the PICK and INACTIVE options to get a list of backups from which you can choose.

For example, if you want to restore the latest version of the deleted file /home/jones/h1.doc, use:

% dsmc restore /home/jones/h1.doc -latest

Add the SUBDIR=YES option to the command if you need to restore the files in a directory and all of its subdirectories. For example, if you are recovering an entire file system (the /home file system in this case), you can restore all of the files using:

% dsmc restore /home -subdir=yes

Archiving and Retrieving Files

Archiving and retrieving files is similar to backing up and restoring files. Many of the windows and concepts are similar. In this chapter, we cover the main archive and retrieve tasks, but where windows and concepts are the same as for backup and restore, we direct you to sections within Backing Up and Restoring Files.

See Do You Want To Restore an Active or Inactive Backup? for a discussion of the difference between backups and archives.

Archiving Files

To archive files, you need to specifically select the files to archive. You can select the files by using a file specification or by choosing them from a directory tree.

Archiving Files Using a File Specification

To archive a file using a file specification:

Choose the file systems that contain the files to be archived from the File Systems for Backup/Archive section of the File System Information window by clicking on them.
Click on the Archive menu; Archive by file specification item.
Fill in the path, name, and extension of the file you want to archive, just as you would do when backing up a file. You can use the standard wildcard characters to archive a set of similarly named files.
Click on Include subdirectories if you want TSM to search all subdirectories of the directory you specified in your path for files that match your file specification.
If the path you specified begins with a file system, TSM searches that file system regardless of the file systems you selected in the File Systems for Backup/Archive section of the File System Information window.

If the path you specified includes a subdirectory that is a mounted file system, TSM does not does not search that subdirectory.

If you did not specify a path, and you click on Include subdirectories, TSM searches the subdirectories of the file systems you selected in the File Systems for Backup/Archive section of the File System Information window.
Click on List files to see the list of files that match your specification. Select the files you want from this list. (Click on Select All to select all the files).
Click on Archive to start archiving the selected files. The Archive Status window that is shown is similar to the Backup Status window. The transaction field (Txn) contains (A) for successfully archived files, (A/D) for successfully archived files that were deleted from your workstation, and (F) for failures. If there are any failures, you can click on List Failures to see a list of them.
Fill in the Archive Options window.
The archive options are:

File to be archived

This is the name of the file TSM is archiving. The options you set apply to this file.

Description

This is the description you want to keep with the archive copy.

Delete file after archive

Instructs TSM to delete the file from your local file system after it is archived and committed to ADSM server storage.
For symbolic links, TSM deletes only the link, not the data.

Management Class

This section allows you to choose the management class you want assigned to the file. You must select Override Include/Exclude List in order for TSM to use the management class you choose. Once you select override, you can choose a management class by clicking on it. For your convenience, TSM shows how long archives are kept according to the policy defined for each management class.
Click on OK to archive the file and bring up the Archive Options window for the next file, or click on Stop Prompt to archive all remaining files without bringing up the Archive Options window for each one.
If you click on Stop Prompt, TSM uses the description and management class you specified for all the remaining files. If you selected Delete file after archive, TSM also deletes all the remaining files you selected for archive from your local file system after they are archived and committed to TSM storage.

Archiving Files Using a Directory Tree

To archive files using a directory tree:

Choose the file systems that contain the files to be archived from the File Systems for Backup/Archive section of the File System Information window by clicking on them.
Click on the Archive menu; Archive by directory tree item.
Select the files and directories you want to archive in the same way you would choose them for backup:
- To select or deselect all the files in a directory, double-click the right mouse button on the directory name. When all the files in a directory are selected, the letter F is displayed to the left of the directory name. Selecting a directory does not select the directory's subdirectories.
- To select or deselect some of the files in a directory, double-click the left mouse button on the directory name. Then select or deselect files from the list that displays on the right side of the window by clicking the left mouse button on the file name. When some of the files in a directory are selected, the letter P is displayed to the left of the directory name.
To see a list of the files you selected, click on List Selections.
Click on Archive to start archiving the selected files. The Archive Status window that is shown is similar to the Backup Status window.
Fill in the Archive Options window.
Click on OK to archive the file and bring up the Archive Options window for the next file, or click on Stop Prompt to archive all remaining files without bringing up the Archive Options window for each one.
If you click on Stop Prompt, TSM uses the description and management class you specified for all the remaining files. If you selected Delete file after archive, TSM also deletes all the remaining files you selected for archive from your local file system after they are archived and committed to TSM storage.

Archiving Files Using Commands

You can use the ARCHIVE command to archive files. Use wildcards to archive more than one file at a time. You can archive all the files in a directory, and you can use the SUBDIR=YES option to include files in all subdirectories under that directory in the archive. You can also use the DELETEFILES option if you want TSM to delete the files from your local workstation after they are archived and committed to TSM storage.

For example, to archive the files in the /home/jones/proj directory and the files in its subdirectories, use:

% dsmc archive /home/jones/proj -subdir=yes -deletefiles

You can use more than one file specification on the ARCHIVE command. For example, to archive the /home/jones/h1.doc and /home/jones/test.doc files, use:

% dsmc archive /home/jones/h1.doc /home/jones/test.doc

Use the description option to assign a description to the archive:

% dsmc archive /home/jones/h1.doc -description="Chapter 1, first version"

Retrieving Archived Files

You retrieve a file when you want to return an archive copy from the TSM server to your workstation.

Retrieving Files

To retrieve an archived file:

Choose the file systems that contain the files to be archived from the File Systems for Restore/Retrieve section of the File System Information window by clicking on them.
Click on the Retrieve menu; Retrieve by file specification item.
Fill in the Retrieve Scope window. You can get a list of archived files using the file name, description, archive date, and expiration date for the file.
Click on List files to get a list of files.
Click on the files you want to delete in the Retrieve by File Specification window.
Fill in the Retrieve Parameters window. You select where to store the retrieved files and what to do if a file is already at that destination.
Click on OK to retrieve the files. The Retrieve Status window shows the results of your action. An (R) in the transaction field (Txn) indicates that the file is retrieved; and (F) indicates failure.

Retrieving Files Using Commands

You can use the RETRIEVE command to retrieve files. Indicate the file you want retrieved and a destination. If you do not indicate a destination, the files are retrieved to their original location.

For example, to retrieve the /home/jones/h1.doc file to its original directory, use:

% dsmc retrieve /home/jones/h1.doc

To retrieve it under a new name, use:

% dsmc retrieve /home/jones/h1.doc /home/jones/h2.doc

You can use the PICK option to get a list of archives from which you can choose.

Using Wildcard Characters

You can use wildcard characters when you want to specify multiple files with similar names in one command. Without wildcards, you would have to repeat the command for each file.

In a command, wildcard characters can only be used in the file name or extension. They cannot be used to specify destination files, file systems, or directories.

The wildcard characters you can use are:

*       Matches zero or more characters

?       Matches any single character at the current position

The following are examples of using the * wildcard character:

Pattern	Matches
`ab*`	`Jab, abb, abxxx`
`ab*rs`	`abrs, abtrs, abrsrs`
`abefrs`	`abefrs, abefghrs`
`.`	`ab.efr, abgh.r, .befr`

Note in the last example that .befr does match the *.* pattern. If you have worked with wildcard characters in the UNIX shell, you may have noticed that files that start with a period are handled as exceptions to normal pattern-matching rules. In the UNIX shell, .befr does not match the *.* pattern. To obtain a match to a file name that begins with a period, you must place the period in the first position of the pattern-matching expression (.*).

However, in TSM, the use of the wildcard character * matches all files. TSM accomplishes this by requiring that all pattern-matching expressions be enclosed with quotation marks. When the pattern-matching expression is enclosed with quotation marks, TSM does the matching and expansion of the wildcard characters, rather than the UNIX shell, through the use of a different algorithm.

When issuing commands while in batch mode, you should enclose all pattern-matching expressions with quotation marks. Otherwise, the command might not produce the results you want. This applies when you use a wildcard character by itself ("*"), and when you use the wildcard character as part of an expression such as "/user/home/*.c". However, quotation marks are not required when issuing commands while in interactive mode. Examples of using pattern-matching expressions are clearly illustrated in command syntax diagrams and command examples.

Here are examples of using the ? wildcard character:

Pattern	Matches
`ab?`	`abc`
`ab?rs`	`abfrs`
`ab?ef?rs`	`abdefjrs`
`ab??rs`	`abcdrs, abzzrs`

Known Problems

The summary statistics are incorrect when filespaces greater than two gigabytes are backed up, restored, archived, or retrieved.
(2 gigabytes-1) is the largest size file that can be backed up with the TSM Backup/Archive client at the current time.
Selective backup of just a few files can take unexpectedly long if there are already thousands of files and hundreds of megabytes of data backed up for that client for that filespace, especially on UNIX clients with non-root users.