跳转到内容
安装

配置

Volant 读取的 ansible.cfg 设置和环境变量,按段列出,并附带默认值。

Volant 读取与 ansible-playbook 相同的 ansible.cfg,并在找到的第一个文件处停止:

  1. ANSIBLE_CONFIG 指定的文件
  2. ./ansible.cfg
  3. ~/.ansible.cfg
  4. /etc/ansible/ansible.cfg

当工作目录可被其他用户写入(权限位 o+w)时,Volant 会跳过 ./ansible.cfg,与 ansible-playbook 一样。其他本地用户可能在那里放了这个文件。粘滞位和目录的所有者都不会改变这一点。Volant 会在标准错误上打印 [WARNING]: Ansible is being run in a world writable directory (...), ignoring it as an ansible.cfg source.,然后继续读取下一个文件。ANSIBLE_CONFIG 指定的文件则不论工作目录的权限如何都会读取。

对于每个设置,环境变量优先于文件,命令行选项又优先于两者。Volant 用不到的键会被忽略,就像 Ansible 忽略它用不到的键一样。

存在但无法读取的文件会被跳过,运行使用默认值继续。Volant 会先打印一条警告,这一点 Ansible 不会做:你写的文件进程却打不开,值得提示一行,而警告不会改变退出码。

inventory 来源,以逗号分隔的列表。见 Inventory。

Option
-i
Environment
ANSIBLE_INVENTORY

等待连接的秒数。它会成为 ssh 命令行上的 ConnectTimeout。

Default
10
Option
-T
Environment
ANSIBLE_TIMEOUT

登录所用的用户。不设置时,由 ssh 选择一个。

Option
-u
Environment
ANSIBLE_REMOTE_USER

ssh 用来认证的私钥。

Option
--private-key
Environment
ANSIBLE_PRIVATE_KEY_FILE

开启时,未知的主机密钥会让该主机不可达。关闭时,Volant 会添加 StrictHostKeyChecking=no 和 UserKnownHostsFile=/dev/null,所以未知的密钥会被接受,但不会被记录。

Default
true
Environment
ANSIBLE_HOST_KEY_CHECKING

每台主机上存放 agent 缓存的目录。

Default
~/.ansible/tmp
Environment
ANSIBLE_REMOTE_TMP

一个 play 同时处理多少台主机。零或不是数字的值会在运行开始前被拒绝。playbook 通过 ansible_forks 读取当前值。

Default
5
Option
-f
Environment
ANSIBLE_FORKS

未指定策略的 play 所用的策略:linear、free、host_pinned 或 debug,也可写在 ansible.builtin. 之下。其他名称会先打印 ansible-core 对 ansible.builtin 之外策略插件的弃用警告。继承其中之一且不添加任何内容的插件按该策略运行,其他名称会被拒绝。

Default
linear
Environment
ANSIBLE_STRATEGY

每台主机上存放异步 task状态文件的目录。ansible_async_dir 会覆盖它。

Default
~/.ansible_async
Environment
ANSIBLE_ASYNC_DIR

在每个失败或不可达的 task 之后打开调试器。

Default
false
Environment
ANSIBLE_ENABLE_TASK_DEBUGGER

在失败 task 的 fatal: 行之前打印 task path: <file>:<line>。从 -vv 起,这一行已经跟在每个 task 横幅之后,所以在那里这个设置没有任何变化。循环项的 failed: 行和不可达的主机不会得到路径行。与 Ansible 一样,y、yes、on、true、t 和 1 在任何大小写下都会开启它,其他任何词(包括空的环境变量)都保持关闭。

Default
false
Environment
ANSIBLE_SHOW_TASK_PATH_ON_FAILURE

即使输出不是终端也着色,CI 日志需要这样。它优先于 nocolor、ANSIBLE_NOCOLOR 和 NO_COLOR;只有 --no-color 优先于它。在 diff 中,只有 Ansible 的 difflib 根据 before 和 after 生成的那些行会着色。

Default
false
Environment
ANSIBLE_FORCE_COLOR

输出从不着色。force_color 优先于它。

Default
false
Environment
ANSIBLE_NOCOLOR

