TL;DR Quick Fix
The fatal: [host]: UNREACHABLE! error in Ansible almost always indicates that your Ansible control node cannot establish an SSH connection to the target host. Start by checking basic network connectivity with ping and then attempt a manual SSH connection from your control node to the problematic host:
ping <your_target_host_ip_or_hostname>
ssh <your_ssh_user>@<your_target_host_ip_or_hostname>
If either of these fail, you've found your starting point: network, firewall, or SSH server issues. If SSH works manually, the problem likely lies with Ansible's configuration for SSH.
Detailed Root Cause
When Ansible reports fatal: [host]: UNREACHABLE!, it means that the underlying communication mechanism Ansible uses (typically SSH) failed to connect to the managed host. Ansible needs to be able to log into the target machine to execute modules and commands. This error is a high-level symptom of a lower-level connectivity problem. It's not that Ansible can't run a task, but that it can't even talk to the server to begin with. Common reasons for this include:
- Network Issues: The control node cannot reach the managed host's IP address or hostname.
- Firewall Restrictions: A firewall (either on the control node, managed node, or somewhere in between) is blocking the SSH connection (port 22 by default).
- SSH Daemon Problems: The SSH server (
sshd) on the managed node is not running, is misconfigured, or is overloaded. - Incorrect Credentials/Authentication: Ansible is trying to authenticate with incorrect usernames, passwords, or SSH keys, leading to connection refusals.
- Host Key Verification Issues: SSH is unable to verify the host key of the managed node, often due to a changed key or first-time connection.
- Inventory Mismatches: The hostname or IP address in your Ansible inventory file is incorrect.
Fix Approaches
1. Verify Network Connectivity
First, ensure your Ansible control node can actually communicate with the target host at a basic network level.
How to Fix:
-
Ping the host:
ping <your_target_host_ip_or_hostname>
If `ping` fails, there's a fundamental network route issue. Check the host's IP address, network cables, router settings, or cloud security groups.
-
**Check SSH Port Reachability:** Use `telnet` or `nc` (netcat) to see if port 22 (the default SSH port) is open and listening.
```bash
telnet <your_target_host_ip_or_hostname> 22
You should see something like SSH-2.0-OpenSSH_.... If it hangs or immediately connects then disconnects, the port might be blocked or the SSH server isn't responding.
Alternatively, using `nc`:
```bash
nc -vz <your_target_host_ip_or_hostname> 22
Look for output like `Connection to <host> 22 port [tcp/ssh] succeeded!`.
#### Verification:
After resolving any network issues, re-run your Ansible playbook or a simple ping module:
```bash
ansible <your_inventory_group> -m ping
2. Inspect SSH Daemon on Managed Host
The SSH server (sshd) on your target machine must be running and correctly configured to accept connections.
How to Fix:
Log in to the managed host (if possible, perhaps via console or another working SSH session) and check the status of the SSH daemon.
-
Check SSH service status:
sudo systemctl status sshd
If it's not running, start it:
```bash
sudo systemctl start sshd
sudo systemctl enable sshd # To ensure it starts on boot
-
Review SSH daemon logs: Check system logs for errors related to SSH.
sudo journalctl -u sshd -e
Or for older systems
sudo tail -f /var/log/auth.log sudo tail -f /var/log/secure # RedHat/CentOS
Look for messages indicating why connections might be failing (e.g., authentication errors, configuration problems).
-
**Check `/etc/ssh/sshd_config`:** Ensure `Port 22` (or your custom SSH port) is uncommented and `PasswordAuthentication yes` or `PubkeyAuthentication yes` are set as expected for your authentication method.
#### Verification:
Attempt a manual SSH connection from the control node:
```bash
ssh <your_ssh_user>@<your_target_host_ip_or_hostname>
Once successful, try the Ansible ping module again.
3. Resolve Firewall Blocks
Firewalls are a common culprit for connection issues. Check firewalls on both the Ansible control node and the managed host.
How to Fix:
-
On the Managed Host:
UFW (Ubuntu/Debian): ```bash sudo ufw status verbose sudo ufw allow OpenSSH # or sudo ufw allow 22/tcp sudo ufw enable
- **firewalld (CentOS/RHEL):**
```bash
sudo firewall-cmd --list-all
sudo firewall-cmd --add-service=ssh --permanent
sudo firewall-cmd --reload
- **iptables (General Linux):** This is more complex, but you might need to check for rules blocking port 22. A quick check for existing rules:
```bash
sudo iptables -L -n | grep 22
You may need to add a rule to allow incoming SSH connections:
```bash
sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
Remember to save iptables rules to persist them across reboots.
-
On the Control Node: While less common for outbound connections, ensure no local firewall rules are preventing your Ansible control node from initiating SSH connections.
-
Cloud Provider Security Groups/Network ACLs: If your hosts are in a cloud environment (AWS, Azure, GCP), verify that their security groups or network ACLs allow inbound traffic on port 22 from your control node's IP address.
Verification:
After adjusting firewall rules, try telnet or nc to port 22 again, then proceed with the Ansible ping module:
ansible <your_inventory_group> -m ping
4. Correct SSH Credentials and Authentication
Ansible relies on SSH for authentication. If Ansible can connect but fails to authenticate, you will get this unreachable error.
How to Fix:
-
Manual SSH Test: First, ensure you can manually SSH into the host using the exact user, key, or password Ansible will use.
ssh <ansible_user>@<your_target_host_ip_or_hostname> -i /path/to/your/private_key
If this fails, resolve the manual SSH issue first. Common problems include:
Incorrect username.
- Private key file permissions (must be `0600` or `0400`): `chmod 600 /path/to/your/private_key`.
- The corresponding public key is not in `~/.ssh/authorized_keys` on the managed host.
- Incorrect password (if using password authentication).
-
**Ansible Inventory and Configuration:** Verify your inventory file (e.g., `/etc/ansible/hosts` or a project-specific one) and `ansible.cfg` for correct SSH parameters:
**`ansible_host`:** The IP address or hostname of the target machine.
- **`ansible_user`:** The username Ansible should use to connect.
- **`ansible_port`:** If SSH isn't on port 22.
- **`ansible_private_key_file`:** Path to the SSH private key.
- **`ansible_ssh_pass` / `ansible_password`:** SSH password (generally not recommended, use SSH keys or Ansible Vault).
- **`ansible_ssh_common_args`:** For custom SSH arguments, e.g., `-o StrictHostKeyChecking=no` (use with caution, for initial setup or known environments only).
Example inventory entry:
```ini
[webservers]
web1 ansible_host=192.168.1.100 ansible_user=deployuser ansible_private_key_file=/home/user/.ssh/id_rsa
-
SSH Agent: If you use an SSH agent, ensure your keys are added:
eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_rsa
-
**Host Key Verification:** If you see a warning about host key verification, you might need to add the host to your `known_hosts` file. You can connect manually first:
```bash
ssh <ansible_user>@<your_target_host_ip_or_hostname>
and accept the key, or, for temporary or controlled environments, use:
```ini
[defaults] host_key_checking = False
in `ansible.cfg` or set `ansible_ssh_common_args='-o StrictHostKeyChecking=no'` in your inventory (again, with caution).
#### Verification:
After adjusting authentication details, try your Ansible command again:
```bash
ansible <your_inventory_group> -m ping
5. Incorrect Python Interpreter Path
While less common for the UNREACHABLE! error itself (which usually happens before any Python code runs), if your connection briefly succeeds and then fails with strange errors, it might relate to Ansible not finding the Python interpreter on the managed host.
How to Fix:
Specify the correct Python interpreter path in your inventory or ansible.cfg:
[webservers:vars]
ansible_python_interpreter=/usr/bin/python3
Or globally in ansible.cfg:
[defaults]
interpreter_python = auto_silent # Ansible will try to auto-detect. Or specify path: /usr/bin/python3
Verification:
Run a simple Ansible command that requires the Python interpreter:
ansible <your_inventory_group> -m setup