Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Data Services Developer's Guide Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

## Setting Resource and Resource Type Properties

Oracle Solaris Cluster software provides a set of resource type properties and resource properties that you use to define the static configuration of a data service. Resource type properties specify the type of the resource, its version, the version of the API, as well as the paths to each of the callback methods. Resource Type Properties lists all the resource type properties.

Resource properties, such as `Failover_mode`, `Thorough_probe_interval`, and method timeouts, also define the static configuration of the resource. Dynamic resource properties, such as `Resource_state` and `Status`, reflect the active state of a managed resource. Resource Properties describes the resource properties.

You declare the resource type and resource properties in the resource type registration (RTR) file, which is an essential component of a data service. The RTR file defines the initial configuration of the data service at the time that the cluster administrator registers the data service with the Oracle Solaris Cluster software.

Use Agent Builder to generate the RTR file for your data service. Agent Builder declares the set of properties that are both useful and required for any data service. For example, particular properties, such as `Resource_type`, must be declared in the RTR file. Otherwise, registration of the data service fails. Other properties, although not required, are not available to a cluster administrator unless you declare them in the RTR file. Some properties are available whether you declare them or not because the RGM defines them and provides default values. To avoid this level of complexity, use Agent Builder to guarantee the generation of a correct RTR file. Later, you can edit the RTR file to change specific values if necessary.

The rest of this section shows a sample RTR file, which was created by Agent Builder.

### Declaring Resource Type Properties

The cluster administrator cannot configure the resource type properties that you declare in the RTR file. They become part of the permanent configuration of the resource type.

Note - Only a cluster administrator can configure the resource type property `Installed_nodes`. You cannot declare `Installed_nodes` in the RTR file.

The syntax of resource type declarations is as follows:

    property-name = value;

Note - Property names for resource groups, resources, and resource types are not case sensitive. You can use any combination of uppercase and lowercase letters when you specify property names.

These are resource type declarations in the RTR file for a sample (`smpl`) data service:

    # Oracle Solaris Cluster Data Services Builder template version 1.0
    # Registration information and resources for smpl
    #
    #NOTE: Keywords are case insensitive, i.e., you can use
    #any capitalization style you prefer.
    #
    Resource_type = "smpl";
    Vendor_id = ORCL;
    RT_description = "Sample Service on Oracle Solaris Cluster";

    RT_version ="1.0";
    API_version = 2;
    Failover = FALSE;

    Init_nodes = RG_PRIMARIES;

    RT_basedir=/opt/ORCLsmpl/bin;

    Start           =    smpl_svc_start;
    Stop            =    smpl_svc_stop;

    Validate        =    smpl_validate;
    Update          =    smpl_update;

    Monitor_start   =    smpl_monitor_start;
    Monitor_stop    =    smpl_monitor_stop;
    Monitor_check   =    smpl_monitor_check;

Tip - You must declare the `Resource_type` property as the first entry in the RTR file. Otherwise, registration of the resource type fails.

The first set of resource type declarations provide basic information about the resource type.

`Resource_type` and `Vendor_id`

  Provide a name for the resource type. You can specify the resource type name with the `Resource_type` property alone (`smpl`) or by using the `Vendor_id` property as a prefix with a period (.) separating it from the resource type (`ORCL.smpl`), as shown in the sample. If you use `Vendor_id`, make it the stock market symbol of the company that is defining the resource type. The resource type name must be unique in the cluster.

  Note - By convention, the resource type name (vendoridApplicationname) is used as the package name. The combination of vendor ID and application name can exceed nine characters.

  Agent Builder, on the other hand, in all cases explicitly generates the package name from the resource type name, so it enforces the nine-character limit.

`RT_description`

  Briefly describes the resource type.

`RT_version`

  Identifies the version of the sample data service.

`API_version`

  Identifies the version of the API. For example, `API_version = 11` indicates that the data service can be registered on any version of Oracle Solaris Cluster starting with Oracle Solaris Cluster 3.3, assuming that the application is compatible with that version of Oracle Solaris Cluster software. However, `API_version = 11` also indicates that the data service cannot be registered on any version of Oracle Solaris Cluster that was released before Oracle Solaris Cluster 3.3. This property is described in more detail under the entry for `API_version` in Resource Type Properties.

`Failover = FALSE`

  Indicates that the data service can run in a resource group that can be online on multiple nodes at the same time. In other words, this declaration specifies a multi-master data service. This property is described in more detail under the entry for `Failover` in Resource Type Properties.

`Start`, `Stop`, and `Validate`

  Provide the paths to the respective callback method programs that are called by the RGM. These paths are relative to the directory that is specified by `RT_basedir`.

The remaining resource type declarations provide configuration information.

`Init_nodes = RG_PRIMARIES`

  Specifies that the RGM call the `Init`, `Boot`, `Fini`, and `Validate` methods only on nodes that can master the data service. The nodes that are specified by `RG_PRIMARIES` are a subset of all nodes on which the data service is installed. Set the value to `RT_INSTALLED_NODES` to specify that the RGM call these methods on all nodes on which the data service is installed.

