Beheerdershandleiding voor het HQbird-replicatiecluster: hqclusternode en hqbirdrcm (RCM). Installatieprogramma's: HQbird 2027 downloaden.

Inhoud


0. Inleiding

Deze handleiding beschrijft hoe u het HQbird-replicatiecluster installeert en gebruikt: de nodes hqclusternode en de clustermanager hqbirdrcm (RCM).

Dit is een handleiding voor de Firebird-beheerder. We gaan ervan uit dat u Firebird, gfix en nbackup kent. U hoeft de interne werking van een node niet te kennen.

Waaruit het cluster bestaat

Onderdeel Hoeveel Waar het draait Wat het doet
Firebird (HQbird) een of meer instanties op elke databaseserver bewaart databases, schrijft replicatiesegmenten
fbagent een per Firebird-instantie naast Firebird stopt en start Firebird op verzoek van een node
hqclusternode (node) een per instantie en rol naast Firebird configureert replicatie, draagt segmenten over, voert replica-initialisatie uit
hqbirdrcm (RCM) een per cluster op elke host die alle nodes kan zien webinterface, opdrachten, meldingen, statistieken

Een node heeft een rol: master of replica. Op één Firebird-instantie kunnen twee nodes draaien: een master-node en een replica-node. In dat geval zijn sommige databases van deze Firebird masters en andere replica’s.

Hoe het werkt

  1. Op de master schrijft Firebird databasewijzigingen naar segmenten (replicatielogbestanden).
  2. De master-node stuurt de segmenten naar de replica-node over een beveiligd kanaal (mTLS).
  3. De replica-node plaatst de segmenten in de map voor binnenkomende segmenten. De Firebird van de replica past ze toe op zijn kopie van de database.
  4. De master-node zelf draagt de eerste kopie van de database over naar de replica. Dit heet initialisatie (reinit). Dat verloopt via nbackup, en de master blijft in die tijd doorwerken.
  5. De nodes sturen statistieken naar RCM. RCM toont de toestand van het cluster en stuurt operatoropdrachten naar de nodes.
Hoe het cluster werkt: segmenten, initialisatie, statistieken en operatoropdrachten
Hoe het cluster werkt: segmenten, initialisatie, statistieken en operatoropdrachten

Ondersteunde versies

  • Firebird / HQbird 5.0 en 4.0 — alle functies.
  • HQbird 3.0 en 2.5 — replicatie via de replconf-plug-in. Er zijn geen publicaties; de verzameling tabellen wordt door filters bepaald. De verschillen staan in de kaders „HQbird 2.5/3.0”.

De hoofdversie van Firebird op de master en op de replica moet overeenkomen. Anders weigert de replica-node de initialisatie.

Poorten

Poort Wie luistert Wie verbindt Waarvoor
7051 node andere nodes en RCM node-API, overdracht van segmenten en databasekopieën
7443 RCM alle nodes statistieken van nodes ontvangen
7444 RCM operator webinterface en operator-API. Installatie via RCM (hoofdstuk 1.3): HTTPS op alle adressen. Installatie via HQCenter Admin of handmatig: HTTP, alleen 127.0.0.1
7450–7459 fbagent, zolang het koppelvenster open is RCM hosts koppelen (hoofdstuk 1.3)
13050 fbagent, alleen 127.0.0.1 node op dezelfde host Firebird-beheer
3050 Firebird toepassingen normale databasewerking

Als er twee nodes op één host staan (master en replica), heeft de tweede node een andere poort. Bij installatie via RCM krijgt de tweede node poort 7061. In andere gevallen stelt u de poort zelf in, bijvoorbeeld 7052.

Poort 13050 mag niet naar het netwerk openstaan. Poort 7444 met HTTP (installatie via HQCenter Admin of handmatig) evenmin: maak verbinding met de RCM-webinterface via een SSH-tunnel (hoofdstuk 1). Bij installatie via RCM werkt poort 7444 over HTTPS, en het installatieprogramma opent die poort in de firewall.

De hoofdregel: geen fbagent, geen wijzigingen

Een node wijzigt de replicatieconfiguratie alleen via fbagent: daarvoor moet Firebird worden herstart. Als fbagent niet beschikbaar is, weigert de node elke actie die de configuratie wijzigt. Hij werkt niet „gedeeltelijk”.

Termen

Term Betekenis
Segment een replicatielogbestand met databasewijzigingen
Publicatie de lijst van mastertabellen waarvan de wijzigingen in segmenten komen (Firebird 4/5)
Initialisatie (reinit) overdracht van een kopie van de database van de master naar de replica via nbackup
Database-GUID de Firebird-database-id; RCM gebruikt die om de master en de replica te koppelen
Peer partnernode: voor een master, zijn replica’s
Companion de tweede node op dezelfde Firebird-instantie (master en replica op één host)
Enroll registratie van masterdatabases in de node

De handleiding lezen

Hoofdstuk Onderwerp
1. Installatie installatie van nodes en RCM via HQCenter Admin, via RCM zonder HQCenter Admin en handmatig, Linux en Windows
2. Clusterconfiguratie koppelingen master → replica, node-instellingen, RCM-gebruikers
3. Een database aan de master toevoegen Enroll, Firebird herstarten, controle
4. Hoe u een database tot replica maakt stappen, de replica voorbereiden, schijfruimte
5. Initialisatie reinit-stappen, invloed op het gebruik, lange transacties, snelheid, fouten
6. De publicatie configureren publicatie in Firebird 4/5, tabellen, nieuwe tabellen, HQbird 2.5/3.0
7. Overige replicatieopties parameters van replication.conf, archief, overdracht, meldingen, pauze, logboeken
8. Een replica omzetten in een gewone database Normaal maken, Promoveren tot master, nieuwe GUID, diensten (switchover, failover), checklist voor switchover

In alle hoofdstukken geldt één voorbeeld:

Wat Waarde
node-a master-node, databases in /databases/master
node-b replica-node, databases in /databases/replica
RCM een afzonderlijke host (mag ook een van de databaseservers zijn)
database employee.fdb

1. Nodes en hqbirdrcm installeren

Er zijn drie installatiemethoden:

Methode Wanneer u die kiest Wat u zelf doet
Via HQCenter Admin (1.2) het gewone pad: de updateserver van HQCenter Admin is bereikbaar, automatische updates zijn nodig u voert het installatiescript van fbagent uit, keurt het verzoek goed, beschrijft het cluster
Via RCM, zonder HQCenter Admin (1.3) er is geen HQCenter Admin, maar u hebt certificaten, configuratie en updates nodig zonder handwerk; tot 3 databaseservers u installeert HQbird op elke host, meldt u aan bij RCM en geeft in Instellingen → Hosts koppelen de hostadressen op
Handmatig (1.4) geen toegang tot HQCenter Admin, gesloten netwerk, bijzondere eisen u installeert de bestanden, maakt certificaten, schrijft node.json en rcm.json, registreert de services

Via HQCenter Admin en via RCM installeert u de nodes en RCM niet zelf. Ze worden geïnstalleerd door fbagent wanneer u die aan het cluster toevoegt (hoofdstuk 2). Certificaten en configuratie worden ook automatisch gemaakt.

Linux en Windows staan in één hoofdstuk. De Windows-verschillen staan in de kaders „Op Windows”.

1.1. Eisen

Op elke databaseserver:

  • Firebird / HQbird 5.0, 4.0, 3.0 of 2.5 (2.5 — alleen Linux).
  • fbagent naast elke Firebird-instantie. Zonder fbagent werkt de node niet.
  • Tijdsynchronisatie (NTP, chrony, w32time) op alle servers en op de RCM-host. Herstart- en overdrachtsvensters, de schatting van de achterstand en de controle „node reageert niet” hangen af van de klokken.
  • Vrije ruimte voor het segmentarchief en voor replica-initialisatie (hoofdstuk 4).
  • Netwerk volgens de poortentabel (hoofdstuk 0).

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

Windows: beheerdersrechten, x64, Windows 10 / Server 2016 of nieuwer, 64-bits Windows PowerShell 5.1. Op Windows 10 en Server 2016–2022 is 7-Zip vereist.

Waar RCM zal draaien. Per cluster is één RCM nodig. Die kan op elke server worden geïnstalleerd die alle nodes kan zien, ook op een van de databaseservers.

1.2. Installatie via HQCenter Admin

Stap 1. Het installatiescript van fbagent uitvoeren

Het script installeert Firebird (de HQbird-build), fbagent, en registreert fbagent op de server van HQCenter Admin. Kies het script dat bij uw Firebird-versie past: fb25, fb30, fb40, fb50.

Linux (als root):

Command
sudo sh fbagent-fb50_known.sh --goafts <HQCenter-Admin-server> --enroll --cluster

Op Windows (PowerShell als beheerder):

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

Er is geen parameter -Cluster op Windows: fbagent draait als LocalSystem en maakt de clustermappen zelf.

Belangrijkste parameters:

Linux Windows Betekenis
--goafts <name> -Goafts HQCenter Admin-server waarvan wordt gedownload; de naam krijgt u van uw leverancier
--enroll -Enroll fbagent registreren in HQCenter Admin (certificaataanvraag)
--cluster — de mappen /opt/hqclusternode en /opt/hqbirdrcm maken (alleen nodig voor fbagent 2.55.2 en ouder; onschadelijk voor nieuwere versies)
--channel -Channel updatekanaal van fbagent, standaard stable
--token -Token licentietoken: HQCenter Admin keurt het verzoek automatisch goed
--port -Port Firebird-poort
--yes -Yes geen vragen stellen (nodig als er geen terminal is)

De volledige lijst parameters staat in de README van het installatiescript van fbagent.

Stap 2. Het fbagent-verzoek goedkeuren

Met de parameter --enroll stuurt fbagent een certificaataanvraag (CSR) naar HQCenter Admin en wacht tot 30 minuten op goedkeuring. U kunt die als volgt goedkeuren:

  • automatisch — als de installatie met een licentietoken (--token) is uitgevoerd en de licentie een vrije plaats heeft;
  • in het paneel van HQCenter Admin — de sectie CSR-verzoeken, het verzoek van deze host, de knop goedkeuren en ondertekenen;
  • via de API van HQCenter Admin — POST /v1/admin/csr-requests/{id}/approve.

Als de registratie niet is gelukt (bijvoorbeeld omdat de wachttijd voorbij was), werkt fbagent nog wel, maar het script eindigt met code 2. Voer het script opnieuw uit met dezelfde parameters: alleen de registratie wordt herhaald.

Een paar minuten na de registratie installeert fbagent zelf HQ Monitor.

Stap 3. Het cluster beschrijven

Nodes en RCM verschijnen zodra u fbagent aan het cluster van HQCenter Admin toevoegt. Hoe u het cluster beschrijft, staat in hoofdstuk 2.

Na het opslaan van het cluster:

  1. Binnen 10 minuten ontvangt fbagent het cluster van HQCenter Admin (daarna controleert hij elke 60 seconden op wijzigingen).
  2. De fbagent op de RCM-host maakt de certificaatautoriteit (CA) van het cluster en ondertekent de certificaten van alle nodes.
  3. Elke fbagent schrijft node.json of rcm.json voor zijn clusterleden.
  4. Bij de volgende productcontrole (elke 3 minuten) installeert fbagent de services en start ze.

Wat wordt geïnstalleerd en waar:

Wat Linux Windows
Master-node /opt/hqclusternode/master/, service hqclusternode-master-p<port> <HQbird>\hqclusternode\master\, service HQClusterNode-master-p<port>
Replica-node /opt/hqclusternode/replica/, service hqclusternode-replica-p<port> <HQbird>\hqclusternode\replica\, service HQClusterNode-replica-p<port>
RCM /opt/hqbirdrcm/, service hqbirdrcm <HQbird>\hqbirdrcm\, service hqbirdrcm

<port> is de Firebird-poort, bijvoorbeeld 3050. Eén fbagent kan niet meer dan één master-node, één replica-node, één RCM en één router huisvesten (hqclusternode router, vanaf HQbird 2027.2.30, hoofdstuk 8.7).

Op Windows. fbagent-versies vóór 2.83.0 installeerden nodes in C:\hqclusternode en RCM in C:\hqbirdrcm. Als deze mappen bestaan, blijft fbagent ze gebruiken.

Updates

  • fbagent controleert elke 3 minuten op nieuwe versies van de node en RCM; het standaardkanaal is stable. Eerst wordt de replica-node bijgewerkt, daarna de master-node.
  • Als de service na een update niet start of de verkeerde versie meldt, draait fbagent terug naar de vorige versie en blokkeert de nieuwe. De lijst van blokkades: <fbagent-map>/update/<product>/blocked-versions.json. Om de versie opnieuw te proberen, verwijdert u de regel uit dit bestand.
  • Productstatus: fbagent --product-status hqclusternode (of hqbirdrcm).

1.3. Installatie via RCM (zonder HQCenter Admin)

Het cluster wordt beheerd door RCM. De fbagent van elke host ontvangt de clusterbeschrijving van RCM, de fbagent op de RCM-host ondertekent certificaten, en de node en RCM worden bijgewerkt vanuit releases die RCM bewaart.

Beperkingen:

  • Eén cluster per RCM.
  • Niet meer dan 3 zetels. Een zetel is een host waarop een master- of replica-node draait. Een master en een replica op dezelfde host tellen als één zetel. Een host die alleen RCM draait, neemt geen zetel in. Een vierde host geeft de fout seats_exceeded.
  • RCM werkt fbagent of Firebird niet bij. fbagent werkt ze zelf bij en raakt replication.conf, node.json, rcm.json of certificaten niet aan.

Er zijn twee methoden:

  • Hosts koppelen in RCM — de gewone methode. Drie handelingen: het installatieprogramma op elke host (RCM op één host, discovery-modus op de andere), aanmelden bij RCM, het formulier Hosts koppelen.
  • Handmatig vanaf de opdrachtregel — join-tokens en fbagent --cluster-join. Nodig als poort 7450 tussen hosts gesloten is of het koppelvenster al gesloten is.

Licentie. De proeflicentie bevat de functie cluster. Na de proefperiode installeert fbagent geen node of RCM als de licentie cluster mist. Hij blokkeert nooit updates van al geïnstalleerde nodes en RCM. Zonder HQCenter Admin stopt een zwevende licentie na online_check_days plus respijtdagen. Installeer daarom op elke fbagent een gebonden licentie:

Command
fbagent --license-request --out license_request.json
# send the file to the vendor and receive license.json
fbagent --license-install license.json

Zonder licentie stopt de master met het versturen van segmenten (hoofdstuk 2.8).

Poorten:

Poort Waar Wie verbindt
7443 RCM-host fbagent en nodes van alle clusterhosts
7444 RCM-host browser van de operator (RCM-console, HTTPS)
7450 (op de tweede en volgende fbagent-host — 7451…7459) host in discovery-modus, zolang het koppelvenster open is RCM op de RCM-host
7051 (tweede node van dezelfde fbagent — 7061) node-hosts andere nodes en RCM (1.4, stap 7)

Hosts koppelen in RCM

Voorbeeld vanaf nul. Twee Linux-servers, het installatieprogramma .run, koppelen, registratie, publicatie, initialisatie en herinitialisatie onder belasting — met schermafbeeldingen en metingen: de handleiding hqbird2027-linux-cluster-guide.ru.md en het runbook hqbird2027-linux-cluster-runbook.ru.md (repository goafts, map documentation).

Stap 1. HQbird op elke host installeren

Installeer HQbird met het volledige installatieprogramma op elke databaseserver. Registreer niet bij HQCenter Admin (--enroll).

Standaard configureert het installatieprogramma geen cluster. Het plaatst de programma’s van de node en van RCM in de fbagent-map (update/<product>/staged/), maar installeert RCM niet, opent het koppelvenster niet en opent de clusterpoorten niet in de firewall. Het cluster wordt ingeschakeld met twee parameters:

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 — op één host, waar de RCM van het cluster zal draaien. Het installatieprogramma:

  1. maakt het cluster van deze host (fbagent --cluster-init); de clusternaam is de hostnaam;
  2. installeert en start RCM; de RCM-console werkt over HTTPS op poort 7444;
  3. maakt de eerste RCM-beheerder rcmadmin met een willekeurig wachtwoord;
  4. opent de poorten 7443, 7444 en de node-poort 7051 in de firewall.

--cluster-pairing on (discovery-modus) — op elke andere host. Het installatieprogramma opent het koppelvenster van fbagent gedurende 24 uur: poort 7450 en node-poort 7051. Zolang het venster open is, kan een RCM uit het netwerk deze host uitnodigen in zijn cluster. fbagent begint binnen een minuut te luisteren op poort 7450.

Zonder deze parameters vraagt het installatieprogramma het zelf: in de tekstinterface is dat de pagina Cluster, met --no-tui — twee vragen. Het standaardantwoord is „nee”. --yes zonder clusterparameters antwoordt ook „nee” op beide vragen.

Aan het eind drukt het installatieprogramma de regels RCM: en Pairing:. Op de 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

Op een andere 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

Er staat geen wachtwoord in de uitvoer: het staat in het bestand van de regel Password:. Noteer de fingerprint van elke host in discovery-modus.

Clusterparameters in het Linux-installatieprogramma:

Parameter Wat het doet
--rcm on|off RCM installeren en een cluster op deze host maken; standaard off
--cluster-pairing on|off discovery-modus: het koppelvenster 24 uur openen; standaard off
--pairing-port N koppelpoort van de nieuwe fbagent, 7450–7459; standaard de eerste vrije
--rcm-password-file F wachtwoord van de RCM-beheerder uit de eerste regel van bestand F, in plaats van willekeurig
--cluster-id ID clusternaam ID in plaats van de hostnaam (met --rcm on)
--cluster-node on|off het node-programma installeren; standaard on
--rcm-allow A,B alleen deze RCM’s mogen deze host uitnodigen: adres, CIDR-netwerk of naam

De eerste fbagent op een host krijgt koppelpoort 7450 en node-poorten 7051 en 7061. De tweede instantie op dezelfde host — 7451, 7052 en 7062.

RCM en het koppelvenster kunt u later inschakelen, zonder het installatieprogramma: in HQ Monitor, de pagina Clusters, of met opdrachten als de fbagent-gebruiker:

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

Oude installatieprogramma’s (fbagent vóór 3.1.0) vragen niet naar het cluster: ze installeren RCM op elke host en openen overal het koppelvenster. U hebt de RCM van één host nodig; de RCM’s van andere hosts stoppen zichzelf na het koppelen.

Op Windows. Dezelfde twee keuzes bestaan in het Windows-installatieprogramma: de parameters /RCM en /DISCOVERY.

Stap 2. Aanmelden bij RCM

