Puppet config 子命令完全指南：通过命令行安全地读写 puppet.conf-开发者社区

运维
DevOps
IaC

【免费下载链接】puppet

Server automation framework and application

项目地址：https://gitcode.com/gh_mirrors/pu/puppet

导读

puppet config是 Puppet 提供的一个用于与puppet.conf配置文件交互的子命令，它支持查看（print）、修改（set）和删除（delete）Puppet 的各项设置。本指南以 Puppet 官方生成的 man page（references/man/config.md）为骨架，结合仓库内 face 源码与单元测试，完整讲解该命令的语法、section 域概念、三个动作的底层行为及可复用的实战示例。读完本文，你将能够用一条命令快速定位任意配置项当前生效的值，并安全地把新配置写入指定 section，而无需手工编辑 INI 文件。

命令概览：定位与基本语法

puppet config属于 Puppet 的 face 体系，其命令入口定义在 lib/puppet/application/config.rb，该入口类仅继承Puppet::Application::FaceBase并声明environment_mode :not_required，说明它可以在不指定环境的情况下运行，实际动作逻辑全部由 face lib/puppet/face/config.rb 实现。

命令的基本语法为：

puppet config <action> [--section SECTION_NAME]

其中action可选print、set、delete三个动作之一。该命令的官方用途说明是：

"This subcommand can inspect and modify settings from Puppet's 'puppet.conf' configuration file."

与直接手工编辑文件相比，puppet config的好处在于：它会经过 Puppet 设置系统完整的校验、插值（interpolation）与 munge 逻辑，并在正确的配置域（section）中写入，避免因手误导致配置不生效。

理解 puppet.conf 与 section 域

所有puppet config操作都围绕puppet.conf展开。仓库中的 conf/puppet.conf 提供了一个最小骨架，说明该文件用于覆盖默认设置，并提示完整的设置清单可在配置文档中查看。

puppet.conf采用 INI 格式，由多个 section 组成。--section选项用于指定要交互的 section，其完整语义定义在 face 源码的option "--section"中（lib/puppet/face/config.rb#L19-L36）：

section	作用范围	说明
`main`	所有 Puppet 应用	默认 section。任何 Puppet 应用都会读取`main`中的设置
`server`	Puppet Server	仅影响服务端（如`puppetserver`/`puppet master`）
`agent`	puppet agent	仅影响 agent 端运行
`user`	puppet apply 等	影响`puppet apply`及其他面向用户的子命令
其他任意名字	遗留环境（legacy environment）	被视为一个已废弃的遗留环境名，且只能包含`manifest`与`modulepath`两个设置

main之外的 section 用于覆盖（override）main中的值，从而实现同一台机器上服务端与客户端配置的差异化。face 源码中通过DEFAULT_SECTION = "main"与一个哨兵对象DEFAULT_SECTION_MARKER来区分"用户未指定 section"与"用户显式指定了 main"两种情况（lib/puppet/face/config.rb#L17-L20）；当未指定 section 时，命令会默认落入main，并在 verbose 级别下打印提示信息。

全局选项

所有动作都共享以下通用选项：

--section SECTION_NAME—— 指定要交互的 puppet.conf 区块（即上文表格中的各域）。这是puppet config最重要的选项，三个动作均支持。

--render-as FORMAT—— 指定输出渲染格式。最常见的是json、s（string）、yaml和console，某些场景下还可用dot等格式。该选项来自 Puppet face 的通用渲染机制，例如puppet config print all --render-as json可得到便于程序消费的 JSON 输出。

--verbose—— 输出详细日志；--debug—— 输出调试信息。在 verbose 级别下，命令还会打印"从哪个 section、哪个环境解析设置"的提示（Resolving settings from section '...' in environment '...'），见 lib/puppet/face/config.rb#L99-L116。

任意配置项均可作为长参数：如 man page 所述，任何在配置文件中合法的设置同样可以写成命令行长参数，例如--server <servername>、--run_mode <runmode>。这意味着你可以把某个设置临时叠加到本次puppet config调用的解析上下文中。

此外，Puppet 还提供两种查看全部可用配置项的途径：

查看配置文件文档中可接受参数的完整列表；
运行puppet --genconfig生成一份带注释的、包含每个设置当前（或默认）值的示例配置输出。该行为由设置项genconfig控制，其定义为"为 true 时让 Puppet 应用打印一份示例配置文件到 stdout 后退出"（lib/puppet/defaults.rb#L304-L311）。

动作一：print —— 查看当前设置

语法与行为

puppet config print [--section SECTION_NAME] all | <setting> [<setting> ...]

print用于输出单个设置或一组设置的值。它是旧接口puppet <subcommand> --configprint的替代方案。未指定参数时等价于传入all，输出全部设置（源码中args.empty? || args == ['all']统一映射为:all，见 lib/puppet/face/config.rb#L76-L80）。

其输出规则（console 渲染器）很直观：

单个设置：只输出值本身，不输出设置名；
多个设置 / all：按字母序逐行输出setting = value。

底层原理

print的核心调用是Puppet.settings.stringify_settings(options[:section], names)（lib/puppet/settings.rb#L95-L118）。该方法的要点在于：

先取指定 section 的值，解析出environmentpath与basemodulepath，用它们构造新的 environment loader；
再基于当前环境重新解析一遍全部值——因此打印出的manifest、modulepath等会真实反映环境目录（environment）解析后的最终结果；
将结果递归地字符串化（Symbol、Hash 等都被转换为字符串），便于网络格式消费。

