cm_ctl

cm_ctl is a tool provided by openGauss to control database instance services. This tool is called by O&M personnel for automatic database instance service restoration. cm_ctl provides the following functions:

Starts database instance services, all the instances in an AZ, all instances on a single host, or a single instance process.
Stops database instance services, all instances in an AZ, all instances on a single host, or instance processes on a single node.
Restarts the logical database instance service.
Queries the database instance status or the status of a single host.
Switches over the primary and standby instances or resets the instance status.
Rebuilds the standby node.
Views the database instance configuration file.
Sets the log level, the arbitration mode of cm_server when one primary and multiple standby database instances are deployed, and the switchover mode between AZs.
Obtains the log level, the arbitration mode of cm_server when one primary and multiple standby database instances are deployed, and the switchover mode between AZs.
Checks the status of an instance process.

Files related to the cm_ctl tool:

cluster_manual_start
This is a flag file for starting and stopping a database instance. The file is stored in $GAUSSHOME/bin, where GAUSSHOME is an environment variable. When the database instance is started, the cm_ctl tool deletes the file. When the database instance is stopped, the cm_ctl tool generates the file and writes the stop mode to the file.
instance_manual_start_X (X indicates the instance ID.)
This is a flag file of starting and stopping a single instance. The file is stored in $GAUSSHOME/bin, where GAUSSHOME is an environment variable. When starting the instance, cm_ctl deletes the file. When stopping the instance, cm_ctl generates the file and writes the stop mode to the file.

cm_ctl constraints:

In cluster mode, the cm_ctl tool instead of the gs_ctl tool is used to switch the database role.

Command Description

cm_ctl uses the following options:

Commands of options
Common options
Options of start
Options of switchover
Options of build
Options of check
Options of stop
Options of query
Options of view
Options of set and Options of set cm
Options of get
Options of setrunmode
Options of changerole
Options of changemember
Options of reload
Options of list
Options of encrypt
Options of ddb
Options of switch
Options of res

Usage:

cm_ctl start [-z AVAILABILITY_ZONE [--cm_arbitration_mode=ARBITRATION_MODE]] | [-n NODEID [-D DATADIR]] [-t SECS]
cm_ctl switchover [-z AVAILABILITY_ZONE] | [-n NODEID -D DATADIR [-f]] | [-a] | [-A] [-t SECS]
cm_ctl finishredo
cm_ctl build [-c] [-n NODEID] [-D DATADIR [-t SECS] [-f] [-b full] [-j NUM]]
cm_ctl check -B BINNAME -T DATAPATH
cm_ctl stop [[-z AVAILABILITY_ZONE] | [-n NODEID [-D DATADIR]]] [-t SECS] [-m SHUTDOWN-MODE]
cm_ctl query [-z ALL] [-l FILENAME] [-v [-C [-s] [-S] [-d] [-i] [-F] [-x] [-p]] | [-r]] [-t SECS] [--minorityAz=AZ_NAME]
cm_ctl view [-v | -N | -n NODEID] [-l FILENAME]
cm_ctl set [--log_level=LOG_LEVEL] [--cm_arbitration_mode=ARBITRATION_MODE] [--cm_switchover_az_mode=SWITCHOVER_AZ_MODE] [--cmsPromoteMode=CMS_PROMOTE_MODE -I INSTANCEID]
cm_ctl set --param --agent | --server [-n [NODEID]] -k [PARAMETER]="[value]"
cm_ctl get [--log_level] [--cm_arbitration_mode] [--cm_switchover_az_mode]
cm_ctl setrunmode -n NODEID -D DATADIR  [[--xmode=normal] | [--xmode=minority --votenum=NUM]]
cm_ctl changerole [--role=PASSIVE | --role=FOLLOWER] -n NODEID -D DATADIR [-t SECS]
cm_ctl changemember [--role=PASSIVE | --role=FOLLOWER] [--group=xx] [--priority=xx] -n NODEID -D DATADIR [-t SECS]
cm_ctl reload --param [--agent | --server]
cm_ctl list --param --agent | --server
cm_ctl encrypt [-M MODE] -D DATADIR
cm_ctl ddb DCC_CMD
cm_ctl switch [--ddb_type=[DDB]] [--commit] [--rollback]

