cm_ctl工具介绍
- 命令说明
- 命令参考

cm_ctl工具介绍

cm_ctl是openGauss提供的用来控制数据库实例服务的工具。该工具主要供OM调用，及数据库实例服务自恢复时使用。cm_ctl的主要功能有：

启动数据库实例服务、AZ的所有实例、单个主机上的所有实例或单独启动某个实例进程。
停止数据库实例服务、AZ的所有实例、单个主机上的所有实例或单独停止某个节点实例进程。
重启逻辑数据库实例服务。
查询数据库实例状态或者单个主机的状态。
切换主备实例或重置实例状态。
重建备机。
查看数据库实例配置文件。
设置日志级别，一主多备数据库实例部署下cm_server的仲裁模式、AZ之间的切换模式。
获取日志级别，一主多备数据库实例部署下cm_server的仲裁模式、AZ之间的切换模式。
检测实例进程状态。

与cm_ctl工具相关的文件：

cluster_manual_start

该文件是数据库实例启停标志文件。文件位于_$GAUSSHOME/bin_下。其中，GAUSSHOME为环境变量。启动数据库实例时，cm_ctl会删除该文件；停止数据库实例时，cm_ctl会生成该文件，并向文件写入停止模式。
instance_manual_start_X（X是实例编号）

该文件是单个实例启停标志文件。文件位于_$GAUSSHOME/bin_下。其中，GAUSSHOME为环境变量。启动实例时，cm_ctl会删除该文件；停止实例时，cm_ctl会生成该文件，并向文件写入停止模式。

cm_ctl的相关约束：

在集群模式下，使用cm_ctl集群工具来切换数据库角色，而不是gs_ctl数据库工具。

命令说明

cm_ctl参数可分为如下几类：

option参数，详细请参见表 option参数。
公共参数，详细请参见表公共参数。
start模式的参数，详细参见表 start参数。
switchover模式的参数，详细请参见表 switchover参数。
build模式的参数，详细请参见表 build参数。
check模式的参数，详细请参见表 check参数。
stop模式的参数，详细请参见表 stop参数。
query模式的参数，详细请参见表 query参数。
view模式的参数，详细请参见表 view参数。
set模式的参数，详细请参见表 set参数表 set cm参数。
get模式的参数，详情请参见表 get参数。
setrunmode模式的参数，详细请参见表 setrunmode参数。
changerole模式的参数，详细请参见表 changerole参数。
changemember功能的参数，详细请参见表 changemember参数。
reload模式的参数，详细请参见表 reload 参数。
list模式的参数，详细请参见表 list参数。
encrypt模式的参数，详细请参见表 encrypt参数。
ddb模式的参数，详细请参见表 ddb参数。
switch模式的参数，详细请参见表 switch参数。
res模式的参数，详细请参见表 res参数。

使用方法:

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]

表 1 option参数

参数	参数说明
start	一主多备数据库部署模式下启动数据库实例服务、单个主机上的所有实例或单独启动某个节点实例进程，或者直接启动整个AZ。
switchover	一主多备数据库部署模式下切换数据库主备实例。
finishredo	所有备机停止回放，每个分片中选择一个强制升主。注意：该参数属于高风险操作，请谨慎执行。
build	重建备实例。
check	检测实例进程运行状态，用户无需关注，不建议使用。
stop	一主多备数据库部署模式下停止数据库实例服务、单个主机上的所有实例或单独停止某个节点实例进程。
query	一主多备数据库部署模式下查询数据库实例状态或者单个主机的状态。
view	查看数据库实例配置文件。
set	设置日志级别，一主多备数据库部署模式下cm_server的仲裁模式、AZ之间的切换模式、cm_server升主模式。
set —param	设置cm参数，默认set所有节点上的参数，也可以通过-n参数指定set某个节点，具体参数可以参考CM配置参数介绍
get	获取日志级别，一主多备数据库部署模式下cm_server的仲裁模式、AZ之间的切换模式。
setrunmode	DCF部署方式下，设置DCF投票数，主要用于DCF强启。
changerole	DCF模式下，将角色为primary的修改为passive或者follower。
changemember	DCF模式下，改变指定DCF节点属性，包括节点角色、节点所在的逻辑组、节点的选举优先级等。
reload	在线加载数据库实例静态配置文件，用户无需关注，不建议使用。
reload —param	加载可以动态生效的cm参数，部分参数不支持reload，只能重启cm才能生效。
list	列出cm_agent或cm_server所有的参数。
encrypt	对输入的密码进行加密操作，密码支持8~15位，且必须包含三种字符（数字，字母，符号）。
ddb	DCC 或者share disk模式下，执行对DCC组件或者 share disk的配置数据存取命令。CM依赖DCC组件或者 share disk对配置数据分布式存取，实现集群配置管理高可用能力。
switch	执行ddb模式的切换。说明： openGauss当前只支持切换到DCC模式。
res	在节点上进行资源配置的新增、修改、查询、删除。
show	展示集群DN节点网络连通性和每个节点的共享盘连通性说明： 1. 节点连通性使用的是DN的HAIP。 2. 共享盘连通性的前提是配置了cma的voting_disk_path参数，否则默认显示不连通。

