NAME

uasm − NetWorker module for saving and recovering UNIX filesystem data

SYNOPSIS

uasm −s [−bednv] [−ix] [ −t time ] [ −f proto ] [ −p ppath ] path... 
uasm −r [−dnv] [ −i {nNyYrR} ] [ −m <src>=<dst> ] −z suffix ] [ path ]... 

DESCRIPTION

uasm is the default UNIX filesystem ASM (Application Specific Module).  It is built-in to save(8) and recover(8).  uasm may also be called directly in a manner similar to tar(1).  This description of uasm applies to all ASM’s.  For clarity, only uasm is mentioned in many of the descriptions in this man page. 

uasm has two modes, saving and recovering.  When saving, uasm will walk UNIX directory trees and generate a save stream, see nsr_data(5), on its stdout representing the files and organization of the directory tree.  When recovering, uasm reads an save stream on its stdin and creates the corresponding directories and files. 

While saving, uasm’s behavior may be controlled by directive files.  Directive files control how descendent directories are searched, which files are ignored, how the save stream is generated, and how to process subsequent directive files.  See nsr(5).  When walking a directory tree, symbolic links are never followed. 

ASM’s can recover save streams from current or earlier versions.  Older ASM’s may not be able to recover files generated by newer ASM’s. 

The following is a brief description of the ASM’s supplied with NetWorker:

skip The skip ASM skips saving files and directories and does not place the file name in the parent directory’s online index. 

null The null ASM skips saving files and directories, but leaves the file name in the parent directory’s online index. 

nullasm nullasm is an alternate name for the null ASM and is so named for backward compatibility with earlier releases where nullasm was a separate executable program instead of an internal ASM. 

holey The holey ASM handles holes or blocks of zeroes when saving files and preserves these holes when recovering.  On some systems file system interfaces can be used to find out file hole location information.  Otherwise, blocks of zeroes read from the file will be skipped.  Note that this ASM is normally automatically applied and need not be specified. 

always The always ASM always saves, independent of the file’s change time. 

logasm The logasm does not complain if a file changes during the save.  logasm can be used for “log” files and other similar files where a file changing during a save is not worth noting. 

mailasm The mailasm uses mail-style file locking and maintains a file’s access time, thus preserving most mail handlers’ “new mail has arrived” flag. 

atimeasm The atimeasm is used to save files without changing the file’s access time.  This functionality is a subset of mailasm’s.  On most systems, atimeasm uses the file mtime for selection and then resets the file atime after the backup (which changes the file ctime).  On other systems that support interfaces for maintaining the file atime without changing the file ctime, atimeasm has not effect since the file atime is normally preserved. 

swapasm The swapasm doesn’t save any actual file data and on recovery recreates a zero-filled file of the correct size.  This is used on systems where the swapping device can be a Unix file, and it is important to recover the swap file with the correct size, but the contents of the swap file don’t need to be saved. 

xlateasm The xlateasm translates the file data in a way so that data saved is not immediately recognizable by humans. 

compressasm
The compressasm uses the Lempel-Ziv compression algorithm to compress file data.  Directories are not compressed. 

nsrmmdbasm
The nsrmmdbasm is used to process NetWorker’s media index.  Normally, nsrmmdbasm is invoked automatically by savegroup and recoverindex, and should not be used in NetWorker directives. 

nsrindexasm
The nsrindexasm is used to process NetWorker’s client file indexes.  Like nsrmmdbasm, nsrindexasm is invoked automatically by savegroup and recoverindex, and should not be used in NetWorker directives. 

Internal ASM’s are not separate programs, but are contained within all ASM’s.  External ASM’s are separate programs, and are invoked as needed.  The only external ASM’s provided with NetWorker are nsrmmdbasm and nsrindexasm.  All other ASM’s listed above are internal. 

For security reasons, external ASM names must end in asm and be located in the origin directory, which is the same directory as the originally invoked program (typically save or recover).  On some system architectures, other directories relative to the origin will be searched if an ASM cannot be located in the origin directory. 

Walking ASM’s traverse directory trees.  The skip, null, and nullasm ASM’s do not walk. 

The internal ASM’s described here are modes, and a number of different internal ASM’s may be applied at the same time.  When an external ASM is needed to process a file, the new ASM is invoked and generates the save stream.  When a filtering ASM is traversing a directory tree and invokes another ASM, that ASM’s save stream is processed by the filtering ASM.  Hence, while using compressasm to save a directory tree, the mailasm can still be used to process the mail files correctly.  Note that once different modes are set, the only way to turn them off is to explicitly match an ASM directive for uasm. 

Auto-applied ASM’s are used under certain conditions, and do not need to be specifically mentioned in a directive file.  For example, when a large file only has a small number of disk blocks allocated, the holey ASM is automatically invoked to process the file.  Auto-applied ASM’s are not used when a file’s name matches an explicit directive. 

