金仓数据库KingbaseES服务器应用参考手册--6. sys_ctl

6.1. 简介：

sys_ctl — 初始化、启动、停止或控制一个KingbaseES服务器。

sys_ctl是一个用于初始化KingbaseES数据库集簇，启动、停止或重启KingbaseES数据库服务器，或者显示一个正在运行服务器的状态的工具。 虽然服务器可以被手动启动，但 sys_ctl的优势是包装了重定向日志输出、从终端和进程组脱离等任务。它也提供了方便的控制关闭选项。

init或initdb模式会创建一个新的KingbaseES数据库集簇，也就是由单个服务器实例管理的数据库集合。这个模式调用initdb命令。详见 initdb 。

start模式启动一个新的服务器。该服务器从后台启动，标准输入接入/dev/null（或 Windows 上的nul）。在 Unix 类系统上，默认情况下服务器的标准输出和标准错误信息会发送到 sys_ctl的标准输出（而不是标准错误信息）。 sys_ctl的标准输出应该接着被重定向到一个文件或用管道导向另一个进程（例如日志轮转程序rotatelogs）。否则kingbase将把它的输出从后台写到控制终端并且不会离开 shell 的进程组。 在 Windows 上，默认情况下服务器的标准输出和标准错误被发送到终端。这些默认行为可以使用-l追加服务器的输出到一个日志文件来改变。我们推荐使用-l或输出重定向。

stop模式关闭运行在指定数据目录中的服务器。设置-m选项可以选择三种不同的关闭方法。 “Smart”模式等待所有客户端断开连接、所有在线备份结束后完成。如果该服务器是热备，当所有的客户端都断开连接后，恢复和流复制即终止。 “Fast”模式（默认）不会等待客户端断开连接，并且会终止进行中的在线备份。所有活动中的事务都回滚，客户端强制断开连接，最后关闭服务器。 “Immediate”模式将立刻中止所有服务器进程，而不是干净的关闭。这会导致下一次启动时服务器执行崩溃恢复。

restart模式实际上会先执行一个停止操作然后紧接着执行一个启动操作。这使得我们能够更改kingbase的命令行选项，或者更改不通过重启服务器无法更改的配置文件选项。 如果在服务器启动期间在命令行上使用了相对路径，则restart可能会失败，除非 sys_ctl被运行在与上次启动服务器相同的目录中。

reload模式简单地向kingbase服务器进程发送一个SIGHUP信号，导致它重新读取它的配置文件（kingbase.conf、sys_hba.conf等）。这允许改变配置文件选项而无需一次完整的服务器重启来让改变生效。

status模式检查一个服务器是否运行在指定的数据目录中。如果有一个服务器正在运行，其PID和用来调用它的命令行选项将被显示。如果服务器没有在运行， sys_ctl将返回退出状态 3。如果没有指定一个可以访问的数据目录， sys_ctl将返回退出状态 4。

promote模式命令运行在指定数据目录中的后备服务器结束后备模式并且开始读写操作。

logrotate模式循环服务器日志文件。 有关如何使用外部日志循环工具使用此模式的详细信息，请参阅日志文件维护 .

kill模式向一个指定进程发送一个消息。这主要用于没有kill命令的Microsoft Windows。使用--help来查看受支持的信号名称列表。

register模式把KingbaseES服务器注册为Microsoft Windows上的一个系统服务。-S选项允许选择服务启动类型，可以是“auto”（随系统自动启动）或“demand”（按需启动）。

unregister模式在Microsoft Windows上移除一个系统服务的注册。这会撤销register命令的效果。

6.2. 命令行参数：

sys_ctl init[db] [-D datadir] [-s] [-o initdb-options]

sys_ctl start [-D datadir] [-l filename] [-W] [-t seconds] [-s] [-o options] [-p path] [-c]

sys_ctl stop [-D datadir] [-m s[mart] | f[ast] | i[mmediate] ] [-W] [-t seconds] [-s]

sys_ctl restart [-D datadir] [-m s[mart] | f[ast] | i[mmediate] ] [-W] [-t seconds] [-s] [-o options] [-c]

sys_ctl reload [-D datadir] [-s]

sys_ctl status [-D datadir]

sys_ctl promote [-D datadir] [-W] [-t seconds] [-s]

sys_ctl logrotate [-D datadir] [-s]

sys_ctl kill signal_name process_id

在Microsoft Windows上，还有：

sys_ctl register [-D datadir] [-N servicename] [-U username] [-P password] [-S a[uto] | d[emand] ] [-e source] [-W] [-t seconds] [-s] [-o options]

sys_ctl unregister [-N servicename]

6.3. 参数说明：

-c

--core-files

在可行的平台上尝试允许服务器崩溃产生核心文件，方法是提升在核心文件上的任何软性资源限制。这通过允许从一个失败的服务器进程中获得一个栈跟踪而有助于调试或诊断问题。

-D datadir

--kingbase_data=datadir

指定数据库配置文件的文件系统位置。如果这个选项被忽略，将使用环境变量KINGBASE_DATA。

-l filename

--log=filename

追加服务器日志输出到 filename 。如果该文件不存在，它会被创建。umask被设置成 077，这样默认情况下不允许其他用户访问该日志文件。

-m mode

--mode=mode

指定关闭模式。可选模式包括smart、fast或immediate，或者这三者之一的第一个字母。如果这个选项被忽略，则fast是默认值。

