UASM(8)UASM(8)NAMEuasm - NetWorker module for saving and recovering UNIX filesystem data
SYNOPSISuasm-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(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 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 Net‐
Worker. 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:
aesasm
The aesasm uses a software encryption algorithm to encrypt file
data. aesasm 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 com‐
press 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.
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 automat‐
ically 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 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. Nor‐
mally, nsrmmdbasm is invoked automatically by savegrp and mmre‐
cov, and should not be used in NetWorker directives.
null
The null ASM does not back up the specified files and directo‐
ries, 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 recover‐
able data.
nullasm
nullasm is an alternate name for the null ASM, named for back‐
ward 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 dur‐
ing the backup itself. Using this ASM it is possible to vali‐
date 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 par‐
tition data. On some systems, /dev entries are actually sym‐
bolic links to device specific names. Unlike other ASMs, rawasm
follows symlinks, allowing the shorter /dev name to be config‐
ured. 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. Precau‐
tions should be taken when using rawasm, see the CAVEATS sec‐
tion.
skip
The skip ASM does not back up the specified files and directo‐
ries, 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 recover‐
able 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 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 architec‐
tures, 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. 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 com‐
pletely 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 directo‐
ries.
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 filter‐
ing 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 secu‐
rity 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) 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 recover‐
ing 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 oper‐
ating 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 informa‐
tion, 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 out‐
put. This argument is used internally when one ASM executes
another external ASM. path must be a properly formatted path
that is either the current working directory or a trailing com‐
ponent of the current working directory.
-t date
The date (in nsr_getdate(3) format) after which files were modi‐
fied will be backed up.
-x Cross filesystem boundaries. Normally, filesystem boundaries
are not crossed during walking. Symbolic links are never fol‐
lowed, 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 let‐
ter can be used. When the name of the file being recovered con‐
flicts 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 over‐
write 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 append‐
ing 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”.
-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 gen‐
erated 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 per‐
formed 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. 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 con‐
figured 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 success‐
fully. 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 ALSOnsr(5), nsr_directive(5), nsrmmdbasm(8), nsrindexasm(8), nsrck(8),
nsr_data(5), recover(8), save(8), scanner(8), XDR(3N).
NetWorker 7.3.2 Aug 23, 06 UASM(8)
