Fehlerbehebung bei SSH-Verbindungsfehlern in Ansible Playbooks

Ansible ist ausschließlich auf das Secure Shell (SSH)-Protokoll zur Kommunikation mit verwalteten Knoten angewiesen. Wenn ein Ansible Playbook mit einem Konnektivitätsfehler fehlschlägt, deutet dies fast immer auf ein zugrunde liegendes Problem in der Standard-SSH-Einrichtung zwischen der Steuerungsmaschine und dem Zielhost hin. Das Verständnis, wie man diese Fehler systematisch diagnostiziert, ist entscheidend für die Aufrechterhaltung zuverlässiger Automatisierung.

Diese Anleitung bietet eine schrittweise Methodik zur Diagnose und Behebung der häufigsten SSH-Verbindungsfehler, die beim Ausführen von Ansible Playbooks auftreten, um sicherzustellen, dass Ihre Konfigurationsverwaltung reibungslos läuft.

Phase 1: Aktivierung der Ausführlichkeit und erste Prüfungen

Das wichtigste Werkzeug bei der Ansible-Fehlerbehebung ist die Erhöhung der Ausführlichkeitsstufe (Verbosity). SSH-Fehler werden oft verschleiert, aber maximale Ausführlichkeit deckt die genauen Parameter auf, die Ansible verwendet, und die spezifische Fehlermeldung, die vom zugrunde liegenden OpenSSH-Client zurückgegeben wird.

Verwendung von Ausführlichkeits-Flags

Führen Sie Ihren Testbefehl oder Ihr Playbook mit drei oder vier Ausführlichkeits-Flags (-v, -vv, -vvv, -vvvv) aus. Die meisten Verbindungsprobleme werden durch die Überprüfung der Ausgabe von -vvv gelöst.

# Testen der Konnektivität zu einem Host namens 'webserver', der in Ihrem Inventar definiert ist
ansible webserver -m ansible.builtin.ping -vvv

# Ausführen eines Playbooks mit maximalem Debugging
ansible-playbook site.yml -i inventory.ini -vvvv

Überprüfung des Inventars und des Host-Status

Stellen Sie sicher, dass der Zielhost korrekt definiert und erreichbar ist.

Ist der Hostname korrekt? Überprüfen Sie die Schreibweise in Ihrer Inventardatei (/etc/ansible/hosts oder benutzerdefiniertes Inventar).
Ist das Ziel aktiv? Stellen Sie sicher, dass der verwaltete Knoten eingeschaltet und im Netzwerk zugänglich ist.
Sind die Inventarvariablen korrekt? Bestätigen Sie, dass wesentliche Variablen wie ansible_host (IP-Adresse oder Hostname) und ansible_user (Remote-Benutzername) für die Zielgruppe oder den Host korrekt festgelegt sind.

# Beispiel Inventar-Ausschnitt
[webservers]
web1 ansible_host=192.168.1.100 ansible_user=deploy_user ansible_port=22

Phase 2: Überprüfung der grundlegenden manuellen Konnektivität

Wenn Ansible keine Verbindung herstellen kann, muss der erste Schritt immer darin bestehen, zu bestätigen, dass Standard-SSH manuell funktioniert, wobei genau derselbe Benutzer, derselbe Schlüssel und derselbe Port verwendet werden, die Ansible zu verwenden konfiguriert ist.

Manueller SSH-Test

Wenn Sie einen bestimmten Benutzer (ansible_user) und einen bestimmten privaten Schlüssel (ansible_ssh_private_key_file) verwenden, replizieren Sie diese Verbindung manuell.

# Standard-SSH-Test (bei Verwendung des Standardports und -schlüssels)
ssh <ansible_user>@<ansible_host>

# Test mit einem nicht standardmäßigen privaten Schlüssel und Port
ssh -i /path/to/private/key -p 2222 [email protected]

Wenn der manuelle SSH-Test fehlschlägt, liegt das Problem in der Umgebung und nicht bei Ansible. Beheben Sie zuerst das zugrunde liegende SSH-Problem, bevor Sie mit Ansible fortfahren.

