frecover - selectively recover files
/usr/sbin/frecover -r [-hmosvyAFNOX] [-c config] [-f device] [-S skip]
/usr/sbin/frecover -R path [-f device]
/usr/sbin/frecover -x [-hmosvyAFNOX] [-c config] [-e path] [-f device]
[-g graph] [-i path] [-S skip] [-E extarg]
/usr/sbin/frecover -I path [-vy] [-f device] [-c config]
/usr/sbin/frecover -V path [-vy] [-f device] [-c config]
frecover reads media written by the fbackup command. Its actions are
controlled by the selected function -r, -R, -x, -V, or -I.
The function performed by frecover is specified by one of the
-r The backup media is read and the contents are loaded into
the directories from which they were backed up. This
option should only be used to recover a complete backup
onto a clear directory or to recover an incremental backup
after a full level-zero recovery (see fbackup(1M)). This
is the default behavior.
-x The files identified by the -i, -e, and -g options (see
below) are extracted or not extracted from the backup
media. If a file to be extracted matches a directory
whose contents have been written to the backup media, and
the -h option is not specified, the directory is
recursively extracted. The owner, modification time, and
access control list (including optional entries, unless
the -A option is specified) are recovered. If no file
argument is given (including an empty graph file), all
files on the backup media are extracted, unless the -h
option is specified.
-I path The index on the current volume is extracted from the
backup media and is written to path.
-V path The volume header on the current volume is extracted from
the backup media and is written to path. The following
fields from the header are extracted in the format
label:value with one pair per line.
Hewlett-Packard Company - 1 - HP-UX Release 11i: November 2000
Magic Field On valid fbackup media, it
contains the value
FBACKUP_LABEL. On pre-10.20
fbackup media, it contains
Machine Identification This field contains the result
of uname -m.
System Identification This field contains the result
of uname -s.
Release Identification This field contains the result
of uname -r.
Node Identification This field contains the result
of uname -n.
User Identification This field contains the result
Record Size This field contains the
maximum length in bytes of a
Time This field contains the time
fbackup was started.
Media Use This field contains the number
of times the media has been
used for backup.
Volume Number This field contains a #
character followed by 3
digits, and identifies the
current volume in the backup.
Checkpoint Frequency This field contains the number
of data records between
Fast Search Mark Frequency This field contains the number
of files between fast search
marks for backups made with
DDS tape drives.
Index Size This field contains the size
of the index.
Backup Identification Tag This field is composed of 2
items: the process ID (pid),
and the start time of that
Language This field contains the
language used to make the
-R path An interrupted full recovery can be continued using this
option. frecover uses the information in file path to
continue the recovery from where it was interrupted. The
only command line option used by frecover with this option
is -f. The values in path override all other options to
frecover. Note also that only full recoveries are
restarted with this option, because no history of include
Hewlett-Packard Company - 2 - HP-UX Release 11i: November 2000
or exclude lists is stored in the restart file. If a
partial recovery (i.e., using the -x option) is
interrupted then restarted with this option, frecover
continues recovering where the partial recovery left off,
but restores all files on the backup media beyond this
The following options can be used in addition to the option above that
selects the desired function:
-c config config specifies the name of a configuration file to be
used to alter the behavior of frecover. The configuration
file allows the user to specify the action to be taken on
all errors, the maximum number of attempts at
resynchronizing on media errors (-S option), and the
action to be taken on media errors. Each entry of a
configuration file consists of an action identifier
followed by a separator followed by the specified action.
Valid action identifiers are error, chgvol, and sync.
Separators can be either tabs or spaces. In the following
sample configuration file, each time an error is
encountered, the script
/var/adm/fbackupfiles/frecovererror is executed. The
script /var/adm/fbackupfiles/frecoverchgvol is executed
each time the backup media is to be changed. The maximum
number of resynchronization attempts is five.
-e path path is interpreted as a graph to be excluded from the
recovery. There is no limit on how many times the -e
option can be specified.
-f device device identifies the backup device to be used instead of
the default /dev/rmt/0m. If device is -, frecover reads
from standard input. Thus fbackup and frecover can be
used in a pipeline to backup and recover a file system as
fbackup -i /usr -f - | (cd /mnt; frecover -Xrf -)
If more than one output file is specified, frecover uses
each one successively and then repeats in a cyclical
pattern. Patterns can be used in the device name in a way
similar to file name expansion as done by sh(1). The
expansion of the pattern results in all matching names
being in the list of devices used. A device on the remote
machine can be specified in the form machine:device.
frecover creates a server process, /usr/sbin/rmt, on the
Hewlett-Packard Company - 3 - HP-UX Release 11i: November 2000
remote machine to access the tape device. If
/usr/sbin/rmt does not exist on the remote system,
frecover creates a server process from /etc/rmt on the
remote machine to access the tape device. The pattern
matching capability does not apply to remote devices.
Only raw magnetic tapes can be remote devices. The fast
search marks capability is not used when accessing remote
-g graph graph defines a graph file. Graph files are text files
and contain the list of file names (graphs) to be
recovered or skipped. Files are recovered using the -i
option; so, for example, if the user wants to recover all
of /usr, the graph file contains one entry:
It is also possible to skip files by using the -e option.
For example, if a user wants to recover all of /usr except
for the subgraph /usr/lib, the graph file contains two
If the graph file is missing, frecover exits with an error
message. An empty graph file results in recovering all
files on the media.
-h Extract the actual directory, rather than the files that
it references. This prevents hierarchical restoration of
complete subtrees from the backup media.
-i path path is interpreted as a graph to be included in the
recovery. There is no limit on how many times the -i
option can be specified.
-m Print a message each time a file marker is encountered.
Using this option, frecover prints a message each time
either a DDS fast search mark, a filemark (EOF), or a
checkpoint record is read. Although useful primarily for
troubleshooting, these messages can also be used to
reassure the user that the backup is progressing during
long, and otherwise silent, periods during the recovery.
-o Recover the file from the backup media irrespective of
age. Normally frecover does not overwrite an existing
file with an older version of the file.
-s Attempt to optimize disk usage by not writing null blocks
of data to sparse files.
Hewlett-Packard Company - 4 - HP-UX Release 11i: November 2000
-v Normally frecover works silently. Verbose option.
Displays the file type and name of each file processed.
-y Automatically answer yes to any inquiries.
-A Do not recover any optional entries in access control
lists (ACLs). Normally, all access control information,
including optional ACL entries, is recovered. This option
drops any optional entries and sets the permissions of the
recovered file to the permissions of the backed up file.
Use this option when recovering files backed up from a
system with ACLs on a system where ACLs are not present
-F Recover files without recovering leading directories. For
example, this option would be used if a user wants to
recover /usr/bin/vi, /usr/bin/sh, and /etc/passwd to a
local directory without creating each of the graph
-E extarg Specifies the handling of any extent attributes backed up
by fbackup. The -E option takes the following keywords as
warn Issue a warning message if extent attributes
cannot be restored, but restore the file anyway.
ignore Do not restore extent attributes.
force Issue an error message and do not restore the
file if extent attributes cannot be restored.
Extent attributes cannot be restored if the
files are being restored to a file system which
does not support extent attributes or if the
file system's block size is incompatible with
the extent attributes. If -E is not specified,
extarg defaults to warn.
-N (no recovery) Prevent frecover from actually recovering
any files onto disk, but read the backup as if it was, in
fact, recovering the data from the backup, producing the
same output that it would on a normal recovery. This
option is useful for verifying backup media contents in
terms of validity (block checksum errors are reported),
and contents (a listing of files can be produced by using
the -N and -v options together). Note that the listing of
files produced with the -N and -v options requires the
reading of the entire backup, but is therefore a more
accurate reflection of the backup's contents than the
index stored at the beginning of the backup (which was
Hewlett-Packard Company - 5 - HP-UX Release 11i: November 2000
created at the start of the backup session, and is not
changed during the course of the backup).
-O Use the effective uid and gid for the owner and group of
the recovered file instead of the values on the backup
-S skip frecover does not ask whether it should abort the recovery
if it gets a media error. It tries to skip the bad block
or blocks and continue. Residual or lost data is written
to the file named by skip. The user can then edit this
file and recover otherwise irretrievable data.
-X Recover files relative to the current working directory.
Normally frecover recovers files to their absolute path
LC_COLLATE determines the order in which frecover expects files to be
stored on the backup device and the order in which file names are
output by the -I option.
LC_MESSAGES determines the language in which messages are displayed.
If LC_COLLATE and LC_MESSAGES are not specified in the environment or
are set to the empty string, the value of LANG is used as a default
for each unspecified or empty variable. If LANG is not specified or
is set to the empty string, a default of "C" (see lang(5)) is used
instead of LANG. If any internationalization variable contains an
invalid setting, frecover behaves as if all internationalization
variables are set to "C". See environ(5).
International Code Set Support
Single- and multi-byte character code sets are supported.
For incremental backups created prior to installing HP-UX Release 8.0,
or for recoveries that do not begin with the first volume (such as
when reading tape 3 first), it is possible for the preceding
directories to a recoverable file to not be on the media. This can
happen, for example, if the directories did not change since the last
full backup. If frecover encounters a file on the backup that should
be recovered, but it has not recovered the file's parent directories
from the backup, it prints a message stating that the recovery will
continue with that file, and attempts to create the file's parent
directories as needed.
Use of frecover does not require special privileges. However, if a
user does not have access permission to a given file, the file is not
Hewlett-Packard Company - 6 - HP-UX Release 11i: November 2000
The fbackup index format now includes the file size in the first
field; the previous format simply had the '#' character in that field.
The implementation provides both forward and backward compatibility
between the old and new index formats. However, the file sizes are
used in conjunction with the checkpoints to increase selective
recovery speed on DLT devices, so recovery of an fbackup volume that
does not have the new index format will not see that performance gain.
When using a DDS tape written with the current release of fbackup to
do a partial recovery, frecover attempts to use the DDS fast-search
capability to find files on the tape more quickly. In order to do
this, however, frecover needs to create an in-memory copy of the
index, and mark the files on that index which it needs to recover
before actually reading through the tape to find the files. This is
done when the first index is read from the tape, and accounts for a
period of time just after recovery is begun where the tape is inactive
while this in-memory index is constructed. The larger the index is,
the longer this period lasts.
The utility set comprised of fbackup and frecover was originally
designed for use on systems equipped with not more than one gigabyte
of total file system storage. Although the utilities have no
programming limitations that restrict users to this size, complete
backups and recoveries of substantially larger systems can cause a
large amount of system activity due to the amount of virtual memory
(swap space) used to store the indices. Users who want to use these
utilities, but are noticing poor system-wide performance due to the
size of the backup, are encouraged to back up their systems in
multiple smaller sessions, rather than attempting to back up the
entire system at one time. However, if the entire backup must be done
with a single session, the user may encounter an error in frecover if
there is not enough virtual memory available. If this happens, the
user might consider adjusting the maxdsiz parameter or the swap space;
both of these require a reboot.
Note that when recovering files with access control lists, the ACL
entries are stored on the backup as user login names. If a login name
cannot be found in the password file, the file is recovered without
its ACL, and an error is printed. In order to fully recover files
backed up with ACLs, the password file (/etc/passwd) must be recovered
before attempting to recover any desired ACLs.
Network special files are obsolete. Therefore, frecover cannot
restore these files. A warning message is issued if an attempt is
made to recover a network special file, and the file is skipped.
Care should be taken to match the names specified by the include and
exclude options with the names in the index on the tape. Since the
files are stored on the backup in lexographic order as defined by the
LANG or LC_COLLATE environment variable, frecover uses the exact path
names to determine when a partial recovery is complete, and when an
Hewlett-Packard Company - 7 - HP-UX Release 11i: November 2000
earlier tape needs to be loaded. If a user's specification of a file
to be recovered is misspelled, this may cause confusing messages, such
as frecover asking for the previous volume, when volume one is
frecover does not support QIC-120 and QIC-150 formats on QIC devices.
If frecover is attempted for these formats, frecover fails and the
following message is displayed :
mt lu X:Read must be a multiple of 512 bytes in QIC 120 and QIC
frecover was developed by HP.
/dev/rmt/0m Default backup device.
cpio(1), dump(1M), fbackup(1M), restore(1M), rmt(1M), acl(5).
Hewlett-Packard Company - 8 - HP-UX Release 11i: November 2000