BRU(1) BRU(1)
NAME
bru - backup and restore utility
SYNOPSIS
bru modes [ control options ] [ selection options ] files
DESCRIPTION
Bru is a Unix filesystem backup utility with significant enhancements
over other more common utilities such as tar, cpio, volcopy, and dd.
Some of bru's capabilities include:
o Full or incremental backup with quick and easy restoration of
files.
o Multiple physical volumes per archive.
o Data integrity assurance via checksum computation on every
archive block.
o Ability to properly save and restore directories, symbolic links,
block special files, and character special files.
o Comparison of archives with current directory hierarchy.
o Ability to recover files from corrupted archives or damaged media
with minimal data loss.
o No inherent maximum archive buffer size.
o Improved performance through random access archive I/O when
available.
o Automatic byte or half word swapping as necessary when reading
archives produced on other machines.
o Recognition of filename generation patterns in the same form as
the shell for files read from an archive.
When files are specified on the command line then the actions to be
performed are limited to those files. If a named file is a directory
then it and all its descendents are used. If no files are specified then
the default for writing archives is all files in and below the current
directory. The default for reading archives is selection of all files in
the archive.
If "-" is given instead of files then the standard input is read to
obtain the file list. This is useful in conjunction with the find
command to provide finer control over files selected for backup.
Obviously this mode is only valid when bru is not also reading its
archive from the standard input.
If you are doing backups non-interactively (for example, via cron, be
sure to read the description of the -B option below.
DEFAULTS
Various default parameters, such as archive device name and size, archive
buffer size, controlling terminal name, etc. are system dependent. These
defaults, along with version, variant, and other miscellaneous internal
information may be discovered via the -h mode.
bru assumes the default tape device to be /dev/tape if no tape device is
Page 1
BRU(1) BRU(1)
specified using the -f option. For this to work correctly, /dev/tape
should be linked to the actual tape device, for ex. /dev/mt/tps0d6. Also
there should be an appropriate entry for /dev/mt/tps0d6 in the
/etc/brutab file.
MODES
One or more of the following modes must be specified. The order of
execution, from highest priority to lowest, is ecitxdgh.
-c Create a new archive. Forces a new archive to be created
regardless of whether one currently exists. Writing starts at
the first block.
-d Differences between archived files and current files are
detected and reported. May be specified more than once, as -dd
-ddd or -dddd to control level of difference checking.
When specified as -d bru reports when it discovers that a
regular file's size (st_size) or contents (when compared as
byte streams) has changed since the archive was made.
When specified as -dd bru reports additional differences in
modification date (st_mtime) access mode (st_mode), number of
links (st_nlink) for non-directory files, differences in the
contents of symbolic links, owner id (st_uid), and group id
(st_gid).
When specified as -ddd bru reports additional differences in
host device (st_dev), major/minor device (st_rdev) for special
files, and time of last access (st_atime) for regular files.
When specified as -dddd bru reports all differences except time
of last status change (st_ctime is not resettable), major/minor
device numbers for non-special files (meaningless), and size
differences for directory files (may have empty entries). The
-dddd mode is generally only meaningful during a verification
pass with full backups of quiescent filesystems.
-e Estimate media requirements for archive creation with same
arguments. Prints estimated number of volumes, number of files
to be archived, total number of archive blocks, and total size
of archive in kilobytes. If the media size is unknown,
unspecified, or set to 0 via the -s flag or the brutab file, it
is assumed to be infinite. The -Z flag may also be given. If
used, every file that would be backed up will be compressed to
a temporary file, which may slow down the estimation
considerably. When -Z,-c and -e are all used, each file will
be compressed twice, once during the estimation pass, and once
while writing to the archive.
Page 2
BRU(1) BRU(1)
-g Dump archive info block in a form more easily parsed by
programs implementing a complete filesystem management package.
Performs no other archive actions. Note: when used with -t,
and the rewind tape device, this information is printed after
the file list. This option will not work when used with -t if
the norewind tape device is used, since bru expects to be
positioned at the beginning of the tape archive after the tape
device is closed. When a number of bru archives are written to
the same tape, a sequence like that below will work correctly
(where # is the position of a particular archive set), listing
first the label information, and then the files in the same
archive.
mt fsf #
bru -vgf /dev/nrtape
mt bsf 1
bru -vtf /dev/nrtape
-h Print help summary of options. Also prints some internal informa-
tion such as version number and default values for archive pathname,
media size, archive buffer size, etc.
-i Inspect archive for internal consistency and data integrity. When
-vv option is also given, prints information from archive header
block.
-t List table of contents of archive. When used with the -v option
will give a verbose table of contents in the same format as the "ls
-l" command. When used with the -vv option will also indicate what
files are linked to other files, and where symbolic links point to.
-x Extract named files from archive. If an archived file is extracted
(see -u option) then the access mode, device id (special files
only), owner uid, group uid, access time, and modification time are
also restored. If the -C flag is given (see below), then the owner
uid and group uid will be changed to that of the current user.
Nonexistent directories are recreated from archived directories if
possible, otherwise they are created with appropriate defaults for
the current user. Extracted or created directories are initially
empty.
CONTROL OPTIONS
Many of the control options are similar in function to their tar or cpio
equivalents.
Sizes are specified in bytes. The scale factors M, k, or b, can be used
to indicate multiplication by 2**20, 1024, or 512 respectively. Thus
"10k", "20b", and "10240" all specify the same number of bytes.
Page 3
BRU(1) BRU(1)
-a Do not update the access times of disk files that have been read
while performing other actions. Normally bru restores the access
and modification times of disk files after they have been read to
the access and modification times to whatever they were before the
read operation. Restoring the times prevents defeat of the mechan-
ism used to track down and remove "dead" files that haven't been
accessed in any meaningful way recently. Note that this has the
side effect that backup programs such as dump(1m) will backup the
file, since the ctime of the file will have been modified; use of -a
is therefore recommended when using dump as your system backup util-
ity. Use of -a will also slightly speed up backups, since the inode
will not be written.
-b bsize
Use bsize as the archive input/output buffer size. The minimum is
the size of an archive block (2k or 2048 bytes) and the maximum is
determined by available memory and I/O device limitations. If bsize
is not an even multiple of 2048 bytes, it will be rounded up. Nor-
mally this option is only required with the -c mode since bru writes
this information in the archive header block. If specified, bsize
overrides any existing default value (generally 20k), whether built
in or read from the archive header.
-B Useful in shell scripts where bru is run in the background with no
operator present or not possible, such as when there is no control-
ling terminal, causing an open of /dev/tty to fail. Under these
conditions, bru simply terminates with appropriate error messages
and status, rather than attempting interaction with the terminal.
With this option, bru will exit, rather than try to open the con-
trolling terminal. In this case, the entire backup must fit on a
single tape or other media, as there is no way to ask for a media
change.
-C Change the owner (chown) and group of each extracted file to the
owner uid and group gid of the current user. Normally, bru will
restore the owner and group to those recorded in the archive. This
flag causes bru to follow the system default, with extracted files
having the same owner and group as the user running bru, including
Root.
The -C option is useful with archives imported from other systems.
In general, it should not be used by the operator or system adminis-
trator when restoring saved files. Use the -tv option to see the
owner and group of files stored in the archive.
-D This option is not implemented, but is still accepted for backward
compatibility with scripts that may use it.
-f path
Use path as the archive file instead of the default. If the path is
"-" then bru uses the standard input for archive reading or standard
output for archive writing, as appropriate. If the path is remote
Page 4
BRU(1) BRU(1)
then it needs to be specified as [user@]system:/dev/??? The <user@>
part of the path is optional, and if none is specified then the
user's login is used. The login has to be equivalently mapped to the
remote machine if it has a password.
-F Fast mode. In fast mode, checksum computations and comparisons are
disabled. This mode is useful when the output of one bru is piped
to the input of another bru, or when the data integrity of the
archive transmission medium is essentially perfect. Archives
recorded with fast mode enabled must also be read with fast mode.
Also, be aware that some of the automatic features of bru, such as
automatic byte swapping, are not functional in fast mode.
-j Convert absolute pathnames to "." relative pathnames. This option
applies only to the -x mode.
-X Echo relative pathnames as absolute pathnames. This option only
valid when used in conjunction with the -x, -j and -v options.
-L str
Label the archive with the specified string str. Str is limited to
63 characters and is usually some meaningful reminder pertaining to
the archive contents.
-l Ignore unresolved links. Normally bru reports problems with
unresolved links (both regular and symbolic links). This option
suppresses all such complaints.
-m Do not cross mounted file system boundaries during expansion of
explicitly named directories. This option applies only to direc-
tories named in files. It limits selection of directory descendents
to those located on the same filesystem as the explicitly named
directory. This option currently applies only to the -c and -e
modes.
-p Pass over files in archive by reading rather than seeking. Normally
bru will use random access capabilities if available. This option
forces reading instead of seeks.
-R Remote files are to be excluded from the archive (unless explicitly
listed on the command line; remote directories on the command line
are backed up as a directory, but files, subdirectories, etc.
therein will not be backed up).
-s msize
Use msize as the media size. The effective media size will be com-
puted from msize since it must be integral multiple of the
input/output buffer size (see the -b option). Normally this option
is only required with the -c or -e flags since bru writes this
information in the archive header block. If specified, msize over-
rides any existing default value, whether built in, read from the
brutab file, or read from the archive header. If set to 0, the tape
Page 5
BRU(1) BRU(1)
is assumed to be infinite in length, and the archive is written
until an error occurs, at which time a new volume is prompted for.
-v Enable verbose mode. May be specified more than once, as -vv, -vvv,
or -vvvv, to get even more verbosity.
-w Wait for confirmation. Bru will print the file name, the action to
be taken, and wait for confirmation. Any response beginning with
'y' will cause the action to complete. Any other response will
abort the action.
-Z Use 12-bit LZW file compression. This is not the default because
not all versions of bru know how to deal with compressed files.
When the -v option is also selected, the compression ratio for each
file is printed as a percentage. When this flag is used in conjunc-
tion with the -t option on an archive that contains compressed file,
the actual archive file sizes and names are printed, rather than the
original values before archiving. Files are compressed into a tem-
porary file in a directory given by the BRUTMPDIR environment vari-
able. If not given, /usr/tmp is used.
FILE SELECTION OPTIONS
The file selection options control which files are selected for process-
ing. Note that some options are only valid with specific modes.
-n date Select only files newer than date. The date is given in one of
the forms:
DD-MMM-YY[,HH:MM:SS] EX: 12-Mar-84,12:45:00
MM/DD/YY[,HH:MM:SS] EX: 3/12/84
MMDDHHMM[YY] EX: 0312124584
pathname EX: /etc/lastfullbackup
The time of day is optional in the first two forms. If
present, it is separated from the date with a comma.
If date is really the pathname of a file, then the modification
date of that file will be used instead. This is useful in
automated backups when a dummy file is "touched" to save the
date of last backup.
-o user Select only files owned by user. User may be specified in one
of three ways:
o As an ascii string corresponding to a user name in the
password file.
o As the pathname of a file in which case the owner of
that file is used.
o As a numeric value (decimal).
Page 6
BRU(1) BRU(1)
-u flags When used in conjunction with -x mode, causes files of type
specified by flags to be unconditionally selected regardless of
modification times. Normally bru will not overwrite (super-
sede) an existing file with an older archive file of the same
name. Files which are not superseded will give warnings if
verbose mode level 2 (-vv) or higher is enabled. Possible
characters for flags are:
b select block special files
c select character special files
d select directories
l select symbolic links
p select fifos (named pipes)
r select regular files
Selection of directories only implies that their attributes may
be modified. Existing directories are never overwritten, this
option merely allows their attributes to be set back to some
previously existing state.
Selection of symbolic links only implies that the contents of
the link will be modified. It is currently impossible to
change access time, modification time, or the file mode of a
symbolic link.
EXAMPLES
Create (-c) a new archive of all files under "/usr/src", writing archive
to file (-f) "/dev/rmt0" using multiple tapes with a maximum size (-s) of
30 megabytes per tape.
bru -c -f /dev/rmt0 -s 30M /usr/src
Create (-c) a new archive on the default device in the first pass,
archiving all files in and below the current directory which have been
created or modified (-n) since 3 P.M. on 14-Jan-84. Then do a second
pass to verify that there are no differences (-d) between the archive and
current files. Each file is listed (-v) as it is processed.
bru -cvd -n 14-Jan-84,15:00:00
Archive all files owned (-o) by user "user1" using the default archive
device.
find / -user user1 -print | bru -c -
bru -c -o user1 /
Copy a directory hierarchy from "/usr/u1" to "/usr/u2".
(cd /usr/u1; bru -cf - ) | (cd /usr/u2; bru -xf -)
Page 7
BRU(1) BRU(1)
Extract (-x) the regular file "/usr/guest/myfile" unconditionally (-ur)
from an archive on file (-f) "/dev/rf0". Since the device size was
recorded in the header block, it need not be specified. Note that option
arguments do not need to be separated from their corresponding option
flag by whitespace.
bru -x -ur -f/dev/rf0 ./usr/guest/myfile
Extract (-x) all C source files in "/usr/src/cmd" that have names begin-
ning with characters 'a' through 'm'. Wait (-w) for confirmation before
extracting each file.
bru -xw '/usr/src/cmd/[a-m]*.c'
Inspect (-i) a previously created archive on the default device, dumping
the contents of the header block for inspection (-vvv) and verifying
internal consistency and data integrity of the archive.
bru -ivvv
Back up the entire root filesystem without crossing mounted (-m) filesys-
tem boundaries. The archive will be written to file (-f) "/dev/rmt0"
using an I/O buffer size (-b) of 10k bytes.
cd /
bru -cvm -f /dev/rmt0 -b 10k
DIAGNOSTICS
Most diagnostics are reasonably informative. The most common have to do
with meaningless combinations of options, incompatible options, hitting
memory or device limits, unresolved file links, trying to archive or
restore something to which access is normally denied, or problems with
media errors and/or archive corruption.
DEVICE TABLE
Bru contains an internal table of known devices and their characteris-
tics. This table is dynamically loaded from a data file specified by the
environment variable BRUTAB, or from /etc/brutab, or from an internal
default description if neither of the preceding is found.
The format of the bru data file for loadable devices is as follows. Note
that the table MUST contain at least one entry and the first entry is the
default archive device.
Also, the table should contain an entry for the standard input and out-
put, with a name of "-".
Entries consist of a device name field, followed by one or more capabili-
ties fields. Entries may span more than one line by escaping the newline
at the end of the line with a '\' character ('\' is last character on
line before newline). All whitespace (tabs, blanks, newlines, formfeeds)
between fields is ignored.
Page 8
BRU(1) BRU(1)
The device name field must be the first field in the entry and has the
following form:
<device name>|<device name>| ... |<device name>
example: /dev/rmt[0-2]|/dev/mt[0-2]
where each device has the same capabilities as the other devices speci-
fied (a class of devices). Regular expressions as described in regexp(3)
may be used.
Each capability field is of the form:
<capability name>=<value> or <boolean flag>
example: size=640K REOPEN pwerr=EIO
Note that there can be no whitespace between the capability name and the
value. Note that a size of 0 is treated specially, see the -s flag
description above. Numeric values may be given in absolute form or with a
trailing scale factor of:
b or B Blocks (512 bytes)
k or K Kilobytes (1024 bytes)
m or M Megabytes (1024 * 1024 bytes)
Error numbers may be given in absolute or symbolic form, as defined in
<errno.h>.
Currently used capabilities include:
Name Type Meaning
______________________________________________________________________
size numeric media size in bytes if known, zero otherwise
seek numeric minimum seek resolution, zero if no seeks allowed
prerr numeric errno for partial reads
pwerr numeric errno for partial writes
zrerr numeric errno for zero reads
zwerr numeric errno for zero writes
frerr numeric errno for read of unformatted media
fwerr numeric errno for write of unformatted media
wperr numeric errno for write protected media
reopen boolean close and reopen archive upon media switch
noreopen boolean no close and reopen archive upon media switch
tape boolean archive device is a tape drive
rawtape boolean archive device is a "raw" tape drive
used primarily with devices that support
multiple block sizes
norewind boolean closing does not automatically rewind
advance boolean read/writes advance media even when errors occur
Page 9
BRU(1) BRU(1)
For instance, an excerpt from /etc/brutab for SCSI tapedrives is:
/dev/r*mt/tps[0-9]d[1-7]nr* \
size=0K seek=0 \
prerr=EIO pwerr=EIO zrerr=ENOSPC zwerr=ENOSPC frerr=0 fwerr=0 \
wperr=EROFS norewind reopen tape rawtape advance
#
/dev/r*mt/tps[0-9]d[1-7]* \
size=0K seek=0 \
prerr=EIO pwerr=EIO zrerr=ENOSPC zwerr=ENOSPC frerr=0 fwerr=0 \
wperr=EROFS reopen tape rawtape advance
# This entry is a generic entry for stdin and stdout.
- size=0 seek=0 prerr=0 pwerr=0 zrerr=0 zwerr=0 frerr=0 fwerr=0 wperr=0
The internal table that is used if no file can be found is:
/dev/tape* \
size=0k seek=0 \
prerr=EIO pwerr=EIO zrerr=ENOSPC zwerr=ENOSPC frerr=0 fwerr=0 \
wperr=EROFS reopen tape rawtape advance
/dev/nrtape* \
size=0k seek=0 \
prerr=EIO pwerr=EIO zrerr=ENOSPC zwerr=ENOSPC frerr=0 fwerr=0 \
wperr=EROFS norewind reopen tape rawtape advance
SIGNAL HANDLING
Bru normally catches both interrupt (SIGINT) and quit (SIGQUIT). When
interrupt is caught during archive creation or extraction, bru completes
its work on the current file before cleaning up and exiting. This is the
normal way of aborting bru. When a quit signal is caught an immediate
exit is taken.
Note that during file extraction, a quit signal may leave the last file
only partially extracted. Similarly, a quit signal during archive writ-
ing may leave the archive truncated. When either interrupt or quit is
caught at any other time an immediate exit is taken.
ERROR RECOVERY
When properly configured for a given software/hardware environment, bru
can recover from most common errors. For example, attempts to use unfor-
matted media are detected, allowing substitution of formatted media.
Random blocks in an archive can be deliberately overwritten (corrupted)
without affecting bru's ability to recover data from the rest of the
archive. When I/O errors are detected, retries are performed automati-
cally. Out of order sequencing on multi-volume archive reads is
detected, allowing replacement with the correct volume.
Page 10
BRU(1) BRU(1)
DIRECTORIES
When creating non-incremental archives bru automatically archives all
directories necessary to fully restore any file from the archive. During
extraction, any required directories which do not already exist are
restored from the archive if possible, otherwise they are created with
appropriate defaults for the current user.
The net result is that restoration from incremental archives (which may
not contain all necessary directories), or incremental restoration from
full archives (which may skip directories needed later), may result in
creation of directories with the default attributes.
WILDCARDS
When reading archives bru recognizes file name generation patterns in the
same format as the shell. This allows greater flexibility in specifying
files to be extracted, compared, or listed. As a special extension to
shell type expansion, the sense of the match is reversed for patterns
that begin with '!'.
Note that the patterns may have to be quoted to prevent expansion by the
shell. Also note that patterns are processed independently, without
regard for any other patterns that may or may not be present. In partic-
ular, "/bin/a* /bin/b*" is equivalent to "/bin/[ab]*", but "/bin/!a*
/bin/!b*" is equivalent to "/bin/*", not "/bin/![ab]*".
BYTE/WORD SWAPPING
While reading archives produced on other machines, bru automatically
attempts to perform byte and/or word swapping as necessary.
If no device table is specified, bru automatically uses the no-swap tape
device, which provides higher performance and compatibility with non-byte
swapped tapes from other systems. The Iris 3000 series does not support
non-byte swapped tapes, but the automatic byte-swapping capabilities of
bru will deal with this problem.
REMOTE TAPE DRIVES
Bru allows the use of remote tape drives for the archive device (via the
-f option). A remote tape drive file name has the form
[user@]system:/dev/???
where system is the remote system, the optional user is the login name to
use on the remote system if different from the current user's login name,
and /dev/??? is the tape drive to use (1600 BPI or 800 BPI, raw or
blocked, rewinding or non-rewinding, etc.). In all cases, the user must
have the appropriate permissions on the remote system. (See also the
CAVEATS section, below.)
EXIT CODES
Bru always returns meaningful status as follows:
Page 11
BRU(1) BRU(1)
0 Normal exit, no errors or warnings.
1 Warnings (or interrupted).
2 Errors (or quit signal).
SEE ALSO
tar(1), cpio(1), rmt(1M).
UNIX SYSTEM INCOMPATIBILITIES
Bru recognizes special file types that may be allowed on one type of Unix
system, but not on another. For instance, on a 4.2 BSD system, bru will
extract fifos as plain files (mode 0666, as modified by the umask), and
issue an appropriate error message. Usually, bru will issue two mes-
sages. The first message will be the more descriptive of the two.
Currently, the only different Unix systems that bru fully understands are
System V, 4.2 BSD, and Pyramid's OSx.
CAVEATS
Pathnames are limited to 127 characters in length. This could become a
chronic problem.
Implementation differences complicate the algorithms for automatic detec-
tion of end of file on devices. The algorithms can be fooled, hence the
-s option.
Special files moved to a machine other than their original host will gen-
erally be useless and possibly even dangerous. This goes double for sym-
bolic links.
When extracting files from archives, patterns used to match directories
may result in some unnecessary directories being extracted. For example,
if the pattern is "a/*/c", and the directory "a/b" is encountered in the
archive, the directory file "a/b" will be extracted since it will be
needed when (and if) the file "a/b/c" is encountered. When in doubt, use
the -w option.
In order to be able to efficiently archive needed directories, bru builds
an image of the directory tree for files using dynamically allocated
memory. Since there may be at most 5120 characters passed on the command
line, it is very unlikely that bru will run out of memory while building
the tree from command line arguments. This is not true of file lists
read from the standard input, particularly on machines with limited ad-
dress space.
Information about file linkages is also kept in memory. Some linkages
may be lost if memory is exhausted.
Since bru is owned by root and runs with "set user id" to allow it to
create directories and special files, it makes every attempt to prevent
normal users from archiving or extracting files they would normally not
have access to. There may be loopholes. Also note that anyone with phy-
Page 12
BRU(1) BRU(1)
sical or electronic access to an archive, and knowledge of the archive
structure, can recover any of its contents by writing their own file ex-
traction program.
Files within directories which have filesystems mounted on them will not
be properly archived until the filesystem is unmounted, since the mounted
filesystem hides them. This is not generally a problem.
Explicitly naming both a directory and one of its descendents will cause
the descendent to be archived twice, unless they are on separate filesys-
tems and the -m flag is used.
Explicitly naming a file more than once is ineffective.
When reading from the raw magnetic tape file (rmtxxx) bru automatically
attempts to adjust the I/O buffer size to match that used to record the
archive. Under certain circumstances it may fail and require help via
the -b option.
Using remote tape drives can be slow.
Page 13