Table 1 Commands of options

Command	Description
start	Starts the database instance service, all instances on a single host, instance processes on a single node, or the entire AZ when one primary database and multiple standby databases are deployed.
switchover	Switches over the primary and standby database instances when one primary database and multiple standby databases are deployed. In DCF mode, the -n NODEID and -D DATADIR parameters are not supported.
finishredo	Stops the playback on all standby nodes, and forcibly promotes one of the shards to primary. Note: Setting this parameter is a high-risk operation. Exercise caution when performing this operation.
build	Rebuilds a standby instance.
check	Checks the running status of an instance process. You are not advised to use this one.
stop	Stops the database instance service, all instances on a single host, or the instance processes on a single node when one primary database and multiple standby databases are deployed.
query	Queries the database instance status or the status of a single host when one primary database and multiple standby databases are deployed.
view	Views the database instance configuration file.
set	Sets the log level, the arbitration mode of cm_server when one primary database and multiple standby databases are deployed, the switchover mode between AZs, and the promotion mode to primary of cm_server.
set --param	Sets CM parameters. By default, parameters on all nodes are set. You can also use the -n option to set parameters on a node. For details about the parameters, see CM Parameters.
get	Obtains the log level, the arbitration mode of cm_server when one primary database and multiple standby databases are deployed, and the switchover mode between AZs.
setrunmode	Sets the number of DCF votes in DCF deployment mode. This is used for forcible DCF startup.
changerole	Changes the primary role to passive or follower in the DCF mode.
changemember	Changes the attributes of a DCF node in DCF mode, including the role, logical group, and election priority of the node.
reload	Loads the static configuration file of a database instance online. You are not advised to use this one.
reload --param	Loads CM parameters that can take effect dynamically. Some parameters cannot be reloaded and can take effect only after the CM is restarted.
list	Lists all parameters of cm_agent or cm_server.
encrypt	Encrypts an entered password. The password can contain 8 to 15 characters and must contain at least three types of the following characters: digits, letters, and symbols.
ddb	Runs the DCC command in DCC mode.
switch	Switches to the DDB mode. Note: Currently, openGauss can be switched only to the DCC mode. Note: Currently, the Currently, openGauss can be switched only to the DCC mode.
res	Adds, modifies, queries, and deletes resource configurations on a node.
show	Shows the network connectivity of DNs in the cluster and the connectivity of shared disk on each node. Note: 1. The HAIP addresses of DNs are used for node connectivity. 2. To check the connectivity of shared disks, ensure that the voting_disk_path parameter is configured on each CM Agent. Otherwise, the shared disk is disconnected by default.

Table 2 Common options

Option	Description
-D DATADIR	Specifies the instance data directory. This is used only to perform operations on database nodes, such as start, stop, switchover, build, setrunmode, changerole, changemember and encrypt.
-l FILENAME	Outputs the result to a specified file. This is used only for query, such as query and view.
-n NODEID	Specifies a node.
-z AVAILABILITY_ZONE	Specifies the AZ name.
-t SECS	Specifies the timeout period.
-V, --version	Prints the cm_ctl version and exits.
-?, -h,--help	Displays help information about cm_ctl command-line options and exits.

NOTE:
The common options listed here may not be applicable to all commands. For details about how to use the common options, see the preceding description. You can also run the cm_ctl --help command to query the common options.

Table 3 Options of switchover

Option	Description
-a	Restores nodes to their initial status.
-A	Switches all node instances from primary to standby.
-f	Specifies a type of switchover.
-z	Switches the host to the AZ specified by the -z parameter. Note: Switchover is performed for maintenance. Before a switchover, ensure that the cluster is running properly, all services are stopped, and the pgxc_get_senders_catchup_time() view shows no ongoing catchup between the primary and standby nodes.

Table 4 Options of build

