restore Command

AIX Version 4.3 Commands Reference, Volume 4

restore Command

Purpose

Extracts files from archives created with the backup command.

Syntax

To Restore Files Archived by File Name

restore -x [ d M v q ] [ -b Number ] [ -f Device ] [ -s SeekBackup ] [ -X Number ] [ File ... ]

To List Files Archived by File Name

restore -T [ q -v ] [ -b Number ] [ -f Device ] [ -s SeekBackup ]

To Restore Files Archived by File System

restore -r [ B q v y ] [ -b Number ] [ -f Device ] [ -s SeekBackup ]

To Restore Files Archived by File System

restore -R [ B v y ] [ -b Number ] [ -f Device ] [ -s SeekBackup ]

To Restore Files Archived by File System

restore -i [ h m q v y ] [ -b Number ] [ -f Device ] [ -s SeekBackup ]

To Restore Files Archived by File System

restore -x [ B h m q v y ] [ -b Number ] [ -f Device ] [ -s SeekBackup ] [ File ... ]

To List Files Archived by File System

restore -t | -T [ B h q v y ] [ -b Number ] [ -f Device ] [ -s SeekBackup ] [ File ... ]

Description

The restore command reads archives created by the backup command and extracts the files stored on them. These archives can be in either file-name or file-system format. An archive can be stored on disk, diskette, or tape. Files must be restored using the same method by which they were archived. This requires that you know the format of the archive. The archive format can be determined by examining the archive volume header information that is displayed when using the -T flag. When using the -x, -r, -T, or -t flags, the restore command automatically determines the archive format.

Individual files can be restored from either file-name or file-system archives by using the -x flag and specifying the file name. The file name must be specified as it exists on the archive. Files can be restored interactively from file-system archives using the -i flag. The names of the files on an archive can be written to standard output using the -T flag.

The diskette device, /dev/rfd0, is the default media for the restore command. To restore from standard input, specify a - (dash) with the -f flag. You can also specify a range of devices, such as /dev/rmt0-2.

Notes:
If you are restoring from a multiple-volume archive, the restore command reads the volume mounted, prompts you for the next volume, and waits for your response. After inserting the next volume, press the Enter key to continue restoring files.

If an archive, created using the backup command, is made to a tape device with the device block size set to 0, it may be necessary for you to have explicit knowledge of the block size that was used when the tape was created in order to restore from the tape.

Multiple archives can exist on a single tape. When restoring multiple archives from tape, the restore command expects the input device to be a no-retension-on-open, no-rewind-on-close tape device. Do not use a no-rewind tape device for restoring unless either the -B, -s, or -X flag is specified. For more information on using tape devices, see the rmt special file.

File-System Archives

File-system archives are also known as i-node archives due to the method used to archive the files. A file-system name is specified with the backup command, and the files within that file system are archived based on their structure and layout within the file system. The restore command restores the files on a file-system archive without any special understanding of the underlying structure of the file system.

When restoring file-system archives, the restore command creates and uses a file named restoresymtable. This file is created in the current directory. The file is necessary for the restore command to do incremental file-system restores.

Note: Do not remove the restoresymtable file if you perform incremental file-system backups and restores.

The File parameter is ignored when using either the -r or the -R flag.

File-Name Archives

File-name archives are created by specifying a list of file names to archive to the backup command. The restore command restores the files from a file-name archive without any special understanding of the underlying structure of the file system.

Flags

