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 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/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=protection-group \
rgList=resource-group1,resource-group2,resource-group3,…
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:
script-based-plug-in-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 multinode 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 multinode 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-resource-groups
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 Availability Suite 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=protection-group 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=protection-group\
rgList=resource-group1,resource-group2,resource-group3,...
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=protection-group
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=protection-group
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 protection-group # local cluster only
For both clusters:
# geopg start -e global protection-group # 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=protection-group
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 protection-group # local cluster only
For both clusters:
# geopg stop -e global protection-group # 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=protection-group newRole={PRIMARY|SECONDARY}
If that step succeeds:
# /var/tmp/switchover -u root -d /mydir \
function=perform_switchover \
validate_parameters=false \
currentRole={PRIMARY|SECONDARY} pg=protection-group \
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=protection-group
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=protection-group 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=protection-group 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=protection-group