UASM(8)

NAME
uasm - NetWorker module for saving and recovering UNIX filesystem data

SYNOPSIS
uasm -s [ -benouv ] [ -ix ] [ -t time ] [ -f proto ]
[ -p path ] path...
uasm -r [ -dnuv ] [ -i {nNyYrR} ] [ -m <src>=<dst> ] -z suffix ] [ path ]...
uasm -c [-nv] [ path ]...

DESCRIPTION
The uasm command is the default filesystem ASM (Application Specific Module). It is built into 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 ASMs. For clarity, only uasm is mentioned in many of the descriptions in this man page.

uasm has three basic modes: saving, recovering, and comparing. When saving, uasm will browse directory trees and generate a save stream (see nsr_data(5)), to the associated stdout file representing the file and directory organization. When recovering, uasm reads a save stream from the associated stdin file and creates the corresponding directories and files. When comparing, uasm reads a save stream from its stdin file and compares the save stream with the files already located in the file system.

During backup sessions, the behavior of uasm can be controlled by directives. Directives control how descendent directories are searched, which files are ignored, how the save stream is generated, and how subsequent directive files are processed. (See nsr(5)). When browsing a directory tree, symbolic links are never followed, except in the case of rawasm.

ASMs can recover save streams from current or earlier versions of NetWorker. Note: older ASMs may not be able to recover files generated by newer ASMs.

The following list provides a brief description of the ASMs supplied with NetWorker:

always
    The always ASM always performs a back up of a file, independent of the change time of the file.

atimeasm
    The atimeasm is used to backup files without changing the access time of the file. This functionality is a subset of mailasm. 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 systems that support interfaces for maintaining the file atime without changing the file ctime, atimeasm has no effect, since the file atime is normally preserved.

compressasm
    The compressasm uses a software compression algorithm to compress file data. This ASM does not compress directories. The amount of compression achieved is data-dependent. compressasm uses considerable amounts of CPU resources, so its benefits may be limited on low-powered systems.

holey
    The holey ASM handles holes or blocks of zeros when backing up files and preserves these holes during recovery. On some filesystems interfaces can be used to find out the location of file hole information. Otherwise, blocks of zeros that are read from the file are skipped. This ASM is normally applied automatically and does not need not be specified.

logasm
    The logasm enables file changes during backup sessions. logasm can be used for “log” files and other similar files where a file changes during a backup operation is not worth noting.

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

mtimeasm
    The mtimeasm is used to backup files using the file mtime for file selection instead of the file ctime.

nsrindexasm
    The nsrindexasm is used to recover from NetWorker file index backups performed prior to Version 6. During recovery from these older index backups, nsrindexasm is invoked automatically by nsrck and mmrecov.

nsrmmdbasm
    The nsrmmdbasm is used to process NetWorker's media index. Normally, nsrmmdbasm is invoked automatically by savegrp and mmrecov, and should not be used in NetWorker directives.

null
    The null ASM does not back up the specified files and directories, but keeps the file name in the online index of the parent directory.

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

posixcrcasm
    The posixcrcasm is used to calculate a 32-bit CRC for a file during a backup. This CRC is stored along with the file and is verified when the file is restored; no verification occurs during the backup itself. Using this ASM it is possible to validate a file at restore time, but it does not provide a way to correct any detected errors.

rawasm
    The rawasm is used to back up /dev entries (for example, block- and character-special files) and their associated raw disk partition data. On some systems, /dev entries are actually symbolic links to device specific names. Unlike other ASMs, rawasm follows symlinks, allowing the shorter /dev name to be configured. When recovering, rawasm requires that the filesystem node for the raw device exist prior to the recovery. This protects against the recovery of a /dev entry and the overwriting of data on a reconfigured disk. You can create the /dev entry, having it refer to a different raw partition, and force an overwrite if desired. If you create the /dev entry as a symbolic link, the data is recovered to the target of the symbolic link. Precautions should be taken when using rawasm, see the CAVEATS section.

skip
    The skip ASM does not back up the specified files and directories, and does not place the filename in the online index of the parent directory.

swapasm
    The swapasm does not backup actual file data, but recreates a zero-filled file of the correct size on recovery. This ASM is used on systems where the swapping device is a swap file that must be recovered with the correct size, but the contents of the swap file are not important and do not need to be backed up.

xlateasm
    The xlateasm translates file data so that data backed up is not immediately recognizable.