Open het adres uit de regel RCM: van de RCM-host (https://<host>:7444). Meld u aan met de login rcmadmin en het wachtwoord uit het bestand in de regel Password:. RCM vraagt meteen om een nieuw wachtwoord (1.5).

Stap 3. De hosts koppelen

Open in RCM Instellingen → Hosts koppelen.

  1. Voer in het veld Hosts de adressen of namen van de hosts in, één per regel. De eerste regel is de RCM-host; die zit al in het cluster.
  2. Klik op Hosts controleren. RCM peilt de koppelpoorten 7450–7459 van elke host en toont het platform, de Firebird-versie, de vingerafdruk en de toestand. De RCM-host heeft geen koppelvenster nodig. Vergelijk de vingerafdrukken met de uitvoer van het installatieprogramma (de regel Pairing:).
  3. Selecteer de Master (standaard de eerste host) en klik op Koppelen.
Hosts koppelen: resultaat van de controle
Hosts koppelen: resultaat van de controle

RCM vraagt om bevestiging en toont de voortgang in de sectie Voortgang. Als alle nodes draaien, staat er „Gereed” en het revisienummer van het cluster:

Hosts koppelen: alle nodes draaien
Hosts koppelen: alle nodes draaien

Hetzelfde vanaf de opdrachtregel:

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

Wat er daarna gebeurt:

  1. RCM stuurt een uitnodiging naar elke vrije host.
  2. De fbagent van de host treedt toe tot het cluster en sluit de koppelpoort. Als de host een eigen RCM zonder nodes heeft, stopt fbagent die en schakelt hem uit, en verplaatst het lege cluster naar cluster/left/ in de fbagent-map.
  3. RCM bewaart het cluster: node <host>-master op de master, <host>-replica op de andere hosts, poort 7051, koppelingen master → replica.
  4. De fbagent van elke host installeert de node en start hem. RCM wacht tot alle nodes draaien en toont Actief voor elke host.

Hosttoestanden na Hosts controleren:

Toestand Wat te doen
Gereed om te koppelen niets. Als eronder staat „De eigen RCM van deze host stopt na het koppelen” — dat is normaal
In cluster de host zit al in dit cluster
Fout unreachable poort 7450 is gesloten: het koppelvenster is uit (zoals standaard) of de 24 uur zijn voorbij. Wacht vlak na de installatie een minuut en klik opnieuw op Hosts controleren. Open anders het venster (--cluster-pairing on) en controleer de firewall
Fout in_other_cluster de host zit in een ander cluster
Fout claimed een andere RCM koppelt deze host nu
Fout seats_exceeded meer dan 3 zetels

Releases. fbagent installeert de node alleen vanuit RCM. RCM haalt ondertekende releases uit zijn map import/ (naast rcm.json) bij het starten en elke 5 minuten. Het installatieprogramma zet de releases van de RCM-host daar, en de fbagents van andere hosts downloaden zelf de release voor hun platform. De lijst releases staat onderaan de pagina Hosts koppelen. Een release kan ook handmatig worden geïmporteerd (stap 5 hieronder).

Handmatig vanaf de opdrachtregel

Volgorde: stappen 1–3 op de RCM-host, stap 4 op elke andere host, stappen 5–6 in RCM.

Stap 1. HQbird met fbagent installeren

Installeer HQbird op elke databaseserver en op de RCM-host met het volledige installatieprogramma. Op de RCM-host kunt u meteen --rcm on opgeven (dan is stap 3 niet nodig). Op andere hosts geeft u geen clusterparameters op: standaard is er geen RCM en geen koppelvenster. Registreer niet bij HQCenter Admin (--enroll).

Op de RCM-host laat het installatieprogramma het RCM-programma achter in de fbagent-map (update/hqbirdrcm/staged/). Zonder dat mislukt stap 3 met de fout no hqbirdrcm to install.

Stap 2. De gebonden licentie installeren

Zoals aan het begin van de sectie, „Licentie”.

Stap 3. Het cluster op de RCM-host maken

Als het installatieprogramma het cluster al heeft gemaakt (--rcm on: een regel RCM: met een adres in de uitvoer), slaat u deze stap over.

Voer de opdracht uit als de fbagent-gebruiker (op Linux — firebird), niet als root: anders zijn de CA-bestanden en rcm.json eigendom van root.

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

Op Windows (PowerShell als beheerder): .\fbagent.exe --cluster-init shop-prod --address 10.0.0.7

  • shop-prod — clusternaam: kleine Latijnse letters, cijfers en -.
  • --address — het adres van de RCM-host waarmee andere hosts verbinding maken. Kan meerdere keren worden herhaald. Zonder de parameter worden de adressen en de naam van de host gebruikt.

De opdracht:

  1. maakt de cluster-CA en de agent-CA (in de fbagent-map, clusterca/<name>/);
  2. schrijft het RCM-certificaat, rcm.json en cluster-init.json naar de RCM-map;
  3. installeert RCM en registreert de service hqbirdrcm. Op Linux draait de service als een afzonderlijke gebruiker hqbirdrcm;
  4. schakelt fbagent over naar RCM (cluster.source = rcm) en herstart hem;
  5. drukt het RCM-adres en de CA-vingerafdruk:
Code
Cluster:    shop-prod
RCM URL:    https://10.0.0.7:7443
CA hash:    sha256:9f86d0...

Noteer RCM URL en CA hash: die zijn nodig op de andere hosts. Opnieuw uitvoeren voor hetzelfde cluster is veilig: de CA en de sleutels blijven dezelfde.

Meld u meteen aan bij RCM en wijzig het wachtwoord van rcmadmin (1.5).

Op Linux. De gebruiker hqbirdrcm zit in de groep fbagent. RCM leest rcm.json via deze groep, maar kan het niet schrijven. Daarom slaat Instellingen → RCM wijzigingen niet op (fout rcm_config_read_only). Bewerk rcm.json op de host als de fbagent-gebruiker en herstart RCM.

Stap 4. fbagents van andere hosts verbinden

  1. Maak op de RCM-host een join-token voor elke fbagent: in RCM Instellingen → Cluster, de knop Join-token maken. Of vanaf de opdrachtregel:

    Command
    cd /opt/hqbirdrcm
    export RCM_USER=rcmadmin RCM_PASSWORD='<password>'
    ./hqbirdrcm cluster join-token -note db2

    Het token is 24 uur geldig, voor één fbagent en slechts één keer. RCM toont het één keer, samen met een kant-en-klare opdracht.

  2. Voer op de node-host deze opdracht uit als de fbagent-gebruiker:

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

    In plaats van --token-file kunt u --token <token> gebruiken. Op Windows — hetzelfde met .\fbagent.exe in PowerShell als beheerder.

fbagent controleert de RCM-CA op vingerafdruk. Als de vingerafdruk niet klopt, stopt hij en schrijft hij niets. Daarna ontvangt fbagent zijn certificaat (90 dagen, automatisch verlengd) en herstart. Een verbonden fbagent is zichtbaar in RCM in de tabel Agents. Zolang hij geen leden heeft, wordt er niets op de host geïnstalleerd.

Stap 5. Releases in RCM importeren

fbagent haalt de node en RCM alleen uit RCM. Als de vereiste release niet in de lijst Releases in de spiegel staat (Instellingen → Hosts koppelen), importeert u elk product (hqclusternode, hqbirdrcm) voor elk platform van uw hosts (linux-amd64, windows-amd64). Het releasebestand en de handtekening .sig komen van de leverancier.

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 zoekt de handtekening in <file>.sig, of u geeft die op met -sig. Zonder een geldige handtekening van de leverancier accepteert RCM het bestand niet.
  • Een nieuwe release vervangt de vorige. Een herstart van RCM is niet nodig.
  • fbagent controleert elke 3 minuten op nieuwe versies. De updatevolgorde en de vergrendeling zijn zoals via HQCenter Admin (1.2, „Updates”).

Stap 6. Het cluster beschrijven

Stel de leden en koppelingen in in RCM, Instellingen → Cluster (hoofdstuk 2.3). Na het opslaan installeert fbagent de nodes op dezelfde manier als via HQCenter Admin (1.2, stap 3): hij schrijft certificaten, node.json en rcm.json, installeert de services en start ze.

Poorten — aan het begin van de sectie.

1.4. Handmatige installatie

Stap 1. HQbird met fbagent installeren

Installeer HQbird op elke databaseserver (met hetzelfde script, maar zonder --enroll, of met het volledige HQbird-installatieprogramma). Controleer dat fbagent draait.

Noteer drie waarden uit agent_config.json van fbagent. Die zijn nodig voor node.json:

fbagent-veld veld in node.json Voorbeeld
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 controleren (het antwoord is de JSON van de Firebird-instantie):

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

Als de host meerdere HQbird-instanties heeft, laat u in firebird.update.services van de fbagent-configuratie alleen de service van uw instantie staan (zie 3.5).

Stap 2. De bestanden neerzetten

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

Op Windows. De standaardmap is C:\hqclusternode met dezelfde indeling. Een pad met een spatie is toegestaan.

Als één host twee nodes heeft (master en replica), geef elk een eigen map, bijvoorbeeld /opt/hqclusternode/master en /opt/hqclusternode/replica.

Stap 3. De certificaten maken

Nodes en RCM communiceren alleen over mTLS. U hebt één CA nodig en een certificaat voor elke deelnemer. Voer dit eenmaal uit op een willekeurige machine:

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

De opdracht maakt ca.crt en ca.key, node-a.crt/.key, node-b.crt/.key en rcm.crt/.key. Zet in -hosts alle namen en adressen waarop de deelnemers bereikbaar zullen zijn.

gencerts en de bestanden die het maakte
gencerts en de bestanden die het maakte

ca.key is de CA-sleutel. Kopieer die niet naar de hosts; bewaar hem apart.

Een nieuwe node wordt later toegevoegd met -add: die ondertekent het paar met dezelfde CA, en de andere bestanden blijven ongewijzigd:

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

Certificaten zijn 90 dagen geldig. gencerts -out certs -list toont de vervaldata, en gencerts -out certs -renew verlengt ze met dezelfde sleutel. Kopieer het nieuwe .crt naar zijn host: de node pakt het op zonder herstart.

Kopieer ca.crt en alleen het eigen certificaat en de eigen sleutel naar elke host.

Stap 4. node.json schrijven

Eén bestand per node. Voorbeeld voor de 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" } ]
}

De replica-node (node-b) heeft hetzelfde bestand, maar met "role": "replica", eigen certificaten, en de master node-a in peers.

Belangrijkste velden:

Veld Waarde
node_id naam van de node; dezelfde in het certificaat, in rcm.json en in de peers van andere nodes
role master of replica
listen_addr het adres van de node-API; een tweede node op dezelfde host gebruikt een andere poort (:7052)
rcm.url het adres voor het ontvangen van RCM-statistieken; none — geen RCM
firebird.* de Firebird en fbagent van deze instantie; de fbagent-waarden moeten exact overeenkomen
firebird.auto_restart of de replica-node Firebird zelf mag herstarten: auto (standaard), never, always
windows.restart_window het herstartvenster van Firebird; voor de master is de standaard 22:00-05:00, voor de replica is het altijd
windows.transfer_window het venster waarin initialisatie op volle snelheid loopt
peers voor de master — zijn replica’s, voor de replica — zijn master
databases de databasemap; beter niet met de hand schrijven, maar instellen via RCM (hoofdstuk 3)

De overige velden hebben standaardwaarden. De node start niet als de fbagent-velden niet zijn ingesteld.

Bescherm het bestand: het bevat het wachtwoord en het token.

Command
chmod 600 /opt/hqclusternode/node.json

Op Windows. Schrijf paden in JSON-formaat: "C:\\HQbird\\replication.conf". service_name is de Windows-servicenaam van Firebird.

Stap 5. rcm.json schrijven

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 — het node-adres zoals de RCM-host het ziet. Alleen https.
  • host — het label van de Firebird-instantie. Een master-node en een replica-node met hetzelfde label draaien op dezelfde Firebird (companion, nodig om een replica tot master te promoveren, hoofdstuk 8). Eén label — niet meer dan één master en één replica.
  • Relatieve paden worden opgelost vanuit de map van rcm.json.

Stap 6. De services registreren

Startvolgorde: eerst RCM, dan de replica’s, dan de master.

RCM (Linux):

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

