Guida dell'amministratore per il cluster di replica HQbird: hqclusternode e hqbirdrcm (RCM). Programmi di installazione: Download di HQbird 2027.

Contenuto


0. Introduzione

Questa guida descrive come installare e usare il cluster di replica HQbird: i nodi hqclusternode e il gestore del cluster hqbirdrcm (RCM).

È una guida per l’amministratore di Firebird. Si presume che tu conosca Firebird, gfix e nbackup. Non è necessario conoscere il funzionamento interno di un nodo.

Di che cosa è composto il cluster

Componente Quanti Dove viene eseguito Che cosa fa
Firebird (HQbird) una o più istanze su ogni server di database memorizza i database, scrive i segmenti di replica
fbagent uno per istanza di Firebird accanto a Firebird arresta e avvia Firebird su richiesta di un nodo
hqclusternode (nodo) uno per istanza e ruolo accanto a Firebird configura la replica, trasferisce i segmenti, esegue l’inizializzazione della replica
hqbirdrcm (RCM) uno per cluster su qualsiasi host che possa vedere tutti i nodi interfaccia web, comandi, avvisi, statistiche

Un nodo ha un ruolo: master o replica. Due nodi possono essere eseguiti su una sola istanza di Firebird: un nodo master e un nodo replica. In quel caso alcuni database di questo Firebird sono master e altri sono repliche.

Come funziona

  1. Sul master, Firebird scrive le modifiche del database nei segmenti (file del registro di replica).
  2. Il nodo master invia i segmenti al nodo replica su un canale protetto (mTLS).
  3. Il nodo replica colloca i segmenti nella cartella dei segmenti in arrivo. Il Firebird della replica li applica alla propria copia del database.
  4. Il nodo master stesso trasferisce la prima copia del database alla replica. Questo si chiama inizializzazione (reinit). Avviene tramite nbackup, e il master continua a funzionare durante questo tempo.
  5. I nodi inviano le statistiche a RCM. RCM mostra lo stato del cluster e invia i comandi dell’operatore ai nodi.
Come funziona il cluster: segmenti, inizializzazione, statistiche e comandi dell'operatore
Come funziona il cluster: segmenti, inizializzazione, statistiche e comandi dell'operatore

Versioni supportate

  • Firebird / HQbird 5.0 e 4.0: tutte le funzioni.
  • HQbird 3.0 e 2.5: replica tramite il plugin replconf. Non ci sono pubblicazioni; l’insieme delle tabelle è definito dai filtri. Le differenze sono descritte nei riquadri «HQbird 2.5/3.0».

La versione principale di Firebird sul master e sulla replica deve coincidere. Altrimenti il nodo replica rifiuterà l’inizializzazione.

Porte

Porta Chi è in ascolto Chi si connette A che cosa serve
7051 nodo gli altri nodi e RCM API del nodo, trasferimento di segmenti e copie del database
7443 RCM tutti i nodi ricezione delle statistiche dai nodi
7444 RCM operatore interfaccia web e API dell’operatore. Installazione tramite RCM (capitolo 1.3): HTTPS su tutti gli indirizzi. Installazione tramite HQCenter Admin o manuale: HTTP, solo 127.0.0.1
7450–7459 fbagent, mentre la finestra di collegamento è aperta RCM collegamento degli host (capitolo 1.3)
13050 fbagent, solo 127.0.0.1 nodo sullo stesso host gestione di Firebird
3050 Firebird applicazioni funzionamento normale del database

Se ci sono due nodi su un host (master e replica), il secondo nodo ha una porta diversa. Con l’installazione tramite RCM, il secondo nodo riceve la porta 7061. Negli altri casi imposta tu stesso la porta, per esempio 7052.

La porta 13050 non deve essere esposta alla rete. Nemmeno la porta 7444 con HTTP (installazione tramite HQCenter Admin o manuale): connettiti all’interfaccia web di RCM attraverso un tunnel SSH (capitolo 1). Con l’installazione tramite RCM, la porta 7444 funziona su HTTPS, e il programma di installazione la apre nel firewall.

La regola principale: senza fbagent, nessuna modifica

Un nodo modifica la configurazione di replica solo tramite fbagent: deve riavviare Firebird. Se fbagent non è disponibile, il nodo rifiuta qualsiasi azione che modifichi la configurazione. Non lavora «a metà».

Termini

Termine Significato
Segmento file del registro di replica con le modifiche del database
Pubblicazione elenco delle tabelle del master le cui modifiche finiscono nei segmenti (Firebird 4/5)
Inizializzazione (reinit) trasferimento di una copia del database dal master alla replica tramite nbackup
GUID del database identificatore del database Firebird; RCM lo usa per collegare il master e la replica
Partner nodo partner: per un master, le sue repliche
Compagno il secondo nodo sulla stessa istanza di Firebird (master e replica su un host)
Iscrizione registrazione dei database master nel nodo

Come leggere la guida

Capitolo Argomento
1. Installazione installazione dei nodi e di RCM tramite HQCenter Admin, tramite RCM senza HQCenter Admin e manualmente, Linux e Windows
2. Configurazione del cluster collegamenti master → replica, impostazioni dei nodi, utenti RCM
3. Aggiungere un database al master iscrizione, riavvio di Firebird, verifica
4. Come rendere un database una replica fasi, preparazione della replica, spazio su disco
5. Inizializzazione passaggi della reinizializzazione, effetto sul funzionamento, transazioni lunghe, velocità, errori
6. Configurazione della pubblicazione pubblicazione Firebird 4/5, tabelle, tabelle nuove, HQbird 2.5/3.0
7. Altre opzioni di replica parametri di replication.conf, archivio, trasferimento, avvisi, pausa, log
8. Conversione di una replica in un database normale Rendi normale, Promuovi a master, nuovo GUID, servizi (commutazione, commutazione di emergenza), elenco di controllo della commutazione

Tutti i capitoli usano un solo esempio:

Che cosa Valore
node-a nodo master, database in /databases/master
node-b nodo replica, database in /databases/replica
RCM un host separato (può essere anche uno dei server di database)
database employee.fdb

1. Installazione dei nodi e di hqbirdrcm

Ci sono tre metodi di installazione:

Metodo Quando sceglierlo Che cosa fai tu
Tramite HQCenter Admin (1.2) il percorso abituale: il server di aggiornamento di HQCenter Admin è raggiungibile, servono gli aggiornamenti automatici esegui lo script di installazione di fbagent, approvi la richiesta, descrivi il cluster
Tramite RCM, senza HQCenter Admin (1.3) non c’è HQCenter Admin, ma servono certificati, configurazione e aggiornamenti senza lavoro manuale; fino a 3 server di database installi HQbird su ogni host, accedi a RCM e in Impostazioni → Collega gli host indichi gli indirizzi degli host
Manuale (1.4) nessun accesso a HQCenter Admin, rete chiusa, requisiti particolari installi i file, crei i certificati, scrivi node.json e rcm.json, registri i servizi

Tramite HQCenter Admin e tramite RCM non installi tu stesso i nodi e RCM. Li installa fbagent quando lo aggiungi al cluster (capitolo 2). Anche i certificati e la configurazione vengono creati automaticamente.

Linux e Windows sono descritti in un solo capitolo. Le differenze di Windows sono nei riquadri «Su Windows».

1.1. Requisiti

Su ogni server di database:

  • Firebird / HQbird 5.0, 4.0, 3.0 o 2.5 (2.5: solo Linux).
  • fbagent accanto a ogni istanza di Firebird. Senza fbagent il nodo non funziona.
  • Sincronizzazione dell’ora (NTP, chrony, w32time) su tutti i server e sull’host di RCM. Le finestre di riavvio e di trasferimento, la stima del ritardo e il controllo «nodo che non risponde» dipendono dagli orologi.
  • Spazio libero per l’archivio dei segmenti e per l’inizializzazione della replica (capitolo 4).
  • Rete secondo la tabella delle porte (capitolo 0).

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

Windows: privilegi di amministratore, x64, Windows 10 / Server 2016 o successivo, Windows PowerShell 5.1 a 64 bit. Su Windows 10 e Server 2016–2022 è necessario 7-Zip.

Dove verrà eseguito RCM. Serve un RCM per cluster. Può essere installato su qualsiasi server che possa vedere tutti i nodi, anche su uno dei server di database.

1.2. Installazione tramite HQCenter Admin

Passo 1. Eseguire lo script di installazione di fbagent

Lo script installa Firebird (la build HQbird), fbagent, e registra fbagent sul server HQCenter Admin. Scegli lo script corrispondente alla tua versione di Firebird: fb25, fb30, fb40, fb50.

Linux (come root):

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

Su Windows (PowerShell come amministratore):

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

Su Windows non esiste il parametro -Cluster: fbagent viene eseguito come LocalSystem e crea da solo le cartelle del cluster.

Parametri principali:

Linux Windows Significato
--goafts <name> -Goafts server HQCenter Admin da cui scaricare; il nome è fornito dal fornitore
--enroll -Enroll registrare fbagent in HQCenter Admin (richiesta di certificato)
--cluster — creare le cartelle /opt/hqclusternode e /opt/hqbirdrcm (necessario solo per fbagent 2.55.2 e precedenti; innocuo per le versioni più recenti)
--channel -Channel canale di aggiornamento di fbagent, stable per impostazione predefinita
--token -Token token di licenza: HQCenter Admin approverà la richiesta automaticamente
--port -Port porta di Firebird
--yes -Yes non fare domande (necessario quando non c’è un terminale)

Per l’elenco completo dei parametri, vedi il README dello script di installazione di fbagent.

Passo 2. Approvare la richiesta di fbagent

Con il parametro --enroll, fbagent invia una richiesta di certificato (CSR) a HQCenter Admin e attende fino a 30 minuti l’approvazione. Puoi approvarla così:

  • automaticamente, se l’installazione è stata eseguita con un token di licenza (--token) e la licenza ha uno slot libero;
  • nel pannello di HQCenter Admin, sezione delle richieste CSR, la richiesta di questo host, pulsante di approvazione e firma;
  • tramite l’API di HQCenter Admin: POST /v1/admin/csr-requests/{id}/approve.

Se la registrazione non è riuscita (per esempio, il tempo di attesa è scaduto), fbagent continua a funzionare, ma lo script termina con il codice 2. Esegui di nuovo lo script con gli stessi parametri: verrà ripetuta solo la registrazione.

Qualche minuto dopo la registrazione, fbagent installa HQ Monitor da solo.

Passo 3. Descrivere il cluster

I nodi e RCM compaiono quando aggiungi fbagent al cluster di HQCenter Admin. Come descrivere il cluster è trattato nel capitolo 2.

Dopo il salvataggio del cluster:

  1. Entro 10 minuti fbagent riceve il cluster da HQCenter Admin (poi controlla le modifiche ogni 60 secondi).
  2. Il fbagent sull’host di RCM crea l’autorità di certificazione (CA) del cluster e firma i certificati di tutti i nodi.
  3. Ogni fbagent scrive node.json o rcm.json per i membri del proprio cluster.
  4. Al controllo successivo dei prodotti (ogni 3 minuti) fbagent installa e avvia i servizi.

Che cosa viene installato e dove:

Che cosa Linux Windows
Nodo master /opt/hqclusternode/master/, servizio hqclusternode-master-p<port> <HQbird>\hqclusternode\master\, servizio HQClusterNode-master-p<port>
Nodo replica /opt/hqclusternode/replica/, servizio hqclusternode-replica-p<port> <HQbird>\hqclusternode\replica\, servizio HQClusterNode-replica-p<port>
RCM /opt/hqbirdrcm/, servizio hqbirdrcm <HQbird>\hqbirdrcm\, servizio hqbirdrcm

<port> è la porta di Firebird, per esempio 3050. Un singolo fbagent può ospitare non più di un nodo master, un nodo replica, un RCM e un router (hqclusternode router, da HQbird 2027.2.30, capitolo 8.7).

Su Windows. Le versioni di fbagent precedenti alla 2.83.0 installavano i nodi in C:\hqclusternode e RCM in C:\hqbirdrcm. Se queste cartelle esistono, fbagent continua a usarle.

Aggiornamenti

  • fbagent controlla le nuove versioni del nodo e di RCM ogni 3 minuti; il canale predefinito è stable. Prima viene aggiornato il nodo replica, poi il nodo master.
  • Se, dopo un aggiornamento, il servizio non si avvia o segnala la versione sbagliata, fbagent torna alla versione precedente e blocca quella nuova. L’elenco dei blocchi: <cartella di fbagent>/update/<product>/blocked-versions.json. Per riprovare la versione, elimina la sua riga da questo file.
  • Stato del prodotto: fbagent --product-status hqclusternode (oppure hqbirdrcm).

1.3. Installazione tramite RCM (senza HQCenter Admin)

Il cluster è gestito da RCM. Il fbagent di ogni host riceve la descrizione del cluster da RCM, il fbagent sull’host di RCM firma i certificati, e il nodo e RCM vengono aggiornati dalle versioni archiviate da RCM.

Limitazioni:

  • Un cluster per RCM.
  • Non più di 3 postazioni. Una postazione è un host che esegue un nodo master o replica. Un master e una replica sullo stesso host contano come una postazione. Un host che esegue solo RCM non occupa una postazione. Un quarto host produce l’errore seats_exceeded.
  • RCM non aggiorna fbagent né Firebird. fbagent li aggiorna da solo e non tocca replication.conf, node.json, rcm.json né i certificati.

Ci sono due metodi:

  • Collega gli host in RCM: il metodo abituale. Tre azioni: il programma di installazione su ogni host (RCM su un host, modalità di rilevamento sugli altri), accesso a RCM, il modulo Collega gli host.
  • Manualmente dalla riga di comando: token di unione e fbagent --cluster-join. Serve quando la porta 7450 è chiusa tra gli host oppure la finestra di associazione si è già chiusa.

Licenza. La licenza di prova include la funzione cluster. Dopo il periodo di prova, fbagent non installa un nodo né RCM se la licenza non ha cluster. Non blocca mai gli aggiornamenti dei nodi e di RCM già installati. Senza HQCenter Admin, una licenza mobile smette di funzionare dopo online_check_days più i giorni di tolleranza. Installa quindi una licenza vincolata su ogni fbagent:

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

Senza licenza, il master smette di inviare i segmenti (capitolo 2.8).

Porte:

Porta Dove Chi si connette
7443 host di RCM fbagent e nodi di tutti gli host del cluster
7444 host di RCM browser dell’operatore (console RCM, HTTPS)
7450 (sul secondo fbagent dell’host e sui successivi: 7451…7459) host in modalità di rilevamento, mentre la finestra di associazione è aperta RCM sull’host di RCM
7051 (secondo nodo dello stesso fbagent: 7061) host dei nodi gli altri nodi e RCM (1.4, passo 7)

Collega gli host in RCM

Esempio da zero. Due server Linux, il programma di installazione .run, collegamento, registrazione, pubblicazione, inizializzazione e reinizializzazione sotto carico, con schermate e misure: la guida hqbird2027-linux-cluster-guide.ru.md e il runbook hqbird2027-linux-cluster-runbook.ru.md (repository goafts, cartella documentazione).

Passo 1. Installare HQbird su ogni host

Installa HQbird con il programma di installazione completo su ogni server di database. Non registrarti presso HQCenter Admin (--enroll).

Per impostazione predefinita il programma di installazione non configura un cluster. Colloca i programmi del nodo e di RCM nella cartella di fbagent (update/<product>/staged/), ma non installa RCM, non apre la finestra di associazione e non apre le porte del cluster nel firewall. Il cluster si attiva con due parametri:

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: su un host, dove verrà eseguito l’RCM del cluster. Il programma di installazione:

  1. crea il cluster di questo host (fbagent --cluster-init); il nome del cluster è il nome dell’host;
  2. installa e avvia RCM; la console RCM funziona su HTTPS alla porta 7444;
  3. crea il primo amministratore RCM rcmadmin con una password casuale;
  4. apre le porte 7443, 7444 e la porta del nodo 7051 nel firewall.

--cluster-pairing on (modalità di rilevamento): su ogni altro host. Il programma di installazione apre la finestra di associazione di fbagent per 24 ore: la porta 7450 e la porta del nodo 7051. Mentre la finestra è aperta, un RCM della rete può invitare questo host nel proprio cluster. fbagent inizia ad ascoltare sulla porta 7450 entro un minuto.

Senza questi parametri il programma di installazione chiede da solo: nell’interfaccia testuale è la pagina Cluster, con --no-tui sono due domande. La risposta predefinita è «no». --yes senza parametri di cluster risponde «no» anche a entrambe le domande.

Alla fine il programma di installazione stampa le righe RCM: e Pairing:. Sull’host di RCM:

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

Su un altro 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

Non c’è una password nell’output: è nel file della riga Password:. Annota il fingerprint di ogni host in modalità di rilevamento.

Parametri del cluster nel programma di installazione Linux:

Parametro Che cosa fa
--rcm on|off installare RCM e creare un cluster su questo host; predefinito off
--cluster-pairing on|off modalità di rilevamento: aprire la finestra di associazione per 24 ore; predefinito off
--pairing-port N porta di associazione del nuovo fbagent, 7450–7459; predefinita la prima libera
--rcm-password-file F password dell’amministratore RCM dalla prima riga del file F, al posto di una casuale
--cluster-id ID nome del cluster ID al posto del nome dell’host (con --rcm on)
--cluster-node on|off installare il programma del nodo; predefinito on
--rcm-allow A,B solo questi RCM possono invitare questo host: indirizzo, rete CIDR o nome

Il primo fbagent di un host riceve la porta di associazione 7450 e le porte del nodo 7051 e 7061. La seconda istanza sullo stesso host: 7451, 7052 e 7062.

RCM e la finestra di associazione si possono attivare più tardi, senza il programma di installazione: in HQ Monitor, la pagina Cluster, oppure con comandi come utente fbagent:

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

Programmi di installazione precedenti (fbagent prima della 3.1.0) non chiedono del cluster: installano RCM su ogni host e aprono la finestra di associazione ovunque. Ti serve l’RCM di un host; gli RCM degli altri host si fermano da soli dopo il collegamento.

Su Windows. Le stesse due scelte esistono nel programma di installazione Windows: i parametri /RCM e /DISCOVERY.

Passo 2. Accedere a RCM

