restore Command

Purpose

Extracts files from archives that are created with the backup command.

Syntax

To restore files archived by file name

restore -x [ d M n O Q v q e ] [ -b Number] [-L Label] [-I Label] [ -f Device] [ -s SeekBackup] [ -E { force | ignore | warn }] [File ... ]

To list files archived by file name

restore -T | -t [a l n q v Q ] [ -bNumber] [ -fDevice] [ -sSeekBackup]

To restore files archived by file system

restore -r [ B O n q v y] [ -bNumber] [ -fDevice] [ -sSeekBackup]

To restore files archived by file system

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

To restore files archived by file system

restore -i [ O h m n q v y ] [ -bNumber] [ -f Device] [ -s SeekBackup]

To restore files archived by file system

restore -x [ B O h n m q v y ] [ -bNumber] [ -fDevice] [ -sSeekBackup] [File ... ]

To restore files beginning at a specified volume number

restore -X Number [-MdnqveOQ ] [ -b Number] [ -f Device] [ -s Number] [ -E { force | ignore | warn }] [File ... ]

To list files archived by file system

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

To restore file attributes archived by file name

restore -Pstring [B d qv Q ] [ bNumber] [ s SeekNumber] [-L Label] [-I Label] [-f Device] [File ... ]

To restore file attributes archived by file system

restore -Pstring [ hqv] [ b Number] [ s SeekNumber] [-f Device] [File ... ]

Description

The restore command reads archives created by the backup command and extracts the files that are 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 by using the same method that was used to archive the files. This operation 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 you use the -T flag. When the -x, -r, -T, or -t flags are used, 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 by using the -i flag. The names of the files on an archive can be written to standard output by using the -T flag.

Users must have write access to the file system device or have Restore authorization to extract the contents of the archive.

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/rfd0.

Notes:

If you are restoring from a multiple-volume archive, the restore command reads the volume that mounted, prompts you for the next volume, and waits for your response. After the next volume is inserted, press the Enter key to continue restoring files.
If an archive, created by using the backup command, is made to a tape device with the device block size set to 0, it is necessary for you to have explicit knowledge of the block size that was used when the tape was created to restore from the tape.
Multiple archives can exist on a single tape. When multiple archives are restored from the 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 because 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 you restore the 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 run incremental file system backups and restores.

The File parameter is ignored when you use 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. The restore command allows for metacharacter to be used when you specify files for archive extraction. This process provides the capability to extract files from an archive that is based on pattern matching. A pattern file name must be enclosed in single quotations, and patterns must be enclosed in brackets (...).

About sparse files

Files in the operating system file system that contain long strings of Nulls can be stored efficiently when compared to the other files. If a string of Nulls spans an entire allocation block, that whole block is not stored on disk at all. Files where one or more blocks are omitted in this way are called sparse files. The missing blocks are also known as holes.

Note: Restores the non-sparse files as nonsparse because they were archived by the name format of the backup command for both packed and unpacked files. It is necessary to know the sparseness and nonsparseness of the file being restored before you archive the files. This check is required because by enabling the -e flag, the flag restores the sparse files as nonsparse. This flag must be enabled only if the files to be restored are non-sparse consisting of more than 4 KB Nulls. If the -e flag is specified during the restore operation, it successfully restores all normal files normally and nonsparse database files as nonsparse.

Flags

