Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Geographic Edition System Administration Guide

Search Scope:

- This Document
- Entire Library

## Property Descriptions for Script-Based Plug-Ins

This section contains the following information:

- Protection Group Properties - Overview

- Replicated Component Properties - Overview

- Protection Group Property Descriptions

### Protection Group Properties - Overview

The table in this section lists the protection group properties, along with a brief description, type of property, and default value for each property.

The scripts named by the developer in these properties can reference independent executables, a single common executable, or a combination of the two. No restrictions are placed on the language used to implement these scripts with the exception that the scripts must be able to run by root, from the command line, without a graphical display, and they must return either a zero (success) or non-zero (failure) exit code. The script-based plug-in Mbean returns any error code resulting from a failure. For more information, see Appendix G, Error Return Codes for Script-Based Plug-Ins.

Protection groups that use script-based plug-in replication have the global properties provided in the following table. Note that all of these properties are tunable when you are offline.

Table 10-1 Protection Group Global Policies

Property Name | Description | Type | Default Value
`add_app_rg_args` | The arguments that are provided to the script, `add_app_rg_script.` | Optional | Not applicable
`add_app_rg_script` | The script used to validate and perform tasks relevant for adding an application resource group to a protection group. | Required | `/bin/true`
`configuration_file` | The per protection group script-based plug-in configuration file containing details of the nodes pertinent to script-based plug-in replicated components held in the protection group. | Required | `/etc/opt/SUNWscgrepsbp/configuration`
`create_config_script` | The script used to create, modify, and validate a script-based plug-in replicated component instance. | Required | `/bin/false`
`remove_app_rg_args` | The arguments that are provided to the script, `remove_app_rg_script`. | Optional | Not applicable
`remove_app_rg_script` | The script used to validate and perform tasks relevant for removing an application resource group from a protection group. | Required | `/bin/true`
`remove_config_script` | The script used to remove a script-based plug-in replicated component instance. | Required | `/bin/true`
`start_replication_script` | The script used to start the data replication for a script-based plug-in replicated component instance. | Required | `/bin/true`
`stop_replication_script` | The script used to stop the data replication for a script-based plug-in replicated component instance. | Required | `/bin/true`
`switchover_script` | The script used to switch over the data replication direction for a script-based plug-in replicated component instance. | Required | `/bin/true`
`takeover_script` | The script used to take over the data replication for a script-based plug-in replicated component instance. | Required | `/bin/true`

The Property Descriptions section describes in detail the actions that each script and its associated arguments should perform when called by the script-based plug-in MBean. Standardized Script Command-Line Parameters explains how scripts can discriminate between the steps being performed. For more information, see Protection Group Property Descriptions and Standardized Script Command-Line Arguments

### Replicated Component Properties - Overview

Each replication component added to a particular protection group uses the scripts named in Protection Group Properties - Overview. Individual replications distinguish themselves by varying the properties passed to these scripts. The replication component script properties are listed in the following table. For more information, see Protection Group Properties - Overview

The script-based plug-in module provides for two site-specific password properties:

- A local service password property (`local_service_password`)

- A remote service password property (`remote_service_password`)

These properties enable administrators of a script-based plug-in deployment to supply passwords to log in to services or remote systems without having to provide these passwords at switchover or takeover time. For more information, see How Geographic Edition Handles Password Properties.

The script-based plug-in module requires the developer to provide a property naming the replication resource contained in the replication resource group that holds the status of the replication.

Replicated components in script-based plug-in protection groups have the optional properties provided in the following table. Note that all of these properties are tunable when you are offline.

Table 10-2 Optional Replicated Component Properties

Property Name | Description | Type
`create_config_args` | The arguments passed to the script named by the `create_config_script` protection group property. | Global
`remove_config_args` | The arguments passed to the script named by the `remove_config_script` protection group property. | Global
`start_replication_args` | The arguments passed to the script named by the `start_replication_script` protection group property. | Global
`stop_replication_args` | The arguments passed to the script named by the `stop_replication_script` protection group property. | Global
`switchover_args` | The arguments passed to the script named by the `switchover_script` protection group property. | Global
`takeover_args` | The arguments passed to the script named by the `takeover_script` protection group property. | Global
`local_service_password` | A password that might be needed by the scripts to perform some function on the local system that requires the entry of a password. | Local
`remote_service_password` | A password that might be needed by the scripts to perform some function on the remote system that requires the entry of a password. | Local

### Protection Group Property Descriptions

This section describes the following protection group properties:

- `add_app_rg_script` Property

- `configuration_file` Property

- `create_config_script` Property

- `remove_app_rg_script` Property

- `remove_config_script` Property

- `start_replication_script` Property

- `stop_replication_script` Property

- `switchover_script` Property

- `takeover_script` Property

#### `add_app_rg_script` Property