Node (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 maakt de service hqclusternode-<role>-p<port> die draait als de gebruiker firebird. Als de Firebird-map eigendom is van root, geeft de opdracht de groep firebird schrijfrechten erop (met de sticky bit) en drukt elke wijziging: de node moet replication.conf kunnen vervangen.

Voor svc start, svc stop en svc uninstall geeft u dezelfde node.json op: de servicenaam wordt afgeleid van de rol en de Firebird-poort.

Op Windows (PowerShell als beheerder):

Command
cd C:\hqclusternode
.\hqclusternode.exe svc install -config C:\hqclusternode\node.json -certs C:\hqclusternode\certs

De service HQClusterNode-<role>-p<port> draait als LocalSystem, start automatisch en herstart na een fout. De node-service hangt niet af van de Firebird-service. Als de node is geïnstalleerd met versie 2027.1.2–2027.1.9, verwijdert u de afhankelijkheid eenmalig: .\hqclusternode.exe svc fix-deps -config C:\hqclusternode\node.json.

svc install en svc start op Windows
svc install en svc start op Windows

Stap 7. De poorten openen

Sta op de node-host inkomende verbindingen toe op 7051 (de poort van listen_addr) vanaf de andere nodes en vanaf RCM. Sta op de RCM-host inkomende verbindingen toe op 7443 vanaf alle nodes. Stel de poorten 7444 en 13050 niet open naar buiten.

Voorbeeld ufw op de node-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

Handmatige update

Stop de service, vervang het programma, start de service:

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

De configuratie en de certificaten worden hierdoor niet gewijzigd.

1.5. Eerste aanmelding bij RCM

Het adres en het wachtwoord hangen af van hoe RCM is geïnstalleerd.

Hoe RCM is geïnstalleerd Adres Login en wachtwoord
Door het HQbird-installatieprogramma of fbagent --cluster-init (1.3) https://<RCM-host>:7444 vanaf elke computer rcmadmin en het wachtwoord dat het installatieprogramma heeft afgedrukt (of uw eigen wachtwoord uit --rcm-password-file)
Via HQCenter Admin (1.2) of handmatig (1.4) http://127.0.0.1:7444, alleen op de RCM-host rcmadmin, wachtwoord strong password (met een spatie)

HTTPS (1.3). Het RCM-certificaat is ondertekend door de cluster-CA, die de browser niet kent, dus hij waarschuwt. Op de aanmeldpagina toont RCM de CA-vingerafdruk. Vergelijk die met de CA hash die het installatieprogramma heeft afgedrukt, en importeer de CA in de browser of in het systeem als vertrouwde root: de koppeling CA-certificaat downloaden op de aanmeldpagina (https://<RCM-host>:7444/ca.crt, bestand hqcluster-ca.crt). Om RCM alleen op localhost te laten luisteren, zet u "operator_addr": "127.0.0.1:7444" in rcm.json en herstart u RCM.

HTTP (1.2, 1.4). Maak vanaf een andere computer verbinding via een SSH-tunnel:

Command
ssh -L 7444:127.0.0.1:7444 <rcm-host>

Open daarna http://127.0.0.1:7444 in uw browser.

Aanmeldpagina van RCM
Aanmeldpagina van RCM

Gegenereerd wachtwoord. RCM vraagt u het bij de eerste aanmelding te wijzigen: tot u het wijzigt, gaan de andere pagina’s niet open. Wijzig het strong password onmiddellijk (de koppeling Wachtwoord in de kop).

Het wachtwoord wijzigen bij de eerste aanmelding
Het wachtwoord wijzigen bij de eerste aanmelding

Taal. Kies Russisch in de talenlijst in de paginakop (die is ook beschikbaar op de aanmeldpagina). Als u er geen kiest, wordt de taal uit de browser genomen.

Wachtwoorden wijzigen en nieuwe gebruikers

Elke gebruiker wijzigt het eigen wachtwoord: de koppeling Wachtwoord in de paginakop. U hebt het huidige wachtwoord nodig en een nieuw wachtwoord van minstens 12 tekens. Na de wijziging worden de andere sessies van die gebruiker gesloten.

Als het installatieprogramma een wachtwoord heeft gegenereerd, staat het in het bestand clusterca/<name>/rcm-initial-password in de fbagent-map. Nadat het wachtwoord is gewijzigd, verwijdert fbagent dit bestand zelf. Verwijder het bestand initial-admin.json in de RCM-map niet: het bevat alleen een hash. Als het gebruikersbestand verloren is en dit bestand ontbreekt, maakt RCM een gebruiker met het standaardwachtwoord.

Nieuwe gebruikers. Er is geen gebruikerspagina in de interface. Gebruikers staan in het bestand rcm-data/users.json. Het wachtwoord wordt opgeslagen als een HA1-hash: MD5("<name>:hqbirdrcm:<password>").

  1. Bereken de hash:

    Command
    printf '%s' 'rcmadmin:hqbirdrcm:<new password>' | md5sum
  2. Schrijf die in het veld ha1 van de gebruiker in users.json. Om een gebruiker toe te voegen, voegt u een extra element toe aan users:

    json
    { "username": "ivanov", "ha1": "<hash>", "algo": "MD5", "created_at": "2026-11-03T00:00:00Z" }
  3. Herstart RCM onmiddellijk: het bestand wordt alleen bij het starten gelezen. Als een wachtwoord in de interface wordt gewijzigd, herschrijft RCM het bestand vanuit het geheugen, en gaan bewerkingen die het nog niet heeft gelezen verloren.

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

Zonder een veld role heeft een gebruiker alle rechten. Sinds HQbird 2027.2.31 is er een rol "role": "viewer": alleen bekijken, elk wijzigingsverzoek krijgt 403.

1.6. Hoe u de installatie controleert

  • De services van de node en van RCM draaien en herstarten niet in een lus: systemctl status hqclusternode-master-p3050, systemctl status hqbirdrcm.

    systemctl status van de node
    systemctl status van de node
systemctl status van RCM
systemctl status van RCM
  • RCM antwoordt (zonder wachtwoord): curl http://127.0.0.1:7444/healthz. Bij installatie via RCM (1.3) werkt de console over HTTPS: curl -k https://127.0.0.1:7444/healthz.

  • In RCM toont de pagina Overzicht alle nodes, zonder de markering „reageert niet”.

  • Vanaf de opdrachtregel op de RCM-host:

    Command
    export RCM_USER=rcmadmin RCM_PASSWORD='<password>'
    ./hqbirdrcm nodes
    ./hqbirdrcm status
  • Het cluster via RCM: Instellingen → Cluster, de sectie Status — elk lid heeft de laatste revisie toegepast en meldt geen fout. Vanaf de opdrachtregel: ./hqbirdrcm cluster status.

1.7. Logboeken

Wat Waar
Node-logboek <map van node.json>/logs/node-YYYYMMDD.jsonl
Uitvoer van de node-service (Linux) journalctl -u hqclusternode-<role>-p<port>
Uitvoer van de RCM-service (Linux) journalctl -u hqbirdrcm
Replicatielogboek van Firebird firebird.replication_log uit node.json
Logboeken van een willekeurige node zonder SSH RCM, pagina Logboeken

1.8. Veelvoorkomende fouten

Wat u ziet Oorzaak Wat te doen
De node start niet: een fout over fbagent_url, fbagent_token of instance_id fbagent draait niet of de waarden komen niet overeen met agent_config.json controleer fbagent met de opdracht curl uit 1.4, stap 1
Het installatiescript eindigde met code 2 het fbagent-verzoek is niet op tijd goedgekeurd keur het verzoek goed en voer het script opnieuw uit
Nodes verschijnen niet via HQCenter Admin fbagent zit niet in het cluster, of het cluster is nog niet opgehaald controleer het cluster (hoofdstuk 2), wacht tot 10 minuten
De node in RCM is „reageert niet” poort 7051 is gesloten, de url in rcm.json is onjuist, het adres staat niet in het certificaat controleer de poorten en de -hosts van de certificaten
Geen aanmelding bij RCM: „Te veel mislukte aanmeldpogingen” 10 mislukte aanmeldingen binnen 5 minuten wacht een paar minuten
De nieuwe versie wordt niet geïnstalleerd de versie staat in blocked-versions.json verwijder de versieregel uit het bestand
--cluster-init: no hqbirdrcm to install het installatieprogramma heeft het RCM-programma niet achtergelaten installeer HQbird met het volledige installatieprogramma (1.3, „Handmatig”, stap 1)
--cluster-join: token_used, token_expired, token_revoked het token is al gebruikt, is ouder dan 24 uur, of is ingetrokken maak een nieuw token (1.3, „Handmatig”, stap 4)
--cluster-join: hostname_conflict het cluster heeft een fbagent met dezelfde hostnaam en andere adressen geef de hosts verschillende namen
--cluster-join: this agent is in cluster … from goafts fbagent zit al in het cluster van HQCenter Admin verwijder hem uit het cluster van HQCenter Admin
De node wordt niet geïnstalleerd via RCM RCM heeft geen release voor dit platform hqbirdrcm release list, importeer de release (1.3, „Handmatig”, stap 5)

2. Clusterconfiguratie

In dit hoofdstuk bepaalt u welke nodes in het cluster zitten en welke master segmenten naar welke replica stuurt. Daarna configureert u de RCM-nodes en de gebruikers.

Relaties worden op een van drie manieren vastgelegd:

Nodes geïnstalleerd Waar relaties worden vastgelegd Sectie
via HQCenter Admin in HQCenter Admin: de pagina Clusters van HQ Monitor of de API van HQCenter Admin 2.2
via RCM, zonder HQCenter Admin in RCM: Instellingen → Cluster, hqbirdrcm cluster of de pagina Clusters van HQ Monitor 2.3
handmatig in RCM: Instellingen → RCM en Instellingen → Knooppunten 2.3

Op nodes die via HQCenter Admin of via RCM zijn geïnstalleerd, wijzigt u relaties alleen in de clusterbeschrijving. fbagent overschrijft node.json en rcm.json volgens de clusterbeschrijving. Relaties bewerken in Instellingen → RCM of Instellingen → Knooppunten van RCM wordt geweigerd (409 cluster_managed). Eerdere versies van RCM accepteerden het, maar het ging verloren.

2.1. Rollen en schema’s

Elke node heeft één rol: master of replica. Twee nodes — een master en een replica — kunnen op één Firebird-instantie draaien.

Ondersteunde schema’s:

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

De koppeling loopt altijd van de master naar de replica. RCM koppelt de database van de master aan zijn replica op database-GUID, niet op nodenaam.

Companion. Een master-node en een replica-node op dezelfde Firebird-instantie zijn companions. Promotie van een replica tot master (hoofdstuk 8) werkt alleen voor zo’n paar. In rcm.json is het paar gemarkeerd door een gelijke waarde van host.

2.2. Koppelingen via HQCenter Admin

Waar u een cluster beschrijft

  • HQ Monitor, pagina Clusters (alleen beheerders; levering van configuratie moet aanstaan). De gewone manier.
  • API van HQCenter Admin: POST /v1/admin/clusters en PUT /v1/admin/clusters/{id}. Het paneel van HQCenter Admin heeft geen clusterpagina.

``

Stappen op de pagina Clusters

  1. Voer een Nieuw cluster-id in (kleine Latijnse letters, cijfers en -) en klik op Maken.
  2. Voeg leden toe (Leden). Geef voor elk op:
    • de fbagent van de host;
    • de rol: master, replica of rcm;
    • de hostadressen;
    • de poort: voor een node — 7051 (een tweede node op dezelfde host — bijv. 7052), voor RCM — de opnamepoort voor statistieken 7443.
  3. Voeg koppelingen toe (Replicatiekoppelingen) van de master naar de replica.
  4. Klik op Valideren, daarna op Opslaan.

Als een andere beheerder het cluster tegelijk heeft gewijzigd, vraagt de pagina u het cluster opnieuw te laden en de wijziging te herhalen.

Regels

  • Een fbagent kan maar tot één cluster behoren.
  • Op één fbagent — niet meer dan één master, één replica, één RCM en één router. De router (rol router, vanaf HQbird 2027.2.30) heeft geen koppelingen en neemt geen licentiezetel in (hoofdstuk 8.7).
  • Een cluster heeft precies één RCM. De fbagent op de RCM-host voert de certificaatautoriteit (CA) van het cluster.
  • De lidnaam (member_id) — Latijnse letters, cijfers, -. De naam, de fbagent en de rol van een lid kunnen niet worden gewijzigd. Om een lid naar een andere host te verplaatsen, maakt u een nieuw lid met een nieuwe naam. Gebruik de oude naam niet opnieuw.
  • Elke replica moet een koppeling naar de master hebben.
  • HQCenter Admin bouwt het node-adres zelf: https://<eerste adres>:<port>.
  • HQbird 2.5/3.0: stel de datum replconf_valid_till van het cluster in (YYYY-MM-DD) — de configuratie van de replconf-plug-in is geldig tot die datum.

Voorbeeld via de 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"}]}
  • Maken: POST /v1/admin/clusters (het document kan samen met de leden worden verstuurd). Het hele document vervangen: PUT /v1/admin/clusters/{id}.
  • PUT vereist de header If-Match: <revision> (de revisie komt van GET en ETag). Zonder de header — 428, met een oude revisie — 409, met een fout in het document — 422 met een lijst fouten.
  • POST /v1/admin/clusters/{id}/validate valideert het document zonder op te slaan.
  • GET /v1/admin/clusters/{id}/status toont de toestand van de leden en de vervaldata van certificaten.

Wat er gebeurt na het opslaan

  1. De fbagent van elk lid ontvangt het cluster. Binnen het cluster — een controle elke 60 seconden (de fbagent op de RCM-host — elke 30 seconden). Buiten een cluster hoort een fbagent over het cluster bij de volgende configuratiepeiling. Als die peiling de server niet bereikt, loopt de controle elke 10 minuten.
  2. Elke fbagent maakt een sleutel en stuurt een certificaataanvraag. De fbagent op de RCM-host ondertekent die. RCM ondertekent het eigen certificaat zonder aanvraag.
  3. fbagent schrijft in node.json: naam, rol, adres, peers (uit de koppelingen), het RCM-adres, certificaatpaden, Firebird- en fbagent-gegevens. In rcm.json: de lijst nodes (nodes), de lijst routers (routers), het opnameadres voor statistieken en de certificaatpaden. fbagent raakt de andere velden van de bestanden niet aan.
  4. fbagent installeert de services en start ze (hoofdstuk 1).

Een cluster wijzigen:

Wat veranderde Wat fbagent doet
alleen de peers van een draaiende node geeft ze door aan de node zonder herstart
andere velden van een node stopt de node, schrijft het bestand, start de node — binnen de windows.transfer_window van de node (niet ingesteld — onmiddellijk)
rcm.json herstart RCM onmiddellijk
certificaten of CA herstart de service
een lid wordt verwijderd stopt en verwijdert de service; cluster-managed.json → cluster-removed.json, het programma → *.removed; de configuratie, certificaten en gegevens blijven

Nadat een node is verwijderd, blijft zijn sectie # BEGIN managed-by:<name> … # END … in de gedeelde replication.conf. Verwijder die met de hand en herstart Firebird via RCM.

Clustercertificaten goedkeuren

Standaard ondertekent de fbagent op de RCM-host verzoeken zelf (auto). Handmatige goedkeuring kan worden ingeschakeld. Opdrachten op de 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>

In de modus manual wacht een nieuw lid of een nieuwe sleutel op goedkeuring. Vernieuwing van een certificaat met een bekende sleutel wordt automatisch ondertekend.

2.3. Koppelingen via RCM

RCM-cluster (zonder HQCenter Admin)

Als het cluster is gemaakt door het HQbird-installatieprogramma of door de opdracht fbagent --cluster-init (hoofdstuk 1.3), bewaart RCM de clusterbeschrijving. De eenvoudigste manier om hosts toe te voegen is op de pagina Instellingen → Hosts koppelen (hoofdstuk 1.3, „Hosts koppelen in RCM”): RCM maakt de leden en koppelingen zelf. De regels zijn dezelfde als in HQCenter Admin (2.2, „Regels”), plus:

  • in RCM is er één cluster; het lid rcm bestaat altijd en kan niet worden verwijderd;
  • niet meer dan 3 zetels (hosts met master- of replica-nodes), anders treedt de fout seats_exceeded op;
  • een lid kan alleen worden toegevoegd op een fbagent die verbinding heeft gemaakt met RCM (hoofdstuk 1.3: „Hosts koppelen” of „Handmatig”, stap 4).

Stappen op de pagina Instellingen → Cluster:

  1. Klik in de tabel Agents op Lid toevoegen in de rij van de fbagent.
  2. Geef de rol op (master, replica of router), member_id, adressen en poort. De pagina stelt de naam <host>-<role> voor en de poort: 7051 voor de eerste fbagent-node, 7061 voor de tweede. Een poort die al door een ander lid van de host is bezet, weigert RCM. De adressen van fbagent zijn knoppen: klik om een adres toe te voegen.
  3. Klik in de sectie Koppelingen op Koppeling toevoegen van de master naar de replica.
  4. Klik op Valideren: RCM toont fouten en waarschuwingen.
  5. Klik op Opslaan. De pagina toont de lijst wijzigingen en vraagt om bevestiging. Als leden worden verwijderd, is het venster rood.

Vóór het opslaan bestaan de wijzigingen alleen op de pagina (het label „Niet opgeslagen”). Als iemand het cluster tegelijk heeft opgeslagen, biedt de pagina aan het opnieuw te laden. Als alleen RCM-velden zijn veranderd (revisie, CA, opdrachten), slaat de pagina uw wijziging zelf op.

Andere secties van de pagina:

Sectie Wat er staat
kop clusternaam, revisie, cluster-CA en agent-CA; de knop Exporteren voor de oude CA
Verbindingstokens een token maken voor een nieuwe fbagent, een ongebruikt token intrekken
JSON-document het hele document in een tekstveld; Valideren en Opslaan gebruiken het
Sleutels en CA’s opdrachten: nieuwe lid-sleutel (rekey), nieuwe cluster-CA (rotate_ca), nieuwe agent-CA (rotate_agent_ca); niet beschikbaar als er niet-opgeslagen wijzigingen zijn
Status de revisie die elk lid heeft toegepast, vervaldatum van het certificaat, service, laatste fout

Vanaf de opdrachtregel op de 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

Het documentformaat is als in 2.2, „Voorbeeld via de API”. apply met een oude revisie krijgt 409: voer show opnieuw uit. RCM bewaart de laatste 20 revisies in rcm-data/cluster/history/.

HQ Monitor. De pagina Clusters werkt ook met RCM. Op de RCM-host benadert HQ Monitor RCM via de fbagent van die host, met het certificaat van fbagent: de RCM-gebruiker en het wachtwoord zijn niet nodig. In het auditlogboek van RCM worden zulke acties vastgelegd als agent:<id> (<user>). Een andere manier, voor eerdere RCM-versies: zet in de configuratie van HQ Monitor rcm_admin_url (http://127.0.0.1:7444), rcm_admin_user (de RCM-gebruiker) en rcm_admin_password_file (een bestand met het wachtwoord).

Na het opslaan verloopt alles zoals via HQCenter Admin (2.2, „Wat er gebeurt na het opslaan”). RCM leest nodes in rcm.json zelf opnieuw, zonder herstart.

Een fbagent uit het cluster verwijderen: verwijder zijn leden en sla op, klik daarna op Intrekken in de tabel Agents (of ./hqbirdrcm cluster revoke -agent <id>). Om hem terug te brengen, is een nieuw token nodig. Na intrekking verlaat de fbagent (vanaf versie 3.1.0) het cluster zelf: hij stopt zijn nodes en verwijdert de clustergegevens. Hetzelfde doet op een node-host de opdracht fbagent --cluster-leave. Op de RCM-host wordt die geweigerd.

Handmatige installatie: een node aan RCM toevoegen

  1. Instellingen → RCM, de tabel Verbonden knooppunten.
  2. Klik op Knooppunt toevoegen. Vul node_id, url (https://<adres>:7051), rol, host (label van de Firebird-instantie) en server in (alleen voor groepering op het scherm).
  3. Klik op Valideren in de rij van de node: RCM controleert de verbinding en de rechten.
  4. Klik op Opslaan. RCM schrijft rcm.json en bewaart het oude bestand als rcm.json.<UTC-tijd>.bak (de laatste 20).
  5. Herstart RCM. Tot de herstart geldt de oude configuratie; de pagina toont welke velden op een herstart wachten.
Instellingen → RCM
Instellingen → RCM
Command
sudo systemctl restart hqbirdrcm

U kunt het ook zonder de interface doen: bewerk rcm.json en herstart RCM.

Handmatige installatie: master en replica koppelen

De koppeling moet aan beide kanten worden vastgelegd:

  1. Instellingen → Knooppunten, selecteer de master-node.
  2. Klik in de sectie Partners op Partner toevoegen: de node_id van de replica, zijn url, compressie (zstd).
  3. Klik op Opslaan. RCM toont de lijst wijzigingen en vraagt om bevestiging. De wijziging van peers gaat onmiddellijk in.
  4. Herhaal dit voor de replica-node: zijn partner is de master.
De sectie Partners van de master-node
De sectie Partners van de master-node

Als de partner niet aan een van de kanten is vastgelegd, biedt RCM die replica-node niet aan bij het initialiseren van de database.

2.4. Node-instellingen

Instellingen → Knooppunten toont de instellingen van node.json die de node vanuit RCM laat wijzigen. Alleen de gewijzigde velden worden opgeslagen, na een venster met de lijst wijzigingen.

Instellingen → Knooppunten: een node selecteren
Instellingen → Knooppunten: een node selecteren
Database-instellingen van de node met markeringen "na scan"
Database-instellingen van de node met markeringen „na scan”

Elke rij is gemarkeerd met wanneer de wijziging ingaat:

Wanneer Welke instellingen
Onmiddellijk channel_a_mbps, channel_a_burst_mbps, windows.restart_window, peers; vanaf HQbird 2027.2.24 — instellingen voor gegevenscontrole (limits.data_check_*); vanaf HQbird 2027.2.31 — advertise_addr
Na herstart van de node de overige limieten, windows.transfer_window; de pagina toont ze op een aparte regel tot de node is herstart
Na scan databases.*, exclude_filter; als replication.conf is gewijzigd, is een herstart van Firebird nodig (hoofdstuk 3.5)

Alleen-lezen (gewijzigd in node.json op de node-host): firebird (inclusief het wachtwoord en auto_restart), rcm, tls, segments, het adres listen_addr.

Belangrijkste instellingen:

Instelling Standaard Betekenis
windows.restart_window master 22:00-05:00, replica — altijd wanneer de node Firebird mag herstarten; de Firebird-master herstart zichzelf nooit
windows.transfer_window 23:00-05:00 het venster waarin initialisatie loopt met de snelheid reinit_window_mbps
limits.channel_a_mbps 50 overdrachtssnelheid van segmenten, MB/s (channel_a_burst_mbps — kortstondige piek, 200)
limits.reinit_window_mbps 100 initialisatiesnelheid binnen het overdrachtsvenster, MB/s
limits.reinit_day_disk_fraction 0.5 fractie van de gemeten schijfsnelheid voor initialisatie buiten het venster
limits.retention_days 2 hoeveel dagen verzonden segmenten in het archief van de master blijven
limits.free_space_floor_gb 1 minimale vrije ruimte, GB; daaronder accepteert de replica geen segmenten
limits.max_concurrent_reinits 1 hoeveel initialisaties de node tegelijk uitvoert

Bijzonderheden over snelheid en archiefbewaring staan in de hoofdstukken 5 en 7.

firebird.auto_restart (alleen in node.json) bepaalt of een replica-node Firebird zelf mag herstarten:

Waarde Gedrag
auto (standaard) mag, als deze Firebird geen masterdatabases bedient
never nooit
always altijd, ook als deze Firebird masterdatabases huisvest

Via HQCenter Admin. De windows.transfer_window van de fbagent-node wordt ook gebruikt als venster voor het herstarten van de node-service zelf wanneer het cluster verandert. Als het venster niet in node.json staat, herstart fbagent de service onmiddellijk.

2.5. Meerdere HQbird-instanties op één host

fbagent herstart de services die in firebird.update.services van zijn configuratie staan. Een lege lijst betekent alle HQbird-services op de host. Laat alleen de service van uw eigen instantie in de lijst staan. De node ziet deze instelling niet en schrijft een waarschuwing fbagent_shared in het logboek als fbagent meer dan één instantie kent.

2.6. SYSDBA-wachtwoord

De node maakt verbinding met Firebird met de gebruiker en het wachtwoord uit firebird.user en firebird.password in node.json. fbagent bewaart een eigen kopie van het wachtwoord. Als u het SYSDBA-wachtwoord hebt gewijzigd:

  1. Corrigeer firebird.password in node.json van elke node van deze instantie (master en replica).
  2. Corrigeer het wachtwoord in de configuratie van fbagent en laad die opnieuw (zie de documentatie van fbagent).
  3. Herstart de node-services.

Anders tonen de publicatie- en controlepagina’s in RCM een aanmeldfout (SQLSTATE 28000).

2.7. RCM-gebruikers en audit

  • Gebruikers staan in het bestand rcm-data/users.json (hoofdstuk 1.5). Zonder rol heeft een gebruiker alle rechten; de rol viewer (vanaf HQbird 2027.2.31) — alleen bekijken.
  • Een sessie duurt 12 uur na de laatste actie.
  • Na 10 mislukte aanmeldingen binnen 5 minuten wordt aanmelden voor die gebruiker en dat adres tijdelijk geblokkeerd. Een geslaagde aanmelding zet de teller terug.
  • Het auditlogboek is het bestand rcm-data/audit.jsonl: één JSON-regel per wijziging, aanmelding en afmelding. Er is geen auditlogboek in de interface.
  • De pagina Opdrachten toont de auteur van elke opdracht.

2.8. Licentie

Eenmaal per minuut leest de master-node de fbagent-licentie van zijn host. Als er geen licentie is (de proefperiode is afgelopen, de licentie is verlopen of ongeldig), stopt de node met het verzenden van segmenten voor alle databases op de master. Firebird en de databases blijven draaien, maar replica’s ontvangen geen wijzigingen meer.

Wat u in RCM ziet:

  • de master is rood (NEEDS_ATTENTION), met een badge „geen licentie: verzending gestopt”;
  • er is geen knop Hervatten: alleen de licentie heft de pauze op;
  • op de replica: „ontvangt niet sinds …: de master heeft geen licentie”;
  • in de tabel Knooppunten een badge „geen licentie”; in Instellingen → Knooppunten het licentieblok van fbagent;
  • de meldingen license_paused en license_pause_archive_released;
  • initialisatie is verboden (license_paused).
Licentieblok van fbagent in Instellingen → Knooppunten
Licentieblok van fbagent in Instellingen → Knooppunten

Installeer de licentie in fbagent. De node heft de pauze zelf binnen een minuut op. De master bewaart het archief voor replica’s gedurende limits.retention_days (standaard 2 dagen) vanaf het begin van de pauze. Als u de licentie later installeert, moeten de replica’s opnieuw worden geïnitialiseerd.

Cluster via RCM, zonder HQCenter Admin. Een zwevende licentie zonder HQCenter Admin stopt na online_check_days plus de respijtdagen. Elke fbagent in het cluster heeft een gebonden licentie nodig (fbagent --license-request, daarna fbagent --license-install, hoofdstuk 1.3, „Licentie”). Na de proefperiode voegt fbagent geen nieuwe node of RCM toe zonder de functie cluster in de licentie; updates verbiedt hij nooit. Voor HQbird 2.5/3.0 mag de datum replconf_valid_till in RCM niet later zijn dan het einde van de licentie plus de respijtdagen op de fbagent-nodes (fout replconf_after_license).

2.9. Hoe u controleert

  • Overzicht: alle nodes zijn aanwezig en gegroepeerd per server.

    Clusteroverzicht
    Clusteroverzicht
  • Instellingen → Knooppunten: de master heeft een replica in Partners, en de replica heeft de master.

  • Instellingen → RCM: de knop Controleren in de rij van elke node slaagt.

  • Clusterrapport als één bestand:

    Command
    ./hqbirdrcm report -o report.json

2.10 Veelvoorkomende fouten

Wat u ziet Oorzaak Wat te doen
Bewerken van partners in RCM geweigerd (409 cluster_managed) of verloren na herstart van de node de node is geïnstalleerd via HQCenter Admin of via RCM wijzig de koppelingen in de clusterbeschrijving (2.2, 2.3)
seats_exceeded bij het opslaan van het cluster in RCM nodes op een vierde host niet meer dan 3 hosts met nodes
Instellingen → RCM: rcm_config_read_only cluster via RCM op Linux: rcm.json is eigendom van fbagent bewerk rcm.json als de fbagent-gebruiker en herstart RCM
Intrekken van een agent werkt niet (agent_has_members) fbagent heeft leden verwijder eerst de leden en sla op
Replica-node wordt niet aangeboden tijdens initialisatie de partner is niet aan een van de kanten vastgelegd voeg de partner aan beide kanten toe (2.3)
Een wijziging in Instellingen → RCM gaat niet in RCM is niet herstart herstart RCM
422 bij het opslaan van het cluster in HQCenter Admin een fout in het document herstel volgens de lijst errors, controleer via validate
409 bij het opslaan van het cluster het cluster is door iemand anders gewijzigd lees het cluster opnieuw en probeer opnieuw
Een nieuw clusterlid van HQCenter Admin ontvangt geen certificaat handmatige goedkeuring op de RCM-host fbagent --cluster-ca-approve <id>
Fout SQLSTATE 28000 op publicatiepagina’s het SYSDBA-wachtwoord is gewijzigd 2.6

3. Een database aan de master toevoegen

In dit hoofdstuk komt de masterdatabase onder beheer van de node. De node legt hem vast in replication.conf en maakt mappen voor de segmenten. Na het herstarten van Firebird is de database gereed voor replicatie.

De replica maken zijn de volgende stappen (publicatie, initialisatie). Die staan in de hoofdstukken 4–6.

De knopnamen zijn gegeven volgens de Russische RCM-interface, met de Engelse tussen haakjes.

3.1. Hoe een node databases ontdekt

De master-node zoekt databases in één map — de databasewortel (databases.root). Wat onder beheer komt, bepalen regels:

Regel Veld Standaard
Databasemap root niet ingesteld
Submappen doorzoeken recursive ja
Inclusiemasker template *.fdb
Exclusiemasker exclude_mask geen
Bestandsgrootte, MB min_size_mb, max_size_mb geen limieten (0)
Tabellen voor gegevensvergelijking sync_tables met HQbird 2027.2.24 — tabellen uit de publicatie van de database, als die er niet zijn — RDB$FIELDS; in 2027.5.7 — RDB$FIELDS
Inclusielijst include_paths leeg (sjabloonmodus)
Exclusielijst exclude_paths leeg

Het pad root is een pad op de node-host, niet op de RCM-host. De node past eerst het inclusiemasker toe, daarna het exclusiemasker, daarna de grootte.

De regels gelden voor de hele node. De lijst sync_tables is ook gedeeld: de controle (hoofdstuk 5.10) zoekt elke tabel uit de lijst in elke database van de node die geen eigen lijst heeft.

Tabellen voor vergelijking, met HQbird 2027.2.24. Elke database kan een eigen lijst hebben (Synchronisatietabellen). De node bewaart die in databases.sync_tables_by_db. De controle neemt de eerste lijst die is ingesteld:

  1. de eigen lijst van de database;
  2. de gedeelde lijst sync_tables van de node;
  3. tabellen uit de publicatie van de database;
  4. RDB$FIELDS.

Een eerder opgeslagen gedeelde lijst gaat vóór de publicatie: een database zonder eigen lijst gebruikt die. De databasepagina van de master toont welke lijst nu geldt (3.3).

Een tabel die zowel in de primaire database als in de replica ontbreekt, krijgt de status „niet in de database” (absent): die wordt niet vergeleken, en de controle toont daardoor geen „Niet OK”. Een tabel die maar aan één kant ontbreekt, is een afwijking.

RCM en node 2027.5.7. Er is één lijst voor de hele node (sync_tables); zonder lijst gebruikt de controle RDB$FIELDS. Een ontbrekende tabel is een fout, en de databasecontrole toont „Niet OK”.

Alle regels staan in node.json van de node. De node past ze bij elke scan toe.

Sjabloonmodus en lijstmodus:

  • Sjabloonmodus (inclusielijst leeg): de node neemt alle bestanden die bij het masker passen, behalve uitgesloten bestanden. Een nieuw bestand in de map pakt de node automatisch op bij de volgende scan.
  • Lijstmodus (inclusielijst niet leeg): de node neemt alleen de bestanden uit de lijst. Een nieuw bestand komt niet automatisch onder beheer — het moet worden toegevoegd.

Kies de lijstmodus als de map databasekopieën, testdatabases of andere bestanden bevat die niet gerepliceerd hoeven te worden.

3.2. Voordat u begint: rechten controleren

De gebruiker waaronder Firebird en de node draaien (firebird op Linux, LocalSystem op Windows) moet lees- en schrijfrechten hebben op:

  • de databasewortelmap en de databasebestanden;
  • replication.conf en zijn map (de node vervangt het bestand via een tijdelijk bestand);
  • de segmentmappen <database>.ReplLog en <database>.LogArch (de node maakt die zelf).

RCM controleert de rechten vóór registratie (preflight). Als de controle mislukt, eindigt de opdracht met de fout preflight failed on <node> en een lijst paden.

Controle op de node-host (Linux):

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

3.3. Pagina voor database-inschrijving

Database-inschrijving: formulier en voorbeeld
Database-inschrijving: formulier en voorbeeld
  1. Open de inschrijfpagina van de master-node. De koppeling staat op twee plaatsen:

    • Databases → tabel Knooppunten → kolom acties → Inschrijven;
    • Overzicht → kaart van de master-node → Databases inschrijven.

    Een replica-node heeft deze pagina niet.

  2. Het formulier toont de huidige regels van de node (de node heeft ze zelf gestuurd). Als de node niet reageert, zijn de knoppen voorbeeld en inschrijven uitgeschakeld: zonder de huidige regels zouden ze de include- en exclude-lijsten terugzetten.

  3. Vul de velden in of corrigeer ze: Pad naar de map op deze server, recursive, maskers, Groottefilter, Synchronisatietabellen.

    Het veld Synchronisatietabellen:

    • met HQbird 2027.2.24 en later — de lijst is per database die deze actie zal inschrijven. Leeg veld: de database gebruikt de tabellen van zijn eigen publicatie. Inschrijven wijzigt de gedeelde lijst van de node niet (sync_tables). Als die bestaat, zegt het formulier dat: een database zonder eigen lijst gebruikt die in plaats van de publicatie. De lijst van een al beheerde database stelt u in op zijn pagina: Databases → masterdatabase → blok Synchronisatietabellen. Het blok toont welke lijst nu geldt. Een leeg veld verwijdert de eigen lijst van de database;
    • in RCM en node 2027.5.7 — één lijst voor alle databases van de node (sync_tables).
  4. Klik op Voorbeeld. De node toont alle bestanden die bij het inclusiemasker passen. Hij wijzigt niets.

  5. Controleer de lijst. Elk bestand heeft een selectievakje:

    • aangevinkt — het bestand komt onder beheer;
    • aangevinkt, vergrendeld, gemarkeerd al in beheer — de database is al ingeschreven;
    • vergrendeld met een reden — het bestand is uitgesloten door masker, grootte of de exclude-lijst. Om het toch te nemen, wijzigt u de regel.
  6. Vink de gewenste databases aan en klik op Geselecteerde inschrijven. RCM vraagt om bevestiging en toont het aantal bestanden.

Bevestiging van de inschrijving
Bevestiging van de inschrijving

Wat deze knop doet:

  • in sjabloonmodus — bestanden zonder vinkje worden aan de exclude-lijst toegevoegd, bestanden met een vinkje worden eruit gehaald;
  • in lijstmodus — bestanden met een vinkje worden aan de include-lijst toegevoegd.

De knop voegt databases toe aan wat al onder beheer staat. Hij wijzigt vergrendelde rijen niet. 7. De knop Inschrijven past het formulier toe zonder de lijsten te wijzigen. 8. Wacht op het voltooiingsbericht en het aantal toegevoegde databases. Als er lang geen antwoord komt, controleer het resultaat op de pagina Opdrachten.

Met HQbird 2027.2.24 en later is het bericht „Ingeschreven: N”. Als de Firebird van de master herstart moet worden, zegt RCM welke knop u moet indrukken (meestal Firebird van de master herstarten in de rij van de database) en geeft een koppeling naar de masterdatabases. RCM 2027.5.7 kan „Geen nieuwe geschikte databases” zeggen, ook al zijn databases toegevoegd: controleer de pagina Databases.

Resultaat van de inschrijving
Resultaat van de inschrijving

Als er na de inschrijving geen databases zijn gevonden, maar de node al databases had, weigert de node (409) en geeft de oude regels terug. Zo schakelt een fout in het pad de replicatie van alle databases niet uit.

Hetzelfde vanaf de opdrachtregel

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

Let op: de opdracht stuurt alleen de velden uit zijn parameters. De overige regels (maskers, groottes, include- en exclude-lijsten, sync_tables) worden door de node teruggezet. De opdracht heeft geen parameters voor deze regels. Controleer vóór het uitvoeren de huidige regels (hqbirdrcm getconfig -node node-a). Als ze zijn ingesteld, gebruik de inschrijfpagina.

3.4. Wat er gebeurt na registratie

  1. De node schrijft de regels naar node.json.
  2. De node scant de map (scansync).
  3. Voor elke gevonden database schrijft de node een blok in zijn eigen gebied van replication.conf (tussen de regels # BEGIN managed-by:node-a role:master en # END …) en maakt de mappen <database>.ReplLog en <database>.LogArch. De node wijzigt geen tekst buiten zijn eigen gebied.
  4. Vóór een wijziging bewaart de node een kopie van het bestand: replication_YYYYMMDD_hhmmss_NNN.conf.
  5. Als replication.conf is gewijzigd, komen de databases in de toestand PENDING_RESTART: Firebird leest het nieuwe bestand pas na een herstart. In de tabel Knooppunten staat dit in de kolom Herstart in behandeling.
De kolom Herstart in behandeling in de tabel Knooppunten
De kolom „Herstart in behandeling” in de tabel „Knooppunten”

Toestanden van een nieuwe database:

Toestand Groep in RCM Betekenis
UNCONFIGURED In behandeling database gevonden, configuratie nog niet geschreven
PENDING_RESTART In behandeling configuratie geschreven, herstart van Firebird vereist
CONFIGURED In behandeling Firebird herstart, database gereed voor publicatie en initialisatie

3.5. De Firebird van de master herstarten

De master-node herstart Firebird nooit zelf. RCM ook niet. Het herstarten van de master is de beslissing van de operator: een herstart verbreekt alle verbindingen met alle databases van die Firebird-instantie.

Kies een rustig moment en klik op een van de knoppen:

  • Firebird van de master herstarten — op de pagina Databases, in de rij van de master van de database die op een herstart wacht;
  • dezelfde knop in het venster Initialiseren, hoofdstuk 5;
  • Firebird herstarten — op de databasepagina.

RCM vraagt om bevestiging. Het toont de nodenaam en een waarschuwing: Firebird herstart onmiddellijk, zonder herstartvenster, en alle verbindingen worden verbroken.

Bevestiging van de herstart van de Firebird van de master
Bevestiging van de herstart van de Firebird van de master

Hetzelfde vanaf de opdrachtregel

Command
hqbirdrcm restartfirebird -node node-a

Deze opdracht herstart ook onmiddellijk, zonder herstartvenster.

Hoe de node Firebird herstart:

  1. Controleert dat fbagent antwoordt en dezelfde instantie beheert (id, poort, servicenaam uit node.json). Als een waarde niet overeenkomt, weigert de node.
  2. Vraagt fbagent Firebird te herstarten.
  3. Wacht tot Firebird op zijn poort antwoordt.
  4. Zet de databases van PENDING_RESTART naar CONFIGURED.

Meerdere HQbird-instanties op één host. fbagent herstart de services die in firebird.update.services van zijn configuratie staan. Een lege lijst betekent alle HQbird-services op de host. Als er twee HQbird-instanties op de host zijn, laat alleen de service van uw instantie in de lijst staan. Anders stopt het herstarten van één node ook de andere instantie.

Op Windows. Als replication.log is gegroeid tot log_portion_mb of meer, verloopt de herstart zo: Firebird stoppen → het logboek archiveren → starten.

3.6. Een database die al handmatig wordt gerepliceerd

Als replicatie voor een database al handmatig is geconfigureerd (een eigen blok in replication.conf, publicatie aan, segmenten stromen), kan die onder beheer worden gebracht zonder de replica opnieuw te initialiseren. Daarvoor is er een modus detect_existing (alleen master).

  1. Voer een voorbeeld uit:

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

    In het antwoord somt taken_over de databases op die worden gemigreerd. Voeg -verbose toe om de overgeslagen databases met de reden te zien.

  2. Als de lijst klopt, voer de opdracht uit zonder -dry-run.

De node migreert een blok alleen als:

  • de segmentmappen exact <database>.ReplLog en <database>.LogArch heten;
  • er al segmenten in het archief staan;
  • publicatie in de database is ingeschakeld.

De node migreert een blok met andere paden niet en meldt het als „gevonden maar niet ondersteund”.

Na de migratie krijgen de databases PENDING_RESTART, ook al zijn de replicatie-instellingen niet gewijzigd: alleen de positie van het blok in het bestand verandert. Herstart Firebird in een onderhoudsvenster.

3.7. Hoe u controleert

  • Databases: de database is zichtbaar in de rij van de master-node, toestand CONFIGURED (na herstart).

  • Naast de database kan een pictogram publicatie UIT staan: publicatie is nog niet ingeschakeld. Dat is normaal, publicatie is de volgende stap (hoofdstuk 6).

    Nieuwe database in de rij van de master
    Nieuwe database in de rij van de master
  • Op de node-host: het databaseblok staat in replication.conf binnen het gebied managed-by:node-a, en naast de database staan de mappen .ReplLog en .LogArch.

3.8. Een database uit beheer verwijderen

De gewone manier is de knop. Vink op de pagina Databases de databases aan, kies de bulkactie Uit beheer verwijderen en klik op Toepassen op selectie. RCM:

  1. voegt de bestanden toe aan de exclusielijst van de node;
  2. scant de map één keer: de databaseblokken worden uit replication.conf verwijderd;
  3. verwijdert de databaserecords in de node.

De databasebestanden en segmentmappen blijven op schijf. Firebird wordt niet herstart. Firebird blijft de databasesegmenten schrijven tot zijn volgende herstart; RCM zegt of een herstart nodig is.

RCM weigert (has_replicas) voor een masterdatabase die een levende replica heeft: anders zou de replica stilzwijgend stoppen. Maak de replica eerst tot een gewone database of verwijder hem (hoofdstuk 8).

Verwijder het databaseblok niet met de hand uit replication.conf: bij de volgende scan schrijft de node het opnieuw.

Als het databasebestand is verdwenen of door een regel is uitgesloten. Dan krijgt de database de toestand ORPHANED (de groep Verweesd). De node bewaart zijn record en het segmentarchief: een ontbrekende database is vaker een vergissing dan een besluit. Als het bestand terugkomt, werkt de database weer en wordt de melding gewist. Om zo’n database definitief te verwijderen, voert u twee stappen in deze volgorde uit:

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>

Na forgetdatabase vindt de opdracht cleanuparchive de database niet meer. Beide opdrachten werken alleen voor een database in de toestand ORPHANED en raken het databasebestand niet aan.

Let op. Na het promoveren van een replica tot master (hoofdstuk 8) voert u cleanuparchive -orphaned niet uit voor het oude record: de nieuwe master gebruikt dezelfde map .LogArch, en de opdracht verwijdert zijn werkende archief.

3.9. De databasewortel wijzigen

Registratie met een ander pad is toegestaan. De node:

  • voegt databases uit de nieuwe map toe;
  • zet databases uit de oude map die niet in de nieuwe staan op ORPHANED (melding orphaned_database) en bewaart hun archieven.

Als u de verkeerde map koos, registreert u de juiste map opnieuw. Een database met het zelfde volledige pad blijft werken onder dezelfde db_id. Een database op een ander pad is een nieuwe database (nieuwe db_id); zijn replica moet opnieuw worden geïnitialiseerd.

3.10. Veelvoorkomende fouten

Wat u ziet Oorzaak Wat te doen
preflight failed on node-a geen rechten op de mappen herstel de rechten, probeer opnieuw (3.2)
409 scan_would_empty_region de nieuwe map bevat geen databases, maar de node had er wel controleer het pad en het masker
Voorbeeld is leeg het masker past niet of de map is verkeerd controleer het pad, het masker, „recursive”
Knoppen zijn uitgeschakeld, „Kan de nodeconfiguratie niet lezen” de node reageert niet controleer de node-service en het netwerk (hoofdstuk 1)
De database blijft lang in PENDING_RESTART de master herstart Firebird niet zelf herstart Firebird (3.5)
Herstart geweigerd vanwege fbagent fbagent draait niet of zijn gegevens komen niet overeen met node.json hoofdstuk 1, fbagent controleren
Het nieuwe bestand verscheen niet de node staat in lijstmodus voeg het bestand toe via „Geselecteerde inschrijven”

4. Hoe u een database tot replica maakt: stappen en schijflocatie

Dit hoofdstuk behandelt de hele weg van een database van primair naar een werkende replica, plus de berekening van de schijfruimte. De initialisatie zelf staat in detail in hoofdstuk 5.

4.1. De hoofdregel

Een database verschijnt op een replica alleen door initialisatie vanaf de master (reinit): de master-node zelf draagt een kopie over via nbackup.

Maak geen kopie met de hand:

  • gbak maakt een nieuwe database-GUID en zet het segmentnummer terug. De koppeling master — replica breekt.
  • Een bestandskopie van een draaiende database is niet consistent, en RCM ziet twee databases met dezelfde GUID (duplicate_guid) en verbiedt initialisatie.

Een al draaiende replica die handmatig is geconfigureerd, kan onder beheer worden genomen zonder een nieuwe kopie — zie 4.6.

4.2. Stappen

Nr. Stap Waar Toestand van de masterdatabase na de stap
1 De database op de master registreren hoofdstuk 3.3 PENDING_RESTART
2 De Firebird van de master herstarten hoofdstuk 3.5 CONFIGURED
3 De publicatie synchroniseren hoofdstuk 6 CONFIGURED, publicatie AAN
4 De replica voorbereiden: map, rechten, Firebird-versie 4.3 —
5 Vrije ruimte op de master en op de replica controleren 4.4 —
6 Initialisatie hoofdstuk 5 SEEDING → IN_SYNC
7 De Firebird van de replica herstarten (indien nodig) hoofdstuk 5.6 de replica begint segmenten toe te passen
8 De gegevens controleren hoofdstuk 5.10 —

Stap 3 is verplicht voor Firebird 4/5. Zonder publicatie schrijft de Firebird van de master geen tabelwijzigingen naar segmenten, en de replica loopt stilzwijgend achter op de master. Op de pagina Databases is zo’n database gemarkeerd met het pictogram publicatie UIT. Klik op Publicatie synchroniseren vóór de initialisatie.

Vanaf HQbird 2027.2.24 waarschuwt het venster Initialiseren hiervoor en biedt een knop Publicatie synchroniseren en initialiseren, terwijl de master-node initialisatie weigert met de fout publication_off (hoofdstuk 5.1). RCM en node 2027.5.7 controleren de publicatie niet.

HQbird 2.5/3.0. Er zijn geen publicaties, dus stap 3 wordt overgeslagen. De verzameling tabellen wordt bepaald door de filters van de replconf-plug-in (hoofdstuk 6).

Toestanden van de database:

Toestand Groep in RCM Betekenis
CONFIGURED In behandeling Firebird heeft de instellingen gelezen, er is nog geen replica
PUBLISHING In behandeling synchronisatie van de publicatie is bezig
SEEDING In behandeling initialisatie is bezig
IN_SYNC Ok de replica heeft alle segmenten ontvangen
LAGGING In behandeling de replica loopt achter, segmenten staan in de wachtrij
NEEDS_REINIT Fout de replica moet opnieuw worden geïnitialiseerd
FAILED Fout de laatste initialisatie is mislukt

4.3. De replica voorbereiden

Map van de replicadatabase

De replica-node plaatst elke database in zijn eigen map databases.root op het pad:

Code
<databases.root>/<master node name>/<database path relative to the master root>

Voorbeeld: master node-a met wortel /databases/master en database /databases/master/sales/employee.fdb. Op replica node-b met wortel /databases/replica komt de database hier:

Code
/databases/replica/node-a/sales/employee.fdb

Zo botsen databases met dezelfde namen van verschillende masters niet.

Niemand maakt de wortelmap automatisch — niet het installatieprogramma, niet HQCenter Admin en niet de node bij het starten. Maak hem op een van deze manieren:

  • in het venster Initialiseren: het veld Replicamap, de knop Map maken. De knop is alleen zichtbaar als de map niet bestaat. Met HQbird 2027.2.24 bevat het veld al /databases/replica/<replica-node-id> als de replica-node nog geen databases.root heeft. Voor een replica op Windows is het veld leeg: voer een map met een stationsletter in. Elke replica-node op dezelfde host heeft een eigen map nodig. De map wordt gemaakt door de replica-node: eigenaar — firebird (of de gebruiker van de node-service), rechten 2770. Als de node hem niet kan maken, toont het venster de opdracht voor de replica-host. Als u een andere map opgeeft, schrijft RCM die vóór de initialisatie naar databases.root van de replica-node;

  • handmatig op de replica-host (Linux):

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

    De bit setgid (2770) is nodig zodat alle bestanden erin de Firebird-groep krijgen.

U kunt de replicawortel alleen wijzigen zolang er geen databases in staan: anders vallen de oude databases buiten de scan. Om één database op een andere plaats te zetten, gebruikt u Verplaatsen op de databasepagina.

Rechten

De replica-node en Firebird moeten naar de databasewortel kunnen schrijven. De node controleert dat de geplaatste bestanden de groep van de map krijgen. Als dat niet kan, weigert hij met ownership_unfixable en tekst over hoe u het herstelt (meestal draait de node-service met Group=root).

Met HQbird 2027.2.24 toont het venster Initialiseren ook een map die bestaat maar waar de node-service niet naartoe kan schrijven: de tekst van de node met de herstelopdracht en een knop Opnieuw controleren. RCM 2027.5.7 zegt in dat geval „Map bestaat”: controleer de rechten zelf (hqbirdrcm checkpermissions -node <replica> -root <folder>).

Firebird-versie

De hoofdversie van Firebird op de replica moet overeenkomen met de master (5.0 → 5.0, 4.0 → 4.0). Anders weigert de replica vóór enige gegevensoverdracht: incompatible_engine.

Bereikbaarheid

De replica-node moet een peer van de master zijn, en de master een peer van de replica (hoofdstuk 2). Anders biedt RCM deze node niet aan in het venster Initialiseren.

4.4. Hoeveel ruimte is nodig

In het kort

Waar Wat Hoeveel
Master, databasevolume vrij vóór initialisatie ≥ 105 % van de databasegrootte
Replica, volume van de databasemap vrij vóór initialisatie ≥ 105 % van de databasegrootte, met HQbird 2027.2.24 — plus free_space_floor_gb (plus het oude bestand, als de replica al bestond; met het vakje Oude replica verwijderen — zonder dat bestand)
Master, <database>.ReplLog werksegmenten van Firebird tot 64 segmenten × segmentgrootte (standaard 16 MB) ≈ 1 GB per database
Master, <database>.LogArch archief van segmenten voor replica’s wijzigingen over retention_days (standaard 2 dagen) + wat de replica’s nog niet hebben bevestigd
Replica, <database>.Incoming wachtrij van toe te passen segmenten tot 256 segmenten × 16 MB ≈ 4 GB per database in het slechtste geval
Replica, heel volume reserve minstens free_space_floor_gb (standaard 1 GB)

Ruimte controleren vóór initialisatie

Initialisatie controleert de ruimte twee keer en alleen vóór het vergrendelen van de database:

  1. RCM — uit de laatste nodestatistieken, vóór het versturen van de opdracht. Als de ruimte duidelijk onvoldoende is, geeft RCM meteen fout 507 terug.
  2. Master-node — een live meting op het eigen volume, daarna een verzoek aan de replica zodat die het zijne meet. Als er aan minstens één kant te weinig is, eindigt de initialisatie bij de stap RUIMTECONTROLE met de fout insufficient disk space on master of … on replica.

De eis aan beide kanten is 105 % van de grootte van de masterdatabase.

Met HQbird 2027.2.24 rekent de replica-node zo:

  • hij heeft 105 % van de databasegrootte plus de free_space_floor_gb van de replica nodig (7.3): na de initialisatie blijft er op het volume een reserve voor segmenten;
  • resten van eerdere initialisaties (<database>.hqcluster-part, <database>.new) tellen als vrije ruimte: de node verwijdert ze vóór de nieuwe kopie;
  • de fouttekst noemt alle getallen. Hij noemt ook de bestanden <database>.pre-reinit-*.fdb en <database>.failed-seed-*.fdb met hun grootte. De node verwijdert ze nooit: verwijder ze zelf als ze niet nodig zijn.

force (geforceerd) slaat alleen de controle in RCM over. De controle van de node kan niet worden omzeild: die beschermt de node tegen een volle schijf midden in het kopiëren. Als de ruimte alleen tekortschiet door de oude replicakopie, noemt RCM 2027.2.24 in fout 507 het vakje Oude replica verwijderen in plaats van force. Daarvoor moeten beide nodes HQbird 2027.2.24 of nieuwer zijn. Anders noemt de fout de node die moet worden bijgewerkt, en force.

Waarom zoveel

Master. Tijdens het kopiëren is de database vergrendeld door nbackup -L. Alle wijzigingen worden geschreven naar het bestand <database>.delta naast de database. De grootte van .delta hangt af van de schrijfbelasting tijdens het kopiëren. Onder zware belasting en trage overdracht kan het flink groeien — let op de ruimte tijdens de eerste initialisatie.

Replica. De kopie wordt rechtstreeks naar het bestand <database>.hqcluster-part naast de databaselocatie geschreven. De node reserveert de volledige grootte vooraf. Het bestand wordt daarna gecontroleerd, hersteld (nbackup -FIXUP -SEQUENCE) en op zijn plaats hernoemd. Een tweede kopie is niet nodig — de databasegrootte is één keer nodig, op het databasevolume.

Als de replica al bestond (herhaalde initialisatie), blijft het oude bestand op schijf tot de laatste stap. Dat betekent dat het oude bestand en de nieuwe kopie tegelijk op het volume nodig zijn. De vrije ruimte wordt berekend zonder het oude bestand — daarom is de eis dezelfde: 105 % van de databasegrootte vrij.

Oude replica verwijderen (met HQbird 2027.2.24). Als er op het replicavolume geen ruimte is voor de nieuwe kopie naast de oude, vinkt u dit vakje aan in het initialisatievenster (hoofdstuk 5.1). De replica-node verwijdert dan de oude kopie en zijn binnenkomende segmenten (.Incoming) vóór de overdracht, en het volume heeft genoeg voor 105 % van de databasegrootte plus free_space_floor_gb. De node verwijdert de kopie alleen als alle voorwaarden waar zijn:

  • zonder verwijdering is er te weinig ruimte, en met verwijdering is er genoeg;
  • het is een kopie die door de initialisatie van deze node is geïnstalleerd: de header is leesbaar, de modus is alleen-lezen replica;
  • de database is niet normaal gemaakt (geen bestand <database>.hqcluster-normal.json, hoofdstuk 8);
  • overwrite_non_replica is niet ingesteld (5.9).

Anders verwijdert de node niets en weigert hij met de reden in de tekst. Om te verwijderen stopt de node de Firebird van de replica voor de duur van de verwijdering (5.6).

Het vakje staat standaard uit. Risico: zolang de overdracht loopt, is er geen databasekopie op de replica. Als de database maar één replica heeft, is de master de hele tijd onbeschermd. Zolang er geen nieuwe kopie is, staat de database op de replica in de toestand NEEDS_REINIT (niet FAILED en niet ORPHANED), en geeft de replica de melding replica_removed_for_reinit (warn). Zodra de nieuwe kopie op zijn plaats staat, wordt de melding gewist. Als de initialisatie na de verwijdering mislukt, blijft het paar NEEDS_REINIT: start de initialisatie opnieuw (of automatische herinitialisatie start hem, 5.8). Een nieuwe initialisatie draagt de database vanaf het begin over.

Masterarchief (.LogArch). De node bewaart verzonden segmenten retention_days dagen, zodat de replica ze opnieuw kan opvragen. Segmenten die de replica nog niet heeft toegepast, worden langer bewaard. Als de ruimte laag is, ruimt de node het archief in stappen op:

  1. segmenten die door alle replica’s zijn toegepast en ouder zijn dan retention_days;
  2. toegepaste segmenten die nieuwer zijn (als de ruimte krap is);
  3. niet-toegepaste segmenten — alleen als laatste redmiddel. Dan verliest de replica de segmenten die hij nodig heeft en krijgt hij NEEDS_REINIT.

Als een replica lang niet beschikbaar is, groeit het archief. Zijn volume = de databasewijzigingen over de stilstandperiode.

Rekenvoorbeeld

Database 100 GB. Belasting — 5 GB segmenten per dag. Initialisatie loopt ’s nachts, het kopiëren duurt 2 uur, waarin ongeveer 2 GB in .delta terechtkomt.

Waar Berekening Totaal vrij
Master, databasevolume 105 GB voor controles (inclusief groei van .delta) + .ReplLog 1 GB + .LogArch 2 dagen × 5 GB = 10 GB ≥ 116 GB
Replica, nieuwe database 105 GB + .Incoming tot 4 GB + 1 GB reserve ≥ 110 GB
Replica, herhaalde initialisatie oud bestand 100 GB al op schijf + 110 GB vrij volume ≥ 210 GB
Replica, herhaalde initialisatie met het vakje Oude replica verwijderen (met HQbird 2027.2.24) oud bestand verwijderd vóór de overdracht: 105 GB + .Incoming tot 4 GB + 1 GB reserve volume ≥ 110 GB

Tel een reserve op voor databasegroei en voor stilstand van de replica (het masterarchief groeit met 5 GB per dag stilstand).

Segmenten op een apart volume

De mappen .ReplLog, .LogArch en .Incoming staan standaard naast de database. Ze kunnen naar een ander volume worden verplaatst: de parameter segments.storage in node.json (met mirror_hierarchy: true kopieert de node de structuur van de databasemappen). Dan neemt het archief geen ruimte weg van de databases. De controle van 105 % geldt nog steeds voor het databasevolume.

Waar u de ruimte bekijkt

  • Databases → Knooppunten en Overzicht: het pictogram vrije ruimte voor het volume databases.root. Geel — minder dan 20 %, rood — minder dan 10 %.

    Pagina Databases: de kolom Schijf in de tabel Knooppunten
    Pagina Databases: de kolom Schijf in de tabel Knooppunten
  • Clusterrapport: hqbirdrcm report.

4.5. Meerdere replica’s van één database

De tweede en volgende replica’s worden op dezelfde manier gemaakt: Initialiseren in de rij van de master, met een vrije replica-node.

  • Zolang een nieuwe replica wordt geïnitialiseerd, stuurt de master deze database ook niet door naar de al draaiende replica’s. Die halen de master in nadat de initialisatie klaar is. Het bevestigingsvenster zegt dat.
  • Eén database — één initialisatie tegelijk, ook voor verschillende replica’s.
  • De ruimte op de master wordt voor elke initialisatie apart gecontroleerd.
Masterdatabase met twee replica's
Masterdatabase met twee replica's

4.6. Handmatig geconfigureerde replica

Als een replica al draait vanuit een met de hand geschreven replication.conf, kunt u hem onder beheer nemen en de database niet opnieuw kopiëren:

  1. Master: registreer de databases met detect_existing (hoofdstuk 3.6).
  2. Replica: Databases → replica-node → Overnemen, of hqbirdrcm takeover-replica. RCM vindt de replicablokken, koppelt de bestanden aan de masterdatabases op GUID en toont voor elk: in_sync, resumable of needs_reinit.
  3. Bevestig de rijen. De node verplaatst de blokken naar zijn eigen gebied in replication.conf.
  4. Herstart de Firebird van de replica zodat die de verplaatste blokken leest.
  5. Initialiseer alleen de rijen needs_reinit: het masterarchief bevat de segmenten die deze replica’s nodig hebben niet meer.

4.7. Veelvoorkomende fouten

Wat u ziet Oorzaak Wat te doen
insufficient disk space on master / on replica te weinig ruimte (4.4). Bij herinitialisatie neemt de oude kopie ruimte in tot het einde (4.4) maak ruimte vrij, probeer opnieuw. De tweede uitweg op de replica (vanaf HQbird 2027.2.24) is het vakje Oude replica verwijderen (4.4, 5.1)
507 van RCM meteen volgens de ruimtestatistieken is er duidelijk te weinig hetzelfde. Als er ruimte is zonder de oude kopie, noemt RCM 2027.2.24 het vakje Oude replica verwijderen
incompatible_engine verschillende hoofdversies van Firebird werk de Firebird van de replica bij
Map ontbreekt op de replica-node wortel niet gemaakt Map maken in het initialisatievenster (4.3)
Map bestaat, maar de node-service kan er niet naartoe schrijven (vanaf HQbird 2027.2.24) geen schrijfrechten voer de opdracht uit het venster uit, klik op Opnieuw controleren (4.3)
publication_off (vanaf HQbird 2027.2.24) de publicatie van de master is uit of heeft geen tabellen Publicatie synchroniseren en initialiseren (5.1)
ownership_unfixable de node-service heeft een vreemde groep herstel de servicegroep zoals in de fouttekst
duplicate_guid twee databases met dezelfde GUID (een bestandskopie) verwijder de kopie of geef hem een nieuwe GUID (nbackup -F)
Replica-node niet in de lijst Initialiseren geen verbinding in de peers hoofdstuk 2
Replica IN_SYNC, maar de gegevens wijken af de publicatie was uitgeschakeld synchroniseer de publicatie, herhaal daarna de initialisatie

5. Initialisatie (reinit)

Initialisatie is de overdracht van een kopie van de masterdatabase naar de replica. De eerste overdracht heet initialisatie (de knop Initialiseren), een herhaalde overdracht is herinitialisatie (de knop Opnieuw initialiseren). Het mechanisme is hetzelfde.

Voltooi vóór het starten de stappen 1–5 uit hoofdstuk 4: de database is geregistreerd, de Firebird van de master is herstart, publicatie is ingeschakeld, de replicamap bestaat, en er is genoeg ruimte. Hoeveel ruimte op de master en op de replica nodig is, staat in hoofdstuk 4.4.

5.1. Hoe u start

Eerst de publicatie. Het registreren van een database omvat geen publicatie. Zonder publicatie ontvangt de replica geen wijzigingen. Voer vóór de initialisatie Publicatie synchroniseren uit (hoofdstuk 6) of hqbirdrcm setpublication -node <master>.

  • Met HQbird 2027.2.24 controleert het initialisatievenster de publicatie. Als die uit staat of geen tabellen met een sleutel heeft, toont het venster een waarschuwing en een knop Publicatie synchroniseren en initialiseren. RCM synchroniseert de publicatie, wacht tot de opdracht klaar is en start de initialisatie met de keuze uit het venster.
  • Een master-node 2027.2.24 weigert zo’n initialisatie zelf (ook de eerste) met de fout publication_off en geeft de melding master_publication_off (hoofdstuk 6.1). Na de weigering heeft de databasecel opnieuw de knop Publicatie synchroniseren en initialiseren.
  • Als de operator de publicatie heeft uitgezet (6.4) of alle tabellen met een sleutel eruit heeft gehaald (6.3), behoudt de synchronisatie dat. RCM start de initialisatie niet en geeft een koppeling naar de pagina Publicatietabellen.
  • RCM en node 2027.5.7 controleren de publicatie niet: de initialisatie slaagt, de database toont „OK” in RCM, maar de replica ontvangt geen wijzigingen. Als de publicatie na de initialisatie is aangezet — initialiseer de database opnieuw.
Het venster "Database opnieuw initialiseren?"
Het venster „Database opnieuw initialiseren?”
  1. Open Databases.
  2. Klik in de rij van de masterdatabase, in de kolom van de replica-node, op Initialiseren. De replica-node wordt door de kolom bepaald: hij wordt niet in het venster gekozen. Voor een bestaand paar — Reinit in de uitgevouwen masterkaart.
  3. In het venster (met HQbird 2027.2.24 is de titel voor een nieuw paar „Database initialiseren?”; in RCM 2027.5.7 — „Database opnieuw initialiseren?” en ook bij de eerste initialisatie):
    • controleer de Replicamap. Het venster toont of de map bestaat. Als dat niet zo is, klikt u op Map maken: de replica-node maakt hem (4.3). Als de node hem niet kan maken, toont het venster de opdracht voor de replica-host. Met HQbird 2027.2.24 toont het venster ook een map waar de node-service niet naartoe kan schrijven: de herstelopdracht en een knop Opnieuw controleren;
    • kies de Reinit-methode: Soepel (aanbevolen) of Standaard (5.4). Met HQbird 2027.2.24, als het archief van de master nog geen segmenten heeft (meestal vóór de eerste initialisatie), toont het venster een hint: op een drukke database is Standaard sneller;
    • als de masterdatabase nog op een herstart van Firebird wacht, zegt het venster dat en toont een knop Firebird van de master herstarten. Zonder de herstart wordt de database niet gerepliceerd;
    • Oude replica verwijderen (met HQbird 2027.2.24, standaard uit) is alleen nodig bij herinitialisatie als het replicavolume geen ruimte heeft voor een nieuwe kopie naast de oude (4.4). Het venster toont de getallen vooraf: hoeveel nodig is, hoeveel vrij is, hoeveel de oude kopie inneemt. Als er ruimte is zonder de oude kopie, vraagt het venster het vakje aan te vinken. Het vakje is inactief als de master- of replica-node een oude versie is: het venster zegt welke node u moet bijwerken. Tot de nieuwe kopie klaar is, heeft de replica geen kopie van deze database (4.4).
  4. Bevestig. RCM zegt dat de database op de master wordt vergrendeld en naar de replica wordt gekopieerd.

De voortgang van de initialisatie is zichtbaar in de uitgevouwen masterkaart op de pagina Databases: stappen en percentages. Met HQbird 2027.2.24 is de voortgang ook zichtbaar na het vernieuwen van de pagina: bij de eerste initialisatie — in de cel van de replica-node, en ook in de rij Voortgang van herinitialisatie op de pagina van de masterdatabase. De knop Initialiseren is inactief zolang de master-node de database kopieert. Als RCM deze initialisatie niet volgt (bijvoorbeeld gestart vanaf de opdrachtregel van de node), komen de stappen uit de nodetoestand, zonder percentages. In RCM 2027.5.7 is na het vernieuwen van de pagina de voortgang van de eerste initialisatie niet zichtbaar: wacht tot de masterdatabase SEEDING verlaat.

Initialisatiestappen in de rij van de master
Initialisatiestappen in de rij van de master

Elke RCM-opdracht (initialisatie, herstart van Firebird, synchronisatie van de publicatie) wordt op de pagina Opdrachten vastgelegd met het resultaat.

De pagina "Opdrachten"
De pagina „Opdrachten”

Hetzelfde vanaf de opdrachtregel

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

Parameters: -mode smooth|standard (standaard smooth), -hold=false (het archief niet vasthouden tijdens lange transacties), -allow-restart (5.6), -force (5.9).

-remove-old-replica (met HQbird 2027.2.24) — hetzelfde als het vakje Oude replica verwijderen. Alleen voor één database: -db en -to zijn verplicht; met -all weigert de opdracht. Als de master- of replica-node een oude versie is, weigert RCM met node_too_old en stuurt niets.

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

-all probeert alle databases en verzamelt fouten in plaats van bij de eerste te stoppen.

5.2. Stappen

Nr. Stap (in RCM) Wat er gebeurt
1 SPACE CHECK controleert de ruimte op de master en op de replica (hoofdstuk 4.4); de replica controleert vooraf of hij het bestand kan aannemen
2 LOCKING nbackup -L: het databasebestand van de master wordt bevroren, wijzigingen gaan naar <database>.delta
3 COPYING TO NODE het bestand wordt in delen overgedragen: lezen → controlesom → compressie → verzenden
4 UNLOCKING nbackup -N meteen na de overdracht: wijzigingen uit .delta gaan terug naar de database
5 SEEDING op de replica: controle van de controlesom van het bestand, nbackup -FIXUP -SEQUENCE, installatie van het bestand, gfix -replica, het blok schrijven naar replication.conf
6 RESTARTING REPLICA herstart van de Firebird van de replica, als die nodig is (5.6)

Na stap 6 krijgt de database de toestand IN_SYNC. De master blijft segmenten sturen vanaf het punt waar de kopie eindigt.

Wat belangrijk is om te weten:

  • De master draait de hele tijd. Gebruikers schrijven naar de database, wijzigingen gaan naar .delta. De vergrendeling wordt meteen na de overdracht opgeheven.
  • Transacties die samenvielen met de vergrendeling gaan niet verloren. De node vindt de transacties die open stonden op het moment van nbackup -L, en de replica speelt ze af vanuit de segmenten.
  • De overdracht gaat door na een onderbreking. Als de verbinding of de replica-node herstartte, gaat de master verder vanaf het laatst ontvangen deel. Een onafgemaakte overdracht blijft 24 uur op de replica (reinit_partial_keep_hours).
  • Bij een fout heft de node de vergrendeling op, verwijdert het onafgemaakte bestand op de replica en zet de database op FAILED. De volgende poging start vanuit een bekende toestand.
  • Met het vakje „Oude replica verwijderen” (sinds HQbird 2027.2.24) verwijdert de replica de oude kopie na de stap LOCKING, vóór de overdracht. De stap COPYING TO NODE toont dan „oude replicakopie verwijderen om ruimte te maken”. Een fout na de verwijdering geeft het paar NEEDS_REINIT in plaats van FAILED (hoofdstuk 4.4).
  • Alleen nbackup. gbak wordt niet gebruikt: die wijzigt de database-GUID.

5.3. Invloed op het gebruik

Wat Invloed
Gebruikers van de master blijven werken; tijdens het kopiëren groeit .delta, na -N worden de wijzigingen in de database opgenomen
Andere replica’s van deze database ontvangen geen segmenten van deze database zolang de initialisatie loopt; daarna halen ze in
Andere databases van de master niet geraakt
Firebird van de replica, nieuwe database niet gestopt; herstart volgens 5.6
Firebird van de replica, herhaalde initialisatie wordt gestopt terwijl het bestand wordt vervangen: alle databases van deze Firebird zijn seconden niet beschikbaar
Firebird van de replica, de node verwijdert de oude kopie (vakje „Oude replica verwijderen”, sinds HQbird 2027.2.24) wordt eerder gestopt, terwijl de verwijdering loopt, vóór de overdracht. De node installeert de nieuwe kopie zonder een tweede stop als het databaseblok in replication.conf niet is gewijzigd. Als er genoeg ruimte is en geen verwijdering nodig is, verwijdert de node niets, en verloopt alles als bij een normale herhaalde initialisatie
Netwerk en schijf belasting volgens de snelheidslimieten (5.5)

Op Windows. Een bestand dat door Firebird is geopend, kan niet worden vervangen. Bij herhaalde initialisatie stopt de node de Firebird van de replica via fbagent, installeert het bestand en start Firebird opnieuw. Op Linux wordt Firebird ook gestopt vóór vervanging: anders zou hij blijven werken met het oude verwijderde bestand.

5.4. Soepele en standaardmethode

Soepel (standaard). Vóór het vergrendelen zoekt de node naar lange transacties: schrijftransacties van gebruikers die begonnen vóór het oudste segment in het archief van de master. Na de initialisatie kan de replica ze niet afspelen en stopt hij bij hun eerste wijziging („Transactie … is niet gevonden”). Transacties zonder wijzigingen tellen niet mee.

Als zulke transacties bestaan, start de initialisatie niet: RCM toont Soepel herinitialiseren wacht op lange transacties en geeft een koppeling Lijst openen.

Pagina Lange transacties: geen lange transacties
Pagina Lange transacties: geen lange transacties

Op de pagina Lange transacties:

  • samenvatting: hoeveel transacties en verbindingen, het oudste segment;
  • Top 5-verbindingen met de oudste transacties: gebruiker, client, start, leeftijd, wijzigingen, huidige query;
  • Segmenten vasthouden / Vasthouden opheffen — zolang het vasthouden aanstaat, wordt het archief van de master niet opgeschoond en wordt de geschiedenis niet afgekapt;
  • Selectie verbreken en reinit opnieuw proberen — verbreekt de verbindingen (hun transacties worden teruggedraaid) en start meteen een soepele reinit;
  • Reinit opnieuw proberen, Opnieuw controleren.

Het vasthouden wordt automatisch ingeschakeld als een reinit wordt geweigerd vanwege lange transacties. Het wordt opgeheven na een geslaagde initialisatie, handmatig, of wanneer het archief groeit tot reinit_hold_max_segments (standaard 1000 segmenten, melding retention_hold_released).

Standaard vergrendelt de database meteen, zonder controle. Gebruik het alleen als u weet dat er geen lange schrijftransacties zijn.

Eerste initialisatie onder belasting. Zolang het archief van de master leeg is, is er geen segment om mee te vergelijken.

Met een master-node HQbird 2027.2.24: als de node de publicatie zelf heeft ingeschakeld en het archief sindsdien niet is veranderd, begint de geschiedenis op het moment dat de publicatie werd ingeschakeld. Een transactie die later begon, komt vanaf zijn eerste wijziging in het journaal en stoort de soepele methode niet. Een transactie die eerder begon, kwam niet in het journaal: de reinit wacht erop vóór het vergrendelen (6 pogingen elke 10 s), en de stap locking toont zijn nummer, verbinding en gebruiker. Als hij niet klaar is, eindigt de reinit met de fout reinit_pre_publication_transactions: maak hem af en probeer opnieuw. De pagina Lange transacties toont zulke transacties in de tabel Transacties gestart voordat de publicatie werd ingeschakeld.

Als de publicatie handmatig is ingeschakeld, niet via de node, of het archief al is veranderd, is het begin van de geschiedenis onbekend. Dan weigert de soepele methode als er een schrijftransactie open is, en het bericht zegt dat het archief nog geen segment bevat. In dat geval opent RCM 2027.2.24 de lijst niet, maar schrijft wat te doen in de cel van de database. Kies Standaard of probeer opnieuw zodra Firebird het eerste segment archiveert.

Met een master-node 2027.5.7 weigert de soepele methode meteen bij de eerste initialisatie van een database waarnaar wordt geschreven: long_transactions … segment 0 (0001-01-01T00:00:00Z). Kies voor de eerste initialisatie van zo’n database Standaard.

Voor latere herinitialisaties werkt de soepele methode zoals gewoonlijk (het archief bestaat al).

Hetzelfde vanaf de opdrachtregel

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

Transacties ouder dan de publicatie. Firebird schrijft naar segmenten geen transactie die begon voordat de publicatie was ingeschakeld. Als de node de publicatie heeft ingeschakeld, wacht de initialisatie (6 pogingen elke 10 seconden) tot zulke transacties klaar zijn; anders eindigt hij met de fout reinit_pre_publication_transactions die ze opsomt. Nadat u een publicatie hebt gesynchroniseerd die tabellen toevoegde, verbindt u de toepassingen opnieuw en start u daarna de initialisatie.

5.5. Snelheid

Wanneer Snelheid Instelling
Binnen het overdrachtsvenster windows.transfer_window (standaard 23:00-05:00) constant limits.reinit_window_mbps, standaard 100 MB/s
Buiten het venster fractie van de gemeten schijfsnelheid limits.reinit_day_disk_fraction, standaard 0.5

De node herberekent de modus elke 30 seconden: een initialisatie die overdag is gestart, versnelt ’s nachts vanzelf.

De node meet de schijfsnelheid met een test. Om de test op de master-host te herhalen:

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

Initialisatietijd ≈ databasegrootte ÷ snelheid. Voorbeeld: 100 GB bij 100 MB/s — ongeveer 17 minuten zuivere overdracht; in de praktijk begrenzen het netwerk of de schijf dat.

5.6. De Firebird van de replica herstarten

Een nieuwe database op de replica. Het bestand wordt geplaatst zonder Firebird te stoppen. Firebird leest het nieuwe blok in replication.conf pas na een herstart. Tot dan past de replica niets toe. De stap RESTARTING REPLICA toont het wachten:

Label Wat het betekent
wachten op een herstart van Firebird op de replica, die is gepland om … de node herstart Firebird zelf na de laatste initialisatie (reinit_restart_delay_sec), zodra de andere initialisaties klaar zijn
… het herstartvenster is gesloten, het volgende opent om … wachten op de restart_window van de replica
… de laatste poging is mislukt, de volgende om … probeert later opnieuw
de replica kan Firebird niet zelf herstarten: herstart hem met de hand auto_restart: never, of deze Firebird bedient ook de databases van de master

De node herstart Firebird eenmaal na een reeks initialisaties, niet na elke database.

Om met de hand te herstarten, klikt u op Firebird van de replica herstarten. Het wachten eindigt na elke geslaagde herstart van Firebird of wanneer de replica een segment nieuwer dan de kopie heeft toegepast.

Herinitialisatie op een Firebird die ook de databases van de master bedient. De node stopt zo’n Firebird niet zelf en weigert met restart_not_allowed. Start de initialisatie opnieuw en vink Sta toe Firebird voor deze reinit te stoppen aan (-allow-restart op de opdrachtregel) — op een moment waarop de verbindingen van deze Firebird mogen worden verbroken, ook naar zijn masterdatabases. Voer zulke initialisaties één voor één per host uit.

De oude kopie verwijderen (het vakje Oude replica verwijderen, met HQbird 2027.2.24) stopt ook de Firebird van de replica, volgens dezelfde regels. Als de node deze Firebird niet zelf kan stoppen, verwijdert hij niets en weigert met restart_not_allowed: vink ook Sta toe Firebird voor deze reinit te stoppen aan. Als op dat moment een andere initialisatie op de replica afloopt of Firebird herstart, verwijdert de node niets en weigert met engine_busy: de master heft de vergrendeling op, probeer later opnieuw.

5.7. Wachtrij en gelijktijdige initialisaties

  • Eén database — één initialisatie tegelijk (ook voor verschillende replica’s). De knop Initialiseren is uitgeschakeld zolang een initialisatie van deze database loopt.
  • De master-node dwingt limits.max_concurrent_reinits gelijktijdige initialisaties van verschillende databases af (standaard 1). De rest wacht in de wachtrij; het antwoord bevat de plaats in de wachtrij.
  • Voer tijdens de initialisatie geen eigen nbackup -L (of ALTER DATABASE BEGIN BACKUP) uit op een database, en start geen initialisatie tijdens zo’n back-up: een database kan maar één vergrendeling hebben. De initialisatie controleert dit en weigert met nbackup backup lock already active.

De wachtrij en de lopende overdrachten zijn zichtbaar op de pagina Overdracht.

Pagina Overdracht / wachtrijen
Pagina Overdracht / wachtrijen
- Als na een fout een bestand `.delta` achterblijft, controleer dat er geen back-up loopt en voer `nbackup -N ` uit. Verwijder de `.delta` niet met de hand.

5.8. Automatische herinitialisatie

RCM kan een database in de toestand NEEDS_REINIT zelf herinitialiseren, alleen binnen een ingesteld venster. Standaard uitgeschakeld.

Wanneer een database in NEEDS_REINIT komt:

Oorzaak Waar het zichtbaar is
terugkerende onherstelbare toepassingsfout (schending van PK, UNIQUE, FK) — 3 keer achter elkaar replica, melding replication_unrecoverable_error
de GUID van de masterdatabase is veranderd (herstel, vervanging van het bestand) replica, melding replication_guid_mismatch
het archief van de master bevat de segmenten die de replica nodig heeft niet meer master
de replica heeft de oude kopie voor initialisatie verwijderd en er is nog geen nieuwe kopie (sinds HQbird 2027.2.24) replica, melding replica_removed_for_reinit; master

Om in te schakelen — Instellingen → RCM (of rcm.json, de sectie 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" } }
  }
}
  • Venster: per database → per node → globaal. "always" — op elk moment.
  • Vensters worden berekend op de klok van de RCM-host.
  • max_concurrent — hoeveel initialisaties (handmatig en automatisch) in het cluster mogen lopen voordat RCM een volgende automatische start.
  • Automatische initialisatie doorloopt dezelfde plaats- en GUID-controles als handmatige initialisatie. De auteur van de opdracht is system:autoreinit.
  • remove_old_replica_when_short (sinds HQbird 2027.2.24, de rij Oude replica verwijderen bij plaatsgebrek) — standaard uitgeschakeld. Als het is ingeschakeld, stuurt automatische initialisatie de vlag Oude replica verwijderen (4.4). RCM stuurt die alleen als de replica zelf in NEEDS_REINIT staat of de NEEDS_REINIT-oorzaak van de master haar noemt. Voor een replica die IN_SYNC of LAGGING is, wordt de vlag nooit gestuurd. Als de node een oudere versie is, start RCM dezelfde initialisatie zonder de vlag.
  • Na een wijziging herstart u RCM.

Uitstellen in de kaart van de master schakelt automatische initialisatie van één database uit voor 1 uur, 4 uur, 24 uur of tot u het annuleert. Handmatige initialisatie blijft beschikbaar.

5.9. Fouten

Fout Oorzaak Wat te doen
insufficient disk space on master / on replica, 507 te weinig plaats. Tijdens herinitialisatie neemt de oude kopie plaats in tot het einde hoofdstuk 4.4; op de replica (vanaf HQbird 2027.2.24) — het vakje Oude replica verwijderen (5.1)
node_too_old (vanaf HQbird 2027.2.24) het vakje Oude replica verwijderen is aangevinkt, maar de master- of replica-node is een oude versie werk de node bij zoals de fouttekst zegt, of voer uit zonder het vakje
engine_busy, reclaim_in_progress (vanaf HQbird 2027.2.24) de replica kan de oude kopie nu niet verwijderen: Firebird of deze database is bezet probeer later opnieuw (5.6)
replica_removed_for_reinit, paar NEEDS_REINIT (vanaf HQbird 2027.2.24) de replica heeft de oude kopie verwijderd, maar de initialisatie is niet afgerond start de initialisatie opnieuw (4.4)
publication_off (vanaf HQbird 2027.2.24) de publicatie van de master is uitgeschakeld of bevat geen tabellen met een sleutel Publicatie synchroniseren en initialiseren (5.1)
long_transactions, „Soepel reinit wacht op lange transacties” er zijn lange schrijftransacties open 5.4
long_transactions, „het archief van de master bevat nog geen enkel segment” eerste initialisatie onder belasting Standaard (5.4)
reinit_pre_publication_transactions transacties die begonnen voordat de publicatie was ingeschakeld verbind de toepassingen opnieuw, probeer opnieuw
duplicate_guid twee masterdatabases met dezelfde GUID verwijder de kopie; als de stap NEW GUID is overgeslagen bij promoveren tot master — -force (hoofdstuk 8.4)
license_paused de fbagent van de master heeft geen licentie hoofdstuk 2.8
409 orphaned de database valt buiten de scan van de master hoofdstuk 3.8
incompatible_engine verschillende hoofdversies van Firebird hoofdstuk 4.3
target_not_replica er staat een werkende database op de plaats van de replica (die is normaal gemaakt) zie hieronder
target_other_replica (vanaf HQbird 2027.2.24) er staat een kopie van een andere database van deze node op de plaats van de replica zie hieronder
restart_not_allowed de Firebird van de replica bedient ook masterdatabases 5.6, het vakje „Sta … toe Firebird te stoppen”
fbagent_required fbagent is niet geïnstalleerd op de replica hoofdstuk 1
nbackup backup lock already active er loopt een nbackup-back-up 5.7
… -L did not finish in 2m0s and was stopped nbackup -L op de master was niet binnen 2 minuten klaar, dus de node heeft hem gestopt probeer opnieuw; als de fout terugkomt, controleer de Firebird van de master (firebird.log)
reinit already in progress for this database de initialisatie van deze database loopt al wacht tot die klaar is

target_not_replica. Er staat een werkende database op de plaats van de kopie: die is normaal gemaakt (het bestand <database>.hqcluster-normal.json bestaat) of hij staat niet in replicamodus. De node overschrijft geen werkende database. Als hij vervangen moet worden, vervangt een verzoek aan de API van de node met overwrite_non_replica: true (hiervoor is geen knop in RCM) het bestand en bewaart het oude als <database>.pre-reinit-<UTC-tijd>.fdb.

target_other_replica (vanaf HQbird 2027.2.24). De replica plaatst de kopie in <databases.root>/<master-id>/<databasepad>. De master-id is alleen uniek binnen zijn eigen cluster, dus twee databases kunnen op hetzelfde pad uitkomen. De replica-node overschrijft geen kopie die bij een andere van zijn databases hoort: de fout noemt die database en zijn master. De node herkent ook een kopie waarvan het pad anders is vastgelegd (een symbolische koppeling of junction in het pad, een korte Windows-mapnaam). overwrite_non_replica heft deze fout niet op. Verplaats een van de kopieën naar een andere map of verwijder die database van de replica, en start daarna de initialisatie opnieuw. De node ziet alleen zijn eigen databases: twee replica-nodes op dezelfde host moeten verschillende replicamappen hebben (databases.root).

5.10. Het resultaat controleren

  1. Databases: het paar master — replica in de groep is Ok, toestand IN_SYNC.

  2. Controleren in de kaart van de master: de nodes tellen de rijen van de tabellen uit de tabellenlijst van de database (hoofdstuk 3.1) op de master en op de replica en vergelijken ze. Controleer in een rustige periode: bij actieve schrijfacties kunnen de aantallen verschillen.

    Met HQbird 2027.2.24 noemt de resultaatpagina de lijst van elke kant (bijvoorbeeld „de eigen lijst van deze database” of „publicatietabellen (lijst niet ingesteld)”). RCM telt de replica met de lijst van de master. Een tabel die in beide databases ontbreekt, wordt getoond als „niet in de database” en telt niet als fout. Als er geen tabellen zijn vergeleken, is het resultaat „Geen tabellen om te vergelijken”, geen afwijking. Als de vergelijking niet binnen de beschikbare tijd klaar was, is het resultaat „Niet vergeleken (tijdslimiet)”, ook dat is geen afwijking.

Resultaat van de controle
Resultaat van de controle
Command
hqbirdrcm verifydata -master node-a -master-db <db_id> -replica node-b -replica-db <db_id>
  1. Periodieke controle (optioneel): de pagina Gegevenscontrole, Inschakelen voor alle nodes. Met HQbird 2027.2.24 past de node de instellingen meteen toe, een herstart van de nodeservice is niet nodig: na Opslaan schrijft RCM „Opgeslagen en al van kracht”. Node 2027.5.7 heeft een herstart van de service hqclusternode nodig, en RCM 2027.2.24 zegt dat. De nodes vergelijken de rijaantallen zelf wanneer de master en de replica op hetzelfde segment zitten. Een afwijking geeft de melding data_mismatch; voer daarna Controleren uit.

Een tabel die de beheerder uit de publicatie heeft verwijderd, wordt getoond als „niet gepubliceerd”, niet als een afwijking.

6. Publicatie configureren

De publicatie zegt de Firebird-master van welke tabellen hij wijzigingen naar de segmenten schrijft. Zonder publicatie ontvangt de replica niets.

6.1. Wat de publicatie is

In Firebird 4 en 5 worden de te repliceren tabellen bepaald door de publicatie RDB$DEFAULT:

  • Publicatie ingeschakeld — in RDB$PUBLICATIONS heeft die RDB$ACTIVE_FLAG = 1 (de opdracht ALTER DATABASE ENABLE PUBLICATION).
  • Gepubliceerde tabellen — de lijst in RDB$PUBLICATION_TABLES.

Firebird schrijft alleen wijzigingen naar de segmenten voor gepubliceerde tabellen en alleen wanneer de publicatie is ingeschakeld. De database registreren (hoofdstuk 3) schakelt de publicatie niet in. Dat doet Publicatie synchroniseren (6.2).

De master-node controleert de publicatie elk uur (limits.publication_check_interval_sec, standaard 3600). Als die is uitgeschakeld, controleert de node elke 2 minuten.

Op de pagina Databases heeft de masterdatabase een pictogram:

Pictogram Betekenis
publicatie AAN publicatie ingeschakeld
publicatie UIT Firebird schrijft niets naar de segmenten, replica’s ontvangen geen wijzigingen
publicatie onbekend de node kon de toestand niet lezen

Het filter Publicatie uit toont databases met een uitgeschakelde of onbekende publicatie.

Als een database met een uitgeschakelde publicatie al een replica heeft, geeft de master de melding master_publication_off.

Met HQbird 2027.2.24 geeft de master deze melding ook wanneer hij weigerde een database te initialiseren met de fout publication_off (hoofdstuk 5.1): de publicatie is uitgeschakeld of bevat geen tabel met een sleutel. Het meldingsniveau:

  • waarschuwing — de database heeft nog geen replica: de initialisatie wacht op de publicatie;
  • ernstig — de database heeft al een replica;
  • info — de beheerder heeft de publicatie uitgeschakeld.

De melding verdwijnt wanneer de publicatie is hersteld of een andere initialisatie is gestart.

6.2. Publicatie synchroniseren

Rij van de master: publicatie uitgeschakeld
Rij van de master: publicatie uitgeschakeld

Waar u klikt:

  • in de rij van de masterdatabase op de pagina Databases. Wanneer de publicatie is uitgeschakeld, staat de knop naast het pictogram;
  • op de databasepagina;
  • voor meerdere databases: vink de rijen aan, kies in de lijst Actie Publicatie synchroniseren. RCM stuurt een aparte opdracht voor elke database.
Bevestiging van publicatiesynchronisatie
Bevestiging van publicatiesynchronisatie

Wat de node doet (één transactie):

  1. Schakelt de publicatie in. Als de beheerder die zelf heeft uitgeschakeld (6.4), schakelt hij die niet in.
  2. Voegt aan de publicatie alle tabellen met een sleutel toe die er nog niet in staan.
  3. Haalt uit de publicatie tabellen zonder sleutel en tabellen die de beheerder heeft uitgesloten (6.3).
  4. Schakelt het automatisch toevoegen van nieuwe tabellen uit (EXCLUDE ALL FROM PUBLICATION, daarna voegt hij de vereiste tabellen toe). Alleen de node bepaalt de samenstelling van de publicatie.
Rij van de master na synchronisatie: publicatie ingeschakeld
Rij van de master na synchronisatie: publicatie ingeschakeld

Een tabel met een sleutel — een permanente gebruikerstabel die een primaire sleutel of een actieve unieke index heeft. Systeem- en tijdelijke tabellen worden niet gepubliceerd.

Synchronisatie haalt ook tabellen zonder sleutel uit de publicatie die de DBA met de hand heeft toegevoegd.

Als de samenstelling al klopt, wijzigt de node niets.

Wanneer de node weigert:

Code Reden
no_publications HQbird 2.5/3.0 (6.6)
not_master de node is niet de master
reinit_in_progress de initialisatie van deze database loopt
orphaned, database_failed, file_missing de database valt buiten de scan, heeft een fout, of heeft geen bestand

Alle databases van de node tegelijk — alleen vanaf de opdrachtregel. Op de pagina Opdrachten wordt het resultaat per database getoond: gereed, overgeslagen of fout. Databases in de toestand FAILED of SEEDING en databases zonder bestand worden overgeslagen.

Hetzelfde vanaf de opdrachtregel

Command
hqbirdrcm setpublication -node node-a -db <db_id>   # one database
hqbirdrcm setpublication -node node-a               # all node databases

De opdracht wacht tot 5 minuten en drukt een regel af voor elke database. Bij een fout is de afsluitcode

  1. -nowait — niet op het resultaat wachten.

6.3. Publicatietabellen

De pagina „Publicatietabellen”
De pagina „Publicatietabellen”

Open Publicatietabellen in de rij van de masterdatabase.

De pagina toont:

  • de toestand van de publicatie (aan/uit, uitgeschakeld door de beheerder) en de tellers;
  • elke tabel: naam, sleutel en toestand.
Toestand Betekenis
gepubliceerd wijzigingen gaan naar de segmenten
nog niet gepubliceerd een tabel met een sleutel, wordt bij synchronisatie toegevoegd
uitgesloten de beheerder heeft hem uit de publicatie gehaald
geen sleutel kan niet worden gepubliceerd

In de sleutelkolom — de primaire sleutel, of, als die er niet is, de unieke index met het kleinste aantal velden.

Waarom een tabel zonder sleutel niet kan worden gepubliceerd. De replica zoekt de rij voor UPDATE en DELETE op sleutel. Zonder sleutel vindt hij de rij niet. Voeg een primaire sleutel of een unieke index toe en synchroniseer daarna de publicatie.

Uitsluiten van publicatie / Terugzetten in publicatie:

  1. Vink de tabellen aan.
  2. Klik op Uitsluiten van publicatie of Terugzetten in publicatie.
  3. De node bewaart de lijst en synchroniseert de publicatie meteen.
Bevestiging van „Uitsluiten van publicatie”
Bevestiging van „Uitsluiten van publicatie”

De lijst van uitgesloten tabellen staat op de master-node. Synchronisatie wijzigt die niet. Wanneer een replica tot master wordt gepromoveerd (hoofdstuk 8), verhuist de lijst naar de nieuwe master.

Controleren (hoofdstuk 5.10) toont een uitgesloten tabel als „niet gepubliceerd”, niet als een afwijking.

6.4. De publicatie in- en uitschakelen

Op de pagina Publicatietabellen: Publicatie uitschakelen / Publicatie inschakelen.

  • Uitschakelen is de keuze van de beheerder. Synchronisatie schakelt de publicatie niet opnieuw in.
  • Wijzigingen die zijn gemaakt terwijl de publicatie was uitgeschakeld (of terwijl een tabel was uitgesloten) worden niet verstuurd naar de replica, ook niet nadat die weer is ingeschakeld.
  • Klik na het inschakelen op Controleren (hoofdstuk 5.10). Als de gegevens uiteenlopen — herinitialiseer de replica (hoofdstuk 5).

6.5. Een nieuwe tabel

Een nieuwe tabel komt niet vanzelf in de publicatie: de node schakelt automatisch toevoegen uit.

Na DDL:

  1. Maak een primaire sleutel of een unieke index op de tabel.
  2. Klik op Publicatie synchroniseren.
  3. Vraag de toepassingen opnieuw te verbinden als herinitialisatie nodig is. Firebird schrijft naar de segmenten geen transacties die begonnen voordat de publicatie was ingeschakeld; COMMIT RETAINING houdt zo’n transactie open. De initialisatie wacht op zulke transacties en faalt daarna met reinit_pre_publication_transactions (hoofdstuk 5.4).
Een nieuwe tabel in de toestand „nog niet gepubliceerd”
Een nieuwe tabel in de toestand „nog niet gepubliceerd”

Rijen die vóór de synchronisatie naar de nieuwe tabel zijn geschreven, bereiken de replica niet. Als die er zijn, controleer de gegevens en herinitialiseer zo nodig de replica.

6.6. HQbird 2.5 en 3.0

HQbird 2.5 en 3.0 hebben geen publicaties. Firebird schrijft segmenten als het plug-inbestand replconf een masterblok bevat. De publicatieknoppen op zulke nodes zijn verborgen, en de API antwoordt met no_publications.

De set tabellen wordt bepaald door de engineparameters:

Parameter Betekenis
include_filter welke tabellen te repliceren: namen of patronen, gescheiden door komma’s; leeg — alle
exclude_filter welke tabellen niet te repliceren

De parameters wijzigt u in Instellingen → Replicatieparameters (hoofdstuk 7.1). De pagina Publicatietabellen toont ze alleen-lezen, met een koppeling Wijzigen in engine-instellingen. Firebird leest de nieuwe waarden na een herstart.

Publicatietabellen op HQbird 3.0: enginefilters
Publicatietabellen op HQbird 3.0: enginefilters

De plug-in replconf. De node schrijft zijn eigen bestand replconf.hqcluster.hqbird in de Firebird-map. Firebird leest het alleen wanneer replconf.properties ernaar wijst. De plug-in moet eenmaal worden geactiveerd:

  1. Instellingen → Knooppunten, het blok Replicatieplug-in (HQbird 2.5 / 3.0). Het blok toont waar replconf.properties naar wijst en de problemen die de node heeft gevonden.

Plug-in niet geactiveerd: replconf.properties wijst naar het HQbird DataGuard-bestand
Plug-in niet geactiveerd: replconf.properties wijst naar het HQbird DataGuard-bestand
  1. Activeren… Het venster somt op wat de node zal doen: de plug-in installeren, replconf.properties naar het bestand van de node laten wijzen, de vermeldingen van het oude bestand migreren. Kies wanneer: Alleen binnen het herstartvenster van de node of Nu, het herstartvenster negeren.

Venster voor activering van de plug-in
Venster voor activering van de plug-in
  1. Na de herstart van Firebird toont het veld Geactiveerd „ja: de engine leest het bestand van de node”.

Plug-in geactiveerd
Plug-in geactiveerd

Activering herstart Firebird en raakt alle databases van deze Firebird. Doe dit in een rustige periode.

7. Overige replicatieopties

7.1. Replicatieparameters

Instellingen → Replicatieparameters, wizardformulier
Instellingen → Replicatieparameters, wizardformulier

De pagina Instellingen → Replicatieparameters wijzigt de sleutels in replication.conf voor de geselecteerde databases of voor de node als geheel.

  1. Master en replica’s toevoegen — selecteer de databases. RCM groepeert ze op Firebird-versie en rol: een apart formulier voor masters en voor replica’s.

  2. Kies voor elke parameter een actie:

    Actie Wat die doet
    geen wijzigingen de waarde wordt niet gewijzigd
    waarde instellen een nieuwe waarde
    terugzetten (naar het volgende niveau) de eigen waarde verwijderen, de waarde van het niveau erboven nemen
    niet schrijven (Firebird-waarde) de sleutel wordt niet geschreven, de Firebird-waarde geldt
  3. Kies waar u het toepast: Op de geselecteerde databases of Als standaard voor hun nodes.

  4. Voorbeeld — de nodes controleren de waarden zonder iets te wijzigen.

Voorbeeld van de wijzigingen
Voorbeeld van de wijzigingen
  1. Toepassen. RCM stuurt de opdracht naar elke node.

Waar de waarde vandaan komt (de kolom Huidig):

Bron Waarde
deze database ingesteld voor de database
nodewaarde ingesteld als standaard voor de node
ingebouwde nodewaarde de nodewaarde uit de code
Firebird-waarde de sleutel is niet geschreven
uit bestand (hier nog niet ingesteld) de waarde uit replication.conf, RCM heeft die nog niet gewijzigd
ingesteld door de node alleen-lezen (paden, voorvoegsels)

Een node die niet antwoordt, toont zijn databases als niet beschikbaar voor selectie. Wijzigingen vereisen fbagent (anders fbagent_required).

Wie Firebird herstart (Firebird leest replication.conf alleen bij het opstarten):

Node Wie
master u herstart hem: de master herstart Firebird nooit zelf
replica met firebird.auto_restart: never u
replica waarvan de Firebird ook de databases van de master bedient u
andere replica’s de node herstart hem in zijn eigen herstartvenster

Voor een handmatige herstart heeft de pagina een knop Firebird herstarten.

7.2. Belangrijkste parameters

Master, Firebird 4/5:

Parameter Label in RCM Nodewaarde Firebird Tip
journal_archive_timeout Archieftime-out 10 s 60 s hoeveel seconden Firebird wacht voordat hij een onvolledig segment sluit. Lager — de replica ligt dichter bij de master. Moet kleiner zijn dan limits.data_check_quiet_sec (90)
journal_segment_count Aantal segmenten 64 8 hoeveel segmenten in .ReplLog mogen staan. Moet groter zijn dan limits.backlog_critical (48)
journal_segment_size Segmentgrootte — 16 MB van 1 MB tot 512 MB; de ontvanger accepteert niet meer dan 512 MB
buffer_size — 1 MB

De node schrijft ook log_errors = true (kan niet worden gewijzigd) en disable_on_error = true.

Replica, Firebird 4/5:

Parameter Label in RCM Firebird Waarde
apply_idle_timeout Rustpauze 10 s pauze wanneer er geen nieuwe segmenten zijn
apply_error_timeout Pauze na toepassingsfout 60 s pauze vóór een nieuwe poging na een fout
verbose_logging node: true uitgebreide replication.log; uitschakelen wordt niet aanbevolen
skip_upddel_without_pk node: true UPDATE/DELETE overslaan op tabellen zonder sleutel

Alleen Firebird 5: include_filter, exclude_filter, cascade_replication.

HQbird 2.5/3.0 — sleutels log_* met dezelfde betekenis: log_archive_timeout, log_segment_count, log_segment_size (niet kleiner dan 2 × buffer_size). De sleutel alert_command wordt alleen in node.json gezet.

Een tip bij elke parameter staat in het RCM-formulier.

7.3. Archiefopslag

Het archief <database>.LogArch op de master wordt in stappen opgeschoond:

  1. Segmenten die door alle replica’s zijn toegepast en ouder zijn dan retention_days.
  2. Als de vrije ruimte kleiner is dan free_space_floor_gb — toegepaste segmenten jonger dan de bewaartermijn. Melding disk_serious_cleanup.
  3. Als er nog te weinig ruimte is — niet-toegepaste segmenten, te beginnen bij de oudste. De replica krijgt NEEDS_REINIT, melding replication_paused_reinit_scheduled.
Parameter (Instellingen → Knooppunten, Opslag en bestanden) Standaard
limits.retention_days — Bewaartermijn archief, dagen 2
limits.retention_min_kept_segments — Altijd de laatste segmenten bewaren 0 (uitgeschakeld)
limits.free_space_floor_gb — Minimale vrije ruimte 1 GB
Instellingen → Knooppunten, „Opslag en bestanden”
Instellingen → Knooppunten, „Opslag en bestanden”

Het archief met de hand opschonen:

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 (alleen samen met -db) verwijdert alle segmenten van de database in de toestand ORPHANED (hoofdstuk 3.8). Voor elke andere database antwoordt de node not_orphaned. Voer nooit -orphaned uit op de donor van een promotie (hoofdstuk 8.5).

7.4. Overdracht: compressie, snelheid, vensters

Compressie wordt per partner ingesteld: Instellingen → Knooppunten → Partners, kolom compress.

Waarde Betekenis
leeg of none geen compressie (standaard)
zstd zstd-compressie

De wijziging geldt meteen. Compressie is nuttig op een traag netwerk.

Snelheid van segmentoverdracht (Instellingen → Knooppunten, Overdracht en herinitialisatie):

Parameter Standaard Wanneer het geldt
limits.channel_a_mbps — Snelheid van segmentoverdracht 50 MB/s onmiddellijk
limits.channel_a_burst_mbps — Burst van segmentoverdracht 200 MB onmiddellijk

De eenheid is mebibyte (MiB), ook al zegt de naam „mbps”. De burst kan niet kleiner zijn dan de snelheid.

Instellingen → Knooppunten, „Overdracht en herinitialisatie”
Instellingen → Knooppunten, „Overdracht en herinitialisatie”

Tijdvensters (Tijdvensters):

Parameter Standaard Wanneer het geldt Wat het beïnvloedt
windows.restart_window — Herstartvenster van Firebird master 22:00-05:00, replica always onmiddellijk wanneer de replica-node Firebird mag herstarten
windows.transfer_window — Overdrachtsvenster 23:00-05:00 na herstart van de node snelheid van volledige initialisatie (hoofdstuk 5.5)

Het label naast elk veld toont wanneer de wijziging geldt: onmiddellijk of herstart van de node.

Instellingen → Knooppunten, „Tijdvensters”
Instellingen → Knooppunten, „Tijdvensters”

7.5. Gegevenscontrole

  • Controleren — een eenmalige vergelijking van het aantal rijen op de master en de replica (hoofdstuk 5.10).
  • Gegevenscontrole — een periodieke vergelijking (hoofdstuk 5.10). De node voert de vergelijking uit wanneer de master en de replica op hetzelfde segment zitten.
  • Met HQbird 2027.2.24 gelden de controle-instellingen meteen na Opslaan; de nodeservice herstarten is niet nodig. RCM toont „Opgeslagen en al van kracht”. Na inschakelen loopt de eerste controle na één interval. Na uitschakelen wordt een lopende controle afgebroken en schrijft die niets. Het nieuwe interval wordt geteld vanaf het einde van de laatste controle. Bewaren, dagen, Querylimiet, Rust en Voortgangsgenerator gelden vanaf de volgende controle.
  • Node 2027.5.7 leest deze instellingen alleen bij het opstarten: herstart na Opslaan de service hqclusternode op die node. RCM 2027.2.24 toont „Opgeslagen, maar nog niet van kracht” en noemt de reden.
  • Welke tabellen worden vergeleken, bepaalt de tabellenlijst van de database (hoofdstuk 3.1). Met HQbird 2027.2.24 kan elke database een eigen lijst hebben: het veld bij registratie of het blok Synchronisatietabellen op de databasepagina van de master (hoofdstuk 3.3). De pagina Gegevenscontrole toont welke lijst is gebruikt, en het aantal tabellen „niet in de database”. In 2027.5.7 is de lijst per node (sync_tables).
  • Tabellen die uit de publicatie zijn uitgesloten, worden getoond als „niet gepubliceerd” (hoofdstuk 6.3).
Pagina Gegevenscontrole
Pagina Gegevenscontrole

7.6. Meldingen

Pagina Meldingen
Pagina Meldingen

De pagina Meldingen. Acties:

  • Bevestigen — de melding blijft zichtbaar maar is gemarkeerd als bevestigd;
  • Dempen voor 60 min — een uur verbergen;
  • Verwijderen / Alles met deze code verwijderen — RCM geeft de verwijdering door aan de node die de melding heeft gegeven. Als de oorzaak blijft, verschijnt de melding opnieuw.
Command
hqbirdrcm clearalerts -code backlog_warn   # also -id, -acked, -all

Vanaf HQbird 2027.2.33 stuurt RCM meldingen naar Telegram, naar een webhook (Slack, Teams, JSON) en per e-mail. De kanalen worden ingesteld in de sectie notify.channels van het bestand rcm.json. Het blok Meldingskanalen op de pagina Meldingen toont de kanalen en stuurt een testbericht. RCM meldt problemen van niveau warn en hoger: een probleem is verschenen, is ernstiger geworden, of is opgelost. Zonder kanalen stuurt RCM niets. Eerdere versies versturen niets: houd de pagina Meldingen in de gaten of bevraag de RCM-API.

Belangrijkste codes:

Code Betekenis
backlog_warn / backlog_critical 32 / 48 niet-gearchiveerde segmenten in .ReplLog
disk_serious_cleanup het archief wordt opgeschoond in stap 2 (7.3)
replication_paused_reinit_scheduled niet-toegepaste segmenten verwijderd, initialisatie vereist
shipping_paused verzending naar de partner is opgeschort (7.7)
apply_error, replication_stopped, replication_unrecoverable_error de replica kan een segment niet toepassen
replication_guid_mismatch de GUID van de masterdatabase is veranderd
segment_missing, segment_rejected, sequence_gap problemen met de segmentvolgorde
firebird_down, firebird_log_error Firebird draait niet of schrijft fouten in het log
firebird_not_answering vanaf HQbird 2027.2.30: Firebird heeft een minuut niet geantwoord op een databaseverbinding (vastloper). Dit omvat ook een verbinding die door een time-out niet tot stand kwam; firebird_down is alleen een verbindingsweigering
master_publication_off publicatie is uit (hoofdstuk 6); vanaf HQbird 2027.2.24 en na een fout publication_off (hoofdstuk 6.1)
replica_removed_for_reinit vanaf HQbird 2027.2.24: de replica heeft de oude kopie voor initialisatie verwijderd, en er is nog geen nieuwe kopie (hoofdstuk 4.4)
orphaned_database database buiten de scan (hoofdstuk 3.8)
restart_required_after_reinit de Firebird van de replica moet worden herstart (hoofdstuk 5.6)
data_mismatch de periodieke controle vond een afwijking
license_paused fbagent heeft geen licentie (hoofdstuk 2.8)

7.7. Verzending pauzeren

Op de pagina Databases, in de rij van de master: Verzending pauzeren / Verzending hervatten. Voor meerdere databases — via de lijst Actie.

Command
hqbirdrcm pauseshipping  -node node-a -db <db_id>
hqbirdrcm resumeshipping -node node-a -db <db_id>
Bevestiging van verzending pauzeren
Bevestiging van verzending pauzeren
Rij van de master tijdens een pauze
Rij van de master tijdens een pauze
  • De pauze blijft gelden tot Verzending hervatten of tot een initialisatie.
  • De Firebird van de master blijft segmenten schrijven. Het archief .LogArch groeit: zolang de replica is gestopt, verwijdert stap 1 (7.3) zijn segmenten niet.
  • Een lange pauze kan stap 3 en NEEDS_REINIT bereiken. Houd de plaats in de gaten.
  • De knop ontbreekt als de database geen replica heeft of de publicatie is uitgeschakeld. Het pictogram Pauze: geen licentie betekent een pauze door de licentie (hoofdstuk 2.8); die verdwijnt alleen door een licentie.

7.8. Logboeken

Log Waar
Node <installatiemap>/logs/node-YYYYMMDD.jsonl (/opt/hqclusternode of C:\hqclusternode), elk 32 MB, 20 bestanden
Firebird replication.log, firebird.log paden in node.json: firebird.replication_log, firebird.firebird_log
RCM Linux: journalctl -u hqbirdrcm
RCM-audit rcm-data/audit.jsonl

Log van een node op afstand — de pagina Logboeken: kies een node en een bron (replication.log, firebird.log, node-agent).

Pagina Logboeken
Pagina Logboeken
Command
hqbirdrcm getlogs -node node-b -source replication -tail 200

8. Hoe u een replica omzet in een gewone database

Er zijn twee paden:

Pad Wanneer Wat u krijgt
Normaal maken, 8.1 u hebt een aparte werkkopie nodig: rapporten, tests, een storing zonder nieuwe master een gewone database buiten de replicatie
Promoveren tot master, 8.3 de replica moet de nieuwe master worden een database die wordt beheerd door een companion-node met de rol master

Geen van beide paden kan via de interface ongedaan worden gemaakt.

8.1. Normaal maken

Lijst „Actie” van de replica: het item „Normaal maken”
Lijst „Actie” van de replica: het item „Normaal maken”
  1. Databases, kant van de replica: vink de replicarijen aan.

  2. Kies in de lijst Actie Normaal maken en bevestig. Er is geen aparte knop in de rij. Er is ook geen opdrachtregelopdracht.

Bevestiging van „Normaal maken”
Bevestiging van „Normaal maken”
3. De replica-node: - voert `gfix -replica none` uit (HQbird 2.5/3.0: `gfix -replica {}`). Als de database bezig is segmenten toe te passen, zet de node hem enkele seconden in `single`-afsluiting (`gfix -shut single -force 0`), wist de replicamodus en brengt hem terug met `gfix -online normal`. **Alle verbindingen met deze database worden verbroken**; - schrijft het markerbestand `.hqcluster-normal.json` (tijd, auteur, db_id, GUID); - begint de wachtrij `.Incoming` te legen (8.2). 4. RCM toont de database in de groep **Geen replica (normaal)**.
De pagina „Databases” na „Normaal maken”
De pagina „Databases” na „Normaal maken”

Daarna staat de database open voor schrijven.

Haal het replicablok uit replication.conf. De node verwijdert het bij de volgende scan, en Firebird leest het bestand bij het opstarten:

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

Tot dan worden fouten „database staat niet in replicamodus” voor deze database niet als meldingen gegeven.

Het markerbestand beschermt de database. Initialisatie overschrijft zo’n database niet: die wordt geweigerd met target_not_replica (hoofdstuk 5.9). Alleen de marker verwijderen is niet genoeg: de node controleert ook de replicamodus in de header van de database. Het vakje Oude replica verwijderen (hoofdstuk 4.4) verwijdert zo’n database ook niet.

Met HQbird 2027.2.24, terwijl de replica de oude kopie van deze database voor initialisatie verwijdert, wordt Normaal maken geweigerd met reclaim_in_progress: probeer later opnieuw.

Als de database weer een replica moet worden — alleen een nieuwe initialisatie met overschrijven volstaat. Dat gaat via de API van de node (overwrite_non_replica: true); zo’n knop is er niet in RCM. Het oude bestand wordt bewaard als <database>.pre-reinit-<UTC-tijd>.fdb, en de marker wordt verwijderd.

8.2. Wat er met segmenten gebeurt

  • Tot de node de databases heeft gescand, blijft de master segmenten sturen. Elke 30 seconden verwijdert de replica-node oude segmenten en bewaart alleen de laatste 100 (keep_segments).
  • Na de scan krijgt het databaserecord op de replica de toestand ORPHANED. De replica-node antwoordt de master met unknown_database. De master stopt met segmenten naar deze replica te sturen, stopt met een archief voor hem bij te houden, en controleert hem elke 10 minuten opnieuw.
  • Andere replica’s van deze database worden niet geraakt.
  • Het record ORPHANED kan worden verwijderd (hoofdstuk 3.8): hqbirdrcm forgetdatabase. Het databasebestand zelf wordt niet verwijderd.

8.3. Promoveren tot master

De replica wordt de nieuwe master. Zijn bestand blijft op zijn plaats, en de besturing gaat naar de companion-node.

Voorwaarden:

Voorwaarde Weigering
de database is een replica bad_request
er draait een node met de rol master — de companion — op dezelfde host (hetzelfde label host in rcm.json, hoofdstuk 2.1) no_companion
de promotie van deze database loopt nog niet already_running
er loopt geen initialisatie naar deze database of vanaf zijn master reinit_running

RCM maakt de companion-node niet aan: installeer die vooraf (hoofdstuk 1).

Hoe u start:

  • in de rij van de replica, Promoveren tot master, of in de lijst Actie;

  • vanaf de opdrachtregel:

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

RCM vraagt om bevestiging en noemt de companion-node.

Bevestiging „Promoveren tot master?”
Bevestiging „Promoveren tot master?”

Stappen (zichtbaar in de rij van de replica, namen in het Engels):

Nr. Stap Wat die doet
1 TURN TO NORMAL zoals in 8.1; overgeslagen als de database al normaal is
2 NEW GUID een nieuwe database-GUID ter plaatse (8.4)
3 EXCLUDE ON DONOR de replica-node (donor) sluit het bestand uit van zijn scan (exclude_paths)
4 ENROLL ON de companion-node registreert het bestand als masterdatabase
5 PUBLICATION SYNC synchronisatie van de publicatie; de lijst van uitgesloten tabellen komt mee van de oude master (hoofdstuk 6.3)
6 RESTART DONOR FIREBIRD herstart van de Firebird van de donor, zonder op een venster te wachten
7 RESTART FIREBIRD herstart van de Firebird van de companion, zonder op een venster te wachten
8 FINALIZE de rij van de donor wordt Spookreplica; de oude master kan Master gedegradeerd worden (8.5)
Promotiestappen in de rij van de replica
Promotiestappen in de rij van de replica

Op HQbird 2.5 en 3.0 zijn er geen publicaties: de stap PUBLICATION SYNC eindigt met de tekst „deze engine heeft geen publicatie”.

Promotiestappen op HQbird 3.0 (Windows)
Promotiestappen op HQbird 3.0 (Windows)

Als de donor en de companion dezelfde Firebird gebruiken, wordt die Firebird herstart: verbindingen met alle databases ervan worden verbroken.

Als een stap mislukt, krijgt de taak failed met de fouttekst. Herstel de oorzaak en klik opnieuw op Promoveren tot master: voltooide stappen worden niet herhaald. Als RCM tijdens de promotie herstart, wordt de taak ook failed — controleer de toestand van de nodes en probeer opnieuw.

Licentie. Als fbagent op de host van de master geen licentie heeft, heeft de master het verzenden gepauzeerd. Promotie is nog steeds mogelijk. RCM waarschuwt u: wijzigingen die na het begin van de pauze zijn gemaakt, gaan verloren.

8.4. Nieuwe GUID

Na de promotie moet de database een eigen GUID krijgen. Anders schrijft de nieuwe master segmenten onder de GUID van de oude master, en worden zijn replica’s geweigerd met duplicate_guid.

De stap NEW GUID op de node:

  1. gfix -shut single -force 0 — alle verbindingen met de database worden beëindigd;
  2. nbackup -L, daarna nbackup -F zonder -SEQUENCE;
  3. verwijdert <database>.delta;
  4. controleert de header: nieuwe GUID, REPLICATION_SEQUENCE = 0;
  5. gfix -online normal.

Firebird wordt niet herstart. De methode werkt op alle versies (2.5, 3.0, 4.0, 5.0).

Als de stap is onderbroken, geeft de node de melding newguid_interrupted. De database kan in single-afsluiting blijven. Herhaal Promoveren tot master: de stap gaat verder.

De stap wordt overgeslagen (de tekst begint met skipped:) als de donor-node een oude versie is of het bestand al een eigen GUID heeft.

Na een nieuwe GUID is de oude nbackup-keten niet meer geschikt. Maak een nieuwe nbackup-kopie van niveau 0.

Als de database is gemaakt met ADD DIFFERENCE FILE, staat zijn .delta op een andere plaats: verwijder die met de hand.

8.5. Na de promotie

Donorrecord. Op de replica-node blijft de database ORPHANED, het pad blijft in exclude_paths, en de map .Incoming en het label blijven. In RCM is dit de rij Spookreplica met de knoppen Openen op nieuwe master en Wissen.

Rij van de donor: „Spookreplica”
Rij van de donor: „Spookreplica”
  • Om de rij te verwijderen, klikt u op Wissen. Dit wijzigt alleen RCM.
  • Om het donorrecord van de replica-node te verwijderen, voert u forgetdatabase uit. Het bestand en de map .Incoming blijven. HQbird 2027.2.30 en nieuwer wijst de opdracht niet af (mailbox_active), omdat het donorpad in exclude_paths staat. Nodes van eerdere versies wijzen hem af zolang het bestand en de map .Incoming aanwezig zijn.
  • Voer nooit cleanuparchive -orphaned uit op de donor. De donor en de companion delen dezelfde map <database>.LogArch. De opdracht verwijdert het levende archief van de nieuwe master.

Oude master.

  • Als de donor zijn laatste werkende replica was, zet RCM de oude master op Master gedegradeerd en pauzeert het verzenden naar de donor („verzending gepauzeerd: … (promotie tot master)”). Hervat het verzenden naar de donor niet: die bevat al een werkende database. Om deze toestand te wissen, initialiseert u de database naar een andere replica.

    Oude master: „Master gedegradeerd”, verzending gepauzeerd
    Oude master: „Master gedegradeerd”, verzending gepauzeerd
  • Initialisatie van de oude master naar de donor-node wordt geweigerd (target_not_replica): die bevat al een werkende database.
  • Als de stap NEW GUID is overgeslagen, hebben de oude en de nieuwe master dezelfde GUID. In dat geval vereist initialisatie vanaf de oude master -force (hoofdstuk 5.9).
  • Na een handmatige promotie maakt RCM van de oude master geen replica van de nieuwe master. Stop de toepassingen op de oude master en haal zijn database uit het beheer (hoofdstuk 3.8). Voor een database die als service is beschreven, doet Opnieuw aansluiten dat (8.7).

Nieuwe master. Richt er een replica voor in: replica-node, partners (hoofdstuk 2), publicatie (hoofdstuk 6), initialisatie (hoofdstuk 5).

Nieuwe master: database met een nieuwe GUID, nog geen replica
Nieuwe master: database met een nieuwe GUID, nog geen replica

8.6. Geplande omschakeling: checklist

Dit is de procedure voor een handmatige omschakeling. Voor een database die als service is beschreven, schakelt RCM de master zelf om (8.7). Een handmatige promotie controleert niet of toepassingen naar de oude master schrijven. Procedure:

  1. Vooraf. Op de replica-host draait een companion-node met de rol master, en beide nodes hebben hetzelfde label host (hoofdstuk 2.1). Een node voor de toekomstige replica staat klaar voor de nieuwe master.
  2. Stop het schrijven van toepassingen naar de database van de oude master.
  3. Wacht tot de replica alles heeft ontvangen en toegepast: Databases → IN_SYNC, geen wachtrij.
  4. Controleren (hoofdstuk 5.10): de rijaantallen komen overeen.
  5. Promoveren tot master (8.3). Wacht op de stap FINALIZE.
  6. Controleer: de database staat in de masterlijst van de companion, publicatie aan.
  7. Schakel de toepassingen over naar de nieuwe master.
  8. Maak een nbackup-kopie van niveau 0 van de nieuwe database (8.4).
  9. Wis het spookrecord van de donorrij (8.5).
  10. Koppel de replica aan de nieuwe master en initialiseer hem (hoofdstuk 5).
  11. Oude master: haal de database uit het beheer of laat hem als archief staan (8.5).

8.7. Services: omschakeling en failover in RCM

Met HQbird 2027.2.30 verplaatst RCM de master zelf naar een andere host. Daarvoor wordt de database beschreven als een service: één logische database op meerdere hosts. Op elke host van de service staat een master-node en een replica-node, en het pad naar het databasebestand is hetzelfde. De service wordt gemaakt op de pagina Diensten (vanaf HQbird 2027.2.31) of met de opdracht hqbirdrcm services put -id <id> -file <file>.json.

Actie Wat die doet Opdrachten
Omschakeling geplande overdracht van de master zonder gegevensverlies. Daarna wordt de oude master automatisch een replica van de nieuwe master hqbirdrcm switchover -service <id> -check, daarna hqbirdrcm switchover -service <id> -to <host>
Failover de host van de master is weg: RCM promoveert de replica. De meest recente wijzigingen van de master kunnen verloren gaan hqbirdrcm failover -service <id> -check, daarna hqbirdrcm failover -service <id> -to <host> -accept-data-loss
Opnieuw aansluiten na een failover brengt dit de oude host terug als replica van de nieuwe master hqbirdrcm rejoin -service <id>
Hervatten haalt de service uit de toestand failed hqbirdrcm resume -service <id> -check, daarna hqbirdrcm resume -service <id>

Dezelfde acties staan op de servicepagina: de knoppen Omschakeling…, Failover…, Opnieuw aansluiten… en Hervatten….

  • Automatische failover staat standaard uit. Die wordt per service ingeschakeld: hqbirdrcm policy -service <id> -auto-failover on -max-data-loss 30. Er zijn routers voor nodig. RCM start een failover alleen wanneer de master-node zwijgt, de meerderheid van de routers de Firebird van de master niet ziet, en de achterstand van de replica niet groter is dan max_data_loss_sec.
  • Een router (hqclusternode router, Linux) houdt HAProxy op de huidige master van de service. Toepassingen verbinden met <router host>:<router_port> en wijzigen de verbindingsreeks niet wanneer er wordt omgeschakeld.
  • Na een failover plaatst RCM de oude master in de rol fenced, zodra die weer antwoordt. Breng hem terug met de opdracht rejoin.