When used in conjunction with recover, all standard ASM’s support security at recovery time.  If a file is saved with an access control list (ACL), then only the owner of the file or root may recover the file.  For files that don’t contain an ACL, the standard Unix mode bits are used to determine who may recover a file, except that the file owner, root, and users in group operator may always recover the file.  Note that when ASM’s are invoked by hand, these security checking rules do not apply. 

OPTIONS

All ASM’s accept the options described below.  These options are generally referred to as the standard-asm-arguments.  ASM’s may also have additional options.  A particular ASM’s additional options must be capital letters. 

Either −s (saving) or −r (recovering) must be specified, and must precede any other options.  When saving, at least one path argument must be specified.  Path may be either a directory or file name. 

The following options are valid when saving or recovering:

−n Perform a dry run.  When saving, do everything except produce the save stream.  When recovering, consume the input save stream, but do not actually create any directories or files. 

−v Turn on verbose mode.  The current ASM, its arguments, and the file it is processing are displayed.  When a filtering ASM operating in filtering mode (that is, processing another ASM’s save stream) modifies the stream, its name, arguments and the current file are displayed within square brackets. 

When saving, the following options may also be used:

−b Produce a byte count.  This option is like the −n option, but byte count mode will estimate the amount of data that would be produced instead of actually reading file data so it is faster but less accurate than the −n option.  Byte count mode produces three numbers: the number of records, i.e., files and directories; the number of bytes of header information; and the approximate number of bytes of file data.  Byte count mode does not produce a save stream so its output cannot be used as input to another asm in recover mode. 

−e Do not generate the final “end of save stream” boolean.  This flag should only be used when an ASM invokes an external ASM and as an optimization chooses not to consume the generated save stream itself. 

−i Ignore all save directives from .nsr directive files found in the directory tree. 

−f proto
Specifies the location of a .nsr directive file to interpret before processing any files, see nsr(5).  Within the directive file specified by proto, <<path>> directives must resolve to files within the directory tree being processed, otherwise their subsequent directives will be ignored. 

−p ppath
This string is prepended to each file’s name as it is output.  This argument is used internally when one ASM exec’s another external ASM. Ppath must be a properly formatted path which is either the current working directory or a trailing component of the current working directory. 

−t date
The date (in getdate(3) format) after which files must have been modified before they will be saved. 

−x Cross filesystem boundaries.  Normally, filesystem boundaries are not crossed during walking.  Symbolic links are never followed. 

When recovering, the following options may also be used:

−i {nNyYrR}
Specifies the initial default overwrite response.  Only one letter may be used.  When the name of the file being recovered conflicts with an existing file, the user is prompted for overwrite permission.  The default response, selected by just pressing Return, is displayed within square brackets.  Unless otherwise specified with the −i option, ‘n’ is the initial default overwrite response.  Each time a response other than the default is selected, the new response becomes the default.  When either N, R, or Y is specified, no prompting is done (except when auto-renaming files that already end with the rename suffix) and each subsequent conflict is resolved as if the corresponding lower case letter had been selected. 

The valid overwrite responses and their meanings are:

n Do not recover the current file. 

N Do not recover any files with conflicting names. 

y Overwrite the existing file with the recovered file. 

Y Overwrite files with conflicting names. 

r Rename the conflicting file.  A dot, “.”, and a suffix are appended to the recovered file’s name.  If a conflict still exists, the user will be prompted again. 

R Automatically renames conflicting files by appending a dot, “.”, and a suffix.  If a conflicting file name already ends in a “.” suffix, the user will be prompted to avoid potential auto rename looping conditions. 

−m src=dst
This option will map the file names that will be created.  Any files that start exactly with src will be mapped to have the path of dst replacing the leading src component of the path name.  This option is useful if you which to perform relocation of the recovered files that were saved using absolute pathnames into an alternate directory (e.g., −m /usr/etc=.). 

−z suffix
Specifies the suffix to append when renaming conflicting files.  The default suffix is “R”. 

path Used to restrict the files being recovered.  Only files with prefixes matching path will be recovered.  This checking is performed before any potential name mapping is done with the −m specification.  When path is not specified, no checking is done. 

EXAMPLES

Copying files

To copy all of the files in the current directory to target_dir, use:

uasm −s . | (cd target_dir; uasm −rv)

This will preserve ownership, time, and the other Unix attributes.  Only the data in holey files will be copied, the holes will not be. 

Copying a file tree to an archive directory

To copy the file tree under the directory here to archive and overwrite any files with conflicting names, use:

cd here
uasm −s . | (cd archive; uasm −r −iY)

Note that we cd to here first and give the first uasm doing the save a relative path so that the second uasm doing the recover will recreate the file tree under archive.  Another way to get the same effect is to use the −m option on the second uasm doing the recover to explicitly map the path names. 

uasm −s here | uasm −r −iY −m here=archive

FILES

.nsr Save directive files located throughout the filesystem. 

SEE ALSO

nsr(5), nsr_directive(5), nsrindexasm(8), nsrmmdbasm(8), nsr_data(5), recover(8), save(8), scanner(8), XDR(3N). 

NetWorker 4.1.2  —  Last change: May 1995