The script referenced by the `add_app_rg_script` property is responsible for checking that one or more application resource groups selected by the administrator are suitable for addition to the protection group. These checks might require that certain resource types be present or absent. Furthermore, the script must also set up any resource group affinities or dependencies within the confines of what is allowed by Geographic Edition. These affinities or dependencies are needed for the application resource group to produce the correct behavior.

Application resource groups must be in the unmanaged state when they are added to the configuration.

The `add_app_rg_script` is called at other points within the protection group life cycle, not just on the addition of application resource groups, to ensure that application resource groups continue to conform to the required rules. The script should be written to ensure that these rules are met at all times.

Resource groups are offline and unmanaged on the standby site so certain application resource groups that represent services with embedded data replication might be unsuitable for addition to the protection group directly. An example is database data replication such as MySQL and Oracle RAC. The `add_app_rg_script` script must accommodate such validation.

The script must also be able to validate the `add_app_rg_args` property supplied to it with the `validate_parameters=true`option without actually performing any of the steps associated with this task. This operation is called only at the time of protection group update and creation, as opposed to at the time of device group update, modification, or validation.

When executed with `validate_parameters=false`, the script must perform any task required to add the resource groups listed in the final comma-separated `rgList` parameter. These actions might include altering one or more of these resource group properties. The script is called on the local cluster to where the `geopg add-resource-group` command is run and called asynchronously on the remote cluster in response to the internal application resource group table being updated.

For example, if `add_app_rg_script =` `/var/tmp/addRGs`and `add_app_rg_args =` `-u root -d /mydir`, the resulting command looks like the following example:

    # /var/tmp/addRGs -u root -d /mydir function=add_application_rgs \
    validate_parameters=true|false \
    currentRole=PRIMARY|SECONDARY pg=pgName \
    rgList=rg1,rg2,rg3,...

where the `rgList` parameter is the comma-separated list of application resource groups that the administrator has opted to add. The script is not responsible for creating these resource groups. Instead, the resource groups must already exist on both clusters. Furthermore, these resource groups must have the `auto_start_on_new_cluster` property set to `false`.

The function name for this step is `add_application_rgs`.

#### `configuration_file` Property

The `configuration_file` property specifies the file name of the configuration file used to drive the execution of replicated component-level scripts described in Plug-In Script Functional Requirements. Because individual script-based plug-ins inside a protection group might be on disjoint node sets or individual nodes, you should call the user scripts only on the appropriate cluster node or nodes. For more information, see Plug-In Script Functional Requirements.

The configuration file must exist on all cluster nodes on both the primary and standby clusters. The script-based plug-in module tries to read the file from each node in turn until it finds a readable copy, but makes no effort to determine whether all copies are identical.

The format of the configuration file is as follows:

    SBP-configuration-name|nodes-that-must-succeed-running-script|comma-separated-node-list

For example:

    foo.com|any|phys-node1,phys-node2 bar.com|all|phys-node1,phys-node3 baz.com|any|phys-node4 boo|any|phys-node4 biff|all|phys-node2

The script-based plug-in configuration name field must match the name of the replicated component being added to the protection group through the `geopg add-device-group` command.

For `foo.com`, a particular function step is tried on `phys-node1` and then, if it fails on `phys-node2`. The function step can succeed on either node. This configuration assumes that the service is a multi-node service like Oracle RAC.

For `bar.com`, a particular function step must succeed on both `phys-node1` and `phys-node3` for the step to complete. Again, this configuration is only relevant to multi-node services like Oracle RAC. This function step enables a script to perform a task on multiple nodes without needing to connect to a remote node using `rsh` or `ssh` between the nodes.

#### `create_config_script` Property

The script referenced by the `create_config_script` property is responsible for creating, modifying, and validating a script-based plug-in configuration. The script must be able to validate the `create_config_args` property supplied to it with the `validate_parameters=true` option without actually performing the configuration creation.

When executed with `validate_parameters=false`, the script must create a replication group and an associated replication resource for the particular script-based plug-in. There must be only one replication resource group per script-based plug-in protection group and only one replication resource per replicated component. For example, a configuration with two script-based plug-in protection groups (`hr-pg` and `sales-pg`), each with two replicated components (`hr-west` and `hr-east` for `hr-pg`, and `sales-north` and `sales-south` for `sales-pg`), would have two resource groups (`hr_pg_rep-rg` and `sales_pg-rep-rg`). These resource groups would then have the following two resources:

- `hr_west-rep-rs` and `hr_east-rep-rs` in `hr_pg-rep-rg`

- `sales_north-rep-rs` and `sales_south-rep-rs` in `hr_pg-rep-rg`

When creating the second replicated component or validating either configuration, the script must handle the case where the resource group already exists.