-B	Specifies that the archive should be read from standard input. Normally, the restore command examines the actual medium to determine the backup format. When using a \| (pipe), this examination cannot occur. As a result, the archive is assumed to be in file-system format, and the device is assumed to be standard input (-f -).
-b Number	For backups done by name, specifies the number of 512-byte blocks; for backups done by i-node, specifies the number of 1024-byte blocks to read in a single output operation. When the restore command reads from tape devices, the default is 100 for backups by name and 32 for backups by i-node. The read size is the number of blocks multiplied by the block size. The default read size for the restore command reading from tape devices is 51200 (100 * 512) for backups by name and 32768 (32 * 1024) for backups by i-node. The read size must be an even multiple of the tape's physical block size. If the read size is not an even multiple of the tape's physical block size and it is in fixed block mode (nonzero), the restore command tries to determine a valid value for Number. If successful, the restore command changes Number to the new value, writes a message about the change to standard output, and continues. If unsuccessful in finding a valid value for Number, the restore command writes an error message to standard error and exits with a nonzero return code. Larger values for the Number parameter result in larger physical transfers from the tape device. The value of the -b flag is always ignored when the restore command reads from diskette. In this case, the command always reads in clusters that occupy a complete track.
-d	Indicates that, if the File parameter is a directory, all files in that directory should be restored. This flag can only be used when the archive is in file-name format.
-f Device	Specifies the input device. To receive input from a named device, specify the Device variable as a path name (such as `/dev/rmt0` ). To receive input from the standard output device, specify a - (minus sign). The - (minus) feature enables you to pipe the input of the restore command from the dd command. You can also specify a range of archive devices. The range specification must be in the following format: /dev/deviceXXX-YYY where XXX and YYY are whole numbers, and XXX must always be less than YYY; for example, `/dev/rfd0-3` . All devices in the specified range must be of the same type. For example, you can use a set of 8mm, 2.3GB tapes or a set of 1.44MB diskettes. All tape devices must be set to the same physical tape block size. If the Device variable specifies a range, the restore command automatically goes from one device in the range to the next. After exhausting all of the specified devices, the restore command halts and requests that new volumes be mounted on the range of devices.
-h	Restores only the actual directory, not the files contained in it. This flag can only be used when the archive is in file-system format. This flag is ignored when used with the -r or -R flags.
-i	Allows you to interactively restore selected files from a file-system archive. The subcommands for the -i flag are: cd Directory Changes the current directory to the specified directory. add [File] Specifies that the File parameter is added to the list of files to extract. If File is a directory, that directory and all the files contained in it are added to the extraction list (unless the -h flag is used). If File is not specified, the current directory is added to the extraction list. delete [File] Specifies that the File parameter is to be removed from the list of files to be extracted. If File is a directory, that directory and all the files contained in it are removed from the extraction list (unless the -h flag is used). ls [Directory] Displays the directories and files contained within the Directory parameter. Directory names are displayed with a / (slash) after the name. Files and directories, within the specified directory, that are on the extraction list are displayed with an * (asterisk) before the name. If verbose mode is on, the i-node number of the files and directories is also displayed. If the Directory parameter is not specified, the current directory is used. extract Restores all the directories and files on the extraction list. pwd Displays the full path name of the current directory. verbose Causes the ls subcommand to display the i-node number of files and directories. Additional information about each file is also displayed as it is extracted from the archive. setmodes Sets the owner, mode, and time for all directories added to the extraction list. quit Causes restore to exit immediately. Any files on the extraction list are not restored. help Displays a summary of the subcommands.
-M	Sets the access and modification times of restored files to the time of restoration. If a restored file is an archive created by the ar command, the modification times in all the member headers are also set to the time of restoration. You can specify the -M flag only when you are restoring individually named files and only if the -x or -X flags are also specified. When the -M flag is not specified, the restore command maintains the access and modification times as they appear on the backup medium. The -M flag is used when the data is in the AIX Version 2 backup by-i-node or by-name format.
-m	Renames restored files to the file's i-node number as it exists on the archive. This is useful if a few files are being restored and you want these files restored under a different file name. Since any restored archive members are renamed to their i-node numbers, directory hierarchies and links are not preserved. Directories and hard links are restored as regular files. The -m flag is used when the archive is in file-system format.
-q	Specifies that the first volume is ready to use and that the restore command should not prompt you to `mount the volume and hit Enter` . If the archive spans multiple volumes, the restore command prompts you for the subsequent volumes.
-r	Restores all files in a file-system archive. The -r flag is only used to restore complete level 0 backups or to restore incremental backups after a level 0 backup is restored. The restoresymtable file is used by restore to pass information between incremental restores. This file should be removed once the last incremental backup is restored. The File parameter is ignored when using the -r flag.
-R	Requests a specific volume of a multiple-volume, file-system archive. The -R flag allows a previously interrupted restore to be restarted. The File parameter is ignored when using the -R flag. Once restarted, the restore command behavior is the same as with the -r flag.
-s SeekBackup	Specifies the backup to seek and restore on a multiple-backup tape archive. The -s flag is only applicable when the archive is written to a tape device. To use the -s flag properly, a no-rewind-on-close and no-retension-on-open tape device, such as /dev/rmt0.1 or /dev/rmt0.5, must be specified. If the -s flag is specified with a rewind tape device, the restore command displays an error message and exits with a nonzero return code. If a no-rewind tape device is used and the -s flag is not specified, a default value of -s 1 is used. The value of the SeekBackup parameter must be in the range of 1 to 100 inclusive. It is necessary to use a no-rewind-on-close, no-retension-on-open tape device because of the behavior of the -s flag. The value specified with -s is relative to the position of the tape's read/write head and not to an archive's position on the tape. For example, to restore the first, second, and fourth backups from a multiple-backup tape archive, the respective values for the -s flag would be -s 1, -s 1, and -s 2.
-t	Displays information about the backup archive. If the archive is in file-system format, a list of files found on the archive is written to standard output. The name of each file is preceded by the i-node number of the file as it exists on the archive. The file names displayed are relative to the root (/) directory of the file system that was backed up. If the File parameter is not specified, all the files on the archive are listed. If the File parameter is used, then just that file is listed. If the File parameter refers to a directory, all the files contained in that directory are listed. If the archive is in file-name format, information contained in the volume header is written to standard output. This flag can be used to determine if the archive is in file-name or file-system format.
-T	Displays information about the backup archive. If the archive is in file-name format, the information contained in the volume header and a list of files found on the archive are written to standard output. The File parameter is ignored for file-name archives. If the archive is in file-system format, the behavior is identical to the -t flag.
-v	Displays additional information when restoring. If the archive is in file-name format and either the -x or -T flag is specified, the size of the file as it exists on the archive is displayed in bytes. Directory, block, or character device files are archived with a size of 0. Symbolic links are listed with the size of the symbolic link. Hard links are listed with the size of the file, which is how they are archived. Once the archive is read, a total of these sizes is displayed. If the archive is in file-system format, directory and nondirectory archive members are distinguished.
-x	Restores individually named files specified by the File parameter. If the File parameter is not specified, all the archive members are restored. If the File parameter is a directory and the archive is in file-name format, only the directory is restored. If the File parameter is a directory and the archive is in file-system format, all the files contained in the directory are restored. The file names specified by the File parameter must be the same as the names shown by the restore -T command. Files are restored with the same name they were archived with. If the file name was archived using a relative path name (./filename), the file is restored relative to the current directory. If the archive is in file-system format, files are restored relative to the current directory. The restore command automatically creates any needed directories. When using this flag to restore file-system backups, you are prompted to enter the beginning volume number.
-X VolumeNumber	Begins restoring from the specified volume of a multiple-volume, file-name backup. Once started, the restore command behavior is the same as with the -x flag. The -X flag applies to file-name archives only.
-y	Continues restoring when tape errors are encountered. Normally, the restore command asks you whether or not to continue. In either case, all data in the read buffer is replaced with zeroes. The -y flag applies only when the archive is in file-system format.
-?	Displays a usage message.

