KeyHelp: System-Domain-Schema und Hostname nutzen, um Websites vor der DNS-Umstellung zu testen

Wer eine Website auf einen KeyHelp-Server umzieht, möchte sie prüfen, bevor die Domain auf den neuen Server zeigt. Dafür gibt es zwei Wege: die System-Domain, die KeyHelp für jeden Kunden unter dem Hostnamen des Servers anlegt, und einen Eintrag in der hosts-Datei des eigenen Rechners. Diese Anleitung zeigt, wie Sie das System-Domain-Schema anpassen, was KeyHelp dabei technisch anlegt, welche DNS-Voraussetzung von außen gilt und wie Sie eine Website unter ihrer echten Domain testen, ohne den DNS anzufassen. Sie richtet sich an Administratoren eines Servers, der wie in KeyHelp installieren und absichern eingerichtet ist. Getestet haben wir mit KeyHelp 26.1.1 auf Debian 12.

Voraussetzungen

• Admin-Zugang zu KeyHelp. Getestet mit KeyHelp 26.1.1 (Build 3698) auf Debian 12.
• Ein gültiger Hostname, unter dem das Panel läuft, im Beispiel server.example.de. Er ist die Basis jeder System-Domain.
• Zugang zum DNS der übergeordneten Domain (hier example.de), wenn System-Domains aus dem Internet erreichbar sein sollen.
• Admin-Rechte auf dem eigenen Rechner, um die hosts-Datei zu bearbeiten.
• Wie Sie Kunden anlegen, steht in KeyHelp: Kunden anlegen und Kontingente festlegen.

Schritt 1: Das System-Domain-Schema prüfen und anpassen

Öffnen Sie im Admin-Bereich „Konfiguration“ und dort „System-Domain-Schema“. Das Feld ist ein Pflichtfeld, ab Werk steht darin <USERNAME>.<PANEL_DOMAIN>. Der Hinweistext nennt die beiden Platzhalter: <USERNAME> wird durch den Benutzernamen ersetzt, <PANEL_DOMAIN> durch die Panel-Domain, also den Hostnamen.

Für den Test haben wir das Schema auf <USERNAME>.vorschau.<PANEL_DOMAIN> geändert. So sind Vorschau-Adressen auf den ersten Blick von echten Diensten des Servers zu unterscheiden. Sie können auch eine ganz andere Domain verwenden, etwa <USERNAME>.vorschau-domain.de, wenn Sie den Hostnamen nicht in Kundenadressen zeigen möchten. Dann muss diese Domain aber auf den Server zeigen, siehe Schritt 3.

Nach „Speichern“ meldet KeyHelp „Die Einstellungen wurden aktualisiert.“ Wichtig: Das neue Schema gilt nur für Kunden, die Sie ab jetzt anlegen. Die bestehende System-Domain kunde1.server.example.de blieb im Test unverändert.

Verifizieren: Öffnen Sie „Benutzerverwaltung“, „Kunde hinzufügen“. Bei „System-Domain erstellen?“ steht nun „Erstellt die System-Domain nach folgendem Schema: <BENUTZERNAME>.vorschau.server.example.de“.

Schritt 2: Kunden mit System-Domain anlegen

Beim Anlegen eines Kunden ist „System-Domain erstellen?“ ab Werk mit „Ja“ angehakt. Wir haben den Kunden kunde2 (Erika Musterfrau) mit dieser Option angelegt. KeyHelp meldete „Der Benutzer kunde2 wurde erfolgreich angelegt. In wenigen Augenblicken kann das Konto benutzt werden.“ Eine Minute später gab es:

• den Eintrag kunde2.vorschau.server.example.de unter „Domains“, Besitzer kunde2, Ziel /home/users/kunde2/www/,
• eine eigene DNS-Zone /etc/bind/keyhelp_domains/kunde2.vorschau.server.example.de mit A-Einträgen für den Namen selbst und den Platzhalter *,
• einen eigenen VirtualHost in /etc/apache2/keyhelp/vhosts/kunde2.conf.

Technisch ist die System-Domain also eine ganz normale Hauptdomain. Sie lässt sich bearbeiten, mit einem Zertifikat versehen oder löschen. Für E-Mail ist sie nicht gedacht: In der Datenbank stand sie im Test mit is_email_domain = 0, anders als die echten Kundendomains.

Danach haben wir für kunde2 die echte Domain kunde2.example.de mit www-Subdomain und demselben Verzeichnis / angelegt, aber mit „DNS deaktivieren“, weil das DNS dieser Domain noch beim bisherigen Anbieter liegt. Ohne Änderung schlägt KeyHelp als Verzeichnis übrigens /kunde2.example.de/ vor, für eine gemeinsame Vorschau muss es auf / stehen.

Verifizieren: Eine Testdatei im Webverzeichnis liefert unter allen Namen dieselbe Ausgabe:

curl -s -H "Host: kunde2.vorschau.server.example.de" http://127.0.0.1/test.php
Neue Website kunde2.vorschau.server.example.de PHP 8.2.33
curl -s -H "Host: kunde2.example.de" http://127.0.0.1/test.php
Neue Website kunde2.example.de PHP 8.2.33

Schritt 3: System-Domains im DNS erreichbar machen

Hier liegt die häufigste Hürde. KeyHelp schreibt zwar Zonen für den Hostnamen und jede System-Domain in den lokalen BIND, und im Test beantwortete der Server Anfragen für kunde2.vorschau.server.example.de korrekt mit seiner IP. Der Rest des Internets fragt aber nicht Ihren Server, sondern die Nameserver der übergeordneten Domain example.de. Dort muss stehen, wo server.example.de und alles darunter zu finden ist.

Am einfachsten ist ein Wildcard-Eintrag beim DNS-Anbieter von example.de:

server.example.de.     3600  IN  A  203.0.113.10
*.server.example.de.   3600  IN  A  203.0.113.10

Der Platzhalter deckt auch die zusätzliche Ebene ab, im Test lösten kunde2.vorschau.server.example.de und sogar foo.kunde2.vorschau.server.example.de lokal auf die Server-IP auf. Ein einzelner Eintrag pro System-Domain funktioniert ebenfalls, muss dann aber für jeden neuen Kunden gepflegt werden.

Verifizieren: Von einem Rechner außerhalb des Servers muss dig +short kunde2.vorschau.server.example.de die IP des KeyHelp-Servers liefern. Lokal auf dem Server prüfen Sie die BIND-Antwort mit dig +short @IP-DES-SERVERS kunde2.vorschau.server.example.de. Das Paket bind9-dnsutils war im Test nicht vorinstalliert.

Schritt 4: Unter der System-Domain testen und die Grenzen kennen

Unter der System-Domain können Sie Dateien, PHP-Version und Datenbankverbindung prüfen, bevor die echte Domain umzieht. Zwei Grenzen sollten Sie kennen:

• HTTPS: Ohne Zertifikat leitete KeyHelp im Test HTTPS-Aufrufe der System-Domain mit 302 auf http:// um. Für einen Test mit HTTPS weisen Sie der System-Domain im Reiter „Sicherheit“ ein Zertifikat zu. Let's Encrypt funktioniert nur, wenn sie aus dem Internet erreichbar ist, siehe KeyHelp: SSL-Zertifikate einrichten.
• Anwendungen mit fester Adresse: CMS wie WordPress speichern ihre URL in der Datenbank und leiten auf diese um. Eine System-Domain zeigt dann nur die Umleitung. Für solche Anwendungen ist Schritt 5 der bessere Weg.

Unterhalb einer System-Domain können Sie weitere Vorschau-Adressen anlegen. Im Test legte KeyHelp neu.kunde1.server.example.de als eigene Hauptdomain mit Ziel /neu/ an, mit eigener Zone. So lässt sich für einen Relaunch eine zweite Vorschau neben der laufenden Website einrichten.

Alternativ wählen Sie beim Anlegen „Subdomain“ statt „Hauptdomain“: In der Auswahl der übergeordneten Domain bot KeyHelp für kunde2 neben kunde2.example.de auch kunde2.vorschau.server.example.de an. Subdomains erhalten in KeyHelp keine eigene Zone, im Test etwa www.kunde1.example.de. Sie werden über den Platzhalter * der übergeordneten Zone aufgelöst. Das hält die Zahl der Zonen klein, wenn Sie viele Vorschauen anlegen.

Verifizieren: curl -sI http://kunde2.vorschau.server.example.de/ liefert 200, im Browser erscheint der Inhalt des Webverzeichnisses.

Schritt 5: Die echte Domain per hosts-Datei testen

Für Anwendungen mit fest eingetragener Adresse testen Sie die echte Domain, ohne den DNS zu ändern. Tragen Sie dazu auf Ihrem eigenen Rechner die Server-IP für die Domain ein:

• Linux und macOS: /etc/hosts, mit sudo bearbeiten.
• Windows: C:\Windows\System32\drivers\etc\hosts, Editor als Administrator starten.

203.0.113.10  kunde2.example.de www.kunde2.example.de

Ab jetzt ruft nur Ihr Rechner die Domain auf dem neuen Server ab, alle anderen Besucher landen weiter auf dem alten. Dafür muss die Domain in KeyHelp angelegt sein, wie in Schritt 2. Mit curl erreichen Sie dasselbe ohne hosts-Datei:

curl -s --resolve kunde2.example.de:80:203.0.113.10 http://kunde2.example.de/

Im Test lieferte dieser Aufruf 200 und den Inhalt von kunde2, obwohl die Domain im DNS noch nicht auf den Server zeigte. Entfernen Sie den hosts-Eintrag nach dem Test wieder, sonst sehen Sie später Änderungen am DNS nicht.

Verifizieren: ping kunde2.example.de zeigt auf Ihrem Rechner die IP des neuen Servers. Erst wenn hier alles passt, stellen Sie den DNS um, idealerweise nach vorher gesenkter TTL, wie in KeyHelp: DNS-Editor, Einträge und TTL beschrieben.

Typische Fehler

• System-Domain ist von außen nicht erreichbar: Es fehlt der Wildcard-Eintrag beim DNS-Anbieter der übergeordneten Domain. Lokal beim Server klappt die Abfrage trotzdem, das täuscht.
• Neues Schema greift nicht: Es gilt nur für neue Kunden. Bestehende System-Domains behalten ihren Namen.
• Vorschau zeigt eine leere Seite statt der Website: Die echte Domain zeigt auf ein anderes Verzeichnis als die System-Domain, etwa den vorgeschlagenen Ordner /kunde2.example.de/.
• HTTPS springt auf HTTP zurück: Die System-Domain hat kein Zertifikat.
• Website leitet auf die alte Adresse um: Die Anwendung hat ihre URL gespeichert. hosts-Datei statt System-Domain verwenden.

Häufige Fragen

Kann ich die System-Domain eines bestehenden Kunden umbenennen?

Nicht über das Schema. Im Formular „Domain bearbeiten“ ist der Domainname nicht änderbar. Legen Sie die neue Vorschau-Adresse als zusätzliche Domain an und löschen Sie die alte bei Bedarf.

Was passiert mit System-Domains, wenn ich den Hostnamen ändere?

Der Hinweistext unter „Konfiguration“, „Hostname“ kündigt an, dass KeyHelp dabei Konfigurationsdateien ändert, ein Backup unter /home/keyhelp/keyhelp.backup/before_hostname_change/ anlegt und bei externer DNS-Verwaltung die DKIM-Einträge der Panel-Domain und der System-Domains ändert. Den Hostnamenwechsel selbst haben wir nicht getestet.

Brauche ich die System-Domain überhaupt?

Nein. Wer Vorschauen nur per hosts-Datei macht, kann „System-Domain erstellen?“ beim Anlegen abwählen. Dann gibt es pro Kunde keine zusätzliche Adresse, unter der seine Website erreichbar ist.

Testumfang

Wir haben auf KeyHelp 26.1.1 das System-Domain-Schema geändert, einen Kunden mit System-Domain und echter Domain angelegt, eine weitere Vorschau unter einer System-Domain eingerichtet und die Auslieferung mit curl sowie die Zonen mit dig gegen den lokalen BIND geprüft. Auffällig: Ein neues Schema ändert bestehende System-Domains nicht. Die Auflösung aus dem Internet und einen Hostnamenwechsel haben wir nicht geprüft. Testen Sie Vorschau-Adressen immer von außen.

Fazit

System-Domains sind in KeyHelp vollwertige Domains und damit ein bequemer Weg, Websites vor dem Umzug zu zeigen, vorausgesetzt der Hostname hat einen Wildcard-Eintrag im DNS. Ein eigenes Schema mit einer Ebene wie vorschau macht die Adressen eindeutig. Für Anwendungen, die auf ihrer echten Adresse bestehen, bleibt die hosts-Datei der zuverlässigste Test vor der DNS-Umstellung.

Weiterführende Anleitungen und Quellen

• KeyHelp installieren und absichern: das kostenlose Hosting-Panel für eigene Server
• KeyHelp: Kunden anlegen und Kontingente festlegen
• KeyHelp: DNS-Editor nutzen, Einträge und TTL pflegen
• KeyHelp: Domains und Subdomains anlegen
• KeyHelp-Handbuch für Administratoren (Version 17, PDF)
• Keyweb: KeyHelp, alle Funktionen im Überblick