The ansible.cfg file is Ansible’s primary configuration file that defines global settings for how Ansible behaves during playbook execution. It allows you to customize various Ansible options, such as inventory location, logging settings, connection settings, and much more. By modifying the ansible.cfg file, you can tailor Ansible’s behavior to meet specific needs of your automation environment.
The file is usually located in one of several places, and Ansible reads from multiple locations in a specific order of precedence to determine which settings to apply.
Where to Find ansible.cfg?
The ansible.cfg file can be located in several places in the system, with Ansible looking for it in the following order of precedence:
- ANSIBLE_CONFIG environment variable: If set, this file will take precedence.
- ansible.cfg: The default configuration file found in the current working directory.
- ~/.ansible.cfg: The user-specific configuration file located in the home directory.
- /etc/ansible/ansible.cfg: The global system-wide configuration file.
Ansible will use the configuration file it finds first in this hierarchy.
Structure of ansible.cfg
The ansible.cfg file is divided into sections that configure different aspects of Ansible’s operation. Each section contains key-value pairs that define specific options. Below is an example of a basic ansible.cfg file structure:
[defaults]
inventory = /etc/ansible/hosts
remote_user = ansible
forks = 5
private_key_file = /home/user/.ssh/id_rsa
host_key_checking = False
log_path = /var/log/ansible.log
[ssh_connection]
ssh_args = -o ControlMaster=auto -o ControlPersist=60s
[privilege_escalation]
become = True
become_method = sudo
become_user = root
Key Sections in ansible.cfg
[defaults]: This is the most important section and contains general configuration options, such as:
inventory: Defines the location of your inventory file.remote_user: Specifies the default user for SSH connections.forks: Sets the number of parallel tasks Ansible should run.private_key_file: Specifies the private SSH key to use for authentication.host_key_checking: Controls whether Ansible checks SSH host keys. Disabling it can speed up execution but may reduce security.log_path: Specifies the path where Ansible logs its output.
[ssh_connection]: Configures the settings for SSH connections between Ansible and the managed hosts. This includes the use of SSH arguments (
ssh_args), which can be customized to optimize connection behavior.[privilege_escalation]: This section deals with privilege escalation options such as
become,become_method, andbecome_user. These settings control how Ansible escalates privileges to run tasks as a different user (e.g.,root) using tools likesudoorsu.[inventory]: This section is where you can specify options related to inventory management, such as the path to your inventory files or the order of precedence for inventory sources.
[paramiko_connection]: Configures settings related to the use of Paramiko as the SSH connection plugin, which can be useful for troubleshooting connection issues or when SSH keys are not available.
Common Use Cases for ansible.cfg
1. Customizing Inventory Location
By default, Ansible looks for an inventory file named hosts in the /etc/ansible/ directory. However, if you store your inventory file elsewhere or have multiple inventory files for different environments, you can specify the path in the ansible.cfg file:
[defaults]
inventory = /path/to/your/inventory
2. Configuring Connection Settings
If you’re working in a network with specific SSH connection requirements, you can customize how Ansible connects to remote hosts. For example, you can specify the use of an SSH agent or set up specific SSH arguments to handle connections:
[ssh_connection]
ssh_args = -o ControlMaster=auto -o ControlPersist=60s
This configuration enables SSH connection multiplexing, which can speed up connections when running multiple tasks.
3. Enabling Privilege Escalation
For tasks that require elevated privileges (e.g., installing packages), you can configure Ansible to use sudo or another escalation method by default:
[privilege_escalation]
become = True
become_method = sudo
become_user = root
This ensures that Ansible will run tasks with the required permissions without needing to specify the become directive in each task.
4. Logging and Debugging
Ansible doesn’t log output by default. However, you can configure logging by specifying a path to a log file in the ansible.cfg file:
[defaults]
log_path = /var/log/ansible.log
This is helpful for auditing and debugging automation runs, as the log will capture detailed execution data.