Option	Description
-f	Forcibly rebuilds a standby node.
-b full	Performs a full build. If this parameter is not specified, automatic build is performed for the deployment mode of one primary database instance and multiple standby database instances. auto build: calls the incremental build first and calls the full build after the incremental build fails.
-c	Rebuilds cm_server (by copying the DCC data directory on the primary node to the specified node. This method is applicable only to the scenario where there are one primary node and one standby node.)

Table 5 Options of check

Option	Description
-B BINNAME	Specifies the name of a process, which can be cm_agent, gaussdb, or cm_server.
-T DATAPATH	Specifies the instance data directory.

Table 6 Options of stop

Option	Description
-m SHUTDOWN-MODE	Specifies the stop mode. The values are as follows: smart (s): All database instances exit after user services end. fast (f): The specified database instance exits without waiting for the user service to end. immediate (i): The specified database instance is forced to exit without waiting for the user service to end.
-I	Specifies the ID of the resource instance to be stopped. You can run the cm_ctl query -Cv command to view the mapping between resource instances and instance IDs.

Option

Description

-m SHUTDOWN-MODE

Specifies the stop mode. The values are as follows:

smart (s): All database instances exit after user services end.
fast (f): The specified database instance exits without waiting for the user service to end.
immediate (i): The specified database instance is forced to exit without waiting for the user service to end.

-I

Specifies the ID of the resource instance to be stopped. You can run the cm_ctl query -Cv command to view the mapping between resource instances and instance IDs.

Table 7 Options of query

Option	Description
-s	Displays instances that result in unbalanced primary and standby instance quantity on each host. Note: The -s option must be used together with -v and -C so that instances that result in unbalanced primary and standby instance quantity on each host can be displayed in pairs. When -s is used, -C and -v must be specified.
-C	Displays the database instance status in pairs based on the primary and standby relationship. Note: The -C option must be used together with -v to display detailed database instance status information in pairs based on the primary and standby relationship. When -C is used, -v must be specified.
-v	Displays the detailed database instance status. Note: A database instance can be in any of the following states: Normal: indicates that the database instance is available and data is backed up. All the processes are running and the primary-standby relationship is normal. Degraded: The database instance is available, but data is not backed up. Unavailable: The database instance is unavailable.
-d	Displays the instance data directory. Note: The -d option must be used together with -v and -C.
-i	Displays the IP address of the physical node. Note: The -i option must be used together with -v and -C.
-F	Displays the Fenced UDF status of each node. Note: The -F option must be used together with -v and -C to display the fenced UDF status of each node. When -F is used, -C and -v must be specified.
-z ALL	Displays the name of the AZ where the database instance is located. Note: The -z option must be used together with -v and -C, and must be followed by ALL.
-r	Displays the redo status of the standby node. Note: When -r is used, the -v must be specified.
-g	Displays information about cluster backup and restoration.
-x	Displays all abnormal database instances. Note: The -x option must be used together with -v and -C.
-S	Displays the status check result when the database instance is started. Note: The -S option must be used together with -v and -C to display the database instance status check result. The values are as follows: Normal: The database instance is available and data is backed up. All the processes are running and the primary-standby relationship is normal. Degraded: The database instance is available, but data is not backed up. Unavailable: The database instance is unavailable.
--minorityAz	Queries the CMS in a specified AZ. Note: This ignores the CMS nodes in non-specified AZs and can improve the query speed in few scenarios.
-p	Displays the ports of all database instance nodes. Note: The -p option must be used together with -v and -C.

Table 8 Options of set

Option	Description
--log_level=LOG_LEVEL	Sets the log level of the primary cm_server. Six log levels are included: DEBUG5, DEBUG1, WARNING, LOG, ERROR, and FATAL, in an ascending order in terms of log print level. The higher the log level, the less the output log information.
--cm_arbitration_mode=ARBITRATION_MODE	Sets the arbitration mode of cm_server when one primary node and multiple standby nodes are deployed. There are two modes: MAJORITY and MINORITY. MAJORITY indicates the majority mode, and MINORITY indicates the minority mode. openGauss does not support the MINORITY mode. This parameter can be set to MINORITY but it does not take effect.
--cm_switchover_az_mode= SWITCHOVER_AZ_MODE	Specifies whether to enable automatic switchover between AZs when one primary node and multiple standby nodes are deployed. There are two modes: NON_AUTO and AUTO. NON_AUTO indicates the non-automatic switchover mode, and AUTO indicates the automatic switchover mode. In AUTO mode, the primary cm_server automatically controls the node instance switchover between AZ1 and AZ2.
--cmsPromoteMode=CMS_PROMOTE_MODE -I INSTANCEID	Sets the promotion mode to primary of cm_server. There are two modes: AUTO and PRIMARY_F. AUTO indicates that the promotion mode to primary is automatically selected. PRIMARY_F indicates that the node specified by -I is forcibly promoted to primary, regardless of whether there is a primary node. Therefore, multiple primary cm_server may exist.

