Administratorhandbuch für den HQbird-Replikationscluster: hqclusternode und hqbirdrcm (RCM). Installationsprogramme: HQbird 2027 herunterladen.

Inhalt


0. Einleitung

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.

Woraus der Cluster besteht

Bestandteil Wie viele Wo er läuft Was er tut
Firebird (HQbird) eine oder mehrere Instanzen auf jedem Datenbankserver speichert Datenbanken, schreibt Replikationssegmente
fbagent einer je Firebird-Instanz neben Firebird 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

  1. Auf dem Master schreibt Firebird Datenbankänderungen in Segmente (Dateien des Replikationsprotokolls).
  2. Der Master-Knoten sendet die Segmente über einen gesicherten Kanal (mTLS) an den Replik-Knoten.
  3. Der Replik-Knoten legt die Segmente in den Ordner der eingehenden Segmente. Das Firebird der Replik wendet sie auf seine Kopie der Datenbank an.
  4. 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.
  5. 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
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)
Aufnehmen Registrierung der Master-Datenbanken im Knoten

Wie Sie das Handbuch lesen

Kapitel Thema
1. Installation Installation der Knoten und von RCM über HQCenter Admin, über RCM ohne HQCenter Admin und von Hand, Linux und Windows
2. Clusterkonfiguration Verknüpfungen Master → Replik, Knoteneinstellungen, RCM-Benutzer
3. Eine Datenbank zum Master hinzufügen Aufnehmen, Firebird neu starten, Prüfung
4. Wie eine Datenbank zur Replik wird Schritte, Vorbereitung der Replik, Plattenplatz
5. Initialisierung Reinit-Schritte, Auswirkung auf den Betrieb, lange Transaktionen, Geschwindigkeit, Fehler
6. Publikation einrichten Publikation von Firebird 4/5, Tabellen, neue Tabellen, HQbird 2.5/3.0
7. Weitere Replikationsoptionen Parameter von replication.conf, Archiv, Übertragung, Warnungen, Pause, Protokolle
8. Eine Replik in eine normale Datenbank umwandeln 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).
  • Netz gemäß der Porttabelle (Kapitel 0).

Linux: root-Rechte, x86_64, systemd, curl. Unterstützt: Ubuntu 20–26, Debian 11–13, Astra, CentOS 7–10, AlmaLinux, Rocky, Oracle Linux 8–10, RED OS, openSUSE 15.6, Fedora 44+.

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 (PowerShell als Administrator):

Command
powershell -NoProfile -ExecutionPolicy Bypass -File .\fbagent-fb50_known.ps1 -Enroll

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:

  1. Innerhalb von 10 Minuten erhält fbagent den Cluster von HQCenter Admin (danach prüft es alle 60 Sekunden auf Änderungen).
  2. Der fbagent auf dem RCM-Host erzeugt die Zertifizierungsstelle des Clusters (CA) und signiert die Zertifikate aller Knoten.
  3. Jeder fbagent schreibt node.json oder rcm.json für die Mitglieder seines Clusters.
  4. Bei der nächsten Produktprüfung (alle 3 Minuten) installiert und startet fbagent die Dienste.

Was installiert wird und wo:

Was Linux Windows
Master-Knoten /opt/hqclusternode/master/, Dienst hqclusternode-master-p<port> <HQbird>\hqclusternode\master\, Dienst HQClusterNode-master-p<port>
Replik-Knoten /opt/hqclusternode/replica/, Dienst hqclusternode-replica-p<port> <HQbird>\hqclusternode\replica\, Dienst HQClusterNode-replica-p<port>
RCM /opt/hqbirdrcm/, Dienst hqbirdrcm <HQbird>\hqbirdrcm\, Dienst hqbirdrcm

<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.
  • Produktstatus: fbagent --product-status hqclusternode (oder hqbirdrcm).

1.3. Installation über RCM (ohne HQCenter Admin)

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.json
fbagent --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 host
sudo 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:

  1. erzeugt den Cluster dieses Hosts (fbagent --cluster-init); der Clustername ist der Hostname;
  2. installiert und startet RCM, die RCM-Konsole läuft über HTTPS auf Port 7444;
  3. erzeugt den ersten RCM-Administrator rcmadmin mit einem Zufallskennwort;
  4. ö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-fb50
