.\"
.\" $Id: nsr_resource.5,v 1.1.64.3 2006/04/26 18:52:18 castrv Exp $ Copyright (c) 2005 EMC Corporation.
.\"

.\"
.\" Copyright (c) 2005 EMC Corporation.
.\"
.\" All rights reserved.  This is an UNPUBLISHED work, and
.\" comprises proprietary and confidential information of EMC.
.\" Unauthorized use, disclosure, and distribution are strictly
.\" prohibited.  Use, duplication, or disclosure of the software
.\" and documentation by the U.S. Government is subject to
.\" restrictions set forth in a license agreement between the
.\" Government and EMC or other written agreement specifying
.\" the Government's rights to use the software and any applicable
.\" FAR provisions, such as FAR 52.227-19.
.\"
.TH NSR_RESOURCE 5 "Aug 23, 06" "StorEdge EBS 7.3.2"
.SH NAME
nsr_resource \- Sun StorEdge EBS resource format
.SH SYNOPSIS
.I resource
::=
.I "attribute list"
.I <blank line>
.br
.I "attribute list"
::=
.I "attribute"
[
.BI ; " attribute"
]*
.br
.I "attribute"
::=
.I name
[
.BI : " value"
[
.BI , " value"
]* ]
.br
.I "name, value"
::=
.I "<printable string>"
.SH DESCRIPTION
The Sun StorEdge EBS system uses files containing
.I resources
to describe itself and its clients.  Each resource represents a
component of the Sun StorEdge EBS system that might need administration.
Devices, schedules, and clients are examples of Sun StorEdge EBS resources.
The system administrator manipulates resources to control the
Sun StorEdge EBS system.  The file and the resources in them are accessible
through
.B Sun StorEdge EBS Management Console
and
.BR nsradmin (8)
programs.
They can also be viewed with a normal text editor.
.PP
The files all share a common format.  The same format is used by the
.BR nsradmin (8)
program.  Each resource is described by a list of attributes, and ends
in a blank line.  Each attribute in the attribute list has a name and
an optional list of values.  The attribute name is separated from the
attribute values by a colon (\fB:\fP), attribute values are separated
by commas (\fB,\fP), and each attribute ends in a semicolon (\fB;\fP).
A comma, semicolon or back-slash (\fB\\\fP) at the end of a line
continues the line.  A line beginning with a pound-sign (\fB#\fP) is a
comment and the rest of the line is ignored.  The back-slash character
can also be used to escape the special meaning of other characters
(comma, semicolon, pound-sign, and back-slash).
.PP
The attribute name and values can contain any printable character.
Upper and lower case is not distinguished on comparisons, and extra
white space is removed from both ends but not from inside of names and
values. For example,
.RS
.nf
\fR\s10Name: this is a test;\fP\s0
.RE
matches
.nf
.RS
\fR\s10name   :   This Is A Test ;\fP\s0
.RE
but is different than
.nf
.RS
\fR\s10Name: this      is     a    test;\fP\s0
.RE
.fi
.PP
In the following example resource, there are eight attributes.
They are
.BR type , " name" , " server" ,
.BR schedule , " directive" ,
.BR group , " save set" ", and" " remote access" .
The \fBremote access\fR attribute has no value.
.PP
.RS
.br
.nf
\fR\s10
.ta \w'remote access:'u+2nR +1m
         type: NSR client;
         name: venus;
       server: earth;
     schedule: Default;
    directive: Unix standard directives;
        group: Default;
     save set: All;
remote access: ;\fP\s0
.ta
.RE
.fi
.PP
In the following resource, there are six attributes.
The 
.B administrator
attribute has three values: \fB&engineering\fR, \fBroot\fP, and
\fBoperator\fR.  Note that the three values are separated by commas.
The \fBaction\fR attribute has one value: \fBincr incr incr incr incr
full incr\fR.  Note that this is a single value \- it just happens to
have spaces separating its words.
.PP
.nf
.RS
.br
.nf
\fR\s10
.ta \w'administrator:'u+2nR +1m
         type: NSR schedule;
       action: incr incr incr incr incr full incr;
administrator: &engineering, root, operator;
         name: engineering servers;
     override: ;
       period: Week;\fP\s0
.ta
.RE
.fi
.SH SPECIAL ATTRIBUTES
.PP
Each Sun StorEdge EBS resource includes seven special attributes: 
.BR type , " name" ,
.BR administrator , " hostname" ,
.BR "ONC program number" , " ONC version number" ,
and
.BR "ONC transport" .
The \fBtype\fR and \fBname\fR attributes are normally visible, but the
others attributes are hidden.  That an attribute is hidden indicates
that it is infrequently used and perhaps esoteric.  Hidden
attributes should usually not be changed by the user.
.PP
The \fBtype\fR attribute defines which other attributes a resource can
contain.  For example, a resource with type \fBNSR client\fR will
always include the attribute \fBserver\fR, while a resource of type
\fBNSR schedule\fR does not.
.PP
The \fBname\fR attribute is a descriptive name of the object that a
resource represents.  In the first example above, the \fBname\fR
attribute is the name of the Sun StorEdge EBS client machine.  In the second
example, the \fBname\fR attribute describes a schedule used to back up
the the servers in the engineering department.
.PP
The \fBadministrator\fR attribute is the list of users that have
permission to modify or delete this resource.  This attribute is
inherited from the
.B "type: NSR" 
resource when a new resource is created.  The administrator of the
.B NSR
resource also controls who has permission to create and delete
Sun StorEdge EBS resources.
.PP
The \fBhostname\fR attribute specifies the hostname of the machine on
which the service that controls this resource is running. It is used
internally and cannot be changed by the administrator.
.PP
The remaining attributes (\fBONC program number\fR, \fBONC version
number\fR, and \fBONC transport\fR) specify the Open Network Computing
information for this service.  They should never be changed manually.
.PP
In some cases, the resource identifier will be visible.  Although it
may look like an attribute, it is an internal value that is set and
used by the Sun StorEdge EBS system to provide unique identification of each
resource.  When new resources are created in the \fBedit\fR command of
.BR nsradmin (8),
the resource identifier attribute should be left off.  This signals
that this is a new resource and a new identifier will be assigned.
.PP
Sun StorEdge EBS resources are implemented by the Resource
Administration Platform, which is described in the
.BR resource (5)
manual page. This flexible architecture means that in future releases
of Sun StorEdge EBS, more resource types or attributes may be added, and the
administration tools in this release will automatically be able to use
them.  To make this possible, each server provides
.I type descriptors
that are used internally to describe the attributes of each type,
between the administration tools and the services.  These type
descriptors may cause limitation on the values, such as only allowing
a single value, allowing no value, or only numeric values.
.SH RESOURCE TYPES
.PP
This release of Sun StorEdge EBS defines the following types of resources:
.TP
.BR "NSR"
This resource describes a Sun StorEdge EBS server.  It contains attributes
that control administrator authorization, information about operations
in progress, and statistics and error information about past
operations.  For more information see the
.BR nsr_service (5)
manual page.
.TP
.BR "NSR client"
This resource describes a Sun StorEdge EBS client.  It includes attributes
that specify the files to save, which schedule to use, and which group
this client belongs to.  There may be more than one client resource
for a Sun StorEdge EBS client.  This allows a client to save files on
different schedules.  For more information see the
.BR nsr_client (5)
manual page.
.TP
.BR "NSR device"
This resource type describes a storage device.  It includes attributes
that specify a particular device name (for example, /dev/nrst1), media
type (for example, 8mm), and the name of the currently mounted volume.
It also provides status and statistics on current and past operations.
For more information see the
.BR nsr_device (5)
manual page.
.TP
.BR "NSR directive"
This resource describes a directive.  Directives control how a
client's files are processed as they are being saved.  For more
information see the
.BR nsr_directive (5),
.BR nsr (5)
and 
.BR uasm (8)
manual pages.
.TP
.BR "NSR group"
This resource specifies a logical grouping of Sun StorEdge EBS clients and a
starting time.  Each day, at the specified time, all members of the
group will start their saves.  For more information see the
.BR nsr_group (5)
manual page.
.TP
.BR "NSR jukebox"
This resource type describes a jukebox.  It includes attributes such
as the jukebox model, the first and last slot numbers in the jukebox,
and the names of the devices within the jukebox.  For more information
see the
.BR nsr_jukebox (5)
manual page.
.TP
.BR "NSR label"
This resource type specifies a template describing a sequence of names
to be used when labeling volumes. For more information see the
.BR nsr_label (5)
manual page.
.TP
.BR "NSR license"
This resource contains licensing information for each feature
currently enabled in this Sun StorEdge EBS installation.  It contains various
enabler and authorization codes that are used by Sun StorEdge EBS to validate
licensed capabilities.  For more information see the
.BR nsr_license (5)
and
.BR nsrcap (8)
manual pages.
.TP
.BR "NSR notification"
A notification specifies an action to be performed when a particular
type of Sun StorEdge EBS event takes place.  For more information see the
.BR nsr_notification (5)
manual page.
.TP
.BR "NSR policy"
Policy resources are used as part of the index management process in
Sun StorEdge EBS.  These policies control how long entries remain in a
client's on-line file index and when to mark a save set as recyclable.
For more information see the
.BR nsr_policy (5)
manual page.
.TP
.BR "NSR pool"
This resource type is used by Sun StorEdge EBS to determine what volumes save
sets should reside on based on the characteristics of the save (for example,
group or level).  For more information see the
.BR nsr_pool (5)
manual page.
.TP 
.BR "NSR schedule"
Schedule resources define a sequence of save levels and an override
list.  The override list is made up of pairs of levels and dates.  The
level controls the amount of data saved when a client is backed up.
For more information see the
.BR nsr_schedule (5)
manual page.
.TP 
.BR "NSR stage"
Each stage resource describes a staging policy.  The resource includes
attributes that define control parameters for the policy, and devices
managed by  the policy.  For more information see the
.BR nsr_stage (5)
manual page.
.SH FILES
.TP 20
.I /nsr/res/nsrdb
Holds the Sun StorEdge EBS server's resources.
Files in this directory should never be edited directly. Use
.BR nsradmin (8)
or
.B Sun StorEdge EBS Management Console
instead.
.SH SEE ALSO
.na
.hy 0
.BR resource (5),
.BR nsr (5),
.BR nsr_client (5),
.BR nsr_device (5),
.BR nsr_directive (5),
.BR nsr_group (5),
.BR nsr_jukebox (5),
.BR nsr_label (5),
.BR nsr_license (5),
.BR nsrcap (8),
.BR nsr_notification (5),
.BR nsr_policy (5),
.BR nsr_pool (5),
.BR nsr_schedule (5),
.BR nsr_service (5),
.BR nsr_stage (5),
.BR nsr (8),
.BR savegroup (8),
.BR savefs (8),
.BR nsradmin (8),
.BR uasm (8).
.hy 14
.ad