这一点在测试中有明确验证：当environment.conf里写了modulepath=/custom/modules:$basemodulepath时，print输出的 modulepath 会正确插值为/custom/modules:/some/base（spec/unit/face/config_spec.rb#L332-L353）；而当引用的环境不存在时，manifest与modulepath会输出为空字符串（spec/unit/face/config_spec.rb#L355-L374）。

示例

# 获取 Puppet 的 runfile 目录（PID 文件存放处） $ puppet config print rundir # 从 server 的配置中筛出所有与路径、目录相关的设置 $ puppet config print all --section server | grep -E "(path|dir)" # 以 JSON 格式输出全部设置（便于脚本处理） $ puppet config print all --render-as json

rundir与vardir这两个设置的定义都位于 lib/puppet/defaults.rb 中：rundir是 "Where Puppet PID files are kept"，类型为目录、权限 0755（lib/puppet/defaults.rb#L296-L303）；vardir是 "Where Puppet stores dynamic and growing data"，其默认值根据运行用户是 service 用户还是普通用户而特殊计算（lib/puppet/defaults.rb#L92-L99）。

动作二：set —— 写入配置

语法与行为

puppet config set [--section SECTION_NAME] <setting_name> <setting_value>

set更新puppet.conf中的值。默认操作main域，可用--section指定其他域。写入流程（lib/puppet/face/config.rb#L139-L198）包括：

若目标文件不存在，先touch创建它；
仅对认识的设置做校验：通过Puppet.settings.setting(name.to_sym)查找设置对象（lib/puppet/settings.rb#L468-L471），存在则赋值并再次读取以触发插值与 munge 校验；
以 UTF-8 编码打开配置文件，用Puppet::Settings::IniFile.update完成落盘。

值得注意的两个行为

（1）mastersection 会被自动迁移到server：如果显式指定--section master写入，face 会先删除master中已有的同名设置（如有），并打印 "Deleted setting from 'master': '...', and adding it to 'server' section"，最终写入serversection。测试用例 spec/unit/face/config_spec.rb#L204-L235 验证了这一迁移逻辑。这是因为master已被server取代。

（2）在main中设置environment会收到警告：源码会提示应将 environment 放在[user]、[agent]或[server]中，因为puppet agent使用[agent]的值，而puppet apply、puppet module等子命令使用[user]的值，且这些环境要求对应环境目录在本机存在（lib/puppet/face/config.rb#L146-L157）。

INI 文件写入的底层实现

set的落盘完全依赖 lib/puppet/settings/ini_file.rb。该解析器按行识别三种结构：section 行（[name]）、设置行（name = value）和其他普通行。Manipulator#set的逻辑是：目标 section 中已有同名设置则直接改值，否则在 section 末尾（或文件末尾新建 section）追加一行（lib/puppet/settings/ini_file.rb#L128-L157）。写入时若main中存在设置但文件中没有显式的[main]行，还会自动补写 section 行，且不会重复生成两个[main]（测试 spec/unit/face/config_spec.rb#L184-L197 专门验证了"不重复已有默认 section"的行为）。

示例

# 设置 Puppet 的 runfile 目录（写入 [main]） $ puppet config set rundir /var/run/puppetlabs # 仅对 agent 设置 vardir（写入 [agent]） $ puppet config set vardir /opt/puppetlabs/puppet/cache --section agent # 把环境指定写入 [user]（供 puppet apply 等使用） $ puppet config --section user set environment production

动作三：delete —— 删除配置

语法与行为

puppet config delete [--section SECTION_NAME] <setting>

delete从指定 section（默认main）删除一个设置。行为细节（lib/puppet/face/config.rb#L221-L265）：

若配置文件不存在，仅打印警告The puppet.conf file does not exist ...，不做其他操作（测试见 spec/unit/face/config_spec.rb#L238-L252）；
若目标 section 中找不到该设置，打印警告 "No setting found in configuration file for section '...' setting name '...'"（spec/unit/face/config_spec.rb#L275-L284）；
特殊行为：当指定--section master或--section server时，会同时从master与server两个 section 中删除同名设置（spec/unit/face/config_spec.rb#L286-L301），以彻底清除可能的历史残留。

示例

# 从 [main] 域删除设置 'setting_name' $ puppet config delete setting_name # 从 [server] 域删除设置 'setting_name' $ puppet config delete setting_name --section server

配置文件定位规则

puppet config修改的是哪一份 puppet.conf？这由 lib/puppet/settings.rb#L1248-L1254 的which_configuration_file决定：

若命令行显式指定了--config文件，则使用该文件；
若以 root 进程运行，使用系统级 puppet.conf（通常为/etc/puppetlabs/puppet/puppet.conf）；
否则使用用户级 puppet.conf（通常为~/.puppetlabs/etc/puppet/puppet.conf）。

因此普通用户直接执行puppet config set不会误写系统级配置；需要写系统配置时应在具备相应权限的环境下运行。此外，配置文件的默认文件名恒为puppet.conf（lib/puppet/settings.rb#L91-L93）。

典型排查场景速查

目标	命令
查看某个设置当前生效值	`puppet config print <setting>`
查看服务端所有路径类设置	`puppet config print all --section server \\| grep -E "(path\\|dir)"`
确认 agent 的缓存目录	`puppet config print vardir --section agent`
为 agent 单独修改缓存目录	`puppet config set vardir /path --section agent`
清除某 section 中的设置	`puppet config delete <setting> --section server`
生成带注释的完整配置样例	`puppet --genconfig`
脚本化读取全部配置	`puppet config print all --render-as json`