JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris Cluster Geographic Edition System Administration Guide
search filter icon
search icon

Document Information

Preface

1.  Introduction to Administering the Geographic Edition Software

2.  Before You Begin

3.  Administering the Geographic Edition Infrastructure

4.  Administering Access and Security

5.  Administering Cluster Partnerships

6.  Administering Heartbeats

7.  Administering Protection Groups

8.  Monitoring and Validating the Geographic Edition Software

9.  Customizing Switchover and Takeover Actions

10.  Script-Based Plug-Ins

Overview of Geographic Edition Script-Based Plug-Ins

Advantages and Disadvantages of Using Script-Based Plug-Ins

Script-Based Plug-In Architecture

Restrictions of Script-Based Plug-Ins

Ways to Create Script-Based Plug-Ins

Property Descriptions for Script-Based Plug-Ins

Protection Group Properties - Overview

Replicated Component Properties - Overview

Protection Group Property Descriptions

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

Internals for Script-Based Plug-Ins

Plug-In Script Functional Requirements

Plug-In Script Argument Validation

Standardized Script Command-Line Arguments

Script-Based Plug-In Replication Resource Groups and Resources

Protection Group Status Mapped from Replication Resource Status

How Geographic Edition Handles Password Properties

A.  Standard Geographic Edition Properties

B.  Legal Names and Values of Geographic Edition Entities

C.  Disaster Recovery Administration Example

D.  Takeover Postconditions

E.  Troubleshooting Geographic Edition Software

F.  Deployment Example: Replicating Data With MySQL

G.  Error Return Codes for Script-Based Plug-Ins

Index

Property Descriptions for Script-Based Plug-Ins

This section contains the following information:

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:

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

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=trueoption 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/addRGsand 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:

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-rgand 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 falsewhen the command has been called as a result of a geopg create-device-groupor geopg validate pgcommand. This parameter is set to truewhen 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:

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 switchovercommand 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:

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