-o options

--options=options

指定被直接传递给kingbase命令的选项。-o可以被指定多次，所有给定的选项都会被传过去。

这些选项应该通常被单引号或双引号包围来确保它们被作为一个组传递。

-o initdb-options

--options=initdb-options

指定要直接传递给initdb命令的选项。-o可以被指定多次，所有给定的选项都会被传过去。

这些选项应该通常被单引号或双引号包围来确保它们被作为一个组传递。

-p

path

指定kingbase可执行程序的位置。默认情况下，kingbase可执行程序可以从sys_ctl相同的目录得到，或者如果没有在那里找到，则在指定的安装目录中获得。 这个选项通常不是必需的，除非在特殊情景下程序报错无法找到kingbase可执行程序。

在init模式中，这个选项类似于指定了initdb可执行程序的位置。

-s

--silent

只打印错误，不打印信息性的消息。

-t seconds

--timeout=seconds

指定等待一个操作完成时要等待的最大秒数（见选项-w）。默认为KCICTLTIMEOUT环境变量的值，如果该环境变量没有设置则默认为60秒。

-V

--version

打印 sys_ctl版本并退出。

-w

--wait

等待操作完成。模式start、stop、restart、promote以及register支持这个选项，并且对那些模式是默认的。

在等待时，sys_ctl会定期重复地检查服务器的PID文件，在两次检查之间会休眠一小段时间。当PID文件指示该服务器已经做好准备接受连接时，启动操作被认为完成。当服务器移除PID文件时，关闭操作被认为完成。sys_ctl会基于启动或关闭的成功与否返回一个退出代码。

如果操作在超时时间（见选项-t）内未能完成，则sys_ctl会以一个非零退出状态退出。但是注意该操作可能会在后台继续进行并且最终取得成功。

-W

--no-wait

不等待操作完成。这是选项-w的对立面。

如果禁用等待，所请求的动作会被触发，但是不会有关于其成功与否的反馈。在这种情况下，可能必须用服务器日志文件或外部监控系统来检查该操作的进度以及成功与否。

在以前版本的KingbaseES中，这是除stop模式之外的模式的默认选项。

-?

--help

显示有关 sys_ctl命令行参数的帮助并退出。

如果一个指定的选项有效，但与选中的操作模式无关，则 sys_ctl会忽略它。

6.3.1. 用于 Windows 的选项

-e source

作为一个 Windows 服务运行时， sys_ctl用来在事件日志中记录日志的事件源的名称。默认是KingbaseES。 注意这只控制由 sys_ctl本身发送的消息，一旦开始， 服务器将使用event_source参数中指定的事件源。 如果服务器在启动时很早（在该参数被设置前）就失败，它可能也会使用默认的事件源名称 KingbaseES来记录。

-N servicename

要注册的系统服务的名称。这个名称将被用于服务名和显示名。默认是KingbaseES。

-P password

用于运行该服务的用户的口令。

-S start-type

要注册的系统服务的启动类型。启动类型可以是auto、demand或者两者之一的第一个字母。如果这个选项被忽略，则auto是默认值。

-U username

用于运行该服务的用户的用户名。对于域用户，使用格式DOMAIN\username。

6.4. 环境变量：

KCICTLTIMEOUT

等待启动或者关闭完成时要等待的默认秒数限制。如果没有设置，默认值是 60 秒。

KINGBASE_DATA

默认的数据目录位置。

大部分的sys_ctl模式都要求知道数据目录的位置，因此-D选项是必需的，除非KINGBASE_DATA被设置。

和大部分其他KingbaseES工具相似，sys_ctl也使用libkci支持的环境变量。

更多影响服务器的变量请见 kingbase 。

6.5. 文件：

kingbase.pid

sys_ctl在数据目录中检查这个文件来判断服务器当前是否正在运行。

kingbase.opts

如果这个文件存在于数据目录中， sys_ctl（处于restart模式中）将把该文件的内容作为选项传递给kingbase，除非通过-o选项进行了覆盖。这个文件的内容也会被显示在status模式中。

6.6. 示例：

6.6.1. 启动服务器：

要启动服务器并且等到服务器接受连接：

$ sys_ctl start

要使用端口 5433 启动服务器并且运行时不使用fsync：

$ sys_ctl -o "-F -p 5433" start

6.6.2. 停止服务器：

要停止服务器，使用：

$ sys_ctl stop

-m选项允许控制服务器如何关闭：

$ sys_ctl stop -m smart

6.6.3. 重启服务器：

重启服务器几乎等价于停止服务器并且再次启动它，不过sys_ctl默认会保存并重用被传递给之前的运行实例的命令行选项。要以和之前相同的选项重启服务器，使用：

$ sys_ctl restart

但是如果指定了-o，则会替换任何之前的选项。要使用端口 5433 重启并在重启时禁用fsync：

$ sys_ctl -o "-F -p 5433" restart

6.6.4. 显示服务器状态：

这里是 sys_ctl状态输出的例子：

$ sys_ctl status

sys_ctl: server is running (PID: 13718)
/opt/Kingbase/ES/V8/bin/kingbase "-D" "/opt/Kingbase/ES/V8/data" "-p" "5433"
"-B" "128"

第二行是在重启模式可能被调用的命令行。

6.7. 错误信息诊断：

无

6.8. 备注：

无

6.9. 参考：

initdb , kingbase