#man UASM

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 [ -nuv ] [ -i {nNyYrR} ] [ -m <src>=<dst> ] -z suffix ] [ path ] [ -P pass-phrase ] ...

DESCRIPTION

The uasm command is the default filesystem ASM (Application Specific Module). It is built into save(1m) and recover(1m). 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 basic modes: saving and recovering. 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.

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 ASM s supplied with NetWorker:

aes

The aes ASM uses a software encryption algorithm to encrypt file data. aes uses a considerable amount of CPU resources so its benefit may be limited on low-powered systems.

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. See the COMPRESSION section.

dmfasm

The dmfasm is used to backup and recover files that are managed by the SGI Data Migration Facility (DMF). On backup, offline files not recalled. On recover, offline and dual-state files are recovered as recallable offline files.

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 to 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 changing during a backup operation is not noteworthy.

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. If a file with null directive is specified as the save set to be backed up, an empty save set (typically shown in 'mminfo -v' query as '4 B' in size) is created in media index for information but the save set will not contain any recoverable data.

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. By 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. If a file with skip directive is specified as the save set to be backed up, an empty save set (typically shown in 'mminfo -v' query as '4 B' in size) is created in media index for information but the save set will not contain any recoverable data.

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 ASM s are not separate programs, but are contained within all ASM s. External ASM s are separate programs, and are invoked as needed. External ASM s provided with NetWorker are nsrmmdbasm and nsrindexasm. All other ASM s 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 ASM s traverse directory trees. The skip, null, and nullasm ASM s do not walk. Note that this does not mean that propagation of the directive can not be applied. The lack of walking means that e.g. all directories that match the specified skip pattern will be skipped completely rather than being walked - however, using +skip will still cause the skip pattern to be recursively applied to any directories that do not match the pattern. As an example, if you have a directory structure of tmp source source/tmp then a directive of skip: tmp will cause only directory tmp to be skipped, whereas +skip: tmp will cause tmp and source/tmp to both be skipped. In other words, the skip directive will still propagate through non-matching subdirectories when + is used, even though skip does not walk through matched directories.

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+1s 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 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 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, 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 ASM s are invoked by hand, these security checking rules do not apply.

OPTIONS

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

Either -s (saving) or -r (recovering) 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, consume the input save stream and perform basic sanity checks, but do not create any directories or files when recovering 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 save stream that can be handled by older NetWorker servers (see nsr_data(5)).

-p path

This string is prepended to the name of each file as it is output. This argument is used internally when an ASM executes an external ASM. path 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 that 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”. Note, since Windows platforms use the suffix to determine file type and therefore changing the suffix effectively changes the file, this option is ignored on Windows.

-P pass-phrase

Specifies an additional pass phrase to use when attempting to recover files backed up using the aes directive. By default the current datazone encryption key is tried as well as the key generated from the default pass phrase. Using this option causes uasm to generate an encryption key from the pass phrase and try it if the default and datazone pass phrase keys do not work. This option can be given multiple times.

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.

COMPRESSION

The compression algorithm for compressasm can be selected with the following options. These options cannot be specified on the command line, but are only possible in a directive. See nsr (5). -default

This option selects the default compression mode which is identical to invoking compressasm without any options. For this mode the level is ignored.

-gzip

compressasm will use zlib compression. This is the same algorithm as known from the gzip command and from .jar files. zlib is copyrighted (c) 1995-2010 by Jean-loup Gailly and Mark Adler. The home page is at http://zlib.net/.

-bzip2

Directs compressasm to use libbzip2 compression known from the bzip2 tool. This software is copyrighted (c) 1996-2010 by Julian R. Seward. The home page is at http://www.bzip.org/.

-level

This option specifies the compression level for zlib and libbzip2. level is an integral value. For zlib compression it is in the range [0..9] and the default (if omitted) is 6. For libbzip2 the range is [0..250] with a default of 0. Generally, the higher the level the better the compression rate.

Because compression is performed on each individual input buffer and not on the input file as a single entity, the resulting compression rate will be far from those achieved by gzip resp. bzip2. However, the larger each individual buffer, the better the achieved compression rate. By default, ASMs will use a buffer size of 64 KB. A test with an ASCII file showed that the compression rate of libbzip2 may be trippled if 256 KB blocks were used. So for higher compression rates it may be a good idea to increase the buffer size by setting the environment variable NSR_READ_SIZE to the desired buffer size (unit: bytes).

As mentioned earlier, the higher the desired compression rate, the more CPU resources are required. Furthermore, compression may take considerable amounts of time. Both factors may result in an increased backup time. Benefits of compression are lower network bandwidth and reduced allocation of backup storage.

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. EMC 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 disk's geometry to match that of 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(1m), nsrindexasm(1m), nsrck(1m), nsr_data(5), recover(1m), save(1m), scanner(1m), XDR(3N)