`RT_basedir`

  Points to `/opt/ORCLsample/bin` as the directory path to complete relative paths, such as callback method paths.

`Start`, `Stop`, and `Validate`

  Provide the paths to the respective callback method programs that are called by the RGM. These paths are relative to the directory that is specified by `RT_basedir`.

See the `rt_properties`(5) man page for more information about resource type properties. See the `clresourcetype`(1CL) man page for more information about registering resource types in the global cluster or in a zone cluster.

### Declaring Resource Properties

As with resource type properties, you declare resource properties in the RTR file. By convention, resource property declarations follow the resource type declarations in the RTR file. The syntax for resource declarations is a set of attribute value pairs enclosed by braces ({ }):

    {
        attribute = value;
        attribute = value;
                 .
                 .
                 .
        attribute = value;
    }

For resource properties that are provided by Oracle Solaris Cluster, which are called system-defined properties, you can change specific attributes in the RTR file. For example, Oracle Solaris Cluster provides default values for method timeout properties for each callback method. In the RTR file, you can specify different default values.

You can also define new resource properties in the RTR file, which are called extension properties, by using a set of property attributes that are provided by Oracle Solaris Cluster. Resource Property Attributes lists the attributes for changing and defining resource properties. Extension property declarations follow the system-defined property declarations in the RTR file.

