fbackup(1M)fbackup(1M)NAMEfbackup - selectively back up files
SYNOPSIS
device device] ... path] path] graph] path] path] path] config]
device device] ... restart] path] path] path] config]
Remarks
Note: The and commands are deprecated for creating new archives. See
for more information.
DESCRIPTION
combines features of and to provide a flexible, high-speed file system
backup mechanism (see dump(1M) and ftio(1)). selectively transfers
files to an output device. For each file transferred, the file's con‐
tents and all the relevant information necessary to restore it to an
equivalent state are copied to the output device. The output device
can be a raw magnetic tape drive (for example, a DLT tape drive), the
standard output, a rewritable magneto-optical disk, or a file.
The selection of files to back up is done by explicitly specifying
trees of files to be included or excluded from an session. The user
can construct an arbitrary graph of files by using the or options on
the command line, or by using the option with a graph file. For back‐
ups being done on a regular basis, the option provides an easier inter‐
face for controlling the backup graph. selects files in this graph,
and attempts to transfer them to the output device. The selectivity
depends on the mode (full or incremental) in which is being used.
When doing full backups, all files in the graph are selected. When
doing incremental backups, only files in the graph that have been modi‐
fied since a previous backup of that graph are selected. If an incre‐
mental backup is being done at level 4 and the option is used, the
database file is searched for the most recent previous backup at levels
0-3. If a file's modification time is before the time when the last
appropriate session began and the i-node change time is before the time
that same session ended, the file is not backed up. All directories
lying on the path to a file that qualifies for the incremental backup
will also be on the backup media, even if the directories do not qual‐
ify on their own status.
If is used for incremental backups, a database of past backups must be
kept. maintains this data in the text file by default. Note that the
directory must be created prior to the first time is used for incremen‐
tal backups. The option can be used to specify an alternate database
file. The user can specify to update this file when an session com‐
pletes successfully. Entries for each session are recorded on separate
pairs of lines. The following four items appear on the first line of
each pair: the graph file name, backup level, starting time, and ending
time (both in format). The second line of each pair contains the same
two times, but in format. These lines contain the local equivalent of
the start time, the local equivalent of and the ending time. These
second lines serve only to make the dates file more readable; does not
use them. All fields are separated by white space. Graph file names
are compared character-by-character when checking the previous-backup
database file to ascertain when a previous session was run for that
graph. Caution must be exercised to ensure that, for example, and are
not used to specify the same graph file because treats them as two dif‐
ferent graph files.
The general structure of an volume is the same, no matter what type of
device is used. There are some small specific differences due to dif‐
fering capabilities of devices. The general structure is as follows:
· reserved space for ASCII tape label (1024 bytes)
· volume header (2048 bytes)
· session index (size in field of volume header)
· data
Each file entry in the index contains the file size, the volume number
and the pathname of the file. At the beginning of every volume,
assumes that all files not already backed up will fit on that volume,
an erroneous assumption for all but the last volume. Indices are accu‐
rate only for the previous volumes in the same set. Hence, the index
on the last volume may indicate that a file resides on that volume, but
it may not have actually been backed up (for example, if it was removed
after the index was created, but before attempted to back it up). The
only index guaranteed to be correct in all cases is the on-line index
option), which is produced after the last volume has been written.
Specific differences in the structure of volumes are listed below:
· When using magnetic tape devices, the main blocks of informa‐
tion (tape label, volume header, index, data) are separated
by EOF marks. also checkpoints the media periodically to
enhance error recovery. If a write error is detected, the
user normally has two options: (1) a new volume can be
mounted and that volume rewritten from the beginning; or, (2)
if the volume is not too severely damaged, the good data
before the error can be saved, and the write error is treated
as a normal end-of-media condition. The blocks of data with
their checkpoint records are also separated by EOF marks. In
addition, for DDS tape drives, if are supported, these will
be used to enhance selective recovery speed by placing them
between blocks of files. Similarly on DLT tape drives,
faster selective recovery is achieved using the EOF marks
used for checkpointing in conjunction with the file sizes
given in the index.
· For a magneto-optical device, a disk, a file, or standard
output, there are no special marks separating the information
pieces; the backup is always a single file (volume).
provides the ability to use UCB-mode tape drives. This makes it possi‐
ble to overlap the tape rewind times if two or more tape drives are
connected to the system.
Set-up
There are several things the user will want to consider when setting up
for regular use. These include type of device and media, full versus
incremental frequency, amount of logging information to keep on-line,
structure of the graph file, and on-line versus off-line backup.
The type of device used for backups can affect such things as media
expenses, ability to do unattended backups, and speed of the backup.
Using 36-track tapes will probably result in the highest performance,
but require user intervention for changing tapes. Both DLT and DDS
autochangers and libraries can provide unattended backups. A magneto-
optical autochanger can also provide an unattended backup for a large
system and long life media, however the media cost is high. Lower cost
and good performance can be achieved with a single DLT tape drive, but
multi-volume backups must be attended.
It is also important to consider how often full backups should be made,
and how many incremental backups to make between full backups. Time
periods can be used, such as a full backup every Friday and incremen‐
tals on all other days. Media capacities can be used if incremental
backups need to run unattended. The availability of personnel to
change media can also be an important factor as well as the length of
time needed for the backup. Other factors may affect the need for full
and incremental backup combinations such as contractual or legal
requirements.
If backup information (output from the or options) is kept on-line, the
required storage space must also be considered. Index file sizes are
hard to predict in advance because they depend on system configuration.
Each volume header file takes less than 2048 bytes. Of course the more
information that is kept on-line, the faster locating a backup media
for a recovery will be.
There are several ways to structure the graph file or files used in a
system backup. The first decision involves whether to use one or more
than one graph file for the backup. Using one file is simpler, but
less flexible. Using two or more graph files simplifies splitting
backups into logical sets. For example, one graph file can be used for
system disks where changes tend to be less frequent, and another graph
file for the users area. Thus two different policies can be imple‐
mented for full and incremental backups.
was designed to allow backups while the system is in use by providing
the capability to retry an active file. When absolute consistency on a
full backup is important, the system should probably be in single-user
mode. However, incremental backups can be made while the system is in
normal use, thus improving system up-time.
Options
config is the name of the configuration file, and can contain
values for the following parameters:
· Number of 1024-byte blocks per record (supported
range: 1 - 9765).
· Number of records of shared memory to allocate.
· Number of records between checkpoints (supported
range: 1 - 9999). Since the EOF marks between check‐
points are also used for fast searching on DLT tape
drives, changing the checkpoint frequency may also
affect selective recovery speed (see section).
· Number of file-reader processes.
· Maximum number of times is to retry an active file.
· Maximum number of bytes of media to use while retry‐
ing the backup of an active file.
· Maximum number of times a magnetic tape volume can be
used (supported range: 1 - 9999).
· Name of a file to be executed when a volume change
occurs. This file must exist and be executable.
· Name of a file to be executed when a fatal error
occurs. This file must exist and be executable.
· The number of files between the on DDS tapes (sup‐
ported range: 1 - 9999). The cost of these marks are
negligible in terms of space on the DDS tape. Not
all DDS tape devices support
Each entry in the configuration file consists of one line
of text in the following format: identifier, white space,
argument. If a parameter exceeds the supported range,
prints a warning message and the maximum supported value
is used. If such a warning message is seen, any backup
already written with this configuration should be tested
for readability.
In the following sample configuration file, the number of
blocks per record is set to 16; the number of shared mem‐
ory records is set to 16; the checkpoint frequency is set
to 256; the number of file reader processes is set to 2;
the maximum number of retries of an active file is set to
5; the maximum retry space for active files is set to
5,000,000 bytes; the maximum number of times a magnetic
tape volume can be used is set to 100; the file to be exe‐
cuted at volume change time is the file to be executed
when a fatal error occurs is and the number of files
between on DDS tapes is set to 200.
blocksperrecord 16
records 16
checkpointfreq 256
readerprocesses 2 (maximum of 6)
maxretries 5
retrylimit 5000000
maxvoluses 100
chgvol /var/adm/fbackupfiles/chgvol
error /var/adm/fbackupfiles/error
filesperfsm 200
Each value listed is also the default value, except and
which default to null values.
This specifies a path to a database for use with incremental backups.
It overrides the default database file
path specifies a tree to be excluded from the backup graph.
This tree must be a subtree of part of the backup graph.
Otherwise, specifying it will not exclude any files from
the graph. There is no limit on how many times the option
can be specified.
device specifies the name of an output file. If the name of the
file is writes to the standard output. There is no
default output file; at least one must be specified. If
more than one output file is specified, uses each one suc‐
cessively and then repeats in a cyclical pattern. Pat‐
terns can be used in the device name in a manner resem‐
bling file name expansion as done by the shell (see sh(1)
and other shell manual entries). The patterns must be
protected from expansion by the shell by quoting them.
The expansion of the pattern results in all matching names
being in the list of devices used.
There is slightly different behavior if remote devices are
used. A device on the remote machine can be specified in
the form creates a server process from on the remote
machine to access the tape device. If does not exist on
the remote system, creates a server process from on the
remote machine to access the tape device. Only magnetic
tapes can be remote devices. When remote DDS tape devices
are used, the capability is not used.
graph defines the graph file. The graph file is a text file
containing the list of file names of trees to be included
or excluded from the backup graph. These trees are inter‐
preted in the same manner as when they are specified with
the and options. Graph file entries consist of a line
beginning with either or followed by white space, and then
the path name of a tree. Lines not beginning with or are
treated as an error. There is no default graph file. For
example, to back up all of except for the subtree a file
could be created with the following two records:
path specifies a tree to be included in the backup graph.
There is no limit on how many times the option can be
specified.
Cross NFS mount points. By default, does not cross NFS mount
points, regardless of paths specified by the or options.
Includes LOFS files specified by the backup graph.
By default, does not cross LOFS mount points. If is spec‐
ified, and the backup graph includes files which are also
in an LOFS directory that is in the backup graph, then
those files will be backed up twice.
Back up the object that a symbolic link refers to.
The default behavior is to back up the symbolic link.
Update the database of past backups
so that it contains the backup level, the time of the
beginning and end of the session, and the graph file used
for this session. For this update to take place, the fol‐
lowing conditions must exist: Neither the nor the option
can be used; the option must be specified exactly once
(see below); the must complete successfully.
Run in verbose mode.
Generates status messages that are otherwise not seen.
Automatically answer
to any inquiries.
Do not back up optional entries of access control lists
(ACLs) for files. Normally, all mode information is
backed up including the optional ACL entries. With the
option, the summary mode information (as returned by is
backed up. Use this option when backing up files from a
system that contains ACLs to be recovered on a system that
does not understand ACLs (see acl(5)).
Do not back up extent attributes.
Normally, all extent attributes that have been set are
included with the file. This option only applies to file
systems which support extent attributes.
path specifies the name of the on-line index file to be gener‐
ated. It consists of one line for each file backed up
during the session. Each line contains the file size, the
volume number on which that file resides, and the file
name. If the option is omitted, no index file is gener‐
ated.
The volume header information is written to
path at the end of a successful session. The following
fields from the header are written in the format with one
pair per line.
On a valid media it contains the value (HP-UX
11i Version 3 and beyond). Previ‐
ous values of this field were
(between HP-UX 10.20 and 11i Ver‐
sion 2 inclusive) and (before HP-UX
10.20).
This field contains the result of
This field contains the result of
This field contains the result of
This field contains the result of
This field contains the result of
(see cuserid(3S)).
This field contains the maximum length in bytes of a data
record.
This field contains the clock time when
was started.
This field contains the number of times
the media has been used for backup.
Since the information is actually
on the media, this field will
always contain the value 0.
This field contains a character followed by 3 digits, and
identifies the number of volumes in
the backup.
This field contains the number of data records between
checkpoints.
This field contains the size of the index.
This field is composed of two items: the process
ID (pid) and the start time of that
process.
This field contains the language used to make the backup.
Restart an session from where it was previously interrupted. The
restart file contains all the information necessary to
restart the interrupted session. None of the options can
be used together with the restart option.
This single-digit number is the backup level.
Level indicates a full backup. Higher levels are gener‐
ally used to perform incremental backups. When doing an
incremental backup of a particular graph at a particular
level, the database of past backups is searched to find
the date of the most recent backup of the same graph that
was done at a lower level. If no such entry is found, the
beginning of time is assumed. All files in the graph that
have been modified since this date are backed up.
Access Control Lists (ACLs)
If a file has optional ACL entries, the option is required to enable
its recovery on a system where the ACL capability is not present.
EXTERNAL INFLUENCES
Environment Variables
determines the order in which files are stored on the backup device and
the order of output by the option.
determines the format and contents of date and time strings.
determines the language in which messages are displayed.
If and are not all specified in the environment, or if either is set to
the empty string, the value of is used as a default for each unspeci‐
fied or empty variable. If is not specified or is set to the empty
string, a default of "C" (see lang(5)) is used instead of If any inter‐
nationalization variable contains an invalid setting, 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.
RETURN VALUE
returns one of the following values:
upon normal completion.
if it is interrupted but allowed
to save its state for possible restart.
if any error conditions
prevent the session from completing.
if any warning conditions are encountered.
If warnings occur, the operator should check the fbackup logs to verify
the sanity of the backup.
EXAMPLES
In the following two examples, assume the graph of interest specifies
all of except (as described for the option above).
The first example is a simple case where a full backup is done but the
database file is not updated. This can be invoked as follows:
The second example is more complicated, and assumes the user wants to
maintain a database of past sessions so that incremental backups are
possible.
If sufficient on-line storage is available, it may be desirable to keep
several of the most recent index files on disk. This eliminates the
need to recover the index from the backup media to determine if the
files to be recovered are on that set. One method of maintaining on-
line index files is outlined below. The system administrator must do
the following once before is run for the first time (creating interme‐
diate level directories where necessary):
· Create a suitable configuration file called in the directory
· Create a graph file called in the directory
· Create a directory called in the directory
A shell script that performs the following tasks could be run for each
session:
· Build an index file path name based on both the graph file
used (passed as a parameter to the script) and the start time
of the session (obtained from the system). For example:
(for Nov 28, 1987 at 3:17 PM)
· Invoke with this path name as its index file name. For exam‐
ple:
When the session completes successfully, the index is automatically
placed in the proper location.
WARNINGS
The and commands are deprecated for creating new archives. In a future
HP-UX release, creation of new archives with these commands will not be
supported. Support will be continued for archive retrieval. Use the
standard command (portable archive interchange) to create archives.
See pax(1).
consists of multiple executable objects, all of which are expected to
reside in directory
does not require special privileges. However, if the user does not
have access to a given file, the file is not backed up.
For security reasons, configuration files and the and executable files
should only be writable by their owners.
In HP-UX 11i Version 3, the maximum value for fields returned via was
increased (from 8 to 256). To accommodate the larger size, a format
change was necessary. A new magic number, was created to distinguish
this new format.
Likewise with HP-UX 10.20, HP-UX added support for large files (greater
than 2GB) and increased UID/GIDs (greater than 60,000). The magic num‐
ber associated with this release through HP-UX 11i Version 2 (inclu‐
sive) is
Archives and files with formats and attributes that are unsupported on
previous HP-UX releases could cause severe problems or unpredictable
behavior if attempts were made to restore onto these systems. For this
reason, creates tapes with a magic number that is only recognized on
releases which support the features and format being archived. This
prevents tape archives from being restored on earlier HP-UX systems
than are supported. still reads all tape formats so that tape archives
created on earlier HP-UX systems can be restored.
EOF marks are used for checkpointing on all magnetic tape devices. On
DLT tape devices, these EOF marks are also used for fast searching on a
selective recovery; "fast searching" in this case means spacing to the
nearest checkpoint before the desired file, and then reading until the
file is found. With this dual purpose for checkpoints, caution should
be used when changing the checkpoint frequency parameter.
The use of for backing up NFS mounted file systems is not guaranteed to
work as expected if the backup is done as a privileged user. This is
due to the manner in which NFS handles privileged-user access by map‐
ping user and uid to user usually uid thus disallowing root privileges
on the remote system to a root user on the local system.
The utility set comprised of and 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 sub‐
stantially 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.
Due to present file-system limitations, files whose inode data, but not
their contents, are modified while a backup is in progress might be
omitted from the next incremental backup of the same graph. Also, does
not reset the inode change times of files to their original values.
should not be used with no-rewind devices, for example, or on systems
where legacy Device Special Files (DSF) is disabled.
allocates resources that are not returned to the system if it is killed
in an ungraceful manner. If it is necessary to kill send it a not a
If sparse files are backed up without using data compression, a very
large amount of media can be consumed.
creates volumes with a format that makes duplication of volumes by
impossible (see dd(1)). Copying an volume created on one media type to
another media type does not produce a valid volume on the new media
because the formats of volumes on raw magnetic tape, on a regular file,
and on rewritable optical disks are not identical.
When configuring the parameter (see option), the record size is limited
by the maximum allowed for the tape drive. Common record sizes include
128 blocks for DLT and DDS tape drives, and 60 blocks for the HP7980.
Note also that the blocksize used in earlier releases (7.0 and before)
was 512 bytes, whereas it is now 1024 bytes. This means that the same
value specified in blocksperrecord in an earlier release creates blocks
twice their earlier size in the current release; for example, a
blocksperrecord parameter of 32 would create 16-Kbyte blocks at HP-UX
7.0, but now creates 32-Kbyte blocks. If blocksperrecord exceeds the
byte count allowed by the tape drive, the tape drive rejects the write,
causing an error to be communicated to which interprets as a bad tape.
The resulting write error message resembles the following:
DEPENDENCIES
NFS
Access control lists of networked files are summarized (as returned in
by but not copied to the new file (see stat(2)).
does not support QIC-120 and QIC-150 formats on QIC devices. If is
attempted for these formats, fails and the following message is dis‐
played :
AUTHOR
was developed by HP.
FILES
database of past backups
SEE ALSOcpio(1), ftio(1), pax(1), dump(1M), frecover(1M), restore(1M), rmt(1M),
stat(2), acl(5), mt(7).
TO BE OBSOLETED fbackup(1M)