Phase 3: Diagnose von Authentifizierungsfehlern

Authentifizierungsfehler sind die häufigste Ursache für Ansible-Verbindungsprobleme. Diese äußern sich normalerweise als Fehler wie Authentication failed oder Permission denied.

3.1 Schlüsselberechtigungen und Speicherort

Wenn Ansible SSH-Schlüssel verwendet, stellen Sie sicher, dass die Datei mit dem privaten Schlüssel auf der Steuerungsmaschine die korrekten, eingeschränkten Berechtigungen aufweist. SSH lehnt oft Schlüssel ab, die zu freizügig sind.

# Korrekte Berechtigungen für die private Schlüsseldatei festlegen
chmod 600 /path/to/private/key

Stellen Sie außerdem sicher, dass Ihr Schlüssel hinzugefügt ist, falls Sie einen SSH-Agenten verwenden:

# Agenten bei Bedarf starten
eval "$(ssh-agent -s)"
# Ihren Schlüssel zum Agenten hinzufügen
ssh-add /path/to/private/key

3.2 Fehler bei der Passworteingabe (Timeout/Fehlendes Passwort)

Wenn Ihr Setup ein Passwort erfordert (in Produktionsumgebungen nicht empfohlen, aber in Laboren üblich), muss Ansible dieses erhalten. Wenn die Verbindung hängt oder einen Timeout verursacht, wartet Ansible wahrscheinlich auf ein Passwort, das nie bereitgestellt wurde.

Verwenden Sie das Flag --ask-pass oder -k, um nach dem SSH-Verbindungspasswort gefragt zu werden:

ansible webserver -m ansible.builtin.ping -k

3.3 Remote-autorisierte Schlüssel

Überprüfen Sie, ob der öffentliche Schlüssel, der Ihrem privaten Schlüssel entspricht, korrekt in der Datei ~/.ssh/authorized_keys auf dem verwalteten Knoten installiert ist und ob die Berechtigungen der Datei und des Verzeichnisses auf der Remote-Seite korrekt sind (700 für .ssh und 600 für authorized_keys).

Phase 4: Behebung von Host-Key-Fehlern

Ansible respektiert die known_hosts-Datei, in der der digitale Fingerabdruck von Remote-Servern gespeichert ist. Wenn sich der Host-Schlüssel eines verwalteten Knotens ändert (z. B. aufgrund einer Neuinstallation oder IP-Neuzuweisung), schlagen SSH-Verbindungsversuche mit einer Warnung fehl, die wie ein Man-in-the-Middle-Angriff aussieht.

Der Fehler `Host key verification failed`

Wenn dieser Fehler auftritt, müssen Sie den widersprüchlichen Schlüsseleintrag aktualisieren oder entfernen.

Identifizieren Sie die Zeilennummer in ~/.ssh/known_hosts, die in der Fehlerausgabe erwähnt wird.
Entfernen Sie den Eintrag mithilfe von ssh-keygen.

# Ersetzen Sie <hostname_or_ip> durch den tatsächlich fehlerhaften Host
ssh-keygen -R <hostname_or_ip>

⚠️ Sicherheitshinweis: Deaktivierung der Host-Überprüfung

Für temporäre Tests oder in streng kontrollierten Laborumgebungen, in denen eine Host-Instabilität erwartet wird, können Sie Ansible so konfigurieren, dass die Host-Schlüsselüberprüfung ignoriert wird. Dies wird für Produktionsumgebungen dringend abgeraten, da es Sie MITM-Angriffen aussetzt.

In Ihrer ansible.cfg (oder temporären Umgebungsvariable):
ini [defaults] host_key_checking = False

Phase 5: Netzwerk-, Firewall- und Remote-Umgebungsprobleme

Manchmal stellt SSH eine Verbindung her, aber die Verbindung stagniert oder schlägt aufgrund von Netzwerk-Konfigurationen oder Beschränkungen auf der Zielmaschine fehl.

5.1 Firewall-Blockade