Internal ASMs are not separate programs, but are contained within all ASMs. External ASMs are separate programs, and are invoked as needed. External ASMs provided with NetWorker are nsrmmdbasm and nsrindexasm. All other ASMs previously listed 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). In some system architectures, other directories relative to the origin will be searched if an ASM cannot be located in the origin directory.

Walking ASMs traverse directory trees. The skip, null, and nullasm ASMs do not walk.

The internal ASMs described here are modes, and a number of different internal ASMs 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 ASMs save stream is processed by the filtering ASM. Hence, while using compressasm to backup a directory, 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 ASMs 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 ASMs are not used when a file name matches an explicit directive.

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

OPTIONS
All ASMs accept the options described in this section. These options are generally referred to as the standard-asm-arguments. ASMs may also have additional options, which must be capital letters.

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

The following options are valid for all modes:

-n  Performs a dry run. When backing up, browse the file system, create the save stream, but do not attempt to open any files. When recovering or comparing, consume the input save stream and perform basic sanity checks, but do not create any directories or files when recovering or comparing file data.

-u  This option makes the ASM stop when an error that would normally cause a warning occurs. This can be useful if you are recovering to a file system that may not have enough disk space or you are performing a save and you want any warnings to stop the save. If you use this option with uasm on recovery, it will stop if it runs out of disk space. Without this option, uasm will continue to try to recover each file until it has processed the entire save stream.

-v  Turns on verbose mode. The current ASM, its arguments, and the file being processed are displayed. When a filtering ASM operating in filtering mode (processing the save stream of another ASM) 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  Produces a byte count. This option is similar to the -n option, but byte count mode will estimate the amount of data that would be produced instead of actually reading file data. (It is faster but less accurate than the -n option.) Byte count mode produces three numbers: the number of records (for example, 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; its output cannot be used as input to another ASM in recover mode.

-e  Do not generate the final "end of save stream" boolean string. 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.

-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.

-i  Ignores all save directives from .nsr directive files found in the directory tree.

-o  Produces a (see nsr_data(5)) save stream that can be handled by older NetWorker servers.

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

-t date
    The date (in nsr_getdate(3) format) after which files were modified will be backed up.

-x  Cross filesystem boundaries. Normally, filesystem boundaries are not crossed during walking. Symbolic links are never followed, except in the case of rawasm. 1.0v

When recovering, the following options may also be used:

-i {nNyYrR}
    Specifies the initial default overwrite response. Only one letter can 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 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, there is no prompting (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 name of the recovered file. 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 is prompted to avoid potential auto rename looping condition.

-m src=dst
    This option maps the file names that are 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 for the relocation of recovered files that were backed up using absolute pathnames into an alternate directory (for example, -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 using the -m specification. When path is not specified, no checking is done.

CAVEATS
Raw partitions are often used to store active DBMS data. If your raw partition contains data managed and updated by an active DBMS product, rawasm alone will not give a consistent backup. The database must not be updating the data in an uncontrolled fashion while rawasm saves or recovers data on the partition. The partition must be offline, the database manager shutdown, or the partition placed in an appropriate state for backup. Legato has products to assist with online database backup. Similarly if rawasm is used to save a partition containing a Unix filesystem, the filesystem must be unmounted or mounted read-only to obtain a consistent backup.

Ideally, recovery of a raw partition should take place on a system configured with the same disk environment and same size partitions as the system which performed the backup. If the new partition is smaller than the original partition, the recovery will not complete successfully. If the new partition is larger than the original partition, only the amount of data originally saved will be recovered.

If the partition backed up includes the disk label - the label often contains the disk geometry - recovering this partition to a new disk also recovers the label, changing the new disks geometry to match the original disk. Similarly, if a Unix filesystem partition is backed up using rawasm, recovering the partition resets all information on the partition, including timestamps concerning mount times (if applicable).

Since rawasm does not discover the size of the partition it backs up until the backup is completed, the estimated size reported on recovery is not accurate.

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 preserves ownership, time, and the other Unix attributes. Only the data in holey files is copied; the holes are not copied.

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)
Change directory (cd) to here first and give the first uasm determining the save a relative path so that the second uasm performing the recover will recreate the file tree under archive.

Another way to achieve the same result is to use the -m option on the second uasm performing 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), nsrmmdbasm(8), nsrindexasm(8), nsrck(8), nsr_data(5), recover(8), save(8), scanner(8), XDR(3N).