osquery 选项与命令行参数开发指南:基于 gflags 的 FLAG 封装机制全解析
osquery 选项与命令行参数开发指南:基于 gflags 的 FLAG 封装机制全解析
导读
本文以 docs/wiki/development/options-arguments.md 为核心,系统讲解如何在 osquery 的守护进程(osqueryd)与交互式 shell(osqueryi)中新增自定义命令行参数(flag / option / argument)。你将掌握 osquery 对 Google gflags 的封装思路、FLAG 系列宏的完整用法(含 SHELL_FLAG、EXTENSION_FLAG、CLI_FLAG、HIDDEN_FLAG 与 FLAG_ALIAS),理解参数如何在 --help 中呈现、如何被配置文件的 options 键覆盖,以及底层 osquery/core/flags.h、osquery/core/flags.cpp 和 osquery/core/flagalias.h 的实现原理,最终能够为 osquery 贡献符合项目规范的新参数。
为什么 osquery 要封装 gflags
osquery 的命令行参数体系建立在 Google 的 gflags 之上。gflags 提供了 DEFINE_bool、DEFINE_string、DEFINE_int32、DEFINE_uint64、DEFINE_double 等宏,可以快速生成全局变量与命令行解析逻辑。
但 osquery 的调用场景比一般二进制更复杂:同一份代码要同时服务于 osqueryd 守护进程、osqueryi 交互式 shell,以及通过 Thrift 协议加载的外部扩展(extension)。不同运行形态对参数有着不同的可见性与可变性要求:
- 某些参数只在 shell 中生效;
- 某些参数只属于外部扩展;
- 某些参数只能在启动命令行(或 flagfile)中设置,不能在配置文件的
options键中下发; - 某些参数需要从
--help输出中隐藏; - 某些参数(旧名)需要作为别名兼容旧版本。
原生 gflags 宏无法表达这些语义。因此 osquery 在 osquery/core/flags.h 中定义了一个极简包装层:用 osquery 自己的 FLAG 宏替换 DEFINE_* 宏,同时在内部维护一份 std::map<std::string, FlagDetail> 元数据表(见 flags.h 的 Flag 类),记录每个参数的描述、shell/extension/cli/hidden 标记、默认值与当前值。
从源码结构看,osquery/core/flags.cpp 中的 Flag::create 只是把 FlagDetail 插入 flags_ 映射,真正的值存储仍然完全由 gflags 的 FLAGS_xxx 全局变量承担——封装层只做“登记”与“查询”,不重复存储,这正是该设计轻量且无侵入的原因。
正确的定义方式:使用 FLAG 宏
错误示范:直接使用 gflags 宏
原文档明确指出,在 osquery 代码库中不应直接写 gflags 宏:
#include <gflags/gflags.h>
// This is the WRONG way to define a flag in osquery.
DEFINE_bool(you_are_awesome, true, "Ground truth for awesome."); // DON'T DO THIS!
这样定义的参数虽然能被 gflags 解析,但 osquery 的 Flag 元数据表中没有它的记录,导致:
osqueryd --help/osqueryi --help的自定义排版输出中不会出现该参数;- 无法被配置文件
options键通过Flag::updateValue更新; - 无法获得 shell / extension / cli / hidden 等语义分类。
正确示范:使用 osquery 封装
#include <osquery/core/flags.h>
FLAG(bool, you_are_awesome, true, "Ground truth for awesome.");
FLAG 宏展开后等价于(见 flags.h 中 OSQUERY_FLAG 宏定义):
DEFINE_bool(you_are_awesome, true, "Ground truth for awesome.");
namespace flags {
const int flag_you_are_awesome = Flag::create(
"you_are_awesome", {"Ground truth for awesome.", 0, 0, 0, 0});
}
即:仍然调用 gflags 的 DEFINE_* 生成 FLAGS_you_are_awesome 全局变量,同时通过 Flag::create 把 FlagDetail(描述、shell、external、cli、hidden)登记到内部表中。namespace flags 中生成的 const int 用于在静态初始化阶段触发登记,这也是 osquery/core/tests/flags_tests.cpp 中 FLAG(string, test_string_flag, "TEST STRING", "TEST DESCRIPTION"); 生效的机制。
声明与访问方式不变
如果你的代码只声明(不定义)某个在其他编译单元定义的参数,用法与 gflags 完全一致:
DECLARE_bool(you_are_awesome);
访问参数值也完全一致:
if (FLAG_you_are_awesome) {
// do something awesome
}
唯一的差异只发生在定义参数的环节。保持声明与访问方式不变,意味着存量 gflags 代码迁移到 osquery 封装层的成本极低。
NOTICE:默认值必须使用字面量
原文档特别强调:
NOTICE: restrict your default values to code literals. It does not help to abstract the default variable into a constant then use it singularly in the macro.
即默认值必须写成 C++ 字面量(如 true、"str"、10),不要预先抽象成常量再传入宏。原因在于宏展开发生在预处理阶段,DEFINE_*(n, v, d) 会把 v 原样嵌入到 FLAGS_xxx 的初始化语句与 gflags 注册信息中;传入非字面量符号可能导致默认值无法被 gflags 正确登记,也会破坏 osquery/core/flags.cpp 中 Flag::getDefaultValue 通过 flags::GetCommandLineFlagInfo 读取的默认值语义。保持字面量还能让 --help 输出中的默认值展示准确、稳定。
五个场景化宏:FLAG / SHELL_FLAG / EXTENSION_FLAG / CLI_FLAG / HIDDEN_FLAG
OSQUERY_FLAG 是底层宏,代码库内禁止直接使用,应使用下面五个派生宏(定义见 osquery/core/flags.h):
| 宏 | 语义标记(shell/external/cli/hidden) | 适用场景 |
|---|---|---|
FLAG(t, n, v, d) |
0,0,0,0 |
普通参数,osqueryd 与 osqueryi 均可用,也允许在配置 options 中设置 |
SHELL_FLAG(t, n, v, d) |
1,0,0,0 |
仅在 osqueryi(shell)中有效的参数 |
EXTENSION_FLAG(t, n, v, d) |
0,1,0,0 |
仅适用于外部扩展的参数 |
CLI_FLAG(t, n, v, d) |
0,0,1,0 |
只能在命令行/flagfile 设置,禁止在配置 options 中下发 |
HIDDEN_FLAG(t, n, v, d) |
0,0,0,1 |
从 --help 输出中隐藏的参数 |
其中 FlagDetail 结构体定义在 flags.h:
struct FlagDetail {
std::string description; // 帮助文本
bool shell; // 是否仅 shell 可见
bool external; // 是否仅扩展可见
bool cli; // 是否只能通过 CLI/flagfile 设置
bool hidden; // 是否从 --help 隐藏
};
真实代码示例
- 通用
FLAG:osquery/core/tables.cpp#L23 定义FLAG(bool, disable_caching, false, "Disable scheduled query caching"); CLI_FLAG:osquery/config/config.cpp#L77 定义CLI_FLAG(string, config_plugin, "filesystem", "Config plugin name");——配置插件名必须在加载配置之前确定,因此只能从命令行传入,这也正是 plugins/config/parsers/options.cpp 会拒绝为cli标记参数执行Flag::updateValue的原因;SHELL_FLAG与EXTENSION_FLAG:见单元测试 osquery/core/tests/flags_tests.cpp#L85-L86 中的SHELL_FLAG(bool, shell_only, true, ...)与EXTENSION_FLAG(bool, extension_only, true, ...)。
CLI 参数在帮助输出中的过滤逻辑
osquery/core/flags.cpp 中 Flag::printFlags 实现了 --help 的排版逻辑:按名字计算对齐缩进(最大名字宽度加 6 个字符的 VALUE 占位)、bool 类型不输出 VALUE、并依据传入的 shell / external / cli 布尔参数过滤可见性,hidden 参数一律跳过。而 osquery/core/init.cpp 中 printUsage 根据工具类型组合调用:
- 守护进程/普通工具:先打印 CLI 参数(
Flag::printFlags(false, false, true)),再打印普通参数; - 扩展:只打印 external 参数;
- shell:额外打印 shell 参数。
这解释了为什么用 FLAG 而非裸 DEFINE_* 能让调用者获得漂亮的 -h, --help 展示——帮助输出完全由 osquery 自己的元数据驱动。
声明式参数别名:FLAG_ALIAS
为了支持被废弃/改名的参数,osquery 提供别名机制。相关宏定义在 osquery/core/flagalias.h:
FLAG_ALIAS(t, alias_name, real_name); // 普通别名
SHELL_FLAG_ALIAS(t, alias_name, real_name); // shell 别名
EXTENSION_FLAG_ALIAS(alias_name, real_name); // 扩展别名(string 类型)
其底层通过模板类 FlagAlias<T> 包装 Flag::updateValue 与 Flag::getValue,并以 FLAGS_alias_name 命名生成全局变量,避免与 gflags 命名规则冲突(见 flagalias.h 中 OSQUERY_FLAG_ALIAS)。对别名的读写会透明地转发到真实参数:写别名等价于更新真实参数,读别名等价于读取真实参数的值。单元测试 osquery/core/tests/flags_tests.cpp#L97-L152 完整覆盖了 bool、int32、int64、double、string 五种类型的别名读写与双向同步。
参数值如何被读取与更新:Flag 类核心 API
osquery/core/flags.cpp 中的 Flag 类提供了统一的查询/更新接口,是“封装层”的实际实现:
| API | 说明 | 源码位置 |
|---|---|---|
Flag::getValue(name) |
返回参数当前值;优先查 custom_ 表,其次查 gflags;若当前进程是外部扩展且参数未找到,会向配置注册表转发 option 请求 |
flags.cpp#L70-L93 |
Flag::getDefaultValue(name, value) |
通过 gflags GetCommandLineFlagInfo 读取默认值 |
flags.cpp#L51-L59 |
Flag::isDefault(name) |
判断参数是否仍为默认值(未被覆盖) | flags.cpp#L61-L68 |
Flag::updateValue(name, value) |
更新参数值;支持普通参数、别名(转发到真实名字)以及以 custom_ 开头的自定义参数 |
flags.cpp#L129-L142 |
Flag::isCLIOnlyFlag(name) |
判断是否为 CLI-only 参数 | flags.cpp#L118-L127 |
Flag::getType(name) / getDescription(name) |
读取类型与描述 | flags.cpp#L99-L116 |
从源码看三种参数设置途径
FLAG 宏的注释(flags.h)明确指出一个 FLAG 可以经由三种途径设置:
- flagfile:通过
--flagfile PATH指定行分隔的附加参数文件;osquery/core/init.cpp 中的初始化逻辑 检测到 flagfile 后会停止加载默认 flagfile(kBackupDefaultFlagfile),daemon 与服务通常都会设置 flagfile; - 命令行开关:如
--config_plugin=tls,由 gflags 的ParseCommandLineFlags统一解析(见 init.cpp#L355); - 配置文件的
options键:由 plugins/config/parsers/options.cpp 中的OptionsConfigParserPlugin处理。
options 解析器的实现细节
plugins/config/parsers/options.cpp#L49-L123 的 update 函数展示了配置下发参数的完整流程:
- 从 JSON 配置中读取
options对象,与已有数据合并(mergeObject); - 将每个选项的值序列化为字符串(支持 string/bool/int/number,对象与数组会序列化为 JSON 字符串);
- 参数校验:非
custom_前缀且Flag::getType(name)为空时打印Cannot set unknown or invalid flag并跳过; - CLI-only 拦截:
Flag::isCLIOnlyFlag(name)为真时打印警告The CLI only flag --xxx set via config file will be ignored, please use a flagfile or pass it to the process at startup并跳过; - 通过
Flag::updateValue(name, value)真正生效; - 对于
kVerboseOptions集合(verbose、minloglevel、logger_min_status、stderrthreshold、logtostderr等日志相关参数),额外触发setVerboseLevel()以即时调整日志冗长级别。
配置加载时 options 解析器会被优先应用(见 osquery/config/config.cpp 中 update 的相关注释),因为后续的其他配置解析器可能依赖这些 flag 值。完整的 options 配置示例可参考 docs/wiki/deployment/configuration.md:options 键是一组“参数名到参数值”的映射,参数名必须是 osquery 参数集合中的 CLI flag(osqueryd --help 可枚举完整列表);若某参数已在命令行或 flagfile 中指定,配置中的等价 options 键会覆盖它;同时有大量决定启动与初始化流程的 flag 不允许用 options 设置,需以 --help 列表判断是否适用。
参数在帮助输出中的呈现
在启动参数解析之前,osquery/core/init.cpp 的初始化流程 会先扫描 argv:识别到 --help、-help、--h、-h 时立即调用 printUsage 并退出;识别 -S/-D 用于在单一二进制中切换 shell / daemon 模式(SHELL_DAEMON 工具类型下还会依据 argv[0] 的文件名判断)。
printUsage 的输出结构为:版本信息 → 用法行 → CLI 参数块 → 普通参数块(OPTIONS)→ shell 参数块(仅 shell 模式)→ 结尾语。每个参数按 --name <a href="https://link.gitcode.com/i/a1f0fcbe843003f1435deb80fb0a11cd" target="_blank">VALUE] description 的格式对齐打印,其中 VALUE 占位符仅对非 bool 类型出现(见 [flags.cpp#L216-L229)。
因此,当你用 FLAG 定义参数后,用户在 osqueryd --help 或 osqueryi --help 中就能立即看到它,且描述的准确性直接取决于宏的第四个参数 d——请保持描述简洁、清晰。
单元测试与验证方式
osquery 为参数封装层提供了完备的单元测试:osquery/core/tests/flags_tests.cpp,覆盖:
- 读写:
test_set_get验证FLAGS_test_string_flag与Flag::getValue一致(L43-L54); - 默认值跟踪:
test_defaults验证isDefault与getDefaultValue(L56-L70); - 元数据登记:
test_details验证Flag::flags()返回的FlagInfo中类型、描述、默认值、当前值与shell/external标记均正确(L72-L83); - 场景宏:
test_flag_detail_types验证SHELL_FLAG与EXTENSION_FLAG的标记位(L88-L95); - 别名:
test_aliases与test_alias_types验证各类别名的双向同步(L97-L152)。
如果你为 osquery 新增参数,可以参考这些测试模式,在新增参数定义旁补充对应的 Flag::flags() 断言,确保元数据登记正确。
给参数贡献者的一页速查
- 包含头文件:
#include <osquery/core/flags.h>(别名场景另含osquery/core/flagalias.h); - 定义参数:根据作用域选择
FLAG、SHELL_FLAG、EXTENSION_FLAG、CLI_FLAG或HIDDEN_FLAG,默认值必须是 C++ 字面量,描述保持简洁; - 不要直接使用
DEFINE_*:否则参数不会出现在 osquery 的--help输出中,也无法被配置options下发; - 跨编译单元使用:用
DECLARE_bool(name)声明,用FLAGS_name访问,与 gflags 完全一致; - 参数命名:以
custom_开头的参数会被视为自定义参数(存入Flag::custom_表,见 flags.cpp#L138-L140),适合运行期动态注册的场景; - 验证呈现:编译后运行
osqueryi --help(shell 参数)与osqueryd --help(daemon 参数)确认排版与过滤符合预期; - 兼容旧名:需要保留旧参数名时使用
FLAG_ALIAS系列宏,避免破坏存量调用方。
按此流程定义的新参数,将同时获得 gflags 的解析能力与 osquery 的元数据管理能力,成为 osquery 参数体系中规范、可文档化的一部分。