Restore

The restore command obtains copies of backup versions of your files from the IBM Spectrum Protect server, or inside a backup set.

To restore files, specify the directories or selected files, or select the files from a list. Restore files to the directory from which you backed them up or to a different directory. The backup-archive client uses the preservepath option with the subtree value as the default for restoring files.

Note:

On UNIX and Linux® systems when a symbolic link is created its modification time is set to the current system time and cannot be changed. So, when restoring a symbolic link its modification date and time is set to the date and time of the restore, not to the date and time the link had when it was backed up. As a result, the client backs up the symbolic link during the next incremental backup because its modification time changed since the last backup.

Note:

When you restore directory, its modification date and time is set to the date and time of the restore, not to the date and time the directory had when it was backed up. This is because the client restores the directories first, then adds the files to the directories.
An error occurs if you attempt to restore a file whose name is the same the short name of an existing file. For example, if you attempt to restore a file that you specifically named ABCDEF~1.DOC into the same directory where a file named abcdefghijk.doc exists, the restore fails because the Windows operating system equates the file named abcdefghijk.doc to a short name of ABCDEF~1.DOC. The restore function treats this as a duplicate file.
If this error occurs, perform any of the following actions to correct it:
- Restore the file with the short file name to a different location.
- Stop the restore and change the name of the existing file.
- Disable the short file name support on Windows.
- Do not use file names that would conflict with the short file naming convention; for example, do not use ABCDEF~1.DOC.

If you set the subdir option to yes when you restore a specific path and file, the client recursively restores all subdirectories under that path, and any instances of the specified file that exist under any of those subdirectories.

