rt_reg

- resource type registration (RTR) file

Description

The resource type registration (RTR) file describes a resource type. Resource types represent highly-available or scalable services that run under the control of the Resource Group Manager (RGM) cluster facility. The file is part of a resource type implementation and is used as an input file for the scrgadm(1M) command to register the resource type in a cluster configuration. Registering the resource type is a prerequisite to creating resources of that type to run in the cluster. By convention, the RTR file resides in the /opt/cluster/lib/rgm/rtreg directory.

A RTR file declares the resource type properties and resource properties of a resource type. The file is divided into two parts, the declaration of resource type properties, and of resource properties. Note that recognition of property names is not case sensitive.

The resource type property declarations provide the information on the resource type implementation, such as paths to the callback methods that are to be invoked by the RGM to control resources of the type. Most resource type properties have fixed values set in the rt_reg file. These properties are inherited by all resources of the type.

A resource type implementor can also customize and extend the administrative view of resource properties. There are two kinds of resource properties that can have entries in the second part of an rt_reg file: system defined properties and extension properties.

System-defined resource properties have predetermined types and semantics. The rt_reg file can be used to set attributes such as default, minimum and maximum values for system defined resource properties. The rt_reg file can also be used to declare extension properties that are defined entirely by the resource type implementation. Extension properties provide a way for a resource type to add information to the configuration data for a resource that is maintained and managed by the cluster system.

The rt_reg file can set default values for resource properties, but the actual values are set in individual resources. The properties in the rt_reg file can be variables that can be set to different values and adjusted by the cluster administrator.

Resource Type Property Declarations

The resource type property declarations consist of a number of property value assignments.

PROPERTY_NAME = "Value"; 

See the rt_properties(5) man page for a list of the resource type properties you can declare in the rt_reg file. Since most properties have default values or are optional, the only declarations that are essential in a RTR file are the type name, the paths to the START and STOP callback methods, and RT_version.

Note that the first property in the file must be the Resource_type property.

A resource type name is of the form vendor-id.RT-name:version.

The three components of the resource type name are properties specified in the RTR file as vendor-id, resource-type, and RT-version. The scrgadm command inserts the period and colon delimiters. Although optional, the vendor-id prefix is recommended to distinguish between two registration files of the same name provided by different vendors. To ensure that the vendor-id is unique, use the stock symbol for the company that is creating the resource type.

Resource Property Declarations

Resource property declarations consist of a number of entries, each entry being a bracketed list of attribute value assignments. The first attribute in the entry must be the resource property name.

System-defined properties have predetermined type and description attributes and so these attributes cannot be re-declared in the rt_reg file. Range restrictions, a default value, and constraints on when the value can be set by the administrator can be declared for system defined properties.

Attributes that can be set for system-defined properties are listed in the property_attributes(5) man page. Attributes not available for system-defined properties are noted as such in the table.

System-defined properties that can have entries in the rt_reg file are listed in the r_properties(5) man page. The following is a sample entry for the system defined RETRY_COUNT resource property.

{ 
  PROPERTY = RETRY_COUNT; 
  MIN=0;
  MAX=10;
  DEFAULT=2;
  TUNABLE = ANYTIME;
}

Entries for extension properties must indicate a type for the property. Attributes that can be set for extension properties are listed in the property_attributes(5) man page.

The following is a sample entry for an extension property named "ConfigDir" that is of string type. The TUNABLE attribute indicates that the cluster administrator can set the value of the property when a resource is created.

{ 
  PROPERTY = ConfigDir; 
  EXTENSION;
  STRING;
  DEFAULT="/";
  TUNABLE = AT_CREATION;
}

Usage

An rt_reg file is an ASCII text file. It can include comments describing the contents of the file. The contents are the two parts described above, with the resource type property list preceding the resource property declarations.