表 2 公共参数

参数	参数说明
-D DATADIR	指定实例数据目录。仅用于对数据库节点进行操作的命令，如start、stop、switchover、build、setrunmode、changerole、changemember、encrypt。
-l FILENAME	查询结果输出到指定文件。仅用于查询类的命令，如query、view。
-n NODEID	指定节点。
-z AVAILABILITY_ZONE	指定AZ名称。
-t SECS	指定超时时间。
-V, —version	打印cm_ctl版本信息，然后退出。
-?, -h,—help	显示关于cm_ctl命令行参数的帮助信息，然后退出。

说明：

此处列出的公共参数并不一定适用于所有命令，而是多个命令支持，为避免冗余信息，所以统一在此说明，详细的使用方法见以上使用方法，也可以使用cm_ctl –help进行查询。

表 3 switchover参数

参数	参数说明
-a	将集群的主机重置到初始配置的节点。
-A	将主机切换到一个合适的备机节点上。
-f	指定进行-f类型switchover。使用方式：cm_ctl switchover -n NODEID -D DATADIR -f。
-z	将主机切换到-z参数指定的AZ。注意： switchover为维护操作：确保数据库实例状态正常，所有业务结束，并使用pgxc_get_senders_catchup_time()视图查询无主备追赶后，再进行switchover操作。

表 4 build参数

参数	参数说明
-f	强制重建备机。
-b full	指定进行全量build。不指定情况下，对于一主多备数据库实例部署模式进行auto build。auto build指：先调用增量build，失败之后调用全量build。
-c	重建 cm_server（将主节点的DCC数据目录拷贝到指定节点，只适用于一主一备模式）。

表 5 check参数

参数	参数说明
-B BINNAME	指定进程名，其进程名包括“cm_agent”,“gaussdb”和“cm_server”。
-T DATAPATH	指定实例数据目录。

表 6 stop参数

参数	参数说明
-m SHUTDOWN-MODE	指定停止模式，停止模式有以下几种： smart（s）：等待用户业务结束后，停止所有数据库实例。 fast（f）：不等待用户业务结束，指定数据库实例退出。 immediate（i）：不等待用户业务结束，指定数据库实例强制退出。
-I	指定需要停止的资源实例号，可以通过cm_ctl query -Cv查看资源实例和实例号的映射关系

参数

参数说明

-m SHUTDOWN-MODE

指定停止模式，停止模式有以下几种：

smart（s）：等待用户业务结束后，停止所有数据库实例。
fast（f）：不等待用户业务结束，指定数据库实例退出。
immediate（i）：不等待用户业务结束，指定数据库实例强制退出。

-I

指定需要停止的资源实例号，可以通过cm_ctl query -Cv查看资源实例和实例号的映射关系

表 7 query参数

