.\" $Id: nsr.5,v 6.4 2000/06/17 05:47:01 msevy Exp $ Copyright (c) 2000, Legato Systems Incorporated"
.\" Copyright (c) 2000 Legato Systems, Incorporated.
.\" All rights reserved.
.TH NSR 5 "Aug 23, 06" "StorEdge EBS 7.3.2"
.SH NAME
nsr \- Sun StorEdge EBS directive file format
.SH DESCRIPTION
This man page describes the format of
.B .nsr
directive files.
These files are interpreted by
.BR save (8)
and Application Specific Module (\s-1ASM\s0) programs,
during Sun StorEdge EBS backup processes.
This format is also used in the
.I directive
attribute of the
.BR nsr_directive (5)
resource.
.PP
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 \s-1ASM\s0 information
required to recover that file is also backed-up.
This enables
.BR recover (8),
or any
.SM ASM
directly invoked, to recover a file correctly,
even if the current directives have changed since the file was backed-up.
See
.BR uasm (8)
for a general description of the various \s-1ASM\s0s.
.PP
The
.B .nsr
directive file in each directory is parsed
before anything in that directory is backed up, unless Sun StorEdge EBS is being run in 
.I ignore
mode.
Each line of a
.B .nsr
directive file, and each line of the 
.B directive
attribute, contains one directive.
Any text after a "\fB#\fR" character until the end of the
line is treated as a comment and discarded.
Directives appear in one of three distinct forms:
.PP
.RS
.nf
[\fB+\fP] \s-1\fIASM\fP\s0 [\fIargs\fP ...] \fB:\fP \fIpattern\fP ...
\fIsave environment\fP
\fB<< \fIdir\fB >>\fR
.fi
.RE
.PP
The three forms are referred to as
.SM ASM
specifications,
.I save environment
directives,
and \fB<< \fIdir\fB >>\fR directives, respectively.
.sp
.PP
Use
.SM ASM
specifications (name and any arguments)
to specify how files or directories with a matching
.I pattern
are backed-up.
When a
.I pattern
matches a directory, the specified
.SM ASM
is responsible for handling the directory
and its contents.
Any
.I pattern
or 
.SM ASM
arguments requiring special control or white space
characters should be quoted using double quotes (\fB"\fP).
.PP
A colon (\fB:\fP) is used as the separator between the
.SM ASM
specification (and any arguments) and the
.I pattern
specification list.
The
.I pattern
list for each
.SM ASM
specification consists of simple file names or patterns.
The
.I pattern
cannot be "\fB..\fP" and must not contain any "\fB/\fP" characters
(all names must be within the current directory).
The string "\fB.\fP" can be used to match the current directory.
Standard
.BR sh (1)
file pattern matching (*, [...], [!...], [x-y], ?)
can be used to match file names.
If a "\fB+\fP" precedes the
.SM ASM
name, then the directive is propagated to subdirectories.
When a directory is first visited, it is searched for a
.B .nsr
file.
If one is found, it is then read.
Each
.B .nsr
file is only read once.
When starting a save at a directory below
.BR / ,
any
.B .nsr
files on the normalized path of the current working directory
are read before any files are saved to catalog any propagated
directives.
.PP
The following algorithm is used to match files to the appropriate
.SM ASM
specification.
First the
.B .nsr
file in the current directory (if any)
is scanned from top to bottom for an
.SM ASM
specification without a leading "+" whose 
.I pattern
matches the file name.
If no match is found, then the
.B .nsr
in the current directory is re-scanned for an
.SM ASM
specification with a leading "+" whose
.I pattern
matches the file name (for clarity, we recommend placing
all propagating ("+") directives after all the non-propagating
directives in a
.B .nsr
file).
If no match is found, then the
.B .nsr
file found in the "\fB..\fP" directory (if any) is scanned
from top to bottom looking for a match with an
.SM ASM
specification that has a leading \fB+\fP.
This process continues until the
.B .nsr
file in the "\fB/\fP" directory (if any) is scanned.
If no match is found
(or a match is found with an
.SM ASM
specification
whose name is the same as the currently running \s-1ASM\s0),
then the currently running
.SM ASM
will handle the save of the file.
.sp
.PP
Use
.I save environment
directives to change how
.SM ASM
specifications and future
.B .nsr
files are used.
The
.I save environment
directives do not take any file patterns.
They affect the currently running
.SM ASM
and subsequent \s-1ASM\s0s invoked below this directory.
There are three different possible
.I save environment
directives that can be used:
.TP 6
.B forget
Forget all inherited directives (those starting with
a "\fB+\fR" in parent directories).
.TP
.B ignore
Ignore subsequent
.B .nsr
files found in descendent directories.
.TP
.B allow 
Allow
.B .nsr
file interpretation in descendent directories.
.sp
.PP
The \fB<< \fIdir\fB >>\fR directive can be used
to specify a directory where subsequent
.SM ASM 
specifications
from the current
.B .nsr
file should be applied.
This directive is intended to be used to consolidate the contents of several
.B .nsr
files to a single location or directory.
The
.I dir
portion of this directive must resolve to a valid directory at or below
the directory containing this directive or subsequent
.SM ASM
specifications will be ignored.
Relative path names should be used for file names to ensure the interpretation 
of subsequent
.SM ASM
directives is consistent, even if a directory
is mounted in a different absolute part of the filesystem.
.PP
There
.B must
be a \fB<< \fIdir\fB >>\fR as the first directive in a directive
file used in conjunction with the \fB\-f\fP option to
.BR save (8),
.BR savefs (8)
or with an
.SM ASM
program.
Also, when \fB<< \fIdir\fB >>\fR 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
.B "directive"
attribute of the
.BR "NSR directive"
resource (see
.BR nsr_directive (5)).
.PP
When a \fB<< \fIdir\fB >>\fR directive is used,
subsequent directives are parsed and logged for later use.
When a directory specified by
.I dir
is opened, any 
.I save environment
directives specified for that directory (for example,
.BR allow ,
.BR ignore ,
and
.BR forget )
are processed first.
If the
.SM ASM
is not currently ignoring
.B .nsr
files and a local
.B .nsr
file exists, the file is read and processed.
Finally, any of the non
.I save environment
directives specified for that directory
are handled as if they where appended to the end of a
.B .nsr
file in that directory.
If multiple \fB<< \fIdir\fB >>\fR
specifications resolve to the same directory,
then the corresponding save directives are
handled logically in "last seen first" order.
.SH EXAMPLES
Having a
.I /usr/src/.nsr
file containing:
.RS
.nf
\fR\s10+skip: errs *.o
+compressasm: .\fP\s0
.fi
.ps
.RE
will cause all files (or directories) located in the
.I /usr/src
directory named
.B errs
or
.B *.o
(and anything contained within them) to be skipped.
In addition, all other files contained in the
.I /usr/src
directory will be compressed during save and will be
set up for automatic decompression on recover.
.PP
Having a
.I /var/.nsr
file containing:
.RS
.nf
\fR\s10compressasm: adm .nsr
null: * .?*\fP\s0
.fi
.ps
.RE
causes all files (or directories) and their contents located within the
.I /var
directory and anything contained within them (except for those
files located in the
.I /var/adm
directory and the
.B .nsr
file itself) to be skipped, although all the names in the directory would
be backed-up.
In addition, since
.B compressasm
is a
.I searching
directive (see
.BR uasm (8)),
the files contained within the
.I /var/adm
directory will be compressed during backup and will be
set up for automatic decompression on recover.
.PP
The following is an example of using the
.B /.nsr
file as a master save directive file for the entire
filesystem by using \fB<< \fIdir\fB >>\fR directives
to consolidate the various
.SM ASM
save directives to a single location:
.RS
.nf
\fR\s10
# Master Sun StorEdge EBS 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. Sun StorEdge EBS
# 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
\fP\s0
.fi
.RE
.SH FILES
.TP
.B .nsr
save directive file in each directory
.SH SEE ALSO
.na
.hy 0
.BR sh (1),
.BR nsr_directive (5),
.BR nsrindexasm (8),
.BR nsrmmdbasm (8),
.BR recover (8),
.BR save (8),
.BR savefs (8),
.BR uasm (8).
.hy 14
.ad