BBBBRRRRUUUU((((1111)))) UUUUNNNNIIIIXXXX 5555....0000 BBBBRRRRUUUU((((1111)))) NNNNAAAAMMMMEEEE bru - backup and restore utility SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS bbbbrrrruuuu mmmmooooddddeeeessss [ ccccoooonnnnttttrrrroooollll ooooppppttttiiiioooonnnnssss ] [ sssseeeelllleeeeccccttttiiiioooonnnn ooooppppttttiiiioooonnnnssss ] files DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN _B_r_u is a UUUUnnnniiiixxxx filesystem backup utility with significant enhancements over other more common utilities such as _t_a_r, _c_p_i_o, _v_o_l_c_o_p_y, and _d_d. Some of _b_r_u'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 _f_i_l_e_s are specified on the command line then the actions to be performed are limited to those _f_i_l_e_s. If a named file is a directory then it and all its descendents are used. If no _f_i_l_e_s 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 _f_i_l_e_s then the standard input is read to obtain the file list. This is useful in conjunction with the _f_i_n_d command to provide finer control over files selected for backup. Obviously this mode is only valid when _b_r_u is not also reading its archive from the standard input. DDDDEEEEFFFFAAAAUUUULLLLTTTTSSSS 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 ----hhhh mode. Page 1 (printed 12/28/86) BBBBRRRRUUUU((((1111)))) UUUUNNNNIIIIXXXX 5555....0000 BBBBRRRRUUUU((((1111)))) MMMMOOOODDDDEEEESSSS One or more of the following modes must be specified. The order of execution, from highest priority to lowest, is eeeecccciiiittttxxxxddddgggghhhh. ----cccc CCCCrrrreeeeaaaatttteeee a new archive. Forces a new archive to be created regardless of whether one currently exists. Writing starts at the first block. ----dddd DDDDiiiiffffffffeeeerrrreeeennnncccceeeessss between archived _f_i_l_e_s and current _f_i_l_e_s are detected and reported. May be specified more than once, as ----dddddddd ----dddddddddddd or ----dddddddddddddddd to control level of difference checking. When specified as ----dddd _b_r_u 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 ----dddddddd _b_r_u 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 ----dddddddddddd _b_r_u 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 ----dddddddddddddddd _b_r_u 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 ----dddddddddddddddd mode is generally only meaningful during a verification pass with full backups of quiescent filesystems. ----eeee EEEEssssttttiiiimmmmaaaatttteeee 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. ----gggg Dump archive info block in a form more easily parsed by programs implementing a complete filesystem management package. Performs no other archive actions. Page 2 (printed 12/28/86) BBBBRRRRUUUU((((1111)))) UUUUNNNNIIIIXXXX 5555....0000 BBBBRRRRUUUU((((1111)))) ----hhhh Print hhhheeeellllpppp summary of options. Also prints some internal information such as version number and default values for archive pathname, media size, archive buffer size, etc. ----iiii IIIInnnnssssppppeeeecccctttt archive for internal consistency and data integrity. When ----vvvvvvvv option is also given, prints information from archive header block. ----tttt List ttttaaaabbbblllleeee of contents of archive. When used with the ----vvvv option will give a verbose table of contents in the same format as the "ls -l" command. When used with the ----vvvvvvvv option will also indicate what files are linked to other files, and where symbolic links point to. ----xxxx EEEExxxxttttrrrraaaacccctttt named _f_i_l_e_s from archive. If an archived file is extracted (see ----uuuu option) then the access mode, device id (special files only), owner uid, group uid, access time, and modification time are also restored. If the ----CCCC 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. CCCCOOOONNNNTTTTRRRROOOOLLLL OOOOPPPPTTTTIIIIOOOONNNNSSSS Many of the control options are similar in function to their _t_a_r or _c_p_i_o equivalents. Sizes are specified in bytes. The scale factors MMMM, kkkk, or bbbb, 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. ----#### _s_t_r Use string _s_t_r as a control string for the built in debugging system. This option provides information about the internal workings of _b_r_u for the software maintainer or the merely curious. Some examples are given later. ----aaaa Do not reset the aaaacccccccceeeessssssss times of disk files that have been read while performing other actions. Normally _b_r_u restores the access and modification times of disk files after they have been read. Resetting the times prevents defeat of the mechanism used to track down and remove "dead" files that haven't been accessed in any meaningful Page 3 (printed 12/28/86) BBBBRRRRUUUU((((1111)))) UUUUNNNNIIIIXXXX 5555....0000 BBBBRRRRUUUU((((1111)))) way recently. ----bbbb _b_s_i_z_e Use _b_s_i_z_e as the archive input/output bbbbuuuuffffffffeeeerrrr 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 _b_s_i_z_e is not an even multiple of 2048 bytes, it will be rounded up. Normally this option is only required with the ----cccc mode since _b_r_u writes this information in the archive header block. If specified, _b_s_i_z_e overrides any existing default value (generally 20k), whether built in or read from the archive header. ----BBBB Useful in shell scripts where _b_r_u is run in the bbbbaaaacccckkkkggggrrrroooouuuunnnndddd with no operator present. Under these conditions, _b_r_u simply terminates with appropriate error messages and status, rather than attempting interaction with the terminal. ----CCCC Change the owner (cccchhhhoooowwwwnnnn) and group of each extracted file to the owner uid and group gid of the current user. Normally, _b_r_u 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 _b_r_u, including Root. (Under 4.2 BSD, the default group is that of the directory in which the file is created.) The ----CCCC 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 files. Use the ----ttttvvvv option to see the owner and group of files stored in the archive. ----ffff _p_a_t_h Use _p_a_t_h as the archive ffffiiiilllleeee instead of the default. If the _p_a_t_h is "-" then _b_r_u uses the standard input for archive reading or standard output for archive writing, as appropriate. ----FFFF FFFFaaaasssstttt mode. In fast mode, checksum computations and comparisons are disabled. This mode is useful when the output of one _b_r_u is piped to the input of another _b_r_u, 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 _b_r_u, such as automatic byte swapping, are not functional in fast mode. Page 4 (printed 12/28/86) BBBBRRRRUUUU((((1111)))) UUUUNNNNIIIIXXXX 5555....0000 BBBBRRRRUUUU((((1111)))) ----LLLL _s_t_r LLLLaaaabbbbeeeellll the archive with the specified string _s_t_r. _S_t_r is limited to 63 characters and is usually some meaningful reminder pertaining to the archive contents. ----llll Ignore unresolved lllliiiinnnnkkkkssss. Normally bru reports problems with unresolved links (both regular and symbolic links). This option suppresses all such complaints. ----mmmm Do not cross mmmmoooouuuunnnntttteeeedddd file system boundaries during expansion of explicitly named directories. This option applies only to directories named in _f_i_l_e_s. 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 ----cccc and ----eeee modes. ----pppp PPPPaaaassssssss over files in archive by reading rather than seeking. Normally _b_r_u will use random access capabilities if available. This option forces reading instead of seeks. ----RRRR RRRReeeemmmmooootttteeee files are to be eeeexxxxcccclllluuuuddddeeeedddd from the archive. If the system does not support remote filesystems, this option is ignored. ----ssss _m_s_i_z_e Use _m_s_i_z_e as the media ssssiiiizzzzeeee. The effective media ssssiiiizzzzeeee will be computed from _m_s_i_z_e since it must be integral multiple of the input/output buffer size (see the ----bbbb option). Normally this option is only required with the ----cccc mode since _b_r_u writes this information in the archive header block. If specified, _m_s_i_z_e overrides any existing default value, whether built in or read from the archive header. ----vvvv Enable vvvveeeerrrrbbbboooosssseeee mode. May be specified more than once, as ----vvvvvvvv, ----vvvvvvvvvvvv, or ----vvvvvvvvvvvvvvvv, to get even more verbosity. ----wwww WWWWaaaaiiiitttt for confirmation. _B_r_u will print the file name, the action to be taken, and wwwwaaaaiiiitttt for confirmation. Any response beginning with 'y' will cause the action to complete. Any other response will abort the action. FFFFIIIILLLLEEEE SSSSEEEELLLLEEEECCCCTTTTIIIIOOOONNNN OOOOPPPPTTTTIIIIOOOONNNNSSSS The file selection options control which files are selected for processing. Note that some options are only valid with specific modes. Page 5 (printed 12/28/86) BBBBRRRRUUUU((((1111)))) UUUUNNNNIIIIXXXX 5555....0000 BBBBRRRRUUUU((((1111)))) ----nnnn _d_a_t_e Select only files nnnneeeewwwweeeerrrr than _d_a_t_e. The _d_a_t_e 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 _d_a_t_e 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. ----oooo _u_s_e_r Select only files oooowwwwnnnneeeedddd by _u_s_e_r. _U_s_e_r 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). ----uuuu _f_l_a_g_s When used in conjunction with ----xxxx mode, causes files of type specified by _f_l_a_g_s to be uuuunnnnccccoooonnnnddddiiiittttiiiioooonnnnaaaallllllllyyyy selected regardless of modification times. Normally _b_r_u 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 vvvveeeerrrrbbbboooosssseeee mode level 2 (----vvvvvvvv) or higher is enabled. Possible characters for _f_l_a_g_s are: bbbb select block special files cccc select character special files dddd select directories llll select symbolic links pppp select fifos (named pipes) rrrr 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 Page 6 (printed 12/28/86) BBBBRRRRUUUU((((1111)))) UUUUNNNNIIIIXXXX 5555....0000 BBBBRRRRUUUU((((1111)))) currently impossible under 4.2 BSD to change access time, modification time, or the file mode of a symbolic link. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS Create (----cccc) a new archive of all files under "/usr/src", writing archive to file (----ffff) "/dev/rmt0" using multiple tapes with a maximum size (----ssss) of 30 megabytes per tape. bru -c -f /dev/rmt0 -s 30M /usr/src Create (----cccc) 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 (----nnnn) since 3 P.M. on 14-Jan-84. Then do a second pass to verify that there are no differences (----dddd) between the archive and current files. Each file is listed (----vvvv) as it is processed. bru -cvd -n 14-Jan-84,15:00:00 Archive all files owned (----oooo) 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 -) Extract (----xxxx) the regular file "/usr/guest/myfile" unconditionally (----uuuurrrr) from an archive on file (----ffff) "/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 (----xxxx) all C source files in "/usr/src/cmd" that have names beginning with characters 'a' through 'm'. Wait (----wwww) for confirmation before extracting each file. bru -xw '/usr/src/cmd/[a-m]*.c' Inspect (----iiii) a previously created archive on the default device, dumping the contents of the header block for inspection (----vvvvvvvvvvvv) and verifying internal consistency and data integrity of the archive. bru -ivvv Page 7 (printed 12/28/86) BBBBRRRRUUUU((((1111)))) UUUUNNNNIIIIXXXX 5555....0000 BBBBRRRRUUUU((((1111)))) Perform the same function as the last example except enable various features of the built in debugger (when linked in). The debug control string is a string of the form "-#::...", where each option is either a single flag character or a flag character followed by a comma separated list. Available flag characters are: 'd' enable debugging for list of keywords, 'f' limit debugging to list of function names, 'F' print source file name, 'L' print source file line numbers, 'n' print nesting depth, 'o' redirect output to listed file, 'p' print process name, 't' enable tracing. bru -ivvv -#t bru -ivvv -#d:t bru -ivvv -#d,ar_io,verify:F:L bru -ivvv -#d:f,ar_seek bru -ivvv -#d:o,trace.out:t:p Back up the entire root filesystem without crossing mounted (----mmmm) filesystem boundaries. The archive will be written to file (----ffff) "/dev/rmt0" using an I/O buffer size (----bbbb) of 10k bytes. A record of all files processed will be written to file "brulogfile" for future reference. cd / bru -cvm -f /dev/rmt0 -b 10k >brulogfile DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS 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. DDDDEEEEVVVVIIIICCCCEEEE TTTTAAAABBBBLLLLEEEE _B_r_u contains an internal table of known devices and their characteristics. This table is dynamically loaded from a data file specified by the environment variable BBBBRRRRUUUUTTTTAAAABBBB, or from ////eeeettttcccc////bbbbrrrruuuuttttaaaabbbb, or from an internal default description if neither of the preceding is found. SSSSIIIIGGGGNNNNAAAALLLL HHHHAAAANNNNDDDDLLLLIIIINNNNGGGG _B_r_u normally catches both interrupt (SIGINT) and quit (SIGQUIT). When interrupt is caught during archive creation or extraction, _b_r_u completes its work on the current file before cleaning up and exiting. This is the normal way of aborting _b_r_u. 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 Page 8 (printed 12/28/86) BBBBRRRRUUUU((((1111)))) UUUUNNNNIIIIXXXX 5555....0000 BBBBRRRRUUUU((((1111)))) signal during archive writing may leave the archive truncated. When either interrupt or quit is caught at any other time an immediate exit is taken. EEEERRRRRRRROOOORRRR RRRREEEECCCCOOOOVVVVEEEERRRRYYYY 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 _b_r_u'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. DDDDIIIIRRRREEEECCCCTTTTOOOORRRRIIIIEEEESSSS When creating non-incremental archives _b_r_u 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. WWWWIIIILLLLDDDDCCCCAAAARRRRDDDDSSSS When rrrreeeeaaaaddddiiiinnnngggg archives _b_r_u 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 particular, "/bin/a* /bin/b*" is equivalent to "/bin/[ab]*", but "/bin/!a* /bin/!b*" is equivalent to "/bin/*", nnnnooootttt "/bin/![ab]*". BBBBYYYYTTTTEEEE////WWWWOOOORRRRDDDD SSSSWWWWAAAAPPPPPPPPIIIINNNNGGGG While reading archives produced on other machines, _b_r_u automatically attempts to perform byte and/or word swapping as necessary. RRRREEEEMMMMOOOOTTTTEEEE TTTTAAAAPPPPEEEE DDDDRRRRIIIIVVVVEEEESSSS PPPPaaaaggggeeee 9999 ((((pppprrrriiiinnnntttteeeedddd 11112222////22228888////88886666)))) BBBBRRRRUUUU((((1111)))) UUUUNNNNIIIIXXXX 5555....0000 BBBBRRRRUUUU((((1111)))) On 4.2 BSD systems, and System V systems that support networking, _b_r_u allows the use of remote tape drives for the archive device (via the ----ffff option). A remote tape drive file name has the form _s_y_s_t_e_m[._u_s_e_r]:/dev/??? where _s_y_s_t_e_m is the remote system, the optional _u_s_e_r is the login name to use on the remote system if different from the current user's login name, and ////ddddeeeevvvv////???????????? 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 CCCCAAAAVVVVEEEEAAAATTTTSSSS section, below.) EEEEXXXXIIIITTTT CCCCOOOODDDDEEEESSSS _B_r_u always returns meaningful status as follows: 0 Normal exit, no errors or warnings. 1 Warnings (or interrupted). 2 Errors (or quit signal). SSSSEEEEEEEE AAAALLLLSSSSOOOO Under System V, see tar(1), cpio(1), volcopy(1M), finc(1M), frec(1M), ff(1M), filesave(1M). Under 4.2 BSD, see tar(1), dd(1), rsh(1), rmt(8), dump(8), restore(8), rdump(8), rrestore(8). AAAAUUUUTTTTHHHHOOOORRRR Fred Fish Ported from System V to 4.2 BSD by Arnold Robbins, at Georgia Tech UUUUNNNNIIIIXXXX SSSSYYYYSSSSTTTTEEEEMMMM IIIINNNNCCCCOOOOMMMMPPPPAAAATTTTIIIIBBBBIIIILLLLIIIITTTTIIIIEEEESSSS _B_r_u recognizes special file types that may be allowed on one type of UUUUnnnniiiixxxx system, but not on another. For instance, on a 4.2 BSD system, _b_r_u will extract fifos as plain files (mode 0666, as modified by the _u_m_a_s_k), and issue an appropriate error message. Usually, _b_r_u will issue two messages. The first message will be the more descriptive of the two. Under System V, when _b_r_u sees a symbolic link, it will check to see if the file to be linked to exists, and is not a directory. If so, it will attempt to make a hard link. If the hard link fails, _b_r_u will issue a warning. Pyramid corporation conditional symbolic links are also sup- ported. On a Pyramid, they are restored properly. On a 4.2 BSD system, _b_r_u will attempt a symbolic link for the Page 10 (printed 12/28/86) BBBBRRRRUUUU((((1111)))) UUUUNNNNIIIIXXXX 5555....0000 BBBBRRRRUUUU((((1111)))) file given in the UCB universe. Under System V, it will at- tempt a hard link for the file given in the ATT universe (with the same constraints as when attempting to restore regular symbolic links). Currently, the only different UUUUnnnniiiixxxx systems that _b_r_u fully understands are System V, 4.2 BSD, and Pyramid's OSx. CCCCAAAAVVVVEEEEAAAATTTTSSSS Pathnames are limited to 127 characters in length. This could become a chronic problem under 4.2 BSD. Implementation differences complicate the algorithms for au- tomatic detection of end of file on devices. The algorithms can be fooled, hence the ----ssss option. Special files moved to a machine other than their original host will generally be useless and possibly even dangerous. This goes double for symbolic 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 ----wwww option. In order to be able to efficiently archive needed direc- tories, _b_r_u builds an image of the directory tree for _f_i_l_e_s using dynamically allocated memory. Since there may be at most 5120 characters passed on the command line, it is very unlikely that _b_r_u 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 address space. Information about file linkages is also kept in memory. Some linkages may be lost if memory is exhausted. Since _b_r_u 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 ex- tracting files they would normally not have access to. There may be loopholes. Also note that anyone with physical or electronic access to an archive, and knowledge of the ar- chive structure, can recover any of its contents by writing their own file extraction program. Directories which have filesystems mounted on them will not be properly archived until the filesystem is unmounted. This is not generally a problem. Page 11 (printed 12/28/86) BBBBRRRRUUUU((((1111)))) UUUUNNNNIIIIXXXX 5555....0000 BBBBRRRRUUUU((((1111)))) Explicitly naming both a directory and one of its descen- dents will cause the descendent to be archived twice, unless they are on separate filesystems and the ----mmmm flag is used. Explicitly naming a file more than once is ineffective. When reading from the raw magnetic tape file (rmtxxx) _b_r_u automatically attempts to adjust the I/O buffer size to match that used to record the archive. Under certain cir- cumstances it may fail and require help via the ----bbbb option. The 4.2 BSD remote magnetic tape protocol, rmt(8), allows writing and reading of no more than 10K bytes, so ----bbbb10k must be specified when reading from or writing to a remote tape drive. Also, using remote tape drives can be slow. Page 12 (printed 12/28/86)