Apri l’indirizzo della riga RCM: dell’host di RCM (https://<host>:7444). Accedi con il nome utente rcmadmin e la password del file della riga Password:. RCM chiede subito una nuova password (1.5).

Passo 3. Collegare gli host

In RCM apri Impostazioni → Collega gli host.

  1. Nel campo Host inserisci gli indirizzi o i nomi degli host, uno per riga. La prima riga è l’host di RCM; è già nel cluster.
  2. Fai clic su Controlla gli host. RCM sonda le porte di associazione 7450–7459 di ogni host e mostra la piattaforma, la versione di Firebird, l’impronta e lo stato. L’host di RCM non ha bisogno di una finestra di associazione. Confronta le impronte con l’output del programma di installazione (la riga Pairing:).
  3. Seleziona il Master (per impostazione predefinita il primo host) e fai clic su Collega.
Collega gli host: risultato del controllo
Collega gli host: risultato del controllo

RCM chiede conferma e mostra l’avanzamento nella sezione Avanzamento. Quando tutti i nodi sono in esecuzione, dice «Fatto» e mostra il numero di revisione del cluster:

Collega gli host: tutti i nodi in esecuzione
Collega gli host: tutti i nodi in esecuzione

La stessa cosa dalla riga di comando:

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

Che cosa succede dopo:

  1. RCM invia un invito a ogni host libero.
  2. Il fbagent dell’host entra nel cluster e chiude la porta di associazione. Se l’host ha un proprio RCM senza nodi, fbagent lo arresta e lo disattiva, e sposta il suo cluster vuoto in cluster/left/ nella cartella di fbagent.
  3. RCM salva il cluster: nodo <host>-master sul master, <host>-replica sugli altri host, porta 7051, collegamenti master → replica.
  4. Il fbagent di ogni host installa e avvia il nodo. RCM attende che tutti i nodi siano in esecuzione e mostra In esecuzione per ogni host.

Stati dell’host dopo Controlla gli host:

Stato Che cosa fare
Pronto per il collegamento niente. Se sotto dice «L’RCM proprio di questo host si arresterà dopo il collegamento», è normale
Nel cluster l’host è già in questo cluster
Errore unreachable la porta 7450 è chiusa: la finestra di associazione è spenta (come per impostazione predefinita) oppure sono passate le 24 ore. Subito dopo l’installazione aspetta un minuto e fai di nuovo clic su Controlla gli host. Altrimenti apri la finestra (--cluster-pairing on) e controlla il firewall
Errore in_other_cluster l’host è in un altro cluster
Errore claimed un altro RCM sta collegando questo host in questo momento
Errore seats_exceeded più di 3 postazioni

Versioni. fbagent installa il nodo solo da RCM. RCM prende le versioni firmate dalla propria cartella import/ (accanto a rcm.json) all’avvio e ogni 5 minuti. Il programma di installazione vi mette le versioni dell’host di RCM, e i fbagent degli altri host scaricano da soli la versione per la propria piattaforma. L’elenco delle versioni è in fondo alla pagina Collega gli host. Una versione si può anche importare manualmente (passo 5, più avanti).

Manualmente dalla riga di comando

Ordine: passi 1–3 sull’host di RCM, passo 4 su ogni altro host, passi 5–6 in RCM.

Passo 1. Installare HQbird con fbagent

Installa HQbird su ogni server di database e sull’host di RCM con il programma di installazione completo. Sull’host di RCM puoi indicare subito --rcm on (allora il passo 3 non serve). Sugli altri host non indicare parametri di cluster: per impostazione predefinita non ci sono né RCM né finestra di associazione. Non registrarti presso HQCenter Admin (--enroll).

Sull’host di RCM il programma di installazione lascia il programma RCM nella cartella di fbagent (update/hqbirdrcm/staged/). Senza di esso il passo 3 fallisce con l’errore no hqbirdrcm to install.

Passo 2. Installare la licenza vincolata

Come all’inizio della sezione, «Licenza».

Passo 3. Creare il cluster sull’host di RCM

Se il programma di installazione ha già creato il cluster (--rcm on: una riga RCM: con un indirizzo nel suo output), salta questo passo.

Esegui il comando come utente fbagent (su Linux, firebird), non come root: altrimenti i file della CA e rcm.json apparterranno a root.

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

Su Windows (PowerShell come amministratore): .\fbagent.exe --cluster-init shop-prod --address 10.0.0.7

  • shop-prod: nome del cluster: lettere latine minuscole, cifre e -.
  • --address: l’indirizzo dell’host di RCM tramite il quale gli altri host vi si connettono. Si può ripetere più volte. Senza il parametro, si usano gli indirizzi e il nome dell’host.

Il comando:

  1. crea la CA del cluster e la CA dell’agente (nella cartella di fbagent, clusterca/<name>/);
  2. scrive il certificato RCM, rcm.json e cluster-init.json nella cartella di RCM;
  3. installa RCM e registra il servizio hqbirdrcm. Su Linux il servizio viene eseguito come utente distinto hqbirdrcm;
  4. passa fbagent a RCM (cluster.source = rcm) e lo riavvia;
  5. stampa l’indirizzo di RCM e l’impronta della CA:
Code
Cluster:    shop-prod
RCM URL:    https://10.0.0.7:7443
CA hash:    sha256:9f86d0...

Annota RCM URL e CA hash: servono sugli altri host. Eseguirlo di nuovo per lo stesso cluster è sicuro: la CA e le chiavi restano le stesse.

Accedi subito a RCM e cambia la password di rcmadmin (1.5).

Su Linux. L’utente hqbirdrcm è nel gruppo di fbagent. RCM legge rcm.json tramite questo gruppo, ma non può scriverlo. Perciò Impostazioni → RCM non salva le modifiche (errore rcm_config_read_only). Modifica rcm.json sull’host come utente fbagent e riavvia RCM.

Passo 4. Collegare i fbagent degli altri host

  1. Sull’host di RCM crea un token di unione per ogni fbagent: in RCM Impostazioni → Cluster, il pulsante Crea token di unione. Oppure dalla riga di comando:

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

    Il token è valido per 24 ore, per un solo fbagent e una sola volta. RCM lo mostra una volta, insieme a un comando già pronto.

  2. Sull’host del nodo esegui questo comando come utente fbagent:

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

    Al posto di --token-file puoi usare --token <token>. Su Windows, la stessa cosa con .\fbagent.exe in PowerShell come amministratore.

fbagent verifica la CA di RCM tramite l’impronta. Se l’impronta non coincide, si ferma e non scrive nulla. Poi fbagent riceve il proprio certificato (90 giorni, rinnovato automaticamente) e si riavvia. Un fbagent collegato è visibile in RCM nella tabella Agenti. Finché non ha membri, sull’host non viene installato nulla.

Passo 5. Importare le versioni in RCM

fbagent prende il nodo e RCM solo da RCM. Se la versione richiesta non è nell’elenco Versioni nello specchio (Impostazioni → Collega gli host), importa ogni prodotto (hqclusternode, hqbirdrcm) per ogni piattaforma dei tuoi host (linux-amd64, windows-amd64). Il file della versione e la firma .sig sono forniti dal fornitore.

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 cerca la firma in <file>.sig, oppure indicala con -sig. Senza una firma valida del fornitore, RCM non accetterà il file.
  • Una versione nuova sostituisce la precedente. Non serve riavviare RCM.
  • fbagent controlla le nuove versioni ogni 3 minuti. L’ordine di aggiornamento e il blocco sono come tramite HQCenter Admin (1.2, «Aggiornamenti»).

Passo 6. Descrivere il cluster

Imposta i membri e i collegamenti in RCM, Impostazioni → Cluster (capitolo 2.3). Dopo il salvataggio, fbagent installa i nodi nello stesso modo che tramite HQCenter Admin (1.2, passo 3): scrive i certificati, node.json e rcm.json, installa e avvia i servizi.

Le porte sono all’inizio della sezione.

1.4. Installazione manuale

Passo 1. Installare HQbird con fbagent

Installa HQbird su ogni server di database (con lo stesso script, ma senza --enroll, oppure con il programma di installazione completo di HQbird). Verifica che fbagent sia in esecuzione.

Annota tre valori dal agent_config.json di fbagent. Servono per node.json:

Campo di fbagent Campo di node.json Esempio
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 —

Controllo di fbagent (la risposta è il JSON dell’istanza di Firebird):

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

Se l’host ha diverse istanze di HQbird, lascia solo il servizio della tua istanza in firebird.update.services della configurazione di fbagent (vedi 3.5).

Passo 2. Disporre i file

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

Su Windows. La cartella predefinita è C:\hqclusternode, con la stessa disposizione. È consentito un percorso che contiene uno spazio.

Se un host ha due nodi (master e replica), dai a ciascuno la propria cartella, per esempio /opt/hqclusternode/master e /opt/hqclusternode/replica.

Passo 3. Creare i certificati

I nodi e RCM comunicano solo tramite mTLS. Serve una CA e un certificato per ogni partecipante. Esegui questo una volta su qualsiasi macchina:

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

Il comando crea ca.crt e ca.key, node-a.crt/.key, node-b.crt/.key e rcm.crt/.key. In -hosts, elenca tutti i nomi e gli indirizzi con cui ci si collegherà ai partecipanti.

gencerts e i file che ha creato
gencerts e i file che ha creato

ca.key è la chiave della CA. Non copiarla sugli host; conservala a parte.

Un nodo nuovo si aggiunge più tardi con -add: firma la coppia con la stessa CA e lascia gli altri file invariati:

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

I certificati sono validi per 90 giorni. gencerts -out certs -list mostra le date di scadenza, e gencerts -out certs -renew li rinnova con la stessa chiave. Copia il nuovo .crt sul suo host: il nodo lo prenderà senza un riavvio.

Copia ca.crt e solo il proprio certificato e la propria chiave su ogni host.

Passo 4. Scrivere node.json

Un file per nodo. Esempio per il 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" } ]
}

Il nodo replica (node-b) ha lo stesso file, ma con "role": "replica", i propri certificati e il master node-a in peers.

Campi principali:

Campo Valore
node_id nome del nodo; lo stesso nel certificato, in rcm.json e nei peers degli altri nodi
role master o replica
listen_addr indirizzo dell’API del nodo; un secondo nodo sullo stesso host usa un’altra porta (:7052)
rcm.url indirizzo per ricevere le statistiche di RCM; none: nessun RCM
firebird.* il Firebird e il fbagent di questa istanza; i valori di fbagent devono coincidere esattamente
firebird.auto_restart se il nodo replica può riavviare Firebird da solo: auto (predefinito), never, always
windows.restart_window finestra di riavvio di Firebird; per il master il valore predefinito è 22:00-05:00, per la replica è sempre
windows.transfer_window finestra in cui l’inizializzazione procede a piena velocità
peers per il master, le sue repliche; per la replica, il suo master
databases cartella dei database; è meglio non scriverla a mano, ma impostarla tramite RCM (capitolo 3)

Gli altri campi hanno valori predefiniti. Il nodo non si avvierà se i campi di fbagent non sono impostati.

Proteggi il file: contiene la password e il token.

Command
chmod 600 /opt/hqclusternode/node.json

Su Windows. Scrivi i percorsi in formato JSON: "C:\\HQbird\\replication.conf". service_name è il nome del servizio Windows di Firebird.

Passo 5. Scrivere rcm.json

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: indirizzo del nodo come lo vede l’host di RCM. Solo https.
  • host: etichetta dell’istanza di Firebird. Un nodo master e un nodo replica con la stessa etichetta vengono eseguiti sullo stesso Firebird (compagno, necessario per promuovere una replica a master, capitolo 8). Un’etichetta: non più di un master e una replica.
  • I percorsi relativi si risolvono dalla cartella di rcm.json.

Passo 6. Registrare i servizi

Ordine di avvio: prima RCM, poi le repliche, poi il master.

RCM (Linux):

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