sudo -u firebird ./fbagent --cluster-init <name>      # RCM host; open ports 7443 and 7444 yourself
sudo -u firebird ./fbagent --cluster-pairing on      # window for 24 hours
sudo -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.

  1. 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.
  2. 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:).
  3. Wählen Sie den Master (standardmäßig der erste Host) und klicken Sie auf Verknüpfen.
Hosts verknüpfen: Prüfergebnis
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
Hosts verknüpfen: alle Knoten laufen

Dasselbe über die Befehlszeile:

Command
cd /opt/hqbirdrcm
export RCM_USER=rcmadmin RCM_PASSWORD='<password>'
./hqbirdrcm cluster link -hosts db1,db2,db3 -master db1

Was danach geschieht:

  1. RCM sendet jedem freien Host eine Einladung.
  2. 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.
  3. RCM speichert den Cluster: Knoten <host>-master auf dem Master, <host>-replica auf den anderen Hosts, Port 7051, Verknüpfungen Master → Replik.
  4. 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.

Command
cd <fbagent folder>
sudo -u firebird ./fbagent --cluster-init shop-prod --address 10.0.0.7

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:

  1. erzeugt die Cluster-CA und die Agent-CA (im fbagent-Ordner, clusterca/<name>/);
  2. schreibt das RCM-Zertifikat, rcm.json und cluster-init.json in den RCM-Ordner;
  3. installiert RCM und registriert den Dienst hqbirdrcm. Unter Linux läuft der Dienst als eigener Benutzer hqbirdrcm;
  4. schaltet fbagent auf RCM (cluster.source = rcm) und startet ihn neu;
  5. 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

  1. 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
    export RCM_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.

  2. Führen Sie auf dem Knoten-Host diesen Befehl als fbagent-Benutzer aus:

    Command
    cd <fbagent folder>
    sudo -u firebird ./fbagent --cluster-join https://10.0.0.7:7443 \
      --ca-hash sha256:9f86d0... --token-file token.txt

    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.

Command
cd /opt/hqbirdrcm
sudo -u hqbirdrcm ./hqbirdrcm release import -config rcm.json \
  -file hqclusternode-linux-amd64 -product hqclusternode \
  -platform linux-amd64 -version 2027.5.12
sudo -u hqbirdrcm ./hqbirdrcm release list -config rcm.json
  • 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):

Command
curl -s -H "Authorization: Bearer <token>" http://127.0.0.1:13050/v1/instances/<instance_id>

Hat der Host mehrere HQbird-Instanzen, lassen Sie in firebird.update.services der fbagent-Konfiguration nur den Dienst Ihrer Instanz (siehe 3.5).

Schritt 2. Die Dateien auslegen

Linux:

Code
/opt/hqclusternode/
  hqclusternode        # program
  node.json            # node configuration (permissions 0600)
  certs/               # ca.crt, <node_id>.crt, <node_id>.key
  work/                # working folder
/opt/hqbirdrcm/
  hqbirdrcm            # program
  rcm.json             # cluster configuration
  certs/               # ca.crt, rcm.crt, rcm.key
  rcm-data/            # state, users, audit log
Command
sudo mkdir -p /opt/hqclusternode/certs /opt/hqclusternode/work
sudo install -m 0755 hqclusternode-linux-amd64 /opt/hqclusternode/hqclusternode
# on the RCM host:
sudo mkdir -p /opt/hqbirdrcm/certs /opt/hqbirdrcm/rcm-data
sudo install -m 0755 hqbirdrcm-linux-amd64 /opt/hqbirdrcm/hqbirdrcm

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:

Command
./hqclusternode gencerts -out certs \
  -nodes 'node-a:master,node-b:replica' \
  -hosts 'localhost,127.0.0.1,<ip-node-a>,<ip-node-b>,<ip-rcm>'

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
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:

Command
./hqclusternode gencerts -out certs -add -nodes 'node-c:replica' -hosts '<ip-node-c>'

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.

Schritt 5. rcm.json schreiben

json
{
  "ingest_addr": "0.0.0.0:7443",
  "operator_addr": "127.0.0.1:7444",
  "users_file": "rcm-data/users.json",
  "data_dir": "./rcm-data",
  "tls": { "ca_cert": "certs/ca.crt", "cert": "certs/rcm.crt", "key": "certs/rcm.key" },
  "nodes": [
    { "node_id": "node-a", "url": "https://<ip-node-a>:7051", "role": "master",  "host": "A" },
    { "node_id": "node-b", "url": "https://<ip-node-b>:7051", "role": "replica", "host": "B" }
  ]
}
  • 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.

