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:
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 [-w] [-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, theCurrently, 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. |
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.
|
-w | Display the database instance status in vertical rows (consistent with the CMS status display format). Note:The -w option must be used together with -v and -C to display detailed database instance status information in pairs vertically based on the primary and standby relationship. When -w is used, -C and -v must be specified. |
-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. |
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. |
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
openGauss 2024-11-22 00:52:56