uasm(8)                                                                             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 [ -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:
       
       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  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 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.  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.  Ppath must be a properly  formatted  path
              are not crossed during walking.  Symbolic links are  never  fol-
              lowed, except in the case of rawasm.  1.0v
              
       -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
                             appending a dot, (€œ.€), and a suffix.  If a  con-
                             flicting  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 ALSO

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

NetWorker 8.0.1 		Dec 02, 12 			uasm(8)