参数	参数说明
-s	显示导致各个节点主备实例数量不均衡的实例。说明： -s参数需要和-v以及-C参数一起使用才能按主备关系成对显示导致各个节点主备实例数量不均衡的实例，使用-s参数时，必须指定-C、-v参数。
-C	按主备关系成对显示数据库实例状态。说明： -C参数需要和-v参数一起使用才能按主备关系成对显示数据库实例详细状态信息，使用-C时，必须指定-v参数。
-v	显示详细数据库实例状态。说明：数据库实例有如下几种状态： Normal：表示数据库实例可用，且数据有冗余备份。所有进程都在运行，主备关系正常。 Degraded：表示数据库实例可用，但数据没有冗余备份。 Unavailable：表示数据库实例不可用。
-d	显示实例数据目录。说明： -d参数需要和-v以及-C参数一起使用。
-i	显示物理节点ip。说明： -i参数需要和-v以及-C参数一起使用。
-F	显示各个节点Fenced UDF状态。说明： -F参数需要和-v以及-C参数一起使用才能显示各个节点Fenced UDF状态，使用-F参数时，必须指定-C、-v参数。
-z ALL	显示数据库实例所在AZ名称。说明： -z参数需要和-v以及-C参数一起使用，并且-z后面需要跟参数ALL。
-r	显示备机redo状态。说明：使用-r时，必须指定-v参数。
-g	显示备份和恢复群集信息。
-x	显示所有异常的数据库实例。说明： -x参数需要和-v以及-C参数一起使用。
-S	显示数据库实例启动时的状态检查结果。说明： -S参数需要和-v以及-C参数一起使用才能按显示数据库实例的状态检查结果。有以下三种状态： Normal：表示数据库实例可用，且数据有冗余备份。所有进程都在运行，主备关系正常。 Degraded：表示数据库实例可用，但数据没有冗余备份。 Unavailable：表示数据库实例不可用。
—minorityAz	只查询指定AZ的cms。说明：此参数会忽略非指定AZ的cms节点，可以在少数派场景提高查询速度。
-p	显示数据库实例所有节点端口。说明： -p参数需要和-v以及-C参数一起使用。

表 8 set参数

参数	参数说明
—log_level=LOG_LEVEL	设置主cm_server日志级别。共分为DEBUG5、DEBUG1、WARNING、LOG、ERROR和FATAL六个级别，日志打印信息级别越来越高。设置日志级别越高，输出日志信息就越少。
—cm_arbitration_mode=ARBITRATION_MODE	一主多备功能，设置cm_server的仲裁模式。共有MAJORITY、MINORITY两种模式，MAJORITY为多数派模式，MINORITY为少数派模式。opengauss不支持少数派，此参数可以设置成MINORITY，但不会生效。
—cm_switchover_az_mode= SWITCHOVER_AZ_MODE	一主多备功能，设置AZ之间的自动切换开关。共有NON_AUTO、AUTO两种模式，NON_AUTO为非自动切换模式，AUTO为自动切换模式。AUTO模式由主cm_server自动控制AZ1和AZ2之间的节点实例切换。
—cmsPromoteMode=CMS_PROMOTE_MODE -I INSTANCEID	设置cm_server的升主方式，共有AUTO、PRIMARY_F两种模式，AUTO为默认自选主方式，PRIMARY_F会强制使-I指定的节点升主，无论当前是否有主，因此，有可能会导致cms存在多主情况。

表 9 set cm参数

参数	参数说明
—param	表明需要设置cm参数，不带此参数则不能执行设置cm参数。
—agent \| —server	此参数为必带参数，表明当前需要设置cm_server还是cm_agent的参数。
-k parameter=”value”	指定设置的参数和参数的值，只能设置已经存在的参数，不支持增加或删减参数。

表 10 get参数

