rc.subr.8
最后更新于
最后更新于
RC.SUBR(8)
RC.SUBR(8)
FreeBSD System Manager's Manual
RC.SUBR(8)
rc.subr —
系统 shell 脚本使用的函数
/etc/rc.subr
action file current backup
var
pidfile procname [interpreter]
procname [interpreter]
message
exitval message
name
message
[-e regex] [-m module] file
name
name var
type
command ...
item ...
argument
file argument
[pid ...]
message
rc.subr 脚本包含常用的 shell 脚本函数和变量定义，这些函数被各种脚本（例如 rc(8) ）使用。 /usr/local/etc/rc.d 中的端口所需的脚本最终也将被重写以使用它。
rc.subr 函数主要是从 NetBSD- 导入的。
通过将 /etc/rc.subr 导入当前 shell 来访问它们。
可以使用以下 shell 函数：
将 file 备份到 current 。 将 current 版本的先前版本保存为 backup 。
action 参数可以是以下之一：
file 现在正在备份或可能重新进入此备份机制。 current 被创建。
file 已更改，需要备份。 如果 current 存在，则将其复制到 backup ，然后将 file 复制到 current 。
此备份机制不再跟踪 file 。 current 移动到 backup 。
如果 var 定义为 “YES”, “TRUE”, “ON” 或 ‘1’ ，则返回 0。 如果 var 定义为 “NO”, “FALSE”, “OFF” 或 ‘0’ ，则返回 0。 否则，警告 var 设置不正确。 这些值不区分大小写。 注意: var- 应该是一个变量名，而不是它的值； checkyesno 将自行扩展变量。
解析 pidfile 第一行的第一个单词以获取 PID，并确保具有该 PID 的进程正在运行并且其第一个参数与 procname 匹配。 如果成功则打印匹配的 PID，否则不打印。 如果提供了 interpreter ，则解析 procname 的第一行，确保该行的格式为：
#! interpreter [...]
并使用带有可选参数和 procname 的 interpreter 作为要搜索的进程字符串附加。
打印使用与 procname 匹配的第一个参数运行的任何进程的 PID。 interpreter 按 check_pidfile 处理。
向 stderr 显示调试消息，使用 logger(1) 将其记录到系统日志中，然后返回给调用者。 错误消息包含脚本名称（从 $0 开始），后跟 “: DEBUG: ”, 然后是 message 。 此功能旨在供开发人员用作调试脚本的辅助工具。 它可以通过 rc.conf(5) 变量 rc_debug 打开或关闭。
向 stderr 显示错误消息，使用 logger(1), 将其记录到系统日志中，并以 exitval 的退出值 exit 。 错误消息包含脚本名称（从 $0 开始），后跟 “: ERROR: ”, 然后是 message 。
输出一条建议消息并强制启动 name 服务。 name 参数是位于 /etc/rc.d 的脚本路径的 basename(1) ) 组件（存储在其他位置的脚本，例如 /usr/local/etc/rc.d 目前无法使用 force_depend- 控制）。 如果脚本因任何原因失败，它将输出警告并返回值 1。 如果成功，它将返回 0。
向 stdout 显示信息性消息，并使用 logger(1) 将其记录到系统日志中。 该消息包含脚本名称（从 $0 开始），后跟 “: INFO: ”, 然后是 message 。 可以通过 rc.conf(5) 变量 rc_info 打开或关闭此信息输出的显示。
除非已加载 file ，否则将 file 作为内核模块加载。 为了检查模块状态，可以使用 -m 指定确切的模块名称，或者可以通过 -e 提供与模块名称匹配的 egrep(1) 正则表达式。 默认情况下，假定模块与 file 同名，但并非总是如此。
name 的配置文件中的源。 首先，如果尚未读入 /etc/rc.conf ，则获取它。 然后，如果 /etc/rc.conf.d/name 是现有文件，则它是源文件。 后者还可能包含其他变量分配以覆盖调用脚本定义的 run_rc_command 参数，从而为管理员提供一种简单的机制来覆盖给定 rc.d(8) 脚本的行为，而无需编辑该脚本。
读取 rc.conf(5) 变量 var 的 name 并在当前 shell 中设置，在子 shell 中使用 load_rc_config 以防止其他变量分配产生不必要的副作用。
查看 rc.conf(5) 变量 critical_filesystems_type 中的关键文件系统列表，安装当前未安装的每个系统。
打印 $0 的使用消息， commands 是前缀为 “[fast|force|one|quiet]”. 的有效参数列表。
以相反的顺序打印 items 列表。
根据各种 shell 变量的设置，运行当前 rc.d(8) 脚本的 argument 方法。 run_rc_command 非常灵活，允许在少量 shell 代码中实现功能齐全的 rc.d(8) 脚本。
在支持的命令列表中搜索 argument ，可能是以下命令之一：
启动服务。 这应该检查服务是否按照 rc.conf(5) 的规定启动。 还检查服务是否已经在运行，如果是则拒绝启动。 如果系统直接启动到多用户模式，则标准 FreeBSD 脚本不会执行后一种检查，以加快启动过程。
如果要按照 rc.conf(5) 的规定启动服务，请停止服务。 这应该检查服务是否正在运行，如果没有运行则抱怨。
执行 stop 然后 start 。 默认显示程序的进程 ID（如果正在运行）。
如果服务启用则返回 0，否则返回 1。 此命令不打印任何内容。
显示哪些 rc.conf(5) 变量用于控制服务的启动（如果有）。
如果设置了 pidfile 或 procname ，还支持：
等待命令退出。
显示进程的状态。
其他支持的命令列在可选变量 extra_commands 中。
argument 可能具有以下前缀之一，这些前缀会改变其操作：
跳过检查现有正在运行的进程，并设置 rc_fast=YES 。
跳过检查 rcvar 是否设置为 “YES” ，并设置 rc_force=YES 。 这将忽略返回非零的 argument_precmd ，并忽略任何失败的 required_* 测试，并始终返回零退出状态。
跳过检查 rcvar 是否设置为 “YES”, 但执行所有其他先决条件测试。
禁止一些详细的诊断。 目前，这包括消息 “Starting ${name}” （由 rc.subr 中的 check_startmsgs 检查）和有关使用 rc.conf(5) 中未启用的服务的错误。 此前缀还设置 rc_quiet=YES 。 请注意： rc_quiet 并非旨在完全屏蔽所有调试和警告消息，而只是屏蔽其中的某些小类。
run_rc_command 使用以下 shell 变量来控制其行为。 除非另有说明，否则这些都是可选的。
name
此脚本的名称。这不是可选的。
rcvar
使用 checkyesno 检查 rcvar 的值以确定是否应该运行此方法。
command
命令的完整路径。如果为每个支持的关键字定义了 argument_cmd ，则不需要。可以被 ${name}_program 覆盖。
command_args
command 的可选参数和/或 shell 指令。
command_interpreter
command 开始于：
#! command_interpreter [...]
这导致其 ps(1) 命令为：
command_interpreter [...] command
所以使用该字符串来查找正在运行的命令而不是 command 的 PID。
extra_commands
支持额外的 commands/keywords/arguments 。
pidfile
PID 文件的路径。 用于确定运行命令的 PID。 如果设置了 pidfile ，请使用：
check_pidfile $pidfile $procname
找到PID。否则，如果设置了 command ，请使用：
check_process $procname
找到PID。
procname
要检查的进程名称。 默认为 command 的值。
required_dirs
在运行 start 方法之前检查列出的目录是否存在。 在运行 start_precmd 之前检查该列表。
required_files
在运行 start 方法之前检查列出的文件的可读性。 在运行 start_precmd 之前检查该列表。
required_modules
确保在运行 start 方法之前加载列出的内核模块。 运行 start_precmd 后检查该列表。 这是在从 start_precmd 调用命令之后完成的，这样如果初步命令指示错误条件，就不会徒劳地加载丢失的模块。 列表中的单词可以有一个可选的 “:modname” 或 “~pattern” 后缀。 modname 或 pattern 参数分别通过 -m 或 -e 选项传递给 load_kld 。 详见本文档对 load_kld 的描述。
required_vars
在运行 start 方法之前，对每个列表变量执行 checkyesno 。 运行 start_precmd 后检查该列表。
${name}_chdir
如果未提供 ${name}_chroot ，则在运行 command 之前要 cd 到的目录。
${name}_chroot
运行 command 之前 chroot(8) 的目录。仅在挂载 /usr 后支持。
${name}_env
用于运行 command 的环境变量列表。 除非定义了 argument_cmd ，否则这些变量将作为参数传递给 env(1) 实用程序。 在这种情况下， ${name}_env 的内容将通过 sh(1) 的 export(1) 内置函数导出，这对变量的名称施加了一些限制（例如，变量名称不能以数字开头）。
${name}_env_file
用于获取环境变量以运行 command 的文件。 请注意，在此文件中分配的所有变量都将导出到 command 环境中。
${name}_fib
用于运行 command 的 FIB Routing Table 。 有关详细信息，请参阅 setfib(1) 。
${name}_flags
调用 command 的参数。 这通常在 rc.conf(5) 中设置，而不是在 rc.d(8) 脚本中。 环境变量 ‘flags’ 可以用来覆盖它。
${name}_nice
nice(1) 级别来运行 command 。 仅在挂载 /usr 后支持。
${name}_limits
应用于 command 的资源限制。 这将作为参数传递给 limits(1) 实用程序。 默认情况下，资源限制基于 ${name}_login_class 中定义的登录类。
${name}_login_class
与 ${name}_limits 一起使用的登录类。 默认为 “daemon” 。
${name}_oomprotect
当交换空间用完时， protect(1) command 不会被杀死。 如果使用 “YES” ，则没有子进程受到保护。 如果为 “ALL”, 则保护所有子进程。
${name}_program
命令的完整路径。 如果两者都设置了，则覆盖 command ，但如果未设置 command ，则无效。 通常， command 应该在脚本中设置，而 ${name}_program 应该在 rc.conf(5) 中设置。
${name}_user
用户运行 command ，如果设置了 ${name}_chroot ，则使用 chroot(8) ，否则使用 su(1) 。 仅在挂载 /usr 后支持。
${name}_group
组以运行 command 命令。
${name}_groups
以逗号分隔的补充组列表，用于运行 command 。
${name}_prepend
要在命令之前添加的 command 。 这是 ${name}_env, ${name}_fib 或 ${name}_nice 的通用版本。
argument_cmd
覆盖 argument 的默认方法的 Shell 命令。
argument_precmd
在运行 argument_cmd 或 argument 的默认方法之前运行的 Shell 命令。 如果这返回非零退出代码，则不执行 main 方法。 如果正在执行默认方法，则在 required_* 检查和处理（不）存在检查之后执行此检查。
argument_postcmd
如果运行 argument_cmd 或 argument 的默认方法返回零退出代码，则要运行的 Shell 命令。
sig_stop
在默认 stop 方法中发送进程停止的信号。 默认为 SIGTERM 。
sig_reload
以默认 reload 方法发送进程以重新加载的信号。 默认为 SIGHUP 。
对于给定的方法 argument ，如果未定义 argument_cmd ，则 run_rc_command 提供默认方法：
Argument
Default method
如果 command 未运行且 checkyesno rcvar 成功，则启动 command 。
使用 check_pidfile 或 check_process （根据需要）确定 command 的 PID， kill sig_stop 这些 PID，并在这些 PID 上运行 wait_for_pids 。
与 stop 类似，只是它使用 sig_reload 代替，并且不运行 wait_for_pids 。 与 stop 的另一个区别是默认情况下不提供 reload 。 如果合适，可以通过 extra_commands 启用它：
extra_commands=reload
运行 stop 方法，然后运行 start 方法。
显示 command 的 PID，或一些其他脚本特定的状态操作。
等待 command 退出。
显示使用了哪个 rc.conf(5)- 变量（如果有）。 即使适当的 rc.conf(5) 变量设置为 “NO” ，此方法也始终有效。
以下变量可用于方法（例如 argument_cmd) 以及 run_rc_command 完成后：
rc_arg
在执行快速和强制处理后，提供给 run_rc_command 的参数。
rc_flags
用于启动默认命令的标志。 默认为 ${name}_flags ，除非被环境变量 ‘flags’ 覆盖。 这个变量可以通过 argument_precmd 方法改变。
rc_service
正在执行的服务脚本的路径，以防它需要重新调用自身。
rc_pid
command 的 PID（如果适用）。
rc_fast
如果使用 “fast” 前缀，则不为空。
rc_force
如果使用 “force” 前缀，则不为空。
Start the script file 使用 argument 的参数启动脚本文件，并处理脚本的返回值。
在 file 启动之前未设置各种 shell 变量：
name, command, command_args, command_interpreter, extra_commands, pidfile, rcvar, required_dirs, required_files, required_vars, argument_cmd, argument_precmd. argument_postcmd.
file 的启动行为取决于以下检查：
如果 file 以 .sh- 结尾，则将其来源到当前 shell。
如果 file 看起来是备份或临时文件（例如，带有 ~, #, .OLD 或 .orig 后缀），请忽略它。
如果 file 不可执行，则忽略它。
如果 rc.conf(5) 变量 rc_fast_and_loose 为空，则源 file 在子 shell 中，否则源 file 到当前 shell。
防止引导到多用户模式。 如果 autoboot 变量设置为 ‘yes’ (请参阅 rc(8) 以了解有关 autoboot 的更多信息），或者 checkyesno 始终指示真值，则向父进程发送 SIGTERM 信号，假定为 rc(8) 。 否则，shell 以非零状态退出。
等到所有提供的 pid 不再存在，每两秒打印一次未完成的 pid 列表。
向 stderr 显示警告消息并使用 logger(1) 将其记录到系统日志中。 警告消息包含脚本名称（从 $0 开始），后跟 “: WARNING: ”, 然后是 message 。
/etc/rc.subr
rc.subr 文件位于 /etc 中。
rc.conf(5), rc(8)
rc.subr 脚本出现在 NetBSD 1.3 中。 rc.d(8) 支持函数出现在 NetBSD 1.5 中。 rc.subr 脚本最早出现在 FreeBSD 5.0 中。
July 31, 2020
FreeBSD 13.1-RELEASE
action file current backup
var
pidfile procname [interpreter]
procname [interpreter]
message
exitval message
name
message
[-e regex] [-m module] file
name
name var
type
command ...
item ...
argument
file argument
[always]
[pid ...]
message