哪些事件显示 traceback,用逗号分隔。设为 error 或 always 时,汇总错误的 Python action 插件失败(例如运行 fact 模块的 gather_facts)会显示它自己和其模块的 traceback,并注册为 exception。其他失败仍为 (traceback unavailable)。

Default
never
Environment
ANSIBLE_DISPLAY_TRACEBACK

打印 [DEPRECATION WARNING] 通知,以及说明如何关闭它们的那一行。设为 False 则两者都不打印。

Default
true
Environment
ANSIBLE_DEPRECATION_WARNINGS

结果不是布尔值的条件默认会失败。设为 True 时,按结果的真值判断,并打印 [DEPRECATION WARNING]。

Default
false
Environment
ANSIBLE_ALLOW_BROKEN_CONDITIONALS

运行显示的每一行都会追加到这个文件,每条消息一条记录,格式与 Ansible 相同:2026-10-30 18:34:18,430 p=<pid> u=<user> n=ansible INFO| TASK [...] ***,[WARNING] 记为 WARNING,[ERROR] 记为 ERROR。

Default
unset
Environment
ANSIBLE_LOG_PATH

一行在运行未显示时,只要它所需的 -v 数不超过此值,仍会写入 log_path。

Default
0
Environment
ANSIBLE_LOG_VERBOSITY

当 inventory 中没有任何主机、只剩下隐式的 localhost 时给出警告。all 不会匹配这台主机。

Default
true
Environment
ANSIBLE_LOCALHOST_WARNING

一个 YAML 文件,其 module_rejectlist 列出不能使用的模块,路径相对于配置文件。命名其中某个模块的 task 会在运行前、在该 task 处让 playbook 停止,并给出 couldn't resolve module/action,与拼错的模块相同。只拒绝列表中所写的名称:列表中的 copy 不影响 ansible.builtin.copy。ansible-core 2.19.12 不为此读取任何环境变量。

Default
unset

让 roles: 中的 role 或未写 public 的 import_role 把自己的 defaults 和 vars 留在内部。设为 false 时,未写 public 的 include_role 也会对外提供它们。不设置时,只有 include_role 会保留它们。

Default
unset
Environment
ANSIBLE_PRIVATE_ROLE_VARS

merge 会在任意两个变量来源之间、以及两个 inventory 来源之间,把同名 mapping 按键逐个合并。replace 则完整保留优先级更高来源的值。该选项在 Ansible 中已弃用,但仍会生效,且不会给出警告。

Default
replace
Environment
ANSIBLE_HASH_BEHAVIOUR

即使在失败的主机上,也运行已被 notify 的 handler。

Default
false
Option
--force-handlers
Environment
ANSIBLE_FORCE_HANDLERS

同一映射中写了两次的 YAML 键如何处理:warn 保留最后一个值并指出第二个键的位置,error 拒绝该文件,ignore 保留最后一个值且不提示。

Default
warn
Environment
ANSIBLE_DUPLICATE_YAML_DICT_KEY

play 收集 facts 时运行的 fact 模块,未设置时为 smart(setup)。plays、其任务或清单中的字面列表(ansible_facts_modules)也会被读取;只由模板给出的模块无法运行。

Default
smart
Environment
ANSIBLE_FACTS_MODULES

在未设置 ansible_python_interpreter 的主机上运行模块所用的 Python;主机变量优先于此设置。auto 和 auto_silent 在主机上查找解释器,auto_silent 不打印指出所找到解释器的警告。auto_legacy 和 auto_legacy_silent 与 auto 和 auto_silent 相同,并附加 ansible-core 的弃用提示。其他任何值都是解释器的路径。

Default
auto
Environment
ANSIBLE_PYTHON_INTERPRETER

from_json 是否拒绝含有孤立代理字符(如 \udc80)的字符串。关闭时,值保留该字符,打印时以 ? 代替,并给出警告。

Default
true
Environment
ANSIBLE_MODULE_STRICT_UTF8_RESPONSE

在汇总之后打印 set_stats 收集的统计信息。

Default
false
Environment
ANSIBLE_SHOW_CUSTOM_STATS