Exit Status

This command returns the following exit values:

0	Successful completion.
>0	An error occurred.

Examples

To list the names of files in either a file-name or file-system archive on the diskette device /dev/rfd0, enter:
```
restore -Tq
```
The archive is read from the /dev/rfd0 default restore device. The names of all the files and directories contained in the archive are displayed. For file-system archives, the file name is preceded by the i-node number of the file as it exists on the archive. The -q flag tells the restore command that the first volume is available and is ready to be read. As a result, you are not prompted to mount the first volume.
To restore a specific file, enter:
```
restore -xvqf myhome.bkup system.data
```
This command extracts the file system.data into the current directory from the archive myhome.bkup . The archive in this example is in the current directory. File and directory names must be specified as they are displayed when using the -T flag. The -v flag displays additional information during the extraction. This example applies to both file-name and file-system archives.
To restore a specific directory and the contents of that directory from a file-name archive, enter:
```
restore -xdvqf /dev/rmt0 /home/mike/tools
```
The -x flag tells restore to extract files by their file name. The -d tells restore to extract all the files and subdirectories in the /home/mike/tools directory. File and directory names must be specified as they are displayed when using the -T flag. If the directories do not exist, they are created.
To restore a specific directory and the contents of that directory from a file-system archive, enter:
```
restore -xvqf /dev/rmt0 /home/mike/tools
```
This command extracts files by file name. File and directory names must be specified as they are displayed when using the -T flag. If the directories do not exist, they are created.
To restore an entire file-system archive, enter:
```
restore -rvqf /dev/rmt0
```
This command restores the entire file system archived on the tape device, /dev/rmt0 , into the current directory. This example assumes you are in the root directory of the file system to be restored. If the archive is part of a set of incremental file-system archives, the archives should be restored in increasing backup-level order beginning with level 0 (for example, 0 , 1 , 2 ).
To restore the fifth and ninth backups from a single-volume, multiple-backup tape, enter:
```
restore -xvqs 5 -f/dev/rmt0.1
restore -xvqs 4 -f/dev/rmt0.1
```
The first command extracts all files from the fifth archive on the multiple-backup tape specified by /dev/rmt0.1 . The .1 designator specifies the tape device will not be retensioned when it is opened and that it will not be rewound when it is closed. It is necessary to use a no-rewind-on-close, no-retension-on-open tape device because of the behavior of the -s flag. The second command extracts all the files from the fourth archive (relative to the current location of the tape head on the tape). After the fifth archive has been restored, the tape read/write head is in a position to read the archive. Since you want to extract the ninth archive on the tape, you must specify a value of 4 with the -s flag. This is because the -s flag is relative to your position on the tape and not to an archive's position on the tape. The ninth archive is the fourth archive from your current position on the tape.
To restore the fourth backup, which begins on the sixth tape on a 10-tape multiple-backup archive, put the sixth tape into the tape drive and enter:
```
restore -xcs 2 -f /dev/rmt0.1 /home/mike/manual/chap3
```
Assuming the fourth backup is the second backup on the sixth tape, specifying -s 2 advances the tape head to the beginning of the second backup on this tape. The restore command then restores the specified file from the archive. If the backup continues onto subsequent volumes and the file has not been restored, the restore command instructs you to insert the next volume until the end of the backup is reached. The -f flag specifies the no-rewind, no-retension tape device name.
Note: The -s flag specifies the backup number relative to the tape inserted in the tape drive, not to the overall 10-tape archive.
To improve the performance on streaming tape devices, pipe the dd command to the restore command by entering:
```
dd if=/dev/rmt0 bs=64b | restore -xf- -b64
```
The dd command reads the archive from the tape using a block size of 64 512-byte blocks and writes the archive to standard output. The restore command reads the standard input using a block size of 64 512-byte blocks. The value of the block size used by the dd command to read the archive from the tape must be an even multiple of the block size that was used to create the tape with the backup command. For example, the following backup command could be used to create the archive that this example extracts:
```
find /home -print | backup -ivqf/dev/rmt0 -b64
```
This example applies to archives in file-name format only. If the archive was in file-system format, the restore command should include the -B flag.
To improve the performance of the restore command on the 9348 Magnetic Tape Unit Model 12, you can change the block size by entering:
```
chdev -l DeviceName -a BlockSize=32k
```

Files

/dev/rfd0	Specifies the default restore device.
/usr/sbin/restore	Contains the restore command.

Related Information

The ar command, backup command, mkfs command, fsck command, dd command.

The filesystems file, backup file, rmt special file.

The Backup Overview for System Management in AIX Version 4.3 System Management Guide: Operating System and Devices.

The File Systems Overview for System Management in AIX Version 4.3 System Management Guide: Operating System and Devices explains file system types, management, structure, and maintenance.

The System Management Interface Tool (SMIT) Overview in AIX Version 4.3 System Management Guide: Operating System and Devices.