ansible.cfg Configuration File: Complete Settings Reference (Guide)
By Luca Berton · Published 2024-01-01 · Category: troubleshooting
Complete guide to ansible.cfg configuration file. Configure defaults, connection settings, privilege escalation, SSH options, plugin paths. Practical configuration examples.
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.
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. [privilege_escalation] This section manages settings for privilege escalation, such as sudo. [ssh_connection] This section contains settings related to SSH connections. [paramiko_connection] This section configures settings specific to Paramiko, an alternative to SSH. [inventory] This section deals with the configuration of the inventory. [logging] This section manages Ansible's logging settings.
Key Settings and Their Usage Inventory File: The inventory setting in the [defaults] section specifies the location of the inventory file. Remote User: The remote_user setting defines the user Ansible will use to connect to remote hosts. Host Key Checking: Disabling host key checking can be useful in development environments. Privilege Escalation: The become settings allow you to specify whether Ansible should use privilege escalation and the method to use. SSH Arguments: Custom SSH arguments can be set to control SSH behavior. Logging: Setting up a log file helps in debugging and auditing Ansible runs.
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.
Configuration Precedence ANSIBLE_CONFIG environment variable ./ansible.cfg (current directory) ~/.ansible.cfg (home directory) /etc/ansible/ansible.cfg (global)
Essential Configuration
Performance Tuning
Inventory Settings
Callback Plugins
Vault Settings
Roles and Collections
Environment Variable Overrides
Project Template
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)
Essential Settings
Performance Tuning
Environment Variable Overrides
View All Settings
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 Guide • Ansible Become Guide • Ansible Inventory Guide • Ansible Environment Variables Guide
Category: troubleshooting