ansible.cfg Configuration File: Complete Settings Reference (Guide)

The ansible.cfg file is a crucial component in the Ansible ecosystem, providing a centralized configuration point to customize the behavior of Ansible. This article explores the structure, key sections, and settings of the ansible.cfg file, and provides best practices for its usage.

What is ansible.cfg?

The ansible.cfg file is an INI-like configuration file used to define various settings and parameters that influence how Ansible operates. This file can be placed in different locations, with Ansible searching for it in the following order of precedence: ANSIBLE_CONFIG environment variable (if set) ansible.cfg file in the current working directory .ansible.cfg file in the user’s home directory /etc/ansible/ansible.cfg file (global configuration)

Each of these configuration files can override the settings specified in the others, with the highest precedence being given to the environment variable.

See also: Ansible-Core: The Foundation of Modern IT Automation

Structure of ansible.cfg

The ansible.cfg file is divided into sections, each containing various parameters that can be customized. Here are some of the key sections and their important settings: [defaults] This section contains the default settings for Ansible, including the inventory file location, remote user, and module path.

   [defaults]
   inventory = /path/to/inventory
   remote_user = your_user
   host_key_checking = False
   

[privilege_escalation] This section manages settings for privilege escalation, such as sudo.

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

[ssh_connection] This section contains settings related to SSH connections.

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

[paramiko_connection] This section configures settings specific to Paramiko, an alternative to SSH.

   [paramiko_connection]
   pipelining = True
   

[inventory] This section deals with the configuration of the inventory.

   [inventory]
   enable_plugins = host_list, script, yaml, ini, auto
   

[logging] This section manages Ansible's logging settings.

   [logging]
   log_path = /var/log/ansible.log
   

Key Settings and Their Usage

Inventory File: The inventory setting in the [defaults] section specifies the location of the inventory file.

   inventory = /path/to/inventory
   

Remote User: The remote_user setting defines the user Ansible will use to connect to remote hosts.

   remote_user = ansible
   

Host Key Checking: Disabling host key checking can be useful in development environments.

   host_key_checking = False
   

Privilege Escalation: The become settings allow you to specify whether Ansible should use privilege escalation and the method to use.

   become = True
   become_method = sudo
   

SSH Arguments: Custom SSH arguments can be set to control SSH behavior.

   ssh_args = -o ControlMaster=auto -o ControlPersist=60s
   

Logging: Setting up a log file helps in debugging and auditing Ansible runs.

   log_path = /var/log/ansible.log
   

See also: Ansible Troubleshooting: Fix Jinja2 Syntax & Inventory Errors

Best Practices for Using ansible.cfg

Environment-Specific Configuration: Maintain different ansible.cfg files for different environments (development, testing, production) and use the ANSIBLE_CONFIG environment variable to switch between them. Version Control: Include your ansible.cfg file in version control to track changes and ensure consistency across different team members. Secure Privilege Escalation: Avoid hardcoding sensitive information in the ansible.cfg file. Use Ansible Vault or environment variables for sensitive data. Optimize SSH Connections: Use SSH pipelining and control persistence to improve performance and reduce connection overhead. Centralized Logging: Configure centralized logging to collect logs from all Ansible runs, which aids in troubleshooting and compliance. Modular Configuration: Split complex configurations into multiple files if needed, and include them as required to maintain clarity and manageability.

Conclusion

The ansible.cfg file is a powerful tool that allows you to tailor Ansible's behavior to fit your specific needs. By understanding and leveraging the various sections and settings available, you can optimize your Ansible automation workflows, improve security, and ensure consistency across your IT environments. Following best practices in configuring and managing ansible.cfg will lead to more efficient and maintainable automation processes. For detailed information on each configuration option, refer to the official Ansible documentation.

See also: Ansible Automation: Complete Guide to IT Automation with Playbook Examples

Configuration Precedence

ANSIBLE_CONFIG environment variable ./ansible.cfg (current directory) ~/.ansible.cfg (home directory) /etc/ansible/ansible.cfg (global)

# Check which config is active
ansible --version | grep "config file"

Essential Configuration

[defaults]
inventory = inventory.yml
remote_user = deploy
host_key_checking = false
timeout = 30
forks = 20
log_path = ./ansible.log
retry_files_enabled = false
stdout_callback = yaml
nocows = true
[privilege_escalation]
become = false
become_method = sudo
become_user = root
become_ask_pass = false
[ssh_connection]
pipelining = true
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o ControlPath=/tmp/ansible-ssh-%h-%p-%r
[galaxy]
server_list = galaxy, automation_hub

Performance Tuning

[defaults]
# Parallel hosts (default: 5)
forks = 50
# Gather only needed facts
gathering = smart
fact_caching = jsonfile
fact_caching_connection = /tmp/ansible-facts
fact_caching_timeout = 86400
# Disable retry files
retry_files_enabled = false
[ssh_connection]
# SSH multiplexing + pipelining
pipelining = true
ssh_args = -o ControlMaster=auto -o ControlPersist=300s

Inventory Settings