White space can be blanks, tabs, newlines, or comments. White space can exist before or after tokens. Blanks and the pound sign (#) are not considered to be white space when found in quoted value tokens. White space separates tokens but is otherwise ignored.

Comments begin with # and end with the first newline encountered, inclusively.

Directives begin with #$ and end with the first newline encountered, inclusively. Directives must appear in the RTR file between the resource type property declaration section and the resource property declaration section. Directives inserted in any other location in the RTR file will produce parser errors. The only valid directives are #$upgrade and #$upgrade_from. Any other directive will produce parser errors.

Tokens are property names, property values, and the following:

{ }

Encloses parameter table properties

;

Terminates properties and attributes

=

Separates property names and property values or attribute names and attribute values

,

Separates values in a value list

The recognition of property-name keywords in the file is case insensitive.

Properties and attributes have one of three formats.

In the format above, the square brackets, [ ], enclose optional items. That is, the property value can be a single property-value or a list of two or more property-values separated by commas.

The first property in the property list must be the simple resource type name.

Boolean properties and attributes have the following syntax:

The first and second forms both set the boolean-property-name to TRUE.

The only property name taking a list for its value is PKGLIST. An example is:

PKGLIST = SUNWsczu, SUNWrsm;

Resource type property names are listed in the rt_properties(5) man page. System-defined properties are listed in the r_properties(5) man page.

Resource declarations consist of any number of entries, each being a bracketed list of resource property attributes.

{attribute-value-list}

Each attribute-value-list consists of attribute values for a resource property, in the same syntax used for property values, with the addition of the two type-attribute formats.

The type-attribute-value syntax declares the data type of the extension property to have the value type-attribute-value. It differs from the first format of the boolean-property-name, which defines the property named by boolean-property-name to have the value TRUE.

For example, the TUNABLE attribute can have one of the following values: FALSE or NONE, AT_CREATION, TRUE or ANYTIME, and WHEN_DISABLED. When the TUNABLE attribute uses the syntax:

TUNABLE;

it gets the value of ANYTIME.

Grammar

The following is a description of the syntax of the rt_reg file with a BNF-like grammar. Non-terminals are in lower case, and terminal keywords are in upper case, although the actual recognition of keywords in the rt_reg file is case insensitive. The colon (:) following a non-terminal at the beginning of a lines indicates a grammar production. Alternative right-hand-sides of a grammar production are indicated on lines starting with a vertical bar (|). Variable terminal tokens are indicated in angled brackets and comments are parenthesized. Other punctuation in the right-hand side of a grammar production, such as semi-colon (;), equals sign (=), and angled brackets ({}) are literals.

A comment has the form:

COMMENT    : # anything but NEWLINE NEWLINE

Comments may appear after any token. Comments are treated as white-space.

    rt_reg_file    :  Resource_type = value ; proplist upgradesect paramtable

    proplist    :  (NONE: empty)
    | proplist rtproperty

    rtproperty    : rtboolean_prop ;
    | rtvalue_prop ;

    rtboolean_prop    : SINGLE_INSTANCE
    | FAILOVER | RT_SYSTEM

    rtvalue_prop    : rtprop = value
    | PKGLIST = valuelist

    rtprop    : RT_BASEDIR
    | RT_VERSION
    | API_VERSION
    | INIT_NODES
    | START
    | STOP
    | VALIDATE
    | UPDATE
    | INIT
    | FINI
    | BOOT
    | MONITOR_START
    | MONITOR_STOP
    | MONITOR_CHECK
    | PRENET_START
    | POSTNET_STOP
    | RT_DESCRIPTION
    | VENDOR_ID 
    | rtboolean_prop (booleans may have explicit assignments.)

    value    : contiguous-non-ws-non-;-characters
    | "anything but quote"
    | TRUE
    | FALSE
    | ANYTIME
    | WHEN_DISABLED
    | AT_CREATION
    | RG_PRIMARIES
    | RT_INSTALLED_NODES
    |  (NONE: Empty value)

    valuelist    : value
    | valuelist , value

    upgradesect : (empty)
    | #$UPGRADE upgradelist 

    upgradelist :  (empty)
    | upgradelist #$UPGRADE_FROM rt_version upgtunability

    upgtunability : ANYTIME
    | AT_CREATION
    | WHEN_DISABLED
    | WHEN_OFFLINE
    | WHEN_UNMANAGED
    | WHEN_UNMONITORED

    paramtable    :  (empty)
    | paramtable parameter

    parameter    :  { pproplist }

    pproplist    : PROPERTY = value ;  (property name must come first)
    | pproplist pproperty

    pproperty    : pboolean_prop ;
    | pvalue_prop ;
    | typespec ;

    pvalue_prop    : tunable_prop
    | pprop = value
    | pprop =  (NONE: no value setting)
    | DEFAULT = valuelist

    pprop    : DESCRIPTION
    | MIN
    | MAX
    | MINLENGTH
    | MAXLENGTH
    | ARRAY_MINSIZE
    | ARRAY_MAXSIZE
    | pboolean_prop

    tunable_prop    : TUNABLE
    | TUNABLE = AT_CREATION
    | TUNABLE = ANYTIME
    | TUNABLE = WHEN_DISABLED
    | TUNABLE = TRUE
    | TUNABLE = FALSE
    | TUNABLE = NONE

    typespec    : INT
    | BOOLEAN
    | STRING
    | STRINGARRAY
    | ENUM { valuelist }

Examples

Example 1 A Sample Registration File

The following is the registration file for a simple example resource type.

#
# Registration information for example resource type
#

Resource_type = example_RT;
Vendor_id = SUNW;
RT_Version = 2.0
RT_Basedir= /opt/SUNWxxx;
START = bin/example_service_start;
STOP  = bin/example_service_stop;
Pkglist = SUNWxxx;

#$upgrade
#$upgrade_from "1.0" when_unmonitored

#
# Set range and defaults for method timeouts and Retry_count.
#
{ Property = START_TIMEOUT;  Tunable; MIN=60; DEFAULT=300; }
{ Property = STOP_TIMEOUT;  Tunable; MIN=60; DEFAULT=300; }
{ Property = Retry_count;  Tunable; MIN=1; MAX=20; DEFAULT=10; }

#
# An extension property that can be set at resource creation
#
{ Property = LogLevel;
  Extension;
  enum { OFF, TERSE, VERBOSE };
  Default = TERSE;
  Tunable = AT_CREATION;
  Description = "Controls the detail of example_service logging";
}

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

scrgadm(1M), attributes(5), rt_properties(5), r_properties(5), property_attributes(5)