Maximilian.pottgiesser: Die Seite wurde neu angelegt: „= Proxmox Cluster-Join Troubleshooting = == Symptome == Nach einem `pvecm add` ist der neue Knoten: * Nicht mehr über die Weboberfläche (Port 8…“

2026-02-13T08:12:54Z

Die Seite wurde neu angelegt: „= Proxmox Cluster-Join Troubleshooting = == Symptome == Nach einem <code>pvecm add</code> ist der neue Knoten: * Nicht mehr über die Weboberfläche (Port 8…“

Neue Seite

= Proxmox Cluster-Join Troubleshooting =

== Symptome ==

Nach einem <code>pvecm add</code> ist der neue Knoten:

* Nicht mehr über die Weboberfläche (Port 8006) erreichbar
* Nicht korrekt im Cluster sichtbar
* Im Journal finden sich Fehler zu <code>/etc/pve/local/pve-ssl.key</code> (private key not found / permission denied)

----

== Ursachenanalyse ==

=== Häufigste Ursache: Falsche /etc/hosts ===

Wenn der Hostname vor dem Join auf <code>127.0.0.1</code> oder <code>127.0.1.1</code> gemappt war statt auf die tatsächliche Management-IP, registriert sich der Knoten mit der falschen Adresse im Cluster. Das ist '''mit Abstand die häufigste Ursache''' für fehlgeschlagene Cluster-Joins.

=== SSL-Zertifikate nicht erreichbar ===

<code>/etc/pve/local/</code> ist ein Symlink auf <code>/etc/pve/nodes/<hostname>/</code>. Dieses Verzeichnis wird über '''pmxcfs''' bereitgestellt, das wiederum auf einer funktionierenden Corosync-Verbindung basiert. Wenn Corosync nach dem Join nicht richtig connected ist, ist <code>/etc/pve</code> nicht oder nur teilweise zugänglich. Damit fehlen:

* <code>/etc/pve/local/pve-ssl.key</code> – der private SSL-Key
* <code>/etc/pve/local/pve-ssl.pem</code> – das SSL-Zertifikat

Ohne diese Dateien kann der <code>pveproxy</code>-Dienst nicht starten → die Weboberfläche auf Port 8006 ist nicht erreichbar.

=== Weitere mögliche Ursachen ===

{| class="wikitable"
|-
! Ursache !! Prüfung
|-
| Netzwerk-Interface hat sich geändert || <code>ip addr show</code> – stimmt die IP mit der Corosync-Config überein?
|-
| Firewall blockiert Corosync-Ports || UDP 5405–5412 zwischen allen Knoten offen? Prüfen mit <code>ss -ulnp | grep corosync</code>
|-
| Hostname stimmt nicht || <code>hostname -f</code> muss mit dem Eintrag in <code>/etc/hosts</code> übereinstimmen
|-
| Alte Cluster-Konfiguration vorhanden || Vor einem Join muss der Knoten entweder eine frische Installation sein oder sauber bereinigt werden
|}

----

== Reparatur ==

=== Voraussetzung: Konsolen-Zugang ===

Da der Host über die Weboberfläche nicht erreichbar ist, wird '''direkter Zugang''' benötigt – entweder über Tastatur/Monitor am Server, über IPMI/iDRAC/iLO, oder falls SSH noch funktioniert.

=== Schritt 1: pmxcfs im lokalen Modus starten ===

<pre>
systemctl stop pve-cluster corosync
pmxcfs -l
</pre>

Das <code>-l</code> startet pmxcfs im '''lokalen Modus''' – also ohne Corosync-Verbindung. Jetzt sollte <code>/etc/pve</code> wieder zugänglich sein.

=== Schritt 2: /etc/hosts prüfen und korrigieren ===

<pre>
cat /etc/hosts
</pre>

Die Datei muss so aussehen (Beispiel):

<pre>
127.0.0.1 localhost
192.168.1.50 pve-node3.domain.lan pve-node3
</pre>

'''Kritisch:''' Der Hostname darf '''nicht''' auf <code>127.0.0.1</code> oder <code>127.0.1.1</code> zeigen. Er muss auf die tatsächliche Management-IP zeigen.

=== Schritt 3: SSL-Zertifikate prüfen ===

<pre>
ls -la /etc/pve/local/
ls -la /etc/pve/nodes/$(hostname)/
</pre>

Falls die Dateien <code>pve-ssl.key</code> und <code>pve-ssl.pem</code> fehlen oder leer sind, müssen sie neu generiert werden:

<pre>
pvecm updatecerts --force
</pre>

Danach prüfen ob die Dateien vorhanden sind:

<pre>
ls -la /etc/pve/local/pve-ssl.key
ls -la /etc/pve/local/pve-ssl.pem
</pre>

=== Schritt 4: Kaputten Knoten aus dem Cluster entfernen ===

Wenn der Knoten halb im Cluster hängt, ist es oft am saubersten, ihn komplett zu entfernen und neu zu joinen.

'''Auf dem bestehenden Cluster-Knoten''' den kaputten Knoten entfernen:

<pre>
pvecm delnode <knotenname>
</pre>

'''Auf dem kaputten Knoten''' den Cluster-Zustand zurücksetzen:

<pre>
systemctl stop pve-cluster corosync
pmxcfs -l
rm -f /etc/pve/corosync.conf
rm -rf /etc/corosync/*
killall pmxcfs
systemctl start pve-cluster
</pre>

=== Schritt 5: SSL-Zertifikate neu generieren ===

Nach dem Zurücksetzen des Cluster-Zustands die Zertifikate erneuern:

<pre>
pvecm updatecerts --force
</pre>

Dienste neu starten:

<pre>
systemctl restart pveproxy
systemctl restart pvedaemon
</pre>

Prüfen ob die Weboberfläche wieder lauscht:

<pre>
ss -tlnp | grep 8006
</pre>

Optional – Zertifikat-Details prüfen:

<pre>
openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -subject -dates
</pre>

=== Schritt 6: Sauber neu joinen ===

Erst sicherstellen, dass der Knoten standalone wieder voll funktioniert (Weboberfläche erreichbar auf Port 8006). Dann den Join erneut durchführen:

<pre>
pvecm add <IP-des-bestehenden-Cluster-Knotens>
</pre>

=== Schritt 7: Ergebnis prüfen ===

<pre>
# Cluster-Status
pvecm status

# Alle Knoten sichtbar?
pvecm nodes

# Quorum vorhanden?
corosync-quorumtool

# Corosync-Ring gesund?
corosync-cfgtool -s
</pre>

----

== Checkliste: Vor jedem Cluster-Join ==

Diese Punkte '''vor''' dem Ausführen von <code>pvecm add</code> prüfen, um Probleme zu vermeiden:

{| class="wikitable"
|-
! ✓ !! Prüfpunkt !! Kommando
|-
| ☐ || Hostname zeigt in <code>/etc/hosts</code> auf Management-IP, '''nicht''' auf 127.0.x.x || <code>cat /etc/hosts</code>
|-
| ☐ || FQDN stimmt mit Hostname überein || <code>hostname -f</code>
|-
| ☐ || Alle Knoten können sich gegenseitig per IP erreichen || <code>ping <IP-des-anderen-Knotens></code>
|-
| ☐ || UDP 5405–5412 ist zwischen den Knoten offen || <code>ss -ulnp | grep corosync</code>
|-
| ☐ || SSH-Zugang vom neuen Knoten zum bestehenden Cluster funktioniert || <code>ssh root@<Cluster-IP></code>
|-
| ☐ || Keine alte Cluster-Konfiguration vorhanden || <code>ls /etc/corosync/</code> sollte leer sein
|-
| ☐ || Knoten hat eine frische Proxmox-Installation oder wurde sauber bereinigt || –
|-
| ☐ || Zeitserver konfiguriert und synchron || <code>timedatectl status</code>
|-
| ☐ || Kein anderes Cluster-Dateisystem gemountet || <code>mount | grep pve</code>
|}

----

== Zusammenfassung der relevanten Ports und Dienste ==

{| class="wikitable"
|-
! Dienst !! Port !! Protokoll !! Beschreibung
|-
| '''Corosync''' || 5405–5412 || UDP || Cluster-Kommunikation (Totem-Ring, Quorum)
|-
| '''pveproxy''' || 8006 || TCP (HTTPS) || Proxmox Weboberfläche
|-
| '''SSH''' || 22 || TCP || Wird für den Cluster-Join und die Verwaltung benötigt
|-
| '''pvedaemon''' || 85 || TCP || Proxmox API-Daemon (intern)
|-
| '''Spice''' || 3128 || TCP || VM-Konsole via Spice-Proxy
|-
| '''VNC''' || 5900–5999 || TCP || VM-Konsole via VNC
|-
| '''Migration''' || 60000–60050 || TCP || Live-Migration von VMs zwischen Knoten
|}

'''Hinweis:''' Alle diese Ports müssen zwischen den Cluster-Knoten erreichbar sein. Insbesondere UDP 5405–5412 (Corosync) und TCP 22 (SSH) sind für den Cluster-Join zwingend erforderlich.

Proxmox Cluster Troubleshooting - Versionsgeschichte

Maximilian.pottgiesser: Die Seite wurde neu angelegt: „= Proxmox Cluster-Join Troubleshooting = == Symptome == Nach einem pvecm add ist der neue Knoten: * Nicht mehr über die Weboberfläche (Port 8…“

Maximilian.pottgiesser: Die Seite wurde neu angelegt: „= Proxmox Cluster-Join Troubleshooting = == Symptome == Nach einem `pvecm add` ist der neue Knoten: * Nicht mehr über die Weboberfläche (Port 8…“