The controller log nobody turned on · Ansible

Ask most teams where their Ansible runs are recorded and the answer is “in CI”. Ask what happens when someone runs a play from their own machine, and the answer is a pause.

There is a setting that would record it. It ships disabled, it has shipped disabled for the entire life of the tool, and it takes one line to turn on. This lesson is about that line and the three things it commits you to.

The default is nothing

Read from the controller rather than from memory:

Read-only / Safethe setting, its default, and every way to set it— Verified on ansible-core 2.21.3. ansible-config list prints the definitions the running version actually uses.

$ ansible-config list | grep -A 9 'DEFAULT_LOG_PATH:'

DEFAULT_LOG_PATH:
default: null
description:
- File to which Ansible will log on the controller.
- When not set the logging is disabled.
env:
- name: ANSIBLE_LOG_PATH
ini:
- key: log_path
  section: defaults

“When not set the logging is disabled.” Not “logs to syslog”, not “logs at a reduced level”. Disabled.

So on a default controller, the complete durable record of a run is whatever the operator’s terminal scrollback happens to contain, until they close the window. If the run was a scheduled job, it is whatever the scheduler captured. If it was ansible-playbook typed by a person at 02:00 during an incident, it is nothing.

That is the gap. Every question in lesson 5 — who changed three hundred servers, when, with what — starts from a record on the controller, and by default there is not one.

Turning it on

In ansible.cfg, under source control with the rest of the project configuration:

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

or for a single run, without changing the repository:

Read-only / Safelogging for one invocation— Sets the log path for this command only. The play itself determines whether anything is changed; the variable only affects recording.

ANSIBLE_LOG_PATH=./run-$(date -u +%Y%m%dT%H%M%SZ).log ansible-playbook -i inventory/ site.yml --check

What lands in the file is the same stream the stdout callback rendered, with a header per line:

Read-only / Safethe record format— Verified on ansible-core 2.21.3. The play targets one host with ansible_connection=local and its only tasks are debug, so nothing was changed on any system.

$ head -9 secret.log

2026-08-11 23:06:41,791 p=367984 u=ebrandi n=ansible INFO| PLAY [Does no_log protect the log file] ****
2026-08-11 23:06:41,795 p=367984 u=ebrandi n=ansible INFO| TASK [Task without no_log] *****************
2026-08-11 23:06:41,804 p=367984 u=ebrandi n=ansible INFO| ok: [web1] => {
  "msg": "token is REPLACE_ME_TOKEN_VALUE"
}
2026-08-11 23:06:41,805 p=367984 u=ebrandi n=ansible INFO| TASK [Task with no_log] ********************
2026-08-11 23:06:41,812 p=367984 u=ebrandi n=ansible INFO| ok: [web1]
2026-08-11 23:06:41,813 p=367984 u=ebrandi n=ansible INFO| PLAY RECAP *********************************
2026-08-11 23:06:41,813 p=367984 u=ebrandi n=ansible INFO| web1  : ok=2  changed=0  unreachable=0  failed=0  skipped=0  rescued=0  ignored=0

Four fields per line, and each is doing audit work:

A timestamp with milliseconds — the join key against managed-node evidence in lesson 5.
p= the controller process id — distinguishes concurrent runs.
u= the operating-system user who ran it — the only place a human name appears anywhere in this chain, and the reason lesson 5 keeps coming back to it.
n= the Python logger name.

Note what is not there: the playbook path, the inventory used, the --limit applied, the repository commit. The log records what the run printed, not what the run was. Reconstructing that is lesson 4’s job.

Three consequences, all of them yours now

It grows without bound

Ansible writes to the file and does nothing else with it. There is no rotation, no size cap, no compression. A verbose nightly run over a four-hundred-host fleet produces tens of megabytes a night into one file, forever, until the controller’s root filesystem fills — at which point the controller stops being able to run anything, including the play that would fix it.

Rotation is a logrotate fragment, and it is not optional:

# /etc/logrotate.d/ansible
/var/log/ansible/ansible.log {
    daily
    rotate 90
    compress
    delaycompress
    missingok
    notifempty
    create 0640 ansible ansible
}

rotate 90 is a retention decision, and it should be made by whoever owns your change-audit requirements rather than defaulted. Ninety days answers “what happened last quarter”; seven does not.

The create line matters for the next consequence.

It is created with your umask

This one surprises people, and it is verifiable in one command.

Read-only / Safethe mode Ansible actually created the log with— Verified on ansible-core 2.21.3. No mode was specified anywhere; the file took the creating user umask.

$ stat -c '%a %U' secret.log

664 ebrandi

Group-writable and world-readable, because that is what the umask produced. On a controller with the common default umask of 022 you get 644 — still world-readable.

On a shared controller, that means every account on the machine can read every line of every run, including the contents of the next section. The create 0640 ansible ansible in the logrotate fragment fixes it for rotated files; the live file needs the directory and the file to be created correctly in the first place:

Configuration changerestrict the log before the first run writes to it— Creates the directory and an empty file with restrictive ownership and mode. Run once, as part of controller provisioning.

install -d -o ansible -g ansible -m 0750 /var/log/ansible
install -o ansible -g ansible -m 0640 /dev/null /var/log/ansible/ansible.log

The controller-security part of this course treats the controller as the most privileged machine in the estate. This file is one of the reasons.

It contains whatever the run printed

Here is the demonstration that matters, and the result is uncomfortable.

A play with two tasks. Both render the same variable. One carries no_log: true:

- name: Does no_log protect the log file
  hosts: web1
  gather_facts: false
  vars:
    api_token: 'REPLACE_ME_TOKEN_VALUE'
  tasks:
    - name: Task without no_log
      ansible.builtin.debug:
        msg: "token is {{ api_token }}"

    - name: Task with no_log
      ansible.builtin.debug:
        msg: "token is {{ api_token }}"
      no_log: true

Run with ANSIBLE_LOG_PATH set, then search the log:

Read-only / Safeone of the two tasks put the token on disk— Verified on ansible-core 2.21.3. The value is an obviously fake placeholder; the count is the number of lines in the log containing it.

$ grep -c REPLACE_ME_TOKEN_VALUE secret.log

no_log worked exactly as documented on the task that carried it: the log line for that task is ok: [web1] with no result body at all. And the task that did not carry it wrote the secret to a file on disk, in a directory that was world-readable, with no indication anywhere that something sensitive had just become durable.

no_log is per task, and the log path is per run

The asymmetry is the whole risk.

no_log is a decision made once, on one task, by whoever wrote it. The log path is a decision made once, for every run of every playbook in the repository, by whoever configured the controller — usually a different person, usually months apart.

Turning on log_path therefore retroactively changes the consequence of every missing no_log in the codebase. A task that has been printing a rendered configuration to a terminal for two years starts writing it to a file that is kept for ninety days.

The order of operations that avoids this:

Audit for secret-bearing tasks before enabling the log, not afterwards. The how secrets actually leak lesson enumerates the routes; --diff on a rendered template is the one people forget, and diff mode and secret exposure covers it.
Create the file with a restrictive mode first, so the first run does not write into a world-readable file.
Then enable it, and treat the log directory with the same access controls as the vault password file.

And remember what no_log and its limits establishes: no_log suppresses the module’s result, not everything. Anything that reaches the output by another route — a --diff of a rendered file, a lookup evaluated in a task name, a secret embedded in a command argument that appears in an error — is not covered by it.

Filtering, and what it cannot do

There is one more setting worth knowing, mostly so that you do not over-estimate it:

Read-only / Safelog filtering operates on logger names— Verified on ansible-core 2.21.3.

$ ansible-config list | grep -A 8 'DEFAULT_LOG_FILTER:'

DEFAULT_LOG_FILTER:
default: []
description: List of logger names to filter out of the log file.
env:
- name: ANSIBLE_LOG_FILTER
ini:
- key: log_filter
  section: defaults
