.\"
.\" $Id: nsr_group.5,v 1.1.64.5 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_GROUP" 5 "Aug 23, 06" "StorEdge EBS 7.3.2"
.SH NAME
nsr_group \- Sun StorEdge EBS resource type ``NSR group''
.SH SYNOPSIS
.B  "type: NSR group"
.SH DESCRIPTION
Each Sun StorEdge EBS group is described by a single resource of type
.B NSR group
(see
.BR nsr_resource (5)).
To edit the
.B NSR group
resources for a Sun StorEdge EBS server type:
.br
.RS
\fR\s10nsradmin \-c "type:NSR group"\fP\s0
.RE
.br
or use
.B Sun StorEdge EBS Management Console.
See the
.BR nsradmin (8)
manual page for more information on using the Sun StorEdge EBS administration program.
.LP
These resources control when a group of Sun StorEdge EBS clients begin saving data and
whether backups are started automatically each day.
Each
.B NSR client
resource (see
.BR nsr_client (5))
lists the groups of which that client (or save sets for that client)
is a member.
Groups can only be deleted if no clients are members of them.
.SH ATTRIBUTES
.LP
The following attributes are defined for resource type
.BR "NSR group" .
The information in parentheses describes how the attribute values are accessed.
.B Create-only
indicates that the value cannot be changed by an administrator once the
resource is created.
.B Read/write
means the value can be set as well as read at any time.
.B Choice
indicates that the value can only be selected from a given list.
.B Yes/no
means only a yes or no choice is possible.
.B Static
attributes change values rarely, if ever.
.B Dynamic
attributes have values which change rapidly.
.B Hidden
means it is an attribute of interest only to programs or experts,
and these attributes can only be seen when the hidden option is turned on in
.BR nsradmin (8).
For example, an attribute marked
.B "(create-only, static)"
has a value which is set when the attribute is created and never changes.
Several additional attributes (for example, administrator) are common
to all resources, and are described in
.BR nsr_resource (5).
.TP
.BR "name"		(create-only)
This attribute contains the name of the group defined by this
resource.
The name must be unique for this Sun StorEdge EBS server, but otherwise can be
anything that makes sense to the administrator.
This name will appear as a choice attribute of each
.B "NSR client"
and
.BR "NSR pool" (5)
resource.
The
.B NSR group
resource named `Default' may be modified, but it may
not be removed.
The name can only be specified when the group is created.
.br
.I Example:
\fR\s10name: marketing;\fP\s0
.TP
.BR "comment" "		(read/write)"
This attribute is provided for the administrator to keep any explanatory
remarks or supplementary information about the group.
.br
.TP
.BR "snapshot" "	(read/write, yes/no)"
This attribute determines whether the group represents snapshot
backups. NOTE: This feature is enabled with EMC PowerSnap modules only.
.br
.TP
.BR "autostart" "	(read/write, choice)"
This attribute determines if this group will be saved automatically
every day.
It may be one of three values:
.BR Enabled ","
.B Disabled
or
.B Start now.
When the value is
.BR Enabled ","
the members of this group will start
saving data at the time specified in the
.B start time
attribute.
When the value is
.BR Disabled ","
the member of this group will not
automatically start saving their data.
When the
.B Start now
value is specified, the member clients will start
saving their data immediately. The attribute will then return to its
prior value.
.br
.I Example:
\fR\s10autostart: Enabled;\fP\s0
.TP
.BR "autorestart" "	(read/write, choice, hidden)"
This attribute controls whether this group should be automatically restarted when an
incomplete run (due to a power failure or administrator intervention) is
noticed during Sun StorEdge EBS server startup.
Like the
.B autostart
attribute, setting this attribute's value to
.B Restart now
causes Sun StorEdge EBS to restart the group immediately. Enabling
.B autorestart
only has an effect if
.B autostart
is also enabled.
.TP
.BR "stop now" "	(read/write, choice, hidden)"
Setting this value to `True' when this group is running causes
this group to abort all of its saves immediately.
Once the group is stopped, the value is set back to `False'.
These are the only valid values.
.TP
.BR "start time"	(read/write)
This attribute specifies the time of day
when this group will start saving.
The Sun StorEdge EBS server's local time is used.
The time is specified as "\fIhours\fR:\fIminutes\fR".
Note that the quotes may be necessary
when using character-based administration tools such as the
.B nsradmin
program
because of the colon
in the value.
The hours may range from 0 to 23 (using a 24 hour clock)
and the minutes range from 0 to 59.
.br
.I Example:
\fR\s10start time: "4:53";\fP\s0
.TP
.BR "last start" "	(read/write, hidden)
The last time this group was started.
If multiple instances were attempted to run, only one instance will 
update this attribute. The "last end" attribute will be cleared 
when this is set.
This attribute is for informational purposes only, and changing it has
no effect on the system.
.TP
.BR "last end" "		(read/write, hidden)
The last time this group ended or completed.
This attribute is for informational purposes only, and changing it has
no effect on the system.
This attribute gets updated only if last start attribute is updated.
If the savegrp program or the machine terminates abnormally, the "last end"
attribute may not be updated.
.TP
.BR "interval" "		(read/write, static, hidden)
This attribute specifies how often this group is to be run automatically
by Sun StorEdge EBS.
Manually starting a group overrides the interval.
The default value is 24:00, which means run once a day.
.TP
.BR "restart window" "		(read/write, static, hidden)
This attribute is used for automatically restarted groups
by Sun StorEdge EBS. This defines the amount of time for which restarts
are valid.
If the restart window has elapsed from the previous start of group, the
restart attempt is converted into a fresh start.
Also individual savesets
are considered elapsed even if successfully completed previously
but the start time is older than this window.
These savesets are considered eligible for restart.
This attribute helps maintain the start time of all savesets
completed as part of the group fall within this time window.
The
.I "restart window"
attribute has to be less than 
.I "interval"
and setting it to half of 
.I "interval"
helps avoid overruning restart attempts beyond the next scheduled start.
The default value is 12:00, which is half of default value of
.I "interval"
(24:00). 
.TP
.BR "success threshold" "		(read/write, choice)"
This attribute helps set the criteria for reporting the success of all
savesets within a group.
The default value is 
.I "Warning" 
which means if any saveset has warning(s) during backup
it will be reported in the
.I Successful Save Sets
section.
The client(s) of these savesets will be reported as
.I successful with warning(s)
in the completion report's header summary.
If set to
.I "Success",
any savesets completed with warning(s) will be reported in the
.I Unsuccesful Savesets
section.
Please note any failures will invoke a retry on the saveset if retry
count is not 0. The client will also be reported as failed in the
savegroup completion report's header summary.
.TP
.BR "snapshot policy" "		(read/write, choice)"
Snapshot policy associated with the group, if this group happens to have
snapshot set to Yes. NOTE: this feature is enabled with PowerSnap modules only.
.TP
.BR "snapshot pool" "		(read/write, choice)"
Pool to which Snapshot meta data needs to be backed up.
NOTE: this feature is enabled with EMC PowerSnap modules only.
.TP
.BR "force incremental" "  (read/write, static, hidden, choice)
Setting this attribute to `Yes' will force an incremental level of
a savegroup, when the
.B "interval"
attribute is less than 24 hours and the group is started after
.IR 12:00am + interval.
Please note that 12:00am is midnight.
The default value is `Yes.' A value of `No' means that all backups
are done at pre-determined level (as specified in the group 
resource's level attribute).
This attribute applies only to automatically started groups.

The following example shows how to use this attribute in conjunction
with "interval". Assume that a group g1 has to be backed up every
6 hours and the first backup must be a level backup.
For g1, set the interval to 06:00, set autostart to "enabled" and
set force incremental to `Yes.'  Also set the level to the desired
level. In this case the first scheduled run of group g1
(before 6:00am) will be run at the level configured.
Subsequent scheduled runs of group g1 on the same day
(after 6:00am) will be run at incremental level.
.TP
.BR "savegrp parallelism" "  (read/write)
If this value is non-zero,
then the
.B savegrp
program eschews all other parallelism policies
and attempts to keep that number of saves running.
.TP
.BR "client retries" "	(read/write)
The number of times failed clients should be retried before
.B savegrp
gives up and declare them failed.
Zero means do not retry.
Abandoned saves are not retried, because they may eventually complete.
A client's save sets are retried by
.B savegrp
whenever it would otherwise not be able to start a new save set.
That is,
.B savegrp
prefers to start new save sets first, and only
retries when there is nothing else to do.
.br
.I Example:
\fR\s10client retries: 1;\fP\s0
.TP
.BR "clones" "          (read/write, static, yes/no, choice)
Setting this value to `Yes' causes saves of this group to
automatically make a clone of every save set backed up.
The save set clones will be sent to the pool named in the
.B "clone pool"
attribute.
.TP
.BR "clone pool" "		(read/write, static, choice)
The pool to which save set clones should be sent when `clones' is `Yes'.
Only pools of type `Backup Clone' are allowed (see
.BR nsr_pool (5)).
.TP
.BR "options" "		(read/write, static, hidden)
The values specify flags with which this group will be run.
The values
No Monitor, No index save, No save, Verbose, Estimate, and Preview
map to the
.B savegrp
command line flags 
.B -m, 
.B -I, 
.B -n, 
.B -v, 
.B -E, 
and 
.B -p 
respectively.
Some of these values (Preview and No save) are automatically reset
when a run of
.B savegrp
completes normally.
.br
.I Example:
\fR\s10options: Verbose;\fP\s0
.TP
.BR "level" "		(read/write, hidden, choice)
This is an explicit level the savegroup will use when started
automatically by Sun StorEdge EBS.
.IR "This hidden attribute can be modified by a user."
This value is not cleared automatically, that is, if one sets this attribute
to full, this savegroup will run with a full level until this value
is manually cleared.
When not specified (the normal case), the NSR Schedule for each client
filesystem will be used to determine the level.
Manually running
.B savegrp
from the command line overrides this value.
The choices are the standard level identifiers `full', `consolidate', `incr', 
`skip', and the number levels `1' through `9'.
.TP
.BR "printer" "		(read/write, static, hidden)
The printer to which the bootstrap save set information will be printed,
if one is generated by the run of this group.
.IR "This hidden attribute can be modified by a user."
If an invalid printer name is specified, bootstrap information will be
included in the savegroup completion information piped through the
.I "savegroup completion"
notification (see
.BR nsr_notification (5)).
.br
.I Example:
\fR\s10printer: ps;\fP\s0
.TP
.BR "schedule" "	(read/write, choice, hidden)
The schedule to use for determining what level of save to perform.
.IR "This hidden attribute can be modified by a user."
This value is not cleared automatically, that is, if one sets this attribute
to a particular schedule, all clients which are part of this group will
have their schedules overridden until this value is manually cleared.
This overrides the schedule specified for individual clients.
See
.BR nsr_schedule (5)).
.TP
.BR "schedule time" "	(read/write, hidden)
An explicit time can be specified when looking at a schedule to
determine which level of save to perform.  A null value (normal setting)
means use the current date to determine the level.
.br
.I Example:
\fR\s10schedule time: "3:00 am 01/11/93";\fP\s0
.TP
.BR "inactivity timeout" "	(read/write, static, hidden)
The number of minutes that
the
.B savegrp
command waits for any kind of activity on the server before
concluding that a
.B savegrp
descendant is hung.
.IR "This hidden attribute can be modified by a user."
Once a hang is detected,
.B savegrp
prints a message indicating that a
.B save
is being aborted, kills or aborts the backup, and
moves on to its next task.
Inactivity is defined as the last time a client has sent data to the server.
If a client has a very large filesystem and an incremental is run, it is
possible for
.B savegrp
to abort a save set that only appears to be hung.  In these cases, the
inactivity timeout should be increased to accommodate the particular client.
.br
.I Example:
\fR\s10inactivity timeout: 30;\fP\s0
.TP
.BR "work list" "	(read/write, dynamic, hidden)
The list of saves still not completed.
These come in sets of three values:  the client name,
the level of save,
and the path to save.
.br
.I Example:
\fR\s10work list: mars, incr, /usr, mars, incr, /g, mars, venus, /usr\fP\s0
.TP
.BR "completion" "	(read/write, dynamic, hidden)
The status of each save set that has been completed.
These come in sets of four values:  the client name,
the path saved,
a status message (succeeded, failed, or unexpectedly exited),
and the output from the save.
.br
.I Example:
\fR\s10completion: "mars", "/usr", "succeeded", "mars: /           level=full,   6577 KB 00:06:41    625 files"\fP\s0
.TP
.BR "progress file name" "	(read/write, dynamic, hidden)"
The name of a (private) file where
.B savegrp
stores the current
representation of the group's
work list and completion information.
Using a file avoids the constant pushing
of massive amounts of information between
.B savegrp
and the RAP database owner,
.BR nsrd .
.TP
.BR "status" "	(read-only, dynamic, hidden)"
The current status of this NSR group.  Currently, this can have the
values `idle', `running' and `cloning'.
The value `idle' is set when the group is not active, it is `running' while
backups are in progress, and it is `cloning' when the backups are complete
and clones are automatically being made.
<<<<<<< nsr_grp.5
.SH EXAMPLE
The default NSR group resource automatically starts its members
at 33 minutes
past 3 o'clock in the morning:
.LP
.RS
.br
.nf
\fR\s10
.ta \w'administrator:'u+2nR +2n
	type:	NSR group;
	name:	Default;
	autostart:	Enabled;
	start time:	"3:33";
	administrator:	root;
.ta
.fi
.RE
.LP
A complete example follows,
with the hidden attributes shown with values reasonable for an active group:
.LP
.RS 0
.nf
\fR\s10
.ta \w'inactivity timeout:'u+2nR +2n
	type:	NSR group;
	name:	Default;
	autostart:	Enabled;
	start time:	"3:33";
	options:	Restartable;
	printer:	lp2;
	inactivity timeout:	30;
	work list:	mars, incr, /g, mars, incr, index,
		venus, incr, /usr, venus, incr, index,
		jupiter, full, /, jupiter, full, /usr,
		jupiter, full, index
	completion:	mars, /, succeeded,
"mars: / level=incr,     31 KB 00:01:01     72 files
",
		mars, /usr, succeeded,
"mars: /usr level=incr,      2 KB 00:00:48      5 files
",
		venus, /, succeeded,
"venus: / level=incr,   7711 KB 00:04:37     29 files
";
	administrator:	root, &operator;
.ta
.fi
.RE
.SH SEE ALSO
.na
.hy 0
.BR nsr (8),
.BR nsr_notification (5),
.BR nsr_pool (5),
.BR nsr_resource (5),
.BR nsr_schedule (5),
.BR nsradmin (8),
.BR savegrp (8)
.hy 14
.ad