Runbook: Troubleshoot a sudo failure

A become failure means the connection worked. SSH authenticated, the remote interpreter is fine, and the problem is entirely in what happens after login. That narrows the search considerably, and Ansible tells you which narrowing applies if you read the exact string it raised.

There are four common failures and four distinct messages. Match the message first; every step after that follows from which one you have.

When to use this runbook

• A task fails at privilege escalation rather than at the module.
• become: true works by hand and fails from Ansible.
• Escalation stopped working on hosts where it used to work.
• A newly onboarded host connects but cannot escalate.

Blast radius

None while diagnosing. Editing sudoers is the one change here that can make things worse, and it can make them much worse - see the rollback section before you touch a sudoers file.

Step 1: Match the message

These are the strings ansible-core raises, verified against the 2.21.3 source in the connection and become plugins:

The first two come from Ansible matching sudo’s own output: Sorry, try again. produces Incorrect sudo password, and sudo: a password is required produces Missing sudo password.

That distinction is worth holding on to. Missing means no password was available; Incorrect means one was and it was wrong. They send you to different places, and the difference is invisible in the recap.

Step 2: Establish the scope

ansible all -b -m command -a 'id -u' -o | tee become-scope.txt
grep -c 'rc=0' become-scope.txt
grep -ciE 'missing sudo|incorrect sudo|not allowed' become-scope.txt

Step 3: Resolve the effective become settings

ansible-config dump --only-changed | grep -i become
ansible-inventory -i inventories/production --host web02.example.com \
| grep -i become
ansible web02.example.com -b -m command -a 'id' -vvv 2>&1 | grep -i 'sudo'

The -vvv output shows the constructed sudo command line, including the flags and the prompt Ansible sets. Ansible uses a distinctive prompt so it can recognise its own escalation:

[sudo via ansible, key=REPLACE_ME] password:

If a password is expected, the fix is not to store one. It is to decide whether this account should need one at all.

Step 4: Reproduce the way Ansible does it

The single most common false conclusion in this runbook is “it works when I do it”. It works because you did it differently.

# -T suppresses TTY allocation, which is how Ansible connects.
# -n makes sudo refuse rather than prompt.
sudo -iu ansible ssh -T -o BatchMode=yes ansible@192.0.2.12 'sudo -n id'

That one line reproduces almost every become failure. Compare it with the way it usually gets tested:

# Interactive, with a TTY, as a human account. Proves nothing about automation.
ssh web02.example.com
sudo id

Three differences, each of which independently produces a failure that the interactive test cannot see: a TTY exists, the account is yours not the automation account, and sudo is allowed to prompt.

Step 5: Read sudo’s own decision

# As the automation account, on the target
sudo -n -l -U ansible

# What actually happened, from the auth log
sudo journalctl -t sudo -n 50 --no-pager
sudo grep -i sudo /var/log/auth.log | tail -20

sudo -l -U ansible prints the rules that apply to that account, resolved - including drop-ins, aliases and Defaults lines. It is the authoritative answer to “is this allowed”, and it is much faster than reading the files.

The auth log shows the specific refusal:

sudo: ansible : command not allowed ; TTY=unknown ; PWD=/home/ansible ;
      USER=root ; COMMAND=/usr/bin/systemctl restart nginx
sudo: ansible : sorry, you must have a tty to run sudo ; TTY=unknown ;
      PWD=/home/ansible ; USER=root ; COMMAND=/bin/sh -c ...

TTY=unknown in those lines is the tell for the requiretty case.

Step 6: The two structural traps

requiretty

sudo -n -l -U ansible | grep -i requiretty
sudo grep -rn 'requiretty' /etc/sudoers /etc/sudoers.d/ 2>/dev/null

Defaults requiretty makes sudo refuse to run without a terminal. Ansible connects without one, so every escalation fails - and it fails in a way that looks like a permissions problem until you read TTY=unknown in the log.

The fix is to exempt the automation account specifically, not to remove the policy for everyone:

# /etc/sudoers.d/50-ansible   (mode 0440, root:root)
Defaults:ansible !requiretty
ansible ALL=(root) NOPASSWD: ALL

Escalation timeout

Timeout (Ns) waiting for privilege escalation prompt means sudo produced no output Ansible recognised as a prompt. Causes, in order of frequency:

• sudo is hanging on something - LDAP or a name service lookup that is not answering, an audit backend that is blocking, a full disk.
• requiretty is set and sudo exited before prompting.
• A Defaults line changed the prompt in a way Ansible’s matcher does not recognise.
• The become method is not the one you think - become_method: su behaves differently from sudo.

sudo -iu ansible ssh -T ansible@192.0.2.12 'time sudo -n true'
sudo -iu ansible ssh -T ansible@192.0.2.12 'getent group ansible; time id ansible'

If sudo -n true takes several seconds, the fault is in name resolution or in a sudo plugin, and no sudoers change will fix it.

Step 7: Validate sudoers before you install anything

# 0. Open a second session that is ALREADY root, and leave it open
#    sudo -i

# 1. Write the candidate somewhere harmless
cat > /tmp/50-ansible <<'EOF'
Defaults:ansible !requiretty
ansible ALL=(root) NOPASSWD: ALL
EOF

# 2. Validate the candidate file itself
visudo -cf /tmp/50-ansible

# 3. Install with the required ownership and mode
install -m 0440 -o root -g root /tmp/50-ansible /etc/sudoers.d/50-ansible

# 4. Validate the whole resolved policy, not just the new file
visudo -c

# 5. Prove it from a NEW non-interactive session before closing the root one
ssh -T -o BatchMode=yes ansible@192.0.2.12 'sudo -n id'

Mode 0440 and owner root:root are requirements, not conventions. sudo ignores files in sudoers.d that are group- or world-writable, and it ignores them silently - the rule is present, readable, correct, and has no effect.

The same applies to filenames: sudo skips files in sudoers.d whose names contain a dot or end in ~. A drop-in called 50-ansible.conf does nothing.

Step 8: Verify

# 1. Non-interactive, no TTY - the way automation does it
sudo -iu ansible ssh -T -o BatchMode=yes ansible@192.0.2.12 'sudo -n id'

# 2. From Ansible
ansible web02.example.com -b -m command -a 'id' -o
echo "exit=$?"

# 3. The whole group
ansible web -b -m command -a 'id -u' -o | grep -c 'rc=0'

# 4. What the account can now do - check it is not more than intended
ansible web02.example.com -m command -a 'sudo -n -l -U ansible' -o

Step 4 is the one to not skip. A become failure fixed by widening a rule is a become failure fixed by granting privilege, and reading back what was granted is how that stays deliberate.

Rollback

# With an open root session available
rm -f /etc/sudoers.d/50-ansible
visudo -c
ssh -T -o BatchMode=yes ansible@192.0.2.12 'sudo -n id' ; echo "expect failure, rc=$?"

Common patterns

Escalation

Escalate when:

• A rule would have to be wider than the roles justify.
• sudo is broken for all accounts on a host. That needs console access.
• Escalation failed fleet-wide. That is a configuration management or policy event.
• The automation account is required to supply a become password in an unattended context.