Table 9 Options of set cm

Option	Description
--param	Specifies the CM parameters to be set. If this option is not specified, the CM parameters cannot be set.
--agent \| --server	Specifies whether to set the cm_server or cm_agent parameters. This option is mandatory.
-k parameter="value"	Specifies the parameters and parameter values to be set. Only existing parameters can be set. Parameters cannot be added or deleted.

Table 10 Options of get

Option	Description
--log_level=LOG_LEVEL	Obtains the log level of the primary cm_server. Six log levels are included: DEBUG5, DEBUG1, WARNING, LOG, ERROR, and FATAL, in an ascending order in terms of log print level. The higher the log level, the less the output log information.
--cm_arbitration_mode=ARBITRATION_MODE	Obtains the arbitration mode of cm_server when one primary node and multiple standby nodes are deployed. There are two modes: MAJORITY and MINORITY. MAJORITY indicates the majority mode, and MINORITY indicates the minority mode. The MINORITY mode is applicable to the scenario where one primary database and multiple standby databases are deployed and only AZ3 is alive. In this case, cm_server can perform arbitration properly. In other modes, after the arbitration mode is set to MINORITY, the CM automatically changes the arbitration mode to MAJORITY to ensure the normal running of the cluster. The MAJORITY mode is applicable to the scenario where one primary database and multiple standby databases are deployed and the number of alive components (cm_server and nodes) is greater than half of the total. In normal cases, the database instance is in MAJORITY mode by default. Note: openGauss does not support the MINORITY mode.
--cm_switchover_az_mode =SWITCHOVER_AZ_MODE	Obtains the automatic switchover between AZs when one primary node and multiple standby nodes are deployed. There are two modes: NON_AUTO and AUTO. NON_AUTO indicates the non-automatic switchover mode, and AUTO indicates the automatic switchover mode. In AUTO mode, the primary cm_server automatically controls the node instance switchover between AZ1 and AZ2.

Option

Description

--log_level=LOG_LEVEL

Obtains the log level of the primary cm_server. Six log levels are included: DEBUG5, DEBUG1, WARNING, LOG, ERROR, and FATAL, in an ascending order in terms of log print level. The higher the log level, the less the output log information.

--cm_arbitration_mode=ARBITRATION_MODE

Obtains the arbitration mode of cm_server when one primary node and multiple standby nodes are deployed. There are two modes: MAJORITY and MINORITY. MAJORITY indicates the majority mode, and MINORITY indicates the minority mode. The MINORITY mode is applicable to the scenario where one primary database and multiple standby databases are deployed and only AZ3 is alive. In this case, cm_server can perform arbitration properly. In other modes, after the arbitration mode is set to MINORITY, the CM automatically changes the arbitration mode to MAJORITY to ensure the normal running of the cluster. The MAJORITY mode is applicable to the scenario where one primary database and multiple standby databases are deployed and the number of alive components (cm_server and nodes) is greater than half of the total. In normal cases, the database instance is in MAJORITY mode by default.

Note:

openGauss does not support the MINORITY mode.

--cm_switchover_az_mode

=SWITCHOVER_AZ_MODE

Obtains the automatic switchover between AZs when one primary node and multiple standby nodes are deployed. There are two modes: NON_AUTO and AUTO. NON_AUTO indicates the non-automatic switchover mode, and AUTO indicates the automatic switchover mode. In AUTO mode, the primary cm_server automatically controls the node instance switchover between AZ1 and AZ2.