打印运行过程的 callback。default 打印横幅、每个结果一行以及汇总。minimal 像 ad hoc 命令一样打印每个结果:命令是 host | CHANGED | rc=0 >> 加输出,其他是 host | SUCCESS => 加 JSON 结果,没有横幅、没有汇总,也没有每个循环项的行。oneline 把同样的结果各打印在一行上;ansible-core 2.19.12 把它标为弃用,Volant 会在标准错误上打印一次它的警告。tree 在标准输出上什么都不打印。带 ansible.builtin. 的名字也可以用。yaml 会以退出码 1 和 community.general 自 12.0.0 起打印的错误停止运行,那个版本移除了这个插件:请改用 callback_result_format = yaml。json 和 ansible.posix.json 在运行期间什么都不打印,结束时把整次运行打印成一个 JSON 文档:每个 play 和 task 带上时间、id 和路径,每台主机的结果按 task 返回的样子并带上 action,按主机的汇总,以及 show_custom_stats 打开时 set_stats 的数据。ASCII 以外的字符写成 \uXXXX。其他任何名字,例如 community.general.unixy,都通过控制端的 ansible-core 加载;找不到时在第一个 play 之前以 [ERROR]: Could not load '<name>' callback plugin. 和退出码 1 停止运行。

Default
default
Environment
ANSIBLE_STDOUT_CALLBACK

default 和 minimal 怎样写出结果:json,或 yaml,此时结果写在 => 之后的各行,缩进四个空格,带换行的文本写成字面块。其他任何值都会在第一个 play 之前以退出码 5 停止运行。oneline 总是写 JSON。

Default
json
Environment
ANSIBLE_CALLBACK_RESULT_FORMAT

default 和 minimal 的 pretty_results。未设置时,JSON 结果只在 debug、assert 以及 -vvv 起缩进,YAML 结果是美化的。打开时,每个结果都缩进四个空格。关闭时,都不缩进,debug 也一样。美化的 YAML 在已有文本时把 stdout_lines 和 stderr_lines 写成 <omitted>,嵌套缩进四个空格,并去掉文本块行尾的空格和制表符,使它保持块形式;不美化的 YAML 保留每个值原样,嵌套缩进两个空格。不是布尔值的词按关闭处理。

Environment
ANSIBLE_CALLBACK_FORMAT_PRETTY

json callback 文档每层的空格数。零或更小时写成一行。

Default
4
Environment
ANSIBLE_JSON_INDENT

在 stdout callback 之外再运行的 callback,以逗号分隔。Volant 运行 junit,它为每个 playbook 在 JUNIT_OUTPUT_DIR(默认 ~/.ansible.log)中写一个 JUnit XML 报告,并读取其他 JUNIT_* 变量;运行 tree,它把每台主机的最后一个结果写入 [callback_tree] directory(ANSIBLE_CALLBACK_TREE_DIR,默认 ~/.ansible/tree)中的文件;当控制端安装了 ansible.posix 时,还运行 ansible.posix.timer 和 ansible.posix.profile_tasks 及其选项([callback_profile_tasks]、PROFILE_TASKS_*)。其他名字都通过控制端的 ansible-core 加载;找不到时打印 [WARNING]: Skipping callback plugin '<name>', unable to load,运行继续。volant.compat.record(用于记录 ansible-playbook 的运行)会被跳过,不打印警告。

Environment
ANSIBLE_CALLBACKS_ENABLED

查找 callback 插件的其他目录,用 : 分隔。在那里或 playbook 旁边的 callback_plugins/ 中找到的插件,通过控制端的 ansible-core 在单独的 Python 进程中运行。没有这类插件的运行不会为此启动 Python。

Environment
ANSIBLE_CALLBACK_PLUGINS

ad hoc 命令是否加载上面的 callback。关闭时,不论 stdout_callback 怎么设,它都用 minimal 打印,带 -o 时用 oneline。见 ad hoc 命令。

Default
false
Environment
ANSIBLE_LOAD_CALLBACK_PLUGINS

保存 vault 密码的文件,或打印该密码的可执行文件。环境变量会替换文件中的值,命令行则追加到胜出的那个值上。见 Vault。

Option
--vault-password-file
Environment
ANSIBLE_VAULT_PASSWORD_FILE

以逗号分隔的 vault 标识,每个写作 label@source,其中来源是文件、可执行文件或 prompt。环境变量会替换文件中的列表,命令行则追加到胜出的那个列表上。

