Dieses Handbuch beschreibt, wie Sie den HQbird-Replikationscluster installieren und nutzen:
die Knoten hqclusternode und den Cluster-Manager hqbirdrcm (RCM).
Es ist ein Handbuch für den Firebird-Administrator. Wir setzen voraus, dass Sie Firebird,
gfix und nbackup kennen. Den inneren Aufbau eines Knotens müssen Sie nicht kennen.
stoppt und startet Firebird auf Anforderung eines Knotens
hqclusternode (Knoten)
einer je Instanz und Rolle
neben Firebird
richtet die Replikation ein, überträgt Segmente, führt die Initialisierung der Replik aus
hqbirdrcm (RCM)
einer je Cluster
auf jedem Host, der alle Knoten sieht
Weboberfläche, Befehle, Warnungen, Statistiken
Ein Knoten hat eine Rolle: master oder replica. Auf einer
Firebird-Instanz können zwei Knoten laufen: ein Master-Knoten und ein Replik-Knoten.
Dann sind einige Datenbanken dieses Firebird Master und andere Repliken.
So funktioniert es
Auf dem Master schreibt Firebird Datenbankänderungen in Segmente (Dateien des
Replikationsprotokolls).
Der Master-Knoten sendet die Segmente über einen gesicherten Kanal (mTLS) an den Replik-Knoten.
Der Replik-Knoten legt die Segmente in den Ordner der eingehenden Segmente. Das Firebird der Replik
wendet sie auf seine Kopie der Datenbank an.
Der Master-Knoten selbst überträgt die erste Kopie der Datenbank an die Replik. Das heißt
Initialisierung (reinit). Sie läuft über nbackup, und der Master läuft in dieser Zeit
weiter.
Die Knoten senden Statistiken an RCM. RCM zeigt den Zustand des Clusters und
sendet Operatorbefehle an die Knoten.
So funktioniert der Cluster: Segmente, Initialisierung, Statistiken und Operatorbefehle
Unterstützte Versionen
Firebird / HQbird 5.0 und 4.0 — alle Funktionen.
HQbird 3.0 und 2.5 — Replikation über das Plugin replconf. Es gibt keine Publikationen;
die Tabellenmenge wird durch Filter bestimmt. Die Unterschiede stehen in den Kästen „HQbird 2.5/3.0“.
Die Hauptversion von Firebird auf dem Master und auf der Replik muss übereinstimmen. Sonst lehnt der
Replik-Knoten die Initialisierung ab.
Ports
Port
Wer lauscht
Wer verbindet sich
Wozu
7051
Knoten
andere Knoten und RCM
Knoten-API, Übertragung von Segmenten und Datenbankkopien
7443
RCM
alle Knoten
Empfang der Statistiken von den Knoten
7444
RCM
Operator
Weboberfläche und Operator-API. Installation über RCM (Kapitel 1.3): HTTPS auf allen Adressen. Installation über HQCenter Admin oder von Hand: HTTP, nur 127.0.0.1
7450–7459
fbagent, solange das Verknüpfungsfenster offen ist
RCM
Hosts verknüpfen (Kapitel 1.3)
13050
fbagent, nur 127.0.0.1
Knoten auf demselben Host
Firebird-Verwaltung
3050
Firebird
Anwendungen
normaler Datenbankbetrieb
Laufen auf einem Host zwei Knoten (Master und Replik), hat der zweite Knoten einen anderen Port.
Bei der Installation über RCM erhält der zweite Knoten den Port 7061. In den anderen Fällen
setzen Sie den Port selbst, zum Beispiel 7052.
Port 13050 darf nicht ins Netz offen sein. Port 7444 mit HTTP (Installation über
HQCenter Admin oder von Hand) ebenfalls nicht: verbinden Sie sich mit der RCM-Weboberfläche
über einen SSH-Tunnel (Kapitel 1). Bei der Installation über RCM läuft Port 7444 über
HTTPS, und das Installationsprogramm öffnet ihn in der Firewall.
Die Hauptregel: kein fbagent, keine Änderungen
Ein Knoten ändert die Replikationskonfiguration nur über fbagent: er muss
Firebird neu starten. Ist fbagent nicht erreichbar, lehnt der Knoten jede Aktion ab,
die die Konfiguration ändert. Er arbeitet nicht „zur Hälfte“.
Begriffe
Begriff
Bedeutung
Segment
eine Replikationsprotokolldatei mit Datenbankänderungen
Publikation
die Liste der Master-Tabellen, deren Änderungen in die Segmente gehen (Firebird 4/5)
Initialisierung (reinit)
Übertragung einer Kopie der Datenbank vom Master zur Replik über nbackup
Datenbank-GUID
der Firebird-Bezeichner der Datenbank; RCM verknüpft damit Master und Replik
Partner
Partnerknoten: für einen Master seine Repliken
Begleiter
der zweite Knoten auf derselben Firebird-Instanz (Master und Replik auf einem Host)
Normal machen, Zum Master befördern, neue GUID, Dienste (Umschaltung, Failover), Checkliste der Umschaltung
Alle Kapitel verwenden ein Beispiel:
Was
Wert
node-a
Master-Knoten, Datenbanken in /databases/master
node-b
Replik-Knoten, Datenbanken in /databases/replica
RCM
ein eigener Host (kann auch einer der Datenbankserver sein)
Datenbank
employee.fdb
1. Knoten und hqbirdrcm installieren
Es gibt drei Installationswege:
Weg
Wann Sie ihn wählen
Was Sie selbst tun
Über HQCenter Admin (1.2)
der übliche Weg: der Aktualisierungsserver von HQCenter Admin ist erreichbar, automatische Aktualisierungen werden gebraucht
Sie starten das Installationsskript von fbagent, genehmigen die Anfrage, beschreiben den Cluster
Über RCM, ohne HQCenter Admin (1.3)
es gibt kein HQCenter Admin, aber Sie brauchen Zertifikate, Konfiguration und Aktualisierungen ohne Handarbeit; bis zu 3 Datenbankserver
Sie installieren HQbird auf jedem Host, melden sich bei RCM an und geben unter Einstellungen → Hosts verknüpfen die Hostadressen an
Von Hand (1.4)
kein Zugang zu HQCenter Admin, geschlossenes Netz, besondere Anforderungen
Sie installieren die Dateien, erstellen Zertifikate, schreiben node.json und rcm.json, registrieren die Dienste
Über HQCenter Admin und über RCM installieren Sie die Knoten und RCM nicht selbst. Sie werden von
fbagent installiert, wenn Sie ihn zum Cluster hinzufügen (Kapitel 2). Zertifikate und
Konfiguration entstehen ebenfalls automatisch.
Linux und Windows sind in einem Kapitel beschrieben. Die Windows-Unterschiede stehen in den
Kästen „Unter Windows“.
1.1. Anforderungen
Auf jedem Datenbankserver:
Firebird / HQbird 5.0, 4.0, 3.0 oder 2.5 (2.5 — nur Linux).
fbagent neben jeder Firebird-Instanz. Ohne fbagent arbeitet der Knoten nicht.
Zeitsynchronisation (NTP, chrony, w32time) auf allen Servern und auf dem
RCM-Host. Neustart- und Übertragungsfenster, die Schätzung der Verzögerung und
die Prüfung „Knoten antwortet nicht“ hängen von den Uhren ab.
Freier Platz für das Segmentarchiv und für die Initialisierung der Replik (Kapitel 4).
Windows: Administratorrechte, x64, Windows 10 / Server 2016 oder neuer,
64-Bit-Windows PowerShell 5.1. Unter Windows 10 und Server 2016–2022 ist 7-Zip erforderlich.
Wo RCM laufen wird. Je Cluster wird ein RCM gebraucht. Es kann auf jedem
Server installiert werden, der alle Knoten sieht, auch auf einem der Datenbankserver.
1.2. Installation über HQCenter Admin
Schritt 1. Das Installationsskript von fbagent ausführen
Das Skript installiert Firebird (den HQbird-Build), fbagent und registriert fbagent auf dem
HQCenter-Admin-Server. Wählen Sie das Skript passend zu Ihrer Firebird-Version: fb25, fb30, fb40,
fb50.
Linux (als root):
Command
sudo sh fbagent-fb50_known.sh --goafts <HQCenter-Admin-server> --enroll --cluster
Unter Windows gibt es den Parameter -Cluster nicht: fbagent läuft als
LocalSystem und legt die Clusterordner selbst an.
Die wichtigsten Parameter:
Linux
Windows
Bedeutung
--goafts <name>
-Goafts
HQCenter-Admin-Server, von dem heruntergeladen wird; den Namen nennt Ihr Lieferant
--enroll
-Enroll
fbagent bei HQCenter Admin registrieren (Zertifikatanforderung)
--cluster
—
die Ordner /opt/hqclusternode und /opt/hqbirdrcm anlegen (nur für fbagent 2.55.2 und älter nötig; bei neueren Versionen harmlos)
--channel
-Channel
Aktualisierungskanal von fbagent, standardmäßig stable
--token
-Token
Lizenz-Token: HQCenter Admin genehmigt die Anfrage automatisch
--port
-Port
Firebird-Port
--yes
-Yes
keine Fragen stellen (nötig, wenn kein Terminal vorhanden ist)
Die vollständige Parameterliste steht in der README des Installationsskripts von fbagent.
Schritt 2. Die fbagent-Anfrage genehmigen
Mit dem Parameter --enroll sendet fbagent eine Zertifikatanforderung (CSR) an HQCenter Admin und
wartet bis zu 30 Minuten auf die Genehmigung. Sie können sie so genehmigen:
automatisch — wenn die Installation mit einem Lizenz-Token (--token) lief und
die Lizenz einen freien Platz hat;
im HQCenter-Admin-Panel — der Bereich der CSR-Anfragen, die Anfrage
dieses Hosts, die Schaltfläche zum Genehmigen und Signieren;
über die HQCenter-Admin-API — POST /v1/admin/csr-requests/{id}/approve.
Wenn die Registrierung nicht gelang (zum Beispiel die Wartezeit ablief), arbeitet fbagent trotzdem,
aber das Skript endet mit Code 2. Führen Sie das Skript mit denselben
Parametern erneut aus: nur die Registrierung wird wiederholt.
Einige Minuten nach der Registrierung installiert fbagent HQ Monitor selbst.
Schritt 3. Den Cluster beschreiben
Knoten und RCM erscheinen, sobald Sie fbagent zum HQCenter-Admin-Cluster hinzufügen. Wie Sie den
Cluster beschreiben, steht in Kapitel 2.
Nach dem Speichern des Clusters:
Innerhalb von 10 Minuten erhält fbagent den Cluster von HQCenter Admin (danach prüft es
alle 60 Sekunden auf Änderungen).
Der fbagent auf dem RCM-Host erzeugt die Zertifizierungsstelle des Clusters (CA) und signiert
die Zertifikate aller Knoten.
Jeder fbagent schreibt node.json oder rcm.json für die Mitglieder
seines Clusters.
Bei der nächsten Produktprüfung (alle 3 Minuten) installiert und
startet fbagent die Dienste.
<port> ist der Firebird-Port, zum Beispiel 3050. Ein einzelner fbagent kann höchstens
einen Master-Knoten, einen Replik-Knoten, ein RCM und einen Router aufnehmen
(hqclusternode router, ab HQbird 2027.2.30, Kapitel 8.7).
Unter Windows. fbagent-Versionen vor 2.83.0 installierten die Knoten in C:\hqclusternode und
RCM in C:\hqbirdrcm. Wenn diese Ordner existieren, verwendet fbagent sie weiter.
Aktualisierungen
fbagent prüft alle 3 Minuten auf neue Versionen von Knoten und RCM; der Standardkanal
ist stable. Zuerst wird der Replik-Knoten aktualisiert, dann der Master-Knoten.
Wenn der Dienst nach einer Aktualisierung nicht startet oder die falsche Version meldet,
kehrt fbagent zur vorherigen Version zurück und blockiert die neue. Die Blockierliste:
<fbagent-Ordner>/update/<product>/blocked-versions.json. Um die
Version erneut zu versuchen, löschen Sie ihre Zeile aus dieser Datei.
Der Cluster wird von RCM verwaltet. Der fbagent jedes Hosts erhält die Clusterbeschreibung von RCM,
der fbagent auf dem RCM-Host signiert die Zertifikate, und Knoten und RCM werden aus
den von RCM gespeicherten Ausgaben aktualisiert.
Einschränkungen:
Ein Cluster je RCM.
Höchstens 3 Plätze. Ein Platz ist ein Host, auf dem ein Master- oder Replik-Knoten läuft.
Master und Replik auf demselben Host zählen als ein Platz. Ein Host, auf dem nur RCM läuft,
belegt keinen Platz. Ein vierter Host erzeugt den Fehler seats_exceeded.
RCM aktualisiert weder fbagent noch Firebird. fbagent aktualisiert sie selbst und rührt
replication.conf, node.json, rcm.json und die Zertifikate nicht an.
Es gibt zwei Wege:
Hosts in RCM verknüpfen — der übliche Weg. Drei Handlungen: das Installationsprogramm auf
jedem Host (RCM auf einem Host, Erkennungsmodus auf den anderen), Anmeldung bei
RCM, das Formular Hosts verknüpfen.
Von Hand über die Befehlszeile — Beitrittstoken und
fbagent --cluster-join. Nötig, wenn Port 7450 zwischen den Hosts geschlossen ist oder
das Kopplungsfenster schon geschlossen wurde.
Lizenz. Die Testlizenz enthält die Funktion cluster. Nach der Testzeit
installiert fbagent keinen Knoten und kein RCM, wenn der Lizenz cluster fehlt.
Aktualisierungen bereits installierter Knoten und von RCM blockiert es nie. Ohne
HQCenter Admin hört eine Floating-Lizenz nach online_check_days plus
Kulanz-Tagen auf zu arbeiten. Installieren Sie deshalb auf jedem fbagent eine gebundene Lizenz:
Command
fbagent --license-request --out license_request.json
# send the file to the vendor and receive license.jsonfbagent --license-install license.json
Ohne Lizenz hört der Master auf, Segmente zu senden (Kapitel 2.8).
Ports:
Port
Wo
Wer verbindet sich
7443
RCM-Host
fbagent und Knoten aller Cluster-Hosts
7444
RCM-Host
Browser des Operators (RCM-Konsole, HTTPS)
7450 (auf dem zweiten und den folgenden fbagent — 7451…7459)
Host im Erkennungsmodus, solange das Kopplungsfenster offen ist
RCM auf dem RCM-Host
7051 (zweiter Knoten desselben fbagent — 7061)
Knoten-Hosts
andere Knoten und RCM (1.4, Schritt 7)
Hosts in RCM verknüpfen
Beispiel von Grund auf. Zwei Linux-Server, das .run-Installationsprogramm, Verknüpfung,
Aufnahme, Publikation, Initialisierung und Neuinitialisierung unter Last — mit
Bildschirmfotos und Messungen: das Handbuch hqbird2027-linux-cluster-guide.ru.md und
das Runbook hqbird2027-linux-cluster-runbook.ru.md (Repository goafts, Ordner
Dokumentation).
Schritt 1. HQbird auf jedem Host installieren
Installieren Sie HQbird mit dem vollständigen Installationsprogramm auf jedem Datenbankserver. Registrieren Sie sich nicht bei
HQCenter Admin (--enroll).
Standardmäßig richtet das Installationsprogramm keinen Cluster ein. Es legt die Programme von Knoten
und RCM in den fbagent-Ordner (update/<product>/staged/), installiert aber kein RCM, öffnet das Kopplungsfenster
nicht und öffnet die Cluster-Ports in der Firewall nicht. Der Cluster
wird durch zwei Parameter eingeschaltet:
Command
sudo sh hqbird2027-fb50-linux-<version>.run --rcm on # RCM hostsudo sh hqbird2027-fb50-linux-<version>.run --cluster-pairing on # other hosts
--rcm on — auf einem Host, auf dem das RCM des Clusters laufen wird. Das Installationsprogramm:
erzeugt den Cluster dieses Hosts (fbagent --cluster-init); der Clustername ist der
Hostname;
installiert und startet RCM, die RCM-Konsole läuft über HTTPS auf Port 7444;
erzeugt den ersten RCM-Administrator rcmadmin mit einem Zufallskennwort;
öffnet die Ports 7443, 7444 und den Knoten-Port 7051 in der Firewall.
--cluster-pairing on (Erkennungsmodus) — auf jedem anderen Host.
Das Installationsprogramm öffnet das Kopplungsfenster von fbagent für 24 Stunden: Port 7450 und
Knoten-Port 7051. Solange das Fenster offen ist, kann ein RCM aus dem Netz diesen Host in
seinen Cluster einladen. fbagent beginnt innerhalb einer Minute, auf Port 7450 zu lauschen.
Ohne diese Parameter fragt das Installationsprogramm selbst: in der Text-
oberfläche ist das die Seite Cluster, mit --no-tui — zwei Fragen.
Die Standardantwort ist „nein“. --yes ohne Clusterparameter antwortet ebenfalls
„nein“ auf beide Fragen.
Am Ende gibt das Installationsprogramm die Zeilen RCM: und Pairing: aus. Auf dem RCM-Host:
text
RCM: https://10.0.0.7:7444 (cluster db1)
CA hash: sha256:7cfc1d4b…032d2582
Login: rcmadmin
Password: in /opt/hqbird/fbagent-fb50/clusterca/db1/rcm-initial-password (read it with sudo; RCM asks for a new one at the first login)
Pairing: not needed: this agent runs the RCM; other agents link through it
Auf einem anderen Host:
text
RCM: off; turn it on in HQbird Monitor or with fbagent --cluster-init <id>
Pairing: port 7450 open until 2026-11-17T17:49:18Z (fingerprint sha256:0439e44a…91a2f9b9); an RCM may invite this host
In der Ausgabe steht kein Kennwort: es liegt in der Datei aus der Zeile Password:. Notieren Sie
den fingerprint jedes Hosts im Erkennungsmodus.
Clusterparameter im Linux-Installationsprogramm:
Parameter
Was er tut
--rcm on|off
RCM installieren und auf diesem Host einen Cluster erzeugen; Standard off
--cluster-pairing on|off
Erkennungsmodus: das Kopplungsfenster für 24 Stunden öffnen; Standard off
--pairing-port N
Kopplungsport des neuen fbagent, 7450–7459; Standard der erste freie
--rcm-password-file F
Kennwort des RCM-Administrators aus der ersten Zeile der Datei F, statt eines zufälligen
--cluster-id ID
Clustername ID statt des Hostnamens (mit --rcm on)
--cluster-node on|off
das Knotenprogramm installieren; Standard on
--rcm-allow A,B
nur diese RCMs dürfen diesen Host einladen: Adresse, CIDR-Netz oder Name
Der erste fbagent eines Hosts erhält den Kopplungsport 7450 und die Knoten-Ports 7051 und
7061. Die zweite Instanz auf demselben Host — 7451, 7052 und 7062.
RCM und das Kopplungsfenster lassen sich später ohne das Installationsprogramm einschalten: in HQ Monitor,
die Seite Cluster, oder mit Befehlen als fbagent-Benutzer:
Command
cd <fbagent folder> # /opt/hqbird/fbagent-fb50sudo -u firebird ./fbagent --cluster-init <name> # RCM host; open ports 7443 and 7444 yourselfsudo -u firebird ./fbagent --cluster-pairing on # window for 24 hourssudo -u firebird ./fbagent --cluster-pairing off
sudo -u firebird ./fbagent --cluster-pairing status
Alte Installationsprogramme (fbagent vor 3.1.0) fragen nicht nach dem Cluster: sie
installieren RCM auf jedem Host und öffnen überall das Kopplungsfenster. Sie brauchen das RCM
eines Hosts; die RCMs der anderen Hosts stoppen sich nach der Verknüpfung selbst.
Unter Windows. Dieselben zwei Wahlmöglichkeiten gibt es im Windows-Installationsprogramm: die Parameter
/RCM und /DISCOVERY.
Schritt 2. Bei RCM anmelden
Öffnen Sie die Adresse aus der Zeile RCM: des RCM-Hosts (https://<host>:7444). Melden Sie sich mit
dem Anmeldenamen rcmadmin und dem Kennwort aus der Datei in der Zeile Password: an. RCM verlangt sofort ein
neues Kennwort (1.5).
Schritt 3. Die Hosts verknüpfen
Öffnen Sie in RCM Einstellungen → Hosts verknüpfen.
Geben Sie im Feld Hosts die Adressen oder Namen der Hosts ein, einen je Zeile.
Die erste Zeile ist der RCM-Host, er ist schon im Cluster.
Klicken Sie auf Hosts prüfen. RCM prüft die Kopplungsports
7450–7459 jedes Hosts und zeigt Plattform, Firebird-Version,
Fingerabdruck und Zustand. Der RCM-Host braucht kein Kopplungsfenster. Vergleichen Sie
die Fingerabdrücke mit der Ausgabe des Installationsprogramms (die Zeile Pairing:).
Wählen Sie den Master (standardmäßig der erste Host) und klicken Sie auf Verknüpfen.
Hosts verknüpfen: Prüfergebnis
RCM bittet um Bestätigung und zeigt den Fortschritt im Abschnitt Fortschritt. Wenn alle Knoten
laufen, sagt es „Fertig“ und zeigt die Revisionsnummer des Clusters:
Hosts verknüpfen: alle Knoten laufen
Dasselbe über die Befehlszeile:
Command
cd /opt/hqbirdrcm
exportRCM_USER=rcmadmin RCM_PASSWORD='<password>'./hqbirdrcm cluster link -hosts db1,db2,db3 -master db1
Was danach geschieht:
RCM sendet jedem freien Host eine Einladung.
Der fbagent des Hosts tritt dem Cluster bei und schließt den Kopplungsport. Hat der
Host ein eigenes RCM ohne Knoten, stoppt und deaktiviert fbagent es und
verschiebt den leeren Cluster nach cluster/left/ im fbagent-Ordner.
RCM speichert den Cluster: Knoten <host>-master auf dem Master, <host>-replica auf
den anderen Hosts, Port 7051, Verknüpfungen Master → Replik.
Der fbagent jedes Hosts installiert und startet den Knoten. RCM wartet, bis alle Knoten
laufen, und zeigt für jeden Host Läuft.
Hostzustände nach Hosts prüfen:
Zustand
Was zu tun ist
Bereit zum Verknüpfen
nichts. Steht darunter „Das eigene RCM dieses Hosts stoppt nach der Verknüpfung“ — das ist normal
Im Cluster
der Host ist schon in diesem Cluster
Fehler unreachable
Port 7450 ist geschlossen: das Kopplungsfenster ist aus (wie standardmäßig) oder die 24 Stunden sind vorbei. Warten Sie direkt nach der Installation eine Minute und klicken Sie erneut auf Hosts prüfen. Sonst öffnen Sie das Fenster (--cluster-pairing on) und prüfen Sie die Firewall
Fehler in_other_cluster
der Host ist in einem anderen Cluster
Fehler claimed
ein anderes RCM verknüpft diesen Host gerade
Fehler seats_exceeded
mehr als 3 Plätze
Ausgaben. fbagent installiert den Knoten nur von RCM. RCM nimmt signierte
Ausgaben aus seinem Ordner import/ (neben rcm.json) beim Start und alle
5 Minuten. Das Installationsprogramm legt dort die Ausgaben des RCM-Hosts ab, und die fbagents der anderen Hosts
laden die Ausgabe für ihre Plattform selbst herunter. Die Liste der Ausgaben steht unten auf der
Seite Hosts verknüpfen. Eine Ausgabe kann auch von Hand importiert werden (Schritt 5 unten).
Von Hand über die Befehlszeile
Reihenfolge: Schritte 1–3 auf dem RCM-Host, Schritt 4 auf jedem anderen Host, Schritte 5–6 in RCM.
Schritt 1. HQbird mit fbagent installieren
Installieren Sie HQbird auf jedem Datenbankserver und auf dem RCM-Host mit dem vollständigen Installationsprogramm.
Auf dem RCM-Host können Sie gleich --rcm on angeben (dann entfällt Schritt 3). Auf den anderen
Hosts geben Sie keine Clusterparameter an: standardmäßig gibt es kein RCM und kein Kopplungsfenster.
Registrieren Sie sich nicht bei HQCenter Admin (--enroll).
Auf dem RCM-Host lässt das Installationsprogramm das RCM-Programm im fbagent-Ordner
(update/hqbirdrcm/staged/). Ohne es schlägt Schritt 3 mit dem Fehler
no hqbirdrcm to install fehl.
Schritt 2. Die gebundene Lizenz installieren
Wie am Anfang des Abschnitts, „Lizenz“.
Schritt 3. Den Cluster auf dem RCM-Host erzeugen
Hat das Installationsprogramm den Cluster schon erzeugt (--rcm on: eine Zeile RCM: mit einer Adresse in der
Ausgabe), überspringen Sie diesen Schritt.
Führen Sie den Befehl als fbagent-Benutzer aus (unter Linux — firebird), nicht als
root: sonst gehören die CA-Dateien und rcm.json root.
Unter Windows (PowerShell als Administrator):
.\fbagent.exe --cluster-init shop-prod --address 10.0.0.7
shop-prod — Clustername: lateinische Kleinbuchstaben, Ziffern und -.
--address — die Adresse des RCM-Hosts, über die sich die anderen
Hosts mit ihm verbinden. Kann mehrfach wiederholt werden. Ohne den Parameter werden die Adressen und der Name des Hosts verwendet.
Der Befehl:
erzeugt die Cluster-CA und die Agent-CA (im fbagent-Ordner, clusterca/<name>/);
schreibt das RCM-Zertifikat, rcm.json und cluster-init.json in den RCM-Ordner;
installiert RCM und registriert den Dienst hqbirdrcm. Unter Linux läuft der Dienst als
eigener Benutzer hqbirdrcm;
schaltet fbagent auf RCM (cluster.source = rcm) und startet ihn neu;
gibt die RCM-Adresse und den CA-Fingerabdruck aus:
Code
Cluster: shop-prod
RCM URL: https://10.0.0.7:7443
CA hash: sha256:9f86d0...
Notieren Sie RCM URL und CA hash: sie werden auf den anderen Hosts gebraucht. Ein erneuter Lauf
für denselben Cluster ist ungefährlich: CA und Schlüssel bleiben gleich.
Melden Sie sich sofort bei RCM an und ändern Sie das Kennwort von rcmadmin (1.5).
Unter Linux. Der Benutzer hqbirdrcm ist in der fbagent-Gruppe. RCM liest
rcm.json über diese Gruppe, kann es aber nicht schreiben. Deshalb speichert Einstellungen → RCM keine Änderungen (Fehler
rcm_config_read_only). Bearbeiten Sie rcm.json auf dem Host als fbagent-Benutzer
und starten Sie RCM neu.
Schritt 4. Die fbagents der anderen Hosts verbinden
Erzeugen Sie auf dem RCM-Host für jeden fbagent ein Beitrittstoken: in RCM
Einstellungen → Cluster, die Schaltfläche Beitrittstoken erzeugen. Oder über
die Befehlszeile:
Command
cd /opt/hqbirdrcm
exportRCM_USER=rcmadmin RCM_PASSWORD='<password>'./hqbirdrcm cluster join-token -note db2
Das Token gilt 24 Stunden, nur für einen fbagent und nur einmal. RCM
zeigt es einmal, zusammen mit einem fertigen Befehl.
Führen Sie auf dem Knoten-Host diesen Befehl als fbagent-Benutzer aus:
Statt --token-file können Sie --token <token> verwenden. Unter Windows — dasselbe mit
.\fbagent.exe in PowerShell als Administrator.
fbagent prüft die RCM-CA am Fingerabdruck. Stimmt der Fingerabdruck nicht, hält es
an und schreibt nichts. Danach erhält fbagent sein Zertifikat
(90 Tage, wird automatisch erneuert) und startet neu. Ein verbundener fbagent ist in
RCM in der Tabelle Agenten sichtbar. Solange er keine Mitglieder hat, wird auf dem Host nichts installiert.
Schritt 5. Ausgaben in RCM importieren
fbagent nimmt Knoten und RCM nur von RCM. Steht die nötige Ausgabe nicht in der
Liste Ausgaben im Spiegel (Einstellungen → Hosts verknüpfen), importieren Sie jedes Produkt
(hqclusternode, hqbirdrcm) für jede Plattform Ihrer Hosts
(linux-amd64, windows-amd64). Die Ausgabedatei und die Signatur .sig liefert
der Anbieter.
RCM sucht die Signatur in <file>.sig, oder Sie geben sie mit -sig an. Ohne
gültige Anbietersignatur nimmt RCM die Datei nicht an.
Eine neue Ausgabe ersetzt die vorherige. Ein Neustart von RCM ist nicht nötig.
fbagent prüft alle 3 Minuten auf neue Versionen. Reihenfolge der Aktualisierung und
Sperre sind wie über HQCenter Admin (1.2, „Aktualisierungen“).
Schritt 6. Den Cluster beschreiben
Setzen Sie Mitglieder und Verknüpfungen in RCM, Einstellungen → Cluster (Kapitel 2.3). Nach dem
Speichern installiert fbagent die Knoten genauso wie über HQCenter Admin (1.2, Schritt 3): es schreibt
Zertifikate, node.json und rcm.json, installiert und startet die Dienste.
Ports — am Anfang des Abschnitts.
1.4. Manuelle Installation
Schritt 1. HQbird mit fbagent installieren
Installieren Sie HQbird auf jedem Datenbankserver (mit demselben Skript, aber ohne --enroll, oder mit dem vollständigen HQbird-Installationsprogramm). Prüfen Sie, dass fbagent läuft.
Notieren Sie drei Werte aus der agent_config.json von fbagent. Sie werden für node.json gebraucht:
fbagent-Feld
node.json-Feld
Beispiel
local_api.listen
firebird.fbagent_url
http://127.0.0.1:13050
local_api.token
firebird.fbagent_token
—
local_api.instance_id
firebird.instance_id
—
fbagent prüfen (die Antwort ist das JSON der Firebird-Instanz):
Unter Windows. Der Standardordner ist C:\hqclusternode mit derselben Anordnung.
Ein Pfad mit Leerzeichen ist erlaubt.
Hat ein Host zwei Knoten (Master und Replik), geben Sie jedem einen eigenen Ordner, zum Beispiel /opt/hqclusternode/master und /opt/hqclusternode/replica.
Schritt 3. Die Zertifikate erzeugen
Knoten und RCM sprechen nur über mTLS. Sie brauchen eine CA und ein Zertifikat für jeden Teilnehmer. Führen Sie dies einmal auf einem beliebigen Rechner aus:
Der Befehl erzeugt ca.crt und ca.key, node-a.crt/.key, node-b.crt/.key und rcm.crt/.key. Listen Sie in -hosts alle Namen und Adressen auf, über die die Teilnehmer erreicht werden.
gencerts und die Dateien, die es erzeugt hat
ca.key ist der CA-Schlüssel. Kopieren Sie ihn nicht auf die Hosts; bewahren Sie ihn getrennt auf.
Ein neuer Knoten wird später mit -add hinzugefügt: das Paar wird mit derselben CA signiert, die anderen Dateien bleiben unverändert:
Zertifikate gelten 90 Tage. gencerts -out certs -list zeigt die Ablaufdaten, und gencerts -out certs -renew erneuert sie mit demselben Schlüssel. Kopieren Sie die neue .crt auf ihren Host: der Knoten übernimmt sie ohne Neustart.
Kopieren Sie auf jeden Host ca.crt und nur sein eigenes Zertifikat und seinen Schlüssel.
Schritt 4. node.json schreiben
Eine Datei je Knoten. Beispiel für den Master (node-a):
json
{"node_id":"node-a","role":"master","listen_addr":":7051","rcm":{"url":"https://<ip-rcm>:7443","ca_cert":"certs/ca.crt","client_cert":"certs/node-a.crt","client_key":"certs/node-a.key"},"firebird":{"root":"/opt/firebird","user":"SYSDBA","password":"<SYSDBA password>","port":3050,"replication_conf":"/opt/firebird/replication.conf","replication_log":"/opt/firebird/replication.log","firebird_log":"/opt/firebird/firebird.log","fbagent_url":"http://127.0.0.1:13050","fbagent_token":"<local_api.token>","instance_id":"<local_api.instance_id>","service_name":"<Firebird service name>"},"windows":{"restart_window":"22:00-05:00","transfer_window":"23:00-05:00"},"peers":[{"node_id":"node-b","url":"https://<ip-node-b>:7051","compress":"zstd"}]}
Der Replik-Knoten (node-b) hat dieselbe Datei, aber mit "role": "replica", eigenen Zertifikaten und dem Master node-a in peers.
Die wichtigsten Felder:
Feld
Wert
node_id
Knotenname; derselbe im Zertifikat, in rcm.json und in den peers der anderen Knoten
role
master oder replica
listen_addr
die Adresse der Knoten-API; ein zweiter Knoten auf demselben Host verwendet einen anderen Port (:7052)
rcm.url
die Adresse für den Empfang der RCM-Statistiken; none — kein RCM
firebird.*
das Firebird und der fbagent dieser Instanz; die fbagent-Werte müssen genau übereinstimmen
firebird.auto_restart
ob der Replik-Knoten Firebird selbst neu starten darf: auto (Standard), never, always
windows.restart_window
das Fenster für den Firebird-Neustart; für den Master ist der Standard 22:00-05:00, für die Replik ist es immer
windows.transfer_window
das Fenster, in dem die Initialisierung mit voller Geschwindigkeit läuft
peers
für den Master — seine Repliken, für die Replik — ihr Master
databases
der Datenbankordner; besser nicht von Hand schreiben, sondern über RCM setzen (Kapitel 3)
Die übrigen Felder haben Standardwerte. Der Knoten startet nicht, wenn die fbagent-Felder nicht gesetzt sind.
Schützen Sie die Datei: sie enthält das Kennwort und das Token.
Command
chmod 600 /opt/hqclusternode/node.json
Unter Windows. Schreiben Sie Pfade im JSON-Format: "C:\\HQbird\\replication.conf".
service_name ist der Windows-Dienstname für Firebird.
url — die Knotenadresse, wie der RCM-Host sie sieht. Nur https.
host — die Bezeichnung der Firebird-Instanz. Ein Master-Knoten und ein Replik-Knoten mit derselben Bezeichnung laufen auf demselben Firebird (Begleiter, nötig, um eine Replik zum Master zu befördern, Kapitel 8). Eine Bezeichnung — höchstens ein Master und eine Replik.
Relative Pfade werden vom Ordner von rcm.json aus aufgelöst.
Schritt 6. Die Dienste registrieren
Startreihenfolge: zuerst RCM, dann die Repliken, dann der Master.
cd /opt/hqclusternode
sudo ./hqclusternode svc install -config /opt/hqclusternode/node.json -certs /opt/hqclusternode/certs
sudo ./hqclusternode svc start -config /opt/hqclusternode/node.json
systemctl status hqclusternode-master-p3050
svc install erzeugt den Dienst hqclusternode-<role>-p<port>, der als Benutzer firebird läuft. Gehört der Firebird-Ordner root, gewährt der Befehl der Gruppe firebird Schreibzugriff darauf (mit Sticky-Bit) und gibt jede Änderung aus: der Knoten muss replication.conf ersetzen.
Geben Sie für svc start, svc stop und svc uninstall dieselbe node.json an: der Dienstname wird aus Rolle und Firebird-Port abgeleitet.
Unter Windows (PowerShell als Administrator):
Command
cd C:\hqclusternode
.\hqclusternode.exe svc install -config C:\hqclusternode\node.json -certs C:\hqclusternode\certs
Der Dienst HQClusterNode-<role>-p<port> läuft als LocalSystem, startet automatisch und startet nach einem Fehler neu. Der Knotendienst hängt nicht vom Firebird-Dienst ab. Wurde der Knoten mit Version 2027.1.2–2027.1.9 installiert, entfernen Sie die Abhängigkeit einmal:
.\hqclusternode.exe svc fix-deps -config C:\hqclusternode\node.json.
svc install und svc start unter Windows
Schritt 7. Die Ports öffnen
Erlauben Sie auf dem Knoten-Host eingehende Verbindungen auf 7051 (den Port von listen_addr) von den anderen Knoten und von RCM. Erlauben Sie auf dem RCM-Host eingehende Verbindungen auf 7443 von allen Knoten. Legen Sie die Ports 7444 und 13050 nicht nach außen offen.
Beispiel ufw auf dem Knoten-Host:
Command
sudo ufw allow from <ip-rcm> to any port 7051 proto tcp
sudo ufw allow from <ip-partner-node> to any port 7051 proto tcp
Manuelle Aktualisierung
Stoppen Sie den Dienst, ersetzen Sie das Programm, starten Sie den Dienst:
Konfiguration und Zertifikate werden dadurch nicht geändert.
1.5. Erste Anmeldung bei RCM
Adresse und Kennwort hängen davon ab, wie RCM installiert wurde.
Wie RCM installiert wurde
Adresse
Anmeldung und Kennwort
Durch das HQbird-Installationsprogramm oder fbagent --cluster-init (1.3)
https://<RCM-Host>:7444 von jedem Computer
rcmadmin und das vom Installationsprogramm ausgegebene Kennwort (oder Ihr eigenes aus --rcm-password-file)
Über HQCenter Admin (1.2) oder von Hand (1.4)
http://127.0.0.1:7444, nur auf dem RCM-Host
rcmadmin, Kennwort strong password (mit einem Leerzeichen)
HTTPS (1.3). Das RCM-Zertifikat ist von der Cluster-CA signiert, die der Browser nicht kennt, deshalb warnt er. Auf der Anmeldeseite zeigt RCM den CA-Fingerabdruck. Vergleichen Sie ihn mit dem vom Installationsprogramm ausgegebenen CA hash und importieren Sie die CA in den Browser oder ins System als vertrauenswürdige Wurzel: der Link CA-Zertifikat herunterladen auf der Anmeldeseite (https://<RCM-Host>:7444/ca.crt, Datei hqcluster-ca.crt). Damit RCM nur auf localhost lauscht, setzen Sie in rcm.json"operator_addr": "127.0.0.1:7444" und starten Sie RCM neu.
HTTP (1.2, 1.4). Verbinden Sie sich von einem anderen Computer über einen SSH-Tunnel:
Command
ssh -L 7444:127.0.0.1:7444 <rcm-host>
Öffnen Sie danach http://127.0.0.1:7444 im Browser.
Anmeldeseite von RCM
Erzeugtes Kennwort. RCM bittet Sie, es bei der ersten Anmeldung zu ändern: bis Sie es ändern, öffnen sich die anderen Seiten nicht. Ändern Sie strong passwordsofort (der Link Kennwort in der Kopfzeile).
Kennwortänderung bei der ersten Anmeldung
Sprache. Wählen Sie Russisch in der Sprachenliste in der Seitenkopfzeile (sie ist auch auf der Anmeldeseite verfügbar). Wenn Sie keine wählen, wird die Sprache vom Browser genommen.
Kennwörter ändern und neue Benutzer
Jeder Benutzer ändert sein eigenes Kennwort: der Link Kennwort in der Seitenkopfzeile. Sie brauchen das aktuelle Kennwort und ein neues mit mindestens 12 Zeichen. Nach der Änderung werden die anderen Sitzungen dieses Benutzers geschlossen.
Hat das Installationsprogramm ein Kennwort erzeugt, steht es in der Datei clusterca/<name>/rcm-initial-password im fbagent-Ordner. Nach der Kennwortänderung löscht fbagent diese Datei selbst. Löschen Sie die Datei initial-admin.json im RCM-Ordner nicht: sie enthält nur einen Hash. Geht die Benutzerdatei verloren und fehlt diese Datei, erzeugt RCM einen Benutzer mit dem Standardkennwort.
Neue Benutzer. In der Oberfläche gibt es keine Benutzerseite. Die Benutzer stehen in der Datei rcm-data/users.json. Das Kennwort wird als HA1-Hash gespeichert: MD5("<name>:hqbirdrcm:<password>").
Starten Sie RCM sofort neu: es liest die Datei nur beim Start. Wird ein Kennwort in der Oberfläche geändert, schreibt RCM die Datei aus dem Speicher neu, und noch nicht gelesene Bearbeitungen gehen verloren.
Ohne ein Feld role hat ein Benutzer alle Rechte. Ab HQbird 2027.2.31 gibt es die Rolle "role": "viewer": nur Ansicht, jede Änderungsanfrage erhält 403.
1.6. So prüfen Sie die Installation
Die Dienste von Knoten und RCM laufen und starten nicht in einer Schleife neu:
systemctl status hqclusternode-master-p3050, systemctl status hqbirdrcm.
systemctl status des Knotens
systemctl status von RCM
RCM antwortet (ohne Kennwort): curl http://127.0.0.1:7444/healthz. Bei
Installation über RCM (1.3) arbeitet die Konsole über HTTPS:
curl -k https://127.0.0.1:7444/healthz.
In RCM zeigt die Seite Übersicht alle Knoten, ohne die Markierung „antwortet
nicht“.
Über die Befehlszeile auf dem RCM-Host:
Command
exportRCM_USER=rcmadmin RCM_PASSWORD='<password>'./hqbirdrcm nodes
./hqbirdrcm status
Der Cluster über RCM: Einstellungen → Cluster, der Abschnitt Zustand — jedes
Mitglied hat die neueste Revision angewendet und meldet keinen Fehler. Über die Befehlszeile:
./hqbirdrcm cluster status.
1.7. Protokolle
Was
Wo
Knotenprotokoll
<Ordner von node.json>/logs/node-YYYYMMDD.jsonl
Ausgabe des Knotendienstes (Linux)
journalctl -u hqclusternode-<role>-p<port>
Ausgabe des RCM-Dienstes (Linux)
journalctl -u hqbirdrcm
Firebird-Replikationsprotokoll
firebird.replication_log aus node.json
Protokolle jedes Knotens ohne SSH
RCM, Seite Protokolle
1.8. Häufige Fehler
Was Sie sehen
Ursache
Was zu tun ist
Der Knoten startet nicht: ein Fehler zu fbagent_url, fbagent_token oder instance_id
fbagent läuft nicht oder die Werte passen nicht zu agent_config.json
prüfen Sie fbagent mit dem curl-Befehl aus 1.4, Schritt 1
Das Installationsskript endete mit Code 2
die fbagent-Anfrage wurde nicht rechtzeitig genehmigt
genehmigen Sie die Anfrage und führen Sie das Skript erneut aus
Knoten erscheinen nicht über HQCenter Admin
fbagent ist nicht im Cluster, oder der Cluster wurde noch nicht geholt
prüfen Sie den Cluster (Kapitel 2), warten Sie bis zu 10 Minuten
Der Knoten in RCM ist „antwortet nicht“
Port 7051 ist geschlossen, die url in rcm.json ist falsch, die Adresse steht nicht im Zertifikat
prüfen Sie die Ports und -hosts der Zertifikate
Keine Anmeldung bei RCM: „Zu viele fehlgeschlagene Anmeldeversuche“
10 fehlgeschlagene Anmeldungen innerhalb von 5 Minuten
warten Sie einige Minuten
Die neue Version wird nicht installiert
die Version steht in blocked-versions.json
entfernen Sie die Versionszeile aus der Datei
--cluster-init: no hqbirdrcm to install
das Installationsprogramm hat das RCM-Programm nicht hinterlassen
installieren Sie HQbird mit dem vollständigen Installationsprogramm (1.3, „Von Hand“, Schritt 1)
das Token wurde schon verwendet, ist älter als 24 Stunden oder wurde widerrufen
erzeugen Sie ein neues Token (1.3, „Von Hand“, Schritt 4)
--cluster-join: hostname_conflict
der Cluster hat einen fbagent mit demselben Hostnamen und anderen Adressen
geben Sie den Hosts verschiedene Namen
--cluster-join: this agent is in cluster … from goafts
fbagent ist schon im HQCenter-Admin-Cluster
entfernen Sie ihn aus dem HQCenter-Admin-Cluster
Der Knoten wird über RCM nicht installiert
RCM hat keine Ausgabe für diese Plattform
hqbirdrcm release list, importieren Sie die Ausgabe (1.3, „Von Hand“, Schritt 5)
2. Clusterkonfiguration
In diesem Kapitel legen Sie fest, welche Knoten im Cluster sind und welcher Master
Segmente an welche Replik sendet. Danach richten Sie die RCM-Knoten und die Benutzer ein.
Beziehungen werden auf eine von drei Arten festgelegt:
Knoten installiert
Wo die Beziehungen festgelegt werden
Abschnitt
über HQCenter Admin
in HQCenter Admin: die Seite Cluster von HQ Monitor oder die HQCenter-Admin-API
2.2
über RCM, ohne HQCenter Admin
in RCM: Einstellungen → Cluster, hqbirdrcm cluster oder die Seite Cluster von HQ Monitor
2.3
von Hand
in RCM: Einstellungen → RCM und Einstellungen → Knoten
2.3
Auf Knoten, die über HQCenter Admin oder über RCM installiert wurden, ändern Sie Beziehungen nur in
der Clusterbeschreibung. fbagent überschreibt node.json und rcm.json gemäß
der Clusterbeschreibung. Beziehungen in Einstellungen → RCM oder Einstellungen → Knoten
von RCM zu bearbeiten wird abgelehnt (409 cluster_managed). Frühere RCM-Versionen nahmen es an, aber es
ging verloren.
2.1. Rollen und Schemata
Jeder Knoten hat eine Rolle: Master oder Replik. Zwei Knoten — ein Master und eine Replik — können auf einer Firebird-Instanz laufen.
Unterstützte Schemata:
Code
1 → 1 node-a (master) ──▶ node-b (replica)
1 → N node-a ──▶ node-b
└─▶ node-c
N → 1 node-a ──┐
├─▶ node-b (one replica for several masters)
node-x ──┘
Both nodes host-1: node-1m (master) + node-1r (replica) ← one Firebird
on a host host-2: node-2m (master) + node-2r (replica) ← one Firebird
node-1m ──▶ node-2r, node-2m ──▶ node-1r
Die Verknüpfung geht immer vom Master zur Replik. RCM verknüpft die Datenbank des Masters mit ihrer Replik über die Datenbank-GUID, nicht über den Knotennamen.
Begleiter. Ein Master-Knoten und ein Replik-Knoten auf derselben Firebird-Instanz sind Begleiter. Die Beförderung einer Replik zum Master (Kapitel 8) funktioniert nur für ein solches Paar. In rcm.json ist das Paar durch denselben Wert von host gekennzeichnet.
2.2. Verknüpfungen über HQCenter Admin
Wo ein Cluster beschrieben wird
HQ Monitor, Seite Cluster (nur Administratoren; die Konfigurationszustellung muss eingeschaltet sein). Der übliche Weg.
HQCenter-Admin-API:POST /v1/admin/clusters und
PUT /v1/admin/clusters/{id}. Das HQCenter-Admin-Panel hat keine
Clusterseite.
``
Schritte auf der Seite Cluster
Geben Sie eine Neue Cluster-ID ein (lateinische Kleinbuchstaben, Ziffern und -) und klicken Sie auf
Erstellen.
Fügen Sie Mitglieder hinzu (Mitglieder). Geben Sie für jedes an:
den fbagent des Hosts;
die Rolle: master, replica oder rcm;
die Hostadressen;
den Port: für einen Knoten — 7051 (ein zweiter Knoten auf demselben Host — z. B. 7052),
für RCM — den Port für den Statistikempfang 7443.
Fügen Sie Verknüpfungen hinzu (Replikationsverknüpfungen) vom Master zur Replik.
Klicken Sie auf Prüfen und dann auf Speichern.
Hat ein anderer Administrator den Cluster gleichzeitig geändert, bittet die Seite Sie,
den Cluster neu zu laden und die Änderung zu wiederholen.
Regeln
Ein fbagent kann nur zu einem Cluster gehören.
Auf einem einzelnen fbagent — höchstens ein Master, eine Replik, ein RCM und
ein Router. Der Router (Rolle router, ab HQbird 2027.2.30) hat keine Verknüpfungen und
belegt keinen Lizenzplatz (Kapitel 8.7).
Ein Cluster hat genau ein RCM. Der fbagent auf dem RCM-Host betreibt die
Zertifizierungsstelle des Clusters (CA).
Der Mitgliedsname (member_id) — lateinische Buchstaben, Ziffern, -. Name, fbagent und Rolle
eines Mitglieds können nicht geändert werden. Um ein Mitglied auf einen anderen Host zu verschieben, erzeugen Sie ein
neues Mitglied mit einem neuen Namen. Verwenden Sie den alten Namen nicht wieder.
Jede Replik muss eine Verknüpfung zum Master haben.
HQCenter Admin baut die Knotenadresse selbst: https://<erste Adresse>:<Port>.
HQbird 2.5/3.0: setzen Sie das Datum replconf_valid_till des Clusters
(YYYY-MM-DD) — die Konfiguration des Plugins replconf gilt bis zu diesem Datum.
Beispiel über die API
json
{"contract":1,"cluster_id":"shop-prod","name":"Shop","pki":"managed","cert_validity_days":90,"renew_before_days":30,"members":[{"member_id":"db1-m","agent_id":"<fbagent of host 1>","role":"master","addresses":["db1.lan"],"listen_port":7051},{"member_id":"db1-rcm","agent_id":"<fbagent of host 1>","role":"rcm","addresses":["db1.lan"],"listen_port":7443},{"member_id":"db2-r","agent_id":"<fbagent of host 2>","role":"replica","addresses":["db2.lan"],"listen_port":7052}],"links":[{"from":"db1-m","to":"db2-r"}]}
Erzeugen: POST /v1/admin/clusters (das Dokument kann zusammen mit den
Mitgliedern gesendet werden). Das ganze Dokument ersetzen: PUT /v1/admin/clusters/{id}.
PUT verlangt den Header If-Match: <revision> (die Revision liefern GET und ETag).
Ohne den Header — 428, mit einer alten Revision — 409, mit einem Fehler im Dokument —
422 mit einer Fehlerliste.
POST /v1/admin/clusters/{id}/validate prüft das Dokument, ohne zu speichern.
GET /v1/admin/clusters/{id}/status zeigt den Zustand der Mitglieder und die
Ablaufdaten der Zertifikate.
Was nach dem Speichern geschieht
Der fbagent jedes Mitglieds erhält den Cluster. Innerhalb des Clusters — eine Prüfung alle
60 Sekunden (der fbagent auf dem RCM-Host — alle 30 Sekunden). Außerhalb eines Clusters erfährt ein fbagent
beim nächsten Konfigurationsabruf vom Cluster. Erreicht dieser Abruf
den Server nicht, läuft die Prüfung alle 10 Minuten.
Jeder fbagent erzeugt einen Schlüssel und sendet eine Zertifikatanforderung. Der fbagent auf dem
RCM-Host signiert sie. RCM signiert sein eigenes Zertifikat ohne Anforderung.
fbagent schreibt in node.json: Name, Rolle, Adresse, peers (aus den Verknüpfungen), die
RCM-Adresse, Zertifikatpfade, Firebird- und fbagent-Daten. In rcm.json: die Liste der
Knoten (nodes), die Liste der Router (routers), die Adresse für den Statistikempfang und die
Zertifikatpfade. Die anderen Felder der Dateien rührt fbagent nicht an.
fbagent installiert und startet die Dienste (Kapitel 1).
Einen Cluster ändern:
Was sich geändert hat
Was fbagent tut
nur die peers eines laufenden Knotens
übergibt sie dem Knoten ohne Neustart
andere Felder eines Knotens
stoppt den Knoten, schreibt die Datei, startet den Knoten — innerhalb von windows.transfer_window des Knotens (nicht gesetzt — sofort)
rcm.json
startet RCM sofort neu
Zertifikate oder CA
startet den Dienst neu
ein Mitglied wird entfernt
stoppt und entfernt den Dienst; cluster-managed.json → cluster-removed.json, das Programm → *.removed; Konfiguration, Zertifikate und Daten bleiben
Nachdem ein Knoten entfernt wurde, bleibt sein Abschnitt
# BEGIN managed-by:<name> … # END … in der gemeinsamen replication.conf. Löschen Sie ihn von Hand und starten Sie
Firebird über RCM neu.
Clusterzertifikate genehmigen
Standardmäßig signiert der fbagent auf dem RCM-Host Anforderungen selbst (auto). Die manuelle Genehmigung
kann eingeschaltet werden. Befehle auf dem RCM-Host:
Command
fbagent --cluster-ca-approval manual # or autofbagent --cluster-status # this fbagent's membership in the cluster (JSON)fbagent --cluster-ca-approve <request_id>
Im Modus manual wartet ein neues Mitglied oder ein neuer Schlüssel auf Genehmigung. Die Erneuerung eines
Zertifikats mit bekanntem Schlüssel wird automatisch signiert.
2.3. Verknüpfungen über RCM
RCM-Cluster (ohne HQCenter Admin)
Wurde der Cluster vom HQbird-Installationsprogramm oder vom Befehl fbagent --cluster-init
erzeugt (Kapitel 1.3), speichert RCM die Clusterbeschreibung. Der einfachste Weg, Hosts hinzuzufügen, ist die Seite
Einstellungen → Hosts verknüpfen (Kapitel 1.3, „Hosts in RCM verknüpfen“):
RCM erzeugt Mitglieder und Verknüpfungen selbst. Die Regeln sind dieselben wie in HQCenter Admin (2.2, „Regeln“), dazu:
in RCM gibt es einen Cluster; das Mitglied rcm existiert immer und kann nicht gelöscht werden;
höchstens 3 Plätze (Hosts mit Master- oder Replik-Knoten), sonst tritt der Fehler
seats_exceeded auf;
ein Mitglied kann nur auf einem fbagent hinzugefügt werden, der sich mit RCM verbunden hat
(Kapitel 1.3: „Hosts verknüpfen“ oder „Von Hand“, Schritt 4).
Schritte auf der Seite Einstellungen → Cluster:
Klicken Sie in der Tabelle Agenten auf Mitglied hinzufügen in der fbagent-Zeile.
Geben Sie die Rolle an (master, replica oder router), member_id, Adressen und Port.
Die Seite schlägt den Namen <host>-<role> und den Port vor: 7051 für den ersten fbagent-Knoten,
7061 für den zweiten. Einen Port, den schon ein anderes Mitglied des Hosts belegt, lehnt RCM ab. Die
fbagent-Adressen sind Schaltflächen: klicken, um eine Adresse hinzuzufügen.
Klicken Sie im Abschnitt Verknüpfungen auf Verknüpfung hinzufügen vom Master zur Replik.
Klicken Sie auf Prüfen: RCM zeigt Fehler und Warnungen.
Klicken Sie auf Speichern. Die Seite zeigt die Liste der Änderungen und bittet um
Bestätigung. Werden Mitglieder gelöscht, ist das Fenster rot.
Vor dem Speichern existieren die Änderungen nur auf der Seite (die Beschriftung „Nicht gespeichert“). Hat
jemand den Cluster gleichzeitig gespeichert, bietet die Seite an, ihn neu zu laden.
Haben sich nur RCM-Felder geändert (Revision, CA, Aufträge), speichert die Seite
Ihre Änderung selbst.
Weitere Abschnitte der Seite:
Abschnitt
Was dort steht
Kopf
Clustername, Revision, Cluster-CA und Agent-CA; die Schaltfläche Exportieren für die alte CA
Verbindungstoken
ein Token für einen neuen fbagent erzeugen, ein ungenutztes widerrufen
JSON-Dokument
das ganze Dokument in einem Textfeld; Prüfen und Speichern verwenden es
Schlüssel und CAs
Aufträge: neuer Mitgliedsschlüssel (rekey), neue Cluster-CA (rotate_ca), neue Agent-CA (rotate_agent_ca); nicht verfügbar, wenn es ungespeicherte Änderungen gibt
Zustand
die Revision, die jedes Mitglied angewendet hat, Zertifikatsablauf, Dienst, letzter Fehler
Über die Befehlszeile auf dem RCM-Host:
Command
exportRCM_USER=rcmadmin RCM_PASSWORD='<password>'./hqbirdrcm cluster show > c.json # document with revision# edit c.json./hqbirdrcm cluster validate -f c.json # validate without saving anything./hqbirdrcm cluster apply -f c.json # save (If-Match = revision from the file)./hqbirdrcm cluster agents # connected fbagents and their members./hqbirdrcm cluster status # what the fbagents reported
Das Dokumentformat ist wie in 2.2, „Beispiel über die API“. apply mit einer alten Revision
erhält 409: führen Sie show erneut aus. RCM behält die letzten 20 Revisionen in
rcm-data/cluster/history/.
HQ Monitor. Die Seite Cluster arbeitet auch mit RCM. Auf dem RCM-Host
greift HQ Monitor über den fbagent dieses Hosts auf RCM zu, mit dem fbagent-
Zertifikat: RCM-Benutzer und Kennwort werden nicht gebraucht. Im RCM-Auditprotokoll werden solche
Aktionen als agent:<id> (<user>) festgehalten. Ein anderer Weg, für frühere
RCM-Versionen: setzen Sie in der HQ-Monitor-Konfiguration rcm_admin_url
(http://127.0.0.1:7444), rcm_admin_user (der RCM-Benutzer) und
rcm_admin_password_file (eine Datei mit seinem Kennwort).
Nach dem Speichern läuft alles wie über HQCenter Admin (2.2, „Was nach dem Speichern
geschieht“). RCM liest nodes in rcm.json selbst neu, ohne Neustart.
Einen fbagent aus dem Cluster entfernen: löschen Sie seine Mitglieder und speichern Sie, dann
klicken Sie auf Widerrufen in der Tabelle Agenten (oder
./hqbirdrcm cluster revoke -agent <id>). Um ihn zurückzuholen, wird ein neues
Token gebraucht. Nach dem Widerruf verlässt der fbagent (ab Version 3.1.0) den Cluster
selbst: er stoppt seine Knoten und löscht die Clusterdaten. Dasselbe tut auf einem
Knoten-Host der Befehl fbagent --cluster-leave. Auf dem RCM-Host wird er abgelehnt.
Manuelle Installation: einen Knoten zu RCM hinzufügen
Einstellungen → RCM, die Tabelle Verbundene Knoten.
Klicken Sie auf Knoten hinzufügen. Füllen Sie node_id, url
(https://<Adresse>:7051), Rolle, host (Bezeichnung der Firebird-Instanz),
server (nur für die Gruppierung auf dem Bildschirm) aus.
Klicken Sie in der Knoten-Zeile auf Prüfen: RCM prüft Verbindung und Rechte.
Klicken Sie auf Speichern. RCM schreibt rcm.json und speichert die alte Datei als
rcm.json.<UTC-Zeit>.bak (die letzten 20).
Starten Sie RCM neu. Bis zum Neustart gilt die alte Konfiguration;
die Seite zeigt, welche Felder auf einen Neustart warten.
Einstellungen → RCM
Command
sudo systemctl restart hqbirdrcm
Sie können es auch ohne die Oberfläche tun: bearbeiten Sie rcm.json und starten Sie RCM neu.
Manuelle Installation: Master und Replik verknüpfen
Die Verknüpfung muss auf beiden Seiten eingetragen werden:
Einstellungen → Knoten, wählen Sie den Master-Knoten.
Klicken Sie im Abschnitt Partner auf Partner hinzufügen: die node_id der Replik, ihre url,
Kompression (zstd).
Klicken Sie auf Speichern. RCM zeigt die Liste der Änderungen und bittet um
Bestätigung. Die Änderung von peers gilt sofort.
Wiederholen Sie es für den Replik-Knoten: sein Partner ist der Master.
Der Abschnitt Partner des Master-Knotens
Ist der Partner auf einer der Seiten nicht eingetragen, bietet RCM diesen Replik-Knoten bei der
Initialisierung der Datenbank nicht an.
2.4. Knoteneinstellungen
Einstellungen → Knoten zeigt die node.json-Einstellungen, die der Knoten von RCM aus ändern lässt. Nur die geänderten Felder werden gespeichert, nach einem Fenster mit der Liste der Änderungen.
Einstellungen → Knoten: einen Knoten auswählenDatenbankeinstellungen des Knotens mit Markierungen "nach dem Scan"
Jede Zeile ist damit markiert, wann die Änderung gilt:
Wann
Welche Einstellungen
Sofort
channel_a_mbps, channel_a_burst_mbps, windows.restart_window, peers; ab HQbird 2027.2.24 — Einstellungen der Datenprüfung (limits.data_check_*); ab HQbird 2027.2.31 — advertise_addr
Nach Knoten-Neustart
die übrigen Grenzen, windows.transfer_window; die Seite zeigt sie in einer eigenen Zeile, bis der Knoten neu gestartet wird
Nach dem Scan
databases.*, exclude_filter; hat sich replication.conf geändert, ist ein Firebird-Neustart nötig (Kapitel 3.5)
Nur lesbar (geändert in node.json auf dem Knoten-Host): firebird (einschließlich Kennwort und auto_restart), rcm, tls, segments, die Adresse listen_addr.
Die wichtigsten Einstellungen:
Einstellung
Standard
Bedeutung
windows.restart_window
Master 22:00-05:00, Replik — immer
wann der Knoten Firebird neu starten darf; das Firebird des Masters startet sich nie selbst neu
windows.transfer_window
23:00-05:00
das Fenster, in dem die Initialisierung mit der Rate reinit_window_mbps läuft
limits.channel_a_mbps
50
Übertragungsrate der Segmente, MB/s (channel_a_burst_mbps — kurzfristige Spitze, 200)
limits.reinit_window_mbps
100
Initialisierungsrate innerhalb des Übertragungsfensters, MB/s
limits.reinit_day_disk_fraction
0,5
Anteil der gemessenen Plattengeschwindigkeit für die Initialisierung außerhalb des Fensters
limits.retention_days
2
wie viele Tage gesendete Segmente im Archiv des Masters behalten werden
limits.free_space_floor_gb
1
minimaler freier Platz, GB; darunter nimmt die Replik keine Segmente an
limits.max_concurrent_reinits
1
wie viele Initialisierungen der Knoten gleichzeitig ausführt
Einzelheiten zu Geschwindigkeit und Archivaufbewahrung stehen in den Kapiteln 5 und 7.
firebird.auto_restart (nur in node.json) bestimmt, ob ein Replik-Knoten Firebird selbst neu starten darf:
Wert
Verhalten
auto (Standard)
darf, wenn dieses Firebird keine Master-Datenbanken bedient
never
nie
always
immer, auch wenn dieses Firebird Master-Datenbanken beherbergt
Über HQCenter Admin. Die windows.transfer_window des fbagent-Knotens wird auch als Fenster für den Neustart des Knotendienstes selbst verwendet, wenn sich der Cluster ändert. Ist das Fenster in node.json nicht gesetzt, startet fbagent den Dienst sofort neu.
2.5. Mehrere HQbird-Instanzen auf einem Host
fbagent startet die Dienste neu, die in firebird.update.services seiner
Konfiguration stehen. Eine leere Liste bedeutet alle HQbird-Dienste auf dem Host. Lassen Sie nur
den Dienst Ihrer eigenen Instanz in der Liste. Der Knoten sieht diese Einstellung nicht und schreibt eine
Warnung fbagent_shared ins Protokoll, wenn fbagent mehr als eine Instanz kennt.
2.6. SYSDBA-Kennwort
Der Knoten verbindet sich mit Firebird mit Benutzer und Kennwort aus firebird.user und
firebird.password in node.json. fbagent speichert eine eigene Kopie des Kennworts. Wenn Sie
das SYSDBA-Kennwort geändert haben:
Korrigieren Sie firebird.password in der node.jsonjedes Knotens dieser
Instanz (Master und Replik).
Korrigieren Sie das Kennwort in der fbagent-Konfiguration und laden Sie sie neu (siehe die
fbagent-Dokumentation).
Starten Sie die Knotendienste neu.
Sonst zeigen die Publikations- und Prüfseiten in RCM einen Anmeldefehler
(SQLSTATE 28000).
2.7. RCM-Benutzer und Audit
Die Benutzer stehen in der Datei rcm-data/users.json (Kapitel 1.5). Ohne Rolle hat ein
Benutzer alle Rechte; die Rolle viewer (ab HQbird 2027.2.31) — nur Ansicht.
Eine Sitzung dauert 12 Stunden nach der letzten Aktion.
Nach 10 fehlgeschlagenen Anmeldungen innerhalb von 5 Minuten wird die Anmeldung für diesen Benutzer und diese Adresse
vorübergehend gesperrt. Eine erfolgreiche Anmeldung setzt den Zähler zurück.
Das Auditprotokoll ist die Datei rcm-data/audit.jsonl: eine JSON-Zeile für jede
Änderung, Anmeldung und Abmeldung. In der Oberfläche gibt es kein Auditprotokoll.
Die Seite Befehle zeigt den Autor jedes Befehls.
2.8. Lizenz
Einmal pro Minute liest der Master-Knoten die fbagent-Lizenz seines Hosts. Gibt es keine Lizenz (die Testzeit ist zu Ende, die Lizenz ist abgelaufen oder ungültig), hört der Knoten auf, Segmente zu senden, für alle Datenbanken des Masters. Firebird und die Datenbanken laufen weiter, aber die Repliken erhalten keine Änderungen mehr.
Was Sie in RCM sehen:
der Master ist rot (NEEDS_ATTENTION), mit dem Kennzeichen „keine Lizenz: Versand gestoppt“;
es gibt keine Schaltfläche Fortsetzen: nur die Lizenz hebt die Pause auf;
auf der Replik: „empfängt nicht seit …: der Master hat keine Lizenz“;
in der Tabelle Knoten ein Kennzeichen „keine Lizenz“; unter Einstellungen → Knoten der Block der fbagent-Lizenz;
die Warnungen license_paused und license_pause_archive_released;
die Initialisierung ist verboten (license_paused).
Block der fbagent-Lizenz unter Einstellungen → Knoten
Installieren Sie die Lizenz in fbagent. Der Knoten hebt die Pause innerhalb einer Minute selbst auf. Der Master behält das Archiv für die Repliken limits.retention_days lang (standardmäßig 2 Tage) ab Beginn der Pause. Installieren Sie die Lizenz später, müssen die Repliken neu initialisiert werden.
Cluster über RCM, ohne HQCenter Admin. Eine Floating-Lizenz ohne HQCenter Admin hört nach online_check_days plus den Kulanz-Tagen auf zu arbeiten. Jeder fbagent im Cluster braucht eine gebundene Lizenz (fbagent --license-request, dann fbagent --license-install, Kapitel 1.3, „Lizenz“). Nach der Testzeit fügt fbagent ohne die Funktion cluster in der Lizenz keinen neuen Knoten und kein RCM hinzu; Aktualisierungen verbietet es nie. Bei HQbird 2.5/3.0 darf das Datum replconf_valid_till in RCM nicht später liegen als das Ende der Lizenz plus die Kulanz-Tage auf den fbagent-Knoten (Fehler replconf_after_license).
2.9. So prüfen Sie
Übersicht: alle Knoten sind vorhanden und nach Server gruppiert.
Clusterübersicht
Einstellungen → Knoten: der Master hat eine Replik unter Partner, und die Replik hat den Master.
Einstellungen → RCM: die Schaltfläche Prüfen in der Zeile jedes Knotens besteht.
Clusterbericht als eine Datei:
Command
./hqbirdrcm report -o report.json
2.10 Häufige Fehler
Was Sie sehen
Ursache
Was zu tun ist
Bearbeiten der Partner in RCM abgelehnt (409 cluster_managed) oder nach Knoten-Neustart verloren
der Knoten wurde über HQCenter Admin oder über RCM installiert
ändern Sie die Verknüpfungen in der Clusterbeschreibung (2.2, 2.3)
seats_exceeded beim Speichern des Clusters in RCM
Knoten auf einem vierten Host
höchstens 3 Hosts mit Knoten
Einstellungen → RCM: rcm_config_read_only
Cluster über RCM unter Linux: rcm.json gehört fbagent
bearbeiten Sie rcm.json als fbagent-Benutzer und starten Sie RCM neu
Widerrufen des Agenten funktioniert nicht (agent_has_members)
fbagent hat Mitglieder
löschen Sie zuerst die Mitglieder und speichern Sie
Replik-Knoten wird bei der Initialisierung nicht angeboten
der Partner ist auf einer der Seiten nicht eingetragen
fügen Sie den Partner auf beiden Seiten hinzu (2.3)
Eine Änderung unter Einstellungen → RCM gilt nicht
RCM wurde nicht neu gestartet
starten Sie RCM neu
422 beim Speichern des Clusters in HQCenter Admin
ein Fehler im Dokument
korrigieren Sie ihn gemäß der Liste errors, prüfen Sie über validate
409 beim Speichern des Clusters
der Cluster wurde von jemand anderem geändert
lesen Sie den Cluster neu und versuchen Sie es erneut
Ein neues HQCenter-Admin-Clustermitglied erhält kein Zertifikat
manuelle Genehmigung auf dem RCM-Host
fbagent --cluster-ca-approve <id>
Fehler SQLSTATE 28000 auf den Publikationsseiten
das SYSDBA-Kennwort wurde geändert
2.6
3. Eine Datenbank zum Master hinzufügen
In diesem Kapitel kommt die Master-Datenbank unter die Kontrolle des Knotens. Der Knoten trägt sie in
replication.conf ein und legt Ordner für die Segmente an. Nach dem Neustart von Firebird
ist die Datenbank bereit für die Replikation.
Die Replik zu erzeugen sind die nächsten Schritte (Publikation, Initialisierung). Sie sind in den
Kapiteln 4–6 beschrieben.
Die Schaltflächennamen folgen der russischen RCM-Oberfläche, mit den englischen in Klammern.
3.1. Wie ein Knoten Datenbanken findet
Der Master-Knoten sucht Datenbanken in einem einzigen Ordner — der Datenbankwurzel (databases.root). Was unter Verwaltung kommt, entscheiden Regeln:
Regel
Feld
Standard
Datenbankordner
root
nicht gesetzt
Unterordner durchsuchen
recursive
ja
Einschlussmaske
template
*.fdb
Ausschlussmaske
exclude_mask
keine
Dateigröße, MB
min_size_mb, max_size_mb
keine Grenzen (0)
Tabellen für den Datenvergleich
sync_tables
mit HQbird 2027.2.24 — Tabellen aus der Publikation der Datenbank, keine — RDB$FIELDS; in 2027.5.7 — RDB$FIELDS
Einschlussliste
include_paths
leer (Maskenmodus)
Ausschlussliste
exclude_paths
leer
Der Pfad root ist ein Pfad auf dem Knoten-Host, nicht auf dem RCM-Host. Der Knoten wendet zuerst die Einschlussmaske an, dann die Ausschlussmaske, dann die Größe.
Die Regeln gelten für den ganzen Knoten. Die Liste sync_tables ist ebenfalls gemeinsam: die Prüfung (Kapitel 5.10) sucht jede Tabelle aus der Liste in jeder Datenbank des Knotens, die keine eigene Liste hat.
Tabellen für den Vergleich, mit HQbird 2027.2.24. Jede Datenbank kann eine eigene Liste haben (Tabellen zur Synchronisationsverfolgung). Der Knoten speichert sie in databases.sync_tables_by_db. Die Prüfung nimmt die erste gesetzte Liste:
die eigene Liste der Datenbank;
die gemeinsame Liste sync_tables des Knotens;
Tabellen aus der Publikation der Datenbank;
RDB$FIELDS.
Eine früher gespeicherte gemeinsame Liste hat Vorrang vor der Publikation: eine Datenbank ohne eigene Liste verwendet sie. Die Datenbankseite des Masters zeigt, welche Liste gerade gilt (3.3).
Eine Tabelle, die sowohl in der primären Datenbank als auch in der Replik fehlt, erhält den Zustand „nicht in der Datenbank“ (absent): sie wird nicht verglichen, und die Prüfung zeigt ihretwegen nicht „Nicht in Ordnung“. Eine Tabelle, die nur auf einer Seite fehlt, ist eine Abweichung.
RCM und Knoten 2027.5.7. Es gibt eine einzige Liste für den ganzen Knoten (sync_tables); ohne Liste verwendet die Prüfung RDB$FIELDS. Eine fehlende Tabelle ist ein Fehler, und die Datenbankprüfung zeigt „Nicht in Ordnung“.
Alle Regeln stehen in der node.json des Knotens. Der Knoten wendet sie bei jedem Scan an.
Maskenmodus und Listenmodus:
Maskenmodus (Einschlussliste leer): der Knoten nimmt alle Dateien, die zur Maske passen, außer den ausgeschlossenen. Eine neue Datei im Ordner nimmt der Knoten beim nächsten Scan automatisch auf.
Listenmodus (Einschlussliste nicht leer): der Knoten nimmt nur die Dateien aus der Liste. Eine neue Datei kommt nicht automatisch unter Verwaltung — sie muss hinzugefügt werden.
Wählen Sie den Listenmodus, wenn der Ordner Datenbankkopien, Testdatenbanken oder andere Dateien enthält, die nicht repliziert werden müssen.
3.2. Bevor Sie beginnen: Rechte prüfen
Der Benutzer, unter dem Firebird und der Knoten laufen (firebird unter Linux,
LocalSystem unter Windows), muss Lese- und Schreibrechte haben auf:
den Wurzelordner der Datenbanken und die Datenbankdateien;
replication.conf und seinen Ordner (der Knoten ersetzt die Datei über eine temporäre Datei);
die Segmentordner <database>.ReplLog und <database>.LogArch (der Knoten legt sie selbst an).
RCM prüft die Rechte vor der Aufnahme (preflight). Schlägt die Prüfung fehl,
endet der Befehl mit dem Fehler preflight failed on <node> und einer Liste von Pfaden.
Übersicht → Karte des Master-Knotens → Datenbanken aufnehmen.
Ein Replik-Knoten hat diese Seite nicht.
Das Formular zeigt die aktuellen Regeln des Knotens (der Knoten hat sie selbst gesendet). Antwortet der Knoten
nicht, sind die Schaltflächen für Vorschau und Aufnehmen deaktiviert: ohne die aktuellen
Regeln würden sie die Einschluss- und Ausschlusslisten zurücksetzen.
Füllen Sie die Felder aus oder korrigieren Sie sie: Pfad zum Ordner auf diesem Server,
rekursiv, Masken, Größenfilter, Tabellen zur Synchronisationsverfolgung.
Das Feld Tabellen zur Synchronisationsverfolgung:
mit HQbird 2027.2.24 und neuer — die Liste gilt je Datenbank, die diese Aktion
aufnimmt. Leeres Feld: die Datenbank verwendet die Tabellen ihrer eigenen Publikation. Die Aufnahme ändert die gemeinsame Liste des Knotens nicht
(sync_tables). Gibt es sie, sagt das Formular das: eine Datenbank ohne eigene Liste verwendet sie
statt der Publikation.
Die Liste einer schon verwalteten Datenbank wird auf ihrer Seite gesetzt: Datenbanken →
Master-Datenbank → Block Tabellen zur Synchronisationsverfolgung. Der Block
zeigt, welche Liste gerade gilt. Ein leeres Feld entfernt die eigene Liste der Datenbank;
in RCM und Knoten 2027.5.7 — eine einzige Liste für alle Datenbanken des Knotens
(sync_tables).
Klicken Sie auf Vorschau. Der Knoten zeigt alle Dateien, die zur Einschlussmaske passen.
Er ändert nichts.
Prüfen Sie die Liste. Jede Datei hat ein Kontrollkästchen:
angehakt — die Datei wird verwaltet;
angehakt, gesperrt, markiert schon verwaltet — die Datenbank ist schon
aufgenommen;
gesperrt mit einem Grund — die Datei ist durch Maske, Größe oder die Ausschlussliste
ausgeschlossen. Um sie aufzunehmen, ändern Sie die Regel.
Haken Sie die nötigen Datenbanken an und klicken Sie auf Ausgewählte
aufnehmen. RCM bittet um Bestätigung und zeigt die Anzahl der Dateien.
Bestätigung der Aufnahme
Was diese Schaltfläche tut:
im Maskenmodus — Dateien ohne Haken kommen auf die Ausschlussliste, Dateien mit
Haken werden davon entfernt;
im Listenmodus — Dateien mit Haken kommen auf die Einschlussliste.
Die Schaltfläche fügt Datenbanken zu denen hinzu, die schon unter Verwaltung stehen. Gesperrte
Zeilen ändert sie nicht.
7. Die Schaltfläche Aufnehmen wendet das Formular an, ohne die
Listen zu ändern.
8. Warten Sie auf die Abschlussmeldung und die Zahl der hinzugefügten Datenbanken. Kommt lange
keine Antwort, prüfen Sie das Ergebnis auf der Seite Befehle.
Mit HQbird 2027.2.24 und neuer lautet die Meldung „Aufgenommen: N“. Muss das Firebird des Masters
neu gestartet werden, sagt RCM, welche Schaltfläche zu drücken ist (meist
Firebird des Masters neu starten in der Zeile der Datenbank) und gibt einen Link zu den Master-
Datenbanken.
RCM 2027.5.7 kann „Keine neuen passenden Datenbanken“ sagen, obwohl Datenbanken
hinzugefügt wurden: prüfen Sie die Seite Datenbanken.
Ergebnis der Aufnahme
Wurden nach der Aufnahme keine Datenbanken gefunden, der Knoten aber schon welche hatte, lehnt der Knoten
ab (409) und gibt die alten Regeln zurück. So schaltet ein Fehler im Pfad nicht die
Replikation aller Datenbanken ab.
Hinweis: der Befehl sendet nur die Felder aus seinen Parametern. Die übrigen
Regeln (Masken, Größen, Einschluss- und Ausschlusslisten, sync_tables) werden vom
Knoten zurückgesetzt. Der Befehl hat keine Parameter für diese Regeln. Prüfen Sie vor
dem Befehl die aktuellen Regeln (hqbirdrcm getconfig -node node-a). Sind
sie gesetzt, verwenden Sie die Aufnahmeseite.
3.4. Was nach der Registrierung geschieht
Der Knoten schreibt die Regeln in node.json.
Der Knoten scannt den Ordner (scansync).
Für jede gefundene Datenbank schreibt der Knoten einen Block in seinen eigenen Bereich von
replication.conf (zwischen den Zeilen # BEGIN managed-by:node-a role:master und
# END …) und legt die Ordner <database>.ReplLog und <database>.LogArch an. Text außerhalb seines eigenen Bereichs ändert der Knoten nicht.
Vor einer Änderung speichert der Knoten eine Kopie der Datei:
replication_YYYYMMDD_hhmmss_NNN.conf.
Hat sich replication.conf geändert, gehen die Datenbanken in den
Zustand PENDING_RESTART: Firebird liest die neue Datei erst nach einem
Neustart. In der Tabelle Knoten steht das in der Spalte Neustart
ausstehend.
Die Spalte „Neustart ausstehend“ in der Tabelle „Knoten“
Zustände einer neuen Datenbank:
Zustand
Gruppe in RCM
Bedeutung
UNCONFIGURED
Ausstehend
Datenbank gefunden, Konfiguration noch nicht geschrieben
Firebird neu gestartet, Datenbank bereit für Publikation und Initialisierung
3.5. Das Firebird des Masters neu starten
Der Master-Knoten startet Firebird nie selbst neu. RCM auch nicht. Den Master
neu zu starten ist die Entscheidung des Operators: ein Neustart wirft alle Verbindungen zu
allen Datenbanken dieser Firebird-Instanz ab.
Wählen Sie eine Zeit geringer Last und klicken Sie auf eine der Schaltflächen:
Firebird des Masters neu starten — auf der Seite Datenbanken, in der Zeile des
Masters der Datenbank, die auf einen Neustart wartet;
dieselbe Schaltfläche im Fenster Initialisieren, Kapitel 5;
Firebird neu starten — auf der Datenbankseite.
RCM bittet um Bestätigung. Es zeigt den Knotennamen und eine Warnung: Firebird
startet sofort neu, ohne Neustartfenster, und alle Verbindungen werden abgeworfen.
Bestätigung des Neustarts von Firebird des Masters
Dasselbe über die Befehlszeile
Command
hqbirdrcm restartfirebird -node node-a
Dieser Befehl startet ebenfalls sofort neu, ohne Neustartfenster.
Wie der Knoten Firebird neu startet:
Prüft, dass fbagent antwortet und dieselbe Instanz verwaltet
(Bezeichner, Port, Dienstname aus node.json). Stimmt ein Wert nicht,
lehnt der Knoten ab.
Bittet fbagent, Firebird neu zu starten.
Wartet, bis Firebird auf seinem Port antwortet.
Verschiebt die Datenbanken von PENDING_RESTART nach CONFIGURED.
Mehrere HQbird-Instanzen auf einem Host. fbagent startet die Dienste neu, die in
firebird.update.services seiner Konfiguration stehen. Eine leere Liste bedeutet alle
HQbird-Dienste auf dem Host. Gibt es zwei HQbird-Instanzen auf dem Host, lassen Sie
nur den Dienst Ihrer Instanz in der Liste. Sonst stoppt der Neustart eines Knotens
auch die andere Instanz.
Unter Windows. Ist replication.log auf log_portion_mb oder mehr angewachsen,
läuft der Neustart so: Firebird stoppen → das Protokoll archivieren → starten.
3.6. Eine Datenbank, die schon von Hand repliziert wird
Ist die Replikation für eine Datenbank schon von Hand eingerichtet (eigener Block in
replication.conf, Publikation eingeschaltet, Segmente fließen), kann sie unter
Verwaltung genommen werden, ohne die Replik neu zu initialisieren. Dafür gibt es den
Modus detect_existing (nur Master).
In der Antwort listet taken_over die Datenbanken, die übernommen werden. Fügen Sie -verbose
hinzu, um die übersprungenen Datenbanken mit dem Grund zu sehen.
Ist die Liste richtig, führen Sie den Befehl ohne -dry-run aus.
Der Knoten übernimmt einen Block nur, wenn:
die Segmentordner genau <database>.ReplLog und <database>.LogArch heißen;
im Archiv schon Segmente liegen;
die Publikation in der Datenbank eingeschaltet ist.
Einen Block mit anderen Pfaden übernimmt der Knoten nicht und meldet ihn als „gefunden, aber
nicht unterstützt“.
Nach der Übernahme erhalten die Datenbanken PENDING_RESTART, obwohl die Replikationseinstellungen
nicht geändert werden: nur die Position des Blocks in der Datei ändert sich. Starten Sie Firebird in einem
Wartungsfenster neu.
3.7. So prüfen Sie
Datenbanken: die Datenbank ist in der Zeile des Master-Knotens sichtbar, Zustand CONFIGURED
(nach dem Neustart).
Neben der Datenbank kann ein Symbol Publikation AUS stehen: die Publikation ist noch
nicht eingeschaltet. Das ist normal, die Publikation ist der nächste Schritt (Kapitel 6).
Neue Datenbank in der Master-Zeile
Auf dem Knoten-Host: der Datenbankblock steht in replication.conf innerhalb des
Bereichs managed-by:node-a, und neben der Datenbank liegen die Ordner .ReplLog und .LogArch.
3.8. Eine Datenbank aus der Verwaltung nehmen
Der übliche Weg ist die Schaltfläche. Haken Sie auf der Seite Datenbanken die Datenbanken an,
wählen Sie die Massenaktion Aus der Verwaltung entfernen und
klicken Sie auf Auf die Auswahl anwenden. RCM:
fügt die Dateien der Ausschlussliste des Knotens hinzu;
scannt den Ordner einmal: die Datenbankblöcke werden aus replication.conf entfernt;
löscht die Datenbankeinträge im Knoten.
Die Datenbankdateien und Segmentordner bleiben auf der Platte. Firebird wird nicht neu gestartet.
Firebird schreibt die Segmente der Datenbank bis zum nächsten Neustart weiter;
RCM sagt, ob ein Neustart nötig ist.
RCM lehnt (has_replicas) eine Master-Datenbank ab, die eine lebende Replik hat:
sonst würde die Replik still aufhören. Machen Sie die Replik zuerst zu einer gewöhnlichen Datenbank oder
entfernen Sie sie (Kapitel 8).
Löschen Sie den Datenbankblock nicht von Hand aus replication.conf: beim nächsten
Scan schreibt der Knoten ihn wieder.
Ist die Datenbankdatei verschwunden oder durch eine Regel ausgeschlossen. Dann erhält die Datenbank
den Zustand ORPHANED (die Gruppe Verwaist). Der Knoten behält seinen Eintrag und das Segmentarchiv:
eine fehlende Datenbank ist öfter ein Versehen als eine Entscheidung. Kommt die Datei zurück, arbeitet die Datenbank
wieder und die Warnung wird gelöscht. Um eine solche Datenbank dauerhaft zu löschen,
führen Sie zwei Schritte in dieser Reihenfolge aus:
Nach forgetdatabase findet der Befehl cleanuparchive die Datenbank nicht mehr. Beide
Befehle arbeiten nur für eine Datenbank im Zustand ORPHANED und rühren die Datenbankdatei nicht an.
Vorsicht. Führen Sie nach der Beförderung einer Replik zum Master (Kapitel 8) nicht
cleanuparchive -orphaned für den alten Eintrag aus: der neue Master verwendet denselben
Ordner .LogArch, und der Befehl löscht sein Arbeitsarchiv.
3.9. Die Datenbankwurzel ändern
Die Registrierung mit einem anderen Pfad ist erlaubt. Der Knoten:
fügt Datenbanken aus dem neuen Ordner hinzu;
verschiebt Datenbanken aus dem alten Ordner, die im neuen nicht vorhanden sind, nach ORPHANED (Meldung
orphaned_database) und behält ihre Archive.
Haben Sie den falschen Ordner gewählt, registrieren Sie den richtigen erneut. Eine Datenbank mit demselben
vollständigen Pfad arbeitet unter derselben db_id weiter. Eine Datenbank auf einem anderen Pfad
ist eine neue Datenbank (neue db_id); ihre Replik muss neu initialisiert werden.
3.10. Häufige Fehler
Was Sie sehen
Ursache
Was zu tun ist
preflight failed on node-a
keine Rechte auf die Ordner
korrigieren Sie die Rechte, versuchen Sie es erneut (3.2)
409 scan_would_empty_region
der neue Ordner enthält keine Datenbanken, der Knoten hatte aber welche
prüfen Sie Pfad und Maske
Die Vorschau ist leer
die Maske passt nicht oder der Ordner ist falsch
prüfen Sie Pfad, Maske, „rekursiv“
Die Schaltflächen sind deaktiviert, „Knotenkonfiguration konnte nicht gelesen werden“
der Knoten antwortet nicht
prüfen Sie den Knotendienst und das Netz (Kapitel 1)
Die Datenbank bleibt lange in PENDING_RESTART
der Master startet Firebird nicht selbst neu
starten Sie Firebird neu (3.5)
Neustart wegen fbagent abgelehnt
fbagent läuft nicht oder seine Daten passen nicht zu node.json
Kapitel 1, fbagent prüfen
Die neue Datei ist nicht erschienen
der Knoten ist im Listenmodus
fügen Sie die Datei über „Ausgewählte aufnehmen“ hinzu
4. Wie eine Datenbank zur Replik wird: Schritte und Platz auf der Platte
Dieses Kapitel behandelt den ganzen Weg einer Datenbank von der primären bis zu einer arbeitenden Replik, dazu die Berechnung des Plattenplatzes. Die Initialisierung selbst ist im Kapitel 5 ausführlich beschrieben.
4.1. Die Hauptregel
Eine Datenbank erscheint auf einer Replik nur durch Initialisierung vom Master (reinit):
der Master-Knoten selbst überträgt eine Kopie über nbackup.
Machen Sie keine Kopie von Hand:
gbak erzeugt eine neue Datenbank-GUID und setzt die Segmentnummer zurück. Die Verknüpfung
Master — Replik bricht.
Eine Dateikopie einer laufenden Datenbank ist nicht konsistent, und RCM sieht zwei Datenbanken mit derselben
GUID (duplicate_guid) und verbietet die Initialisierung.
Eine schon laufende, von Hand eingerichtete Replik kann ohne eine neue Kopie unter
Verwaltung genommen werden — siehe 4.6.
Schritt 3 ist für Firebird 4/5 verpflichtend. Ohne Publikation schreibt das Firebird des Masters keine
Tabellenänderungen in die Segmente, und die Replik bleibt still hinter dem Master zurück. Auf der
Seite Datenbanken ist eine solche Datenbank mit dem Symbol Publikation AUS markiert. Klicken Sie vor der Initialisierung auf
Publikation synchronisieren.
Ab HQbird 2027.2.24 warnt das Fenster Initialisieren davor und
bietet eine Schaltfläche Publikation synchronisieren und initialisieren, während der
Master-Knoten die Initialisierung mit dem Fehler publication_off ablehnt (Kapitel 5.1).
RCM und Knoten 2027.5.7 prüfen die Publikation nicht.
HQbird 2.5/3.0. Es gibt keine Publikationen, deshalb wird Schritt 3 übersprungen. Die Tabellenmenge bestimmen die
Filter des Plugins replconf (Kapitel 6).
Zustände der Datenbank:
Zustand
Gruppe in RCM
Bedeutung
CONFIGURED
Ausstehend
Firebird hat die Einstellungen gelesen, eine Replik gibt es noch nicht
PUBLISHING
Ausstehend
die Synchronisation der Publikation läuft
SEEDING
Ausstehend
die Initialisierung läuft
IN_SYNC
In Ordnung
die Replik hat alle Segmente erhalten
LAGGING
Ausstehend
die Replik hinkt hinterher, Segmente stehen in der Warteschlange
NEEDS_REINIT
Fehler
die Replik muss neu initialisiert werden
FAILED
Fehler
die letzte Initialisierung ist fehlgeschlagen
4.3. Die Replik vorbereiten
Datenbankordner der Replik
Der Replik-Knoten legt jede Datenbank in seinem eigenen Ordner databases.root unter dem Pfad ab:
Code
<databases.root>/<master node name>/<database path relative to the master root>
Beispiel: Master node-a mit Wurzel /databases/master und Datenbank
/databases/master/sales/employee.fdb. Auf der Replik node-b mit Wurzel
/databases/replica liegt die Datenbank hier:
Code
/databases/replica/node-a/sales/employee.fdb
So kollidieren Datenbanken mit denselben Namen von verschiedenen Mastern nicht.
Niemand legt den Wurzelordner automatisch an — weder das Installationsprogramm, noch HQCenter Admin, noch der Knoten beim
Start. Legen Sie ihn auf eine der folgenden Arten an:
im Fenster Initialisieren: das Feld Replikordner, die
Schaltfläche Ordner anlegen. Die Schaltfläche ist nur sichtbar, wenn der Ordner nicht existiert. Mit HQbird 2027.2.24
enthält das Feld, wenn der Replik-Knoten noch kein databases.root hat, schon
/databases/replica/<ID des Replik-Knotens>. Für eine Replik unter Windows ist das Feld leer:
geben Sie einen Ordner mit Laufwerksbuchstaben ein. Jeder Replik-Knoten auf demselben Host braucht einen eigenen
Ordner. Den Ordner legt der
Replik-Knoten an: Eigentümer — firebird (oder der Benutzer des Knotendienstes), Rechte
2770. Kann der Knoten ihn nicht anlegen, zeigt das Fenster den Befehl für den Host der
Replik. Geben Sie einen anderen Ordner an, schreibt RCM ihn vor der Initialisierung in databases.root des Replik-Knotens;
Das Bit setgid (2770) wird gebraucht, damit alle Dateien darin die Firebird-Gruppe erhalten.
Die Replikwurzel können Sie nur ändern, solange sie keine Datenbanken hat: sonst liegen die alten Datenbanken
außerhalb des Scans. Um eine einzelne Datenbank an einen anderen Ort zu legen, verwenden Sie
Verschieben auf der Datenbankseite.
Rechte
Der Replik-Knoten und Firebird müssen in die Datenbankwurzel schreiben können. Der Knoten prüft, dass
die abgelegten Dateien die Gruppe des Ordners erhalten. Kann er das nicht — lehnt er mit
ownership_unfixable ab und einem Text, wie es zu beheben ist (meist läuft der Knotendienst mit
Group=root).
Mit HQbird 2027.2.24 zeigt das Fenster Initialisieren auch einen Ordner, der
existiert, in den der Knotendienst aber nicht schreiben kann: den Text des Knotens mit dem
Korrekturbefehl und eine Schaltfläche Erneut prüfen. RCM 2027.5.7 sagt in diesem Fall
„Ordner existiert“: prüfen Sie die Rechte selbst (hqbirdrcm checkpermissions -node <replica> -root <folder>).
Firebird-Version
Die Hauptversion von Firebird auf der Replik muss zum Master passen (5.0 → 5.0,
4.0 → 4.0). Sonst lehnt die Replik ab, bevor Daten übertragen werden:
incompatible_engine.
Erreichbarkeit
Der Replik-Knoten muss ein Partner des Masters sein, und der Master ein Partner der Replik (Kapitel 2).
Sonst bietet RCM diesen Knoten im Fenster Initialisieren nicht an.
4.4. Wie viel Platz nötig ist
Kurz
Wo
Was
Wie viel
Master, Datenbankvolume
frei vor der Initialisierung
≥ 105 % der Datenbankgröße
Replik, Volume des Datenbankordners
frei vor der Initialisierung
≥ 105 % der Datenbankgröße, mit HQbird 2027.2.24 — plus free_space_floor_gb (plus die alte Datei, wenn die Replik schon existierte; mit dem Kontrollkästchen Alte Replik entfernen — ohne sie)
Master, <database>.ReplLog
Arbeitssegmente von Firebird
bis zu 64 Segmente × Segmentgröße (standardmäßig 16 MB) ≈ 1 GB je Datenbank
Master, <database>.LogArch
Archiv der Segmente für die Repliken
Änderungen über retention_days (Standard 2 Tage) + was die Repliken noch nicht bestätigt haben
Replik, <database>.Incoming
Warteschlange der anzuwendenden Segmente
bis zu 256 Segmente × 16 MB ≈ 4 GB je Datenbank im schlimmsten Fall
Replik, ganzes Volume
Reserve
mindestens free_space_floor_gb (Standard 1 GB)
Platz vor der Initialisierung prüfen
Die Initialisierung prüft den Platz zweimal und nur bevor die Datenbank gesperrt wird:
RCM — anhand der letzten Knotenstatistik, bevor der Befehl gesendet wird. Ist der Platz
offensichtlich nicht ausreichend, gibt RCM sofort den Fehler 507 zurück.
Master-Knoten — eine Live-Messung auf dem eigenen Volume, dann eine Anfrage an die Replik, damit
sie ihr eigenes misst. Fehlt auf mindestens einer Seite Platz, endet die Initialisierung
beim Schritt SPACE CHECK mit dem Fehler
insufficient disk space on master oder … on replica.
Die Anforderung auf beiden Seiten ist 105 % der Größe der Master-Datenbank.
Mit HQbird 2027.2.24 rechnet der Replik-Knoten so:
er braucht 105 % der Datenbankgröße plus das free_space_floor_gb der Replik (7.3):
nach der Initialisierung bleibt auf dem Volume eine Reserve für Segmente;
Reste früherer Initialisierungen (<database>.hqcluster-part, <database>.new)
zählen als freier Platz: der Knoten löscht sie vor der neuen Kopie;
der Fehlertext nennt alle Zahlen. Er nennt auch die Dateien
<database>.pre-reinit-*.fdb und <database>.failed-seed-*.fdb mit ihrer Größe. Der Knoten
löscht sie nie: löschen Sie sie selbst, wenn sie nicht gebraucht werden.
force (erzwungen) überspringt nur die Prüfung in RCM. Die Prüfung des Knotens
lässt sich nicht umgehen: sie schützt den Knoten davor, mitten beim Kopieren die Platte zu füllen.
Fehlt Platz nur wegen der alten Replikkopie, nennt RCM 2027.2.24 im
Fehler 507 das Kontrollkästchen Alte Replik entfernen und nicht force. Dafür
müssen beide Knoten HQbird 2027.2.24 oder neuer sein. Sonst nennt der Fehler
den Knoten, der aktualisiert werden muss, und force.
Warum so viel
Master. Während des Kopierens ist die Datenbank durch nbackup -L gesperrt. Alle
Änderungen werden in die Datei <database>.delta neben der Datenbank geschrieben. Die Größe von .delta hängt
von der Schreiblast während des Kopierens ab. Bei hoher Last und langsamer
Übertragung kann sie stark wachsen — beobachten Sie den Platz bei der ersten
Initialisierung.
Replik. Die Kopie wird direkt in die Datei <database>.hqcluster-part neben
dem Datenbankort geschrieben. Der Knoten reserviert die volle Größe im Voraus. Die Datei wird dann geprüft,
repariert (nbackup -FIXUP -SEQUENCE) und an ihren Platz umbenannt. Eine zweite
Kopie ist nicht nötig — die Datenbankgröße wird einmal gebraucht, auf dem Datenbankvolume.
Wenn die Replik schon existierte (wiederholte Initialisierung), liegt die alte Datei auf der
Platte bis zum letzten Schritt. Das heißt, die alte Datei und die neue Kopie werden auf dem Volume
gleichzeitig gebraucht. Der freie Platz wird ohne die alte Datei gerechnet — deshalb ist die Anforderung
dieselbe: 105 % der Datenbankgröße frei.
Alte Replik entfernen (mit HQbird 2027.2.24). Ist auf dem Replikvolume kein Platz
für die neue Kopie neben der alten, setzen Sie dieses Kontrollkästchen im Initialisierungsfenster
(Kapitel 5.1). Der Replik-Knoten löscht dann die alte Kopie und ihre
eingehenden Segmente (.Incoming) vor der Übertragung, und das Volume reicht für 105 % der
Datenbankgröße plus free_space_floor_gb. Der Knoten löscht die Kopie nur, wenn alle Bedingungen
zutreffen:
ohne Löschen reicht der Platz nicht, mit Löschen reicht er;
es ist eine Kopie, die die Initialisierung dieses Knotens installiert hat: der Header
ist lesbar, der Modus ist eine schreibgeschützte Replik;
die Datenbank wurde nicht zu einer normalen gemacht (keine Datei <database>.hqcluster-normal.json, Kapitel 8);
overwrite_non_replica ist nicht gesetzt (5.9).
Sonst löscht der Knoten nichts und lehnt mit dem Grund im Text ab. Zum Löschen
stoppt der Knoten das Firebird der Replik für die Dauer des Löschens (5.6).
Das Kontrollkästchen ist standardmäßig aus. Risiko: während die Übertragung läuft, gibt es keine
Datenbankkopie auf der Replik. Hat die Datenbank nur eine Replik, ist der Master die ganze
Zeit ungeschützt. Solange es keine neue Kopie gibt, ist die Datenbank auf der Replik im Zustand NEEDS_REINIT (nicht FAILED und
nicht ORPHANED), und die Replik gibt die Warnung replica_removed_for_reinit
(warn) aus. Sobald die neue Kopie an ihrem Platz ist, wird die Warnung gelöscht. Schlägt die Initialisierung
nach dem Löschen fehl, bleibt das Paar NEEDS_REINIT: starten Sie die
Initialisierung erneut (oder die automatische Neuinitialisierung startet sie, 5.8).
Eine neue Initialisierung überträgt die Datenbank von Anfang an.
Archiv des Masters (.LogArch). Der Knoten behält gesendete Segmente
retention_days Tage, damit die Replik sie erneut anfordern kann. Segmente,
die die Replik noch nicht angewendet hat, werden länger behalten. Ist der Platz knapp, räumt der Knoten
das Archiv in Stufen auf:
von allen Repliken angewendete Segmente, die älter sind als retention_days;
angewendete Segmente, die neuer sind (wenn der Platz knapp ist);
nicht angewendete Segmente — nur als letzter Ausweg. Dann verliert die Replik
die Segmente, die sie braucht, und erhält NEEDS_REINIT.
Ist eine Replik lange nicht erreichbar, wächst das Archiv. Sein Volumen = die Datenbankänderungen über die
Ausfallzeit.
Rechenbeispiel
Datenbank 100 GB. Last — 5 GB Segmente pro Tag. Die Initialisierung läuft
nachts, das Kopieren dauert 2 Stunden, in denen etwa
2 GB in .delta landen.
Wo
Rechnung
Frei insgesamt
Master, Datenbankvolume
105 GB für die Prüfungen (einschließlich des Wachstums von .delta) + .ReplLog 1 GB + .LogArch 2 Tage × 5 GB = 10 GB
≥ 116 GB
Replik, neue Datenbank
105 GB + .Incoming bis 4 GB + 1 GB Reserve
≥ 110 GB
Replik, wiederholte Initialisierung
alte Datei 100 GB schon auf der Platte + 110 GB frei
Volume ≥ 210 GB
Replik, wiederholte Initialisierung mit dem Kontrollkästchen Alte Replik entfernen (mit HQbird 2027.2.24)
alte Datei vor der Übertragung gelöscht: 105 GB + .Incoming bis 4 GB + 1 GB Reserve
Volume ≥ 110 GB
Rechnen Sie eine Reserve für das Wachstum der Datenbank und für den Ausfall der Replik hinzu (das Archiv des Masters wächst um
5 GB je Ausfalltag).
Segmente auf einem eigenen Volume
Die Ordner .ReplLog, .LogArch und .Incoming liegen standardmäßig neben der Datenbank.
Sie können auf ein anderes Volume verschoben werden: der Parameter segments.storage in node.json
(mit mirror_hierarchy: true bildet der Knoten die Struktur der Datenbankordner nach). Dann
nimmt das Archiv den Datenbanken keinen Platz weg. Die Prüfung auf 105 % gilt weiter für das Datenbankvolume.
Wo Sie den Platz sehen
Datenbanken → Knoten und Übersicht: das Symbol für den freien Platz des
Volumes databases.root. Gelb — weniger als 20 %, rot — weniger als 10 %.
Seite Datenbanken: die Spalte Platte in der Tabelle Knoten
Clusterbericht: hqbirdrcm report.
4.5. Mehrere Repliken einer Datenbank
Die zweite und die weiteren Repliken werden auf dieselbe Weise erzeugt: Initialisieren in der Master-Zeile, mit Auswahl eines freien Replik-Knotens.
Während eine neue Replik initialisiert wird, überträgt der Master diese Datenbank auch an die schon laufenden Repliken nicht. Sie holen den Master ein, nachdem die Initialisierung beendet ist. Das Bestätigungsfenster sagt das.
Eine Datenbank — eine Initialisierung gleichzeitig, auch für verschiedene Repliken.
Der Platz auf dem Master wird für jede Initialisierung getrennt geprüft.
Master-Datenbank mit zwei Repliken
4.6. Von Hand eingerichtete Replik
Läuft eine Replik schon aus einer von Hand geschriebenen replication.conf, können Sie sie unter Verwaltung nehmen und die Datenbank nicht erneut kopieren:
Master: registrieren Sie die Datenbanken mit detect_existing (Kapitel 3.6).
Replik:Datenbanken → Replik-Knoten → Übernehmen, oder hqbirdrcm takeover-replica. RCM findet die Replikblöcke, ordnet die Dateien den Master-Datenbanken nach GUID zu und zeigt für jede: in_sync, resumable oder needs_reinit.
Bestätigen Sie die Zeilen. Der Knoten verschiebt die Blöcke in seinen eigenen Bereich von replication.conf.
Starten Sie das Firebird der Replik neu, damit es die verschobenen Blöcke liest.
Initialisieren Sie nur die Zeilen needs_reinit: das Archiv des Masters enthält die Segmente, die diese Repliken brauchen, nicht mehr.
4.7. Häufige Fehler
Was Sie sehen
Ursache
Was zu tun ist
insufficient disk space on master / on replica
nicht genug Platz (4.4). Bei der Neuinitialisierung belegt die alte Kopie Platz bis zum Ende (4.4)
machen Sie Platz frei, versuchen Sie es erneut. Der zweite Ausweg auf der Replik (ab HQbird 2027.2.24) ist das Kontrollkästchen Alte Replik entfernen (4.4, 5.1)
507 von RCM sofort
nach der Platzstatistik reicht es offensichtlich nicht
dasselbe. Gibt es Platz ohne die alte Kopie, nennt RCM 2027.2.24 das Kontrollkästchen Alte Replik entfernen
incompatible_engine
unterschiedliche Firebird-Hauptversionen
aktualisieren Sie das Firebird der Replik
Ordner fehlt auf dem Replik-Knoten
die Wurzel wurde nicht angelegt
Ordner anlegen im Initialisierungsfenster (4.3)
Ordner existiert, aber der Knotendienst kann nicht hineinschreiben (ab HQbird 2027.2.24)
keine Schreibrechte
führen Sie den Befehl aus dem Fenster aus, klicken Sie auf Erneut prüfen (4.3)
publication_off (ab HQbird 2027.2.24)
die Publikation des Masters ist aus oder hat keine Tabellen
Publikation synchronisieren und initialisieren (5.1)
ownership_unfixable
der Knotendienst hat eine fremde Gruppe
korrigieren Sie die Dienstgruppe, wie der Fehlertext es beschreibt
duplicate_guid
zwei Datenbanken mit derselben GUID (eine Dateikopie)
entfernen Sie die Kopie oder geben Sie ihr eine neue GUID (nbackup -F)
Replik-Knoten nicht in der Liste Initialisieren
keine Verbindung in den Partnern
Kapitel 2
Replik IN_SYNC, aber die Daten weichen ab
die Publikation war aus
synchronisieren Sie die Publikation, dann wiederholen Sie die Initialisierung
5. Initialisierung (reinit)
Die Initialisierung ist die Übertragung einer Kopie der Master-Datenbank auf die Replik. Die erste Übertragung
heißt Initialisierung (die Schaltfläche Initialisieren), eine wiederholte Übertragung
Neuinitialisierung (die Schaltfläche Neu initialisieren). Der Mechanismus ist derselbe.
Schließen Sie vor dem Start die Schritte 1–5 aus Kapitel 4 ab:
die Datenbank ist registriert, das Firebird des Masters wurde neu gestartet, die Publikation ist eingeschaltet,
der Replikordner existiert, und es ist genug Platz da. Wie viel Platz auf dem Master und auf der
Replik nötig ist, steht in Kapitel 4.4.
5.1. So starten Sie
Zuerst die Publikation. Das Registrieren einer Datenbank schaltet die Publikation nicht ein. Ohne
Publikation erhält die Replik keine Änderungen. Führen Sie vor der Initialisierung
Publikation synchronisieren (Kapitel 6) oder
hqbirdrcm setpublication -node <master> aus.
Mit HQbird 2027.2.24 prüft das Initialisierungsfenster die Publikation. Ist
sie aus oder hat sie keine Tabellen mit Schlüssel, zeigt das Fenster eine
Warnung und eine Schaltfläche Publikation synchronisieren und
initialisieren. RCM synchronisiert die Publikation, wartet auf das Ende des Befehls und
startet die Initialisierung mit der Auswahl aus dem Fenster.
Ein Master-Knoten 2027.2.24 lehnt eine solche Initialisierung selbst ab (auch die erste)
mit dem Fehler publication_off und gibt die Meldung
master_publication_off aus (Kapitel 6.1). Nach der Ablehnung hat die Datenbankzelle wieder
die Schaltfläche Publikation synchronisieren und initialisieren.
Hat der Operator die Publikation ausgeschaltet (6.4) oder alle Tabellen mit
Schlüssel daraus entfernt (6.3), bewahrt die Synchronisation das. RCM startet die
Initialisierung nicht und gibt einen Link zur Seite Publikationstabellen.
RCM und Knoten 2027.5.7 prüfen die Publikation nicht: die Initialisierung
gelingt, die Datenbank zeigt in RCM „In Ordnung“, aber die Replik erhält keine Änderungen. Wurde
die Publikation nach der Initialisierung eingeschaltet — initialisieren Sie die Datenbank neu.
Das Fenster „Datenbank neu initialisieren?“
Öffnen Sie Datenbanken.
Klicken Sie in der Zeile der Master-Datenbank, in der Spalte des Replik-Knotens, auf Initialisieren.
Der Replik-Knoten ist durch die Spalte festgelegt: er wird im Fenster nicht ausgewählt. Für ein
bestehendes Paar — Neu initialisieren in der aufgeklappten Master-Karte.
Im Fenster (mit HQbird 2027.2.24 lautet der Titel für ein neues Paar „Datenbank
initialisieren?“; in RCM 2027.5.7 — „Datenbank neu initialisieren?“ und auch bei der
ersten Initialisierung):
prüfen Sie den Replikordner. Das Fenster zeigt, ob der Ordner existiert. Wenn nicht,
klicken Sie auf Ordner anlegen: der Replik-Knoten legt ihn an (4.3). Kann der Knoten
ihn nicht anlegen, zeigt das Fenster den Befehl für den Host der Replik. Mit HQbird
2027.2.24 zeigt das Fenster auch einen Ordner, in den der Knotendienst nicht
schreiben kann: den Korrekturbefehl und eine Schaltfläche Erneut prüfen;
wählen Sie die Reinit-Methode: Sanft (empfohlen) oder Standard
(5.4). Mit HQbird 2027.2.24, wenn das Archiv des Masters noch keine Segmente hat
(meist vor der ersten Initialisierung), zeigt das Fenster einen Hinweis: auf einer
stark belasteten Datenbank ist Standard schneller;
wartet die Master-Datenbank noch auf einen Firebird-Neustart, sagt das Fenster das und
zeigt eine Schaltfläche Firebird des Masters neu starten. Ohne den Neustart wird die Datenbank
nicht repliziert;
Alte Replik entfernen (mit HQbird 2027.2.24, standardmäßig aus)
wird nur bei der Neuinitialisierung gebraucht, wenn das Replikvolume keinen
Platz für eine neue Kopie neben der alten hat (4.4). Das Fenster zeigt die
Zahlen im Voraus: wie viel nötig ist, wie viel frei ist, wie viel die alte Kopie belegt.
Gibt es Platz ohne die alte Kopie, bittet das Fenster, das Kontrollkästchen zu setzen. Das Kontrollkästchen
ist inaktiv, wenn der Master- oder der Replik-Knoten eine alte Version ist: das Fenster nennt
den zu aktualisierenden Knoten. Bis die neue Kopie fertig ist, hat die Replik keine Kopie
dieser Datenbank (4.4).
Bestätigen Sie. RCM teilt mit, dass die Datenbank auf dem Master gesperrt und
auf die Replik kopiert wird.
Der Fortschritt der Initialisierung ist in der aufgeklappten Master-Karte auf der Seite Datenbanken
sichtbar: Schritte und Prozente. Mit HQbird 2027.2.24 ist der Fortschritt auch nach dem Aktualisieren
der Seite sichtbar: bei der ersten Initialisierung — in der Zelle des Replik-Knotens und außerdem in der
Zeile Fortschritt der Neuinitialisierung auf der Seite der Master-Datenbank. Die
Schaltfläche Initialisieren ist inaktiv, während der Master-Knoten die Datenbank kopiert. Verfolgt RCM diese
Initialisierung nicht (sie wurde zum Beispiel von der Befehlszeile des Knotens gestartet),
kommen die Schritte aus dem Knotenzustand, ohne Prozente. In RCM 2027.5.7 ist nach dem
Aktualisieren der Seite der Fortschritt der ersten Initialisierung nicht sichtbar: warten Sie, bis die Master-
Datenbank SEEDING verlässt.
Initialisierungsschritte in der Master-Zeile
Jeder RCM-Befehl (Initialisierung, Firebird-Neustart, Synchronisation der
Publikation) wird auf der Seite Befehle mit seinem Ergebnis festgehalten.
Die Seite „Befehle“
Dasselbe über die Befehlszeile
Command
# one databasehqbirdrcm reinit -node node-a -db <db_id> -to node-b
# all master databaseshqbirdrcm reinit -node node-a -all -to node-b
Parameter: -mode smooth|standard (Standard smooth), -hold=false
(das Archiv während langer Transaktionen nicht halten), -allow-restart (5.6),
-force (5.9).
-remove-old-replica (mit HQbird 2027.2.24) — dasselbe wie das Kontrollkästchen Alte
Replik entfernen. Nur für eine einzelne Datenbank: -db und -to sind erforderlich; mit
-all lehnt der Befehl ab. Ist der Master- oder der Replik-Knoten eine alte Version, lehnt RCM
mit node_too_old ab und sendet nichts.
-all versucht alle Datenbanken und sammelt die Fehler, statt beim ersten stehen zu bleiben.
5.2. Schritte
Nr.
Schritt (in RCM)
Was geschieht
1
SPACE CHECK
prüft den Platz auf dem Master und auf der Replik (Kapitel 4.4); die Replik prüft im Voraus, dass sie die Datei annehmen kann
2
LOCKING
nbackup -L: die Datenbankdatei des Masters wird eingefroren, Änderungen gehen nach <database>.delta
3
COPYING TO NODE
die Datei wird in Teilen übertragen: lesen → Prüfsumme → Kompression → senden
4
UNLOCKING
nbackup -N sofort nach der Übertragung: Änderungen aus .delta kehren in die Datenbank zurück
5
SEEDING
auf der Replik: Prüfung der Dateiprüfsumme, nbackup -FIXUP -SEQUENCE, Installation der Datei, gfix -replica, Schreiben des Blocks in replication.conf
6
RESTARTING REPLICA
Neustart des Firebird der Replik, wenn er nötig ist (5.6)
Nach Schritt 6 erhält die Datenbank den Zustand IN_SYNC. Der Master sendet weiter
Segmente ab dem Punkt, an dem die Kopie endet.
Was wichtig ist:
Der Master läuft die ganze Zeit. Benutzer schreiben in die Datenbank, Änderungen gehen nach
.delta. Die Sperre wird sofort nach der Übertragung aufgehoben.
Transaktionen, die mit der Sperre zusammenfielen, gehen nicht verloren. Der Knoten findet
die Transaktionen, die im Moment von nbackup -L offen waren, und die Replik spielt sie aus
den Segmenten nach.
Die Übertragung geht nach einer Unterbrechung weiter. Ist die Verbindung oder der Replik-Knoten
neu gestartet, setzt der Master bei dem zuletzt empfangenen Teil fort. Eine unvollendete
Übertragung bleibt auf der Replik 24 Stunden (reinit_partial_keep_hours).
Bei einem Fehler hebt der Knoten die Sperre auf, löscht die unvollendete Datei auf
der Replik und setzt die Datenbank auf FAILED. Der nächste Versuch startet aus einem bekannten
Zustand.
Mit dem Kontrollkästchen „Alte Replik entfernen“ (ab HQbird 2027.2.24) löscht die Replik
die alte Kopie nach dem Schritt LOCKING, vor der Übertragung. Der Schritt COPYING TO
NODE zeigt dann „alte Replikkopie wird entfernt, um Platz zu schaffen“. Ein Fehler nach dem Löschen gibt dem Paar NEEDS_REINIT statt FAILED
(Kapitel 4.4).
Nur nbackup. gbak wird nicht verwendet: es ändert die Datenbank-GUID.
5.3. Auswirkung auf den Betrieb
Was
Auswirkung
Benutzer des Masters
arbeiten weiter; während des Kopierens wächst .delta, nach -N werden die Änderungen in die Datenbank übernommen
Andere Repliken dieser Datenbank
erhalten keine Segmente dieser Datenbank, solange die Initialisierung läuft; danach holen sie auf
Andere Datenbanken des Masters
nicht betroffen
Firebird der Replik, neue Datenbank
wird nicht gestoppt; Neustart nach 5.6
Firebird der Replik, wiederholte Initialisierung
wird gestoppt, während die Datei ersetzt wird: alle Datenbanken dieses Firebird sind für Sekunden nicht verfügbar
Firebird der Replik, der Knoten löscht die alte Kopie (Kontrollkästchen „Alte Replik entfernen“, ab HQbird 2027.2.24)
wird früher gestoppt, während das Löschen läuft, vor der Übertragung. Der Knoten installiert die neue Kopie ohne zweiten Stopp, wenn sich der Datenbankblock in replication.conf nicht geändert hat. Reicht der Platz und ist kein Löschen nötig, löscht der Knoten nichts, und alles läuft wie bei einer gewöhnlichen wiederholten Initialisierung
Netz und Platte
Last gemäß den Geschwindigkeitsgrenzen (5.5)
Unter Windows. Eine von Firebird geöffnete Datei kann nicht ersetzt werden. Bei der wiederholten
Initialisierung stoppt der Knoten das Firebird der Replik über fbagent, installiert die
Datei und startet Firebird wieder. Unter Linux wird Firebird vor dem
Ersetzen ebenfalls gestoppt: sonst würde es mit der alten gelöschten Datei weiterarbeiten.
5.4. Sanfte und Standardmethode
Sanft (Standard). Vor dem Sperren sucht der Knoten nach langen Transaktionen: Schreibtransaktionen von Benutzern, die vor dem ältesten Segment im Archiv des Masters begonnen haben. Nach der Initialisierung kann die Replik sie nicht nachspielen und bleibt bei ihrer ersten Änderung stehen („Transaktion … wurde nicht gefunden“). Transaktionen ohne Änderungen zählen nicht.
Gibt es solche Transaktionen, startet die Initialisierung nicht: RCM zeigt Sanfte Neuinitialisierung wartet auf lange Transaktionen und einen Link Liste öffnen.
Seite Lange Transaktionen: keine langen Transaktionen
Auf der Seite Lange Transaktionen:
Zusammenfassung: wie viele Transaktionen und Verbindungen, das älteste Segment;
Top 5 Verbindungen mit den ältesten Transaktionen: Benutzer, Client, Beginn, Alter, Änderungen, aktuelle Abfrage;
Segmente halten / Halten aufheben — solange das Halten eingeschaltet ist, wird das Archiv des Masters nicht bereinigt und die Historie nicht abgeschnitten;
Ausgewählte trennen und Neuinitialisierung wiederholen — trennt die Verbindungen (ihre Transaktionen werden zurückgerollt) und startet sofort eine sanfte Neuinitialisierung;
Neuinitialisierung wiederholen, Erneut prüfen.
Das Halten wird automatisch eingeschaltet, wenn eine Neuinitialisierung wegen langer Transaktionen abgelehnt wird. Es wird nach einer erfolgreichen Initialisierung aufgehoben, von Hand, oder wenn das Archiv auf reinit_hold_max_segments anwächst (standardmäßig 1000 Segmente, Meldung retention_hold_released).
Standard sperrt die Datenbank sofort, ohne Prüfung. Verwenden Sie es nur, wenn Sie wissen, dass es keine langen Schreibtransaktionen gibt.
Erste Initialisierung unter Last. Solange das Archiv des Masters leer ist, gibt es kein Segment zum Vergleich.
Mit einem Master-Knoten HQbird 2027.2.24: hat der Knoten die Publikation selbst eingeschaltet und das Archiv sich seitdem nicht geändert, beginnt die Historie im Moment, in dem die Publikation eingeschaltet wurde. Eine später begonnene Transaktion kommt ab ihrer ersten Änderung ins Journal und stört die sanfte Methode nicht. Eine früher begonnene Transaktion kam nicht ins Journal: die Neuinitialisierung wartet vor dem Sperren auf sie (6 Versuche alle 10 s), und der Schritt locking zeigt ihre Nummer, Verbindung und den Benutzer. Ist sie nicht beendet, endet die Neuinitialisierung mit dem Fehler reinit_pre_publication_transactions: beenden Sie sie und versuchen Sie es erneut. Die Seite Lange Transaktionen zeigt solche Transaktionen in der Tabelle Transaktionen, die vor dem Einschalten der Publikation begonnen haben.
Wurde die Publikation von Hand eingeschaltet, nicht über den Knoten, oder hat sich das Archiv schon geändert, ist der Beginn der Historie unbekannt. Dann lehnt die sanfte Methode ab, wenn irgendeine Schreibtransaktion offen ist, und die Meldung sagt, dass das Archiv noch kein Segment enthält. In diesem Fall öffnet RCM 2027.2.24 die Liste nicht, sondern schreibt in die Zelle der Datenbank, was zu tun ist. Wählen Sie Standard oder versuchen Sie es erneut, sobald Firebird das erste Segment archiviert.
Mit einem Master-Knoten 2027.5.7 lehnt die sanfte Methode bei der ersten Initialisierung einer Datenbank, in die gerade geschrieben wird, sofort ab: long_transactions … segment 0 (0001-01-01T00:00:00Z). Wählen Sie für die erste Initialisierung einer solchen Datenbank Standard.
Bei späteren Neuinitialisierungen arbeitet die sanfte Methode wie gewöhnlich (das Archiv existiert schon).
Transaktionen, die älter sind als die Publikation. Firebird schreibt in die Segmente keine Transaktion, die vor dem Einschalten der Publikation begonnen hat. Hat der Knoten die Publikation eingeschaltet, wartet die Initialisierung (6 Versuche alle 10 Sekunden), bis solche Transaktionen enden; sonst endet sie mit dem Fehler reinit_pre_publication_transactions und listet sie. Verbinden Sie die Anwendungen nach der Synchronisation einer Publikation, die Tabellen hinzugefügt hat, neu, und starten Sie dann die Initialisierung.
5.5. Geschwindigkeit
Wann
Geschwindigkeit
Einstellung
Innerhalb des Übertragungsfensters windows.transfer_window (Standard 23:00-05:00)
konstant
limits.reinit_window_mbps, Standard 100 MB/s
Außerhalb des Fensters
Anteil der gemessenen Plattengeschwindigkeit
limits.reinit_day_disk_fraction, Standard 0,5
Der Knoten berechnet den Modus alle 30 Sekunden neu: eine tagsüber gestartete Initialisierung wird nachts von selbst schneller.
Der Knoten misst die Plattengeschwindigkeit mit einem Test. Um den Test auf dem Master-Host zu wiederholen:
Initialisierungszeit ≈ Datenbankgröße ÷ Geschwindigkeit. Beispiel: 100 GB bei 100 MB/s — etwa 17 Minuten reine Übertragung; in der Praxis begrenzt das Netz oder die Platte.
5.6. Das Firebird der Replik neu starten
Eine neue Datenbank auf der Replik. Die Datei wird ohne Stoppen von Firebird abgelegt. Firebird
liest den neuen Block von replication.conf erst nach einem Neustart. Bis dahin wendet die
Replik nichts an. Der Schritt RESTARTING REPLICA zeigt das Warten:
Beschriftung
Bedeutung
wartet auf einen Firebird-Neustart auf der Replik, geplant für …
der Knoten startet Firebird selbst nach der letzten Initialisierung neu (reinit_restart_delay_sec), sobald die anderen Initialisierungen beendet sind
… das Neustartfenster ist geschlossen, das nächste öffnet um …
Warten auf das restart_window der Replik
… der letzte Versuch ist fehlgeschlagen, der nächste um …
wird später erneut versucht
die Replik kann Firebird nicht selbst neu starten: starten Sie es von Hand neu
auto_restart: never, oder dieses Firebird bedient auch die Datenbanken des Masters
Der Knoten startet Firebird einmal nach einer Reihe von Initialisierungen neu, nicht nach
jeder Datenbank.
Zum Neustart von Hand klicken Sie auf Firebird der Replik neu starten.
Das Warten endet nach jedem erfolgreichen Firebird-Neustart oder wenn
die Replik ein Segment angewendet hat, das neuer ist als die Kopie.
Neuinitialisierung auf einem Firebird, das auch die Datenbanken des Masters bedient.
Der Knoten stoppt ein solches Firebird nicht selbst und lehnt mit
restart_not_allowed ab. Starten Sie die Initialisierung erneut und setzen Sie
erlauben, Firebird für diese Neuinitialisierung zu stoppen (-allow-restart auf der Befehlszeile)
— zu einer Zeit, in der die Verbindungen dieses Firebird abgeworfen werden dürfen, auch
zu seinen Master-Datenbanken. Führen Sie solche Initialisierungen je Host einzeln aus.
Das Löschen der alten Kopie (das Kontrollkästchen Alte Replik entfernen, mit HQbird
2027.2.24) stoppt ebenfalls das Firebird der Replik, nach denselben Regeln. Kann
der Knoten dieses Firebird nicht selbst stoppen, löscht er nichts und
lehnt mit restart_not_allowed ab: setzen Sie ebenfalls
erlauben, Firebird für diese Neuinitialisierung zu stoppen. Beendet zu dieser Zeit eine andere Initialisierung
auf der Replik oder startet Firebird neu, löscht der Knoten
nichts und lehnt mit engine_busy ab: der Master hebt die Sperre auf,
versuchen Sie es später erneut.
5.7. Warteschlange und gleichzeitige Initialisierungen
Eine Datenbank — eine Initialisierung gleichzeitig (auch für verschiedene Repliken). Die Schaltfläche Initialisieren ist deaktiviert, solange eine Initialisierung dieser Datenbank läuft.
Der Master-Knoten lässt limits.max_concurrent_reinits Initialisierungen verschiedener Datenbanken gleichzeitig zu (Standard 1). Der Rest wartet in der Warteschlange; die Antwort enthält die Position in der Warteschlange.
Führen Sie während der Initialisierung einer Datenbank kein eigenes nbackup -L (oder ALTER DATABASE BEGIN BACKUP) auf ihr aus, und starten Sie keine Initialisierung während einer solchen Sicherung: eine Datenbank kann nur eine Sperre haben. Die Initialisierung prüft das und lehnt mit nbackup backup lock already active ab.
Die Warteschlange und die aktuellen Übertragungen sind auf der Seite Übertragung sichtbar.
Seite Übertragung / Warteschlangen
- Bleibt nach einem Fehler eine Datei `.delta`, stellen Sie sicher, dass keine Sicherung läuft, und führen Sie `nbackup -N ` aus. Löschen Sie die `.delta` nicht von Hand.
5.8. Automatische Neuinitialisierung
RCM kann eine Datenbank im Zustand NEEDS_REINIT selbst neu initialisieren, nur innerhalb
eines eingestellten Fensters. Standardmäßig aus.
Wenn eine Datenbank nach NEEDS_REINIT geht:
Ursache
Wo es sichtbar ist
wiederkehrender nicht behebbarer Anwendefehler (Verletzung von PK, UNIQUE, FK) — 3-mal hintereinander
Replik, Warnung replication_unrecoverable_error
die GUID der Master-Datenbank hat sich geändert (Wiederherstellung, Dateiaustausch)
Replik, Warnung replication_guid_mismatch
das Archiv des Masters enthält die Segmente, die die Replik braucht, nicht mehr
Master
die Replik hat die alte Kopie für die Initialisierung gelöscht, und es gibt noch keine neue Kopie (ab HQbird 2027.2.24)
Fenster: je Datenbank → je Knoten → global. "always" — jederzeit.
Die Fenster werden nach der Uhr des RCM-Hosts gerechnet.
max_concurrent — wie viele Initialisierungen (von Hand und automatisch) im
Cluster laufen dürfen, damit RCM eine weitere automatische startet.
Die automatische Initialisierung durchläuft dieselben Prüfungen von Platz und GUID wie die
Initialisierung von Hand. Der Autor des Befehls ist system:autoreinit.
remove_old_replica_when_short (ab HQbird 2027.2.24, die Zeile Alte
Replik entfernen, wenn der Platz nicht reicht) — standardmäßig aus. Ist es
eingeschaltet, sendet die automatische Initialisierung das Kennzeichen Alte Replik
entfernen (4.4). RCM sendet es nur, wenn die Replik selbst in
NEEDS_REINIT ist oder die Ursache NEEDS_REINIT des Masters sie nennt. Für
eine Replik, die IN_SYNC oder LAGGING ist, wird das Kennzeichen nie gesendet. Ist der Knoten
eine ältere Version, startet RCM dieselbe Initialisierung ohne das Kennzeichen.
Starten Sie RCM nach der Änderung neu.
Zurückstellen in der Karte des Masters schaltet die automatische
Initialisierung einer einzelnen Datenbank für 1 Stunde, 4 Stunden, 24 Stunden oder bis zum Abbruch aus. Die Initialisierung
von Hand bleibt verfügbar.
5.9. Fehler
Fehler
Ursache
Was zu tun ist
insufficient disk space on master / on replica, 507
nicht genug Platz. Bei der Neuinitialisierung belegt die alte Kopie Platz bis zum Ende
Kapitel 4.4; auf der Replik (ab HQbird 2027.2.24) — das Kontrollkästchen Alte Replik entfernen (5.1)
node_too_old (ab HQbird 2027.2.24)
das Kontrollkästchen Alte Replik entfernen ist gesetzt, aber der Master- oder der Replik-Knoten ist eine alte Version
aktualisieren Sie den Knoten, wie der Fehlertext es sagt, oder führen Sie es ohne das Kontrollkästchen aus
engine_busy, reclaim_in_progress (ab HQbird 2027.2.24)
die Replik kann die alte Kopie gerade nicht löschen: Firebird oder diese Datenbank ist beschäftigt
später erneut versuchen (5.6)
replica_removed_for_reinit, Paar NEEDS_REINIT (ab HQbird 2027.2.24)
die Replik hat die alte Kopie gelöscht, aber die Initialisierung ist nicht zu Ende gegangen
Initialisierung erneut starten (4.4)
publication_off (ab HQbird 2027.2.24)
die Publikation des Masters ist aus oder enthält keine Tabellen mit Schlüssel
Publikation synchronisieren und initialisieren (5.1)
long_transactions, „Sanfte Neuinitialisierung wartet auf lange Transaktionen“
lange Schreibtransaktionen sind offen
5.4
long_transactions, „das Archiv des Masters enthält noch kein einziges Segment“
erste Initialisierung unter Last
Standard (5.4)
reinit_pre_publication_transactions
Transaktionen, die vor dem Einschalten der Publikation begonnen haben
die Anwendungen neu verbinden, erneut versuchen
duplicate_guid
zwei Master-Datenbanken mit derselben GUID
die Kopie entfernen; wurde der Schritt NEW GUID bei der Beförderung zum Master übersprungen — -force (Kapitel 8.4)
license_paused
der fbagent des Masters hat keine Lizenz
Kapitel 2.8
409 orphaned
die Datenbank liegt außerhalb des Scans des Masters
Kapitel 3.8
incompatible_engine
unterschiedliche Firebird-Hauptversionen
Kapitel 4.3
target_not_replica
an der Stelle der Replik liegt eine arbeitende Datenbank (sie wurde normal gemacht)
siehe unten
target_other_replica (ab HQbird 2027.2.24)
an der Stelle der Replik liegt eine Kopie einer anderen Datenbank dieses Knotens
siehe unten
restart_not_allowed
das Firebird der Replik bedient auch Master-Datenbanken
5.6, das Kontrollkästchen „… erlauben, Firebird zu stoppen“
fbagent_required
fbagent ist auf der Replik nicht installiert
Kapitel 1
nbackup backup lock already active
eine nbackup-Sicherung läuft
5.7
… -L did not finish in 2m0s and was stopped
nbackup -L auf dem Master ist nicht innerhalb von 2 Minuten zu Ende gegangen, deshalb hat der Knoten es gestoppt
erneut versuchen; kehrt der Fehler wieder, prüfen Sie das Firebird des Masters (firebird.log)
reinit already in progress for this database
die Initialisierung dieser Datenbank läuft schon
auf das Ende warten
target_not_replica. An der Stelle der Kopie liegt eine arbeitende Datenbank: sie wurde
normal gemacht (die Datei <database>.hqcluster-normal.json existiert) oder sie ist nicht im
Replikmodus. Der Knoten überschreibt eine arbeitende Datenbank nicht. Muss sie ersetzt werden, ersetzt eine Anfrage an die API des Knotens mit
overwrite_non_replica: true (dafür gibt es in RCM keine Schaltfläche) die Datei und behält die alte als
<database>.pre-reinit-<UTC-Zeit>.fdb.
target_other_replica (ab HQbird 2027.2.24). Die Replik legt die Kopie in
<databases.root>/<master id>/<database path> ab. Die Master-ID ist nur innerhalb
ihres eigenen Clusters eindeutig, deshalb können zwei Datenbanken denselben Pfad erhalten. Der Replik-Knoten
überschreibt keine Kopie, die zu einer anderen seiner Datenbanken gehört: der Fehler nennt diese Datenbank und ihren
Master. Der Knoten erkennt auch eine Kopie, deren Pfad anders aufgezeichnet ist (ein symbolischer Link oder
eine Junction im Pfad, ein kurzer Windows-Ordnername). overwrite_non_replica hebt diesen Fehler nicht auf. Verschieben Sie eine der
Kopien in einen anderen Ordner oder entfernen Sie diese Datenbank von der Replik, und starten Sie die
Initialisierung erneut. Der Knoten sieht nur seine eigenen Datenbanken: zwei Replik-Knoten auf
demselben Host müssen verschiedene Replikordner haben (databases.root).
5.10. So prüfen Sie das Ergebnis
Datenbanken: das Paar Master — Replik in der Gruppe In Ordnung, Zustand
IN_SYNC.
Prüfen in der Karte des Masters: die Knoten zählen die Zeilen der Tabellen aus
der Tabellenliste der Datenbank (Kapitel 3.1) auf dem Master und auf der Replik und vergleichen sie.
Prüfen Sie in einer ruhigen Zeit: bei aktivem Schreiben können die Zahlen abweichen.
Mit HQbird 2027.2.24 nennt die Ergebnisseite die Liste jeder Seite
(zum Beispiel „eigene Liste dieser Datenbank“ oder „Publikationstabellen
(Liste nicht gesetzt)“). RCM zählt die Replik mit der Liste des Masters. Eine Tabelle,
die in beiden Datenbanken fehlt, wird als „nicht in der Datenbank“ gezeigt und zählt nicht als
Fehler. Wurden keine Tabellen verglichen, lautet das Ergebnis „Keine Tabellen zum
Vergleich“, keine Abweichung. Ist der Vergleich nicht innerhalb der vorgesehenen Zeit zu Ende gegangen,
lautet das Ergebnis „Nicht verglichen (Zeitlimit)“, was ebenfalls keine Abweichung ist.
Periodische Prüfung (optional): die Seite Datenprüfung,
Für alle Knoten einschalten. Mit HQbird 2027.2.24 wendet der Knoten
die Einstellungen sofort an, ein Neustart des Knotendienstes ist nicht nötig: nach Speichern schreibt RCM
„Gespeichert und schon wirksam“. Der Knoten 2027.5.7 braucht einen Neustart des
Dienstes hqclusternode, und RCM 2027.2.24 sagt das.
Die Knoten vergleichen die Zeilenzahlen selbst, wenn Master und Replik auf demselben
Segment sind. Eine Abweichung löst die Warnung data_mismatch aus; führen Sie dann
Prüfen aus.
Eine Tabelle, die der Operator aus der Publikation entfernt hat, wird als „nicht
veröffentlicht“ gezeigt, nicht als Abweichung.
6. Publikation einrichten
Die Publikation sagt dem Firebird-Master, die Änderungen welcher Tabellen in die Segmente zu schreiben sind.
Ohne sie erhält die Replik nichts.
6.1. Was die Publikation ist
In Firebird 4 und 5 bestimmt die Publikation RDB$DEFAULT die zu replizierenden Tabellen:
Publikation eingeschaltet — in RDB$PUBLICATIONS hat sie RDB$ACTIVE_FLAG = 1
(der Befehl ALTER DATABASE ENABLE PUBLICATION).
Veröffentlichte Tabellen — die Liste in RDB$PUBLICATION_TABLES.
Firebird schreibt Änderungen in die Segmente nur für veröffentlichte Tabellen und nur,
wenn die Publikation eingeschaltet ist. Das Registrieren der Datenbank (Kapitel 3) schaltet die
Publikation nicht ein. Eingeschaltet wird sie durch Publikation synchronisieren (6.2).
Der Master-Knoten prüft die Publikation jede Stunde
(limits.publication_check_interval_sec, Standard 3600). Ist sie
aus, prüft der Knoten sie alle 2 Minuten.
Auf der Seite Datenbanken hat die Master-Datenbank ein Symbol:
Symbol
Bedeutung
Publikation EIN
Publikation eingeschaltet
Publikation AUS
Firebird schreibt nichts in die Segmente, die Repliken erhalten keine Änderungen
Publikation unbekannt
der Knoten konnte den Zustand nicht lesen
Der Filter Publikation aus zeigt Datenbanken mit ausgeschalteter oder unbekannter
Publikation.
Hat eine Datenbank mit ausgeschalteter Publikation schon eine Replik, gibt der Master
die Warnung master_publication_off aus.
Mit HQbird 2027.2.24 gibt der Master diese Warnung auch aus, wenn er die
Initialisierung einer Datenbank mit dem Fehler publication_off abgelehnt hat (Kapitel 5.1): die Publikation
ist aus oder enthält keine Tabelle mit Schlüssel. Die Stufe der Warnung:
warn — die Datenbank hat noch keine Replik: die Initialisierung wartet auf die Publikation;
serious — die Datenbank hat schon eine Replik;
info — der Operator hat die Publikation ausgeschaltet.
Die Warnung wird gelöscht, wenn die Publikation korrigiert ist oder eine andere
Initialisierung begonnen hat.
6.2. Publikation synchronisieren
Master-Zeile: Publikation ausgeschaltet
Wo Sie klicken:
in der Zeile der Master-Datenbank auf der Seite Datenbanken. Ist die Publikation
ausgeschaltet, steht die Schaltfläche neben dem Symbol;
auf der Datenbankseite;
für mehrere Datenbanken: haken Sie die Zeilen an, wählen Sie in der Liste AktionPublikation synchronisieren. RCM sendet für jede
Datenbank einen eigenen Befehl.
Bestätigung der Publikationssynchronisation
Was der Knoten tut (eine einzige Transaktion):
Schaltet die Publikation ein. Hat der Operator sie selbst ausgeschaltet (6.4), schaltet er sie nicht ein.
Fügt der Publikation alle Tabellen mit Schlüssel hinzu, die noch nicht darin sind.
Entfernt aus der Publikation Tabellen ohne Schlüssel und Tabellen, die der Operator
ausgeschlossen hat (6.3).
Schaltet das automatische Hinzufügen neuer Tabellen aus (EXCLUDE ALL FROM PUBLICATION, dann fügt er die nötigen Tabellen hinzu). Nur der Knoten bestimmt die
Zusammensetzung der Publikation.
Master-Zeile nach der Synchronisation: Publikation eingeschaltet
Eine Tabelle mit Schlüssel — eine dauerhafte Benutzertabelle, die einen
Primärschlüssel oder einen aktiven eindeutigen Index hat. System- und temporäre
Tabellen werden nicht veröffentlicht.
Die Synchronisation entfernt aus der Publikation auch Tabellen ohne Schlüssel, die der DBA
von Hand hinzugefügt hat.
Ist die Zusammensetzung schon richtig, ändert der Knoten nichts.
Wann der Knoten ablehnt:
Code
Grund
no_publications
HQbird 2.5/3.0 (6.6)
not_master
der Knoten ist nicht der Master
reinit_in_progress
die Initialisierung dieser Datenbank läuft
orphaned, database_failed, file_missing
die Datenbank liegt außerhalb des Scans, ist im Fehler, oder hat keine Datei
Alle Datenbanken des Knotens auf einmal — nur über die Befehlszeile. Auf der Seite Befehle
wird das Ergebnis je Datenbank gezeigt: erledigt, übersprungen oder Fehler.
Datenbanken im Zustand FAILED oder SEEDING und Datenbanken ohne Datei werden übersprungen.
Dasselbe über die Befehlszeile
Command
hqbirdrcm setpublication -node node-a -db <db_id> # one databasehqbirdrcm setpublication -node node-a # all node databases
Der Befehl wartet bis zu 5 Minuten und gibt für jede Datenbank eine Zeile aus. Bei einem Fehler ist der Exitcode
-nowait — nicht auf das Ergebnis warten.
6.3. Publikationstabellen
Die Seite „Publikationstabellen“
Öffnen Sie Publikationstabellen in der Zeile der Master-Datenbank.
Die Seite zeigt:
den Zustand der Publikation (ein/aus, vom Operator ausgeschaltet) und die Zähler;
jede Tabelle: Name, Schlüssel und Zustand.
Zustand
Bedeutung
veröffentlicht
Änderungen gehen in die Segmente
noch nicht veröffentlicht
eine Tabelle mit Schlüssel, wird bei der Synchronisation hinzugefügt
ausgeschlossen
der Operator hat sie aus der Publikation entfernt
kein Schlüssel
kann nicht veröffentlicht werden
In der Schlüsselspalte — der Primärschlüssel oder, wenn es keinen gibt, der eindeutige Index mit
der kleinsten Feldzahl.
Warum eine Tabelle ohne Schlüssel nicht veröffentlicht werden kann. Die Replik sucht die Zeile für
UPDATE und DELETE über den Schlüssel. Ohne Schlüssel findet sie die Zeile nicht. Fügen Sie einen
Primärschlüssel oder einen eindeutigen Index hinzu und synchronisieren Sie dann die Publikation.
Aus der Publikation ausschließen / In die Publikation zurückholen:
Haken Sie die Tabellen an.
Klicken Sie auf Aus der Publikation ausschließen oder In die Publikation zurückholen.
Der Knoten speichert die Liste und synchronisiert die Publikation sofort.
Bestätigung von „Aus der Publikation ausschließen“
Die Liste der ausgeschlossenen Tabellen wird auf dem Master-Knoten gespeichert. Die Synchronisation
ändert sie nicht. Wenn eine Replik zum Master befördert wird (Kapitel 8), wandert die Liste zum
neuen Master.
Prüfen (Kapitel 5.10) zeigt eine ausgeschlossene Tabelle als „nicht veröffentlicht“,
nicht als Abweichung.
6.4. Publikation ein- und ausschalten
Auf der Seite Publikationstabellen: Publikation ausschalten /
Publikation einschalten.
Das Ausschalten ist die Entscheidung des Operators. Die Synchronisation schaltet die
Publikation nicht wieder ein.
Änderungen, die gemacht wurden, während die Publikation aus war (oder während eine Tabelle
ausgeschlossen war), werden nicht an die Replik gesendet, auch nicht nach dem Einschalten.
Klicken Sie nach dem Einschalten auf Prüfen (Kapitel 5.10). Weichen die Daten
ab — initialisieren Sie die Replik neu (Kapitel 5).
6.5. Eine neue Tabelle
Eine neue Tabelle kommt nicht von selbst in die Publikation: der Knoten schaltet das
automatische Hinzufügen aus.
Nach dem DDL:
Legen Sie einen Primärschlüssel oder einen eindeutigen Index auf der Tabelle an.
Klicken Sie auf Publikation synchronisieren.
Bitten Sie die Anwendungen, sich neu zu verbinden, wenn eine Neuinitialisierung nötig ist. Firebird
schreibt in die Segmente keine Transaktionen, die vor dem Einschalten der Publikation begonnen haben;
COMMIT RETAINING hält eine solche Transaktion offen. Die Initialisierung wartet auf
solche Transaktionen und scheitert dann mit reinit_pre_publication_transactions
(Kapitel 5.4).
Eine neue Tabelle im Zustand „noch nicht veröffentlicht“
Zeilen, die vor der Synchronisation in die neue Tabelle geschrieben wurden, erreichen die Replik nicht.
Gibt es welche, prüfen Sie die Daten und initialisieren Sie die Replik bei Bedarf neu.
6.6. HQbird 2.5 und 3.0
HQbird 2.5 und 3.0 haben keine Publikationen. Firebird schreibt Segmente, wenn die
Datei des Plugins replconf einen Master-Block enthält. Die Publikationsschaltflächen auf solchen Knoten sind verborgen,
und die API antwortet mit no_publications.
Die Tabellenmenge bestimmen die Engine-Parameter:
Parameter
Bedeutung
include_filter
welche Tabellen repliziert werden: Namen oder Muster, durch Kommas getrennt; leer — alle
exclude_filter
welche Tabellen nicht repliziert werden
Die Parameter werden unter Einstellungen → Replikationsparameter geändert (Kapitel 7.1). Die
Seite Publikationstabellen zeigt sie nur zum Lesen, mit einem Link In den
Engine-Einstellungen ändern. Firebird liest die neuen Werte nach einem Neustart.
Publikationstabellen auf HQbird 3.0: Engine-Filter
Das Plugin replconf. Der Knoten schreibt seine eigene Datei replconf.hqcluster.hqbird im
Firebird-Ordner. Firebird liest sie nur, wenn replconf.properties auf
sie zeigt. Das Plugin muss einmal aktiviert werden:
Einstellungen → Knoten, der Block Replikations-Plugin (HQbird 2.5 / 3.0). Der Block
zeigt, wohin replconf.properties zeigt, und die Probleme, die der Knoten
gefunden hat.
Plugin nicht aktiviert: replconf.properties zeigt auf die HQbird-DataGuard-Datei
Aktivieren… Das Fenster listet, was der Knoten tun wird: das Plugin installieren,
replconf.properties auf die Datei des Knotens zeigen lassen, die Einträge der alten Datei übernehmen.
Wählen Sie wann: Nur innerhalb des Knoten-Neustartfensters oder Jetzt, das
Neustartfenster ignorieren.
Fenster zur Plugin-Aktivierung
Nach dem Neustart von Firebird zeigt das Feld Aktiviert „ja: die Engine
liest die Datei des Knotens“.
Plugin aktiviert
Die Aktivierung startet Firebird neu und betrifft alle Datenbanken dieses Firebird.
Führen Sie sie in einer ruhigen Zeit aus.
Die Seite Einstellungen → Replikationsparameter ändert die Schlüssel in
replication.conf für die ausgewählten Datenbanken oder für den Knoten als Ganzes.
Master und Repliken hinzufügen — wählen Sie die Datenbanken. RCM gruppiert sie nach
Firebird-Version und Rolle: ein eigenes Formular für Master und für Repliken.
Wählen Sie für jeden Parameter eine Aktion:
Aktion
Was sie tut
keine Änderungen
der Wert wird nicht geändert
Wert setzen
ein neuer Wert
zurücksetzen (auf die nächste Ebene)
den eigenen Wert entfernen, den Wert der Ebene darüber nehmen
nicht schreiben (Firebird-Wert)
der Schlüssel wird nicht geschrieben, der Firebird-Wert gilt
Wählen Sie, wo es gilt: Auf die ausgewählten Datenbanken oder Als Standard
für ihre Knoten.
Vorschau — die Knoten prüfen die Werte, ohne etwas zu ändern.
Vorschau der Änderungen
Anwenden. RCM sendet den Befehl an jeden Knoten.
Woher der Wert kommt (die Spalte Aktuell):
Quelle
Wert
diese Datenbank
für die Datenbank gesetzt
Knotenwert
als Standard für den Knoten gesetzt
eingebauter Knotenwert
der Knotenwert aus dem Code
Firebird-Wert
der Schlüssel wird nicht geschrieben
aus der Datei (hier noch nicht gesetzt)
der Wert aus replication.conf, RCM hat ihn noch nicht geändert
vom Knoten gesetzt
nur lesbar (Pfade, Präfixe)
Ein Knoten, der nicht antwortet, zeigt seine Datenbanken als nicht auswählbar.
Änderungen brauchen fbagent (sonst fbagent_required).
Wer Firebird neu startet (Firebird liest replication.conf nur beim
Start):
Knoten
Wer
Master
Sie starten ihn neu: der Master startet Firebird nie selbst neu
Replik mit firebird.auto_restart: never
Sie
Replik, deren Firebird auch die Datenbanken des Masters bedient
Sie
andere Repliken
der Knoten startet es neu in seinem eigenen Neustartfenster
Für einen Neustart von Hand hat die Seite eine Schaltfläche Firebird neu starten.
7.2. Die wichtigsten Parameter
Master, Firebird 4/5:
Parameter
Beschriftung in RCM
Knotenwert
Firebird
Hinweis
journal_archive_timeout
Archiv-Timeout
10 s
60 s
wie viele Sekunden Firebird wartet, bevor es ein unvollständiges Segment schließt. Niedriger — die Replik ist näher am Master. Muss kleiner sein als limits.data_check_quiet_sec (90)
journal_segment_count
Anzahl der Segmente
64
8
wie viele Segmente in .ReplLog liegen können. Muss größer sein als limits.backlog_critical (48)
journal_segment_size
Segmentgröße
—
16 MB
von 1 MB bis 512 MB; der Empfänger nimmt nicht mehr als 512 MB an
buffer_size
—
1 MB
Der Knoten schreibt außerdem log_errors = true (kann nicht geändert werden) und
disable_on_error = true.
Replik, Firebird 4/5:
Parameter
Beschriftung in RCM
Firebird
Wert
apply_idle_timeout
Leerlaufpause
10 s
Pause, wenn es keine neuen Segmente gibt
apply_error_timeout
Pause nach Anwendefehler
60 s
Pause vor einem erneuten Versuch nach einem Fehler
verbose_logging
Knoten: true
ausführliches replication.log; Abschalten wird nicht empfohlen
skip_upddel_without_pk
Knoten: true
UPDATE/DELETE auf Tabellen ohne Schlüssel überspringen
Nur Firebird 5: include_filter, exclude_filter, cascade_replication.
HQbird 2.5/3.0 — Schlüssel log_* mit derselben Bedeutung: log_archive_timeout,
log_segment_count, log_segment_size (nicht kleiner als 2 × buffer_size). Der
Schlüssel alert_command wird nur in node.json gesetzt.
Ein Hinweis zu jedem Parameter steht im RCM-Formular.
7.3. Archivaufbewahrung
Das Archiv <database>.LogArch auf dem Master wird in Stufen aufgeräumt:
Segmente, die von allen Repliken angewendet wurden und älter sind als
retention_days.
Ist der freie Platz kleiner als free_space_floor_gb — angewendete Segmente,
die jünger sind als die Aufbewahrungsfrist. Warnung disk_serious_cleanup.
Ist der Platz immer noch knapp — nicht angewendete Segmente, beginnend mit den ältesten.
Die Replik erhält NEEDS_REINIT, Warnung
replication_paused_reinit_scheduled.
Parameter (Einstellungen → Knoten, Speicher und Dateien)
Standard
limits.retention_days — Archivaufbewahrung, Tage
2
limits.retention_min_kept_segments — Die letzten Segmente immer behalten
0 (aus)
limits.free_space_floor_gb — Minimaler freier Platz
1 GB
Einstellungen → Knoten, „Speicher und Dateien“
Das Archiv von Hand aufräumen:
Command
hqbirdrcm cleanuparchive -node node-a # stages for all databases on the nodehqbirdrcm cleanuparchive -node node-a -db <db_id> # a single database
-orphaned (nur zusammen mit -db) löscht alle Segmente der Datenbank im
Zustand ORPHANED (Kapitel 3.8). Für jede andere Datenbank antwortet der Knoten not_orphaned.
Führen Sie -orphaned auf dem Spender der Beförderung nie aus (Kapitel 8.5).
Die Beschriftung neben jedem Feld zeigt, wann die Änderung gilt: sofort oder
Knoten-Neustart.
Einstellungen → Knoten, „Zeitfenster“
7.5. Datenprüfung
Prüfen — ein einmaliger Vergleich der Zeilenzahl auf dem Master und der Replik
(Kapitel 5.10).
Datenprüfung — ein periodischer Vergleich (Kapitel 5.10). Der Knoten führt den Vergleich
aus, wenn Master und Replik auf demselben Segment sind.
Mit HQbird 2027.2.24 gelten die Prüfungseinstellungen sofort nach
Speichern; ein Neustart des Knotendienstes ist nicht nötig. RCM zeigt „Gespeichert und schon
wirksam“. Nach dem Einschalten läuft die erste Prüfung nach einem Intervall. Nach dem
Ausschalten wird eine laufende Prüfung abgebrochen und schreibt nichts. Das neue
Intervall wird vom Ende der letzten Prüfung gezählt. Behalten, Tage, Abfrage-
limit, Ruhe und Fortschrittsgenerator gelten ab der nächsten
Prüfung.
Der Knoten 2027.5.7 liest diese Einstellungen nur beim Start: starten Sie nach
Speichern den Dienst hqclusternode auf diesem Knoten neu. RCM
2027.2.24 zeigt „Gespeichert, aber noch nicht wirksam“ und nennt den Grund.
Welche Tabellen verglichen werden, bestimmt die Tabellenliste der Datenbank (Kapitel 3.1). Mit HQbird
2027.2.24 kann jede Datenbank eine eigene Liste haben: das Feld bei der Registrierung oder der
Block Tabellen zur Synchronisationsverfolgung auf der Datenbankseite des Masters
(Kapitel 3.3). Die Seite Datenprüfung zeigt, welche Liste
verwendet wurde, und die Zahl der Tabellen „nicht in der Datenbank“. In 2027.5.7 ist die Liste je Knoten
(sync_tables).
Aus der Publikation ausgeschlossene Tabellen werden als „nicht veröffentlicht“ gezeigt
(Kapitel 6.3).
Seite Datenprüfung
7.6. Warnungen
Seite Warnungen
Die Seite Warnungen. Aktionen:
Bestätigen — die Warnung bleibt sichtbar, ist aber als bestätigt markiert;
60 Min. stummschalten — eine Stunde ausblenden;
Löschen / Alle mit diesem Code löschen — RCM gibt das Löschen an den Knoten weiter,
der die Warnung ausgelöst hat. Bleibt die Ursache, erscheint die Warnung wieder.
Command
hqbirdrcm clearalerts -code backlog_warn # also -id, -acked, -all
Ab HQbird 2027.2.33 sendet RCM Warnungen an Telegram, an einen Webhook (Slack,
Teams, JSON) und per E-Mail. Die Kanäle werden im Abschnitt notify.channels
der Datei rcm.json eingestellt. Der Block Benachrichtigungskanäle auf der
Seite Warnungen zeigt die Kanäle und sendet eine Testnachricht. RCM meldet
Probleme der Stufe warn und höher: ein Problem ist aufgetreten, ist ernster
geworden oder wurde behoben. Ohne Kanäle sendet RCM nichts. Frühere
Versionen senden nicht: beobachten Sie die Seite Warnungen oder fragen Sie die RCM-API ab.
Die wichtigsten Codes:
Code
Bedeutung
backlog_warn / backlog_critical
32 / 48 nicht archivierte Segmente in .ReplLog
disk_serious_cleanup
das Archiv wird in Stufe 2 aufgeräumt (7.3)
replication_paused_reinit_scheduled
nicht angewendete Segmente gelöscht, Initialisierung erforderlich
Firebird läuft nicht oder schreibt Fehler ins Protokoll
firebird_not_answering
ab HQbird 2027.2.30: Firebird hat eine Minute lang nicht auf eine Datenbankverbindung geantwortet (Hänger). Dazu gehört auch eine Verbindung, die wegen eines Timeouts nicht zustande kam; firebird_down ist nur eine Verbindungsablehnung
master_publication_off
die Publikation ist aus (Kapitel 6); ab HQbird 2027.2.24 auch nach einem Fehlschlag publication_off (Kapitel 6.1)
replica_removed_for_reinit
ab HQbird 2027.2.24: die Replik hat die alte Kopie für die Initialisierung gelöscht, und es gibt noch keine neue Kopie (Kapitel 4.4)
orphaned_database
Datenbank außerhalb des Scans (Kapitel 3.8)
restart_required_after_reinit
das Firebird der Replik braucht einen Neustart (Kapitel 5.6)
data_mismatch
die periodische Prüfung hat eine Abweichung gefunden
license_paused
fbagent hat keine Lizenz (Kapitel 2.8)
7.7. Versand anhalten
Auf der Seite Datenbanken, in der Master-Zeile: Versand anhalten /
Versand fortsetzen. Für mehrere Datenbanken — über die Liste Aktion.
Bestätigung des Anhaltens des VersandsMaster-Zeile während einer Pause
Die Pause gilt bis Versand fortsetzen oder bis zur Initialisierung.
Das Firebird des Masters schreibt weiter Segmente. Das Archiv .LogArch wächst: solange
die Replik gestoppt ist, löscht Stufe 1 (7.3) ihre Segmente nicht.
Eine lange Pause kann Stufe 3 und NEEDS_REINIT erreichen. Behalten Sie den Platz im Auge.
Die Schaltfläche fehlt, wenn die Datenbank keine Replik hat oder die Publikation aus ist. Das
Symbol Pause: keine Lizenz bedeutet eine Pause wegen der Lizenz (Kapitel 2.8); sie wird
nur durch eine Lizenz aufgehoben.
7.8. Protokolle
Protokoll
Wo
Knoten
<installation folder>/logs/node-YYYYMMDD.jsonl (/opt/hqclusternode oder C:\hqclusternode), je 32 MB, 20 Dateien
Firebird replication.log, firebird.log
Pfade in node.json: firebird.replication_log, firebird.firebird_log
RCM
Linux: journalctl -u hqbirdrcm
RCM-Audit
rcm-data/audit.jsonl
Protokoll eines entfernten Knotens — die Seite Protokolle: wählen Sie einen Knoten und eine Quelle
(replication.log, firebird.log, Knotenagent).
8. Wie eine Replik zu einer normalen Datenbank wird
Es gibt zwei Wege:
Weg
Wann
Was Sie erhalten
Normal machen, 8.1
Sie brauchen eine eigene Arbeitskopie: Berichte, Tests, ein Ausfall ohne neuen Master
eine gewöhnliche Datenbank außerhalb der Replikation
Zum Master befördern, 8.3
die Replik soll der neue Master werden
eine Datenbank, die ein Begleiterknoten mit der Rolle Master verwaltet
Keiner der Wege lässt sich über die Oberfläche rückgängig machen.
8.1. Normal machen
Liste „Aktion“ der Replik: der Eintrag „Normal machen“
Datenbanken, Seite der Replik: haken Sie die Replikzeilen an.
Wählen Sie in der Liste AktionNormal machen und bestätigen Sie.
In der Zeile gibt es keine eigene Schaltfläche. Einen Befehl für die Befehlszeile gibt es auch nicht.
Bestätigung von „Normal machen“
3. Der Replik-Knoten:
- führt `gfix -replica none` aus (HQbird 2.5/3.0: `gfix -replica {}`). Ist
die Datenbank mit dem Anwenden von Segmenten beschäftigt, versetzt der Knoten sie für ein paar Sekunden in
`single`-Shutdown (`gfix -shut single -force 0`), hebt den Replikmodus auf und
bringt sie mit `gfix -online normal` zurück. **Alle Verbindungen zu dieser Datenbank
werden abgeworfen**;
- schreibt die Markierungsdatei `.hqcluster-normal.json` (Zeit, Autor, db_id,
GUID);
- beginnt, die Warteschlange `.Incoming` zu leeren (8.2).
4. RCM zeigt die Datenbank in der Gruppe **Keine Replik (normal)**.
Die Seite „Datenbanken“ nach „Normal machen“
Danach ist die Datenbank zum Schreiben geöffnet.
Entfernen Sie den Replikblock aus replication.conf. Der Knoten entfernt ihn beim nächsten
Scan, und Firebird liest die Datei beim Start:
Bis dahin werden Fehler „Datenbank ist nicht im Replikmodus“ für diese Datenbank nicht
als Warnungen ausgelöst.
Die Markierungsdatei schützt die Datenbank. Die Initialisierung überschreibt eine solche Datenbank nicht:
sie wird mit target_not_replica abgelehnt (Kapitel 5.9). Nur die Markierung zu löschen reicht nicht:
der Knoten prüft auch den Replikmodus im Datenbankheader. Das Kontrollkästchen Alte
Replik entfernen (Kapitel 4.4) löscht eine solche Datenbank ebenfalls nicht.
Mit HQbird 2027.2.24 wird Normal machen abgelehnt, solange die Replik die alte Kopie dieser Datenbank für die
Initialisierung löscht, mit reclaim_in_progress:
versuchen Sie es später erneut.
Soll die Datenbank wieder eine Replik werden — das geht nur mit einer neuen Initialisierung mit
Überschreiben. Das geschieht über die API des Knotens (overwrite_non_replica: true); eine solche Schaltfläche gibt es in
RCM nicht. Die alte Datei wird als
<database>.pre-reinit-<UTC-Zeit>.fdb gespeichert, und die Markierung wird gelöscht.
8.2. Was mit den Segmenten geschieht
Bis der Knoten die Datenbanken gescannt hat, sendet der Master weiter Segmente. Alle 30 Sekunden löscht der Replik-Knoten alte Segmente und behält nur die letzten 100 (keep_segments).
Nach dem Scan erhält der Datenbankeintrag auf der Replik den Zustand ORPHANED. Der Replik-Knoten antwortet dem Master mit unknown_database. Der Master hört auf, Segmente an diese Replik zu senden, hört auf, ein Archiv für sie zu behalten, und prüft sie alle 10 Minuten erneut.
Andere Repliken dieser Datenbank sind nicht betroffen.
Der Eintrag ORPHANED kann gelöscht werden (Kapitel 3.8): hqbirdrcm forgetdatabase. Die Datenbankdatei selbst wird nicht gelöscht.
8.3. Zum Master befördern
Die Replik wird der neue Master. Ihre Datei bleibt an ihrem Platz, und die Verwaltung
geht an den Begleiterknoten über.
Bedingungen:
Bedingung
Ablehnung
die Datenbank ist eine Replik
bad_request
ein Knoten mit der Rolle Master — der Begleiter — läuft auf demselben Host (dieselbe Bezeichnung host in rcm.json, Kapitel 2.1)
no_companion
die Beförderung dieser Datenbank läuft nicht schon
already_running
es gibt keine Initialisierung in diese Datenbank oder von ihrem Master
reinit_running
RCM erzeugt den Begleiterknoten nicht: installieren Sie ihn im Voraus (Kapitel 1).
So starten Sie:
in der Replikzeile Zum Master befördern, oder in der Liste Aktion;
RCM bittet um Bestätigung und nennt den Begleiterknoten.
Bestätigung „Zum Master befördern?“
Schritte (in der Replikzeile sichtbar, Namen auf Englisch):
Nr.
Schritt
Was er tut
1
TURN TO NORMAL
wie in 8.1; wird übersprungen, wenn die Datenbank schon normal ist
2
NEW GUID
eine neue Datenbank-GUID an Ort und Stelle (8.4)
3
EXCLUDE ON DONOR
der Replik-Knoten (Spender) schließt die Datei aus seinem Scan aus (exclude_paths)
4
ENROLL ON
der Begleiterknoten registriert die Datei als Master-Datenbank
5
PUBLICATION SYNC
Synchronisation der Publikation; die Liste der ausgeschlossenen Tabellen wird vom alten Master übernommen (Kapitel 6.3)
6
RESTART DONOR FIREBIRD
Neustart des Firebird des Spenders, ohne auf ein Fenster zu warten
7
RESTART FIREBIRD
Neustart des Firebird des Begleiters, ohne auf ein Fenster zu warten
8
FINALIZE
die Spenderzeile wird Geisterreplik; der alte Master kann Master herabgestuft werden (8.5)
Beförderungsschritte in der Replikzeile
Auf HQbird 2.5 und 3.0 gibt es keine Publikationen: der Schritt PUBLICATION SYNC
endet mit dem Text „diese Engine hat keine Publikation“.
Beförderungsschritte auf HQbird 3.0 (Windows)
Verwenden Spender und Begleiter dasselbe Firebird, wird dieses Firebird
neu gestartet: Verbindungen zu allen seinen Datenbanken werden abgeworfen.
Schlägt ein Schritt fehl, erhält der Auftrag failed mit dem Fehlertext. Beheben Sie die
Ursache und klicken Sie erneut auf Zum Master befördern: abgeschlossene Schritte werden nicht
wiederholt. Startet RCM während der Beförderung neu, wird der Auftrag ebenfalls
failed — prüfen Sie den Zustand der Knoten und versuchen Sie es erneut.
Lizenz. Hat fbagent auf dem Host des Masters keine Lizenz, hat der Master
den Versand angehalten. Die Beförderung ist trotzdem möglich. RCM warnt Sie:
Änderungen, die nach Beginn der Pause gemacht wurden, gehen verloren.
8.4. Neue GUID
Nach der Beförderung muss die Datenbank eine eigene GUID erhalten. Sonst schreibt der neue Master
Segmente unter der GUID des alten Masters, und seine Repliken werden mit
duplicate_guid abgelehnt.
Der Schritt NEW GUID auf dem Knoten:
gfix -shut single -force 0 — alle Verbindungen zur Datenbank werden beendet;
nbackup -L, dann nbackup -F ohne -SEQUENCE;
löscht <database>.delta;
prüft den Header: neue GUID, REPLICATION_SEQUENCE = 0;
gfix -online normal.
Firebird wird nicht neu gestartet. Die Methode funktioniert auf allen Versionen (2.5, 3.0, 4.0,
5.0).
Wurde der Schritt unterbrochen, gibt der Knoten die Warnung newguid_interrupted aus. Die Datenbank kann
im single-Shutdown bleiben. Wiederholen Sie Zum Master befördern: der Schritt
wird fortgesetzt.
Der Schritt wird übersprungen (der Text beginnt mit skipped:), wenn der Spenderknoten eine alte
Version ist oder die Datei schon eine eigene GUID hat.
Nach einer neuen GUID taugt die alte nbackup-Kette nicht mehr. Machen Sie eine neue
nbackup-Kopie der Stufe 0.
Wurde die Datenbank mit ADD DIFFERENCE FILE erzeugt, liegt ihre .delta an einem anderen
Ort: löschen Sie sie von Hand.
8.5. Nach der Beförderung
Spendereintrag. Auf dem Replik-Knoten bleibt die Datenbank ORPHANED, der Pfad bleibt in
exclude_paths, und der Ordner .Incoming und die Beschriftung bleiben. In RCM ist das die Zeile
Geisterreplik mit den Schaltflächen Auf dem neuen Master öffnen und Bereinigen.
Spenderzeile: «Geisterreplik»
Um die Zeile zu entfernen, klicken Sie auf Bereinigen. Das ändert nur RCM.
Um den Spendereintrag vom Replik-Knoten zu entfernen, führen Sie forgetdatabase aus.
Die Datei und der Ordner .Incoming bleiben. HQbird 2027.2.30 und neuer lehnt den
Befehl nicht ab (mailbox_active), weil der Spenderpfad in
exclude_paths steht. Knoten früherer Versionen lehnen ab, solange die Datei und der
Ordner .Incoming vorhanden sind.
Führen Sie auf dem Spender nie cleanuparchive -orphaned aus. Spender und
Begleiter teilen denselben Ordner <database>.LogArch. Der Befehl löscht das lebende
Archiv des neuen Masters.
Alter Master.
War der Spender seine letzte arbeitende Replik, setzt RCM den alten
Master auf Master herabgestuft und hält den Versand an den Spender an
(„Versand angehalten: … (Beförderung zum Master)“). Setzen Sie den
Versand an den Spender nicht fort: er hält schon eine arbeitende Datenbank. Um diesen Zustand aufzuheben,
initialisieren Sie die Datenbank auf eine andere Replik.
Alter Master: «Master herabgestuft», Versand angehalten
Eine Initialisierung vom alten Master zum Spenderknoten wird abgelehnt
(target_not_replica): er hält schon eine arbeitende Datenbank.
Wurde der Schritt NEW GUID übersprungen, haben der alte und der neue Master dieselbe GUID.
Dann verlangt die Initialisierung vom alten Master -force (Kapitel 5.9).
Nach einer Beförderung von Hand macht RCM den alten Master nicht zur Replik des neuen
Masters. Stoppen Sie die Anwendungen auf dem alten Master und nehmen Sie seine Datenbank aus der
Verwaltung (Kapitel 3.8). Für eine als Dienst beschriebene Datenbank tut das der Wiederbeitritt
(8.7).
Neuer Master. Richten Sie eine Replik für ihn ein: Replik-Knoten, Partner (Kapitel 2),
Publikation (Kapitel 6), Initialisierung (Kapitel 5).
Neuer Master: Datenbank mit neuer GUID, noch keine Replik
8.6. Geplante Umschaltung: Checkliste
Das ist das Verfahren für eine Umschaltung von Hand. Für eine als Dienst beschriebene Datenbank schaltet RCM den Master selbst um (8.7). Eine Beförderung von Hand prüft nicht, ob Anwendungen auf den alten Master schreiben. Verfahren:
Im Voraus. Auf dem Host der Replik läuft ein Begleiterknoten mit der Rolle Master, und beide Knoten haben dieselbe Bezeichnung host (Kapitel 2.1). Ein Knoten für die künftige Replik des neuen Masters ist bereit.
Stoppen Sie die Schreibzugriffe der Anwendungen auf die Datenbank des alten Masters.
Warten Sie, bis die Replik alles empfangen und angewendet hat: Datenbanken → IN_SYNC, keine Warteschlange.
Prüfen (Kapitel 5.10): die Zeilenzahlen stimmen überein.
Zum Master befördern (8.3). Warten Sie auf den Schritt FINALIZE.
Prüfen Sie: die Datenbank steht in der Masterliste des Begleiters, Publikation ein.
Schalten Sie die Anwendungen auf den neuen Master um.
Machen Sie eine nbackup-Kopie der Stufe 0 der neuen Datenbank (8.4).
Bereinigen Sie den Geistereintrag der Spenderzeile (8.5).
Verbinden Sie die Replik mit dem neuen Master und initialisieren Sie sie (Kapitel 5).
Alter Master: nehmen Sie die Datenbank aus der Verwaltung oder lassen Sie sie als Archiv (8.5).
8.7. Dienste: Umschaltung und Failover in RCM
Mit HQbird 2027.2.30 verlegt RCM den Master selbst auf einen anderen Host. Dafür wird die Datenbank als Dienst beschrieben: eine logische Datenbank auf mehreren Hosts. Auf jedem Host des Dienstes gibt es einen Master-Knoten und einen Replik-Knoten, und der Pfad zur Datenbankdatei ist derselbe. Der Dienst wird auf der Seite Dienste angelegt (ab HQbird 2027.2.31) oder mit dem Befehl hqbirdrcm services put -id <id> -file <file>.json.
Aktion
Was sie tut
Befehle
Umschaltung
geplante Verlegung des Masters ohne Datenverlust. Danach wird der alte Master automatisch zur Replik des neuen Masters
nach einem Failover bringt er den alten Host als Replik des neuen Masters zurück
hqbirdrcm rejoin -service <id>
Fortsetzen
nimmt den Dienst aus dem Zustand failed
hqbirdrcm resume -service <id> -check, dann hqbirdrcm resume -service <id>
Dieselben Aktionen gibt es auf der Dienstseite: die Schaltflächen Umschaltung…, Failover…, Wiederbeitritt… und Fortsetzen….
Automatisches Failover ist standardmäßig aus. Es wird für jeden Dienst getrennt eingeschaltet:
hqbirdrcm policy -service <id> -auto-failover on -max-data-loss 30.
Es braucht Router. RCM startet ein Failover nur, wenn der Master-Knoten schweigt, die Mehrheit der Router das Firebird des Masters nicht sieht und der Rückstand der Replik nicht größer ist als max_data_loss_sec.
Ein Router (hqclusternode router, Linux) hält HAProxy auf dem aktuellen Master des Dienstes. Anwendungen verbinden sich mit <router host>:<router_port> und ändern die Verbindungszeichenfolge bei einer Umschaltung nicht.
Nach einem Failover isoliert RCM den alten Master (Rolle fenced), sobald er wieder antwortet. Bringen Sie ihn mit dem Befehl rejoin zurück.
Diese Website verwendet Cookies, um Ihre Erfahrung zu verbessern und Einstellungen zu speichern.