Item	Descriptor
`-a`	Specified with the `t` and `T` option, the `-a` option displays the list of files in the archive, along with their permissions.
`-B`	Specifies that the archive must be read from standard input. Normally, the restore command examines the actual medium to determine the backup format. When you use 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`).
`-bNumber`	Specifies the number of 512-byte blocks for backups done by name. For backups that are done by i-node, the flag specifies the number of 1024-byte blocks to read in a single output. 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 that are 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 tapes physical block size. If the read size is not an even multiple of the tapes 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, write 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 must be restored. This flag can be used when the archive is in file name format.
`-e`	Specifies to not restore sparse files actively. If a file has a block that is aligned and sized areas that are Null populated, then the restore operation creates physical space for those file system blocks to be allocated and filled with Nulls. The file size that is specified in bytes corresponds to the space taken within the file system. This flag must be enabled only if files are to be restored are nonsparse consisting of more than 4 KB Nulls. If the `-e` flag is specified during restore, it successfully restores all normal files normally and nonsparse database files as nonsparse.
`-E`	The `-E` option extracts beginning at a specified volume number and requires one of the following arguments. If you omit the `-E` option, `warn` is the default behavior. force Fails the restore operation on a file if the fixed extent size or space reservation of the file cannot be preserved. ignore Ignores any errors in preserving extent attributes. warn Issues a warning if the space reservation or the fixed size of the file cannot be preserved.
`-fDevice`	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 allows to pipe the input of therestore 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 8 mm, 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, therestore command automatically goes from one device in the range to the next. After all the specified devices are exhausted , therestore command halts and requests that new volumes be mounted on the range of devices.
`-h`	Restores only the actual directory, not the files that are contained in it. This flag can be used when the archive is in file system format. This flag is ignored when used with the `-r` or `-R` flags.
`-I` `Label`	The restore command applies this integrity label for files without security labels in the archive. The label that is supplied must exist on the system. This option is valid only for restoring files by name on Trusted AIX®.
`-i`	Restores the selected files interactively from a file system archive. The following are the subcommand for the `-i` flag: 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 that are 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 that are contained in it are removed from the extraction list (unless the `-h` flag is used). ls [`Directory`] Displays the directories and files that are 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. More 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 subcommand.
`-l`	Specified with the `-t` and `-T` option. When specified, displays a detailed list of files, which includes the timestamp, file permissions, file size, owner, and group. The `-l` option overrides the `-a` option.
`-LLabel`	The restore command applies this sensitivity label for files without security labels in the archive. The label that is supplied must exist on the system. This option is valid only for restoring files by name on Trusted AIX.
`-M`	Sets the access and modification times of restored files to the time of restoration. If a restored file is an archive that is 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 displayed on the backup medium. The`-M` flag is used when the data is in the AIX 4.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 function is useful if a few files are being restored and you want these files that are 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.
`-n`	By default the restore command restores any ACLs, PCLs, or named extended attributes in the archive. The `-n` flag causes the restore command to ignore any ACLs, PCLs, or named extended attributes in the archive and not restore them.When the archived files contain Encrypted file system (EFS) information, the EFS extended attributes are restored even if the `-n` flag is specified. On Trusted AIX systems, the `-n` option causes the restore command to ignore Trusted AIX security attributes. For more information about EFS restoration, see Backup and restore in Security.
`-O`	Causes the restore command to ignore Trusted AIX security attributes.
`-Pstring`	Restore only the file attributes. Does not restore the file contents. If the file specified does not exist in the target directory path, the files are not created. This flag restores file attributes selectively depending on the flags that are specified in the string parameter. String parameter can be a combination of the following characters: A restore all attributes. a restore only the permissions of the files. o restore only the ownership of the files. t restore only the timestamp of the files. c restore only the ACL attributes of the files. Note: Among the existing options for the restore command, options `v`, `h`, `b`, `s`, `f`, `B`, `d`, and `q` are valid with the `P` option. The `P` option can be used with both file name and file system archives. If the `File` argument is a symbolic link, then the metadata of the target file is modified and not that of the symbolic link. Warning: Usage of the `-P` flag overwrites the attributes of files that are owned by another user when run by the superuser.
`-Q`	Specifies that the command must exit when an error is encountered, for backups done by name. This process does not attempt to recover and continue processing the archive, when an error occurs.
`-q`	Specifies that the first volume is ready to use and that the restore command cannot 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 must be removed when the last incremental backup is restored. The `File` parameter is ignored when use 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 you use the `-R` flag. When the restore command is restarted, it functions similar to the `-r` flag.
`-sSeekBackup`	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 `-s1` 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 that is specified with `-s` is relative to the position of the tapes read/write head and not to an archives 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 `-s1`, and `-s2`.
`-t`	Displays information about the backup archive. If the archive is in file system format, a list of files that are 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 that are 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 that are contained in that directory are listed. If the archive is in file name format, information that is contained in the volume header is written to standard error. This flag can be used to determine whether the archive is in the file name or the file system format.
`-T`	Displays information about the backup archive. If the archive is in file name format, the information that is contained in the volume header is written to standard error, and a list of files that are found on the archive is 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 information when the file name is restored . 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 that are 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 that are contained in the directory are restored. The file names that are 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 by 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 you use this flag to restore file system backups, you are prompted to enter the beginning volume number. The restore command allows for shell-style pattern matching metacharacters to be used when files for archive extraction is specified . The rules for matching metacharacters are the same as used in shell pathname "globbing," namely: * (asterisk) Matches zero or more characters, but not a '.' (period) or '/' (slash). ? (question mark) Matches any single character, but not a '.' (period) or '/' (slash). [ ] (brackets) Matches any one of the characters that are enclosed within the brackets. If a pair of characters that are separated by a dash is contained within the brackets, the pattern matches any character that lexically falls between the two characters in the current local. Additionally, a '.' (period) or a '/' (slash) within the brackets does not match a '.' (period) or a '/' (slash) in a file name. \ (backslash) Matches the immediately following character, preventing its possible interpretation as a metacharacter.
`-XVolumeNumber`	Begins restoring from the specified volume of a multiple-volume, file name backup. When the restore command is started, the command behaves similar to the `-x` flag. The `-X` flag applies to file name archives only.
`-y`	Continues restoring when tape errors are encountered. Normally, the restore command request input to continue. In either case, all data in the read buffer is replaced with zeros. 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:

Item	Descriptor
0	Successful completion.
>0	An error occurred.

Security

On Trusted AIX systems, only authorized users can run the restore command.

Item	Descriptor
aix.fs.manage.restore	Required to run this command.

Attention RBAC users and Trusted AIX users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in Security. For a list of privileges and the authorizations associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

To list the names of files in either a file name or file system archive on the diskette device /dev/rfd0, type:
```
restore -Tq
```
The archive is read from the /dev/rfd0 default restore device. The names of all the files and directories that are 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, type:
```
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 the -T flag is used. The -v flag displays 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, type:
```
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 you use 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, type:
```
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 you use the -T flag. If the directories do not exist, they are created.
To restore an entire file system archive, type:
```
restore -rvqf /dev/rmt0
```
This command restores the entire file system that is 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 must be restored in increasing backup-level order beginning with level 0 (for example, 0, 1, and 2).
To restore the fifth and ninth backups from a single-volume, multiple-backup tape, type:
```
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 that is specified by /dev/rmt0.1. The .1 designator specifies the tape device that is not retensioned when it is opened and 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 is restored, the tape read/write head is in a position to read the archive. 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 archives 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 type:
```
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 is not 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 typing:
```
dd if=/dev/rmt0 bs=64b | restore -xf- -b64
```
The dd command reads the archive from the tape by using a block size of 64 512-byte blocks and writes the archive to standard output. The restore command reads the standard input by using a block size of 64 512-byte blocks. The value of the block size that is 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 cannot 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 must 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 typing:
```
chdev -l DeviceName -a BlockSize=32k
```
To restore non-sparse database files, type:
```
restore  -xef  /dev/rmt0
```
To restore files that were sparse before archive as sparse, type:
```
restore  -xf  /dev/rmt0
```
To restore only the permissions of the files from the archive, type:
```
restore -Pa -vf /dev/rmt0
```
To restore only the ACL attributes of the files from the archive, type:
```
 restore -Pc -vf /dev/rmt0
```
To view the table of contents along with the file permissions, type:
```
restore -Ta -vf /dev/rmt0 
```
To view the table of contents of file name archive along with the timestamps and file permissions, type:
```
restore -Tl -vf /dev/rmt0
```
To view the table of contents of file system archive along with the timestamps and file permissions, type:
```
restore -tl -vf /dev/rmt0
```

Files

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