Skip Navigation Links | |
Exit Print View | |
![]() |
Oracle Solaris Cluster Geographic Edition System Administration Guide Oracle Solaris Cluster 4.0 |
1. Introduction to Administering the Geographic Edition Software
3. Administering the Geographic Edition Infrastructure
4. Administering Access and Security
5. Administering Cluster Partnerships
7. Administering Protection Groups
8. Monitoring and Validating the Geographic Edition Software
9. Customizing Switchover and Takeover Actions
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
start_replication_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
E. Troubleshooting Geographic Edition Software
This section contains the following information:
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 F, 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
|
The Protection Group 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 Arguments explains how scripts can discriminate between the steps being performed.
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 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
|
This section describes the following protection group properties:
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 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.
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.
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-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.
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.
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.
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.
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.
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 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
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