RCM (Linux):

Command
cd /opt/hqbirdrcm
sudo ./hqbirdrcm svc install -config /opt/hqbirdrcm/rcm.json
sudo ./hqbirdrcm svc start

Knoten (Linux):

Command
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
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:

Command
sudo systemctl stop hqclusternode-master-p3050
sudo install -m 0755 hqclusternode-linux-amd64 /opt/hqclusternode/hqclusternode
sudo systemctl start hqclusternode-master-p3050

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
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 password sofort (der Link Kennwort in der Kopfzeile).

Kennwortänderung bei der ersten Anmeldung
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>").

  1. Berechnen Sie den Hash:

    Command
    printf '%s' 'rcmadmin:hqbirdrcm:<new password>' | md5sum
  2. Schreiben Sie ihn in das Feld ha1 des Benutzers in users.json. Um einen Benutzer hinzuzufügen, fügen Sie users ein weiteres Element hinzu:

    json
    { "username": "ivanov", "ha1": "<hash>", "algo": "MD5", "created_at": "2026-11-03T00:00:00Z" }
  3. 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.

Command
chmod 600 /opt/hqbirdrcm/rcm-data/users.json
sudo systemctl restart hqbirdrcm

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 des Knotens
systemctl status von RCM
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
    export RCM_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)
--cluster-join: token_used, token_expired, token_revoked 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

  1. Geben Sie eine Neue Cluster-ID ein (lateinische Kleinbuchstaben, Ziffern und -) und klicken Sie auf Erstellen.
  2. 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.
  3. Fügen Sie Verknüpfungen hinzu (Replikationsverknüpfungen) vom Master zur Replik.
  4. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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 auto
fbagent --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:

  1. Klicken Sie in der Tabelle Agenten auf Mitglied hinzufügen in der fbagent-Zeile.
  2. 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.
  3. Klicken Sie im Abschnitt Verknüpfungen auf Verknüpfung hinzufügen vom Master zur Replik.
  4. Klicken Sie auf Prüfen: RCM zeigt Fehler und Warnungen.
  5. 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
export RCM_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

  1. Einstellungen → RCM, die Tabelle Verbundene Knoten.
  2. 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.
  3. Klicken Sie in der Knoten-Zeile auf Prüfen: RCM prüft Verbindung und Rechte.
  4. Klicken Sie auf Speichern. RCM schreibt rcm.json und speichert die alte Datei als rcm.json.<UTC-Zeit>.bak (die letzten 20).
  5. Starten Sie RCM neu. Bis zum Neustart gilt die alte Konfiguration; die Seite zeigt, welche Felder auf einen Neustart warten.
Einstellungen → RCM
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:

  1. Einstellungen → Knoten, wählen Sie den Master-Knoten.
  2. Klicken Sie im Abschnitt Partner auf Partner hinzufügen: die node_id der Replik, ihre url, Kompression (zstd).
  3. Klicken Sie auf Speichern. RCM zeigt die Liste der Änderungen und bittet um Bestätigung. Die Änderung von peers gilt sofort.
  4. Wiederholen Sie es für den Replik-Knoten: sein Partner ist der Master.
Der Abschnitt Partner des Master-Knotens
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ählen
Einstellungen → Knoten: einen Knoten auswählen
Datenbankeinstellungen des Knotens mit Markierungen "nach dem Scan"
Datenbankeinstellungen 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:

  1. Korrigieren Sie firebird.password in der node.json jedes Knotens dieser Instanz (Master und Replik).
  2. Korrigieren Sie das Kennwort in der fbagent-Konfiguration und laden Sie sie neu (siehe die fbagent-Dokumentation).
  3. 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
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
    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:

  1. die eigene Liste der Datenbank;
  2. die gemeinsame Liste sync_tables des Knotens;
  3. Tabellen aus der Publikation der Datenbank;
  4. 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.

Prüfung auf dem Knoten-Host (Linux):

Command
sudo -u firebird /opt/hqclusternode/hqclusternode checkpermissions -config /opt/hqclusternode/node.json

3.3. Seite zum Aufnehmen von Datenbanken

Datenbanken aufnehmen: Formular und Vorschau
Datenbanken aufnehmen: Formular und Vorschau
  1. Öffnen Sie die Aufnahmeseite des Master-Knotens. Der Link steht an zwei Stellen:

    • Datenbanken → Tabelle Knoten → Aktionsspalte → Aufnehmen;
    • Übersicht → Karte des Master-Knotens → Datenbanken aufnehmen.

    Ein Replik-Knoten hat diese Seite nicht.

  2. 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.

  3. 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).
  4. Klicken Sie auf Vorschau. Der Knoten zeigt alle Dateien, die zur Einschlussmaske passen. Er ändert nichts.

  5. 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.
  6. 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
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
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.

Dasselbe über die Befehlszeile

Command
hqbirdrcm enroll-databases -node node-a -root /databases/master

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

  1. Der Knoten schreibt die Regeln in node.json.
  2. Der Knoten scannt den Ordner (scansync).
  3. 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.
  4. Vor einer Änderung speichert der Knoten eine Kopie der Datei: replication_YYYYMMDD_hhmmss_NNN.conf.
  5. 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“
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
PENDING_RESTART Ausstehend Konfiguration geschrieben, Firebird-Neustart erforderlich
CONFIGURED Ausstehend 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
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:

  1. Prüft, dass fbagent antwortet und dieselbe Instanz verwaltet (Bezeichner, Port, Dienstname aus node.json). Stimmt ein Wert nicht, lehnt der Knoten ab.
  2. Bittet fbagent, Firebird neu zu starten.
  3. Wartet, bis Firebird auf seinem Port antwortet.
  4. 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).

  1. Führen Sie eine Vorschau aus:

    Command
    hqbirdrcm enroll-databases -node node-a -root /databases/master -detect-existing -dry-run

    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.

  2. 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
    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:

  1. fügt die Dateien der Ausschlussliste des Knotens hinzu;
  2. scannt den Ordner einmal: die Datenbankblöcke werden aus replication.conf entfernt;
  3. 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:

Command
# 1. delete the segment archive (optional)
hqbirdrcm cleanuparchive -node node-a -db <db_id> -orphaned
# 2. delete the database record
hqbirdrcm forgetdatabase -node node-a -db <db_id>

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.

4.2. Schritte

Nr. Schritt Wo Zustand der Master-Datenbank nach dem Schritt
1 Datenbank auf dem Master registrieren Kapitel 3.3 PENDING_RESTART
2 Firebird des Masters neu starten Kapitel 3.5 CONFIGURED
3 Publikation synchronisieren Kapitel 6 CONFIGURED, Publikation EIN
4 Replik vorbereiten: Ordner, Rechte, Firebird-Version 4.3 —
5 Freien Platz auf Master und Replik prüfen 4.4 —
6 Initialisierung Kapitel 5 SEEDING → IN_SYNC
7 Firebird der Replik neu starten (falls nötig) Kapitel 5.6 die Replik beginnt, Segmente anzuwenden
8 Daten prüfen Kapitel 5.10 —

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;

  • von Hand auf dem Replik-Host (Linux):

    Command
    sudo mkdir -p /databases/replica
    sudo chown firebird:firebird /databases/replica
    sudo chmod 2770 /databases/replica

    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:

  1. RCM — anhand der letzten Knotenstatistik, bevor der Befehl gesendet wird. Ist der Platz offensichtlich nicht ausreichend, gibt RCM sofort den Fehler 507 zurück.
  2. 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:

  1. von allen Repliken angewendete Segmente, die älter sind als retention_days;
  2. angewendete Segmente, die neuer sind (wenn der Platz knapp ist);
  3. 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
    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
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:

  1. Master: registrieren Sie die Datenbanken mit detect_existing (Kapitel 3.6).
  2. 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.
  3. Bestätigen Sie die Zeilen. Der Knoten verschiebt die Blöcke in seinen eigenen Bereich von replication.conf.
  4. Starten Sie das Firebird der Replik neu, damit es die verschobenen Blöcke liest.
  5. 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?“
Das Fenster „Datenbank neu initialisieren?“
  1. Öffnen Sie Datenbanken.
  2. 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.
  3. 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).
  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
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“
Die Seite „Befehle“

Dasselbe über die Befehlszeile

Command
# one database
hqbirdrcm reinit -node node-a -db <db_id> -to node-b
# all master databases
hqbirdrcm 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.

Command
hqbirdrcm reinit -node node-a -db <db_id> -to node-b -remove-old-replica

-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
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).

Dasselbe über die Befehlszeile

Command
hqbirdrcm longtx -node node-a -db <db_id>                       # list
hqbirdrcm longtx -node node-a -db <db_id> -disconnect 12,34 -retry-to node-b
hqbirdrcm longtx -node node-a -db <db_id> -hold false           # release hold

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:

Command
hqclusternode benchmark -config /opt/hqclusternode/master/node.json

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
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) Replik, Warnung replica_removed_for_reinit; Master

Einschalten — Einstellungen → RCM (oder rcm.json, der Abschnitt auto_reinit):

json
"auto_reinit": {
  "enabled": true,
  "default_window": "22:30-04:00",
  "max_concurrent": 1,
  "nodes": {
    "node-a": { "window": "23:00-05:00",
                "databases": { "sales/employee.fdb": "01:00-03:00" } }
  }
}
  • 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

  1. Datenbanken: das Paar Master — Replik in der Gruppe In Ordnung, Zustand IN_SYNC.

  2. 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.

Ergebnis der Prüfung
Ergebnis der Prüfung
Command
hqbirdrcm verifydata -master node-a -master-db <db_id> -replica node-b -replica-db <db_id>
  1. 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
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 Aktion Publikation synchronisieren. RCM sendet für jede Datenbank einen eigenen Befehl.
Bestätigung der Publikationssynchronisation
Bestätigung der Publikationssynchronisation

Was der Knoten tut (eine einzige Transaktion):

  1. Schaltet die Publikation ein. Hat der Operator sie selbst ausgeschaltet (6.4), schaltet er sie nicht ein.
  2. Fügt der Publikation alle Tabellen mit Schlüssel hinzu, die noch nicht darin sind.
  3. Entfernt aus der Publikation Tabellen ohne Schlüssel und Tabellen, die der Operator ausgeschlossen hat (6.3).
  4. 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
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 database
hqbirdrcm 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

  1. -nowait — nicht auf das Ergebnis warten.

6.3. Publikationstabellen

Die Seite „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:

  1. Haken Sie die Tabellen an.
  2. Klicken Sie auf Aus der Publikation ausschließen oder In die Publikation zurückholen.
  3. Der Knoten speichert die Liste und synchronisiert die Publikation sofort.
Bestätigung von „Aus der Publikation ausschließen“
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:

  1. Legen Sie einen Primärschlüssel oder einen eindeutigen Index auf der Tabelle an.
  2. Klicken Sie auf Publikation synchronisieren.
  3. 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“
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
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:

  1. 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
Plugin nicht aktiviert: replconf.properties zeigt auf die HQbird-DataGuard-Datei
  1. 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
Fenster zur Plugin-Aktivierung
  1. Nach dem Neustart von Firebird zeigt das Feld Aktiviert „ja: die Engine liest die Datei des Knotens“.

Plugin aktiviert
Plugin aktiviert

Die Aktivierung startet Firebird neu und betrifft alle Datenbanken dieses Firebird. Führen Sie sie in einer ruhigen Zeit aus.

7. Weitere Replikationsoptionen

7.1. Replikationsparameter

Einstellungen → Replikationsparameter, Assistentenformular
Einstellungen → Replikationsparameter, Assistentenformular

Die Seite Einstellungen → Replikationsparameter ändert die Schlüssel in replication.conf für die ausgewählten Datenbanken oder für den Knoten als Ganzes.

  1. 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.

  2. 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
  3. Wählen Sie, wo es gilt: Auf die ausgewählten Datenbanken oder Als Standard für ihre Knoten.

  4. Vorschau — die Knoten prüfen die Werte, ohne etwas zu ändern.

Vorschau der Änderungen
Vorschau der Änderungen
  1. 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:

  1. Segmente, die von allen Repliken angewendet wurden und älter sind als retention_days.
  2. Ist der freie Platz kleiner als free_space_floor_gb — angewendete Segmente, die jünger sind als die Aufbewahrungsfrist. Warnung disk_serious_cleanup.
  3. 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“
Einstellungen → Knoten, „Speicher und Dateien“

Das Archiv von Hand aufräumen:

Command
hqbirdrcm cleanuparchive -node node-a              # stages for all databases on the node
hqbirdrcm 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).

7.4. Übertragung: Kompression, Geschwindigkeit, Fenster

Kompression wird je Partner gesetzt: Einstellungen → Knoten → Partner, Spalte compress.

Wert Bedeutung
leer oder none keine Kompression (Standard)
zstd Kompression zstd

Die Änderung gilt sofort. Kompression ist in einem langsamen Netz nützlich.