参数	参数说明
—log_level=LOG_LEVEL	获取主cm_server日志级别。共分为DEBUG5、DEBUG1、WARNING、LOG、ERROR和FATAL六个级别，日志打印信息级别越来越高。设置日志级别越高，输出日志信息就越少。
—cm_arbitration_mode=ARBITRATION_MODE	一主多备功能，获取cm_server的仲裁模式。共有MAJORITY、MINORITY两种模式，MAJORITY为多数派模式，MINORITY为少数派模式。少数派模式适用于一主多备数据库部署并且只有AZ3存活时，此时cm_server可以进行正常的仲裁业务，非此模式下将仲裁模式设置成少数派成功后，cm会自动将仲裁模式改为多数派，以保证集群正常运转；多数派模式适用于一主多备数据库部署并且各个组件（cm_server，节点）存活数量大于一半的场景。数据库实例正常情况下默认为多数派模式。注意： opengauss不支持少数派
—cm_switchover_az_mode =SWITCHOVER_AZ_MODE	一主多备功能，获取AZ之间的自动切换开关。共有NON_AUTO、AUTO两种模式，NON_AUTO为非自动切换模式，AUTO为自动切换模式。AUTO模式由主cm_server自动控制AZ1和AZ2之间的节点实例切换。

参数

参数说明

—log_level=LOG_LEVEL

获取主cm_server日志级别。共分为DEBUG5、DEBUG1、WARNING、LOG、ERROR和FATAL六个级别，日志打印信息级别越来越高。设置日志级别越高，输出日志信息就越少。

—cm_arbitration_mode=ARBITRATION_MODE

一主多备功能，获取cm_server的仲裁模式。共有MAJORITY、MINORITY两种模式，MAJORITY为多数派模式，MINORITY为少数派模式。少数派模式适用于一主多备数据库部署并且只有AZ3存活时，此时cm_server可以进行正常的仲裁业务，非此模式下将仲裁模式设置成少数派成功后，cm会自动将仲裁模式改为多数派，以保证集群正常运转；多数派模式适用于一主多备数据库部署并且各个组件（cm_server，节点）存活数量大于一半的场景。数据库实例正常情况下默认为多数派模式。

注意：

opengauss不支持少数派

—cm_switchover_az_mode

=SWITCHOVER_AZ_MODE

一主多备功能，获取AZ之间的自动切换开关。共有NON_AUTO、AUTO两种模式，NON_AUTO为非自动切换模式，AUTO为自动切换模式。AUTO模式由主cm_server自动控制AZ1和AZ2之间的节点实例切换。

表 11 view参数

参数	参数说明
-v	显示数据库实例所有节点的静态配置详细信息。说明：相对于cm_ctl view命令，-v 显示内容增加了cmserver、节点组件的编号显示，如下：cmseverInstanceID，datanodeInstanceID。
-N	只显示本节点的静态配置信息，即执行cm_ctl view命令的节点的信息，N表示Native。

表 12 setrunmode参数

参数	参数说明	取值范围
—xmode	指定DCF的运行模式。	normal：正常模式。 minority：少数派模式，需要—votenum指定投票数。
—votenum	指定DCF少数派运行方式的投票数。	正整数，不高于DCF总副本数。

表 13 changerole参数

参数	参数说明	取值范围
—role	DCF模式下，将角色为primary的修改为passive或者follower。	passive：passive角色。 follower：follow角色。

表 14 changemember参数

参数	参数说明	取值范围
—role	DCF模式下，将角色为primary的修改为passive或者follower。	passive：passive角色。 follower：follow角色。
—group	DCF模式下，修改group的值。	0~2147483647
—priority	DCF模式下，修改priority的值。	0~2147483647

表 15 start参数

参数	参数说明
—cm_arbitration_mode=ARBITRATION_MODE	一主多备功能，获取cm_server的仲裁模式。共有MAJORITY、MINORITY两种模式，MAJORITY为多数派模式，MINORITY为少数派模式。少数派模式适用于一主多备数据库部署并且只有AZ3存活时，此时cm_server可以进行正常的仲裁业务，非此模式下将仲裁模式设置成少数派成功后，cm会自动将仲裁模式改为多数派，以保证集群正常运转；多数派模式适用于一主多备数据库部署并且各个组件（cm_server，节点）存活数量大于一半的场景。数据库实例正常情况下默认为多数派模式。注意： opengauss不支持少数派
-I	指定需要启动的资源实例号，可以通过cm_ctl query -Cv查看资源实例和实例号的映射关系

