Introduction to the cm_ctl Tool

cm_ctl is a tool provided by MogDB to control database instance services. This tool is called by O&M personnel for automatic database instance service restoration. The cm_ctl tool 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. This 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 for starting and stopping a single instance. This file is stored in $GAUSSHOME**/bin**, where GAUSSHOME is an environment variable. When the instance is started, the cm_ctl tool deletes the file. When the instance is stopped, the cm_ctl tool 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

The cm_ctl tool can use the following types of parameters:

Parameters for option. For details, see Parameters for option.
Common parameters. For details, see Common parameters.
Parameters for start. For details, see Parameters for start.
Parameters for switchover. For details, see Parameters for switchover.
Parameters for build. For details, see Parameters for build.
Parameters for check. For details, see Parameters for check.
Parameters for stop. For details, see Parameters for stop.
Parameters for query. For details, see Parameters for query.
Parameters for view. For details, see Parameters for view.
Parameters for set. For details, see Parameters for set and Parameters for set cm.
Parameters for get. For details, see Parameters for get.
Parameters for setrunmode. For details, see Parameters for setrunmode.
Parameters for changerole. For details, see Parameters for changerole.
Parameters for changemember. For details, see Parameters for changemember.
Parameters for reload. For details, see Parameters for reload.
Parameters for list. For details, see Parameters for list.
Parameters for encrypt. For details, see Parameters for encrypt.
Parameters for ddb. For details, see Parameters for ddb.
Parameters for switch. For details, see Parameters for switch.

Usage method:

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 Parameters for option

Parameter	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. CAUTION: 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 parameter.
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 parameter to set parameters on a node.
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 parameter 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 parameter.
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, MogDB can be switched only to the DCC mode.

Table 2 Common parameters

Parameter	Description
-D DATADIR	Specifies the instance data directory.
-l FILENAME	Outputs the result to a specified file.
-n NODEID	Specifies a node.
-z AVAILABILITY_ZONE	Specifies an AZ name.
-t SECS	Specifies a timeout period.
-V, --version	Prints the cm_ctl version and exits.
-?, -h,--help	Displays help information about cm_ctl command parameters and exits.

Table 3 Parameters for switchover

Parameter	Description
-a	Restores nodes to their initial status. 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.
-A	Switches all node instances from primary to standby.
-f	Specifies that a switchover of the -f type is performed. 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. Usage: cm_ctl switchover -n NODEID -D DATADIR -f.

Table 4 Parameters for build

Parameter	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 Parameters for check

Parameter	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 Parameters for stop

Parameter	Description
-m SHUTDOWN-MODE	Specifies the stop mode. The options are as follows: smart (s): The database instance exits after user services end. fast (f): The database instance exits without waiting for the user service to end. immediate (i): The database instance is forced to exit without waiting for the user service to end.

Parameter

Description

-m SHUTDOWN-MODE

Specifies the stop mode. The options are as follows:

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

Table 7 Parameters for query

Parameter	Description
-s	Displays instances that result in unbalanced primary and standby instance quantity on each host. NOTE: The -s parameter 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 using -s, -C and -v must be specified.
-C	Displays the database instance status in pairs based on the primary and standby relationship. NOTE: The -C parameter must be used together with -v to display detailed database instance status information in pairs based on the primary and standby relationship. When using -C, -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 the data is backed up. All the processes are running and the primary and 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 parameter must be used together with the -v and -C parameters.
-i	Displays the IP addresses of physical nodes. NOTE: The -i parameter must be used together with the -v and -C parameters.
-F	Displays the fenced UDF status of each node. NOTE: The -F parameter must be used together with the -v and -C parameters to display the fenced UDF status of each node. When the -F parameter is used, the -C and -v parameters must be specified.
-z ALL	Displays the AZ name of a database instance. NOTE: The -z parameter must be used together with -v and -C and be followed by ALL.
-r	Displays the redo status of the standby node. NOTE: When using -r, you must specify the -v parameter.
-g	Displays information about cluster backup and restoration.
-x	Displays all abnormal database instances. NOTE: The -x parameter must be used together with the -v and -C parameters.
-S	Displays the status check result when a database instance is started. NOTE: The -S parameter must be used together with the -v and -C parameters to display the database instance status check result. The states are as follows: Normal: The database instance is available and the data is backed up. All the processes are running and the primary and 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 parameter 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 parameter must be used together with the -v and -C parameters.

Table 8 Parameters for set

Parameter	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 log print information.
--cm_arbitration_mode=ARBITRATION_MODE	Sets the arbitration mode of cm_server when one primary and multiple standbys are deployed. There are two modes: MAJORITY and MINORITY. MAJORITY indicates the majority mode, and MINORITY indicates the minority mode. MogDB 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	Enables/Disables automatic switchover between AZs when one primary and multiple standbys 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 Parameters for set cm

Parameter	Description
--param	Specifies the CM parameters to be set. If this parameter is not specified, the CM parameters cannot be set.
--agent \| --server	Specifies whether to set the cm_server or cm_agent parameters. This parameter 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 Parameters for get

Parameter	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 log print information.
--cm_arbitration_mode=ARBITRATION_MODE	Obtains the arbitration mode of cm_server when one primary and multiple standbys 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. CAUTION: MogDB does not support the MINORITY mode.
--cm_switchover_az_mode =SWITCHOVER_AZ_MODE	Obtains the automatic switchover mode between AZs when one primary and multiple standbys 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.

Parameter

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 log print information.

--cm_arbitration_mode=ARBITRATION_MODE

Obtains the arbitration mode of cm_server when one primary and multiple standbys 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.

CAUTION:

MogDB does not support the MINORITY mode.

--cm_switchover_az_mode

=SWITCHOVER_AZ_MODE

Obtains the automatic switchover mode between AZs when one primary and multiple standbys 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 Parameters for view

Parameter	Description
-v	Displays the static configuration details of all nodes in the database instance. NOTE: 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 Parameters for setrunmode

Parameter	Description	Value Range
--xmode	Specified the DCF running mode.	normal: normal mode. minority: minority mode. In this mode, --votenum is used 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 Parameters for changerole

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

Table 14 Parameters for changemember

Parameter	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 Parameters for start

Parameter	Description
--cm_arbitration_mode=ARBITRATION_MODE	Obtains the arbitration mode of cm_server when one primary and multiple standbys 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. CAUTION: MogDB does not support the MINORITY mode.

Parameter

Description

--cm_arbitration_mode=ARBITRATION_MODE

CAUTION:

MogDB does not support the MINORITY mode.

Table 16 Parameters for reload

Parameter	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 Parameters for list

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

Table 18 Parameters for encrypt

Parameter	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 Parameters for switch

Parameter	Description
--ddb_type=[DDB]	Select the DDB mode to be switched to. (MogDB 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 Parameters for ddb

Parameter	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 parameter 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 DCC version information.

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]