Table 11 Options of view

Option	Description
-v	Displays the static configuration details of all nodes in the database instance. description: Compared with the cm_ctl view command, cm-server and node component IDs (for example, cmseverInstanceID and datanodeInstanceID) are added to the output of -v.
-N	Displays only the static configuration of the local node, that is, information about the node where the cm_ctl view command is executed. N indicates native.

Table 12 Options of setrunmode

Option	Description	Value Range
--xmode	Specifies the DCF running mode.	normal: normal mode. minority: minority mode. The --votenum option is required to specify the number of votes.
--votenum	Specifies the number of votes for a DCF minority run.	The value is a positive integer and cannot be greater than the total number of DCF copies.

Table 13 Options of changerole

Option	Description	Value Range
--role	Changes the primary role to passive or follower in the DCF mode.	passive: passive role follower: follower role

Table 14 Options of changemember

Option	Description	Value Range
--role	Changes the primary role to passive or follower in the DCF mode.	passive: passive role follower: follower role
--group	Changes the value of group in DCF mode.	0~2147483647
--priority	Changes the value of priority in DCF mode.	0~2147483647

Table 15 Options of start

Option	Description
--cm_arbitration_mode=ARBITRATION_MODE	Obtains the arbitration mode of cm_server when one primary node and multiple standby nodes are deployed. There are two modes: MAJORITY and MINORITY. MAJORITY indicates the majority mode, and MINORITY indicates the minority mode. The MINORITY mode is applicable to the scenario where one primary database and multiple standby databases are deployed and only AZ3 is alive. In this case, cm_server can perform arbitration properly. In other modes, after the arbitration mode is set to MINORITY, the CM automatically changes the arbitration mode to MAJORITY to ensure the normal running of the cluster. The MAJORITY mode is applicable to the scenario where one primary database and multiple standby databases are deployed and the number of alive components (cm_server and nodes) is greater than half of the total. In normal cases, the database instance is in MAJORITY mode by default. Note: openGauss does not support the MINORITY mode.
-I	Specifies the ID of the resource instance to be started. You can run the cm_ctl query -Cv command to view the mapping between resource instances and instance IDs.

Option

Description

--cm_arbitration_mode=ARBITRATION_MODE

Note:

openGauss does not support the MINORITY mode.

-I

Specifies the ID of the resource instance to be started. You can run the cm_ctl query -Cv command to view the mapping between resource instances and instance IDs.

Table 16 Options of reload

Option	Description
--param	Specifies the CM parameters to be loaded. If this parameter is not specified, the CM parameters cannot be loaded.
--agent \| --server	Specifies whether to dynamically load cm_server or cm_agent parameters.

Table 17 Options of list

Option	Description
--param	Specifies the CM parameters to be listed. This is mandatory.
--agent \| --server	Specifies the cm_server or cm_agent parameters to be listed. This is mandatory.

Table 18 Options of encrypt

Option	Description
-M	Specifies the encryption type. The value can be server or client. The default value is server.
-D	Specifies the path of the encrypted password file.

Table 19 Options of switch

Option	Description
--ddb_type=[DDB]	Select the DDB mode to be switched to. (openGauss supports only the DCC mode.)
--commit	After the switchover, the database instance cannot be promoted to primary. You need to run the commit command to restore the database instance.
--rollback	Rolls back the switchover that fails.

Table 20 Options of ddb

Option	Description
--put [key] [value]	Inserts a key-value pair to DCC. If the key-value pair already exists, the value corresponding to the key is changed.
--get [key]	Queries the value corresponding to the key in DCC.
--delete [key]	Deletes a specified key-value pair from DCC.
--prefix	You can add the prefix option after the get or delete operation to implement fuzzy query and deletion.
--cluster_info	Obtains the database instance information.
--leader_info	Obtains information about the primary node.
--help, -h	Displays the DCC command help information.
--version, -v	Displays the DCC version information.

Table 21 Options of res

