跳到主要内容

ansible.cfg 配置速查

本篇按 section 整理 ansible.cfg 的常用配置项，每项给出键和示例值，随查随用。

配置文件优先级​

Ansible 按以下顺序查找配置文件，取第一个命中的，其余全部忽略：ANSIBLE_CONFIG 环境变量 → 当前目录 ansible.cfg → 家目录 ~/.ansible.cfg → /etc/ansible/ansible.cfg。

当前目录配置的例外

当前目录如果全局可写（world-writable），其中的 ansible.cfg 会被拒绝加载，防止他人在目录里植入恶意配置。项目目录务必收紧权限，或用 ANSIBLE_CONFIG 显式指定。

[defaults]​

键 = 示例值说明
inventory = ./inventory.ini默认 inventory 路径，可指向文件、目录或逗号分隔的多个来源
forks = 20并发连接的主机数，默认 5；管理主机多时调大能明显缩短执行时间
host_key_checking = False首次连接是否校验 SSH 主机密钥；内网批量初始化常关闭，安全要求高时保持开启
roles_path = ./rolesrole 的搜索路径，多个路径用冒号分隔
log_path = ./logs/ansible.log执行日志落盘路径，默认不记录日志
retry_files_enabled = False是否生成记录失败主机的 .retry 文件；默认关闭，ansible-core 2.19 起该功能已废弃
stdout_callback = ansible.builtin.yaml标准输出回调插件；yaml 回调的输出更可读，默认为 default
gathering = smartfacts 采集策略：implicit（默认，每次都采集）/ explicit（仅显式调 setup）/ smart（有缓存则复用）
timeout = 30SSH 连接超时秒数，默认 10；网络质量差时适当调大

[privilege_escalation]​

键 = 示例值说明
become = True是否对所有任务默认提权，默认 False；命令行 -b 等价
become_method = sudo提权方式，默认 sudo；可选 su、doas、pbrun 等
become_user = root提权后的目标用户，默认 root
become_ask_pass = False是否交互询问提权密码；设为 True 等价于命令行 -K

[ssh_connection]​

键 = 示例值说明
pipelining = True模块经 SSH 管道直接执行，省去写远端临时文件，显著提速；要求被控端 sudoers 关闭 requiretty
ssh_args = -C -o ControlMaster=auto -o ControlPersist=60s透传给 ssh 的参数；默认值已包含 ControlPersist 连接复用，显式设置会整体覆盖默认值，别只写新增的那条
scp_if_ssh = smart传输文件用 scp 还是 sftp；smart（默认）先试 sftp，失败回退 scp
连接复用是提速关键

ControlPersist=60s 让同一主机的 SSH 连接在 60 秒内复用，避免每个任务重新握手。配合 pipelining = True，大批量任务耗时常能减少一半以上。

最小生产可用配置​

[defaults]
inventory      = ./inventory.ini
forks          = 20
roles_path     = ./roles
log_path       = ./logs/ansible.log
gathering      = smart
timeout        = 30

[privilege_escalation]
become          = True
become_method   = sudo
become_user     = root
become_ask_pass = False

[ssh_connection]
pipelining = True
ssh_args   = -C -o ControlMaster=auto -o ControlPersist=60s

用 ansible-config dump --only-changed 可以随时核对当前生效的非默认配置及其来源。