The first set of system-defined resource properties specifies timeout values for the callback methods.

    …

    # Resource property declarations appear as a list of bracketed
    # entries after the resource type declarations. The property
    # name declaration must be the first attribute after the open
    # curly bracket of a resource property entry.
    #
    # Set minimum and default for method timeouts.
    {
            PROPERTY = Start_timeout;
            MIN=60;
            DEFAULT=300;
    }

    {
            PROPERTY = Stop_timeout;
            MIN=60;
            DEFAULT=300;
    }
    {
            PROPERTY = Validate_timeout;
            MIN=60;
            DEFAULT=300;
    }
    {
            PROPERTY = Update_timeout;
            MIN=60;
            DEFAULT=300;
    }
    {
            PROPERTY = Monitor_Start_timeout;
            MIN=60;
            DEFAULT=300;
    }
    {
            PROPERTY = Monitor_Stop_timeout;
            MIN=60;
            DEFAULT=300;
    {
            PROPERTY = Monitor_Check_timeout;
            MIN=60;
            DEFAULT=300;
    }

The name of the property (`PROPERTY =` value) must be the first attribute for each resource-property declaration. You can configure resource properties within limits that are defined by the property attributes in the RTR file. For example, the default value for each method timeout in the sample is 300 seconds. The cluster administrator can change this value. However, the minimum allowable value, specified by the `MIN` attribute, is 60 seconds. Resource Property Attributes contains a list of resource property attributes.

The next set of resource properties defines properties that have specific uses in the data service.

    {
            PROPERTY = Failover_mode;
            DEFAULT=SOFT;
            TUNABLE = ANYTIME;
    }
    {
            PROPERTY = Thorough_Probe_Interval;
            MIN=1;
            MAX=3600;
            DEFAULT=60;
            TUNABLE = ANYTIME;
    }

    # The number of retries to be done within a certain period before concluding
    # that the application cannot be successfully started on this node.
    {
            PROPERTY = Retry_count;
            MAX=10;
            DEFAULT=2;
            TUNABLE = ANYTIME;
    }

    # Set Retry_interval as a multiple of 60 since it is converted from seconds
    # to minutes, rounding up. For example, a value of 50 (seconds)
    # is converted to 1 minute. Use this property to time the number of
    # retries (Retry_count).
    {
            PROPERTY = Retry_interval;
            MAX=3600;
            DEFAULT=300;
            TUNABLE = ANYTIME;
    }

    {
            PROPERTY = Network_resources_used;
            TUNABLE = WHEN_DISABLED;
            DEFAULT = "";
    }
    {
            PROPERTY = Scalable;
            DEFAULT = FALSE;
            TUNABLE = AT_CREATION;
    }
    {
            PROPERTY = Load_balancing_policy;
            DEFAULT = LB_WEIGHTED;
            TUNABLE = AT_CREATION;
    }
    {
            PROPERTY = Load_balancing_weights;
            DEFAULT = "";
            TUNABLE = ANYTIME;
    }
    {
            PROPERTY = Port_list;
            TUNABLE = ANYTIME;
            DEFAULT = ;
    }

These resource-property declarations include the `TUNABLE` attribute. This attribute limits the occasions on which the cluster administrator can change the value of the property with which this attribute is associated. For example, the value `AT_CREATION` means that the cluster administrator can only specify the value when the resource is created and cannot change the value later.

For most of these properties, you can accept the default values as generated by Agent Builder unless you have a reason to change them. Information about these properties follows. For additional information, see Resource Properties or the `r_properties`(5) man page.

`Failover_mode`

  Indicates whether the RGM should relocate the resource group or abort the node in the case of a failure of a `Start` or `Stop` method.

`Thorough_probe_interval`, `Retry_count`, and `Retry_interval`

  Used in the fault monitor. `Tunable` equals `ANYTIME`, so a cluster administrator can adjust them if the fault monitor is not functioning optimally.

`Network_resources_used`

  A list of logical-hostname or shared-address resources on which this resource has a dependency. This list contains all network-address resources that appear in the properties `Resource_dependencies`, `Resource_dependencies_weak`, `Resource_dependencies_restart`, or `Resource_dependencies_offline_restart`.

  The RGM automatically creates this property if the `Scalable` property is declared in the RTR file. If the `Scalable` property is not declared in the RTR file, `Network_resources_used` is unavailable unless it is explicitly declared in the RTR file.

  If you do not assign a value to the `Network_resources_used` property, its value is updated automatically by the RGM, based on the setting of the resource-dependencies properties. You do not need to set this property directly. Instead, set the `Resource_dependencies`, `Resource_dependencies_offline_restart`, `Resource_dependencies_restart`, or `Resource_dependencies_weak` property. If per-node dependencies are specified, the derived value of the `Network_resources_used` property includes only those dependencies which are in effect on the local node. The value might differ on each node.

  For simplicity, avoid setting a value for the `Network_resources_used` property. Set only the resource dependency properties, and treat the `Network_resources_used` property as a read-only property. For more information, see the `r_properties`(5) man page.

`Scalable`

  If set to `TRUE`, indicates that the resource uses the network load balancing feature of Oracle Solaris Cluster software. In this case, the resource must be configured with a dependency upon a shared address resource. See Implementing a Scalable Resource for additional information about how to use this property.

  In this example, the tunability of the `Scalable` property is declared to be `AT_CREATION`, which means that this property may be set to either `TRUE` or `FALSE` when the resource is created. This implies that the resource type implementation is capable of supporting either a scalable or non-scalable mode of operation for the resource.

`Load_balancing_policy` and `Load_balancing_weights`

  These properties are declared automatically when the `Scalable` property is declared. Therefore, their appearance in the RTR file is optional unless you want to override the default tunability. These properties are used only when the `Scalable` property is set to `TRUE`.

`Port_list`

  Identifies the list of ports on which the application is listening. Agent Builder declares this property so that a cluster administrator can specify a list of ports when the cluster administrator configures the data service.

### Declaring Extension Properties

Extension properties appear at the end of the sample RTR file.

    # Extension Properties
    #

    # The cluster administrator must set the value of this property to point to the
    # directory that contains the configuration files used by the application.
    # For this application, smpl, specify the path of the configuration file on
    # PXFS (typically named.conf).
    {
            PROPERTY = Confdir_list;
            EXTENSION;
            STRINGARRAY;
            TUNABLE = AT_CREATION;
            DESCRIPTION = "The Configuration Directory Path(s)";
    }

    # The following two properties control restart of the fault monitor.
    {
            PROPERTY = Monitor_retry_count;
            EXTENSION;
            INT;
            DEFAULT = 4;
            TUNABLE = ANYTIME;
            DESCRIPTION = "Number of PMF restarts allowed for fault monitor.";
    }
    {
            PROPERTY = Monitor_retry_interval;
            EXTENSION;
            INT;
            DEFAULT = 2;
            TUNABLE = ANYTIME;
            DESCRIPTION = "Time window (minutes) for fault monitor restarts.";
    }
    # Time out value in seconds for the probe.
    {
            PROPERTY = Probe_timeout;
            EXTENSION;
            INT;
            DEFAULT = 120;
            TUNABLE = ANYTIME;
            DESCRIPTION = "Time out value for the probe (seconds)";
    }

    # Child process monitoring level for PMF (-C option of pmfadm).
    # Default of -1 means to not use the -C option of pmfadm.
    # A value of 0 or greater indicates the desired level of child-process.
    # monitoring.
    {
            PROPERTY = Child_mon_level;
            EXTENSION;
            INT;
            DEFAULT = -1;
            TUNABLE = ANYTIME;
            DESCRIPTION = “Child monitoring level for PMF";
    }
    # User added code -- BEGIN VVVVVVVVVVVV
    # User added code -- END   ^^^^^^^^^^^^

Agent Builder creates the following extension properties, which are useful for most data services.

`Confdir_list`

  Specifies the path to the application configuration directory, which is useful information for many applications. The cluster administrator can provide the location of this directory when the cluster administrator configures the data service.

`Monitor_retry_count`, `Monitor_retry_interval`, and `Probe_timeout`

  Controls the restarts of the fault monitor itself, not the server daemon.

`Child_mon_level`

  Sets the level of monitoring to be carried out by the PMF. See the `pmfadm`(1M) man page for more information.

You can create additional extension properties in the area that is delimited by the `User added code` comments.

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