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参数，详细请参见。
公共参数，详细请参见表公共参数。
start模式的参数，详细参见。
switchover模式的参数，详细请参见表 switchover参数。
build模式的参数，详细请参见。
check模式的参数，详细请参见表 check参数。
stop模式的参数，详细请参见。
query模式的参数，详细请参见表 query参数。
view模式的参数，详细请参见。
set模式的参数，详细请参见表 set参数。
get模式的参数，详情请参见表 get参数。
setrunmode模式的参数，详细请参见。
changerole模式的参数，详细请参见表 changerole参数。
changemember功能的参数，详细请参见。
reload模式的参数，详细请参见表 reload 参数。
list模式的参数，详细请参见。
ddb模式的参数，详细请参见表 ddb参数。
switch模式的参数，详细请参见。
res模式的参数，详细请参见表 res参数。

使用方法:

表 1 option参数

表 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”。
	指定实例数据目录。

表 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参数

表 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角色。

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

表 15 start参数

表 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]	往DCC或者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	显示DDB命令帮助信息。
—version，-v	DCC部署模式下显示DCC版本信息，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 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 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 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参数：

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 --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 --check