On completion, the script must write the resource group name and resource to standard output. This task is checked by the script-based plug-in framework to both validate that the objects exist and to set up the appropriate notification handling for state change events. The format for the output is as follows:

    reprg=replication-resource-group-name
    reprs=replication-resource-name

For example, for the case where the replication resource group is called `hr_pg-rep-rg`and the replication resource is called `hr_west-rep-rs`, the output would be as follows:

    reprg=hr_pg-rep-rg
    reprs=hr_west-rep-rs

The script must also write a list of resource groups to standard output that it has either created, or that exist already, or that it considers internal to the protection group. The format of the output must be as follows, with a carriage return at the end of the line:

    rglist=comma-separated-list-of-rgs

For example, for the case where `foo-rg` and `bar-rg` are internal, the output would be as follows:

    rglist=foo-rg,bar-rg

If no resource groups exist, the output would be as follows:

    rglist=

Examples of such internal resource groups are the lightweight resource groups in the AVS module or the shadow RAC proxy server resource groups in the Oracle Data Guard module.

This script is called for each script-based plug-in created in any specific protection group because `create_config_script` is a global protection group property. For example, if a protection group has script-based plug-in configurations `foobar.com` and `baz.com`, the `create_config_script` script is called once when `foobar.com` is added with the `create_config_args` property given for the `foobar.com` property. The script is later called for `baz.com` when it is added to the protection group with the `baz.com` `create_config_args` property value. This process results in a replication resource group with two resources: one resource monitoring `foobar.com` replication and the other resource monitoring `baz.com`.

If the protection group is known to both the primary and standby sites, then adding the script-based plug-in configuration to the protection group will cause the `create_config_script` script to be executed on the site that the `geopg` command is run from and then on the remote site as a result of the internal Oracle Solaris Cluster Geographic protection group table transfer. The latter step happens asynchronously.

The `create_config_script` script is called with the `create_config_args` property followed by the standard command-line arguments and an additional `isModify` parameter. This parameter is set to `false`when the command has been called as a result of a `geopg create-device-group`or `geopg validate pg`command. This parameter is set to `true`when the command has been called as a result of a `geopg modify-device-group` command.

For example, if `create_config_script = /var/tmp/add` and `create_config_args = "-u root -d /mydir"`, the resulting command looks like the following example:

    /var/tmp/add -u root -d /mydir function=create_configuration \
    validate_parameters=true|false currentRole=PRIMARY|SECONDARY
    pg=pgName isModify=true|false

The function name for this step is `create_configuration`.

#### `remove_app_rg_script` Property

The script referenced by the `remove_app_rg_script` property is responsible for removing one or more application resource groups, selected by the administrator, from the protection group. A comma-separated list of resource groups to remove is passed to the script through the `rgList` parameter. The script is called on the local cluster to where the `geopg remove-resource-group` command is run and called asynchronously on the remote cluster in response to the internal application resource group table being updated.

The script must also be able to validate the `remove_app_rg_args` property supplied to it with the `validate_parameters=true` option without actually performing any of the steps associated with this task. This operation is called only at the time of protection group update and creation, as opposed to at the time of device group update, modification, or validation.

For example, if `remove_app_rg_script =` `/var/tmp/removeRGs` and `remove_app_rg_args =` `"-u root -d /mydir"`, the resulting command looks like the following example:

    #/var/tmp/removeRGs -u root -d /mydir\
        function=remove_application_rgs \
        validate_parameters=true|false \
        currentRole=PRIMARY|SECONDARY pg=pgName\
        rgList=rg1,rg2,rg3,...

where the `rgList` parameter is the comma-separated list of application resource groups that the administrator has opted to remove. The script is not responsible for removing these resource groups, only for making the necessary changes to their properties that might be required as a result of removing them from Geographic Edition protection group control.

The function name for this step is `remove_application_rgs`.

#### `remove_config_script` Property

The script referenced by the `remove_config_script` property is responsible for reversing the work of the `create_config_script` script. The script must be able to validate the `remove_config_args` property supplied to it with the `validate_parameters=true` option without actually performing the configuration removal.

When executed with `validate_parameters=false`, the script must remove the replication resource (originally named by the `create_config_script` script `reprs=` output for the specific script-based plug-in) from the replication resource group given by the `create_config_script` script `reprg=` output. If the resource is the last in the resource group, the script must also remove the resource group.

For example, if `remove_config_script = /var/tmp/remove and remove_config_args = "-u root -d /mydir"`, the resulting command looks like the following example:

    # /var/tmp/remove -u root -d /mydir function=remove_configuration \
        validate_parameters=true|false \
        currentRole=PRIMARY|SECONDARY pg=pgName

The function name for this step is `remove_configuration`.

#### `start_replication_script` Property

The script referenced by the `start_replication_script` property is responsible for starting the data replication process and enabling the replication resource that is used to monitor the replication. The script must also be able to validate the `start_replication_args` property supplied to it with the `validate_parameters=true` option without actually starting the data replication.

