Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Reference Manual Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

### 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.

`property-name = property-value;`
`property-name;`
`property-name = property-value [, property-value];`

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-value`s 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:

`boolean-property-name;`
`boolean-property-name = TRUE;`
`boolean-property-name = FALSE;`

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

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.

`type-attribute-value;`
`enum-type-attribute { enum-value [ , enum-value ] };`

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;

    #$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:

ATTRIBUTE TYPE | ATTRIBUTE VALUE
--- | ---
Availability | ha-cluster/developer/api
Interface Stability | Evolving

## See Also

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

Oracle Solaris Cluster Data Services Developer’s Guide

Copyright © 2000, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |