Hochverfügbarkeit auf netcup: Zwei VPS mit Keepalived, Failover-IP und Cloud-vLAN absichern

Dies ist Teil 14 unserer netcup-Serie. Davor: Teil 13: Failover-IP. Danach: Teil 15: REST-API.

Läuft ein kritischer Dienst auf einem einzelnen VPS, reicht ein Kernel-Panic, ein fehlgeschlagenes Update oder ein Hardwarefehler, und der Dienst ist stundenlang nicht erreichbar. Mit zwei netcup-Servern, einem Cloud vLAN und einer Failover-IPv4 beheben Sie diesen Engpass. Typische Ausfallzeit: unter 20 Sekunden, ohne proprietäre Cluster-Software.

Voraussetzungen

1. Zwei netcup VPS oder Root-Server im selben Rechenzentrum (z. B. Nürnberg), standortübergreifende Failover-IPs werden nicht angeboten
2. Debian 12 oder Ubuntu 24.04 (root-Zugang per SSH auf beiden Knoten)
3. Eine bestellte Failover-IPv4 aus dem netcup CCP (Erweiterungen für KVM-Server)
4. Ein bestelltes Cloud vLAN Free 100 Mbit/s aus dem netcup CCP, beiden Servern zugewiesen
5. Einen Refresh-Token für die SCP REST API (Menüpunkt „API“ in der oberen Leiste des SCP)
6. Pro Knoten 1 vCPU und 1 GB RAM (keepalived selbst benötigt nur wenige MB), curl und python3 installiert

Schritt 1: Failover-IP und Cloud-vLAN im CCP/SCP bestellen

Beide Erweiterungen müssen im selben Rechenzentrum wie Ihre VPS liegen; ein nachträglicher Umzug ist nicht möglich. Legen Sie deshalb zuerst den Standort der Server fest.

1. Rufen Sie https://www.customercontrolpanel.de auf und melden Sie sich an.
2. Navigieren Sie zu Meine Bestellungen → Erweiterungen für KVM-Server → Failover IPv4 und schließen Sie die Bestellung ab.
3. Wechseln Sie ins Server Control Panel (SCP) unter https://www.servercontrolpanel.de, öffnen Sie Server 1 und weisen Sie dort unter Netzwerk → Failover-IP die neue IP der primären Netzwerkkarte zu.
4. Zurück im CCP: Bestellen Sie unter Erweiterungen → Cloud vLAN Free 100 Mbit/s das VLAN-Produkt. Weisen Sie es beiden Servern zu. Das VLAN erscheint anschließend auf jedem Knoten als zweite Netzwerkkarte (meist eth1 oder ens7, je nach Image).

Verifizieren: Führen Sie auf beiden Servern ip link show aus. Sie sehen mindestens zwei Interfaces: eth0 (öffentlich) und eth1 (VLAN, noch ohne IP-Adresse).

Schritt 2: eth1-Interface im Cloud-vLAN konfigurieren

Beide Server erhalten statische private Adressen im VLAN-Subnetz. Sie können ein beliebiges privates Subnetz nach RFC 1918 verwenden; das Beispiel nutzt 10.132.0.0/24.

Server 1, /etc/network/interfaces.d/vlan.cfg

auto eth1
iface eth1 inet static
    address 10.132.0.10
    netmask 255.255.255.0

Server 2, /etc/network/interfaces.d/vlan.cfg

auto eth1
iface eth1 inet static
    address 10.132.0.20
    netmask 255.255.255.0
sudo systemctl restart networking
ip addr show eth1   # Zuweisung prüfen

Verifizieren: ping -c3 10.132.0.20 von Server 1 aus muss drei erfolgreiche Antworten liefern. Kein Ping? Prüfen Sie, ob das Cloud vLAN im SCP wirklich beiden Servern zugewiesen ist.

Schritt 3: IPv4-Forwarding aktivieren

Schalten Sie IP-Forwarding auf beiden Servern ein, damit der aktive Knoten Pakete für die Failover-IP weiterleitet.

echo "net.ipv4.ip_forward = 1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Verifizieren: sysctl net.ipv4.ip_forward gibt net.ipv4.ip_forward = 1 aus.

Schritt 4: keepalived installieren

sudo apt update && sudo apt install -y keepalived

Verifizieren: keepalived --version gibt auf beiden Servern eine Versionsnummer aus.

Schritt 5: keepalived konfigurieren

Die VRRP-Instanz läuft ausschließlich über eth1 (das private VLAN). Würde sie auf eth0 laufen, würden VRRP-Multicast-Pakete ins öffentliche Internet gesendet. Das stört andere netcup-Kunden und kann zur Sperrung des Servers führen.

Die virtuelle IP 10.132.0.100 ist eine interne Cluster-IP im VLAN, nicht die öffentliche Failover-IP.

Server 1, /etc/keepalived/keepalived.conf (MASTER)

vrrp_instance VI_1 {
    state MASTER
    interface eth1
    virtual_router_id 101
    priority 255
    advert_int 2
    authentication {
        auth_type PASS
        auth_pass GEHEIMES_PASSWORT
    }
    virtual_ipaddress {
        10.132.0.100
    }
    notify_master /etc/keepalived/scripts/to_master.sh
    notify_backup /etc/keepalived/scripts/to_backup.sh
    notify_fault  /etc/keepalived/scripts/to_backup.sh
}

Server 2, /etc/keepalived/keepalived.conf (BACKUP)

vrrp_instance VI_1 {
    state BACKUP
    interface eth1
    virtual_router_id 101
    priority 254
    advert_int 2
    authentication {
        auth_type PASS
        auth_pass GEHEIMES_PASSWORT
    }
    virtual_ipaddress {
        10.132.0.100
    }
    notify_master /etc/keepalived/scripts/to_master.sh
    notify_backup /etc/keepalived/scripts/to_backup.sh
    notify_fault  /etc/keepalived/scripts/to_backup.sh
}

Wichtige Parameter im Überblick:

Nach drei ausgebliebenen Heartbeats (ca. 6 Sekunden bei advert_int 2) stuft der BACKUP-Knoten den MASTER als ausgefallen ein und übernimmt die Rolle.

Verifizieren: sudo keepalived -t -f /etc/keepalived/keepalived.conf meldet auf beiden Servern keine Syntaxfehler (Exit-Code 0).

Schritt 6: netcup REST-API-Token einrichten

Die SCP REST API ersetzt den abgekündigten SOAP-Webservice. Sie authentifizieren sich per OAuth2 über den Keycloak-Server des SCP: Aus einem langlebigen Refresh-Token erzeugt das Skript bei jedem Lauf einen Access-Token, der 5 Minuten gilt. Wie Sie den Refresh-Token einmalig abrufen, beschreibt die Anleitung netcup SCP REST API einrichten; die offizielle Beschreibung finden Sie im SCP unter API → REST API Dokumentation → Authentication. Speichern Sie den Token auf beiden Servern an einem Ort, den keepalived als root liest:

# Refresh-Token dauerhaft speichern (einmalig, als root)
echo 'IHR_REFRESH_TOKEN' | sudo tee /etc/keepalived/netcup_refresh_token > /dev/null
sudo chmod 600 /etc/keepalived/netcup_refresh_token

# Access-Token testweise abrufen
BEARER=$(curl -s -X POST \
  "https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect/token" \
  -d 'client_id=scp' -d 'grant_type=refresh_token' \
  -d "refresh_token=$(sudo cat /etc/keepalived/netcup_refresh_token)" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
echo "Token OK: ${BEARER:0:20}..."

Ermitteln Sie anschließend Ihre SCP-User-ID (nicht die CCP-Kundennummer), die ID der Failover-IP und die numerischen Server-IDs beider Knoten:

# SCP-User-ID (Feld "id")
curl -s "https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect/userinfo" \
  -H "Authorization: Bearer ${BEARER}" | python3 -m json.tool
USER_ID="IHRE_USER_ID"

# Alle Failover-IPs auflisten
curl -s "https://www.servercontrolpanel.de/scp-core/api/v1/users/${USER_ID}/failoverips/v4" \
  -H "Authorization: Bearer ${BEARER}" | python3 -m json.tool

# Server-IDs auflisten
curl -s "https://www.servercontrolpanel.de/scp-core/api/v1/servers" \
  -H "Authorization: Bearer ${BEARER}" | python3 -m json.tool

Achtung: Die USER_ID ist eine interne numerische ID des SCP und unterscheidet sich von Ihrer CCP-Kundennummer. Eine falsche ID führt zu HTTP 403 oder 404.

Verifizieren: Die Liste der Failover-IPs enthält Ihre bestellte IPv4 mit einer numerischen id, die Serverliste beide Knoten mit ihrer numerischen id.

Schritt 7: Failover-Skript anlegen

Das Skript to_master.sh wird von keepalived als root aufgerufen, sobald ein Knoten die MASTER-Rolle übernimmt. Es holt sich einen frischen Bearer-Token und leitet die Failover-IP per PATCH-Request auf diesen Server um. Die API antwortet mit HTTP 202 und startet einen Task. Das Rate-Limit liegt laut OpenAPI-Spezifikation des SCP bei 10 Umschaltungen pro 5 Minuten und 20 pro 60 Minuten (sonst HTTP 429); die Retry-Logik fängt kurze Fehler ab.

sudo mkdir -p /etc/keepalived/scripts

/etc/keepalived/scripts/to_master.sh

#!/bin/bash
# netcup Failover per SCP REST API
# Variablen anpassen:
USER_ID="IHRE_USER_ID"
REFRESH_TOKEN_FILE="/etc/keepalived/netcup_refresh_token"
FAILOVER_IP_ID="ID_DER_FAILOVER_IP"
TARGET_SERVER_ID="ID_DIESES_SERVERS"
API_BASE="https://www.servercontrolpanel.de/scp-core/api/v1"
TOKEN_URL="https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect/token"
MAX_RETRIES=10
RETRY_INTERVAL=5

get_bearer() {
  curl -s -X POST "${TOKEN_URL}" -d 'client_id=scp' -d 'grant_type=refresh_token' \
    -d "refresh_token=$(cat ${REFRESH_TOKEN_FILE})" \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])"
}

BEARER=$(get_bearer)

for i in $(seq 1 ${MAX_RETRIES}); do
  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
    -X PATCH "${API_BASE}/users/${USER_ID}/failoverips/v4/${FAILOVER_IP_ID}" \
    -H "Authorization: Bearer ${BEARER}" \
    -H "Content-Type: application/json" \
    -d "{\"serverId\": ${TARGET_SERVER_ID}}")
  if [ "$HTTP_CODE" == "202" ]; then
    echo "[$(date)] Failover erfolgreich (Versuch ${i})" >> /var/log/keepalived-failover.log
    # Failover-IP lokal als Interface-Alias einbinden
    ip addr add FAILOVER_IP/32 dev eth0 label eth0:1 2>/dev/null || true
    exit 0
  fi
  echo "[$(date)] Versuch ${i} fehlgeschlagen (HTTP ${HTTP_CODE}), warte ${RETRY_INTERVAL}s" \
    >> /var/log/keepalived-failover.log
  sleep ${RETRY_INTERVAL}
done
echo "[$(date)] Failover nach ${MAX_RETRIES} Versuchen fehlgeschlagen!" \
  >> /var/log/keepalived-failover.log
exit 1

Legen Sie außerdem eine leere to_backup.sh an (keepalived erwartet sie) und setzen Sie die Berechtigungen:

