NSR(5)

NAME
nsr - NetWorker directive file format

DESCRIPTION
This man page describes the format of .nsr directive files. These files are interpreted by save(8) and Application Specific Module (ASM) programs, during NetWorker backup processes. This format is also used in the directive attribute of the nsr_directive(5) resource.

Directives control how particular files are to be backed-up, how descendent directories are searched, and how subsequent directives are processed. For each file backed-up, any ASM information required to recover that file is also backed-up. This enables recover(8), or any ASM directly invoked, to recover a file correctly, even if the current directives have changed since the file was backed-up. See uasm(8) for a general description of the various ASMs.

The .nsr directive file in each directory is parsed before anything in that directory is backed up, unless NetWorker is being run in ignore mode. Each line of a .nsr directive file, and each line of the directive attribute, contains one directive. Any text after a "#" character until the end of the line is treated as a comment and discarded. Directives appear in one of three distinct forms:

    [+] ASM [args ...] : pattern ...
    save environment
    << dir >>

The three forms are referred to as ASM specifications, save environment directives, and << dir >> directives, respectively.

Use ASM specifications (name and any arguments) to specify how files or directories with a matching pattern are backed-up. When a pattern matches a directory, the specified ASM is responsible for handling the directory and its contents. Any pattern or ASM arguments requiring special control or white space characters should be quoted using double quotes (").

A colon (:) is used as the separator between the ASM specification (and any arguments) and the pattern specification list. The pattern list for each ASM specification consists of simple file names or patterns. The pattern cannot be ".." and must not contain any "/" characters (all names must be within the current directory). The string "." can be used to match the current directory. Standard sh(1) file pattern matching (*, [...], [!...], [x-y], ?) can be used to match file names. If a "+" precedes the ASM name, then the directive is propagated to subdirectories. When a directory is first visited, it is searched for a .nsr file. If one is found, it is then read. Each .nsr file is only read once. When starting a save at a directory below /, any .nsr files on the normalized path of the current working directory are read before any files are saved to catalog any propagated directives.

The following algorithm is used to match files to the appropriate ASM specification. First the .nsr file in the current directory (if any) is scanned from top to bottom for an ASM specification without a leading "+" whose pattern matches the file name. If no match is found, then the .nsr in the current directory is re-scanned for an ASM specification with a leading "+" whose pattern matches the file name (for clarity, we recommend placing all propagating ("+") directives after all the non-propagating directives in a .nsr file). If no match is found, then the .nsr file found in the ".." directory (if any) is scanned from top to bottom looking for a match with an ASM specification that has a leading +. This process continues until the .nsr file in the "/" directory (if any) is scanned. If no match is found (or a match is found with an ASM specification whose name is the same as the currently running ASM), then the currently running ASM will handle the save of the file.

Use save environment directives to change how ASM specifications and future .nsr files are used. The save environment directives do not take any file patterns. They affect the currently running ASM and subsequent ASMs invoked below this directory. There are three different possible save environment directives that can be used:

forget
    Forget all inherited directives (those starting with a "+" in parent directories).

ignore
    Ignore subsequent .nsr files found in descendent directories.

allow
    Allow .nsr file interpretation in descendent directories.

The << dir >> directive can be used to specify a directory where subsequent ASM specifications from the current .nsr file should be applied. This directive is intended to be used to consolidate the contents of several .nsr files to a single location or directory. The dir portion of this directive must resolve to a valid directory at or below the directory containing this directive or subsequent ASM specifications will be ignored. Relative path names should be used for file names to ensure the interpretation of subsequent ASM directives is consistent, even if a directory is mounted in a different absolute part of the filesystem.

There must be a << dir >> as the first directive in a directive file used in conjunction with the -f option to save(8), savefs(8) or with an ASM program. Also, when << dir >> directives are used in this manner, whether first or later in the file, absolute path names should be used to ensure appropriate interpretation. Absolute path names should also be used for each directory specified within the directive attribute of the NSR directive resource (see nsr_directive(5)).

When a << dir >> directive is used, subsequent directives are parsed and logged for later use. When a directory specified by dir is opened, any save environment directives specified for that directory (for example, allow, ignore, and forget) are processed first. If the ASM is not currently ignoring .nsr files and a local .nsr file exists, the file is read and processed. Finally, any of the non save environment directives specified for that directory are handled as if they where appended to the end of a .nsr file in that directory. If multiple << dir >> specifications resolve to the same directory, then the corresponding save directives are handled logically in "last seen first" order.

EXAMPLES
Having a /usr/src/.nsr file containing:
    +skip: errs *.o
    +compressasm: .
will cause all files (or directories) located in the /usr/src directory named errs or *.o (and anything contained within them) to be skipped. In addition, all other files contained in the /usr/src directory will be compressed during save and will be set up for automatic decompression on recover.

Having a /var/.nsr file containing:
    compressasm: adm .nsr
    null: * .?*
causes all files (or directories) and their contents located within the /var directory and anything contained within them (except for those files located in the /var/adm directory and the .nsr file itself) to be skipped, although all the names in the directory would be backed-up. In addition, since compressasm is a searching directive (see uasm(8)), the files contained within the /var/adm directory will be compressed during backup and will be set up for automatic decompression on recover.

The following is an example of using the /.nsr file as a master save directive file for the entire filesystem by using << dir >> directives to consolidate the various ASM save directives to a single location:

    # Master NetWorker directive file for this machine
    << ./ >>
    # /mnt and /a are used for temporary fs mounting
    # and need not be saved
    	skip: mnt a
    	+skip: core errs dead.letter *% *~
    # Don't bother saving anything within /tmp
    << ./tmp >>
    	skip: .?* *
    << ./export/swap >>
    	swapasm: *
    # Translate all mailboxes. Also, use mailasm to save each
    # mail file to maintain mail file locking conventions and
    # to preserve the last file access time.
    << ./usr/spool/mail >>
    	xlateasm: .
     	mailasm: *
    # Allow .nsr files to be interpreted in /nsr, even if we
    # are currently ignoring .nsr files. NetWorker
    # applications (such as nsrindexd) set up their own private
    # .nsr files which save index files more intelligently.
    << ./nsr >>
    	allow
    # We can rebuild any .o files in /usr/src
    # from sources except those in /usr/src/sys.
    << ./usr/src >>
    	+skip: *.o
    << ./usr/src/sys >>
    	forget

FILES

.nsr
    save directive file in each directory

SEE ALSO
sh(1), nsr_directive(5), nsrindexasm(8), nsrmmdbasm(8), recover(8), save(8), savefs(8), uasm(8).