Wenn die Verbindung ohne Eingabeaufforderung abbricht (Timeout), blockiert wahrscheinlich eine Firewall den Verbindungsversuch. Überprüfen Sie die Firewall an drei Stellen:

Lokal (Steuerungsmaschine): Stellen Sie sicher, dass ausgehender Datenverkehr über Port 22 (oder benutzerdefinierten Port) zugelassen ist.
Netzwerkpfad: Stellen Sie sicher, dass keine zwischengeschalteten Netzwerk-ACLs oder Unternehmens-Firewalls den Datenverkehr blockieren.
Remote (Verwalteter Knoten): Überprüfen Sie, ob die Firewall des Remote-Hosts (firewalld, ufw usw.) SSH (normalerweise Port 22) geöffnet hat und für die richtige Netzwerkschnittstelle konfiguriert ist.

5.2 Fehler des Python-Interpreters

Ansible benötigt einen Python-Interpreter auf dem verwalteten Knoten, um Module auszuführen. Obwohl es sich technisch gesehen nicht um einen SSH-Fehler handelt, beinhaltet die anfängliche Verbindungsphase von Ansible das Sammeln von Fakten, was die Ausführung eines Python-Skripts ist. Wenn der Zielcomputer eine minimale Installation ohne Python 3 ist, kann die Verbindung während der Einrichtung fehlschlagen.

Wenn Ihr Ziel Python 3 verwendet, der Interpreterpfad jedoch nicht standardmäßig ist (z. B. python3.8 anstelle von python3), geben Sie den korrekten Pfad in Ihrem Inventar an:

[target_host]
ansible_python_interpreter=/usr/bin/python3.8

5.3 SELinux- oder AppArmor-Kontext

In seltenen Fällen können zu strenge Sicherheitsmodule wie SELinux (unter RHEL/CentOS/Fedora) oder AppArmor (unter Ubuntu/Debian) dazu führen, dass das Shell-Profil oder die Verzeichnisberechtigungen des Remote-Benutzers während der SSH-Sitzung nicht korrekt abgerufen werden. Überprüfen Sie die Audit-Protokolle des Remote-Hosts (/var/log/audit/audit.log oder Äquivalent) auf AVC-Ablehnungen im Zusammenhang mit SSH oder dem Zugriff auf das Home-Verzeichnis des Benutzers.

Zusammenfassung der häufigsten Verbindungsfehler und Lösungen

Fehlermeldung	Wahrscheinliche Ursache	Umsetzbare Lösung
`Permission denied (publickey).`	Schlüssel wird nicht erkannt oder falsche Schlüsselberechtigungen.	`chmod 600` auf dem privaten Schlüssel; öffentlichen Schlüssel auf dem Remote-Host überprüfen.
`Host key verification failed.`	Host-Schlüssel wurde geändert oder `known_hosts`-Datei ist beschädigt.	`ssh-keygen -R hostname` verwenden, um den alten Eintrag zu entfernen.
`Connection timed out.`	Firewall-Blockade oder Host ist nicht erreichbar/offline.	Manuelle Konnektivität (`ping`, `ssh`) prüfen; Firewall-Regeln auf dem Zielhost überprüfen.
Verbindung hängt/friert ein.	Wartet auf eine Passworteingabe, die nicht bereitgestellt wurde.	Mit `-k` ausführen oder Schlüssel-basierte Authentifizierung konfigurieren.

Fazit

Die Fehlerbehebung bei SSH-Verbindungsproblemen in Ansible ist hauptsächlich ein systematischer Prozess zur Fehlersuche in der zugrunde liegenden SSH-Client-Konfiguration. Indem Sie mit grundlegenden manuellen Konnektivitätsprüfungen beginnen, die Ausführlichkeit erhöhen (-vvv) und systematisch Authentifizierung, Host-Schlüssel und Netzwerkpfade überprüfen, können Sie die meisten Verbindungsausfälle schnell isolieren und beheben, sodass Ihre Automatisierungsworkflows ohne Unterbrechung fortgesetzt werden können.