Ansible Configuration File

Ansible looks for a file named <span>ansible.cfg</span> as its configuration file.

[root@ansible ansible]# ansible --version
ansible [core 2.16.3]
  config file = /root/ansible/ansible.cfg
  configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/local/lib/python3.12/site-packages/ansible_core-2.16.3-py3.12.egg/ansible
  ansible collection location = /root/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/local/bin/ansible
  python version = 3.12.8 (main, Dec 12 2024, 16:30:29) [GCC 8.5.0 20210514 (Red Hat 8.5.0-22)] (/usr/bin/python3)
  jinja version = 3.1.6
  libyaml = True

File Locations and Priority

The Ansible configuration file can appear in four locations:

• • The environment variable <span>ANSIBLE_CONFIG</span>
• • The <span>ansible.cfg</span> file in the current working directory
• • The hidden file <span>.ansible.cfg</span> in the current user’s home directory
• • The global default configuration file <span>/etc/ansible/ansible.cfg</span>

The priority from highest to lowest is: environment variable → current working directory → home directory → <span>/etc</span>

Therefore, when executing Ansible commands, it first looks for the configuration file in the environment variable, if not found, it checks the current working directory, then the user’s home directory, and finally <span>/etc/ansible/ansible.cfg</span>.

The recommended management method for <span>ansible.cfg</span> is as follows:

The priority from highest to lowest is:

1. 1. The <span>./ansible.cfg</span> in the current directory
2. 2. The path specified by the environment variable <span>ANSIBLE_CONFIG</span>
3. 3. The <span>~/.ansible.cfg</span> in the user directory
4. 4. The system path <span>/etc/ansible/ansible.cfg</span>

Generating a Default Configuration File

[root@ansible ansible]# ansible-config init --disabled > ansible.cfg

File Content

[root@ansible ansible]# grep -E '^
' ansible.cfg
[defaults]
[privilege_escalation]
[persistent_connection]
[connection]
[colors]
[selinux]
[diff]
[galaxy]
[inventory]
[netconf_connection]
[paramiko_connection]
[jinja2]
[tags]

Explanation of Ansible Configuration Sections

Configuration Section	Purpose	Description
[defaults]	Default Settings	Mainly configures the basic behavior of Ansible, such as <span>inventory</span>, <span>remote_user</span>, <span>timeout</span>, <span>roles_path</span>, etc.
[privilege_escalation]	Privilege Control	Controls privilege escalation actions such as <span>become</span>, <span>become_user</span>, <span>become_method</span>, etc. (e.g., sudo)
[persistent_connection]	Persistent Connection Parameters	Controls the persistence of connection plugins like SSH (can reduce connection overhead)
[connection]	General Connection Configuration	Includes timeout, retries, and caching controls for remote connections
[colors]	Console Color Output	Defines the colors for different types of information in the output
[selinux]	SELinux Settings	Whether to automatically manage <span>semanage</span>, label restoration, etc. (useful for hosts with SELinux enabled)
[diff]	Display Difference Settings	Controls whether to enable diff mode, which can show differences when modifying configurations
[galaxy]	Ansible Galaxy Settings	Sets Galaxy sources, caching policies, role downloads, etc.
[inventory]	Dynamic Inventory Parameters	Default settings for Inventory plugins, such as caching, paths, etc.
[netconf_connection]	Netconf Connection Parameters	Connection settings for network devices that support NETCONF (e.g., Cisco, Juniper)
[paramiko_connection]	Settings when using paramiko	Controls behavior when using paramiko (Python SSH library) instead of OpenSSH
[jinja2]	Template Rendering Settings	Controls template variables, undefined variable behavior, Jinja environment, etc.
[tags]	Tag Behavior	Controls the matching method for tags when running playbooks

Common Configuration Options

<span>[defaults]</span> Common Configurations:

Configuration Item	Description	Example
<span>inventory</span>	Specifies the path to the host inventory	<span>inventory = ./hosts</span>
<span>remote_user</span>	Default remote login user	<span>remote_user = ansible</span>
<span>ask_pass</span>	Whether to prompt for SSH password during execution	<span>ask_pass = false</span>
<span>ask_become_pass</span>	Whether to prompt for sudo password	<span>ask_become_pass = true</span>
<span>private_key_file</span>	Specifies the path to the private key	<span>private_key_file = ~/.ssh/id_rsa</span>
<span>host_key_checking</span>	Whether to enable SSH host key checking	<span>host_key_checking = false</span>
<span>timeout</span>	Connection timeout (seconds)	<span>timeout = 30</span>
<span>forks</span>	Number of concurrent hosts to execute	<span>forks = 10</span>
<span>retry_files_enabled</span>	Whether to generate <span>.retry</span> files	<span>retry_files_enabled = false</span>
<span>log_path</span>	Path to the log file	<span>log_path = /var/log/ansible.log</span>
<span>roles_path</span>	Specifies the roles directory	<span>roles_path = ./roles</span>
<span>gathering</span>	Controls the method of collecting facts (implicit, explicit, smart)	<span>gathering = smart</span>
<span>fact_caching</span>	Whether to enable facts caching	<span>fact_caching = jsonfile</span>
<span>fact_caching_connection</span>	Path for facts caching	<span>fact_caching_connection = ./fact_cache</span>