[defaults]
inventory = inventory/production,inventory/staging
# Or directory
inventory = inventory/
# Enable inventory plugins
enable_plugins = yaml, ini, auto, aws_ec2

Callback Plugins

[defaults]
# Output format
stdout_callback = yaml     # Readable YAML output
# stdout_callback = debug  # Full debug output
# stdout_callback = dense  # Minimal output
# Enable additional callbacks
callbacks_enabled = timer, profile_tasks, profile_roles

Vault Settings

[defaults]
vault_password_file = ~/.vault_pass
# Or prompt
# ask_vault_pass = true
vault_identity_list = dev@~/.vault_dev, prod@~/.vault_prod

Roles and Collections

[defaults]
roles_path = ./roles:~/.ansible/roles:/etc/ansible/roles
collections_paths = ./collections:~/.ansible/collections
[galaxy]
server_list = galaxy, automation_hub
[galaxy_server.galaxy]
url = https://galaxy.ansible.com/
[galaxy_server.automation_hub]
url = https://console.redhat.com/api/automation-hub/
auth_url = https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token = your-token-here

Environment Variable Overrides

# Override any setting with ANSIBLE_ prefix
export ANSIBLE_CONFIG=/path/to/ansible.cfg
export ANSIBLE_INVENTORY=inventory.yml
export ANSIBLE_REMOTE_USER=deploy
export ANSIBLE_FORKS=50
export ANSIBLE_HOST_KEY_CHECKING=false
export ANSIBLE_STDOUT_CALLBACK=yaml
export ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass

Project Template

# ansible.cfg — Production-ready template
[defaults]
inventory = inventory.yml
remote_user = deploy
forks = 30
timeout = 30
gathering = smart
fact_caching = jsonfile
fact_caching_connection = .facts_cache
fact_caching_timeout = 3600
host_key_checking = false
retry_files_enabled = false
stdout_callback = yaml
callbacks_enabled = timer, profile_tasks
interpreter_python = auto_silent
nocows = true
[privilege_escalation]
become = true
become_method = sudo
[ssh_connection]
pipelining = true
ssh_args = -o ControlMaster=auto -o ControlPersist=60s
[diff]
always = true
context = 3

FAQ

Why doesn't my ansible.cfg take effect?

Check precedence — a config file in a parent directory or ANSIBLE_CONFIG env var may override it. Run ansible --version to see which file is active.

Is ansible.cfg required?

No — Ansible works without it using built-in defaults. But a project-level config ensures consistent behavior across team members.

Security warning about world-writable config?

Ansible won't load ansible.cfg from a world-writable directory. Fix: chmod 755 . or move config to ~/.ansible.cfg.

Configuration File Locations

Ansible loads configuration in this order (first found wins): ANSIBLE_CONFIG environment variable ./ansible.cfg (current directory) ~/.ansible.cfg (home directory) /etc/ansible/ansible.cfg (system-wide)

# Check which config is active
ansible --version | grep "config file"

Essential Settings

[defaults]
# Inventory
inventory = inventory/
host_key_checking = False
remote_user = deploy
# Performance
forks = 20
gathering = smart
fact_caching = jsonfile
fact_caching_connection = /tmp/ansible_facts
fact_caching_timeout = 86400
# Output
stdout_callback = yaml
callbacks_enabled = timer, profile_tasks
# Roles and collections
roles_path = roles/
collections_path = collections/
# Vault
vault_password_file = ~/.vault_pass
[ssh_connection]
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o StrictHostKeyChecking=accept-new
pipelining = True
control_path_dir = /tmp/.ansible-cp
[privilege_escalation]
become = True
become_method = sudo
become_user = root
become_ask_pass = False

Performance Tuning

[defaults]
# More parallel connections
forks = 50
# Smart fact gathering (cache + minimal)
gathering = smart
gather_subset = !hardware,!ohai,!facter
# Faster SSH
[ssh_connection]
pipelining = True
ssh_args = -o ControlMaster=auto -o ControlPersist=120s

Environment Variable Overrides

# Any setting can be overridden
export ANSIBLE_FORKS=50
export ANSIBLE_REMOTE_USER=deploy
export ANSIBLE_STDOUT_CALLBACK=yaml
export ANSIBLE_HOST_KEY_CHECKING=False
export ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass

View All Settings

# Dump current configuration
ansible-config dump
# Show only changed settings
ansible-config dump --only-changed
# List all available settings
ansible-config list

FAQ

Why isn't my ansible.cfg being loaded?

Check: file permissions (world-writable directories are rejected), ANSIBLE_CONFIG env var might override, wrong directory.

Can I use YAML format?

No — ansible.cfg uses INI format only. But you can use environment variables or command-line options as alternatives.

What's the most impactful performance setting?

pipelining = True in [ssh_connection] — reduces SSH operations per task from 5+ to 2. Requires requiretty disabled in sudoers.

Related Articles

• Ansible Vault CLI reference • Ansible privilege escalation patterns • Ansible Inventory Guide • play-scoped env vars in Ansible