geomg - create or manage multigroups
/usr/cluster/bin/geomg [subcommand] -?
/usr/cluster/bin/geomg -V
/usr/cluster/bin/geomg add-protection-group protection-group-list multigroup
/usr/cluster/bin/geomg create -s site [[-p name=value] [-p …]] multigroup
/usr/cluster/bin/geomg delete [-f] multigroup
/usr/cluster/bin/geomg list [-s site[,…]]
/usr/cluster/bin/geomg remove-protection-group protection-group-list multigroup
/usr/cluster/bin/geomg set-prop -p name=value [-p…] multigroup
/usr/cluster/bin/geomg show [-s site[,…]] [multigroup […]]
/usr/cluster/bin/geomg start -e {local | global} [-f] [-n] multigroup
/usr/cluster/bin/geomg status [-v] [-s site[,…]] multigroup[,…]
/usr/cluster/bin/geomg stop -e {local | global} [-f] [-D] multigroup
/usr/cluster/bin/geomg switchover [-u] [-i] [-f] -s site multigroup
/usr/cluster/bin/geomg takeover [-f] -s site multigroup
/usr/cluster/bin/geomg update cluster multigroup
/usr/cluster/bin/geomg validate multigroup
The geomg command enables you to configure and maintain multigroups. To administer an individual protection group, instead use the geopg command. See the geopg(1M) man page for more information.
Before you create a multigroup, ensure that the clusters whose protection groups will be members of the multigroup are already configured within the same site. See the geosite(1M) man page for more information about sites.
Several subcommands must be issued from a particular cluster in the site:
To run the geomg commands to create, modify, or delete a multigroup, you must run the command from a cluster that is a controller for the specified site.
To run the geomg commands to stop or start the protection groups in a multigroup, you must run the command from a cluster that is a controller for a site that is defined for the multigroup.
To run the geomg commands to switch over or take over the protection groups in a multigroup, you must run the command from a cluster that is a controller for the target site, which is defined for the multigroup.
Normally, multigroup configuration changes that are made on the issuing cluster are automatically synchronized with the other clusters in the same site as the issuing cluster. If a cluster is temporarily unavailable due to an Error or Unknown status, the cluster is autosynchronized when it returns to the OK status. If you need to manually synchronize changes, use the update subcommand.
If you have root access, you have permission to perform any operation. If you do not have root access, the following RBAC rights apply:
Basic Solaris User. You can read information about Oracle Solaris Cluster Geographic Edition (Geographic Edition) entities by running commands such as geomg list.
Geo Management. You can perform all the read operations that someone with Basic Solaris User access can perform. You can use commands like geomg create, geomg delete, and geomg start to perform administrative and configuration operations.
For more information, see the rbac (5) man page and Planning Security in Oracle Solaris Cluster 4.3 Geographic Edition Installation and Configuration Guide .
The general form of this command is as follows:
geomg [subcommand] [options] [operands]
You can omit subcommand only if options specifies the option –? or –V.
Each option of this command has a long form and a short form. Both forms of each option are given with the description of the option in the OPTIONS section of this man page.
The following subcommands are supported:
Add one or more protection groups to the specified multigroup. This subcommand must be issued from a site controller.
The system performs this action on the local cluster, then propagates the action to other clusters in the site.
Specify protection groups by using the form cluster:protection-group. Use a comma-separated list to specify multiple protection groups.
To specify a dependency between protection groups, called a dependency chain, use a slash (/) to separate the name of one or more dependent protection groups from the name of the protection group to depend on.
For example, if the pg1 protection group depends on the pg2 protection group, and both protection groups are configured on the berlin cluster, you specify them as follows:
berlin:pg1/berlin:pg2
When a switchover is performed, pg1 is stopped on its current primary partner cluster before pg2 is stopped, and pg2 is started on its new primary partner cluster before pg1 is started.
To specify the dependency of multiple protection groups to another protection group, enclose the dependent protection group names with parentheses and separate the names with commas (,). The parentheses are followed by a slash and the name of the depended-on protection group.
For example, if the pg1 and pg2 protection groups on the berlin cluster depend on the pg3 protection group on the tokyo cluster, you specify them as follows:
(berlin:pg1,berlin:pg2)/tokyo:pg3
You cannot use parentheses to enclose multiple protection group names after the slash in a dependency chain.
You can use more than one slash to set multiple dependency levels. For example, if the pg1 protection group on the berlin cluster depends on the pg2 protection group on the same cluster, and that protection group depends on the pg3 protection group on the tokyo cluster, you specify the three protection groups and their relationships as follows:
berlin:pg1/berlin:pg2/tokyo:pg3
When you add a protection group that is in a dependency chain, such as berlin:pg1/berlin:pg2, you cannot later modify or remove only one of the protection groups in that interdependency. You must instead use the remove-protection-group subcommand to remove the entire protection group interdependency from the multigroup. Then you use the add-protection-group subcommand to add back any protection groups that you had to remove but want to keep in the multigroup.
See the OPERANDS section for more information about using the slash (/) and parentheses operands to specify dependencies between protection groups in a multigroup.
Create a multigroup at the specified site. This subcommand must be issued from a site controller.
The system performs this action on the local cluster, then propagates the action to other clusters in the site.
You specify the name to assign to the new multigroup. Multigroup names must be unique throughout the site. If multiple sites share a common cluster, those sites cannot contain multigroups of the same name. If you specify the name of an existing multigroup, the operation fails with an error.
The multigroup software automatically calculates and sets an appropriate value for the multigroup Timeout property. This value is based on the Timeout property settings for the protection groups in the multigroup. The multigroup Timeout property value might be adjusted automatically by the multigroup software when protection groups are added or removed, or when the multigroup is validated. The Timeout property can also be manually set to any value that is higher than the value that is automatically calculated by the multigroup software.
Delete the specified multigroup from all clusters in the site where the multigroup is configured. This subcommand must be issued from a site controller.
The system performs this action on the local cluster, then propagates the action to other clusters in the site where the multigroup is configured.
When used with the –f option, the multigroup is deleted even if the multigroup still contains any protection groups. Protection group status and state are not affected by multigroup deletion.
Display defined multigroups on one or more sites where the current cluster is a site controller or site member.
The issuing cluster must be a member of each specified site. This subcommand can be issued from a site controller or a site member.
If you omit the –s option, the list subcommand displays information for all multigroups that are configured on all sites to which the local cluster belongs.
Remove one or more specified protection groups from the specified multigroup. This subcommand must be issued from a site controller.
The system performs this action on the local cluster, then propagates the action to other clusters in the site.
Specify protection groups by using the form cluster:protection-group. Use a comma-separated list to specify multiple protection groups.
If the protection group to remove is configured in a dependency chain, such as (cluster:pg1,cluster:pg2)/cluster:pg3, specify the entire dependency chain. Then use the add-protection-group subcommand to add back those protection groups that you want to continue as part of the multigroup, including any dependency relationship, such as cluster:pg1/cluster:pg3.
Modify the properties of the specified multigroup. This subcommand must be issued from a site controller. The system performs this action on the local cluster, then propagates the action to other clusters in the site.
Changes are automatically propagated to all clusters in the site where the multigroup exists. If a change is not automatically propagated, use the validate subcommand to manually synchronize the changes. If necessary, also use the update subcommand.
See the EXTENDED DESCRIPTION section for descriptions of multigroup properties.
Display configuration information for one or more specified multigroups in each specified site. This subcommand can be issued from a site controller or a site member.
Start all protection groups in the specified multigroup with the specified scope of global or local partner clusters. This subcommand must be issued from a site controller.
The –e option specifies the scope for starting the protection groups. For both of the following scopes, each protection group is started from the cluster that is specified in the protection-group list of the multigroup:
With the –e global option, starts each protection group on both partner clusters where the protection group is configured
With the –e local option, starts each protection group only on the local partner cluster
See the WARNINGS section of this man page for information about site synchronization errors that might interfere with the operation of this subcommand.
If the –f option is used, any protection groups that are already started are skipped. If a protection group in a dependency chain is already started, the dependencies in the dependency chain are ignored.
If the –n option is used, data replication is not started.
Show the status of one or more specified multigroups to which the issuing cluster belongs. This subcommand can be issued from a site controller or a site member.
When used with the –v option, the subcommand also displays status details for each protection group in the multigroup.
When used with the –s option, the subcommand displays the status of one or more specified multigroups in each specified site to which the issuing cluster belongs.
Use a comma-separated list to specify multiple multigroups.
Stop all protection groups of the specified multigroup with the specified scope of global or local partner clusters. This subcommand must be issued from a site controller.
The –e option specifies the scope for stopping the protection groups. For both of the following scopes, each protection group is stopped on the cluster that is specified in the protection-group list of the multigroup:
With the –e global option, stops each protection group on both partner clusters where the protection group is configured
With the –e local option, stops each protection group only on the local partner cluster
If the –f option is used, any protection groups that are already stopped are skipped. If a protection group in a dependency chain is already stopped, the dependencies in the dependency chain are ignored.
If the –D option is used, only data replication is stopped. The application resource groups are not stopped.
See the WARNINGS section of this man page for information about site synchronization errors that might interfere with the operation of this subcommand.
Switches over the primary role for all protection groups in the specified multigroup to the specified site. This subcommand must be issued from a site controller cluster where the multigroup is defined.
The protection groups in the multigroup must already be started before you issue the switchover subcommand.
See the WARNINGS section of this man page for information about site synchronization errors that might interfere with the operation of this subcommand.
Performs a takeover of each protection group in the multigroup to force the protection group to become primary on the cluster in the site. This operation is not the same as a switchover.
Run the geomg takeover command only in situations when the primary partner cluster is not available or during unplanned downtime. The situation must justify a potential loss of data and the time required to repair and to reactivate the multigroup on the standby partner cluster in the site.
This subcommand must be issued from a site controller cluster where the multigroup is defined.
For each protection group in the multigroup, if the partner cluster is unreachable, the cluster in the site becomes primary without considering the partner cluster state.
For each protection group in the multigroup, if the cluster in the site can communicate with its partner cluster, the Geographic Edition software switches the role of the protection group, so that the cluster in the multigroup's site becomes the new primary partner cluster, if it is not already the primary. Each protection group in the multigroup is deactivated on its new standby partner cluster.
If used with the –f option, the operation proceeds even if the primary cluster for any protection group in the multigroup is still reachable and the protection group is active on that cluster.
After the geomg takeover command successfully completes, reactivating each protection group in the multigroup on its new standby cluster might require that you recover and synchronize data.
See the WARNINGS section of this man page for information about site synchronization errors that might interfere with the operation of this subcommand.
Resynchronize the multigroup configuration information in the local cluster with multigroup configuration information from the specified remote cluster of the same site. This subcommand can be issued from a site controller or a site member.
When the update subcommand is issued, it retrieves the configuration from the specified cluster and updates the configuration information on the local cluster with the retrieved configuration information.
If the local cluster is a site controller, the new local configuration information is propagated to all remote clusters. The remote clusters either accept the new configuration copy or reject it, depending on their synchronization status with the site controller that is propagating the configuration update.
See the geoadm(1M) man page for information about the multigroup synchronization statuses.
Manually validate and synchronize all clusters where the specified multigroup is active. This subcommand can be issued from a site controller or a site member.
If the validate subcommand is issued from a site controller cluster, the multigroup configuration is validated and the local copy of the configuration is updated. That updated configuration data is then propagated to the other clusters in the site. The other clusters in the site either reject or accept the new configuration data, depending on whether they are in an Error synchronization status with the site controller.
If the validate subcommand is issued from a site member cluster, the cluster retrieves validated configuration information from a controller of the site and updates only its own local copy of the configuration data. The configuration data is not propagated to any other site cluster.
The multigroup software automatically calculates and sets an appropriate value for the multigroup Timeout property, based on the current Timeout property settings for the protection groups in the multigroup.
Use the validate subcommand if multigroup changes are not correctly propagated at the time a change is made to the multigroup.
See the geoadm(1M) man page for information about the multigroup synchronization statuses.
The following options are supported:
Displays help information.
You can specify this option with or without a subcommand.
If you specify this option without a subcommand, the list of subcommands for this command is displayed.
If you specify this option with a subcommand, the usage options for the subcommand are displayed.
The question mark might be interpreted as a special character by some shells. Use quotes (–"?") or an escape character to avoid pattern matching.
Deactivates only data replication. leaving the protection groups active. This option is valid with the stop subcommand.
If you do not use this option, the entire protection group is deactivated.
To stop the protection groups in a multigroup that has already had its data replication subsystem stopped, you must run the geomg stop command again, without the –D option.
Specifies whether the command operates only on each protection group's partner cluster in the local site, using the local argument, or on both partner clusters where each protection group has been configured, using the global argument. This option is valid with the start and stop subcommands.
Forces the command to perform the operation without asking you for confirmation. This option is valid with the delete, start, stop, switchover, and takeover subcommands.
When used with geomg switchover -i, any protection groups that are not yet online on the target partner cluster are switched over, ignoring any dependencies with protection groups that are already online on the target.
When used with geomg takeover, the operation proceeds even if the primary cluster for a protection group in the multigroup is reachable and the protection group is active on that cluster.
When used with the start or stop subcommand, protection groups that are already started or stopped are ignored.
Ignores any protection groups that are already active as primary on their target cluster in the site. This option is valid with the switchover subcommand.
If the –i option is omitted and any protection groups to switch over are already active as primary on the target site, the switchover operation is refused.
Using the –i option might break dependencies between two protection groups. This can happen if, on the target partner cluster, a dependent protection group is already online as primary but the protection group it depends on is not yet online as primary on the site.
Use the –f option with the –i option to switch over those dependency protection groups that are not yet online as primary on the site but to ignore dependent protection groups that are already online as primary on the site. The dependency order is still followed for any other protection groups that do not have such dependency breakage issues.
Specifies to not start data replication when the protection groups in the multigroup are started. This option is valid with the start subcommand.
If the –n option is omitted, when protection groups in a multigroup are started, data replication also starts.
Sets a property of the specified multigroup. This option is valid with the set-prop subcommand.
A multigroup property is assigned a value by using a name=value pair statement. You can set multiple properties in a single command by using multiple –p statements.
See the EXTENDED DESCRIPTION section for defined properties.
Specifies the name of the site where the specified multigroup is configured. This option is valid with the create, list, show, status, switchover, and takeover subcommands.
Specifies running the operation in an unsynchronized manner. This option is valid with the switchover subcommand.
When the –u option is used, the switchover subcommand does not wait for all protection groups to be stopped on their primary partner clusters outside of the site before starting them on their standby partner clusters within the site.
Displays the version of the command.
Do not specify this option with subcommands, operands, or other options, as they are ignored. The –V option only displays the version of the command. No other operations are performed.
Displays details for each protection group in the multigroup. This option is valid with the status subcommand.
The following operands are supported:
Specifies the name of the protection group you want to administer and the cluster in which it is configured.
Specifies the name of the multigroup that you want to administer. The multigroup name must be unique throughout all clusters of the designated site.
Specifies a strong dependency in the multigroup by two or more protection groups on another protection group, which is specified after a slash.
The following shows the syntax to specify a dependency chain between two protection groups in a multigroup:
cluster:dependent-protection-group/cluster:depended-on-protection-group
For example, in the dependency chain clust1:pg1/clust1:pg2, if a switchover is issued, pg1 is stopped on its current primary partner cluster before pg2 is stopped. Then pg2 is started on its new primary partner cluster before pg1 is started.
You can specify more than one /cluster: protection-group string in a dependency chain to indicate a series of dependencies, such as clust1:pg1/clust1:pg2/clust1:pg3.
You can only specify one protection group name after a slash in a dependency chain. You cannot use parentheses to specify multiple protection group names after a slash.
In a dependency chain, encloses a set of protection groups that depend on another protection group in the same multigroup. The protection group names within the parentheses are separated by commas. The parentheses are followed by a slash (/) and the name of the protection group that is depended on.
The following shows syntax examples of dependency chains that involve more than two protection groups in the multigroup:
(cluster:protection-group1,cluster:protection-group2)/cluster:protection-group3 cluster:protection-group1/cluster:protection-group2/cluster:protection-group3
For example, in the dependency chain (clust1:pg1,clust1:pg2)/clust1:pg3, if a switchover is issued, pg1 and pg2 are both stopped on the current primary partner cluster before pg3 is stopped. Then pg3 is started on the new primary partner cluster before pg1 and pg2 are started.
This section contains descriptions of properties that you can specify.
Describes the multigroup. The system sets this property on the local cluster, then propagates the value to the other clusters in the site where the multigroup is defined.
Optional
None
Assigned at creation and tunable at runtime
Specifies the timeout period for the multigroup in seconds. The timeout period is the longest time Geographic Edition waits for a geomg command to finish. If the command does not respond within the timeout period, the Geographic Edition software reports the operation as timed out, even if the underlying command eventually completes successfully.
The timeout period applies to operations on a per-cluster basis. An operation with a local scope times out if the operation is not completed after the specified timeout period.
An operation with a global scope consists of an action on the local cluster and an action on the remote cluster. The local and remote actions are timed separately. So, an operation with a global scope times out if the local operation is not completed after the specified timeout period or if the remote operation is not completed after the specified timeout period.
For example, the following command is started with a local scope:
# geomg start -e local multigroup
If you set the Timeout property to 3000 seconds, the geomg start command times out if the operation does not complete after 3000 seconds.
You can start the same command with a global scope as follows:
# geomg start -e global multigroup
If the Timeout property is set to 3000 seconds, the geomg start command times out if the operation is not completed on the local cluster after 3000 seconds or if the operation is not completed on the remote cluster after 3000 seconds. If the local action takes 1500 seconds and the remote action takes 1500 seconds, the operation is not timed out.
The multigroup timeout value is a per-operation timeout.
Optional
120 seconds
1000000 seconds
120 seconds
Assigned at creation and tunable at runtime
The following exit values are returned:
The command completed successfully.
An error occurred.
The following geomg command creates the multigroup london-paris-mg. The command is run from a node of the site controller clustercluster-soho in the site-paris site.
phys-soho-1# geomg create -s site-paris london-paris-mgExample 2 Adding a Protection Group to a Multigroup
The following geomg command adds the protection groups sales-pg and finance-pg on the cluster-soho cluster to the london-paris-mg multigroup. The command configures the sales-pg protection group with a strong dependency on the finance-pg protection group.
phys-soho-1# geomg add-protection-group cluster-soho:sales-pg/cluster-soho:finance-pg \ london-paris-mgExample 3 Starting Protection Groups in a Multigroup
The following geomg command starts the local member protection groups of the london-paris-mg multigroup.
phys-soho-1# geomg start -e local london-paris-mgExample 4 Performing a Switchover of a Multigroup
The following geomg command switches over all protection groups in the london-paris-mg multigroup to the site-paris site. The command ignores any protection group that is already active on the site-paris site. The cluster-louvre cluster is a controller of the site-paris site.
phys-louvre-1# geomg switchover -i -s site-paris london-paris-mgExample 5 Performing a Takeover of a Multigroup
The following geomg command performs a takeover by the site-paris site of all protection groups in the london-paris-mg multigroup. The cluster-louvre cluster is a controller of the site-paris site.
phys-louvre-1# geomg takeover -s site-paris london-paris-mgExample 6 Removing a Protection Group That Has No Dependency With Another Protection Group
The following geomg command removes from the london-paris-mg multigroup the hr-pg and finance-pg protection groups on the cluster-soho cluster. The cluster-soho:hr-pg and cluster-soho:finance-pg protection groups have no dependency relationships with any other protection group in the multigroup.
phys-soho-1# geomg remove-protection-group cluster-soho:hr-pg,cluster-soho:finance-pg \ london-paris-mgExample 7 Removing From a Multigroup a Protection Group That Is in a Dependency Chain
The following geomg command removes the cluster-soho:sales-pg protection group from the longon-paris-mg multigroup. This protection group has a dependency on the cluster-soho:finance-pg protection group. Another protection group, cluster-soho:hr-pg, also has a dependency on the cluster-soho:finance-pg protection group.
The entire interdependency (cluster-soho:hr-pg,cluster-soho:sales-pg)/cluster-soho:finance-pg is removed from the multigroup. Then the cluster-soho:hr-pg and cluster-soho:finance-pg protection groups are added back in the dependency cluster-soho:hr-pg/cluster-soho:finance-pg.
phys-soho-1# geomg show london-paris-mg Multigroup: london-paris-mg Description : Site name : site-paris Protection group list : (cluster-soho:hr-pg,cluster-soho:sales-pg)/cluster-soho:finance-pg Timeout : 10800 phys-soho-1# geomg remove-protection-group \ (cluster-soho:hr-pg,cluster-soho:sales-pg)/cluster-soho:finance-pg \ london-paris-mg phys-soho-1# geomg add-protection-group \ cluster-soho:hr-pg/cluster-soho:finance-pg \ london-paris-mg phys-soho-1# geomg show london-paris-mg Multigroup: london-paris-mg Description : Site name : site-paris Protection group list : cluster-soho:hr-pg/cluster-soho:finance-pg Timeout : 7200Example 8 Modifying a Multigroup
The following geomg command modifies the timeout property of the london-paris-mg multigroup.
phys-soho-1# geomg set-prop -p Timeout=3000 london-paris-mgExample 9 Synchronizing Multigroup Configuration Information
The following geomg command resynchronizes configuration information for the london-paris-mg multigroup on the issuing cluster, cluster-soho, with information from the remote cluster, cluster-louvre, where the multigroup also exists.
phys-soho-1# geomg update cluster-louvre london-paris-mgExample 10 Deleting a Multigroup
The following geomg command deletes the london-paris-mg multigroup.
phys-soho-1# geomg delete london-paris-mg
See attributes (5) for descriptions of the following attributes.
|
geoadm(1M), geohb(1M), geopg(1M), geops(1M), geosite(1M), rbac (5)
This section describes the error conditions between the issuing site controller cluster and another cluster in the site that prevent start, stop, switchover, and takeover operations from succeeding.
If another site controller cluster has an Error synchronization status for the multigroup with the issuing site controller, the operation completely errors out.
If a site member cluster has an Error synchronization status for the multigroup with the issuing site controller, the operation is not performed on those protection groups in the multigroup that are present on that member cluster.
However, in the extreme case of a takeover, this rule does not apply. The operation still tries to perform takeover on those protection groups in the multigroup that are present on that member cluster.
If a cluster in the site has an Unknown synchronization status for the multigroup with the issuing site controller, the operation is not performed on those protection groups in that multigroup that are present on that cluster.
An attempt is still made to perform an operation on those protection groups in the multigroup that are on clusters with an Ok synchronization status.
To help avoid such errors, perform the following checks of the site before you issue a start, stop, switchover, or takeover operation on a multigroup:
Ensure that the issuing site controller is accepted by all other site clusters for the multigroup as a site controller.
Ensure that the synchronization status of all site clusters and all multigroups for the site is Ok. The exception is a cluster that is down or on which the Geographic Edition framework is not started, which causes the Unknown status, and you do not intend to perform the operation on the protection groups on that cluster.