When executed with `validate_parameters=false`, the script must start the actual data replication and enable the replication resource that is used to monitor the replication.

For example, if `start_replication_script =` `/var/tmp/start` and `start_replication_args =``"-u root -d /mydir"`, the resulting command looks like the following example:

    # /var/tmp/start -u root -d /mydir function=start_replication \
        validate_parameters=true|false \
        currentRole=PRIMARY|SECONDARY pg=pgName

The `start_replication_script` script is called on one or both clusters depending on which of the following commands the administrator specifies:

For local clusters only:

    # geopg start -e local pgname      # local cluster only

For both clusters:

    # geopg start -e global pgname     # both clusters

The function name for this step is `start_replication`.

#### `stop_replication_script` Property

The script referenced by the `stop_replication_script` property is responsible for stopping the data replication process and disabling the replication resource that is used to monitor the replication. The script must also be able to validate the `stop_replication_args` property supplied to it with the `validate_parameters=true` option without actually starting the data replication.

When executed with `validate_parameters=false`, the script must stop the actual data replication and disable the replication resource that is used to monitor the replication.

For example, if `stop_replication_script =` `/var/tmp/stop` and `stop_replication_args =` `"-u root -d /mydir"`, the resulting command looks like the following example:

    # /var/tmp/stop -u root -d /mydir function=start_replication \
        validate_parameters=true|false \
        currentRole=PRIMARY|SECONDARY pg=pgName

The `stop_replication_script` script is called on one or both clusters depending on which of the following commands the administrator specifies:

For local cluster only:

    # geopg stop -e local pgname      # local cluster only

For both clusters:

    # geopg stop -e global pgname     # both clusters

The function name for this step is `stop_replication`.

#### `switchover_script` Property

The script referenced by the `switchover_script` property is responsible for two functions:

- Checking that the service is in a position to switch over

- Performing the actual data replication switchover

The second step is only performed if the first step is completed successfully, meaning that the step exits with a zero exit code. In each case, the script is called on both clusters.

The `switchover_script` script is first called on the cluster on which the `geopg switchover`command is executed. Subsequent changes in Geographic Edition status trigger an event on the remote cluster, causing the script to be executed asynchronously on that cluster, too. The arguments for the two calls are different.

For example:

If `switchover_script =` `/var/tmp/switchover` and `switchover_args =` `"-u root -d /mydir"`, the resulting command looks like the following example:

    # /var/tmp/switchover -u root -d /mydir function=check_switchover \
        validate_parameters=false currentRole=PRIMARY|SECONDARY \
        pg=pgName newRole=PRIMARY|SECONDARY

If that step succeeds:

    # /var/tmp/switchover -u root -d /mydir \
        function=perform_switchover \
        validate_parameters=false \
        currentRole=PRIMARY|SECONDARY pg=pgName \
        newRole=PRIMARY|SECONDARY

The argument `newRole` is the target role of the cluster after a successful switchover.

The function names for these steps are `check_switchover` and `perform_switchover` and just `switchover` for the `validate_parameter` step, which is called as follows:

    # Developer-switchover-program Developer-switchover-program-arguments \
        function=switchover validate_parameters=true \
        currentRole=PRIMARY|SECONDARY pg=pgName

#### `takeover_script` Property

The script referenced by the `takeover_script` property is responsible for two functions:

- Checking that the service is in a position to be taken over

- Performing the actual data replication takeover

The second step is only performed if the first step is completed successfully, meaning that the step exits with a zero exit code. In each case, the script is called on both clusters. If the original primary cluster is available, the protection group is deactivated on that cluster. Deactivation involves stopping the application resource groups.

The `takeover_script` script must be called on the standby cluster by executing the `geopg takeover` command on that cluster. The arguments for the two calls are different.

For example, if `takeover_script =` `/var/tmp/switchover` and `takeover_args =` `"-u root -d /mydir"`, the resulting command looks like the following example:

    # /var/tmp/switchover -u root -d /mydir function=check_takeover \
        validate_parameters=false currentRole=PRIMARY|SECONDARY \
        pg=pgName newRole=PRIMARY|SECONDARY

Then, if that step succeeds:

    # /var/tmp/switchover -u root -d /mydir function=perform_takeover \
        validate_parameters=false currentRole=PRIMARY|SECONDARY \
        pg=pgName newRole=PRIMARY|SECONDARY

The argument `newRole` is the target role of the cluster after a successful takeover.

The function names for these steps are `check_takeover` and `perform_takeover` and just `takeover` for the `validate_parameter` step, which is called as follows:

    # Developer-takeover-program Developer-takeover-program-arguments> \
    function=takeover validate_parameters=true \
        currentRole=PRIMARY|SECONDARY pg=pgName

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