Option	Description
--add --res_name=[name] --res_attr=[res_info]	Adds a resource configuration. In the command, name indicates the name of the new resource, and res_info indicates the information about the new resource.
--del --res_name=[name]	Deletes a resource configuration. name indicates the name of the deleted resource.
--edit --res_name=[name] --res_attr=[res_info]	Modifies the resource configuration. In the command, name indicates the name of the modified resource, and res_info indicates the new resource information.
--edit --res_name=[name] --add_inst=[inst_info]	Adds a resource instance. name indicates the resource name of the new instance, and inst_info indicates the information about the new instance.
--edit --res_name=[name] --del_inst=[inst_info]	Deletes a resource instance. name indicates the resource name of the deleted instance, and inst_info indicates the information about the deleted instance.
--check	Checks the resource configuration. If the configuration is improper, a warning is displayed. An error is reported only when the configuration is unavailable.

Command Reference

Start an instance.

cm_ctl start [-z AVAILABILITY_ZONE [--cm_arbitration_mode=ARBITRATION_MODE]] | [-n NODEID [-D DATADIR]] [-t SECS]

Perform a switchover between primary and standby databases.

cm_ctl switchover [-z AVAILABILITY_ZONE] | [-n NODEID -D DATADIR [-f]] | [-a] | [-A] [-t SECS]

Stop the playback on all standby nodes, and forcibly promote one of the shards to primary.
```
cm_ctl finishredo
```

Rebuild the standby node.

cm_ctl build -n NODEID -D DATADIR [-t SECS] [-f] [-b full]

Check the running status of an instance process.
```
cm_ctl check -B BINNAME -T DATAPATH
```

Stop an instance.

cm_ctl stop [[-z AVAILABILITY_ZONE] | [-n NODEID [-D DATADIR [-R]]]] [-t SECS] [-m SHUTDOWN-MODE]

Query the cluster status.

cm_ctl query [-z ALL] [-l FILENAME] [-v [-C [-s] [-S] [-d] [-i] [-F] [-x] [-p]] | [-r]] [-t SECS] [--minorityAz=AZ_NAME]

View the cluster configuration file.

cm_ctl view [-v | -N | -n NODEID] [-l FILENAME]

Set parameters.

cm_ctl set [--log_level=LOG_LEVEL] [--cm_arbitration_mode=ARBITRATION_MODE] [--cm_switchover_az_mode=SWITCHOVER_AZ_MODE]

Set CM parameters.

cm_ctl set --param --agent | --server [-n NODEID] -k "PARAMETER='value'"

Obtain parameters.

cm_ctl get [--log_level] [--cm_arbitration_mode] [--cm_switchover_az_mode]

Set the number of DCF votes.

cm_ctl setrunmode -n NODEID -D DATADIR  [[--xmode=normal] | [--xmode=minority --votenum=NUM]]

Change the DCF role information.

cm_ctl changerole [--role=PASSIVE | --role=FOLLOWER] -n NODEID -D DATADIR [-t SECS]

Change the attributes of the DCF node.

cm_ctl changemember [--role=PASSIVE | --role=FOLLOWER] [--group=xx] [--priority=xx] -n NODEID -D DATADIR [-t SECS]

Dynamically load CM parameters.

cm_ctl reload --param [--agent | --server]

List all CM parameters.

cm_ctl list --param [--agent | --server]

Perform encryption.
```
cm_ctl encrypt [-M MODE] -D DATADIR
```

Run the DCC command.

cm_ctl ddb DCC_CMD
Set: cm\_ctl ddb --put [key] [value]
Delete: cm\_ctl ddb --delete [key]
View DCC command help information: cm\_ctl ddb --help

Run the switch ddb command.

cm_ctl switch [--ddb_type=[DDB]] [--commit] [--rollback]

Run the res command.

Add a resource: cm_ctl res --add --res_name=[name] --res_attr=[res_info]
Delete a resource: cm_ctl res --del --res_name=[name]
Modify a resource: cm_ctl res --edit --res_name=[name] --res_attr=[res_info]
Add a resource instance: cm_ctl res --edit --res_name=[name] --add_inst=[inst_info]
Delete a resource instance: cm_ctl res --edit --res_name=[name] --del_inst=[inst_info]
Check resources: cm_ctl res --check