Diagnosing Ansible Playbook Failures Caused by SSH Authentication Issues

Problem Statement

When an Ansible playbook aborts with errors such as FAILED! => SSH: Authentication failed or UNREACHABLE!, the root cause is almost always an SSH authentication problem. The playbook may be syntactically correct, but if Ansible cannot establish a secure channel to the target host, no tasks will run. This guide provides a concise cause–check–fix table, an ordered troubleshooting sequence, and clear escalation criteria.

Cause–Check–Fix Table

Possible Cause	Check	Fix
Missing or unreadable private key	Run ls -l ~/.ssh/id_rsa	Set permissions to 600 or update ansible.cfg to point to the correct key
SSH agent not loaded or key not added	Run ssh-add -l	Start the agent and add the key: ssh-add ~/.ssh/id_rsa
Host key verification failed	Test with ssh -o StrictHostKeyChecking=no -i ~/.ssh/id_rsa user@host	Add host to ~/.ssh/known_hosts or set host_key_checking = False in ansible.cfg (only for testing)
Wrong remote user or become settings	Run ansible -m ping -u user host	Adjust remote_user or become_user in the playbook or inventory
Firewall or network blocks SSH port	Run telnet host 22 or nc -zv host 22	Open port 22 in the firewall or configure a proxy
Incorrect SSH port configured	Run ansible -m ping -e "ansible_port=2222" host	Update inventory or ansible.cfg with the correct port

Ordered Troubleshooting Steps

1. Verify the Private Key

   Check that the key file exists and is readable by the user running Ansible:

   # Run as the Ansible operator
   ls -l ~/.ssh/id_rsa
   # Expected output: -rw------- 1 user user 1675 Oct 12 10:00 id_rsa
   

   If the file is missing or has permissions other than 600, correct them:

   # Fix permissions
   chmod 600 ~/.ssh/id_rsa
   

   Alternatively, point Ansible to another key via ansible.cfg:

   [defaults]
   private_key_file = ~/.ssh/other_id_rsa
   

2. Check the SSH Agent

   Confirm that the key is loaded into the agent:

   ssh-add -l
   # If no identities are listed, add the key
   ssh-add ~/.ssh/id_rsa
   

   On systems without an agent, you can bypass it by specifying the key directly in ansible.cfg or the inventory.

3. Test Host Key Verification

   Attempt a manual SSH connection with host key checking disabled to see if the key is accepted:

   ssh -o StrictHostKeyChecking=no -i ~/.ssh/id_rsa user@host
   

   If the connection succeeds, the issue is host key verification. Add the host to known_hosts or enable host_key_checking = False in ansible.cfg only for debugging. In production, never disable this setting.

4. Validate Remote User and Privilege Escalation

   Run a quick ping module to confirm user credentials:

   ansible -m ping -u user host
   

   Adjust the playbook or inventory if a different user is required:

   - hosts: webservers
     remote_user: deploy
     become: yes
     become_user: root
   

5. Inspect Network Connectivity

   Ensure the SSH port is reachable from the Ansible control node:

   telnet host 22
   # or
   nc -zv host 22
   

   When blocked, modify firewall rules or use an SSH proxy. Verify the proxy configuration in ansible.cfg with ssh_common_args if needed.

6. Confirm the SSH Port

   If the target uses a non‑standard port, explicitly set it:

   ansible -m ping -e "ansible_port=2222" host
   

   Update the inventory entry:

   host ansible_port=2222
   

7. Run the Playbook with Verbose Logging

   Execute the playbook with -vvv to capture the SSH negotiation details:

   ansible-playbook playbook.yml -vvv
   

   Look for lines such as ssh: connect to host 192.168.1.10 port 22: Connection timed out or Authentication failed to pinpoint the failure.

Verification Checklist

• Confirm the key file exists and has 600 permissions.
• Ensure ssh-add -l lists the key.
• Test manual SSH with the same credentials.
• Verify ansible.cfg and inventory contain correct remote_user, ansible_port, and private_key_file settings.
• Check /var/log/secure (Linux) or /var/log/auth.log on the target for authentication attempts.
• Run ansible-inventory --graph to confirm hosts are reachable.

Escalation Criteria

1. If all local checks succeed but the playbook still fails, involve the network team to verify that the SSH port is open and that no IDS/IPS is blocking the traffic.
2. If the host key is unknown and adding it manually is not feasible (e.g., dynamic hosts), coordinate with the infrastructure team to update the known_hosts file centrally.
3. When key permissions or ownership appear correct but authentication still fails, suspect key corruption or a mismatched algorithm; regenerate the key pair and update all relevant systems.
4. For production environments, if host key checking must be disabled for a quick fix, document the change and schedule a review to re‑enable it.

Limitations and Best Practices

• Never disable host_key_checking in production; it exposes the system to man‑in‑the‑middle attacks.
• Avoid using root over SSH; prefer become for privilege escalation.
• Never store private keys in playbooks or version control; use ssh-agent or Ansible Vault for secrets.
• When troubleshooting, always revert any temporary changes (e.g., host_key_checking = False) before committing to production.