Option
--vault-id
Environment
ANSIBLE_VAULT_IDENTITY_LIST

未给出 --encrypt-vault-id 时,volant vault encrypt 使用的 vault id。见 Vault。

Option
--encrypt-vault-id
Environment
ANSIBLE_VAULT_ENCRYPT_IDENTITY

volant vault create 和 edit 运行的编辑器。最后设置的环境变量优先,其次是文件,最后是 vi。见 Vault。

Environment
ANSIBLE_EDITOR, EDITOR

volant vault create 和 edit 存放编辑器所操作的私有副本的位置。

Default
~/.ansible/tmp
Environment
ANSIBLE_LOCAL_TEMP

在终端上,volant vault view 把输出送入的程序。最后设置的环境变量优先,其次是文件。

Default
less
Environment
ANSIBLE_PAGER, PAGER

查找 role 的位置,在 <playbook_dir>/roles 之后、<playbook_dir> 本身之前。见 role。

Default
~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles
Environment
ANSIBLE_ROLES_PATH

也可以写作 collections_paths,以及通过 ANSIBLE_COLLECTIONS_PATHS 设置,后者优先于 ANSIBLE_COLLECTIONS_PATH。查找 acme.demo.hello 这类由三段组成的 role 名的位置。collection 中的模块由控制节点的 ansible-core 在它所配置的路径中查找:见来自 collection 的模块。

Default
~/.ansible/collections:/usr/share/ansible/collections
Environment
ANSIBLE_COLLECTIONS_PATH

implicit、explicit 或 smart。见 facts 缓存。

Default
implicit
Environment
ANSIBLE_GATHERING

memory 在本次运行期间保留 facts,jsonfile 在多次运行之间保留,其他任何名字都是 Python 插件。见 facts 缓存。

Default
memory
Environment
ANSIBLE_CACHE_PLUGIN

jsonfile 缓存的目录。

Environment
ANSIBLE_CACHE_PLUGIN_CONNECTION

缓存条目保持有效的秒数。0 表示永不过期。

Default
86400
Environment
ANSIBLE_CACHE_PLUGIN_TIMEOUT

加在每个缓存文件名前面。

Environment
ANSIBLE_CACHE_PLUGIN_PREFIX

按顺序尝试的 inventory 插件。见插件链。

Default
host_list, script, auto, yaml, ini, toml
Environment
ANSIBLE_INVENTORY_ENABLED

读取目录时跳过的文件扩展名。设置的值会替换默认列表。[defaults] inventory_ignore_extensions 同样会被读取。

Default
.pyc, .pyo, .swp, .bak, ~, .rpm, .md, .txt, .rst, .orig, .cfg, .retry
Environment
ANSIBLE_INVENTORY_IGNORE

读取目录时要跳过的文件名所用的正则表达式。[defaults] inventory_ignore_patterns 同样会被读取。

Environment
ANSIBLE_INVENTORY_IGNORE_REGEX

在没有任何来源能被读取时让运行失败。

Default
false
Environment
ANSIBLE_INVENTORY_UNPARSED_FAILED

在遇到第一个没有任何插件能读取的来源时就让运行失败。

Default
false
Environment
ANSIBLE_INVENTORY_ANY_UNPARSED_IS_FAILED

让 volant inventory 把每个变量保留在它被设置的地方,与 --export 的作用相同。--export 只对一次运行开启它;命令行上没有任何选项能把它关掉,与 ansible-inventory 一样。见 inventory 命令。

Default
false
Environment
ANSIBLE_INVENTORY_EXPORT

把成功的 inventory 脚本写到标准错误的内容显示为一行 [ERROR]:。设为 false 时,只显示失败脚本的标准错误。

Default
true
Environment
ANSIBLE_INVENTORY_PLUGIN_SCRIPT_STDERR

默认提升权限。playbook 关键字和主机变量优先,见权限提升。

Default
false
Option
-b
Environment
ANSIBLE_BECOME

要提升到的用户。

Default
root
Option
--become-user
Environment
ANSIBLE_BECOME_USER

提升权限的方法:sudo 或 su。其他方法会让运行在开始前就停止。

Default
sudo
Option
--become-method
Environment
ANSIBLE_BECOME_METHOD