name: Name filters for python logger

“Logger names” — the n= field. It suppresses noise from a named Python logger. It is not a content filter, and there is no supported way to say “log everything except things that look like credentials”. Redaction has to happen at the task, with no_log, before the value ever becomes an event.

Under the hood

The log is written by Python’s standard logging module, configured once at startup, and the callback that renders stdout also emits to that logger. This explains several behaviours that otherwise look arbitrary.

The log follows the stdout callback. Change result_format to yaml and the log lines change shape too, because they are the same rendering. If you want a stable, parseable record, the log path is the wrong tool — lesson 4 is about a callback that emits a structure rather than a rendering.

Redaction happens upstream of the logger. no_log causes the engine to replace the result before any consumer sees it, which is why the log line for the no_log task above is ok: [web1] with nothing after it rather than a line with the value blanked out. The censorship is not a filter on the way to the file; the file never had the value.

Everything shares one file. Concurrent runs from the same controller interleave, distinguished only by p=. Two operators running against overlapping host sets produce a single log in which the events alternate, and reconstructing which run did what means grouping by process id first. This is one of several reasons the shared versus personal controllers lesson treats controller multiplicity as a design decision rather than an accident.

The file handle is opened at startup. A run that is still going when logrotate renames the file keeps writing to the renamed inode, which is why the fragment above uses delaycompress and why copytruncate is the wrong choice here: truncating a file an active run holds open loses the run.

What happens if the controller log is the only record you keep?

You have solved about half the audit problem, and it is worth being precise about which half.

What the log answers well. What was printed, by which OS user, at what millisecond, from which process. For “was there an Ansible run against this host at 14:32 on Tuesday”, it is exactly right, and the timestamps join cleanly to journald on the managed node.

What it cannot answer. Which playbook. Which inventory. Which --limit. Which repository commit. Which vault ids. Whether the run was --check. None of that appears in the log unless a task happened to print it, because the log records output rather than invocation.

What it answers misleadingly. The u= field is the operating-system user on the controller. On a shared controller with a service account — which is the normal arrangement for scheduled runs — every entry says u=ansible, and the human is not recorded anywhere in the file. That is the attribution problem lesson 5 is entirely about.

The practical conclusion: enable it, because a partial record beats none and it costs one line. Then treat it as the timeline, and get the identity of each run from the artefact in lesson 4 and from CI or controller job records. Neither one alone answers the question a change board asks.

Enabling controller logging safely

In this order. Reversing steps 1 and 4 is how secrets end up on disk.

Audit for tasks that print secret material, and add no_log where it is missing. Include --diff on templates that render credentials.
Create the directory and file with restrictive ownership and mode before the first run writes to them.
Install a logrotate fragment with an explicit retention that somebody chose, and a create mode that matches step 2.
Set log_path in ansible.cfg, in the repository, so it applies to everyone rather than to whoever exported the variable.
Check the log directory in your controller backup and restore plan. A record that does not survive the controller is not an audit trail.
Decide what happens on a personal controller. Either people run from the shared one, or their runs are unrecorded, and both are positions — only one of them should be accidental.

Knowledge check

Why this matters

One unset configuration key is the difference between an estate that can answer “what happened on Tuesday” and one that cannot, and it has been unset by default on every controller anyone has ever installed.

That is worth sitting with, because it is not an oversight. There is a genuine reason the default is off: turning it on writes everything a run printed to a file that persists, and Ansible cannot know whether your tasks print secrets, whether your controller is shared, or how long you are allowed to keep the result. Those are your decisions, and the tool declines to make them for you.

Which means enabling it is not a checkbox. It is three commitments taken together: a rotation policy with a retention someone chose, a mode and ownership that match how sensitive the contents actually are, and an audit of every task that prints something it should not. Do the third one first.

And when it is on, be clear about what you have bought. A timeline of what ran and when, attributed to an operating-system account. Not what the run was, not who the human was, and not what changed on the hosts. The next two lessons are about each of those in turn.