The full BRU manual page follows. Appendix B is an abbreviated form of this manual page. It contains a help list of bru options and short definitions. It also shows you how to list brutab parameter values and device information. Appendix D contains a table of options cross referenced to the bru modes with which they may be used.
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:
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 descendants 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.
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.
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 capable of being reset), major/minor device numbers for non-special files (meaningless), and size differences for directory files (may have empty entries). The -dddd mode is generally meaningful only 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 or unspecified, it is assumed to be infinite. Estimates are for uncompressed data only; the -Z option will be ignored.
-g Dump archive info block in a form more easily parsed by programs implementing a complete filesystem management package. Performs no other archive actions.
-gg List archive list of files created during the bru -cvG mode. This has been deprecated and is no longer used in BRU 17.0.
-h Print help summary of options. Also prints some internal information 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.
-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 G, M, k, or b, can be used to indicate multiplication by 1024*1024*1024 (one Gigabyte), 1024*1024 (one Megabyte), 1024, or 2048 (the size of a bru tape block) respectively. Thus “10k”, “5b”, and “10240” all specify the same number of bytes.
-a Reset the access times of disk files that have been read while performing other actions.
-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. Normally this option is only required with -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. Under these conditions, bru simply terminates with appropriate error messages and status, rather than attempting interaction with the terminal.
-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. (Under 4.2 BSD, the default group is that of the directory in which the file is created.)
The -C option is useful with archives imported from other systems. In general, it should not be used by the operator or system administrator when restoring saved file. Use the -tv option to see the owner and group of files stored in the archive.
-D Causes bru to use double buffering to the archive device on systems that have System V-style shared memory. Depending on hardware constraints, double buffering may dramatically increase the archive device I/O rate but may adversely affect the error recovery algorithms.
-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 multiple -f options are given, each path is added to a list of files to cycle through each time a volume change is required. When the end of the list is reached, bru automatically cycles back to the first path and waits for confirmation to continue the cycle again. Any input other than a carriage return will cause bru to use the newly entered path and to abort the cycling for the remainder of the current run.
-F 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 in this mode must also be read in this mode. Be aware that some of the automatic features of bru, such as automatic byte swapping and AUTOSCAN, are not functional in fast mode.
-Iqrlb
When BRU is running in the background, there is no way to interact with it. The -I qrlb options allow a users to setup a set of read and write fifos that a second program BRUTALK and work with to responed with BRU. Below we have listed the “qrlb” options that are currently valid with the -I option.
q,fifo write queries to fifo
r,fifo read responses from fifo
l,file write log info to file
b Use the default fifos created durning install.
/bru/bru.q (Default send fifo)
/bru/bru.r (Default reply fifo)
The q and r options are useful for interacting with bru when it has been run without a controlling terminal. See the discussion under RUNNING FROM CRON.
-L str (c)
In create mode, label tape with given string (63 char max).
-L file
In create mode, the first 63 characters in file are used as the label for the archive members. In extract mode the first 63 characters within file are used for the comparison as described below.
-L str (x)
In extract mode, only restore if the label of the archive EXACTLY matches the given string. If the string does not match on the initial tape, the operation aborts. If the label does not match on subsequent tapes, a warning is issued, but the extraction continues.
-r rawdev
This enables BRU to backup or restore raw data partitions. A BRURAW file must exist and contain entries that define the raw data to be accessed. See the discussion of the BRURAW global variable below for information on the BRURAW file and location. The file contains entries in this format:
Raw Device Name Size Blk Size Starting Offset
———————- —— ———— ———————-
a sample entry would be:
/dev/rdisk0 30M 512 0
An entry MUST exist in the BRURAW file or bru will abort the operation with an error message.
When backing up raw partitions, you must either have the device node in the tree relative to your current location or you must explicitly declare the raw device on the command line as a file name. For example, if you are in / and the raw device node is /dev/rdisk1, you can use this command line to back it up properly:
bru -cvV -r /dev/rdisk1
If, however, you are invoking the bru command from your home directory, you must include the path to the device node on the command line:
bru -cvV -r /dev/rdisk1 /dev/rdisk1
Additionally, the filesystem being backed up MUST be locked or unmounted to prevent any writes from occurring during the backup. If this is not done, the data could be corrupted during the process of backing it up.
-T file
Translate on restore – rename or relocate files based on the contents of a translation file. The file can be any file name. It is an ASCII text file which contains two columns – all files that contain the text in column 1 will have that text translated to the text in column 2.
* It is important to note that there can be NO empty fields in this file. You MUST provide both columns for each line in the translation file.
This translation applies to directories, names and extensions. By default, symbolic links will not be translated. See the
-Q option below. Translate works with all BRU modes except create (-c).
To restore all of the files in /home/bob to /home/ted, you should have the following information in your file.:
/home/bob /home/ted
No further interaction is required by the user. Also multiple translations can occur within a single restore. We could perform both of the above translations and others by placing the columns into a single translation file as follows:
/home/bob /home/ted
/usr/lib /usr2/lib
/home /u2
...etc
The translation file can contain as many translation lines as necessary, but each line must consist of a balanced pair of entries.
-Q HLRSV
Changes default BRU operation as described below:
H This turns off placing small files into tape headers. Using this option allows you to create BRU tapes that are compatible with versions of BRU prior to 14.2
L Use a literal string as a tape label. This overrides BRU’s attempt to look for a file from which to read the tape label. This can be useful if you have a file that is the same name as the label you wish to apply.
R Disable SmartRestore. This turns off BRU’s handling of open or shared files. It is not recommended that you override this setting.
S Translate Symbolic Links. Used in conjunction with the -T option (see above) will force the translation of symbolic links.
V Ignore “Incorrect Volume” warnings. When restoring from a multi-tape set or beginning a restore from other than the first tape in a set, use of this option will prevent the normal warning about having the incorrect volume and continue with the restore.
-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 directories named in files. It limits selection of directory descendants to those located on the same filesystem as the explicitly named directory. This option currently applies only to the -c and -e modes.
-N level
Use level as the compression level if -Z is also specified. The default is to use level 3. The allowable values are 1 – 9, with 1 being lowest. The higher the level, the more agreesively BRU will work to compress the file. This will be at the cost of processor power – higher compression uses more CPU power.
-O Overwrite the archive regardless of the settings for OVERWRITEPROTECT and RECYCLEDAYS.
-p Pass over files in archive by reading rather than seeking. Normally bru will use random access capabilities if available. This option forces reads instead of seeks. Use only on disk files or disk media.
-P flags
Pathname options that provide explicit control of expansion of directories, automatic archiving of parent directories, etc.
Possible characters for flags are:
e Disable automatic expansion of explicitly named directories.
E Enable automatic expansion of explicitly named directories
f Disable filter mode. Builds internal tree of pathnames before doing anything with the pathnames from the input list.
F Enable filter mode. Each pathname from the input list is treated individually, and processing is done with that pathname before the next pathname is examined.
p Disable automatic archiving of parent directories of explicitly named files or directories.
P Enable automatic archiving of parent directories of explicitly named files or directories.
See the discussion under DIRECTORIES.
-R Remote files are to be excluded from the archive. If the system does not support remote filesystems, this option is ignored.
-s msize
Use msize as the media size. The effective media size will be computed from msize since it must be an integral multiple of the input/output buffer size (see the -b option). Normally this option is only required with the -c mode since bru writes this information in the archive header block. If specified, msize overrides any existing default value, whether built in or read from the archive header.
-S size
Enable options to deal more intelligently with sparse files (files with lots of null bytes). When used in conjunction with the -c mode, turns on automatic file compression for files that are larger than the specified size. When used in conjunction with the -x mode, seeks will be used to create blocks of null bytes in the output file, rather than actually writing null bytes. See the discussion under SPARSE FILES.
-v Enable verbose mode. May be specified more than once, as -vv, -vvv, or -vvvv, to get even more verbosity. The -vvvv form of this option includes an execution summary (see -V).
-V Print execution summary only. The -vvvv option includes an execution summary as part of its output.
-X Apply exclusion patterns specified in the file /etc/bruxpat (or in the file specified by the BRUXPAT environment variable).
-w Wait for confirmation. bru will print the file name and the action to be taken and will wait for confirmation. Any response beginning with ‘y’ or ‘Y’ will cause the action to complete. Any response beginning with ‘g’ or ‘G’ will cause the action to complete and will reset the -w option so that no further confirmations will be requested. Any other response will abort the action.
-Z Use lzop 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 conjunction with the -t option on an archive that contains compressed files, the actual archive file sizes and names are printed, rather than the original values before archiving.
A limited amount of backward compatibility with non-compressed versions of bru is provided. Archives read by older versions will appear to contain files that were precompressed prior to archiving. The public domain compress utility can be used to decompress such files after dearchiving. See the -N option.
FILE SELECTION OPTIONS
The file selection options control which files are selected for processing. Note that some options are valid only with specific modes.
-n date
Select only files newer than date. The date is given in one of the forms:
Format Example
DD-MMM-YY[,HH:MM:SS],[amc] 12-Mar-84,12:45:00.ac
MM/DD/YY[,HH:MM:SS],[amc] 3/12/84,ac
MMDDHHMM[YY],[amc] 0312124584,ac
pathname /etc/lastfullbackup
The time of day is optional in the first two forms. If present, it is separated from the date by a comma.
By default, the modification and create times are used for comparison. Other times can be used by specifying letters after the date (a=access time, m=modification time, c=create time). For example:
-n 14-Apr-84,15:24:00,ac
If the date is preceded by an exclamation point (!), then files older than the specified date will be selected.
If date is the pathname of a file, then the modification date of that file will be used. This is useful in automated backups when a dummy file is “touched” to save the date of the last backup. NOTE: do not use the [amc] modifier with tis option.
-o user
Select only files owned by user. User may be specified in one of three ways:
As an ascii string corresponding to a user name in the password file.
As the pathname of a file, in which case the owner of that file is used.
As a numeric (decimal) value. This value will be the user ID as found in the passwd file.
-u flags
When used in conjunction with -x mode, causes files of the type specified by flags to be unconditionally selected regardless of modification times. Normally bru will not overwrite (supersede) 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:
a select all files (same as specifying all flags)
b select block special files
c select character special files
d select directories
l select symbolic links
p select fifos (named pipes)
f select regular files (same as r)
r select regular files (same as f)
-U # Selection depth for backup or restore of files in relation to the current directory depth. Files more than (#) levels Under this level will not be processed.
For example, if the current directory is /home/ted, -U0 (zero) will only backup the files and directory nodes in the home/ted directory. While the directory nodes will be backed up, any files in directories off of this level will not be backed up. With a level of 2, BRU will backup files in /home/ted/test, /home/ted/test/runone, /home/ted/test/runtwo, but not in /home/ted/test/runone/demo1.
This same feature works for restoring files and directory trees as well.
Selection of directories implies that only 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 implies that only the contents of the link will be modified. It is currently impossible under 4.2 BSD 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) “tape0” using multiple tapes with a maximum size (-s) of 20 gigabytes per tape.
bru -c -f tape0 -s 20G /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 since 3 P.M. on 14-Jan-92 (-n). 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-92,15:00:00
Archive all files owned (-o) by user “user1” using the default archive device.
bru -c -o user1 /
Copy a directory hierarchy from “/usr/u1” to “/usr/u2”.
(cd /usr/u1; bru -cf – ) | (cd /usr/u2; bru -xf -)
Extract (-x) the regular file “/usr/guest/myfile” unconditionally (-ur) from an archive on file (-f) “tape0”. 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 tape0 ./usr/guest/myfile
Extract (-x) all C source files in “/usr/src/cmd” that have names beginning 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 the internal consistency and data integrity of the archive.
bru -ivvv
Back up the entire root filesystem without crossing mounted (-m) filesystem boundaries. The archive will be written to file (-f) “tape0” using an I/O buffer size (-b) of 10k bytes. A record of all files processed will be written to file “brulogfile” for future reference.
cd /
bru -cvm -f tape0 -b 10k >brulogfile
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 characteristics. bru first looks for an environment variable BRUTAB, which contains the name of the dynamically loaded file if it begins with a ‘/’ character, or contains device descriptions if the first character is not ‘/’. If there is no BRUTAB environment variable, the file /etc/brutab is loaded. If neither of the preceding is found, an internal default description is loaded.
SIGNAL HANDLING
bru normally catches both interrupt (SIGINT) and quit (SIGQUIT) signals. When an 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 creation may leave the archive truncated.
When either interrupt or quit is caught at any time other than during archive creation or extraction, 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 unformatted 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 automatically. Out of order sequencing on multi-volume archive reads is detected, allowing replacement with the correct volume.
DIRECTORIES
bru takes two actions with respect to directories that make creation and extraction of entire hierarchies of files more convenient and complete. These actions are automatic archiving of parent directories and automatic expansion of explicitly named directories.
Automatic archiving of parent directories means that when bru is given the complete pathname of a file to archive, it attempts to automatically archive all parent directory nodes necessary to fully restore the specified file. 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. When bru reads it’s list of files from the standard input, or when the -Pp option is given, this automatic archiving of parent directory nodes is suppressed. Note also that when creating archives with additional constraints on the selected files (such as use of the -n option), these parent directories may be excluded.
Automatic expansion of explicitly named directories means that when bru is given an explicit file name that names a directory node, not only is that directory node archived, but all files and subdirectories in that directory are archived. I.e., the entire file hierarchy rooted in the explicitly named directory is archived. When bru reads its list of files from the standard input, or when the -Pe option is given, this automatic expansion of directories is suppressed.
Note that incremental archives, archives created with the -Pp option, or archives created from a list of files supplied on the standard input stream, may not contain all of the necessary parent directories to replicate the original hierarchy and thus may result in creation of directories with the default attributes when files are extracted from the archive.
When bru reads the list of files from the standard input stream, the default values for the -P options are -PeFp, which turns off expansion of directories, turns on filter mode, and turns off automatic archiving of parent directories. This allows bru to be conveniently used to archive only filesystem nodes that are explicitly named on the input list.
When files are explicitly named on the command line (or default to ‘.’), the default values for the -P options are -PEfP, which turns on expansion of directories, turns off filter mode, and turns on automatic archiving of parent directories. This is typically the most convenient behavior for arguments given on the command line.
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 of 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 to any other patterns that may or may not be present. In particular, “/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.
REMOTE TAPE DRIVES
On 4.2 BSD systems, and System V systems that support networking, 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
system[.user]:/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.)
RUNNING FROM CRON
Sometimes it is convenient to run bru under conditions where there is no controlling terminal. This can be a problem if interaction is needed, such as when switching to a new volume. As an example, consider the case of running bru from cron, where the operator mounts a tape before leaving in the evening, and bru writes the first volume in the middle of the night. When returning in the morning, the operator wants to be able to mount a second tape if necessary, and instruct bru to continue.
If no interaction with the user is required, running from cron is no different than running directly from a terminal. However, when interaction is necessary there are basically two options; terminate, or find some way to communicate with the operator (or another program masquerading as the operator). The -B option provides for simple termination. The -I options provide for communication with an operator.
On systems that support fifos, a pair of fifos are used to send requests and receive replies. Before running bru, verifiy that these fifos are present if they are not then create the pair of fifos with the commands:
mknod /bru/bru.q p
mknod /bru/bru.r p
Then, add the arguments “Ib” or if you created any other name for your fifos then run the following command “-Iq,/bru/bru.q -Ir,/bru/bru.r” to the desired bru command line which ultimately gets executed undercron. The first time bru needs to communicate with an operator, it will open the two fifos, write a query to the bru.q fifo, and wait for a response from the bru.r fifo. A simple program provided with bru, called brutalk can be used to read the query and send a reply:
brutalk
brutalk /bru/bru.r
The brutalk program will continue to read queries and send replies until either bru exits, or a control-D (EOF) is typed at the terminal.
EXIT CODES
Bru always returns meaningful status as follows:
0 Normal exit, no errors or warnings.
1 Warnings (or interrupted).
2 Errors (or quit received).