用来代替 sudo 或 su 运行的程序。

Environment
ANSIBLE_BECOME_EXE

传给该程序的标志,取代 sudo 的 -H,su 则默认没有标志。空值表示完全不带标志。

Environment
ANSIBLE_BECOME_FLAGS

为 raw、script,以及 reboot 这类模块插件不带输入发送的命令提供终端,就像 ssh -tt 那样。当 sudoers 规则含有 requiretty,或命令在终端上打印控制字符时,把它设为 False。主机变量 ansible_ssh_use_tty 优先于环境变量,环境变量又优先于文件。y、yes、on、true、t 和 1 以外的词都按关闭处理。

Default
true
Environment
ANSIBLE_SSH_USETTY

默认选中的 tag。--tags 是追加到这个列表,而不是替换它。

Option
--tags
Environment
ANSIBLE_RUN_TAGS

默认跳过的 tag。--skip-tags 会追加到这个列表。

Option
--skip-tags
Environment
ANSIBLE_SKIP_TAGS

Ansible 会忽略这个段,所以同一个 ansible.cfg 可以包含它,并同时驱动两个引擎。ansible-config validate 是例外,见跨主机批处理。

默认关闭。设置 batching = true 后,主机会直接进入下一批 task,不等待其他主机,但文本中读取了另一台主机的 task(hostvars、ansible_play_hosts、delegate_to,以及这样做的模板或变量)之前除外。playbook 没有明说的依赖不会被等待,例如另一台主机仍在安装的服务,或直接写出主机名的某台主机上的文件。只对主机之间不存在这类依赖的 play 开启它。见跨主机批处理。

Default
false
Environment
VOLANT_BATCHING

当 task 的参数没有超出原生版本所实现的范围时,让 agent 用模块的原生版本来处理该 task。设为 false 时,每个 task 都交给 ansible-core 的 Python 模块,setup 也是如此,这是在真实运行中比较两条路径的方法。该值按 ansible-core 读取布尔值的方式解析,遇到它不认识的词会让运行以退出码 5 停止。见原生模块。

Default
true
Environment
VOLANT_NATIVE_MODULES

控制节点的 Python 来自哪里。auto 依次使用 VOLANT_PYTHON、已安装的托管运行时、当前激活的虚拟环境和 python3,其中没有一个可用时就安装托管运行时。managed 只使用 VOLANT_PYTHON 或托管运行时,缺少时会安装它。system 从不使用也从不安装托管运行时。其他任何词都会让运行以退出码 5 停止。见托管运行时。

Default
auto
Environment
VOLANT_RUNTIME

让一台 inventory 主机的所有 ssh 运行共享同一个 OpenSSH 连接。设为 false 时,每个链路和探测都会打开自己的连接。见每台主机一个连接。

Default
true
Environment
VOLANT_SSH_CONTROL_MASTER

volant shadow status 在判定一个 playbook 为 ready 之前,要求连续多少次干净的重放。至少为 1 的整数;其他任何值都会以退出码 5 终止运行。参见无风险切换。

Default
5

这些重放必须比较过的 playbook 任务所占比例,取值 0 到 1,达到后 volant shadow status 才判定为 ready。其他任何值都会以退出码 5 终止运行。

Default
0.9

与 volant.lock 不一致的运行以退出码 4 拒绝,效果同 --locked。关闭时,差异只是一条警告,运行继续。Ansible 会连同 [volant] 的其他设置一起忽略它。

Default
false

设置 template、copy、script、unarchive 和 assemble 如何处理受管主机指定的控制节点 src,以及 fetch 能否写入主机指定的 dest:allow、contained 或 refuse。默认值是 allow,行为与 ansible-core 相同,其他任何词都会让运行以退出码 5 停止。每个词的具体含义见受管主机指定的源文件。

Default
allow
Environment
VOLANT_HOST_NAMED_PATHS

以冒号分隔的控制节点绝对目录列表,fetch 可以在这些目录下写入受管主机指定的 dest。相对路径、使用 ~ 或 .. 的条目,或者 /,都会让运行以退出码 5 停止。规则见受管主机指定的 dest。

Default
unset
Environment
VOLANT_HOST_NAMED_DEST_DIRS