sudo touch /etc/keepalived/scripts/to_backup.sh
sudo chmod +x /etc/keepalived/scripts/to_master.sh
sudo chmod +x /etc/keepalived/scripts/to_backup.sh
sudo chown root:root /etc/keepalived/scripts/*.sh

Ersetzen Sie in to_master.sh den Platzhalter FAILOVER_IP durch die öffentliche IP-Adresse und ID_DIESES_SERVERS durch die numerische Server-ID des jeweiligen Knotens. Das ip addr add ist entscheidend: Die API-Weiterleitung allein reicht nicht, der neue MASTER muss die IP auch lokal als Interface-Alias einbinden, sonst beantwortet er keine Pakete für diese Adresse.

Verifizieren: ls -l /etc/keepalived/scripts/ zeigt beide Skripte mit Eigentümer root und Rechten -rwx; bash -n /etc/keepalived/scripts/to_master.sh meldet keinen Syntaxfehler.

Schritt 8: keepalived starten und testen

# Auf beiden Servern:
sudo systemctl enable --now keepalived
sudo systemctl status keepalived

Prüfen Sie den VRRP-Verkehr auf dem VLAN-Interface:

sudo tcpdump proto 112 -i eth1 -n

Testen Sie den Failover kontrolliert, indem Sie keepalived auf Server 1 anhalten:

# Auf Server 1:
sudo systemctl stop keepalived
# Server 2 sollte nach ca. 6 Sekunden MASTER werden und das Skript aufrufen

# Ergebnis auf Server 2 prüfen:
ip addr show eth0                      # Failover-IP sollte als eth0:1 erscheinen
cat /var/log/keepalived-failover.log   # Skript-Protokoll

Verifizieren: Nach dem Stoppen von keepalived auf Server 1 erscheint in /var/log/keepalived-failover.log auf Server 2 eine Zeile „Failover erfolgreich“, und ip addr show eth0 zeigt die Failover-IP als eth0:1. Ein curl -I http://FAILOVER_IP von einem externen Rechner muss den Dienst von Server 2 erreichen.

API-Schnittstellenvergleich: SOAP vs. REST

Cloud-vLAN-Produktübersicht

Troubleshooting / Typische Fehler

Keepalived sendet VRRP auf eth0 statt eth1

Prüfen Sie mit tcpdump proto 112 -i eth0: Erscheinen dort Pakete, läuft die VRRP-Instanz auf der falschen Schnittstelle. Korrigieren Sie interface eth1 in keepalived.conf und starten Sie den Dienst neu. VRRP auf der öffentlichen IP kann zur Sperrung durch netcup führen.

HTTP 403 oder 404 beim REST-API-Aufruf

Die USER_ID ist nicht die CCP-Kundennummer; fragen Sie sie über den Userinfo-Endpunkt ab (Schritt 6). HTTP 401 bedeutet einen ungültigen Token: Prüfen Sie, ob /etc/keepalived/netcup_refresh_token den aktuellen Refresh-Token enthält.

Failover-Skript wird nicht ausgeführt

Meist fehlt die Ausführberechtigung, oder das Skript gehört nicht root. Prüfen Sie ls -la /etc/keepalived/scripts/ und die Meldungen in journalctl -u keepalived.

Rate-Limit der REST API (HTTP 429)

Die API erlaubt 10 Umschaltungen pro 5 Minuten und 20 pro 60 Minuten. Flapping erreicht diese Grenze schnell. Erhöhen Sie advert_int auf 3 und setzen Sie nopreempt (erfordert state BACKUP auf beiden Knoten).

Failover-IP nach Umschwenkung nicht erreichbar

Prüfen Sie mit ip addr show eth0, ob der Alias eth0:1 gesetzt ist. Fehlt er, ist das Skript vor ip addr add abgebrochen; die Ursache steht in /var/log/keepalived-failover.log.

SOAP-Skript nach dem 1. Mai 2026

Ein Skript mit changeIPRouting und Webservice-Passwort schwenkt die IP nach der Abschaltung nicht mehr. Stellen Sie es wie in Schritt 6 und 7 auf die REST API um; das Webservice-Passwort funktioniert dort nicht.

Häufige Fragen

Kann ich die Failover-IP zwischen Servern in verschiedenen Städten schwenken?

Nein. netcup bietet keine standortübergreifenden Failover-IPs. Beide VPS und die Failover-IP müssen am selben Standort liegen; sonst antwortet die API mit HTTP 400.

Was passiert, wenn Server 1 zurückkommt (Revert)?

keepalived arbeitet standardmäßig „preemptive“: Server 1 (priority 255) übernimmt nach seiner Rückkehr die MASTER-Rolle, sein notify_master-Skript leitet die IP zurück. Wollen Sie das verhindern, setzen Sie auf beiden Knoten state BACKUP und nopreempt.

Wie lange dauert der automatische Failover?

Bei advert_int 2 erkennt der BACKUP nach ca. 6 Sekunden (3 ausgebliebene Pakete) den Ausfall. Mit Token-Abruf, API-Aufruf und Umschalt-Task liegt die Ausfallzeit typischerweise bei 10 bis 20 Sekunden.

Brauche ich das Cloud-vLAN zwingend?

Ja. Über eth0 wären die VRRP-Pakete öffentlich sichtbar, was zur Sperrung durch netcup führen kann.

Kann ich das SOAP-Skript weiter nutzen?

Nein. netcup hat den SOAP-Webservice zum 1. Mai 2026 abgekündigt. Verwenden Sie für neue und bestehende Cluster ausschließlich die REST API aus Schritt 6 und 7.

Fazit

keepalived, Cloud vLAN und SCP REST API ergeben einen HA-Cluster aus zwei netcup-VPS, der in rund 90 Minuten steht. Die wichtigsten Stolperfallen: SCP-User-ID und Kundennummer verwechselt, fehlende Ausführungsrechte am Skript und das vergessene ip addr add für den Interface-Alias.

Weiterführende Anleitungen und Quellen

1. Linux-Server absichern mit ufw und Fail2ban
2. Docker Compose unter Linux: Grundlage für Selfhosting
3. netcup SCP REST API einrichten und nutzen: Server automatisieren ohne SOAP
4. netcup Cloud VLAN einrichten: Private Server-Kommunikation ohne öffentliche IP
5. netcup Failover-IP: Bestellung, SCP-Zuweisung und Server-zu-Server-Wechsel
6. VPS absichern und härten: Anleitung mit UFW, SSH-Keys und Fail2Ban (Hetzner/Netcup)
7. netcup Helpcenter: REST API (Server Control Panel)
8. netcup Helpcenter: Adding IP Addresses / Failover IP
9. netcup Community Tutorial: High Availability Cluster with Keepalived and Failover IPv4