Nodo (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 crea il servizio hqclusternode-<role>-p<port>, eseguito come utente firebird. Se la cartella di Firebird appartiene a root, il comando concede al gruppo firebird l’accesso in scrittura (con il bit sticky) e stampa ogni modifica: il nodo deve sostituire replication.conf.

Per svc start, svc stop e svc uninstall, indica lo stesso node.json: il nome del servizio deriva dal ruolo e dalla porta di Firebird.

Su Windows (PowerShell come amministratore):

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

Il servizio HQClusterNode-<role>-p<port> viene eseguito come LocalSystem, si avvia automaticamente e si riavvia dopo un errore. Il servizio del nodo non dipende dal servizio di Firebird. Se il nodo è stato installato con la versione 2027.1.2–2027.1.9, rimuovi la dipendenza una volta: .\hqclusternode.exe svc fix-deps -config C:\hqclusternode\node.json.

svc install e svc start su Windows
svc install e svc start su Windows

Passo 7. Aprire le porte

Sull’host del nodo, consenti le connessioni in ingresso su 7051 (la porta di listen_addr) dagli altri nodi e da RCM. Sull’host di RCM, consenti le connessioni in ingresso su 7443 da tutti i nodi. Non esporre all’esterno le porte 7444 e 13050.

Esempio di ufw sull’host del nodo:

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

Aggiornamento manuale

Arresta il servizio, sostituisci il programma, avvia il servizio:

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

La configurazione e i certificati non vengono modificati da questo.

1.5. Primo accesso a RCM

L’indirizzo e la password dipendono da come è stato installato RCM.

Come è stato installato RCM Indirizzo Nome utente e password
Dal programma di installazione di HQbird o da fbagent --cluster-init (1.3) https://<host di RCM>:7444 da qualsiasi computer rcmadmin e la password stampata dal programma di installazione (oppure la tua, da --rcm-password-file)
Tramite HQCenter Admin (1.2) o manualmente (1.4) http://127.0.0.1:7444, solo sull’host di RCM rcmadmin, password strong password (con uno spazio)

HTTPS (1.3). Il certificato di RCM è firmato dalla CA del cluster, che il browser non conosce, quindi avvisa. Nella pagina di accesso RCM mostra l’impronta della CA. Confrontala con il CA hash stampato dal programma di installazione, e importa la CA nel browser o nel sistema come radice attendibile: il collegamento Scarica il certificato della CA nella pagina di accesso (https://<host di RCM>:7444/ca.crt, file hqcluster-ca.crt). Per far ascoltare RCM solo su localhost, imposta "operator_addr": "127.0.0.1:7444" in rcm.json e riavvia RCM.

HTTP (1.2, 1.4). Da un altro computer, connettiti tramite un tunnel SSH:

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

Poi apri http://127.0.0.1:7444 nel browser.

Pagina di accesso di RCM
Pagina di accesso di RCM

Password generata. RCM chiede di cambiarla al primo accesso: finché non la cambi, le altre pagine non si apriranno. Cambia strong password subito (il collegamento Password nell’intestazione).

Cambio della password al primo accesso
Cambio della password al primo accesso

Lingua. Seleziona Russo nell’elenco delle lingue nell’intestazione della pagina (è disponibile anche nella pagina di accesso). Se non ne selezioni una, la lingua viene presa dal browser.

Cambio delle password e nuovi utenti

Ogni utente cambia la propria password: il collegamento Password nell’intestazione della pagina. Servono la password attuale e una nuova di almeno 12 caratteri. Dopo il cambio, le altre sessioni di quell’utente vengono chiuse.

Se il programma di installazione ha generato una password, viene scritta nel file clusterca/<name>/rcm-initial-password nella cartella di fbagent. Dopo il cambio della password, fbagent elimina questo file da solo. Non eliminare il file initial-admin.json nella cartella di RCM: contiene solo un hash. Se il file degli utenti viene perso e questo file è assente, RCM creerà un utente con la password predefinita.

Nuovi utenti. Non c’è una pagina degli utenti nell’interfaccia. Gli utenti sono memorizzati nel file rcm-data/users.json. La password è memorizzata come hash HA1: MD5("<name>:hqbirdrcm:<password>").

  1. Calcola l’hash:

    Command
    printf '%s' 'rcmadmin:hqbirdrcm:<new password>' | md5sum
  2. Scrivilo nel campo ha1 dell’utente in users.json. Per aggiungere un utente, aggiungi un altro elemento a users:

    json
    { "username": "ivanov", "ha1": "<hash>", "algo": "MD5", "created_at": "2026-11-03T00:00:00Z" }
  3. Riavvia subito RCM: legge il file solo all’avvio. Quando una password viene cambiata nell’interfaccia, RCM riscrive il file dalla memoria, e le modifiche che non ha ancora letto andranno perse.

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

Senza un campo role, un utente ha tutti i permessi. Da HQbird 2027.2.31 esiste il ruolo "role": "viewer": sola visualizzazione; qualsiasi richiesta di modifica riceve 403.

1.6. Come verificare l’installazione

  • I servizi del nodo e di RCM sono in esecuzione e non si riavviano in ciclo: systemctl status hqclusternode-master-p3050, systemctl status hqbirdrcm.

    systemctl status del nodo
    systemctl status del nodo
systemctl status di RCM
systemctl status di RCM
  • RCM risponde (senza password): curl http://127.0.0.1:7444/healthz. Se installato tramite RCM (1.3), la console funziona su HTTPS: curl -k https://127.0.0.1:7444/healthz.

  • In RCM, la pagina Panoramica mostra tutti i nodi, senza il contrassegno «non risponde».

  • Dalla riga di comando sull’host di RCM:

    Command
    export RCM_USER=rcmadmin RCM_PASSWORD='<password>'
    ./hqbirdrcm nodes
    ./hqbirdrcm status
  • Il cluster tramite RCM: Impostazioni → Cluster, la sezione Stato: ogni membro ha applicato l’ultima revisione e non segnala errori. Dalla riga di comando: ./hqbirdrcm cluster status.

1.7. Log

Che cosa Dove
Log del nodo <cartella di node.json>/logs/node-YYYYMMDD.jsonl
Output del servizio del nodo (Linux) journalctl -u hqclusternode-<role>-p<port>
Output del servizio RCM (Linux) journalctl -u hqbirdrcm
Log di replica di Firebird firebird.replication_log da node.json
Log di qualsiasi nodo senza SSH RCM, pagina Log

1.8. Errori comuni

Che cosa vedi Causa Che cosa fare
Il nodo non si avvia: un errore su fbagent_url, fbagent_token o instance_id fbagent non è in esecuzione oppure i valori non coincidono con agent_config.json controlla fbagent con il comando curl del 1.4, passo 1
Lo script di installazione è terminato con il codice 2 la richiesta di fbagent non è stata approvata in tempo approva la richiesta ed esegui di nuovo lo script
I nodi non compaiono tramite HQCenter Admin fbagent non è nel cluster, oppure il cluster non è ancora stato ottenuto controlla il cluster (capitolo 2), aspetta fino a 10 minuti
Il nodo in RCM è «non risponde» la porta 7051 è chiusa, l’url in rcm.json è errato, l’indirizzo non è nel certificato controlla le porte e il -hosts dei certificati
Nessun accesso a RCM: «Troppi tentativi di accesso non riusciti» 10 accessi non riusciti in 5 minuti aspetta qualche minuto
La nuova versione non si installa la versione è in blocked-versions.json rimuovi la riga della versione dal file
--cluster-init: no hqbirdrcm to install il programma di installazione non ha lasciato il programma RCM installa HQbird con il programma di installazione completo (1.3, «Manualmente», passo 1)
--cluster-join: token_used, token_expired, token_revoked il token è già stato usato, ha più di 24 ore oppure è stato revocato crea un nuovo token (1.3, «Manualmente», passo 4)
--cluster-join: hostname_conflict il cluster ha un fbagent con lo stesso nome host e indirizzi diversi dai nomi diversi agli host
--cluster-join: this agent is in cluster … from goafts fbagent è già nel cluster di HQCenter Admin rimuovilo dal cluster di HQCenter Admin
Il nodo non si installa tramite RCM RCM non ha una versione per questa piattaforma hqbirdrcm release list, importa la versione (1.3, «Manualmente», passo 5)

2. Configurazione del cluster

In questo capitolo definisci quali nodi sono nel cluster e quale master invia i segmenti a quale replica. Poi configuri i nodi e gli utenti di RCM.

Le relazioni si definiscono in uno di questi tre modi:

Nodi installati Dove si definiscono le relazioni Sezione
tramite HQCenter Admin in HQCenter Admin: la pagina Cluster di HQ Monitor o l’API di HQCenter Admin 2.2
tramite RCM, senza HQCenter Admin in RCM: Impostazioni → Cluster, hqbirdrcm cluster o la pagina Cluster di HQ Monitor 2.3
manualmente in RCM: Impostazioni → RCM e Impostazioni → Nodi 2.3

Sui nodi installati tramite HQCenter Admin o tramite RCM, cambia le relazioni solo nella descrizione del cluster. fbagent sovrascrive node.json e rcm.json secondo la descrizione del cluster. Modificare le relazioni in Impostazioni → RCM o Impostazioni → Nodi di RCM viene rifiutato (409 cluster_managed). Le versioni precedenti di RCM lo accettavano, ma andava perso.

2.1. Ruoli e schemi

Ogni nodo ha un ruolo: master o replica. Due nodi, un master e una replica, possono essere eseguiti su una sola istanza di Firebird.

Schemi supportati:

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

Il collegamento va sempre dal master alla replica. RCM collega il database del master alla sua replica tramite il GUID del database, non tramite il nome del nodo.

Compagno. Un nodo master e un nodo replica sulla stessa istanza di Firebird sono compagni. La promozione di una replica a master (capitolo 8) funziona solo per una tale coppia. In rcm.json la coppia è contrassegnata da un valore host identico.

2.2. Collegamenti tramite HQCenter Admin

Dove descrivere un cluster

  • HQ Monitor, pagina Cluster (solo amministratori; la consegna della configurazione deve essere attivata). Il modo abituale.
  • API di HQCenter Admin: POST /v1/admin/clusters e PUT /v1/admin/clusters/{id}. Il pannello di HQCenter Admin non ha una pagina dei cluster.

``

Passi nella pagina Cluster

  1. Inserisci un Id del nuovo cluster (lettere latine minuscole, cifre e -) e fai clic su Crea.
  2. Aggiungi i membri (Membri). Per ciascuno indica:
    • il fbagent dell’host;
    • il ruolo: master, replica o rcm;
    • gli indirizzi dell’host;
    • la porta: per un nodo, 7051 (un secondo nodo sullo stesso host, per esempio 7052); per RCM, la porta di ingresso delle statistiche 7443.
  3. Aggiungi i collegamenti (Collegamenti di replica) dal master alla replica.
  4. Fai clic su Valida, poi su Salva.

Se un altro amministratore ha modificato il cluster nello stesso momento, la pagina chiederà di ricaricare il cluster e di ripetere la modifica.

Regole

  • Un fbagent può appartenere a un solo cluster.
  • Su un singolo fbagent: non più di un master, una replica, un RCM e un router. Il router (ruolo router, da HQbird 2027.2.30) non ha collegamenti e non occupa una postazione di licenza (capitolo 8.7).
  • Un cluster ha esattamente un RCM. Il fbagent sull’host di RCM esegue l’autorità di certificazione (CA) del cluster.
  • Il nome del membro (member_id): lettere latine, cifre, -. Il nome, il fbagent e il ruolo di un membro non si possono cambiare. Per spostare un membro su un altro host, crea un nuovo membro con un nome nuovo. Non riusare il vecchio nome.
  • Ogni replica deve avere un collegamento verso il master.
  • HQCenter Admin costruisce da solo l’indirizzo del nodo: https://<primo indirizzo>:<port>.
  • HQbird 2.5/3.0: imposta la data replconf_valid_till del cluster (YYYY-MM-DD): la configurazione del plugin replconf è valida fino a quella data.

Esempio tramite l’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"}]}
  • Creare: POST /v1/admin/clusters (il documento può essere inviato insieme ai membri). Sostituire l’intero documento: PUT /v1/admin/clusters/{id}.
  • PUT richiede l’intestazione If-Match: <revision> (la revisione è fornita da GET e ETag). Senza l’intestazione, 428; con una revisione vecchia, 409; con un errore nel documento, 422 con un elenco di errori.
  • POST /v1/admin/clusters/{id}/validate valida il documento senza salvarlo.
  • GET /v1/admin/clusters/{id}/status mostra lo stato dei membri e le date di scadenza dei certificati.

Che cosa succede dopo il salvataggio

  1. Il fbagent di ogni membro riceve il cluster. Dentro il cluster, un controllo ogni 60 secondi (il fbagent sull’host di RCM, ogni 30 secondi). Fuori da un cluster, un fbagent viene a sapere del cluster al successivo sondaggio della configurazione. Se quel sondaggio non raggiunge il server, il controllo avviene ogni 10 minuti.
  2. Ogni fbagent crea una chiave e invia una richiesta di certificato. Il fbagent sull’host di RCM la firma. RCM firma il proprio certificato senza richiesta.
  3. fbagent scrive in node.json: nome, ruolo, indirizzo, peers (dai collegamenti), l’indirizzo di RCM, i percorsi dei certificati, i dati di Firebird e di fbagent. In rcm.json: l’elenco dei nodi (nodes), l’elenco dei router (routers), l’indirizzo di ingresso delle statistiche e i percorsi dei certificati. fbagent non tocca gli altri campi dei file.
  4. fbagent installa e avvia i servizi (capitolo 1).

Modifica di un cluster:

Che cosa è cambiato Che cosa fa fbagent
solo i peers di un nodo in esecuzione li passa al nodo senza riavvio
altri campi di un nodo arresta il nodo, scrive il file, avvia il nodo, dentro windows.transfer_window del nodo (non impostata: subito)
rcm.json riavvia subito RCM
certificati o CA riavvia il servizio
un membro viene rimosso arresta e rimuove il servizio; cluster-managed.json → cluster-removed.json, il programma → *.removed; configurazione, certificati e dati restano

Dopo la rimozione di un nodo, la sua sezione # BEGIN managed-by:<name> … # END … resta nel replication.conf condiviso. Eliminala a mano e riavvia Firebird tramite RCM.

Approvazione dei certificati del cluster

Per impostazione predefinita il fbagent sull’host di RCM firma le richieste da solo (auto). Si può attivare l’approvazione manuale. Comandi sull’host di RCM:

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 modalità manual, un membro nuovo o una chiave nuova attendono l’approvazione. Il rinnovo di un certificato con una chiave nota viene firmato automaticamente.

2.3. Collegamenti tramite RCM

Cluster RCM (senza HQCenter Admin)

Se il cluster è stato creato dal programma di installazione di HQbird o dal comando fbagent --cluster-init (capitolo 1.3), la descrizione del cluster è memorizzata da RCM. Il modo più semplice per aggiungere host è la pagina Impostazioni → Collega gli host (capitolo 1.3, «Collega gli host in RCM»): RCM crea da solo i membri e i collegamenti. Le regole sono le stesse di HQCenter Admin (2.2, «Regole»), più:

  • in RCM c’è un cluster; il membro rcm esiste sempre e non si può eliminare;
  • non più di 3 postazioni (host con nodi master o replica), altrimenti si verifica l’errore seats_exceeded;
  • un membro si può aggiungere solo su un fbagent che si è connesso a RCM (capitolo 1.3: «Collega gli host» o «Manualmente», passo 4).

Passi nella pagina Impostazioni → Cluster:

  1. Nella tabella Agenti, fai clic su Aggiungi membro nella riga del fbagent.
  2. Indica il ruolo (master, replica o router), member_id, gli indirizzi e la porta. La pagina suggerisce il nome <host>-<role> e la porta: 7051 per il primo nodo del fbagent, 7061 per il secondo. RCM rifiuta una porta già occupata da un altro membro dell’host. Gli indirizzi del fbagent sono pulsanti: fai clic per aggiungere un indirizzo.
  3. Nella sezione Collegamenti, fai clic su Aggiungi collegamento dal master alla replica.
  4. Fai clic su Valida: RCM mostrerà errori e avvisi.
  5. Fai clic su Salva. La pagina mostrerà l’elenco delle modifiche e chiederà conferma. Se si stanno eliminando dei membri, la finestra è rossa.

Prima del salvataggio, le modifiche esistono solo nella pagina (l’etichetta «Non salvato»). Se qualcuno ha salvato il cluster nello stesso momento, la pagina offrirà di ricaricarlo. Se sono cambiati solo campi di RCM (revisione, CA, incarichi), la pagina salverà la modifica da sola.

Altre sezioni della pagina:

Sezione Che cosa c’è
intestazione nome del cluster, revisione, CA del cluster e CA dell’agente; il pulsante Esporta per la CA precedente
Token di connessione creare un token per un nuovo fbagent, revocare uno non usato
Documento JSON l’intero documento in un campo di testo; Valida e Salva lo usano
Chiavi e CA incarichi: nuova chiave di un membro (rekey), nuova CA del cluster (rotate_ca), nuova CA dell’agente (rotate_agent_ca); non disponibili quando ci sono modifiche non salvate
Stato la revisione che ogni membro ha applicato, la scadenza del certificato, il servizio, l’ultimo errore

Dalla riga di comando sull’host di RCM:

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

Il formato del documento è quello del 2.2, «Esempio tramite l’API». apply con una revisione vecchia ottiene 409: esegui di nuovo show. RCM conserva le ultime 20 revisioni in rcm-data/cluster/history/.

HQ Monitor. La pagina Cluster funziona anche con RCM. Sull’host di RCM, HQ Monitor accede a RCM tramite il fbagent di quell’host, con il certificato di fbagent: utente e password di RCM non servono. Nel registro di audit di RCM queste azioni sono registrate come agent:<id> (<user>). Un altro modo, per le versioni precedenti di RCM: nella configurazione di HQ Monitor imposta rcm_admin_url (http://127.0.0.1:7444), rcm_admin_user (l’utente RCM) e rcm_admin_password_file (un file con la sua password).

Dopo il salvataggio, tutto procede come tramite HQCenter Admin (2.2, «Che cosa succede dopo il salvataggio»). RCM rilegge nodes in rcm.json da solo, senza riavvio.

Rimuovere un fbagent dal cluster: elimina i suoi membri e salva, poi fai clic su Revoca nella tabella Agenti (oppure ./hqbirdrcm cluster revoke -agent <id>). Per riportarlo serve un nuovo token. Dopo la revoca, il fbagent (dalla versione 3.1.0) lascia il cluster da solo: arresta i suoi nodi ed elimina i dati del cluster. Lo stesso si fa su un host di nodo con il comando fbagent --cluster-leave. Sull’host di RCM viene rifiutato.

Installazione manuale: aggiungere un nodo a RCM

  1. Impostazioni → RCM, la tabella Nodi connessi.
  2. Fai clic su Aggiungi nodo. Compila node_id, url (https://<indirizzo>:7051), il ruolo, host (etichetta dell’istanza di Firebird), server (solo per il raggruppamento a schermo).
  3. Fai clic su Valida nella riga del nodo: RCM controllerà la connessione e i permessi.
  4. Fai clic su Salva. RCM scriverà rcm.json e conserverà il file vecchio come rcm.json.<ora UTC>.bak (gli ultimi 20).
  5. Riavvia RCM. Fino al riavvio resta in vigore la configurazione vecchia; la pagina mostra quali campi attendono un riavvio.
Impostazioni → RCM
Impostazioni → RCM
Command
sudo systemctl restart hqbirdrcm

Si può fare anche senza l’interfaccia: modifica rcm.json e riavvia RCM.

Installazione manuale: collegare master e replica

Il collegamento deve essere registrato da entrambi i lati:

  1. Impostazioni → Nodi, seleziona il nodo master.
  2. Nella sezione Partner, fai clic su Aggiungi partner: il node_id della replica, il suo url, la compressione (zstd).
  3. Fai clic su Salva. RCM mostrerà l’elenco delle modifiche e chiederà conferma. La modifica di peers ha effetto subito.
  4. Ripeti per il nodo replica: il suo partner è il master.
Sezione Partner del nodo master
Sezione Partner del nodo master

Se il partner non è registrato da uno dei lati, RCM non offrirà quel nodo replica durante l’inizializzazione del database.

2.4. Impostazioni del nodo

Impostazioni → Nodi mostra le impostazioni di node.json che il nodo consente di modificare da RCM. Si salvano solo i campi modificati, dopo una finestra che elenca le modifiche.

Impostazioni → Nodi: selezione di un nodo
Impostazioni → Nodi: selezione di un nodo
Impostazioni dei database del nodo con i contrassegni «dopo l'analisi»
Impostazioni dei database del nodo con i contrassegni «dopo l'analisi»

Ogni riga indica quando la modifica avrà effetto:

Quando Quali impostazioni
Subito channel_a_mbps, channel_a_burst_mbps, windows.restart_window, peers; da HQbird 2027.2.24, impostazioni del controllo dei dati (limits.data_check_*); da HQbird 2027.2.31, advertise_addr
Dopo il riavvio del nodo gli altri limiti, windows.transfer_window; la pagina li mostra su una riga a parte finché il nodo non viene riavviato
Dopo l’analisi databases.*, exclude_filter; se replication.conf è cambiato, serve un riavvio di Firebird (capitolo 3.5)

Sola lettura (si modificano in node.json sull’host del nodo): firebird (compresi la password e auto_restart), rcm, tls, segments, l’indirizzo listen_addr.

Impostazioni principali:

Impostazione Predefinito Significato
windows.restart_window master 22:00-05:00, replica: sempre quando il nodo può riavviare Firebird; il Firebird master non si riavvia mai da solo
windows.transfer_window 23:00-05:00 finestra in cui l’inizializzazione procede alla velocità reinit_window_mbps
limits.channel_a_mbps 50 velocità di trasferimento dei segmenti, MB/s (channel_a_burst_mbps: picco breve, 200)
limits.reinit_window_mbps 100 velocità di inizializzazione dentro la finestra di trasferimento, MB/s
limits.reinit_day_disk_fraction 0.5 frazione della velocità del disco misurata per l’inizializzazione fuori dalla finestra
limits.retention_days 2 per quanti giorni conservare i segmenti inviati nell’archivio del master
limits.free_space_floor_gb 1 spazio libero minimo, GB; al di sotto, la replica non accetta segmenti
limits.max_concurrent_reinits 1 quante inizializzazioni il nodo esegue contemporaneamente

I dettagli su velocità e conservazione dell’archivio sono nei capitoli 5 e 7.

firebird.auto_restart (solo in node.json) determina se un nodo replica può riavviare Firebird da solo:

Valore Comportamento
auto (predefinito) può, se questo Firebird non serve database master
never mai
always sempre, anche se questo Firebird ospita database master

Tramite HQCenter Admin. Il windows.transfer_window del nodo fbagent si usa anche come finestra per riavviare il servizio del nodo stesso quando il cluster cambia. Se la finestra non è impostata in node.json, fbagent riavvia subito il servizio.

2.5. Più istanze di HQbird su un host

fbagent riavvia i servizi elencati in firebird.update.services della sua configurazione. Un elenco vuoto significa tutti i servizi HQbird dell’host. Lascia nell’elenco solo il servizio della tua istanza. Il nodo non vede questa impostazione e scrive un avviso fbagent_shared nel log se fbagent conosce più di un’istanza.

2.6. Password di SYSDBA

Il nodo si connette a Firebird con l’utente e la password di firebird.user e firebird.password in node.json. fbagent conserva una propria copia della password. Se hai cambiato la password di SYSDBA:

  1. Correggi firebird.password nel node.json di ogni nodo di questa istanza (master e replica).
  2. Correggi la password nella configurazione di fbagent e ricaricala (vedi la documentazione di fbagent).
  3. Riavvia i servizi del nodo.

Altrimenti le pagine di pubblicazione e di verifica di RCM mostreranno un errore di accesso (SQLSTATE 28000).

2.7. Utenti di RCM e audit

  • Gli utenti sono nel file rcm-data/users.json (capitolo 1.5). Senza ruolo, un utente ha tutti i diritti; il ruolo viewer (da HQbird 2027.2.31) è sola visualizzazione.
  • Una sessione dura 12 ore dopo l’ultima azione.
  • Dopo 10 accessi non riusciti in 5 minuti, l’accesso di quell’utente e di quell’indirizzo viene bloccato temporaneamente. Un accesso riuscito azzera il contatore.
  • Il registro di audit è il file rcm-data/audit.jsonl: una riga JSON per ogni modifica, accesso e uscita. Non c’è un registro di audit nell’interfaccia.
  • La pagina Comandi mostra l’autore di ogni comando.

2.8. Licenza

Una volta al minuto, il nodo master legge la licenza fbagent del proprio host. Se non c’è licenza (il periodo di prova è finito, la licenza è scaduta o non è valida), il nodo smette di inviare i segmenti di tutti i database del master. Firebird e i database continuano a funzionare, ma le repliche smettono di ricevere le modifiche.

Che cosa vedi in RCM:

  • il master è rosso (NEEDS_ATTENTION), con il contrassegno «nessuna licenza: invio fermato»;
  • non c’è il pulsante Riprendi: solo la licenza toglie la pausa;
  • sulla replica: «non riceve da …: il master non ha licenza»;
  • nella tabella Nodi, un contrassegno «nessuna licenza»; in Impostazioni → Nodi, il blocco della licenza di fbagent;
  • gli avvisi license_paused e license_pause_archive_released;
  • l’inizializzazione è vietata (license_paused).
Blocco della licenza di fbagent in Impostazioni → Nodi
Blocco della licenza di fbagent in Impostazioni → Nodi

Installa la licenza in fbagent. Il nodo toglie la pausa da solo entro un minuto. Il master conserva l’archivio per le repliche per limits.retention_days (2 giorni per impostazione predefinita) dall’inizio della pausa. Se installi la licenza più tardi, le repliche dovranno essere inizializzate di nuovo.

Cluster tramite RCM, senza HQCenter Admin. Una licenza mobile senza HQCenter Admin smette di funzionare dopo online_check_days più i giorni di tolleranza. Ogni fbagent del cluster ha bisogno di una licenza vincolata (fbagent --license-request, poi fbagent --license-install, capitolo 1.3, «Licenza»). Dopo il periodo di prova, fbagent non aggiungerà un nuovo nodo né RCM senza la funzione cluster nella licenza; non vieta mai gli aggiornamenti. Per HQbird 2.5/3.0, la data replconf_valid_till in RCM non può essere successiva alla fine della licenza più i giorni di tolleranza sui nodi fbagent (errore replconf_after_license).

2.9. Come controllare

  • Panoramica: tutti i nodi sono presenti e raggruppati per server.

    Panoramica del cluster
    Panoramica del cluster
  • Impostazioni → Nodi: il master ha una replica in Partner, e la replica ha il master.

  • Impostazioni → RCM: il pulsante Controlla nella riga di ogni nodo riesce.

  • Rapporto del cluster in un solo file:

    Command
    ./hqbirdrcm report -o report.json

2.10 Errori comuni

Che cosa vedi Causa Che cosa fare
La modifica dei partner in RCM viene rifiutata (409 cluster_managed) o si perde dopo il riavvio del nodo il nodo è stato installato tramite HQCenter Admin o tramite RCM cambia i collegamenti nella descrizione del cluster (2.2, 2.3)
seats_exceeded al salvataggio del cluster in RCM nodi su un quarto host non più di 3 host con nodi
Impostazioni → RCM: rcm_config_read_only cluster tramite RCM su Linux: rcm.json appartiene a fbagent modifica rcm.json come utente fbagent e riavvia RCM
Revoca dell’agente non funziona (agent_has_members) fbagent ha dei membri prima elimina i membri e salva
Il nodo replica non viene offerto durante l’inizializzazione il partner non è registrato da uno dei lati aggiungi il partner da entrambi i lati (2.3)
Una modifica in Impostazioni → RCM non ha effetto RCM non è stato riavviato riavvia RCM
422 al salvataggio del cluster in HQCenter Admin un errore nel documento correggilo secondo l’elenco errors, controlla tramite validate
409 al salvataggio del cluster il cluster è stato modificato da qualcun altro rileggi il cluster e riprova
Un nuovo membro del cluster di HQCenter Admin non riceve un certificato approvazione manuale sull’host di RCM fbagent --cluster-ca-approve <id>
Errore SQLSTATE 28000 nelle pagine di pubblicazione la password di SYSDBA è stata cambiata 2.6

3. Aggiungere un database al master

In questo capitolo il database master passa sotto il controllo del nodo. Il nodo lo registra in replication.conf e crea le cartelle dei segmenti. Dopo il riavvio di Firebird il database è pronto per la replica.

Creare la replica sono i passi successivi (pubblicazione, inizializzazione). Sono descritti nei capitoli 4–6.

I nomi dei pulsanti sono dati secondo l’interfaccia russa di RCM, con quelli inglesi tra parentesi.

3.1. Come un nodo scopre i database

Il nodo master cerca i database in una sola cartella, la radice dei database (databases.root). Che cosa passa sotto gestione lo decidono delle regole:

Regola Campo Predefinito
Cartella dei database root non impostata
Cercare nelle sottocartelle recursive sì
Maschera di inclusione template *.fdb
Maschera di esclusione exclude_mask nessuna
Dimensione del file, MB min_size_mb, max_size_mb nessun limite (0)
Tabelle per il confronto dei dati sync_tables con HQbird 2027.2.24, tabelle della pubblicazione del database; se non ce ne sono, RDB$FIELDS; nel 2027.5.7, RDB$FIELDS
Elenco di inclusione include_paths vuoto (modalità modello)
Elenco di esclusione exclude_paths vuoto

Il percorso root è un percorso sull’host del nodo, non sull’host di RCM. Il nodo applica prima la maschera di inclusione, poi quella di esclusione, poi la dimensione.

Le regole sono le stesse per tutto il nodo. Anche l’elenco sync_tables è condiviso: il controllo (capitolo 5.10) cerca ogni tabella dell’elenco in ogni database del nodo che non ha un proprio elenco.

Tabelle per il confronto, con HQbird 2027.2.24. Ogni database può avere un proprio elenco (Tabelle di tracciamento della sincronizzazione). Il nodo lo memorizza in databases.sync_tables_by_db. Il controllo prende il primo elenco impostato:

  1. l’elenco proprio del database;
  2. l’elenco condiviso sync_tables del nodo;
  3. le tabelle della pubblicazione del database;
  4. RDB$FIELDS.

Un elenco condiviso salvato prima ha la precedenza sulla pubblicazione: un database senza elenco proprio lo usa. La pagina del database del master mostra quale elenco è in vigore (3.3).

Una tabella assente sia dal database primario sia dalla replica riceve lo stato «non nel database» (absent): non viene confrontata, e il controllo non mostrerà «Non OK» per causa sua. Una tabella che manca solo da un lato è una discrepanza.

RCM e nodo 2027.5.7. C’è un solo elenco per tutto il nodo (sync_tables); senza elenco il controllo usa RDB$FIELDS. Una tabella mancante è un errore, e il controllo del database mostrerà «Non OK».

Tutte le regole sono memorizzate nel node.json del nodo. Il nodo le applica a ogni analisi.

Modalità modello e modalità elenco:

  • Modalità modello (elenco di inclusione vuoto): il nodo prende tutti i file che corrispondono alla maschera, tranne quelli esclusi. Un file nuovo nella cartella verrà raccolto dal nodo automaticamente all’analisi successiva.
  • Modalità elenco (elenco di inclusione non vuoto): il nodo prende solo i file dell’elenco. Un file nuovo non passerà sotto gestione automaticamente: va aggiunto.

Scegli la modalità elenco se la cartella contiene copie di database, database di prova o altri file che non vanno replicati.

3.2. Prima di iniziare: controllare i permessi

L’utente con cui vengono eseguiti Firebird e il nodo (firebird su Linux, LocalSystem su Windows) deve avere permessi di lettura e scrittura su:

  • la cartella radice dei database e i file dei database;
  • replication.conf e la sua cartella (il nodo sostituisce il file tramite un file temporaneo);
  • le cartelle dei segmenti <database>.ReplLog e <database>.LogArch (il nodo le crea da solo).

RCM controlla i permessi prima della registrazione (preflight). Se il controllo fallisce, il comando termina con l’errore preflight failed on <node> e un elenco di percorsi.

Controllo sull’host del nodo (Linux):

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

3.3. Pagina di iscrizione dei database

Iscrizione dei database: modulo e anteprima
Iscrizione dei database: modulo e anteprima
  1. Apri la pagina di iscrizione del nodo master. Il collegamento è in due posti:

    • Database → tabella Nodi → colonna delle azioni → Iscrivi;
    • Panoramica → scheda del nodo master → Iscrivi i database.

    Un nodo replica non ha questa pagina.

  2. Il modulo mostra le regole attuali del nodo (il nodo le ha inviate da solo). Se il nodo non risponde, i pulsanti di anteprima e di iscrizione sono disattivati: senza le regole attuali azzererebbero gli elenchi di inclusione e di esclusione.

  3. Compila o correggi i campi: Percorso della cartella su questo server, ricorsivo, maschere, Filtro dimensione, Tabelle di tracciamento della sincronizzazione.

    Il campo Tabelle di tracciamento della sincronizzazione:

    • con HQbird 2027.2.24 e successivi, l’elenco è per database che questa azione iscriverà. Campo vuoto: il database usa le tabelle della propria pubblicazione. L’iscrizione non cambia l’elenco condiviso del nodo (sync_tables). Se esiste, il modulo lo dice: un database senza elenco proprio lo usa al posto della pubblicazione. L’elenco di un database già gestito si imposta nella sua pagina: Database → database master → blocco Tabelle di tracciamento della sincronizzazione. Il blocco mostra quale elenco è in vigore. Un campo vuoto toglie l’elenco proprio del database;
    • in RCM e nel nodo 2027.5.7, un solo elenco per tutti i database del nodo (sync_tables).
  4. Fai clic su Anteprima. Il nodo mostrerà tutti i file che corrispondono alla maschera di inclusione. Non cambia nulla.

  5. Controlla l’elenco. Ogni file ha una casella:

    • selezionata: il file sarà gestito;
    • selezionata, bloccata, contrassegnata già gestito: il database è già iscritto;
    • bloccata con un motivo: il file è escluso da maschera, dimensione o elenco di esclusione. Per prenderlo, cambia la regola.
  6. Seleziona i database necessari e fai clic su Iscrivi i selezionati. RCM chiederà conferma e mostrerà il numero di file.

Conferma dell'iscrizione
Conferma dell'iscrizione

Che cosa fa questo pulsante:

  • in modalità modello, i file senza casella vengono aggiunti all’elenco di esclusione e i file con casella ne vengono tolti;
  • in modalità elenco, i file con casella vengono aggiunti all’elenco di inclusione.

Il pulsante aggiunge database a quelli già sotto gestione. Non cambia le righe bloccate. 7. Il pulsante Iscrivi applica il modulo senza cambiare gli elenchi. 8. Aspetta il messaggio di completamento e il numero di database aggiunti. Se non c’è risposta per molto tempo, controlla il risultato nella pagina Comandi.

Con HQbird 2027.2.24 e successivi il messaggio è «Iscritti: N». Se il Firebird del master va riavviato, RCM dice quale pulsante premere (di solito Riavvia il Firebird del master nella riga del database) e fornisce un collegamento ai database master. RCM 2027.5.7 può dire «Nessun nuovo database adatto», anche se dei database sono stati aggiunti: controlla la pagina Database.

Risultato dell'iscrizione
Risultato dell'iscrizione

Se dopo l’iscrizione non è stato trovato nessun database, ma il nodo ne aveva già, il nodo rifiuta (409) e restituisce le regole vecchie. Così un errore nel percorso non disattiva la replica di tutti i database.

La stessa cosa dalla riga di comando

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

Nota: il comando invia solo i campi dei suoi parametri. Il nodo azzererà le altre regole (maschere, dimensioni, elenchi di inclusione e di esclusione, sync_tables). Il comando non ha parametri per queste regole. Prima di eseguire il comando, controlla le regole attuali (hqbirdrcm getconfig -node node-a). Se sono impostate, usa la pagina di iscrizione.

3.4. Che cosa succede dopo la registrazione

  1. Il nodo scrive le regole in node.json.
  2. Il nodo analizza la cartella (scansync).
  3. Per ogni database trovato, il nodo scrive un blocco nella propria area di replication.conf (tra le righe # BEGIN managed-by:node-a role:master e # END …) e crea le cartelle <database>.ReplLog e <database>.LogArch. Il nodo non modifica il testo fuori dalla propria area.
  4. Prima di fare una modifica, il nodo salva una copia del file: replication_YYYYMMDD_hhmmss_NNN.conf.
  5. Se replication.conf è cambiato, i database passano allo stato PENDING_RESTART: Firebird leggerà il file nuovo solo dopo un riavvio. Nella tabella Nodi questo compare nella colonna Riavvio in attesa.
La colonna «Riavvio in attesa» nella tabella «Nodi»
La colonna «Riavvio in attesa» nella tabella «Nodi»

Stati di un database nuovo:

Stato Gruppo in RCM Significato
UNCONFIGURED In attesa database trovato, configurazione non ancora scritta
PENDING_RESTART In attesa configurazione scritta, serve il riavvio di Firebird
CONFIGURED In attesa Firebird riavviato, database pronto per la pubblicazione e l’inizializzazione

3.5. Riavviare il Firebird del master

Il nodo master non riavvia mai Firebird da solo. Nemmeno RCM. Riavviare il master è una decisione dell’operatore: un riavvio interrompe tutte le connessioni a tutti i database di quell’istanza di Firebird.

Scegli un momento di basso carico e fai clic su uno dei pulsanti:

  • Riavvia il Firebird del master, nella pagina Database, nella riga del master del database che attende un riavvio;
  • lo stesso pulsante nella finestra Inizializza, capitolo 5;
  • Riavvia Firebird, nella pagina del database.

RCM chiederà conferma. Mostra il nome del nodo e un avviso: Firebird si riavvierà subito, senza finestra di riavvio, e tutte le connessioni verranno interrotte.

Conferma del riavvio del Firebird del master
Conferma del riavvio del Firebird del master

La stessa cosa dalla riga di comando

Command
hqbirdrcm restartfirebird -node node-a

Anche questo comando riavvia subito, senza finestra di riavvio.

Come il nodo riavvia Firebird:

  1. Controlla che fbagent risponda e gestisca la stessa istanza (identificatore, porta, nome del servizio da node.json). Se un valore non coincide, il nodo rifiuta.
  2. Chiede a fbagent di riavviare Firebird.
  3. Aspetta che Firebird risponda sulla propria porta.
  4. Sposta i database da PENDING_RESTART a CONFIGURED.

Diverse istanze di HQbird su un host. fbagent riavvia i servizi elencati in firebird.update.services della sua configurazione. Un elenco vuoto significa tutti i servizi HQbird dell’host. Se sull’host ci sono due istanze di HQbird, lascia nell’elenco solo il servizio della tua istanza. Altrimenti, il riavvio di un nodo arresterà anche l’altra istanza.

Su Windows. Se replication.log è cresciuto fino a log_portion_mb o più, il riavvio procede così: arrestare Firebird → archiviare il log → avviare.

3.6. Un database già replicato a mano

Se la replica di un database è già configurata a mano (un proprio blocco in replication.conf, pubblicazione attivata, segmenti in circolo), si può metterlo sotto gestione senza reinizializzare la replica. Per questo esiste la modalità detect_existing (solo master).

  1. Esegui un’anteprima:

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

    Nella risposta, taken_over elenca i database che verranno migrati. Aggiungi -verbose per vedere i database saltati con il motivo.

  2. Se l’elenco è corretto, esegui il comando senza -dry-run.

Il nodo migra un blocco solo se:

  • le cartelle dei segmenti si chiamano esattamente <database>.ReplLog e <database>.LogArch;
  • nell’archivio esistono già dei segmenti;
  • la pubblicazione è attivata nel database.

Il nodo non migra un blocco con percorsi diversi e lo segnala come «trovato ma non supportato».

Dopo la migrazione i database ricevono PENDING_RESTART, anche se le impostazioni di replica non cambiano: cambia solo la posizione del blocco nel file. Riavvia Firebird in una finestra di manutenzione.

3.7. Come verificare

  • Database: il database è visibile nella riga del nodo master, stato CONFIGURED (dopo il riavvio).

  • Accanto al database può esserci un’icona pubblicazione disattivata: la pubblicazione non è ancora attivata. È normale; la pubblicazione è il passo successivo (capitolo 6).

    Nuovo database nella riga del master
    Nuovo database nella riga del master
  • Sull’host del nodo: il blocco del database è presente in replication.conf dentro l’area managed-by:node-a, e accanto al database ci sono le cartelle .ReplLog e .LogArch.

3.8. Togliere un database dalla gestione

Il modo abituale è il pulsante. Nella pagina Database, seleziona i database, scegli l’azione di massa Togli dalla gestione e fai clic su Applica ai selezionati. RCM:

  1. aggiunge i file all’elenco di esclusione del nodo;
  2. analizza la cartella una volta: i blocchi del database vengono tolti da replication.conf;
  3. elimina i record del database nel nodo.

I file del database e le cartelle dei segmenti restano sul disco. Firebird non viene riavviato. Firebird continua a scrivere i segmenti del database fino al riavvio successivo; RCM dirà se serve un riavvio.

RCM rifiuterà (has_replicas) un database master che ha una replica viva: altrimenti la replica si fermerebbe in silenzio. Prima trasforma la replica in un database normale oppure rimuovila (capitolo 8).

Non eliminare a mano il blocco del database da replication.conf: all’analisi successiva il nodo lo riscriverà.

Se il file del database è sparito o è stato escluso da una regola. Allora il database riceve lo stato ORPHANED (il gruppo Orfani). Il nodo conserva il suo record e l’archivio dei segmenti: un database mancante è più spesso un errore che una decisione. Se il file torna, il database funziona di nuovo e l’avviso viene cancellato. Per eliminare in modo permanente un tale database, esegui due passi in questo ordine:

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>

Dopo forgetdatabase, il comando cleanuparchive non troverà più il database. Entrambi i comandi funzionano solo per un database nello stato ORPHANED e non toccano il file del database.

Attenzione. Dopo aver promosso una replica a master (capitolo 8), non eseguire cleanuparchive -orphaned per il record vecchio: il nuovo master usa la stessa cartella .LogArch, e il comando cancellerà il suo archivio di lavoro.

3.9. Cambiare la radice dei database

La registrazione con un percorso diverso è consentita. Il nodo:

  • aggiunge i database della cartella nuova;
  • sposta in ORPHANED i database della cartella vecchia che non sono nella nuova (notifica orphaned_database) e conserva i loro archivi.

Se hai scelto la cartella sbagliata, registra di nuovo la cartella corretta. Un database con lo stesso percorso completo continuerà a funzionare con lo stesso db_id. Un database a un percorso diverso è un database nuovo (nuovo db_id); la sua replica va inizializzata di nuovo.

3.10. Errori comuni

Che cosa vedi Causa Che cosa fare
preflight failed on node-a nessun permesso sulle cartelle correggi i permessi, riprova (3.2)
409 scan_would_empty_region la cartella nuova non contiene database, ma il nodo ne aveva controlla il percorso e la maschera
L’anteprima è vuota la maschera non corrisponde oppure la cartella è sbagliata controlla il percorso, la maschera, «ricorsivo»
I pulsanti sono disattivati, «Impossibile leggere la configurazione del nodo» il nodo non risponde controlla il servizio del nodo e la rete (capitolo 1)
Il database resta a lungo in PENDING_RESTART il master non riavvia Firebird da solo riavvia Firebird (3.5)
Riavvio rifiutato a causa di fbagent fbagent non è in esecuzione oppure i suoi dati non coincidono con node.json capitolo 1, controllo di fbagent
Il file nuovo non è comparso il nodo è in modalità elenco aggiungi il file tramite «Iscrivi i selezionati»

4. Come rendere un database una replica: passaggi e posizione su disco

Questo capitolo copre l’intero percorso di un database, dal primario a una replica funzionante, più il calcolo dello spazio su disco. L’inizializzazione vera e propria è descritta in dettaglio nel capitolo 5.

4.1. La regola principale

Un database compare su una replica solo tramite l’inizializzazione dal master (reinit): il nodo master stesso trasferisce una copia tramite nbackup.

Non fare una copia a mano:

  • gbak crea un nuovo GUID del database e azzera il numero di segmento. Il collegamento master-replica si rompe.
  • Una copia di file di un database in esecuzione non è coerente, e RCM vedrà due database con lo stesso GUID (duplicate_guid) e vieterà l’inizializzazione.

Una replica già in funzione, configurata a mano, si può prendere sotto gestione senza una copia nuova: vedi 4.6.

4.2. Fasi

N. Fase Dove Stato del database master dopo la fase
1 Registrazione del database sul master capitolo 3.3 PENDING_RESTART
2 Riavvio del Firebird del master capitolo 3.5 CONFIGURED
3 Sincronizzazione della pubblicazione capitolo 6 CONFIGURED, pubblicazione attivata
4 Preparazione della replica: cartella, permessi, versione di Firebird 4.3 —
5 Controllo dello spazio libero sul master e sulla replica 4.4 —
6 Inizializzazione capitolo 5 SEEDING → IN_SYNC
7 Riavvio del Firebird della replica (se serve) capitolo 5.6 la replica inizia ad applicare i segmenti
8 Verifica dei dati capitolo 5.10 —

La fase 3 è obbligatoria per Firebird 4/5. Senza pubblicazione, il Firebird del master non scrive le modifiche delle tabelle nei segmenti, e la replica resta indietro rispetto al master in silenzio. Nella pagina Database un tale database è contrassegnato dall’icona pubblicazione disattivata. Fai clic su Sincronizza la pubblicazione prima dell’inizializzazione.

Da HQbird 2027.2.24, la finestra Inizializza avvisa di questo e offre un pulsante Sincronizza la pubblicazione e inizializza, mentre il nodo master rifiuta l’inizializzazione con l’errore publication_off (capitolo 5.1). RCM e il nodo 2027.5.7 non controllano la pubblicazione.

HQbird 2.5/3.0. Non ci sono pubblicazioni, quindi la fase 3 viene saltata. L’insieme delle tabelle è definito dai filtri del plugin replconf (capitolo 6).

Stati del database:

Stato Gruppo in RCM Significato
CONFIGURED In attesa Firebird ha letto le impostazioni, non c’è ancora una replica
PUBLISHING In attesa la sincronizzazione della pubblicazione è in corso
SEEDING In attesa l’inizializzazione è in corso
IN_SYNC Ok la replica ha ricevuto tutti i segmenti
LAGGING In attesa la replica è in ritardo, i segmenti sono in coda
NEEDS_REINIT Errore la replica va inizializzata di nuovo
FAILED Errore l’ultima inizializzazione è fallita

4.3. Preparazione della replica

Cartella del database della replica

Il nodo replica colloca ogni database nella propria cartella databases.root, al percorso:

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

Esempio: master node-a con radice /databases/master e database /databases/master/sales/employee.fdb. Sulla replica node-b con radice /databases/replica, il database sarà qui:

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

Così i database con gli stessi nomi da master diversi non si scontrano.

Nessuno crea la cartella radice automaticamente: né il programma di installazione, né HQCenter Admin, né il nodo all’avvio. Creala in uno di questi modi:

  • nella finestra Inizializza: il campo Cartella della replica, il pulsante Crea cartella. Il pulsante è visibile solo quando la cartella non esiste. Con HQbird 2027.2.24, se il nodo replica non ha ancora un databases.root, il campo contiene già /databases/replica/<id del nodo replica>. Per una replica su Windows il campo è vuoto: inserisci una cartella con la lettera dell’unità. Ogni nodo replica sullo stesso host ha bisogno della propria cartella. La cartella la crea il nodo replica: proprietario firebird (o l’utente del servizio del nodo), permessi 2770. Se il nodo non può crearla, la finestra mostrerà il comando per l’host della replica. Se indichi un’altra cartella, RCM la scriverà in databases.root del nodo replica prima dell’inizializzazione;

  • a mano sull’host della replica (Linux):

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

    Il bit setgid (2770) serve perché tutti i file all’interno ricevano il gruppo di Firebird.

Puoi cambiare la radice della replica solo finché non ha database: altrimenti i database vecchi finiranno fuori dall’analisi. Per mettere un solo database in un’altra posizione, usa Sposta nella pagina del database.

Permessi

Il nodo replica e Firebird devono poter scrivere nella radice dei database. Il nodo controlla che i file collocati ricevano il gruppo della cartella. Se non può, rifiuta con ownership_unfixable e un testo su come correggere (di solito il servizio del nodo viene eseguito con Group=root).

Con HQbird 2027.2.24, la finestra Inizializza mostra anche una cartella che esiste ma in cui il servizio del nodo non può scrivere: il testo del nodo con il comando di correzione e un pulsante Controlla di nuovo. RCM 2027.5.7 in questo caso dice «La cartella esiste»: controlla tu i permessi (hqbirdrcm checkpermissions -node <replica> -root <folder>).

Versione di Firebird

La versione principale di Firebird sulla replica deve coincidere con il master (5.0 → 5.0, 4.0 → 4.0). Altrimenti la replica rifiuterà prima di qualsiasi trasferimento di dati: incompatible_engine.

Connettività

Il nodo replica deve essere un partner del master, e il master deve essere un partner della replica (capitolo 2). Altrimenti RCM non offrirà questo nodo nella finestra Inizializza.

4.4. Quanto spazio serve

In breve

Dove Che cosa Quanto
Master, volume del database libero prima dell’inizializzazione ≥ 105 % della dimensione del database
Replica, volume della cartella del database libero prima dell’inizializzazione ≥ 105 % della dimensione del database, con HQbird 2027.2.24, più free_space_floor_gb (più il file vecchio, se la replica esisteva già; con la casella Elimina la replica vecchia, senza di esso)
Master, <database>.ReplLog segmenti di lavoro di Firebird fino a 64 segmenti × dimensione del segmento (16 MB per impostazione predefinita) ≈ 1 GB per database
Master, <database>.LogArch archivio dei segmenti per le repliche modifiche su retention_days (per impostazione predefinita 2 giorni) + ciò che le repliche non hanno ancora confermato
Replica, <database>.Incoming coda dei segmenti da applicare fino a 256 segmenti × 16 MB ≈ 4 GB per database nel caso peggiore
Replica, intero volume margine almeno free_space_floor_gb (per impostazione predefinita 1 GB)

Controllo dello spazio prima dell’inizializzazione

L’inizializzazione controlla lo spazio due volte e solo prima di bloccare il database:

  1. RCM, dalle ultime statistiche del nodo, prima di inviare il comando. Se lo spazio è chiaramente insufficiente, RCM restituisce subito l’errore 507.
  2. Nodo master, una misura dal vivo sul proprio volume, poi una richiesta alla replica perché misuri il suo. Se manca da almeno un lato, l’inizializzazione termina al passo SPACE CHECK con l’errore insufficient disk space on master oppure … on replica.

Il requisito su entrambi i lati è il 105 % della dimensione del database master.

Con HQbird 2027.2.24 il nodo replica calcola così:

  • gli serve il 105 % della dimensione del database più il free_space_floor_gb della replica (7.3): dopo l’inizializzazione sul volume resta una riserva per i segmenti;
  • i resti delle inizializzazioni precedenti (<database>.hqcluster-part, <database>.new) contano come spazio libero: il nodo li elimina prima della copia nuova;
  • il testo dell’errore nomina tutti i numeri. Nomina anche i file <database>.pre-reinit-*.fdb e <database>.failed-seed-*.fdb con la loro dimensione. Il nodo non li elimina mai: eliminali tu se non servono.

force (forzato) salta solo il controllo in RCM. Il controllo del nodo non si può aggirare: protegge il nodo dall’esaurimento del disco a metà della copia. Se lo spazio è insufficiente solo a causa della copia vecchia della replica, RCM 2027.2.24 nell’errore 507 nomina la casella Elimina la replica vecchia invece di force. Per questo, entrambi i nodi devono essere HQbird 2027.2.24 o successivi. Altrimenti l’errore nomina il nodo da aggiornare, e force.

Perché così tanto

Master. Durante la copia il database è bloccato da nbackup -L. Tutte le modifiche vengono scritte nel file <database>.delta accanto al database. La dimensione di .delta dipende dal carico di scrittura durante la copia. Con carico alto e trasferimento lento può crescere parecchio: tieni d’occhio lo spazio durante la prima inizializzazione.

Replica. La copia viene scritta direttamente nel file <database>.hqcluster-part accanto alla posizione del database. Il nodo riserva in anticipo la dimensione intera. Il file viene poi controllato, riparato (nbackup -FIXUP -SEQUENCE) e rinominato al suo posto. Non serve una seconda copia: la dimensione del database serve una volta, sul volume del database.

Se la replica esisteva già (inizializzazione ripetuta), il file vecchio resta sul disco fino all’ultimo passo. Questo significa che il file vecchio e la copia nuova servono sul volume nello stesso momento. Lo spazio libero si calcola senza il file vecchio, quindi il requisito è lo stesso: il 105 % della dimensione del database libero.

Elimina la replica vecchia (con HQbird 2027.2.24). Se sul volume della replica non c’è spazio per la copia nuova accanto a quella vecchia, seleziona questa casella nella finestra di inizializzazione (capitolo 5.1). Allora il nodo replica elimina la copia vecchia e i suoi segmenti in arrivo (.Incoming) prima del trasferimento, e il volume basta per il 105 % della dimensione del database più free_space_floor_gb. Il nodo elimina la copia solo se tutte le condizioni sono vere:

  • senza l’eliminazione non c’è abbastanza spazio, e con l’eliminazione ce n’è abbastanza;
  • è una copia installata dall’inizializzazione di questo nodo: l’intestazione è leggibile, la modalità è replica in sola lettura;
  • il database non è stato reso normale (non c’è il file <database>.hqcluster-normal.json, capitolo 8);
  • overwrite_non_replica non è impostato (5.9).

Altrimenti il nodo non elimina nulla e rifiuta con il motivo nel testo. Per eliminare, il nodo arresta il Firebird della replica per la durata dell’eliminazione (5.6).

La casella è disattivata per impostazione predefinita. Rischio: mentre il trasferimento è in corso, non c’è una copia del database sulla replica. Se il database ha una sola replica, il master resta non protetto per tutto il tempo. Finché non c’è la copia nuova, il database sulla replica è nello stato NEEDS_REINIT (non FAILED e non ORPHANED), e la replica emette l’avviso replica_removed_for_reinit (avviso). Quando la copia nuova è al suo posto, l’avviso viene cancellato. Se l’inizializzazione fallisce dopo l’eliminazione, la coppia resta NEEDS_REINIT: avvia di nuovo l’inizializzazione (oppure la reinizializzazione automatica la avvierà, 5.8). Una nuova inizializzazione trasferisce il database dall’inizio.

Archivio del master (.LogArch). Il nodo conserva i segmenti inviati per retention_days giorni, così la replica può richiederli di nuovo. I segmenti che la replica non ha ancora applicato vengono conservati più a lungo. Se lo spazio è scarso, il nodo pulisce l’archivio a fasi:

  1. segmenti applicati da tutte le repliche più vecchi di retention_days;
  2. segmenti applicati più recenti (quando lo spazio è scarso);
  3. segmenti non applicati, solo come ultima risorsa. Allora la replica perde i segmenti di cui ha bisogno e riceve NEEDS_REINIT.

Se una replica non è disponibile a lungo, l’archivio cresce. Il suo volume è le modifiche del database nel periodo di fermo.

Esempio di calcolo

Database di 100 GB. Carico: 5 GB di segmenti al giorno. L’inizializzazione avviene di notte, la copia richiede 2 ore, durante le quali circa 2 GB finiscono in .delta.

Dove Calcolo Totale libero
Master, volume del database 105 GB per i controlli (include la crescita di .delta) + .ReplLog 1 GB + .LogArch 2 giorni × 5 GB = 10 GB ≥ 116 GB
Replica, database nuovo 105 GB + .Incoming fino a 4 GB + 1 GB di riserva ≥ 110 GB
Replica, inizializzazione ripetuta file vecchio di 100 GB già sul disco + 110 GB liberi volume ≥ 210 GB
Replica, inizializzazione ripetuta con la casella Elimina la replica vecchia (con HQbird 2027.2.24) file vecchio eliminato prima del trasferimento: 105 GB + .Incoming fino a 4 GB + 1 GB di riserva volume ≥ 110 GB

Aggiungi una riserva per la crescita del database e per il fermo della replica (l’archivio del master cresce di 5 GB per giorno di fermo).

Segmenti su un volume separato

Le cartelle .ReplLog, .LogArch e .Incoming si trovano per impostazione predefinita accanto al database. Si possono spostare su un altro volume: il parametro segments.storage in node.json (con mirror_hierarchy: true il nodo riproduce la struttura delle cartelle dei database). Allora l’archivio non toglie spazio ai database. Il controllo del 105 % si applica comunque al volume del database.

Dove guardare lo spazio

  • Database → Nodi e Panoramica: l’icona dello spazio libero del volume di databases.root. Giallo: meno del 20 %, rosso: meno del 10 %.

    Pagina Database: la colonna Disco nella tabella Nodi
    Pagina Database: la colonna Disco nella tabella Nodi
  • Rapporto del cluster: hqbirdrcm report.

4.5. Più repliche di un database

La seconda replica e le successive si creano allo stesso modo: Inizializza nella riga del master, selezionando un nodo replica libero.

  • Mentre una replica nuova viene inizializzata, il master non trasmette questo database nemmeno alle repliche già in funzione. Raggiungeranno il master al termine dell’inizializzazione. La finestra di conferma lo dice.
  • Un database: una inizializzazione alla volta, anche per repliche diverse.
  • Lo spazio sul master viene controllato separatamente per ogni inizializzazione.
Database master con due repliche
Database master con due repliche

4.6. Replica configurata a mano

Se una replica è già in funzione da un replication.conf scritto a mano, puoi prenderla sotto gestione e non copiare di nuovo il database:

  1. Master: registra i database con detect_existing (capitolo 3.6).
  2. Replica: Database → nodo replica → Prendi in carico, oppure hqbirdrcm takeover-replica. RCM troverà i blocchi della replica, abbinerà i file ai database master tramite GUID e mostrerà per ciascuno: in_sync, resumable o needs_reinit.
  3. Conferma le righe. Il nodo sposterà i blocchi nella propria area di replication.conf.
  4. Riavvia il Firebird della replica perché legga i blocchi spostati.
  5. Inizializza solo le righe needs_reinit: l’archivio del master non contiene più i segmenti richiesti da queste repliche.

4.7. Errori comuni

Che cosa vedi Causa Che cosa fare
insufficient disk space on master / on replica spazio insufficiente (4.4). In una reinizializzazione la copia vecchia occupa spazio fino alla fine (4.4) libera spazio, riprova. La seconda via sulla replica (da HQbird 2027.2.24) è la casella Elimina la replica vecchia (4.4, 5.1)
507 da RCM subito secondo le statistiche dello spazio, chiaramente non basta lo stesso. Se c’è spazio senza la copia vecchia, RCM 2027.2.24 nomina la casella Elimina la replica vecchia
incompatible_engine versioni principali di Firebird diverse aggiorna il Firebird della replica
Cartella mancante sul nodo replica radice non creata Crea cartella nella finestra di inizializzazione (4.3)
La cartella esiste, ma il servizio del nodo non può scriverci (da HQbird 2027.2.24) nessun permesso di scrittura esegui il comando della finestra, fai clic su Controlla di nuovo (4.3)
publication_off (da HQbird 2027.2.24) la pubblicazione del master è disattivata o non ha tabelle Sincronizza la pubblicazione e inizializza (5.1)
ownership_unfixable il servizio del nodo ha un gruppo estraneo correggi il gruppo del servizio come dice il testo dell’errore
duplicate_guid due database con lo stesso GUID (una copia di file) rimuovi la copia oppure dalle un GUID nuovo (nbackup -F)
Nodo replica assente dall’elenco Inizializza nessun collegamento nei partner capitolo 2
Replica IN_SYNC, ma i dati divergono la pubblicazione era disattivata sincronizza la pubblicazione, poi ripeti l’inizializzazione

5. Inizializzazione (reinit)

L’inizializzazione è il trasferimento di una copia del database master alla replica. Il primo trasferimento si chiama inizializzazione (il pulsante Inizializza); un trasferimento ripetuto è la reinizializzazione (il pulsante Reinizializza). Il meccanismo è lo stesso.

Prima di iniziare, completa i passi 1–5 del capitolo 4: il database è registrato, il Firebird del master è stato riavviato, la pubblicazione è attivata, la cartella della replica esiste e c’è spazio sufficiente. Quanto spazio serve sul master e sulla replica è descritto nel capitolo 4.4.

5.1. Come iniziare

Prima la pubblicazione. Registrare un database non include la pubblicazione. Senza pubblicazione, la replica non riceve modifiche. Prima dell’inizializzazione, esegui Sincronizza la pubblicazione (capitolo 6) oppure hqbirdrcm setpublication -node <master>.

  • Con HQbird 2027.2.24, la finestra di inizializzazione controlla la pubblicazione. Se è disattivata o non ha tabelle con chiave, la finestra mostra un avviso e un pulsante Sincronizza la pubblicazione e inizializza. RCM sincronizza la pubblicazione, aspetta che il comando finisca e avvia l’inizializzazione con la selezione della finestra.
  • Un nodo master 2027.2.24 rifiuta da solo tale inizializzazione (anche la prima) con l’errore publication_off ed emette la notifica master_publication_off (capitolo 6.1). Dopo il rifiuto, la cella del database ha di nuovo il pulsante Sincronizza la pubblicazione e inizializza.
  • Se l’operatore ha disattivato la pubblicazione (6.4) o ne ha tolto tutte le tabelle con chiave (6.3), la sincronizzazione lo conserva. RCM non avvia l’inizializzazione e fornisce un collegamento alla pagina Tabelle della pubblicazione.
  • RCM e il nodo 2027.5.7 non controllano la pubblicazione: l’inizializzazione riesce, il database mostra «OK» in RCM, ma la replica non riceve modifiche. Se la pubblicazione è stata attivata dopo l’inizializzazione, reinizializza il database.
La finestra «Reinizializzare il database?»
La finestra «Reinizializzare il database?»
  1. Apri Database.
  2. Nella riga del database master, nella colonna del nodo replica, fai clic su Inizializza. Il nodo replica è fissato dalla colonna: non si sceglie nella finestra. Per una coppia esistente, Reinizializza nella scheda espansa del master.
  3. Nella finestra (con HQbird 2027.2.24 il titolo per una coppia nuova è «Inizializzare il database?»; in RCM 2027.5.7, «Reinizializzare il database?» anche alla prima inizializzazione):
    • controlla la Cartella della replica. La finestra mostra se la cartella esiste. Se non esiste, fai clic su Crea cartella: il nodo replica la creerà (4.3). Se il nodo non può crearla, la finestra mostra il comando per l’host della replica. Con HQbird 2027.2.24 la finestra mostra anche una cartella in cui il servizio del nodo non può scrivere: il comando di correzione e un pulsante Controlla di nuovo;
    • seleziona il Metodo di reinizializzazione: Morbido (consigliato) o Standard (5.4). Con HQbird 2027.2.24, se l’archivio del master non ha ancora segmenti (di solito prima della prima inizializzazione), la finestra mostra un suggerimento: su un database occupato Standard è più veloce;
    • se il database master attende ancora un riavvio di Firebird, la finestra lo dirà e mostrerà un pulsante Riavvia il Firebird del master. Senza il riavvio il database non viene replicato;
    • Elimina la replica vecchia (con HQbird 2027.2.24, disattivata per impostazione predefinita) serve solo per una reinizializzazione quando il volume della replica non ha spazio per una copia nuova accanto a quella vecchia (4.4). La finestra mostra i numeri in anticipo: quanto serve, quanto è libero, quanto occupa la copia vecchia. Se c’è spazio senza la copia vecchia, la finestra chiede di selezionare la casella. La casella è inattiva se il nodo master o replica è una versione vecchia: la finestra indica quale nodo aggiornare. Finché la copia nuova non è pronta, la replica non ha una copia di questo database (4.4).
  4. Conferma. RCM indicherà che il database verrà bloccato sul master e copiato sulla replica.

L’avanzamento dell’inizializzazione è visibile nella scheda espansa del master nella pagina Database: passi e percentuali. Con HQbird 2027.2.24 l’avanzamento resta visibile anche dopo l’aggiornamento della pagina: alla prima inizializzazione, nella cella del nodo replica, e anche nella riga Avanzamento della reinizializzazione della pagina del database master. Il pulsante Inizializza è inattivo mentre il nodo master copia il database. Se RCM non segue questa inizializzazione (per esempio, è stata avviata dalla riga di comando del nodo), i passi sono presi dallo stato del nodo, senza percentuali. In RCM 2027.5.7, dopo l’aggiornamento della pagina, l’avanzamento della prima inizializzazione non è visibile: aspetta che il database master esca da SEEDING.

Passi dell'inizializzazione nella riga del master
Passi dell'inizializzazione nella riga del master

Ogni comando di RCM (inizializzazione, riavvio di Firebird, sincronizzazione della pubblicazione) è registrato nella pagina Comandi con il suo risultato.

La pagina «Comandi»
La pagina «Comandi»

La stessa cosa dalla riga di comando

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

Parametri: -mode smooth|standard (predefinito smooth), -hold=false (non trattenere l’archivio durante le transazioni lunghe), -allow-restart (5.6), -force (5.9).

-remove-old-replica (con HQbird 2027.2.24) è lo stesso della casella Elimina la replica vecchia. Solo per un database: -db e -to sono obbligatori; con -all il comando rifiuta. Se il nodo master o replica è una versione vecchia, RCM rifiuta con node_too_old e non invia nulla.

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

-all prova tutti i database e raccoglie gli errori invece di fermarsi al primo.

5.2. Passi

N. Passo (in RCM) Che cosa succede
1 SPACE CHECK controlla lo spazio sul master e sulla replica (capitolo 4.4); la replica controlla in anticipo di poter accettare il file
2 LOCKING nbackup -L: il file del database master viene congelato, le modifiche vanno in <database>.delta
3 COPYING TO NODE il file viene trasferito a parti: lettura → checksum → compressione → invio
4 UNLOCKING nbackup -N subito dopo il trasferimento: le modifiche di .delta tornano nel database
5 SEEDING sulla replica: verifica del checksum del file, nbackup -FIXUP -SEQUENCE, installazione del file, gfix -replica, scrittura del blocco in replication.conf
6 RESTARTING REPLICA riavvio del Firebird della replica, se serve (5.6)

Dopo il passo 6 il database riceve lo stato IN_SYNC. Il master continua a inviare i segmenti dal punto in cui finisce la copia.

Che cosa è importante sapere:

  • Il master funziona tutto il tempo. Gli utenti scrivono nel database, le modifiche vanno in .delta. Il blocco viene rilasciato subito dopo il trasferimento.
  • Le transazioni che hanno coinciso con il blocco non si perdono. Il nodo trova le transazioni aperte al momento di nbackup -L, e la replica le riproduce dai segmenti.
  • Il trasferimento continua dopo un’interruzione. Se la connessione o il nodo replica si è riavviato, il master continuerà dall’ultima parte ricevuta. Un trasferimento non finito viene conservato sulla replica per 24 ore (reinit_partial_keep_hours).
  • In caso di errore il nodo rilascia il blocco, elimina il file non finito sulla replica e mette il database in FAILED. Il tentativo successivo parte da uno stato noto.
  • Con la casella «Elimina la replica vecchia» (da HQbird 2027.2.24) la replica elimina la copia vecchia dopo il passo LOCKING, prima del trasferimento. Il passo COPYING TO NODE mostra in quel momento «rimozione della copia vecchia della replica per fare spazio». Un errore dopo l’eliminazione dà alla coppia NEEDS_REINIT invece di FAILED (capitolo 4.4).
  • Solo nbackup. gbak non si usa: cambia il GUID del database.

5.3. Effetto sul funzionamento

Che cosa Effetto
Utenti del master continuano a lavorare; durante la copia .delta cresce, dopo -N le modifiche vengono trasferite nel database
Altre repliche di questo database non ricevono i segmenti di questo database mentre l’inizializzazione è in corso; recuperano dopo
Altri database del master non sono interessati
Firebird della replica, database nuovo non viene arrestato; riavvio secondo 5.6
Firebird della replica, inizializzazione ripetuta viene arrestato mentre il file viene sostituito: tutti i database di questo Firebird non sono disponibili per qualche secondo
Firebird della replica, il nodo elimina la copia vecchia (casella «Elimina la replica vecchia», da HQbird 2027.2.24) viene arrestato prima, mentre dura l’eliminazione, prima del trasferimento. Il nodo installa la copia nuova senza un secondo arresto se il blocco del database in replication.conf non è cambiato. Se c’è spazio sufficiente e non serve eliminare, il nodo non elimina nulla, e tutto procede come in una inizializzazione ripetuta normale
Rete e disco carico secondo i limiti di velocità (5.5)

Su Windows. Un file aperto da Firebird non si può sostituire. Durante una inizializzazione ripetuta il nodo arresta il Firebird della replica tramite fbagent, installa il file e avvia di nuovo Firebird. Su Linux Firebird viene arrestato anche prima della sostituzione: altrimenti continuerebbe a lavorare con il file vecchio già eliminato.

5.4. Metodi morbido e standard

Morbido (predefinito). Prima del blocco, il nodo cerca le transazioni lunghe: transazioni di scrittura dell’utente iniziate prima del segmento più vecchio dell’archivio del master. Dopo l’inizializzazione la replica non potrà riprodurle e si fermerà alla loro prima modifica («Transaction … is not found»). Le transazioni senza modifiche non vengono contate.

Se esistono tali transazioni, l’inizializzazione non parte: RCM mostra La reinizializzazione morbida attende transazioni lunghe e fornisce un collegamento Apri l’elenco.

Pagina delle transazioni lunghe: nessuna transazione lunga
Pagina delle transazioni lunghe: nessuna transazione lunga

Nella pagina Transazioni lunghe:

  • riepilogo: quante transazioni e connessioni, il segmento più vecchio;
  • Le prime 5 connessioni con le transazioni più vecchie: utente, client, inizio, età, modifiche, query attuale;
  • Trattieni i segmenti / Rilascia la trattenuta: mentre la trattenuta è attiva, l’archivio del master non viene ripulito e la cronologia non viene troncata;
  • Disconnetti i selezionati e riprova la reinizializzazione: disconnette le connessioni (le loro transazioni vengono annullate) e avvia subito una reinizializzazione morbida;
  • Riprova la reinizializzazione, Controlla di nuovo.

La trattenuta si attiva automaticamente quando una reinizializzazione viene rifiutata a causa di transazioni lunghe. Viene rilasciata dopo una inizializzazione riuscita, a mano, oppure quando l’archivio cresce fino a reinit_hold_max_segments (1000 segmenti per impostazione predefinita, notifica retention_hold_released).

Standard blocca il database subito, senza controllo. Usalo solo se sai che non ci sono transazioni di scrittura lunghe.

Prima inizializzazione sotto carico. Mentre l’archivio del master è vuoto, non c’è un segmento con cui confrontare.

Con un nodo master HQbird 2027.2.24: se il nodo ha attivato la pubblicazione da solo e l’archivio non è cambiato da allora, la cronologia inizia nel momento in cui la pubblicazione è stata attivata. Una transazione iniziata dopo entra nel giornale dalla sua prima modifica e non ostacola il metodo morbido. Una transazione iniziata prima non è entrata nel giornale: la reinizializzazione la aspetta prima del blocco (6 tentativi ogni 10 s), e il passo locking mostra il suo numero, la connessione e l’utente. Se non è finita, la reinizializzazione termina con l’errore reinit_pre_publication_transactions: terminala e riprova. La pagina Transazioni lunghe mostra tali transazioni nella tabella Transazioni iniziate prima che la pubblicazione fosse attivata.

Se la pubblicazione è stata attivata a mano, non tramite il nodo, oppure l’archivio è già cambiato, l’inizio della cronologia è sconosciuto. In quel caso il metodo morbido rifiuta se una qualsiasi transazione di scrittura è aperta, e il messaggio dice che l’archivio non contiene ancora un segmento. In questo caso RCM 2027.2.24 non apre l’elenco ma scrive che cosa fare nella cella del database. Scegli Standard oppure riprova quando Firebird archivia il primo segmento.

Con un nodo master 2027.5.7, il metodo morbido rifiuta subito alla prima inizializzazione di un database su cui si sta scrivendo: long_transactions … segment 0 (0001-01-01T00:00:00Z). Per la prima inizializzazione di un tale database, scegli Standard.

Per le reinizializzazioni successive il metodo morbido funziona come al solito (l’archivio esiste già).

La stessa cosa dalla riga di comando

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

Transazioni più vecchie della pubblicazione. Firebird non scrive nei segmenti una transazione iniziata prima che la pubblicazione fosse attivata. Se il nodo ha attivato la pubblicazione, l’inizializzazione aspetta (6 tentativi ogni 10 secondi) che tali transazioni finiscano; altrimenti termina con l’errore reinit_pre_publication_transactions elencandole. Dopo aver sincronizzato una pubblicazione che ha aggiunto tabelle, riconnetti le applicazioni, poi avvia l’inizializzazione.

5.5. Velocità

Quando Velocità Impostazione
Dentro la finestra di trasferimento windows.transfer_window (predefinito 23:00-05:00) costante limits.reinit_window_mbps, predefinito 100 MB/s
Fuori dalla finestra frazione della velocità del disco misurata limits.reinit_day_disk_fraction, predefinito 0.5

Il nodo ricalcola la modalità ogni 30 secondi: una inizializzazione iniziata di giorno accelererà da sola di notte.

Il nodo misura la velocità del disco con una prova. Per ripetere la prova sull’host del master:

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

Tempo di inizializzazione ≈ dimensione del database ÷ velocità. Esempio: 100 GB a 100 MB/s, circa 17 minuti di trasferimento puro; in pratica lo limitano la rete o il disco.

5.6. Riavvio del Firebird della replica

Un database nuovo sulla replica. Il file viene collocato senza arrestare Firebird. Firebird leggerà il nuovo blocco di replication.conf solo dopo un riavvio. Fino ad allora la replica non applica nulla. Il passo RESTARTING REPLICA mostra l’attesa:

Etichetta Che cosa significa
in attesa di un riavvio di Firebird sulla replica, è previsto per … il nodo riavvierà Firebird da solo dopo l’ultima inizializzazione (reinit_restart_delay_sec), quando le altre inizializzazioni saranno finite
… la finestra di riavvio è chiusa, la prossima si aprirà alle … attesa di restart_window della replica
… l’ultimo tentativo è fallito, il prossimo alle … riproverà più tardi
la replica non può riavviare Firebird da sola: riavvialo a mano auto_restart: never, oppure questo Firebird serve anche i database del master

Il nodo riavvia Firebird una volta dopo una serie di inizializzazioni, non dopo ogni database.

Per riavviare a mano, fai clic su Riavvia il Firebird della replica. L’attesa termina dopo qualsiasi riavvio riuscito di Firebird oppure quando la replica ha applicato un segmento più recente della copia.

Reinizializzazione su un Firebird che serve anche i database del master. Il nodo non arresta tale Firebird da solo e rifiuta con restart_not_allowed. Avvia di nuovo l’inizializzazione e seleziona Consenti a di arrestare Firebird per questa reinizializzazione (-allow-restart sulla riga di comando), in un momento in cui le connessioni di questo Firebird possono essere interrotte, comprese quelle verso i suoi database master. Esegui tali inizializzazioni una alla volta per host.

Eliminazione della copia vecchia (la casella Elimina la replica vecchia, con HQbird 2027.2.24) arresta anche il Firebird della replica, con le stesse regole. Se il nodo non può arrestare questo Firebird da solo, non elimina nulla e rifiuta con restart_not_allowed: seleziona anche Consenti a di arrestare Firebird per questa reinizializzazione. Se in quel momento un’altra inizializzazione sta finendo sulla replica o Firebird si sta riavviando, il nodo non elimina nulla e rifiuta con engine_busy: il master rilascia il blocco, riprova più tardi.

5.7. Coda e inizializzazioni contemporanee

  • Un database: una inizializzazione alla volta (anche per repliche diverse). Il pulsante Inizializza è disattivato mentre è in corso una inizializzazione di questo database.
  • Il nodo master impone limits.max_concurrent_reinits inizializzazioni di database diversi contemporaneamente (per impostazione predefinita 1). Il resto aspetta in coda; la risposta contiene la posizione in coda.
  • Non eseguire un tuo nbackup -L (né ALTER DATABASE BEGIN BACKUP) su un database durante la sua inizializzazione, e non avviare una inizializzazione durante tale backup: un database può avere un solo blocco. L’inizializzazione lo controlla e rifiuta con nbackup backup lock already active.

La coda e i trasferimenti in corso sono visibili nella pagina Trasferimento.

Pagina Trasferimento / code
Pagina Trasferimento / code
- Se dopo un errore resta un file `.delta`, assicurati che non sia in corso un backup ed esegui `nbackup -N `. Non eliminare il `.delta` a mano.

5.8. Reinizializzazione automatica

RCM può reinizializzare da solo un database nello stato NEEDS_REINIT, solo dentro una finestra configurata. Disattivata per impostazione predefinita.

Quando un database entra in NEEDS_REINIT:

Causa Dove è visibile
errore di applicazione irrecuperabile che si ripete (violazione di PK, UNIQUE, FK), 3 volte di seguito replica, avviso replication_unrecoverable_error
il GUID del database master è cambiato (ripristino, sostituzione del file) replica, avviso replication_guid_mismatch
l’archivio del master non contiene più i segmenti di cui la replica ha bisogno master
la replica ha eliminato la copia vecchia per l’inizializzazione e non c’è ancora la copia nuova (da HQbird 2027.2.24) replica, avviso replica_removed_for_reinit; master

Per attivarla: Impostazioni → RCM (oppure rcm.json, la sezione 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" } }
  }
}
  • Finestra: per database → per nodo → globale. "always": in qualsiasi momento.
  • Le finestre si calcolano sull’orologio dell’host di RCM.
  • max_concurrent: quante inizializzazioni (manuali e automatiche) possono essere in corso nel cluster perché RCM ne avvii un’altra automatica.
  • L’inizializzazione automatica passa attraverso gli stessi controlli di spazio e di GUID dell’inizializzazione manuale. L’autore del comando è system:autoreinit.
  • remove_old_replica_when_short (da HQbird 2027.2.24, la riga Elimina la replica vecchia quando manca spazio): disattivata per impostazione predefinita. Se è attivata, l’inizializzazione automatica invia il flag Elimina la replica vecchia (4.4). RCM lo invia solo se la replica stessa è in NEEDS_REINIT oppure la causa NEEDS_REINIT del master la nomina. Per una replica che è IN_SYNC o LAGGING il flag non viene mai inviato. Se il nodo è una versione precedente, RCM avvia la stessa inizializzazione senza il flag.
  • Dopo la modifica, riavvia RCM.

Rimanda nella scheda del master disattiva l’inizializzazione automatica di un singolo database per 1 ora, 4 ore, 24 ore o fino all’annullamento. L’inizializzazione manuale resta disponibile.

5.9. Errori

Errore Causa Che cosa fare
insufficient disk space on master / on replica, 507 spazio insufficiente. Durante la reinizializzazione la copia vecchia occupa spazio fino alla fine capitolo 4.4; sulla replica (da HQbird 2027.2.24), la casella Elimina la replica vecchia (5.1)
node_too_old (da HQbird 2027.2.24) la casella Elimina la replica vecchia è selezionata, ma il nodo master o replica è una versione vecchia aggiorna il nodo come dice il testo dell’errore oppure esegui senza la casella
engine_busy, reclaim_in_progress (da HQbird 2027.2.24) la replica non può eliminare la copia vecchia adesso: Firebird o questo database è occupato riprova più tardi (5.6)
replica_removed_for_reinit, coppia NEEDS_REINIT (da HQbird 2027.2.24) la replica ha eliminato la copia vecchia, ma l’inizializzazione non è finita avvia di nuovo l’inizializzazione (4.4)
publication_off (da HQbird 2027.2.24) la pubblicazione del master è disattivata o non contiene tabelle con chiave Sincronizza la pubblicazione e inizializza (5.1)
long_transactions, «La reinizializzazione morbida attende transazioni lunghe» sono aperte transazioni di scrittura lunghe 5.4
long_transactions, «l’archivio del master non contiene ancora un solo segmento» prima inizializzazione sotto carico Standard (5.4)
reinit_pre_publication_transactions transazioni iniziate prima che la pubblicazione fosse attivata riconnetti le applicazioni, riprova
duplicate_guid due database master con lo stesso GUID rimuovi la copia; se il passo NEW GUID è stato saltato nella promozione a master, -force (capitolo 8.4)
license_paused il fbagent del master non ha licenza capitolo 2.8
409 orphaned il database è fuori dall’analisi del master capitolo 3.8
incompatible_engine versioni principali di Firebird diverse capitolo 4.3
target_not_replica un database di lavoro occupa il posto della replica (è stato reso normale) vedi sotto
target_other_replica (da HQbird 2027.2.24) una copia di un altro database di questo nodo occupa il posto della replica vedi sotto
restart_not_allowed il Firebird della replica serve anche database master 5.6, la casella «Consenti … di arrestare Firebird»
fbagent_required fbagent non è installato sulla replica capitolo 1
nbackup backup lock already active è in corso un backup nbackup 5.7
… -L did not finish in 2m0s and was stopped nbackup -L sul master non è finito in 2 minuti, quindi il nodo lo ha arrestato riprova; se l’errore si ripete, controlla il Firebird del master (firebird.log)
reinit already in progress for this database l’inizializzazione di questo database è già in corso aspetta che finisca

target_not_replica. Un database di lavoro occupa il posto della copia: è stato reso normale (esiste il file <database>.hqcluster-normal.json) oppure non è in modalità replica. Il nodo non sovrascrive un database di lavoro. Se va sostituito, una richiesta all’API del nodo con overwrite_non_replica: true (non c’è un pulsante per questo in RCM) sostituirà il file e conserverà quello vecchio come <database>.pre-reinit-<ora UTC>.fdb.

target_other_replica (da HQbird 2027.2.24). La replica colloca la copia in <databases.root>/<id del master>/<percorso del database>. L’id del master è unico solo dentro il proprio cluster, quindi due database possono finire con lo stesso percorso. Il nodo replica non sovrascrive una copia che appartiene a un altro dei suoi database: l’errore nomina quel database e il suo master. Il nodo riconosce anche una copia il cui percorso è registrato in modo diverso (un collegamento simbolico o una junction nel percorso, un nome breve di cartella Windows). overwrite_non_replica non elimina questo errore. Sposta una delle copie in un’altra cartella oppure togli quel database dalla replica, poi avvia di nuovo l’inizializzazione. Il nodo vede solo i propri database: due nodi replica sullo stesso host devono avere cartelle di replica diverse (databases.root).

5.10. Come controllare il risultato

  1. Database: la coppia master-replica del gruppo è Ok, stato IN_SYNC.

  2. Verifica nella scheda del master: i nodi contano le righe delle tabelle dell’elenco di tabelle del database (capitolo 3.1) sul master e sulla replica e le confrontano. Controlla in un momento tranquillo: con scritture attive i numeri possono differire.

    Con HQbird 2027.2.24 la pagina del risultato nomina l’elenco di ciascun lato (per esempio, «l’elenco proprio di questo database» o «tabelle della pubblicazione (elenco non impostato)»). RCM conta la replica usando l’elenco del master. Una tabella assente da entrambi i database è mostrata come «non nel database» e non viene contata come errore. Se non è stata confrontata nessuna tabella, il risultato è «Nessuna tabella da confrontare», non una discrepanza. Se il confronto non è finito nel tempo assegnato, il risultato è «Non confrontato (limite di tempo)», che non è nemmeno una discrepanza.

Risultato della verifica
Risultato della verifica
Command
hqbirdrcm verifydata -master node-a -master-db <db_id> -replica node-b -replica-db <db_id>
  1. Controllo periodico (facoltativo): la pagina Controllo dei dati, Attiva per tutti i nodi. Con HQbird 2027.2.24 il nodo applica le impostazioni subito, non serve riavviare il servizio del nodo: dopo Salva RCM scrive «Salvato e già in vigore». Il nodo 2027.5.7 ha bisogno che il servizio hqclusternode venga riavviato, e RCM 2027.2.24 lo dice. I nodi confrontano da soli il numero di righe quando il master e la replica sono sullo stesso segmento. Una discrepanza alza l’avviso data_mismatch; allora esegui Verifica.

Una tabella che l’operatore ha tolto dalla pubblicazione è mostrata come «non pubblicata», non come una discrepanza.

6. Configurazione della pubblicazione

La pubblicazione dice al Firebird master di quali tabelle scrivere le modifiche nei segmenti. Senza di essa, la replica non riceve nulla.

6.1. Che cos’è la pubblicazione

In Firebird 4 e 5, le tabelle da replicare sono definite dalla pubblicazione RDB$DEFAULT:

  • Pubblicazione attivata: in RDB$PUBLICATIONS ha RDB$ACTIVE_FLAG = 1 (il comando ALTER DATABASE ENABLE PUBLICATION).
  • Tabelle pubblicate: l’elenco in RDB$PUBLICATION_TABLES.

Firebird scrive le modifiche nei segmenti solo per le tabelle pubblicate e solo quando la pubblicazione è attivata. Registrare il database (capitolo 3) non attiva la pubblicazione. La attiva Sincronizza la pubblicazione (6.2).

Il nodo master controlla la pubblicazione ogni ora (limits.publication_check_interval_sec, 3600 per impostazione predefinita). Se è disattivata, il nodo la controlla ogni 2 minuti.

Nella pagina Database, il database master ha un’icona:

Icona Significato
pubblicazione attivata pubblicazione attivata
pubblicazione disattivata Firebird non scrive nulla nei segmenti, le repliche non ricevono modifiche
pubblicazione sconosciuta il nodo non ha potuto leggere lo stato

Il filtro Pubblicazione disattivata mostra i database con pubblicazione disattivata o sconosciuta.

Se un database con la pubblicazione disattivata ha già una replica, il master alza l’avviso master_publication_off.

Con HQbird 2027.2.24, il master alza questo avviso anche quando ha rifiutato di inizializzare un database con l’errore publication_off (capitolo 5.1): la pubblicazione è disattivata o non contiene nessuna tabella con chiave. Il livello dell’avviso:

  • avviso: il database non ha ancora una replica: l’inizializzazione aspetta la pubblicazione;
  • grave: il database ha già una replica;
  • informazione: l’operatore ha disattivato la pubblicazione.

L’avviso viene cancellato quando la pubblicazione è corretta oppure è iniziata un’altra inizializzazione.

6.2. Sincronizzare la pubblicazione

Riga del master: pubblicazione disattivata
Riga del master: pubblicazione disattivata

Dove fare clic:

  • nella riga del database master della pagina Database. Quando la pubblicazione è disattivata, il pulsante è accanto all’icona;
  • nella pagina del database;
  • per più database: seleziona le righe, nell’elenco Azione scegli Sincronizza la pubblicazione. RCM invierà un comando distinto per ogni database.
Conferma della sincronizzazione della pubblicazione
Conferma della sincronizzazione della pubblicazione

Che cosa fa il nodo (una sola transazione):

  1. Attiva la pubblicazione. Se l’operatore l’ha disattivata da solo (6.4), non la attiva.
  2. Aggiunge alla pubblicazione tutte le tabelle con chiave che non ci sono ancora.
  3. Toglie dalla pubblicazione le tabelle senza chiave e le tabelle che l’operatore ha escluso (6.3).
  4. Disattiva l’aggiunta automatica delle tabelle nuove (EXCLUDE ALL FROM PUBLICATION, poi aggiunge le tabelle necessarie). Solo il nodo definisce la composizione della pubblicazione.
Riga del master dopo la sincronizzazione: pubblicazione attivata
Riga del master dopo la sincronizzazione: pubblicazione attivata

Una tabella con chiave è una tabella permanente utente che ha una chiave primaria oppure un indice univoco attivo. Le tabelle di sistema e quelle temporanee non vengono pubblicate.

La sincronizzazione toglie dalla pubblicazione anche le tabelle senza chiave che il DBA ha aggiunto a mano.

Se la composizione è già corretta, il nodo non cambia nulla.

Quando il nodo rifiuta:

Codice Motivo
no_publications HQbird 2.5/3.0 (6.6)
not_master il nodo non è il master
reinit_in_progress l’inizializzazione di questo database è in corso
orphaned, database_failed, file_missing il database è fuori dall’analisi, in errore, oppure non ha un file

Tutti i database del nodo in una volta, solo dalla riga di comando. Nella pagina Comandi il risultato è mostrato per database: fatto, saltato o errore. I database nello stato FAILED o SEEDING e i database senza file vengono saltati.

La stessa cosa dalla riga di comando

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

Il comando aspetta fino a 5 minuti e stampa una riga per ogni database. In caso di errore il codice di uscita è 1. -nowait: non aspettare il risultato.

6.3. Tabelle della pubblicazione

La pagina «Tabelle della pubblicazione»
La pagina «Tabelle della pubblicazione»

Apri Tabelle della pubblicazione nella riga del database master.

La pagina mostra:

  • lo stato della pubblicazione (attivata/disattivata, disattivata dall’operatore) e i contatori;
  • ogni tabella: nome, chiave e stato.
Stato Significato
pubblicata le modifiche vanno nei segmenti
non ancora pubblicata una tabella con chiave, verrà aggiunta alla sincronizzazione
esclusa l’operatore l’ha tolta dalla pubblicazione
senza chiave non si può pubblicare

Nella colonna della chiave: la chiave primaria oppure, se non c’è, l’indice univoco con il minor numero di campi.

Perché una tabella senza chiave non si può pubblicare. La replica cerca la riga per UPDATE e DELETE tramite la chiave. Senza chiave non troverà la riga. Aggiungi una chiave primaria o un indice univoco, poi sincronizza la pubblicazione.

Escludi dalla pubblicazione / Rimetti nella pubblicazione:

  1. Seleziona le tabelle.
  2. Fai clic su Escludi dalla pubblicazione o Rimetti nella pubblicazione.
  3. Il nodo salva l’elenco e sincronizza subito la pubblicazione.
Conferma di «Escludi dalla pubblicazione»
Conferma di «Escludi dalla pubblicazione»

L’elenco delle tabelle escluse è memorizzato sul nodo master. La sincronizzazione non lo cambia. Quando una replica viene promossa a master (capitolo 8), l’elenco passa al nuovo master.

Verifica (capitolo 5.10) mostra una tabella esclusa come «non pubblicata», non come una discrepanza.

6.4. Attivare e disattivare la pubblicazione

Nella pagina Tabelle della pubblicazione: Disattiva la pubblicazione / Attiva la pubblicazione.

  • La disattivazione è una scelta dell’operatore. La sincronizzazione non riattiva la pubblicazione.
  • Le modifiche fatte mentre la pubblicazione è disattivata (o mentre una tabella è esclusa) non vengono inviate alla replica, nemmeno dopo l’attivazione.
  • Dopo l’attivazione, fai clic su Verifica (capitolo 5.10). Se i dati divergono, reinizializza la replica (capitolo 5).

6.5. Una tabella nuova

Una tabella nuova non entra da sola nella pubblicazione: il nodo disattiva l’aggiunta automatica.

Dopo il DDL:

  1. Crea una chiave primaria o un indice univoco sulla tabella.
  2. Fai clic su Sincronizza la pubblicazione.
  3. Chiedi alle applicazioni di riconnettersi se serve una reinizializzazione. Firebird non scrive nei segmenti le transazioni iniziate prima che la pubblicazione fosse attivata; COMMIT RETAINING tiene aperta tale transazione. L’inizializzazione aspetta queste transazioni e poi fallisce con reinit_pre_publication_transactions (capitolo 5.4).
Una tabella nuova nello stato «non ancora pubblicata»
Una tabella nuova nello stato «non ancora pubblicata»

Le righe scritte nella tabella nuova prima della sincronizzazione non arriveranno alla replica. Se ce ne sono, controlla i dati e, se necessario, reinizializza la replica.

6.6. HQbird 2.5 e 3.0

HQbird 2.5 e 3.0 non hanno pubblicazioni. Firebird scrive segmenti se il file del plugin replconf contiene un blocco master. I pulsanti della pubblicazione su tali nodi sono nascosti, e l’API risponde con no_publications.

L’insieme delle tabelle è definito dai parametri del motore:

Parametro Significato
include_filter quali tabelle replicare: nomi o motivi separati da virgole; vuoto: tutte
exclude_filter quali tabelle non replicare

I parametri si cambiano in Impostazioni → Parametri di replica (capitolo 7.1). La pagina Tabelle della pubblicazione li mostra in sola lettura, con un collegamento Cambia nelle impostazioni del motore. Firebird legge i valori nuovi dopo un riavvio.

Tabelle della pubblicazione su HQbird 3.0: filtri del motore
Tabelle della pubblicazione su HQbird 3.0: filtri del motore

Il plugin replconf. Il nodo scrive il proprio file replconf.hqcluster.hqbird nella cartella di Firebird. Firebird lo legge solo quando replconf.properties punta a esso. Il plugin va attivato una volta:

  1. Impostazioni → Nodi, il blocco Plugin di replica (HQbird 2.5 / 3.0). Il blocco mostra dove punta replconf.properties e i problemi che il nodo ha trovato.

Plugin non attivato: replconf.properties punta al file di HQbird DataGuard
Plugin non attivato: replconf.properties punta al file di HQbird DataGuard
  1. Attiva… La finestra elenca che cosa farà il nodo: installare il plugin, far puntare replconf.properties al file del nodo, migrare le voci del file vecchio. Scegli quando: Solo dentro la finestra di riavvio del nodo oppure Adesso, ignorando la finestra di riavvio.

Finestra di attivazione del plugin
Finestra di attivazione del plugin
  1. Dopo il riavvio di Firebird, il campo Attivato mostra «sì: il motore legge il file del nodo».

Plugin attivato
Plugin attivato

L’attivazione riavvia Firebird e riguarda tutti i database di questo Firebird. Falla in un periodo tranquillo.

7. Altre opzioni di replica

7.1. Parametri di replica

Impostazioni → Parametri di replica, modulo della procedura guidata
Impostazioni → Parametri di replica, modulo della procedura guidata

La pagina Impostazioni → Parametri di replica cambia le chiavi di replication.conf per i database selezionati o per il nodo nel suo insieme.

  1. Aggiungi master e repliche: seleziona i database. RCM li raggruppa per versione di Firebird e ruolo: un modulo distinto per i master e per le repliche.

  2. Per ogni parametro, scegli un’azione:

    Azione Che cosa fa
    nessuna modifica il valore non viene cambiato
    imposta valore un valore nuovo
    reimposta (al livello superiore) togli il valore proprio, prendi il valore del livello sopra
    non scrivere (valore di Firebird) la chiave non viene scritta, si applica il valore di Firebird
  3. Scegli dove applicarlo: Ai database selezionati oppure Come valore predefinito dei loro nodi.

  4. Anteprima: i nodi controllano i valori senza cambiare nulla.

Anteprima delle modifiche
Anteprima delle modifiche
  1. Applica. RCM invia il comando a ogni nodo.

Da dove viene il valore (la colonna Attuale):

Origine Valore
questo database impostato per il database
valore del nodo impostato come predefinito del nodo
valore integrato del nodo il valore del nodo che viene dal codice
valore di Firebird la chiave non è scritta
dal file (non ancora impostato qui) il valore di replication.conf, RCM non l’ha ancora cambiato
impostato dal nodo sola lettura (percorsi, prefissi)

Un nodo che non risponde mostra i suoi database come non disponibili per la selezione. Le modifiche richiedono fbagent (altrimenti fbagent_required).

Chi riavvia Firebird (Firebird legge replication.conf solo all’avvio):

Nodo Chi
master lo riavvii tu: il master non riavvia mai Firebird da solo
replica con firebird.auto_restart: never tu
replica il cui Firebird serve anche i database del master tu
le altre repliche il nodo lo riavvia nella propria finestra di riavvio

Per un riavvio manuale, la pagina ha un pulsante Riavvia Firebird.

7.2. Parametri principali

Master, Firebird 4/5:

Parametro Etichetta in RCM Valore del nodo Firebird Suggerimento
journal_archive_timeout Timeout dell’archivio 10 s 60 s quanti secondi Firebird aspetta prima di chiudere un segmento incompleto. Più basso: la replica è più vicina al master. Deve essere minore di limits.data_check_quiet_sec (90)
journal_segment_count Numero di segmenti 64 8 quanti segmenti possono risiedere in .ReplLog. Deve essere maggiore di limits.backlog_critical (48)
journal_segment_size Dimensione del segmento — 16 MB da 1 MB a 512 MB; il ricevitore non accetterà più di 512 MB
buffer_size — 1 MB

Il nodo scrive anche log_errors = true (non si può cambiare) e disable_on_error = true.

Replica, Firebird 4/5:

Parametro Etichetta in RCM Firebird Valore
apply_idle_timeout Pausa di inattività 10 s pausa quando non ci sono segmenti nuovi
apply_error_timeout Pausa dopo un errore di applicazione 60 s pausa prima di riprovare dopo un errore
verbose_logging nodo: true replication.log dettagliato; non è consigliato disattivarlo
skip_upddel_without_pk nodo: true saltare UPDATE/DELETE sulle tabelle senza chiave

Solo Firebird 5: include_filter, exclude_filter, cascade_replication.

HQbird 2.5/3.0: chiavi log_* con lo stesso significato: log_archive_timeout, log_segment_count, log_segment_size (non minore di 2 × buffer_size). La chiave alert_command si imposta solo in node.json.

Nel modulo di RCM c’è un suggerimento per ogni parametro.

7.3. Archiviazione dell’archivio

L’archivio <database>.LogArch del master viene ripulito a fasi:

  1. Segmenti che sono stati applicati da tutte le repliche e che sono più vecchi di retention_days.
  2. Se lo spazio libero è minore di free_space_floor_gb, segmenti applicati più recenti del periodo di conservazione. Avviso disk_serious_cleanup.
  3. Se lo spazio è ancora scarso, segmenti non applicati, a partire dai più vecchi. La replica riceve NEEDS_REINIT, avviso replication_paused_reinit_scheduled.
Parametro (Impostazioni → Nodi, Archiviazione e file) Predefinito
limits.retention_days: Conservazione dell’archivio, giorni 2
limits.retention_min_kept_segments: Conserva sempre gli ultimi segmenti 0 (disattivato)
limits.free_space_floor_gb: Spazio libero minimo 1 GB
Impostazioni → Nodi, «Archiviazione e file»
Impostazioni → Nodi, «Archiviazione e file»

Ripulisci l’archivio a mano:

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 (solo insieme a -db) elimina tutti i segmenti del database nello stato ORPHANED (capitolo 3.8). Per qualsiasi altro database il nodo risponderà not_orphaned. Non eseguire mai -orphaned sul donatore della promozione (capitolo 8.5).

7.4. Trasferimento: compressione, velocità, finestre

La compressione si imposta per partner: Impostazioni → Nodi → Partner, colonna compress.

Valore Significato
vuoto o none nessuna compressione (predefinito)
zstd compressione zstd

La modifica ha effetto subito. La compressione è utile su una rete lenta.

Velocità di trasferimento dei segmenti (Impostazioni → Nodi, Trasferimento e reinizializzazione):

Parametro Predefinito Quando ha effetto
limits.channel_a_mbps: Velocità di trasferimento dei segmenti 50 MB/s subito
limits.channel_a_burst_mbps: Picco di trasferimento dei segmenti 200 MB subito

L’unità è il mebibyte (MiB), anche se il nome dice «mbps». Il picco non può essere minore della velocità.

Impostazioni → Nodi, «Trasferimento e reinizializzazione»
Impostazioni → Nodi, «Trasferimento e reinizializzazione»

Finestre di tempo (Finestre di tempo):

Parametro Predefinito Quando ha effetto Che cosa influenza
windows.restart_window: Finestra di riavvio di Firebird master 22:00-05:00, replica always subito quando il nodo replica può riavviare Firebird
windows.transfer_window: Finestra di trasferimento 23:00-05:00 dopo il riavvio del nodo velocità piena di inizializzazione (capitolo 5.5)

L’etichetta accanto a ogni campo mostra quando la modifica ha effetto: subito oppure riavvio del nodo.

Impostazioni → Nodi, «Finestre di tempo»
Impostazioni → Nodi, «Finestre di tempo»

7.5. Verifica dei dati

  • Verifica: un confronto una tantum del numero di righe sul master e sulla replica (capitolo 5.10).
  • Verifica dei dati: un confronto periodico (capitolo 5.10). Il nodo esegue il confronto quando il master e la replica sono sullo stesso segmento.
  • Con HQbird 2027.2.24, le impostazioni di verifica hanno effetto subito dopo Salva; non serve riavviare il servizio del nodo. RCM mostra «Salvato e già in vigore». Dopo l’attivazione, la prima verifica viene eseguita dopo un intervallo. Dopo la disattivazione, una verifica in corso viene interrotta e non scrive nulla. Il nuovo intervallo si conta dalla fine dell’ultima verifica. Conserva, giorni, Limite della query, Quiete e Generatore di avanzamento hanno effetto dalla verifica successiva.
  • Il nodo 2027.5.7 legge queste impostazioni solo all’avvio: dopo Salva, riavvia il servizio hqclusternode di quel nodo. RCM 2027.2.24 mostra «Salvato, ma non ancora in vigore» e indica il motivo.
  • Quali tabelle confrontare è definito dall’elenco di tabelle del database (capitolo 3.1). Con HQbird 2027.2.24, ogni database può avere un proprio elenco: il campo alla registrazione o il blocco Tabelle di tracciamento della sincronizzazione nella pagina del database del master (capitolo 3.3). La pagina Verifica dei dati mostra quale elenco è stato usato, e il numero di tabelle «non nel database». Nel 2027.5.7 l’elenco è per nodo (sync_tables).
  • Le tabelle escluse dalla pubblicazione sono mostrate come «non pubblicata» (capitolo 6.3).
Pagina di verifica dei dati
Pagina di verifica dei dati

7.6. Avvisi

Pagina degli avvisi
Pagina degli avvisi

La pagina Avvisi. Azioni:

  • Conferma: l’avviso resta visibile ma è contrassegnato come confermato;
  • Silenzia per 60 min: nascondi per un’ora;
  • Elimina / Elimina tutti con questo codice: RCM passa l’eliminazione al nodo che ha alzato l’avviso. Se la causa resta, l’avviso ricomparirà.
Command
hqbirdrcm clearalerts -code backlog_warn   # also -id, -acked, -all

Da HQbird 2027.2.33, RCM invia gli avvisi a Telegram, a un webhook (Slack, Teams, JSON) e per e-mail. I canali si configurano nella sezione notify.channels del file rcm.json. Il blocco Canali di notifica della pagina Avvisi mostra i canali e invia un messaggio di prova. RCM segnala i problemi di livello warn e superiori: è comparso un problema, è diventato più grave, oppure è stato cancellato. Senza canali, RCM non invia nulla. Le versioni precedenti non inviano: tieni d’occhio la pagina Avvisi oppure interroga l’API di RCM.

Codici principali:

Codice Significato
backlog_warn / backlog_critical 32 / 48 segmenti non archiviati in .ReplLog
disk_serious_cleanup l’archivio viene ripulito alla fase 2 (7.3)
replication_paused_reinit_scheduled segmenti non applicati eliminati, serve l’inizializzazione
shipping_paused l’invio al partner è sospeso (7.7)
apply_error, replication_stopped, replication_unrecoverable_error la replica non può applicare un segmento
replication_guid_mismatch il GUID del database master è cambiato
segment_missing, segment_rejected, sequence_gap problemi con la sequenza dei segmenti
firebird_down, firebird_log_error Firebird non è in esecuzione oppure registra errori
firebird_not_answering da HQbird 2027.2.30: Firebird non ha risposto a una connessione di database per un minuto (blocco). Questo include anche una connessione che non si è stabilita per un timeout; firebird_down è solo un rifiuto di connessione
master_publication_off la pubblicazione è disattivata (capitolo 6); da HQbird 2027.2.24 e dopo un fallimento publication_off (capitolo 6.1)
replica_removed_for_reinit da HQbird 2027.2.24: la replica ha eliminato la copia vecchia per l’inizializzazione, e non c’è ancora la copia nuova (capitolo 4.4)
orphaned_database database fuori dall’analisi (capitolo 3.8)
restart_required_after_reinit il Firebird della replica ha bisogno di un riavvio (capitolo 5.6)
data_mismatch il controllo periodico ha trovato una discrepanza
license_paused fbagent non ha licenza (capitolo 2.8)

7.7. Mettere in pausa l’invio

Nella pagina Database, nella riga del master: Metti in pausa l’invio / Riprendi l’invio. Per più database, tramite l’elenco Azione.

Command
hqbirdrcm pauseshipping  -node node-a -db <db_id>
hqbirdrcm resumeshipping -node node-a -db <db_id>
Conferma della pausa dell'invio
Conferma della pausa dell'invio
Riga del master durante una pausa
Riga del master durante una pausa
  • La pausa resta in vigore fino a Riprendi l’invio oppure fino all’inizializzazione.
  • Il Firebird master continua a scrivere segmenti. L’archivio .LogArch cresce: mentre la replica è ferma, la fase 1 (7.3) non elimina i suoi segmenti.
  • Una pausa lunga può arrivare alla fase 3 e a NEEDS_REINIT. Tieni d’occhio lo spazio.
  • Il pulsante è assente se il database non ha una replica o la pubblicazione è disattivata. L’icona Pausa: nessuna licenza significa una pausa legata alla licenza (capitolo 2.8); la toglie solo una licenza.

7.8. Log

Log Dove
Nodo <cartella di installazione>/logs/node-YYYYMMDD.jsonl (/opt/hqclusternode o C:\hqclusternode), 32 MB ciascuno, 20 file
replication.log e firebird.log di Firebird percorsi in node.json: firebird.replication_log, firebird.firebird_log
RCM Linux: journalctl -u hqbirdrcm
Audit di RCM rcm-data/audit.jsonl

Log remoto del nodo: la pagina Log: seleziona un nodo e una fonte (replication.log, firebird.log, agente del nodo).

Pagina dei log
Pagina dei log
Command
hqbirdrcm getlogs -node node-b -source replication -tail 200

8. Come trasferire una replica a un database normale

Ci sono due percorsi:

Percorso Quando Che cosa ottieni
Rendi normale, 8.1 ti serve una copia di lavoro separata: report, prove, un guasto senza un nuovo master un database normale fuori dalla replica
Promuovi a master, 8.3 la replica deve diventare il nuovo master un database gestito da un nodo compagno con il ruolo di master

Nessuno dei due percorsi si può annullare dall’interfaccia.

8.1. Rendi normale

Elenco «Azione» della replica: la voce «Rendi normale»
Elenco «Azione» della replica: la voce «Rendi normale»
  1. Database, lato replica: seleziona le righe della replica.

  2. Nell’elenco Azione, scegli Rendi normale e conferma. Non c’è un pulsante distinto nella riga. Non c’è nemmeno un comando da riga di comando.

Conferma di «Rendi normale»
Conferma di «Rendi normale»
3. Il nodo replica: - esegue `gfix -replica none` (HQbird 2.5/3.0: `gfix -replica {}`). Se il database è occupato ad applicare segmenti, il nodo lo mette in arresto `single` per qualche secondo (`gfix -shut single -force 0`), toglie la modalità replica e lo riporta con `gfix -online normal`. **Tutte le connessioni a questo database vengono interrotte**; - scrive il file marcatore `.hqcluster-normal.json` (ora, autore, db_id, GUID); - inizia a svuotare la coda `.Incoming` (8.2). 4. RCM mostra il database nel gruppo **Non è una replica (normale)**.
La pagina «Database» dopo «Rendi normale»
La pagina «Database» dopo «Rendi normale»

Dopo questo, il database è aperto in scrittura.

Togli il blocco della replica da replication.conf. Il nodo lo toglie all’analisi successiva, e Firebird legge il file all’avvio:

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

Fino ad allora, gli errori «il database non è in modalità replica» per questo database non vengono alzati come avvisi.

Il file marcatore protegge il database. L’inizializzazione non sovrascriverà un tale database: viene rifiutata con target_not_replica (capitolo 5.9). Eliminare solo il marcatore non basta: il nodo controlla anche la modalità replica nell’intestazione del database. La casella Elimina la replica vecchia (capitolo 4.4) non elimina nemmeno un tale database.

Con HQbird 2027.2.24, mentre la replica sta eliminando la copia vecchia di questo database per l’inizializzazione, Rendi normale viene rifiutato con reclaim_in_progress: riprova più tardi.

Se il database deve tornare a essere una replica, serve solo una nuova inizializzazione con sovrascrittura. Si fa tramite l’API del nodo (overwrite_non_replica: true); non c’è questo pulsante in RCM. Il file vecchio viene conservato come <database>.pre-reinit-<ora UTC>.fdb, e il marcatore viene eliminato.

8.2. Che cosa succede ai segmenti

  • Finché il nodo non ha analizzato i database, il master continua a inviare segmenti. Ogni 30 secondi il nodo replica elimina i segmenti vecchi e conserva solo gli ultimi 100 (keep_segments).
  • Dopo l’analisi, il record del database sulla replica riceve lo stato ORPHANED. Il nodo replica risponde al master con unknown_database. Il master smette di inviare segmenti a questa replica, smette di conservare un archivio per essa e la ricontrolla ogni 10 minuti.
  • Le altre repliche di questo database non sono interessate.
  • Il record ORPHANED si può eliminare (capitolo 3.8): hqbirdrcm forgetdatabase. Il file del database stesso non viene eliminato.

8.3. Promuovi a master

La replica diventa il nuovo master. Il suo file resta al suo posto, e il controllo passa al nodo compagno.

Condizioni:

Condizione Rifiuto
il database è una replica bad_request
sullo stesso host è in esecuzione un nodo con il ruolo di master, il compagno (la stessa etichetta host in rcm.json, capitolo 2.1) no_companion
la promozione di questo database non è già in corso already_running
non c’è una inizializzazione verso questo database né dal suo master reinit_running

RCM non crea il nodo compagno: installalo in anticipo (capitolo 1).

Come iniziare:

  • nella riga della replica, Promuovi a master, oppure nell’elenco Azione;

  • dalla riga di comando:

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

RCM chiederà conferma e nominerà il nodo compagno.

Conferma «Promuovere a master?»
Conferma «Promuovere a master?»

Passi (visibili nella riga della replica, nomi in inglese):

N. Passo Che cosa fa
1 TURN TO NORMAL come in 8.1; saltato se il database è già normale
2 NEW GUID un GUID nuovo del database sul posto (8.4)
3 EXCLUDE ON DONOR il nodo replica (donatore) esclude il file dalla propria analisi (exclude_paths)
4 ENROLL ON il nodo compagno registra il file come database master
5 PUBLICATION SYNC sincronizzazione della pubblicazione; l’elenco delle tabelle escluse viene portato dal vecchio master (capitolo 6.3)
6 RESTART DONOR FIREBIRD riavvio del Firebird del donatore, senza aspettare una finestra
7 RESTART FIREBIRD riavvio del Firebird del compagno, senza aspettare una finestra
8 FINALIZE la riga del donatore diventa Replica fantasma; il vecchio master può diventare Master degradato (8.5)
Passi della promozione nella riga della replica
Passi della promozione nella riga della replica

Su HQbird 2.5 e 3.0 non ci sono pubblicazioni: il passo PUBLICATION SYNC termina con il testo «questo motore non ha pubblicazione».

Passi della promozione su HQbird 3.0 (Windows)
Passi della promozione su HQbird 3.0 (Windows)

Se il donatore e il compagno usano lo stesso Firebird, quel Firebird viene riavviato: le connessioni a tutti i suoi database vengono interrotte.

Se un passo fallisce, il lavoro riceve failed con il testo dell’errore. Correggi la causa e fai di nuovo clic su Promuovi a master: i passi completati non vengono ripetuti. Se RCM si riavvia durante la promozione, anche il lavoro diventerà failed: controlla lo stato dei nodi e riprova.

Licenza. Se il fbagent sull’host del master non ha licenza, il master ha messo in pausa l’invio. La promozione è comunque possibile. RCM ti avviserà: le modifiche fatte dopo l’inizio della pausa andranno perse.

8.4. GUID nuovo

Dopo la promozione, il database deve ricevere un proprio GUID. Altrimenti il nuovo master scrive segmenti sotto il GUID del vecchio master, e le sue repliche vengono rifiutate con duplicate_guid.

Il passo NEW GUID sul nodo:

  1. gfix -shut single -force 0: tutte le connessioni al database vengono terminate;
  2. nbackup -L, poi nbackup -F senza -SEQUENCE;
  3. elimina <database>.delta;
  4. controlla l’intestazione: GUID nuovo, REPLICATION_SEQUENCE = 0;
  5. gfix -online normal.

Firebird non viene riavviato. Il metodo funziona su tutte le versioni (2.5, 3.0, 4.0, 5.0).

Se il passo è stato interrotto, il nodo emette l’avviso newguid_interrupted. Il database può restare in arresto single. Ripeti Promuovi a master: il passo continuerà.

Il passo viene saltato (il testo inizia con skipped:) se il nodo donatore è una versione vecchia oppure il file ha già un proprio GUID.

Dopo un GUID nuovo, la vecchia catena nbackup non è più adatta. Fai una nuova copia nbackup di livello 0.

Se il database è stato creato con ADD DIFFERENCE FILE, il suo .delta si trova in un altro posto: eliminalo a mano.

8.5. Dopo la promozione

Record del donatore. Sul nodo replica il database resta ORPHANED, il percorso resta in exclude_paths, e restano la cartella .Incoming e l’etichetta. In RCM è la riga Replica fantasma con i pulsanti Apri sul nuovo master e Cancella.

Riga del donatore: «Replica fantasma»
Riga del donatore: «Replica fantasma»
  • Per togliere la riga, fai clic su Cancella. Questo cambia solo RCM.
  • Per togliere il record del donatore dal nodo replica, esegui forgetdatabase. Il file e la cartella .Incoming restano. HQbird 2027.2.30 e successivi non rifiutano il comando (mailbox_active), perché il percorso del donatore è in exclude_paths. I nodi delle versioni precedenti lo rifiutano finché sono presenti il file e la cartella .Incoming.
  • Non eseguire mai cleanuparchive -orphaned sul donatore. Il donatore e il compagno condividono la stessa cartella <database>.LogArch. Il comando eliminerà l’archivio vivo del nuovo master.

Vecchio master.

  • Se il donatore era la sua ultima replica funzionante, RCM mette il vecchio master in Master degradato e mette in pausa l’invio al donatore («invio in pausa: … (promozione a master)»). Non riprendere l’invio al donatore: contiene già un database di lavoro. Per togliere questo stato, inizializza il database su un’altra replica.

    Vecchio master: «Master degradato», invio in pausa
    Vecchio master: «Master degradato», invio in pausa
  • L’inizializzazione dal vecchio master verso il nodo donatore verrà rifiutata (target_not_replica): contiene già un database di lavoro.
  • Se il passo NEW GUID è stato saltato, il vecchio e il nuovo master hanno lo stesso GUID. In quel caso l’inizializzazione dal vecchio master richiede -force (capitolo 5.9).
  • Dopo una promozione manuale, RCM non trasforma il vecchio master in una replica del nuovo master. Ferma le applicazioni sul vecchio master e togli il suo database dalla gestione (capitolo 3.8). Per un database descritto come servizio, lo fa Reintegra (8.7).

Nuovo master. Configura una replica per esso: nodo replica, partner (capitolo 2), pubblicazione (capitolo 6), inizializzazione (capitolo 5).

Nuovo master: database con un GUID nuovo, ancora senza replica
Nuovo master: database con un GUID nuovo, ancora senza replica

8.6. Commutazione pianificata: elenco di controllo

Questa è la procedura di una commutazione manuale. Per un database descritto come servizio, RCM cambia il master da solo (8.7). Una promozione manuale non controlla se le applicazioni scrivono sul vecchio master. Procedura:

  1. In anticipo. Sull’host della replica è in esecuzione un nodo compagno con il ruolo di master, ed entrambi i nodi hanno la stessa etichetta host (capitolo 2.1). Un nodo per la replica futura è pronto per il nuovo master.
  2. Ferma le scritture delle applicazioni verso il database del vecchio master.
  3. Aspetta che la replica abbia ricevuto e applicato tutto: Database → IN_SYNC, nessuna coda.
  4. Verifica (capitolo 5.10): i numeri di righe coincidono.
  5. Promuovi a master (8.3). Aspetta il passo FINALIZE.
  6. Controlla: il database è nell’elenco dei master del compagno, pubblicazione attivata.
  7. Passa le applicazioni al nuovo master.
  8. Fai una copia nbackup di livello 0 del database nuovo (8.4).
  9. Cancella il record fantasma della riga del donatore (8.5).
  10. Collega la replica al nuovo master e inizializzala (capitolo 5).
  11. Vecchio master: togli il database dalla gestione oppure lascialo come archivio (8.5).

8.7. Servizi: commutazione e commutazione di emergenza in RCM

Con HQbird 2027.2.30, RCM sposta il master su un altro host da solo. Per farlo, il database è descritto come un servizio: un database logico su più host. Su ogni host del servizio c’è un nodo master e un nodo replica, e il percorso del file del database è lo stesso. Il servizio si crea nella pagina Servizi (da HQbird 2027.2.31) oppure con il comando hqbirdrcm services put -id <id> -file <file>.json.

Azione Che cosa fa Comandi
Commutazione trasferimento pianificato del master senza perdita di dati. Dopo, il vecchio master diventa automaticamente una replica del nuovo master hqbirdrcm switchover -service <id> -check, poi hqbirdrcm switchover -service <id> -to <host>
Commutazione di emergenza l’host del master è perso: RCM promuove la replica. Le modifiche più recenti del master possono andare perse hqbirdrcm failover -service <id> -check, poi hqbirdrcm failover -service <id> -to <host> -accept-data-loss
Reintegra dopo una commutazione di emergenza, riporta il vecchio host come replica del nuovo master hqbirdrcm rejoin -service <id>
Riprendi toglie il servizio dallo stato failed hqbirdrcm resume -service <id> -check, poi hqbirdrcm resume -service <id>

Le stesse azioni sono disponibili nella pagina del servizio: i pulsanti Commutazione…, Commutazione di emergenza…, Reintegra… e Riprendi….

  • La commutazione di emergenza automatica è disattivata per impostazione predefinita. Si attiva per ogni servizio separatamente: hqbirdrcm policy -service <id> -auto-failover on -max-data-loss 30. Richiede dei router. RCM avvia una commutazione di emergenza solo quando il nodo master è silenzioso, la maggioranza dei router non vede il Firebird del master, e il ritardo della replica non supera max_data_loss_sec.
  • Un router (hqclusternode router, Linux) mantiene HAProxy sul master attuale del servizio. Le applicazioni si connettono a <host del router>:<router_port> e non cambiano la stringa di connessione quando avviene una commutazione.
  • Dopo una commutazione di emergenza, RCM isola il vecchio master (ruolo fenced) non appena risponde di nuovo. Riportalo con il comando rejoin.