参数

参数说明

—cm_arbitration_mode=ARBITRATION_MODE

注意：

opengauss不支持少数派

-I

指定需要启动的资源实例号，可以通过cm_ctl query -Cv查看资源实例和实例号的映射关系

表 16 reload 参数

参数	参数说明
—param	表明需要加载cm参数，不带此参数则不能执行加载cm参数。
—agent \| —server	表明当前需要动态加载cm_server还是cm_agent的参数。

表 17 list参数

参数	参数说明
—param	此参数为必带参数，表明需要列出cm参数信息。
—agent \| —server	此参数为必带参数，表明当前需要查看cm_server还是cm_agent的参数。

表 18 encrypt参数

参数	参数说明
-M	指定加密类型，支持server、client。默认类型为server。
-D	指定生成的加密密码文件路径。

表 19 switch参数

参数	参数说明
—ddb_type=[DDB]	选择需要切换DDB模式（opengauss只支持DCC模式）。
—commit	执行切换会使数据库实例无法选主，需要执行commit恢复数据库实例。
—rollback	回滚操作，执行切换失败需要执行回滚操作。

表 20 ddb参数

参数	参数说明
—put [key] [value]	往D CC或者 share disk中插入键值对，如果键值对已存在则会修改键key所对应的值value。
—get [key]	查询DCC 或者 share disk中key对应的value。
—delete [key]	删除DCC 或者 share disk中指定的键值对。
—prefix	get或者delete后添加prefix参数，可以实现模糊匹配查询和删除。
—cluster_info	DCC部署模式下获取数据库实例信息，share disk部署模式下不支持该命令。
—leader_info	DCC部署模式下获取主节点信息，share disk部署模式下不支持该命令。
—help，-h	显示D DB命令帮助信息。
—version，-v	DCC部署模式下显示D CC版本信息，share disk部署模式下不支持该命令。

表 21 res参数

参数	参数说明
—add —res_name=[name] —res_attr=[res_info]	新增资源配置，name为新增资源的名称，res_info为新增资源的信息。
—del —res_name=[name]	删除资源配置，name为删除资源的名称。
—edit —res_name=[name] —res_attr=[res_info]	修改资源配置，name为被修改资源的名称，res_info为新修改的资源信息。
—edit —res_name=[name] —add_inst=[inst_info]	新增资源实例，name为新增实例的资源名称，inst_info为新增实例的信息。
—edit —res_name=[name] —del_inst=[inst_info]	删除资源实例，name为删除实例的资源名称，inst_info为删除实例的信息。
—check	检查资源配置。不合理处会显示Warning，配置不可用才会报错。

命令参考

启动实例：

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 -n NODEID -D DATADIR [-t SECS] [-f] [-b full]

检测实例进程运行状态：
```
cm_ctl check -B BINNAME -T DATAPATH
```

停止实例：

cm_ctl stop [[-z AVAILABILITY_ZONE] | [-n NODEID [-D DATADIR [-R]]]] [-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]

设置CM参数：

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

获取参数：

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

设置DCF投票数：

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

改变dcf角色信息：

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

改变dcf节点属性：

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

动态加载CM参数：

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

列出所有CM参数：

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

加密：
```
cm_ctl encrypt [-M MODE] -D DATADIR
```

执行DDB命令行：

cm_ctl ddb DDB_CMD
设置：cm_ctl ddb --put [key] [value]
删除：cm_ctl ddb --delete [key]
查看DDB命令帮助信息：cm_ctl ddb --help

执行switch ddb命令：

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

执行res命令：

新增资源：cm_ctl res --add --res_name=[name] --res_attr=[res_info]
删除资源：cm_ctl res --del --res_name=[name]
修改资源：cm_ctl res --edit --res_name=[name] --res_attr=[res_info]
新增资源实例：cm_ctl res --edit --res_name=[name] --add_inst=[inst_info]
删除资源实例：cm_ctl res --edit --res_name=[name] --del_inst=[inst_info]
检查资源：cm_ctl res --check