When you restore an entire directory or directory tree, and you do not specify the inactive, latest, pick, todate, and fromdate options on the restore command, the client tracks which objects are restored. If the restore process is interrupted for any reason, you can restart the restore at the point of interruption by entering the restart restore command. It is possible to create more than one restartable restore session. Restores are only restartable if the file specification is fully wildcarded. For example, for a restore that is restartable, enter:

  dsmc rest /home/* -sub=yes

For a restore that is not restartable, enter:

  dsmc rest "/Users/user1/file?.c" -sub=yes

Use the query restore command to display a list of your restartable restore sessions in the server database. Further backups of the file system cannot be performed unless the restartable restore completes by using the restart restore command or is canceled by using the cancel restore command.

  dsmc rest "/Users/user1/file?.c" -sub=yes

Windows operating systems For more information, see the Microsoft Knowledge Base article Q121007, entitled How to Disable the 8.3 Name Creation on NTFS Partitions, for more information.

Windows operating systems If the restore command is tried again because of a communication failure or session loss, the transfer statistics display the bytes that the client attempted to transfer across all command attempts. Therefore, the statistics for bytes transferred might not match file statistics, such as those for file size.

Supported Clients

This command is valid for all clients.

Syntax

Parameters

file

This parameter specifies that the source file specification is an explicit file name. This parameter is required when you restore a file name from the current path, when you do not specify a relative or absolute path, and when the file name conflicts with one of the reserved restore command keywords, such as restore backupset.

sourcefilespec

Specifies the path and file name in storage that you want to restore. Use wildcard characters to specify a group of files or all the files in a directory.

Note: If you include filespacename, do not include a drive letter in the file specification.

{filespacename}

Specifies the file space (enclosed in braces) on the server that contains the files you want to restore. This is the name on the workstation drive from which the files were backed up.

Specify the file space name if the drive label name has changed or if you are restoring files that were backed up from another node that had drive labels that are different from yours.

Note: You must specify a mixed or lowercase NTFS or ReFS file space name that is enclosed in quotation marks and braces. For example, {"NTFSDrive"}. Single quotation marks or double quotation marks are valid in loop mode. For example: {"NTFSDrive"} and {'NTFSDrive'} are both valid. In batch mode, only single quotation marks are valid. The single quotation marks requirement is a restriction of the operating system.

destinationfilespec

Specifies the path and file name where you want to place the restored files. If you do not specify a destination, the client restores the files to the original source path.

Windows operating systems When you enter the destinationfilespec, consider the following points:

If the sourcefilespec names a single file, the destinationfilespec can be a file or a directory. If you are restoring a single file, you can optionally end the specification with a file name if you want to give the restored file a new name.
If the sourcefilespec is wildcarded or subdir=yes is specified, the destinationfilespec must be a directory and end with a directory delimiter (\).

Note: If the destination path or any part of it does not exist, the client creates it.

Note: If you do not specify a destination, the client determines whether the original file system can be reached. If the original file system cannot be reached, the client will not restore the file. In this case, you can specify a different destination and try the command again.

BACKUPSETName=

Specifies the name of a backup set. This parameter is optional. If you specify the backupsetname parameter with the restore command, you cannot use the pick option.

The value of backupsetname depends on the location of the backup set, and corresponds to one of the following options:

backupsetname: Specifies the name of the backup set from the IBM Spectrum Protect server. If the location parameter is specified, you must set -location=server. If the backup set resides in IBM Spectrum Protect server storage, the backup set must have a TOC.
localfilename: Specifies the file name of the first backup set volume. You must set -location=file.
tapedevice: Specifies the name of the tape device that contains the backup set volume. You must use a Windows-provided device driver, not the device driver that is provided by IBM®. You must set -location=tape.

LOCation=

Specifies where the client searches for the backup set. If you do not specify the location parameter, the client searches for backup sets on the IBM Spectrum Protect server.

server: Specifies that the client searches for the backup set from the server. This is the default location.
file: Specifies that the client searches for the backup set from a local file.
tape: Specifies that the client searches for the backup set from a local tape device.

Table 1. Restore command: Related options
Option	Where to use
asrmode	Command line only.
dateformat	Client options file (dsm.opt) or command line.
dateformat	Client user options file (dsm.opt) or command line.
dirsonly	Command line only.
filelist	Command line only.
filesonly	Command line only.
followsymbolic	Client user options file (dsm.opt) or command line.
fromdate	Command line only.
fromnode	Command line only.
fromowner	Command line only.
fromtime	Command line only.
ifnewer	Command line only.
inactive	Command line only.
latest	Command line only.
numberformat	Client options file (dsm.opt) or command line.
numberformat	Client user options file (dsm.opt) or command line.
pick Note: If you specify the backupsetname parameter with the restore command, you cannot use the pick option.	Command line only.
pitdate	Command line only.
pittime	Command line only.
preservepath	Command line only.
replace	Client options file (dsm.opt) or command line.
replace	Client user options file (dsm.opt) or command line.
skipntpermissions	Client options file (dsm.opt) or command line.
skipntsecuritycrc	Client options file (dsm.opt) or command line.
subdir	Client options file (dsm.opt) or command line.
subdir	Client user options file (dsm.opt) or command line.
tapeprompt	Client options file (dsm.opt) or command line.
tapeprompt	Client user options file (dsm.opt) or command line.
timeformat	Client options file (dsm.opt) or command line.
timeformat	Client user options file (dsm.opt) or command line.
todate	Command line only.
totime	Command line only.

Examples

Task: Restore a single file named budget in the /Users/user1/Documents directory.
restore /home/devel/projecta/budget
Task: Restore a single file named budget.fin.
restore c:\devel\projecta\budget.fin
Task: Restore a single file named budget, which exists in the current directory.
restore file budget
Task: Restore a single file named budget.fin, which exists in the current directory.
restore file budget.fin
Task: Restore files from the abc file space proj directory.
rest {"abc"}\proj\*.*
Task: Restore all files with a file extension of .c from the /home/devel/projecta directory.
restore "/home/devel/projecta/*.c"
Task: Restore all files with a file extension of .c from the c:\devel\projecta directory.
rest c:\devel\projecta\*.c
Task: Restore all files with an extension of .c from the \devel\projecta directory that is located in the winnt file space.
rest {winnt}\devel\projecta\*.c
Task: Restore all files with a file extension of .c from the c:\devel\projecta directory to the c:\newdevel\projectn\projecta directory. If the projectn or projectn\projecta directory does not exist, it is created.
restore c:\devel\projecta\*.c c:\newdevel\projectn\
Task: Restore files in the /user/project directory. Use the pick and inactive options to select active and inactive backup versions.
restore "/user/project/*" -pick -inactive
Task: Restore files in the c:\project directory. Use the pick and inactive options to select active and inactive backup versions.
restore c:\project\* -pi -ina
Task: Restore all files from the /home/devel/projecta directory that end with the character .c to the /home/newdevel/projectn/projecta directory. If the projectn or the projectn/projecta directory does not exist, it is created.
restore "/home/devel/projecta/*.c" /home/newdevel/projectn/
Task: Restore all files in the /home/mydir directory to their state as of 1:00 PM on August 17, 2002.
restore -pitd=8/17/2002 -pitt=13:00:00 /home/mydir/
Task: Restore all files in the c:\mydir directory to their state as of 1:00 PM on August 17, 2002.
restore -pitd=8/17/2002 -pitt=13:00:00 c:\mydir\
Task: Restore all objects in the /home/myid/ directory. Since this restore operation is fully wildcarded, if the restore process is interrupted, a restartable restore session is created.
res "/home/myid/*"
Task: Restore a file from the renamed file space \\your-node\h$_OLD to its original location. Enter both the source and destination as follows:
res \\your-node\h$_OLD\docs\myresume.doc h:\docs\
Task: Restore all files in the /home/mydir directory to their state as of 1:00 PM on August 17, 2002.
restore -pitd=8/17/2002 -pitt=13:00:00 /home/mydir/
Task: Restore all files in the c:\mydir directory to their state as of 1:00 PM on August 17, 2002.
restore -pitd=8/17/2002 -pitt=13:00:00 c:\mydir\
Task: Restore a single file named budget.fin contained within the backup set daily_backup_data.12345678.
restore c:\projecta\budget.fin -backupsetname=daily_backup_data.12345678 -location=server