<span>[privilege_escalation]</span> Privilege Configuration:

Configuration Item	Description	Example
<span>become</span>	Whether to enable privilege escalation	<span>become = true</span>
<span>become_method</span>	Method of privilege escalation (sudo/su/pbrun/doas, etc.)	<span>become_method = sudo</span>
<span>become_user</span>	The target user after privilege escalation	<span>become_user = root</span>
<span>become_ask_pass</span>	Whether to prompt for privilege password	<span>become_ask_pass = false</span>

<span>[ssh_connection]</span> (or <span>[connection]</span>) Connection Optimization Configuration:

Configuration Item	Description	Example
<span>pipelining</span>	Enable SSH pipelining to speed up execution	<span>pipelining = true</span>
<span>control_path</span>	Socket path for SSH control connection	<span>control_path = %(directory)s/%%h-%%r</span>
<span>ssh_args</span>	Parameters passed to SSH	<span>ssh_args = -o ControlMaster=auto -o ControlPersist=60s</span>
<span>retries</span>	Number of retries for SSH failures	<span>retries = 3</span>

<span>[jinja2]</span> Template Rendering Related:

Configuration Item	Description	Example
<span>undefined</span>	Controls the handling of undefined variables (e.g., <span>strict</span>)	<span>undefined = strict</span>
<span>trim_blocks</span>	Removes empty lines in Jinja2 templates	<span>trim_blocks = true</span>
<span>lstrip_blocks</span>	Removes leading spaces in Jinja2	<span>lstrip_blocks = true</span>

<span>[diff]</span> Difference Display:

Configuration Item	Description	Example
<span>always</span>	Whether to always display change diffs	<span>always = true</span>
<span>context</span>	Number of context lines to display	<span>context = 5</span>

<span>[galaxy]</span> Ansible Galaxy Settings:

Configuration Item	Description	Example
<span>server_list</span>	Specifies the Galaxy server	<span>server_list = ansible_galaxy</span>
<span>ignore_certs</span>	Whether to ignore Galaxy HTTPS certificate verification	<span>ignore_certs = false</span>

<span>[inventory]</span> Host Inventory Settings (Dynamic Inventory):

Configuration Item	Description	Example
<span>enable_plugins</span>	Enabled inventory plugins	<span>enable_plugins = host_list, yaml, ini</span>
<span>cache</span>	Enables host caching	<span>cache = true</span>
<span>cache_plugin</span>	Cache plugin used	<span>cache_plugin = jsonfile</span>
<span>cache_timeout</span>	Cache validity period	<span>cache_timeout = 600</span>

Other Configuration Sections (Optional):

Section Name	Purpose
<span>[paramiko_connection]</span>	Configures connection behavior if using paramiko as the SSH connection backend
<span>[netconf_connection]</span>	Manages connection parameters for NETCONF network devices
<span>[colors]</span>	Controls terminal output color styles
<span>[selinux]</span>	Configures how to handle SELinux label restoration
<span>[tags]</span>	Controls tag matching behavior, such as default values for <span>skip_tags</span>, etc.

Configuration Example

[defaults]  
inventory      = ./inventory    # Path to the host inventory
fork           = 20                # Number of concurrent hosts to execute
ask_pass       = False            # Whether to prompt for password when executing Ansible
remote_user    =  root            # Indicates using root user to access controlled nodes
log_path       = /var/log/ansible.log    # Specifies the log file location for Ansible
host_key_checking = False                # Whether to perform SSH host key checking
ansible_python_interpreter = /usr/bin/python3.9        # Specifies the Python interpreter on the controlled end
[privilege_escalation]
become = True    # Whether to escalate privileges
become_method = sudo    # Method of privilege escalation
become_user = root        # User to escalate to
become_ask_pass = False    # Whether to prompt for privilege password during Ansible execution

Remove comments when using.