Exploring the configuration file

Ansible's behavior is, in part, defined by its configuration file. The central configuration file (which impacts the behavior of Ansible for all users on the system) can be found at /etc/ansible/ansible.cfg. However, this is not the only place Ansible will look for its configuration; in fact, it will look in the following locations, from the top to the bottom.

The first instance of the file is the configuration it will use; all of the others are ignored, even if they are present:

1. ANSIBLE_CONFIG: The file location specified by the value of this environment variable, if set
2. ansible.cfg: In the current working directory
3. ~/.ansible.cfg: In the home directory of the user
4. /etc/ansible/ansible.cfg: The central configuration that we previously mentioned

If you installed Ansible through a package manager, such as yum or apt, you will almost always find a default configuration file called ansible.cfg in /etc/ansible. However, if you built Ansible from the source or installed it via pip, the central configuration file will not exist and you will need to create it yourself. A good starting point is to reference the example Ansible configuration file that is included with the source code, a copy of which can be found on GitHub at https://raw.githubusercontent.com/ansible/ansible/devel/examples/ansible.cfg.

In this section, we will detail how to locate Ansible's running configuration and how to manipulate it. Most people who install Ansible through a package find that they can get a long way with Ansible before they have to modify the default configuration, as it has been carefully designed to work in a great many scenarios. However, it is important to know a little about configuring Ansible in case you come across an issue in your environment that can only be changed by modifying the configuration.

Obviously, if you don't have Ansible installed, there's little point in exploring its configuration, so let's just check whether you have Ansible installed and working by issuing a command such as the following (the output shown is from the latest version of Ansible at the time of writing, installed on macOS with Homebrew):

$ ansible 2.9.6
  config file = None
  configured module search path = ['/Users/james/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/local/Cellar/ansible/2.9.6_1/libexec/lib/python3.8/site-packages/ansible
  executable location = /usr/local/bin/ansible
  python version = 3.8.2 (default, Mar 11 2020, 00:28:52) [Clang 11.0.0 (clang-1100.0.33.17)]

Let's get started by exploring the default configuration that is provided with Ansible:

1. The command in the following code block lists the current configuration parameters supported by Ansible. It is incredibly useful because it tells you both the environment variable that can be used to change the setting (see the env field) as well as the configuration file parameter and section that can be used (see the ini field). Other valuable information, including the default configuration values and a description of the configuration, is given (see the default and description fields, respectively). All of the information is sourced from lib/constants.py. Run the following command to explore the output: 

$ ansible-config list

The following is an example of the kind of output you will see. There are, of course, many pages to it, but a snippet is shown here as an example: 

$ ansible-config list
ACTION_WARNINGS:
 default: true
 description:
 - By default Ansible will issue a warning when received from a task action (module
 or action plugin)
 - These warnings can be silenced by adjusting this setting to False.
 env:
 - name: ANSIBLE_ACTION_WARNINGS
 ini:
 - key: action_warnings
 section: defaults
 name: Toggle action warnings
 type: boolean
 version_added: '2.5'
AGNOSTIC_BECOME_PROMPT:
 default: true
 description: Display an agnostic become prompt instead of displaying a prompt containing
 the command line supplied become method
 env:
 - name: ANSIBLE_AGNOSTIC_BECOME_PROMPT
 ini:
 - key: agnostic_become_prompt
 section: privilege_escalation
 name: Display an agnostic become prompt
 type: boolean
 version_added: '2.5'
 yaml:
 key: privilege_escalation.agnostic_become_prompt
.....

2. If you want to see a straightforward display of all the possible configuration parameters, along with their current values (regardless of whether they are configured from environment variables or a configuration file in one of the previously listed locations), you can run the following command:

$ ansible-config dump

The output shows all the configuration parameters (in an environment variable format), along with the current settings. If the parameter is configured with its default value, you are told so (see the (default) element after each parameter name):

$ ansible-config dump
ACTION_WARNINGS(default) = True
AGNOSTIC_BECOME_PROMPT(default) = True
ALLOW_WORLD_READABLE_TMPFILES(default) = False
ANSIBLE_CONNECTION_PATH(default) = None
ANSIBLE_COW_PATH(default) = None
ANSIBLE_COW_SELECTION(default) = default
ANSIBLE_COW_WHITELIST(default) = ['bud-frogs', 'bunny', 'cheese', 'daemon', 'default', 'dragon', 'elephant-in-snake', 'elephant', 'eyes', 'hellokitty', 'kitty', 'luke-koala', 'meow', 'milk', 'moofasa', 'moose', 'ren', 'sheep', 'small', 'stegosaurus', 'stimpy', 'supermilker', 'three-eyes', 'turkey', 'turtle', 'tux', 'udder', 'vader-koala', 'vader', 'www']
ANSIBLE_FORCE_COLOR(default) = False
ANSIBLE_NOCOLOR(default) = False
ANSIBLE_NOCOWS(default) = False
ANSIBLE_PIPELINING(default) = False
ANSIBLE_SSH_ARGS(default) = -C -o ControlMaster=auto -o ControlPersist=60s
ANSIBLE_SSH_CONTROL_PATH(default) = None
ANSIBLE_SSH_CONTROL_PATH_DIR(default) = ~/.ansible/cp
....

3. Let's see the effect on this output by editing one of the configuration parameters. Let's do this by setting an environment variable, as follows (this command has been tested in the bash shell, but may differ for other shells):

$ export ANSIBLE_FORCE_COLOR=True

Now, let's re-run the ansible-config command, but this time get it to tell us only the parameters that have been changed from their default values:

$ ansible-config dump --only-change
ANSIBLE_FORCE_COLOR(env: ANSIBLE_FORCE_COLOR) = True

Here, you can see that ansible-config tells us that we have only changed ANSIBLE_FORCE_COLOR from the default value, that it is set to True, and that we set it through an env variable. This is incredibly valuable, especially if you have to debug configuration issues.

When working with the Ansible configuration file itself, you will note that it is in INI format, meaning it has sections such as [defaults], parameters in the format key = value, and comments beginning with either # or ;. You only need to place the parameters you wish to change from their defaults in your configuration file, so if you wanted to create a simple configuration to change the location of your default inventory file, it might look as follows:

# Set my configuration variables
[defaults]
inventory = /Users/danieloh/ansible/hosts ; Here is the path of the inventory file

As discussed earlier, one of the possible valid locations for the ansible.cfg configuration file is in your current working directory. It is likely that this is within your home directory, so on a multi-user system, we strongly recommend you restrict access to the Ansible configuration file to your user account alone. You should take all the usual precautions when it comes to securing important configuration files on a multi-user system, especially as Ansible is normally used to configure multiple remote systems and so, a lot of damage could be done if a configuration file is inadvertently compromised!

Of course, Ansible's behavior is not just controlled by the configuration files and switches—the command-line arguments that you pass to the various Ansible executables are also of vital importance. In fact, we have already worked with one already—in the preceding example, we showed you how to change where Ansible looks for its inventory file using the inventory parameter in ansible.cfg. However, in many of the examples that we previously covered in this book, we overrode this with the -i switch when running Ansible. So, let's proceed to the next section to look at the use of command-line arguments when running Ansible.