Geschwindigkeit der Segmentübertragung (Einstellungen → Knoten, Übertragung und Neuinitialisierung):

Parameter Standard Wann sie gilt
limits.channel_a_mbps — Geschwindigkeit der Segmentübertragung 50 MB/s sofort
limits.channel_a_burst_mbps — Spitze der Segmentübertragung 200 MB sofort

Die Einheit ist Mebibyte (MiB), auch wenn der Name „mbps“ sagt. Die Spitze kann nicht kleiner sein als die Geschwindigkeit.

Einstellungen → Knoten, „Übertragung und Neuinitialisierung“
Einstellungen → Knoten, „Übertragung und Neuinitialisierung“

Zeitfenster (Zeitfenster):

Parameter Standard Wann sie gilt Was sie betrifft
windows.restart_window — Fenster für den Firebird-Neustart Master 22:00-05:00, Replik always sofort wann der Replik-Knoten Firebird neu starten darf
windows.transfer_window — Übertragungsfenster 23:00-05:00 nach Knoten-Neustart volle Initialisierungsgeschwindigkeit (Kapitel 5.5)

Die Beschriftung neben jedem Feld zeigt, wann die Änderung gilt: sofort oder Knoten-Neustart.

Einstellungen → Knoten, „Zeitfenster“
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
Seite Datenprüfung

7.6. Warnungen

Seite 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
shipping_paused der Versand an den Partner ist ausgesetzt (7.7)
apply_error, replication_stopped, replication_unrecoverable_error die Replik kann ein Segment nicht anwenden
replication_guid_mismatch die GUID der Master-Datenbank hat sich geändert
segment_missing, segment_rejected, sequence_gap Probleme mit der Segmentfolge
firebird_down, firebird_log_error 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.

Command
hqbirdrcm pauseshipping  -node node-a -db <db_id>
hqbirdrcm resumeshipping -node node-a -db <db_id>
Bestätigung des Anhaltens des Versands
Bestätigung des Anhaltens des Versands
Master-Zeile während einer Pause
Master-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).

Seite Protokolle
Seite Protokolle
Command
hqbirdrcm getlogs -node node-b -source replication -tail 200

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“
Liste „Aktion“ der Replik: der Eintrag „Normal machen“
  1. Datenbanken, Seite der Replik: haken Sie die Replikzeilen an.

  2. Wählen Sie in der Liste Aktion Normal 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“
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“
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:

Command
hqbirdrcm scansync -node node-b
hqbirdrcm restartfirebird -node node-b

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;

  • über die Befehlszeile:

    Command
    hqbirdrcm promotetomaster -node node-b -db <db_id>   # -timeout 10m

RCM bittet um Bestätigung und nennt den Begleiterknoten.

Bestätigung „Zum Master befördern?“
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
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)
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:

  1. gfix -shut single -force 0 — alle Verbindungen zur Datenbank werden beendet;
  2. nbackup -L, dann nbackup -F ohne -SEQUENCE;
  3. löscht <database>.delta;
  4. prüft den Header: neue GUID, REPLICATION_SEQUENCE = 0;
  5. 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»
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
    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
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:

  1. 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.
  2. Stoppen Sie die Schreibzugriffe der Anwendungen auf die Datenbank des alten Masters.
  3. Warten Sie, bis die Replik alles empfangen und angewendet hat: Datenbanken → IN_SYNC, keine Warteschlange.
  4. Prüfen (Kapitel 5.10): die Zeilenzahlen stimmen überein.
  5. Zum Master befördern (8.3). Warten Sie auf den Schritt FINALIZE.
  6. Prüfen Sie: die Datenbank steht in der Masterliste des Begleiters, Publikation ein.
  7. Schalten Sie die Anwendungen auf den neuen Master um.
  8. Machen Sie eine nbackup-Kopie der Stufe 0 der neuen Datenbank (8.4).
  9. Bereinigen Sie den Geistereintrag der Spenderzeile (8.5).
  10. Verbinden Sie die Replik mit dem neuen Master und initialisieren Sie sie (Kapitel 5).
  11. 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 hqbirdrcm switchover -service <id> -check, dann hqbirdrcm switchover -service <id> -to <host>
Failover der Host des Masters ist verloren: RCM befördert die Replik. Die jüngsten Änderungen des Masters können verloren gehen hqbirdrcm failover -service <id> -check, dann hqbirdrcm failover -service <id> -to <host> -accept-data-loss
Wiederbeitritt 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.