Guide de l'administrateur pour le cluster de réplication HQbird : hqclusternode et hqbirdrcm (RCM). Programmes d'installation : Téléchargement de HQbird 2027.

Sommaire


0. Introduction

Ce guide décrit comment installer et utiliser le cluster de réplication HQbird : les nœuds hqclusternode et le gestionnaire de cluster hqbirdrcm (RCM).

C’est un guide pour l’administrateur Firebird. Nous supposons que vous connaissez Firebird, gfix et nbackup. Vous n’avez pas besoin de connaître le fonctionnement interne d’un nœud.

De quoi le cluster est composé

Composant Combien Où il s’exécute Ce qu’il fait
Firebird (HQbird) une ou plusieurs instances sur chaque serveur de bases de données stocke les bases de données, écrit les segments de réplication
fbagent un par instance Firebird à côté de Firebird arrête et démarre Firebird à la demande d’un nœud
hqclusternode (nœud) un par instance et par rôle à côté de Firebird configure la réplication, transfère les segments, effectue l’initialisation de la réplique
hqbirdrcm (RCM) un par cluster sur tout hôte qui peut voir tous les nœuds interface web, commandes, alertes, statistiques

Un nœud a un rôle : master ou replica. Deux nœuds peuvent s’exécuter sur une seule instance Firebird : un nœud maître et un nœud réplique. Dans ce cas, certaines bases de données de ce Firebird sont des maîtres et d’autres des répliques.

Comment cela fonctionne

  1. Sur le maître, Firebird écrit les modifications de la base de données dans des segments (fichiers du journal de réplication).
  2. Le nœud maître envoie les segments au nœud réplique par un canal sécurisé (mTLS).
  3. Le nœud réplique place les segments dans le dossier des segments entrants. Le Firebird de la réplique les applique à sa copie de la base de données.
  4. Le nœud maître transfère lui-même la première copie de la base de données vers la réplique. C’est l’initialisation (reinit). Elle passe par nbackup, et le maître continue de fonctionner pendant ce temps.
  5. Les nœuds envoient des statistiques à RCM. RCM affiche l’état du cluster et envoie les commandes de l’opérateur aux nœuds.
Fonctionnement du cluster : segments, initialisation, statistiques et commandes de l'opérateur
Fonctionnement du cluster : segments, initialisation, statistiques et commandes de l'opérateur

Versions prises en charge

  • Firebird / HQbird 5.0 et 4.0 : toutes les fonctions.
  • HQbird 3.0 et 2.5 : réplication via le greffon replconf. Il n’y a pas de publications ; l’ensemble des tables est défini par des filtres. Les différences sont décrites dans les encadrés « HQbird 2.5/3.0 ».

La version majeure de Firebird sur le maître et sur la réplique doit être la même. Sinon, le nœud réplique refusera l’initialisation.

Ports

Port Qui écoute Qui se connecte À quoi ça sert
7051 nœud les autres nœuds et RCM API du nœud, transfert des segments et des copies de base de données
7443 RCM tous les nœuds réception des statistiques des nœuds
7444 RCM opérateur interface web et API de l’opérateur. Installation via RCM (chapitre 1.3) : HTTPS sur toutes les adresses. Installation via HQCenter Admin ou manuelle : HTTP, 127.0.0.1 uniquement
7450–7459 fbagent, tant que la fenêtre de liaison est ouverte RCM liaison des hôtes (chapitre 1.3)
13050 fbagent, 127.0.0.1 uniquement nœud sur le même hôte gestion de Firebird
3050 Firebird applications fonctionnement normal de la base de données

S’il y a deux nœuds sur un hôte (maître et réplique), le second nœud a un port différent. Lors d’une installation via RCM, le second nœud reçoit le port 7061. Dans les autres cas, vous fixez le port vous-même, par exemple 7052.

Le port 13050 ne doit pas être exposé au réseau. Le port 7444 en HTTP (installation via HQCenter Admin ou manuelle) non plus : connectez-vous à l’interface web de RCM par un tunnel SSH (chapitre 1). Lors d’une installation via RCM, le port 7444 fonctionne en HTTPS, et le programme d’installation l’ouvre dans le pare-feu.

La règle principale : pas de fbagent, pas de modifications

Un nœud ne modifie la configuration de réplication que par l’intermédiaire de fbagent : il doit redémarrer Firebird. Si fbagent n’est pas disponible, le nœud refuse toute action qui modifie la configuration. Il ne travaille pas « à moitié ».

Termes

Terme Signification
Segment fichier du journal de réplication contenant les modifications de la base de données
Publication liste des tables du maître dont les modifications vont dans les segments (Firebird 4/5)
Initialisation (reinit) transfert d’une copie de la base de données du maître vers la réplique via nbackup
GUID de base de données identifiant de la base de données Firebird ; RCM l’utilise pour relier le maître et la réplique
Pair nœud partenaire : pour un maître, ses répliques
Compagnon le second nœud sur la même instance Firebird (maître et réplique sur un hôte)
Inscription enregistrement des bases de données maîtres dans le nœud

Comment lire le guide

Chapitre Sujet
1. Installation installation des nœuds et de RCM via HQCenter Admin, via RCM sans HQCenter Admin et manuellement, Linux et Windows
2. Configuration du cluster liens maître → réplique, paramètres des nœuds, utilisateurs RCM
3. Ajouter une base de données au maître inscription, redémarrage de Firebird, vérification
4. Comment faire d’une base de données une réplique étapes, préparation de la réplique, espace disque
5. Initialisation étapes de la réinitialisation, effet sur le fonctionnement, transactions longues, vitesse, erreurs
6. Configuration de la publication publication Firebird 4/5, tables, nouvelles tables, HQbird 2.5/3.0
7. Autres options de réplication paramètres de replication.conf, archive, transfert, alertes, pause, journaux
8. Conversion d’une réplique en base de données ordinaire Rendre normale, Promouvoir en maître, nouveau GUID, services (bascule, basculement), liste de contrôle de la bascule

Tous les chapitres utilisent un seul exemple :

Quoi Valeur
node-a nœud maître, bases de données dans /databases/master
node-b nœud réplique, bases de données dans /databases/replica
RCM un hôte distinct (peut aussi être l’un des serveurs de bases de données)
base de données employee.fdb

1. Installation des nœuds et de hqbirdrcm

Il y a trois méthodes d’installation :

Méthode Quand la choisir Ce que vous faites vous-même
Via HQCenter Admin (1.2) le chemin habituel : le serveur de mises à jour HQCenter Admin est accessible, les mises à jour automatiques sont nécessaires vous lancez le script d’installation de fbagent, approuvez la demande, décrivez le cluster
Via RCM, sans HQCenter Admin (1.3) il n’y a pas de HQCenter Admin, mais vous avez besoin de certificats, de la configuration et des mises à jour sans travail manuel ; jusqu’à 3 serveurs de bases de données vous installez HQbird sur chaque hôte, vous vous connectez à RCM, et dans Paramètres → Lier les hôtes vous indiquez les adresses des hôtes
Manuellement (1.4) pas d’accès à HQCenter Admin, réseau fermé, exigences particulières vous installez les fichiers, créez les certificats, écrivez node.json et rcm.json, enregistrez les services

Via HQCenter Admin et via RCM, vous n’installez pas vous-même les nœuds et RCM. Ils sont installés par fbagent lorsque vous l’ajoutez au cluster (chapitre 2). Les certificats et la configuration sont aussi créés automatiquement.

Linux et Windows sont décrits dans un seul chapitre. Les différences Windows sont dans les encadrés « Sous Windows ».

1.1. Exigences

Sur chaque serveur de bases de données :

  • Firebird / HQbird 5.0, 4.0, 3.0 ou 2.5 (2.5 : Linux uniquement).
  • fbagent à côté de chaque instance Firebird. Sans fbagent, le nœud ne fonctionne pas.
  • Synchronisation de l’heure (NTP, chrony, w32time) sur tous les serveurs et sur l’hôte RCM. Les fenêtres de redémarrage et de transfert, l’estimation du retard et le contrôle « nœud ne répond pas » dépendent des horloges.
  • Espace libre pour l’archive des segments et pour l’initialisation de la réplique (chapitre 4).
  • Réseau selon le tableau des ports (chapitre 0).

Linux : privilèges root, x86_64, systemd, curl. Pris en charge : Ubuntu 20–26, Debian 11–13, Astra, CentOS 7–10, AlmaLinux, Rocky, Oracle Linux 8–10, RED OS, openSUSE 15.6, Fedora 44+.

Windows : privilèges d’administrateur, x64, Windows 10 / Server 2016 ou plus récent, Windows PowerShell 5.1 64 bits. Sur Windows 10 et Server 2016–2022, 7-Zip est requis.

Où RCM s’exécutera. Un RCM est nécessaire par cluster. Il peut être installé sur tout serveur qui peut voir tous les nœuds, y compris sur l’un des serveurs de bases de données.

1.2. Installation via HQCenter Admin

Étape 1. Lancer le script d’installation de fbagent

Le script installe Firebird (la version HQbird), fbagent, et enregistre fbagent sur le serveur HQCenter Admin. Choisissez le script correspondant à votre version de Firebird : fb25, fb30, fb40, fb50.

Linux (en tant que root) :

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

Sous Windows (PowerShell en tant qu’administrateur) :

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

Il n’y a pas de paramètre -Cluster sous Windows : fbagent s’exécute en tant que LocalSystem et crée lui-même les dossiers du cluster.

Paramètres principaux :

Linux Windows Signification
--goafts <name> -Goafts serveur HQCenter Admin depuis lequel télécharger ; le nom est fourni par votre fournisseur
--enroll -Enroll enregistrer fbagent dans HQCenter Admin (demande de certificat)
--cluster — créer les dossiers /opt/hqclusternode et /opt/hqbirdrcm (nécessaire seulement pour fbagent 2.55.2 et antérieur ; sans effet pour les versions plus récentes)
--channel -Channel canal de mise à jour de fbagent, stable par défaut
--token -Token jeton de licence : HQCenter Admin approuvera la demande automatiquement
--port -Port port Firebird
--yes -Yes ne pas poser de questions (nécessaire lorsqu’il n’y a pas de terminal)

Pour la liste complète des paramètres, voir le README du script d’installation de fbagent.

Étape 2. Approuver la demande fbagent

Avec le paramètre --enroll, fbagent envoie une demande de certificat (CSR) à HQCenter Admin et attend jusqu’à 30 minutes l’approbation. Vous pouvez l’approuver ainsi :

  • automatiquement, si l’installation a été lancée avec un jeton de licence (--token) et que la licence a un siège libre ;
  • dans le panneau HQCenter Admin, section des demandes CSR, la demande de cet hôte, bouton approuver et signer ;
  • via l’API HQCenter Admin : POST /v1/admin/csr-requests/{id}/approve.

Si l’enregistrement n’a pas réussi (par exemple, le délai d’attente est écoulé), fbagent fonctionne quand même, mais le script se termine avec le code 2. Relancez le script avec les mêmes paramètres : seul l’enregistrement sera répété.

Quelques minutes après l’enregistrement, fbagent installe HQ Monitor lui-même.

Étape 3. Décrire le cluster

Les nœuds et RCM apparaissent une fois que vous ajoutez fbagent au cluster HQCenter Admin. Comment décrire le cluster est traité au chapitre 2.

Après l’enregistrement du cluster :

  1. Dans les 10 minutes, fbagent reçoit le cluster depuis HQCenter Admin (ensuite il vérifie les modifications toutes les 60 secondes).
  2. Le fbagent de l’hôte RCM crée l’autorité de certification (CA) du cluster et signe les certificats de tous les nœuds.
  3. Chaque fbagent écrit node.json ou rcm.json pour les membres de son cluster.
  4. À la vérification de produit suivante (toutes les 3 minutes), fbagent installe et démarre les services.

Ce qui est installé, et où :

Quoi Linux Windows
Nœud maître /opt/hqclusternode/master/, service hqclusternode-master-p<port> <HQbird>\hqclusternode\master\, service HQClusterNode-master-p<port>
Nœud réplique /opt/hqclusternode/replica/, service hqclusternode-replica-p<port> <HQbird>\hqclusternode\replica\, service HQClusterNode-replica-p<port>
RCM /opt/hqbirdrcm/, service hqbirdrcm <HQbird>\hqbirdrcm\, service hqbirdrcm

<port> est le port Firebird, par exemple 3050. Un seul fbagent ne peut héberger au plus qu’un nœud maître, un nœud réplique, un RCM et un routeur (hqclusternode router, à partir de HQbird 2027.2.30, chapitre 8.7).

Sous Windows. Les versions de fbagent antérieures à 2.83.0 installaient les nœuds dans C:\hqclusternode et RCM dans C:\hqbirdrcm. Si ces dossiers existent, fbagent continue de les utiliser.

Mises à jour

  • fbagent vérifie les nouvelles versions du nœud et de RCM toutes les 3 minutes ; le canal par défaut est stable. Le nœud réplique est mis à jour en premier, puis le nœud maître.
  • Si, après une mise à jour, le service ne démarre pas ou signale la mauvaise version, fbagent revient à la version précédente et bloque la nouvelle. La liste des blocages : <dossier fbagent>/update/<product>/blocked-versions.json. Pour réessayer la version, supprimez sa ligne de ce fichier.
  • État du produit : fbagent --product-status hqclusternode (ou hqbirdrcm).

1.3. Installation via RCM (sans HQCenter Admin)

Le cluster est géré par RCM. Le fbagent de chaque hôte reçoit la description du cluster depuis RCM, le fbagent de l’hôte RCM signe les certificats, et le nœud et RCM sont mis à jour à partir des versions stockées par RCM.

Limitations :

  • Un cluster par RCM.
  • Pas plus de 3 sièges. Un siège est un hôte qui exécute un nœud maître ou réplique. Un maître et une réplique sur le même hôte comptent pour un siège. Un hôte qui n’exécute que RCM n’occupe pas de siège. Un quatrième hôte produit l’erreur seats_exceeded.
  • RCM ne met pas à jour fbagent ni Firebird. fbagent les met à jour lui-même et ne touche pas à replication.conf, node.json, rcm.json ni aux certificats.

Il y a deux méthodes :

  • Lier les hôtes dans RCM : la méthode habituelle. Trois actions : le programme d’installation sur chaque hôte (RCM sur un hôte, mode découverte sur les autres), connexion à RCM, le formulaire Lier les hôtes.
  • Manuellement depuis la ligne de commande : jetons d’adhésion et fbagent --cluster-join. Nécessaire lorsque le port 7450 est fermé entre les hôtes ou que la fenêtre d’appairage est déjà fermée.

Licence. La licence d’essai inclut la fonction cluster. Après la période d’essai, fbagent n’installe pas de nœud ni de RCM si la licence n’a pas cluster. Il ne bloque jamais les mises à jour des nœuds et de RCM déjà installés. Sans HQCenter Admin, une licence flottante cesse de fonctionner après online_check_days plus les jours de grâce. Installez donc une licence liée sur chaque fbagent :

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

Sans licence, le maître cesse d’envoyer les segments (chapitre 2.8).

Ports :

Port Où Qui se connecte
7443 hôte RCM fbagent et nœuds de tous les hôtes du cluster
7444 hôte RCM navigateur de l’opérateur (console RCM, HTTPS)
7450 (sur le deuxième fbagent de l’hôte et les suivants : 7451…7459) hôte en mode découverte, tant que la fenêtre d’appairage est ouverte RCM sur l’hôte RCM
7051 (second nœud du même fbagent : 7061) hôtes des nœuds les autres nœuds et RCM (1.4, étape 7)

Lier les hôtes dans RCM

Exemple à partir de zéro. Deux serveurs Linux, le programme d’installation .run, liaison, enregistrement, publication, initialisation et réinitialisation en charge, avec captures d’écran et mesures : le guide hqbird2027-linux-cluster-guide.ru.md et le runbook hqbird2027-linux-cluster-runbook.ru.md (dépôt goafts, dossier documentation).

Étape 1. Installer HQbird sur chaque hôte

Installez HQbird avec le programme d’installation complet sur chaque serveur de bases de données. Ne vous enregistrez pas auprès de HQCenter Admin (--enroll).

Par défaut, le programme d’installation ne configure pas de cluster. Il place les programmes du nœud et de RCM dans le dossier de fbagent (update/<product>/staged/), mais n’installe pas RCM, n’ouvre pas la fenêtre d’appairage et n’ouvre pas les ports du cluster dans le pare-feu. Le cluster est activé par deux paramètres :

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 : sur un hôte, là où s’exécutera le RCM du cluster. Le programme d’installation :

  1. crée le cluster de cet hôte (fbagent --cluster-init) ; le nom du cluster est le nom de l’hôte ;
  2. installe et démarre RCM ; la console RCM fonctionne en HTTPS sur le port 7444 ;
  3. crée le premier administrateur RCM rcmadmin avec un mot de passe aléatoire ;
  4. ouvre les ports 7443, 7444 et le port de nœud 7051 dans le pare-feu.

--cluster-pairing on (mode découverte) : sur chaque autre hôte. Le programme d’installation ouvre la fenêtre d’appairage de fbagent pendant 24 heures : le port 7450 et le port de nœud 7051. Tant que la fenêtre est ouverte, un RCM du réseau peut inviter cet hôte dans son cluster. fbagent commence à écouter sur le port 7450 en moins d’une minute.

Sans ces paramètres, le programme d’installation pose lui-même la question : dans l’interface texte, c’est la page Cluster ; avec --no-tui, ce sont deux questions. La réponse par défaut est « non ». --yes sans paramètres de cluster répond aussi « non » aux deux questions.

À la fin, le programme d’installation affiche les lignes RCM: et Pairing:. Sur l’hôte 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

Sur un autre hôte :

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

Il n’y a pas de mot de passe dans la sortie : il est dans le fichier de la ligne Password:. Notez l’empreinte fingerprint de chaque hôte en mode découverte.

Paramètres de cluster du programme d’installation Linux :

Paramètre Ce qu’il fait
--rcm on|off installer RCM et créer un cluster sur cet hôte ; par défaut off
--cluster-pairing on|off mode découverte : ouvrir la fenêtre d’appairage pendant 24 heures ; par défaut off
--pairing-port N port d’appairage du nouveau fbagent, 7450–7459 ; par défaut, le premier libre
--rcm-password-file F mot de passe de l’administrateur RCM pris de la première ligne du fichier F, au lieu d’un mot de passe aléatoire
--cluster-id ID nom de cluster ID au lieu du nom de l’hôte (avec --rcm on)
--cluster-node on|off installer le programme du nœud ; par défaut on
--rcm-allow A,B seuls ces RCM peuvent inviter cet hôte : adresse, réseau CIDR ou nom

Le premier fbagent d’un hôte reçoit le port d’appairage 7450 et les ports de nœud 7051 et 7061. La seconde instance sur le même hôte : 7451, 7052 et 7062.

RCM et la fenêtre d’appairage peuvent être activés plus tard, sans le programme d’installation : dans HQ Monitor, la page Clusters, ou avec des commandes en tant qu’utilisateur 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

Anciens programmes d’installation (fbagent avant 3.1.0) ne posent pas de question sur le cluster : ils installent RCM sur chaque hôte et ouvrent la fenêtre d’appairage partout. Vous avez besoin du RCM d' un hôte ; les RCM des autres hôtes s’arrêtent d’eux-mêmes après la liaison.

Sous Windows. Les mêmes deux choix existent dans le programme d’installation Windows : les paramètres /RCM et /DISCOVERY.

Étape 2. Se connecter à RCM

Ouvrez l’adresse de la ligne RCM: de l’hôte RCM (https://<host>:7444). Connectez-vous avec l’identifiant rcmadmin et le mot de passe du fichier de la ligne Password:. RCM demande aussitôt un nouveau mot de passe (1.5).

Étape 3. Lier les hôtes

Dans RCM, ouvrez Paramètres → Lier les hôtes.

  1. Dans le champ Hôtes, saisissez les adresses ou les noms des hôtes, un par ligne. La première ligne est l’hôte RCM ; il est déjà dans le cluster.
  2. Cliquez sur Vérifier les hôtes. RCM sonde les ports d’appairage 7450–7459 de chaque hôte et affiche la plateforme, la version de Firebird, l’empreinte et l’état. L’hôte RCM n’a pas besoin d’une fenêtre d’appairage. Comparez les empreintes avec la sortie du programme d’installation (la ligne Pairing:).
  3. Sélectionnez le Maître (par défaut, le premier hôte) et cliquez sur Lier.
Lier les hôtes : résultat de la vérification
Lier les hôtes : résultat de la vérification

RCM demande une confirmation et affiche la progression dans la section Progression. Lorsque tous les nœuds sont en cours d’exécution, il indique « Terminé » et affiche le numéro de révision du cluster :

Lier les hôtes : tous les nœuds en cours d'exécution
Lier les hôtes : tous les nœuds en cours d'exécution

La même chose depuis la ligne de commande :

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

Ce qui se passe ensuite :

  1. RCM envoie une invitation à chaque hôte libre.
  2. Le fbagent de l’hôte rejoint le cluster et ferme le port d’appairage. Si l’hôte a son propre RCM sans nœuds, fbagent l’arrête et le désactive, et déplace son cluster vide vers cluster/left/ dans le dossier de fbagent.
  3. RCM enregistre le cluster : nœud <host>-master sur le maître, <host>-replica sur les autres hôtes, port 7051, liens maître → réplique.
  4. Le fbagent de chaque hôte installe et démarre le nœud. RCM attend que tous les nœuds soient en cours d’exécution et affiche En cours d’exécution pour chaque hôte.

États de l’hôte après Vérifier les hôtes :

État Que faire
Prêt à lier rien. Si en dessous il est écrit « Le RCM propre de cet hôte s’arrêtera après la liaison », c’est normal
Dans le cluster l’hôte est déjà dans ce cluster
Erreur unreachable le port 7450 est fermé : la fenêtre d’appairage est désactivée (comme par défaut) ou les 24 heures sont passées. Juste après l’installation, attendez une minute et cliquez de nouveau sur Vérifier les hôtes. Sinon, ouvrez la fenêtre (--cluster-pairing on) et vérifiez le pare-feu
Erreur in_other_cluster l’hôte est dans un autre cluster
Erreur claimed un autre RCM est en train de lier cet hôte
Erreur seats_exceeded plus de 3 sièges

Versions. fbagent installe le nœud uniquement depuis RCM. RCM prend les versions signées dans son dossier import/ (à côté de rcm.json) au démarrage et toutes les 5 minutes. Le programme d’installation y place les versions de l’hôte RCM, et les fbagent des autres hôtes téléchargent eux-mêmes la version de leur plateforme. La liste des versions est en bas de la page Lier les hôtes. Une version peut aussi être importée manuellement (étape 5 ci-dessous).

Manuellement depuis la ligne de commande

Ordre : étapes 1 à 3 sur l’hôte RCM, étape 4 sur chaque autre hôte, étapes 5 et 6 dans RCM.

Étape 1. Installer HQbird avec fbagent

Installez HQbird sur chaque serveur de bases de données et sur l’hôte RCM avec le programme d’installation complet. Sur l’hôte RCM, vous pouvez indiquer --rcm on tout de suite (l’étape 3 n’est alors pas nécessaire). Sur les autres hôtes, n’indiquez pas de paramètres de cluster : par défaut, il n’y a ni RCM ni fenêtre d’appairage. Ne vous enregistrez pas auprès de HQCenter Admin (--enroll).

Sur l’hôte RCM, le programme d’installation laisse le programme RCM dans le dossier de fbagent (update/hqbirdrcm/staged/). Sans lui, l’étape 3 échoue avec l’erreur no hqbirdrcm to install.

Étape 2. Installer la licence liée

Comme au début de la section, « Licence ».

Étape 3. Créer le cluster sur l’hôte RCM

Si le programme d’installation a déjà créé le cluster (--rcm on : une ligne RCM: avec une adresse dans sa sortie), sautez cette étape.

Exécutez la commande en tant qu’utilisateur fbagent (sous Linux, firebird), pas en tant que root : sinon les fichiers de la CA et rcm.json appartiendront à root.

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

Sous Windows (PowerShell en tant qu’administrateur) : .\fbagent.exe --cluster-init shop-prod --address 10.0.0.7

  • shop-prod : nom du cluster : lettres latines minuscules, chiffres et -.
  • --address : l’adresse de l’hôte RCM par laquelle les autres hôtes s’y connectent. Peut être répétée plusieurs fois. Sans le paramètre, les adresses et le nom de l’hôte sont utilisés.

La commande :

  1. crée la CA du cluster et la CA de l’agent (dans le dossier de fbagent, clusterca/<name>/) ;
  2. écrit le certificat RCM, rcm.json et cluster-init.json dans le dossier RCM ;
  3. installe RCM et enregistre le service hqbirdrcm. Sous Linux, le service s’exécute sous un utilisateur distinct hqbirdrcm ;
  4. bascule fbagent vers RCM (cluster.source = rcm) et le redémarre ;
  5. affiche l’adresse RCM et l’empreinte de la CA :
Code
Cluster:    shop-prod
RCM URL:    https://10.0.0.7:7443
CA hash:    sha256:9f86d0...

Notez RCM URL et CA hash : ils sont nécessaires sur les autres hôtes. Relancer pour le même cluster est sans risque : la CA et les clés restent les mêmes.

Connectez-vous tout de suite à RCM et changez le mot de passe de rcmadmin (1.5).

Sous Linux. L’utilisateur hqbirdrcm est dans le groupe fbagent. RCM lit rcm.json par l’intermédiaire de ce groupe, mais ne peut pas l’écrire. Par conséquent, Paramètres → RCM n’enregistre pas les modifications (erreur rcm_config_read_only). Modifiez rcm.json sur l’hôte en tant qu’utilisateur fbagent et redémarrez RCM.

Étape 4. Connecter les fbagent des autres hôtes

  1. Sur l’hôte RCM, créez un jeton d’adhésion pour chaque fbagent : dans RCM Paramètres → Cluster, le bouton Créer un jeton d’adhésion. Ou depuis la ligne de commande :

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

    Le jeton est valable 24 heures, pour un seul fbagent et une seule fois. RCM l’affiche une fois, avec une commande prête à l’emploi.

  2. Sur l’hôte du nœud, exécutez cette commande en tant qu’utilisateur 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

    À la place de --token-file, vous pouvez utiliser --token <token>. Sous Windows, la même chose avec .\fbagent.exe dans PowerShell en tant qu’administrateur.

fbagent vérifie la CA de RCM par l’empreinte. Si l’empreinte ne correspond pas, il s’arrête et n’écrit rien. Ensuite fbagent reçoit son certificat (90 jours, renouvelé automatiquement) et redémarre. Un fbagent connecté est visible dans RCM dans la table Agents. Tant qu’il n’a pas de membres, rien n’est installé sur l’hôte.

Étape 5. Importer les versions dans RCM

fbagent prend le nœud et RCM uniquement depuis RCM. Si la version requise n’est pas dans la liste Versions dans le miroir (Paramètres → Lier les hôtes), importez chaque produit (hqclusternode, hqbirdrcm) pour chaque plateforme de vos hôtes (linux-amd64, windows-amd64). Le fichier de version et la signature .sig sont fournis par le fournisseur.

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 cherche la signature dans <file>.sig, ou indiquez-la avec -sig. Sans signature valide du fournisseur, RCM n’acceptera pas le fichier.
  • Une nouvelle version remplace la précédente. Aucun redémarrage de RCM n’est nécessaire.
  • fbagent vérifie les nouvelles versions toutes les 3 minutes. L’ordre de mise à jour et le verrouillage sont les mêmes que via HQCenter Admin (1.2, « Mises à jour »).

Étape 6. Décrire le cluster

Définissez les membres et les liens dans RCM, Paramètres → Cluster (chapitre 2.3). Après l’enregistrement, fbagent installe les nœuds de la même façon que via HQCenter Admin (1.2, étape 3) : il écrit les certificats, node.json et rcm.json, installe et démarre les services.

Les ports sont au début de la section.

1.4. Installation manuelle

Étape 1. Installer HQbird avec fbagent

Installez HQbird sur chaque serveur de bases de données (avec le même script, mais sans --enroll, ou avec le programme d’installation complet de HQbird). Vérifiez que fbagent est en cours d’exécution.

Notez trois valeurs du agent_config.json de fbagent. Elles sont nécessaires pour node.json :

Champ fbagent Champ node.json Exemple
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 —

Vérification de fbagent (la réponse est le JSON de l’instance Firebird) :

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

Si l’hôte a plusieurs instances HQbird, ne laissez que le service de votre instance dans firebird.update.services de la configuration de fbagent (voir 3.5).

Étape 2. Disposer les fichiers

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

Sous Windows. Le dossier par défaut est C:\hqclusternode, avec la même disposition. Un chemin contenant un espace est autorisé.

Si un hôte a deux nœuds (maître et réplique), donnez à chacun son propre dossier, par exemple /opt/hqclusternode/master et /opt/hqclusternode/replica.

Étape 3. Créer les certificats

Les nœuds et RCM ne communiquent que par mTLS. Il faut une CA et un certificat pour chaque participant. Exécutez ceci une fois sur n’importe quelle machine :

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

La commande crée ca.crt et ca.key, node-a.crt/.key, node-b.crt/.key et rcm.crt/.key. Dans -hosts, indiquez tous les noms et adresses par lesquels on se connectera aux participants.

gencerts et les fichiers qu'il a créés
gencerts et les fichiers qu'il a créés

ca.key est la clé de la CA. Ne la copiez pas sur les hôtes ; conservez-la à part.

Un nouveau nœud s’ajoute plus tard avec -add : il signe la paire avec la même CA, et les autres fichiers restent inchangés :

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

Les certificats sont valables 90 jours. gencerts -out certs -list affiche les dates d’expiration, et gencerts -out certs -renew les renouvelle avec la même clé. Copiez le nouveau .crt sur son hôte : le nœud le prendra en compte sans redémarrage.

Copiez ca.crt et uniquement son propre certificat et sa clé sur chaque hôte.

Étape 4. Écrire node.json

Un fichier par nœud. Exemple pour le maître (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" } ]
}

Le nœud réplique (node-b) a le même fichier, mais avec "role": "replica", ses propres certificats, et le maître node-a dans peers.

Champs principaux :

Champ Valeur
node_id nom du nœud ; le même dans le certificat, dans rcm.json et dans les peers des autres nœuds
role master ou replica
listen_addr adresse de l’API du nœud ; un second nœud sur le même hôte utilise un autre port (:7052)
rcm.url adresse de réception des statistiques RCM ; none : pas de RCM
firebird.* le Firebird et le fbagent de cette instance ; les valeurs fbagent doivent correspondre exactement
firebird.auto_restart si le nœud réplique peut redémarrer Firebird lui-même : auto (par défaut), never, always
windows.restart_window fenêtre de redémarrage de Firebird ; pour le maître la valeur par défaut est 22:00-05:00, pour la réplique c’est toujours
windows.transfer_window fenêtre pendant laquelle l’initialisation s’exécute à pleine vitesse
peers pour le maître, ses répliques ; pour la réplique, son maître
databases dossier des bases de données ; mieux vaut ne pas l’écrire à la main, mais le définir via RCM (chapitre 3)

Les autres champs ont des valeurs par défaut. Le nœud ne démarrera pas si les champs fbagent ne sont pas définis.

Protégez le fichier : il contient le mot de passe et le jeton.

Command
chmod 600 /opt/hqclusternode/node.json

Sous Windows. Écrivez les chemins au format JSON : "C:\\HQbird\\replication.conf". service_name est le nom du service Windows de Firebird.

Étape 5. Écrire 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 : adresse du nœud telle que la voit l’hôte RCM. https uniquement.
  • host : étiquette de l’instance Firebird. Un nœud maître et un nœud réplique avec la même étiquette s’exécutent sur le même Firebird (compagnon, nécessaire pour promouvoir une réplique en maître, chapitre 8). Une étiquette : pas plus d’un maître et d’une réplique.
  • Les chemins relatifs sont résolus à partir du dossier de rcm.json.

Étape 6. Enregistrer les services

Ordre de démarrage : d’abord RCM, puis les répliques, puis le maître.

RCM (Linux) :

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

Nœud (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 crée le service hqclusternode-<role>-p<port>, qui s’exécute sous l’utilisateur firebird. Si le dossier Firebird appartient à root, la commande accorde au groupe firebird l’accès en écriture (avec le bit sticky) et affiche chaque modification : le nœud doit remplacer replication.conf.

Pour svc start, svc stop et svc uninstall, indiquez le même node.json : le nom du service est dérivé du rôle et du port Firebird.

Sous Windows (PowerShell en tant qu’administrateur) :

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

Le service HQClusterNode-<role>-p<port> s’exécute en tant que LocalSystem, démarre automatiquement et redémarre après un échec. Le service du nœud ne dépend pas du service Firebird. Si le nœud a été installé avec la version 2027.1.2–2027.1.9, retirez la dépendance une fois : .\hqclusternode.exe svc fix-deps -config C:\hqclusternode\node.json.

svc install et svc start sous Windows
svc install et svc start sous Windows

Étape 7. Ouvrir les ports

Sur l’hôte du nœud, autorisez les connexions entrantes sur 7051 (le port de listen_addr) depuis les autres nœuds et depuis RCM. Sur l’hôte RCM, autorisez les connexions entrantes sur 7443 depuis tous les nœuds. N’exposez pas les ports 7444 et 13050 à l’extérieur.

Exemple ufw sur l’hôte du nœud :

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

Mise à jour manuelle

Arrêtez le service, remplacez le programme, démarrez le service :

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

La configuration et les certificats ne sont pas modifiés par cela.

1.5. Première connexion à RCM

L’adresse et le mot de passe dépendent de la façon dont RCM a été installé.

Comment RCM a été installé Adresse Identifiant et mot de passe
Par le programme d’installation HQbird ou fbagent --cluster-init (1.3) https://<hôte RCM>:7444 depuis n’importe quel ordinateur rcmadmin et le mot de passe affiché par le programme d’installation (ou le vôtre, depuis --rcm-password-file)
Via HQCenter Admin (1.2) ou manuellement (1.4) http://127.0.0.1:7444, uniquement sur l’hôte RCM rcmadmin, mot de passe strong password (avec un espace)

HTTPS (1.3). Le certificat RCM est signé par la CA du cluster, que le navigateur ne connaît pas, donc il vous avertit. Sur la page de connexion, RCM affiche l’empreinte de la CA. Comparez-la au CA hash affiché par le programme d’installation, et importez la CA dans le navigateur ou dans le système comme racine de confiance : le lien Télécharger le certificat de la CA sur la page de connexion (https://<hôte RCM>:7444/ca.crt, fichier hqcluster-ca.crt). Pour que RCM n’écoute que sur localhost, mettez "operator_addr": "127.0.0.1:7444" dans rcm.json et redémarrez RCM.

HTTP (1.2, 1.4). Depuis un autre ordinateur, connectez-vous par un tunnel SSH :

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

Puis ouvrez http://127.0.0.1:7444 dans votre navigateur.

Page de connexion RCM
Page de connexion RCM

Mot de passe généré. RCM vous demande de le changer à la première connexion : tant que vous ne le changez pas, les autres pages ne s’ouvriront pas. Changez strong password immédiatement (le lien Mot de passe dans l’en-tête).

Changement du mot de passe à la première connexion
Changement du mot de passe à la première connexion

Langue. Sélectionnez Russe dans la liste des langues de l’en-tête de la page (elle est aussi disponible sur la page de connexion). Si vous n’en sélectionnez pas, la langue est prise du navigateur.

Changement des mots de passe et nouveaux utilisateurs

Chaque utilisateur change son propre mot de passe : le lien Mot de passe dans l’en-tête de la page. Il faut le mot de passe actuel et un nouveau d’au moins 12 caractères. Après le changement, les autres sessions de cet utilisateur sont fermées.

Si le programme d’installation a généré un mot de passe, il est écrit dans le fichier clusterca/<name>/rcm-initial-password du dossier de fbagent. Après le changement du mot de passe, fbagent supprime ce fichier lui-même. Ne supprimez pas le fichier initial-admin.json du dossier RCM : il ne contient qu’un hachage. Si le fichier des utilisateurs est perdu et que ce fichier est absent, RCM créera un utilisateur avec le mot de passe par défaut.

Nouveaux utilisateurs. Il n’y a pas de page des utilisateurs dans l’interface. Les utilisateurs sont stockés dans le fichier rcm-data/users.json. Le mot de passe est stocké comme un hachage HA1 : MD5("<name>:hqbirdrcm:<password>").

  1. Calculez le hachage :

    Command
    printf '%s' 'rcmadmin:hqbirdrcm:<new password>' | md5sum
  2. Écrivez-le dans le champ ha1 de l’utilisateur dans users.json. Pour ajouter un utilisateur, ajoutez un autre élément à users :

    json
    { "username": "ivanov", "ha1": "<hash>", "algo": "MD5", "created_at": "2026-11-03T00:00:00Z" }
  3. Redémarrez RCM immédiatement : il ne lit le fichier qu’au démarrage. Lorsqu’un mot de passe est changé dans l’interface, RCM réécrit le fichier depuis la mémoire, et les modifications qu’il n’a pas encore lues seront perdues.

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

Sans champ role, un utilisateur a toutes les permissions. Depuis HQbird 2027.2.31, il existe le rôle "role": "viewer" : consultation seule ; toute demande de modification reçoit 403.

1.6. Comment vérifier l’installation

  • Les services du nœud et de RCM sont en cours d’exécution et ne redémarrent pas en boucle : systemctl status hqclusternode-master-p3050, systemctl status hqbirdrcm.

    systemctl status du nœud
    systemctl status du nœud
systemctl status de RCM
systemctl status de RCM
  • RCM répond (sans mot de passe) : curl http://127.0.0.1:7444/healthz. Lors d’une installation via RCM (1.3), la console fonctionne en HTTPS : curl -k https://127.0.0.1:7444/healthz.

  • Dans RCM, la page Vue d’ensemble affiche tous les nœuds, sans la marque « ne répond pas ».

  • Depuis la ligne de commande sur l’hôte RCM :

    Command
    export RCM_USER=rcmadmin RCM_PASSWORD='<password>'
    ./hqbirdrcm nodes
    ./hqbirdrcm status
  • Le cluster via RCM : Paramètres → Cluster, la section État : chaque membre a appliqué la dernière révision et ne signale aucune erreur. Depuis la ligne de commande : ./hqbirdrcm cluster status.

1.7. Journaux

Quoi Où
Journal du nœud <dossier de node.json>/logs/node-YYYYMMDD.jsonl
Sortie du service du nœud (Linux) journalctl -u hqclusternode-<role>-p<port>
Sortie du service RCM (Linux) journalctl -u hqbirdrcm
Journal de réplication Firebird firebird.replication_log de node.json
Journaux de n’importe quel nœud sans SSH RCM, page Journaux

1.8. Erreurs fréquentes

Ce que vous voyez Cause Que faire
Le nœud ne démarre pas : une erreur sur fbagent_url, fbagent_token ou instance_id fbagent n’est pas en cours d’exécution ou les valeurs ne correspondent pas à agent_config.json vérifiez fbagent avec la commande curl du 1.4, étape 1
Le script d’installation s’est terminé avec le code 2 la demande fbagent n’a pas été approuvée à temps approuvez la demande et relancez le script
Les nœuds n’apparaissent pas via HQCenter Admin fbagent n’est pas dans le cluster, ou le cluster n’a pas encore été obtenu vérifiez le cluster (chapitre 2), attendez jusqu’à 10 minutes
Le nœud dans RCM est « ne répond pas » le port 7051 est fermé, l’url dans rcm.json est incorrecte, l’adresse n’est pas dans le certificat vérifiez les ports et le -hosts des certificats
Pas de connexion à RCM : « Trop de tentatives de connexion échouées » 10 connexions échouées en 5 minutes attendez quelques minutes
La nouvelle version ne s’installe pas la version est dans blocked-versions.json retirez la ligne de la version du fichier
--cluster-init : no hqbirdrcm to install le programme d’installation n’a pas laissé le programme RCM installez HQbird avec le programme d’installation complet (1.3, « Manuellement », étape 1)
--cluster-join : token_used, token_expired, token_revoked le jeton a déjà été utilisé, a plus de 24 heures ou a été révoqué créez un nouveau jeton (1.3, « Manuellement », étape 4)
--cluster-join : hostname_conflict le cluster a un fbagent avec le même nom d’hôte et des adresses différentes donnez des noms différents aux hôtes
--cluster-join : this agent is in cluster … from goafts fbagent est déjà dans le cluster HQCenter Admin retirez-le du cluster HQCenter Admin
Le nœud ne s’installe pas via RCM RCM n’a pas de version pour cette plateforme hqbirdrcm release list, importez la version (1.3, « Manuellement », étape 5)

2. Configuration du cluster

Dans ce chapitre, vous définissez quels nœuds sont dans le cluster et quel maître envoie des segments à quelle réplique. Ensuite vous configurez les nœuds et les utilisateurs de RCM.

Les relations se définissent de l’une de ces trois façons :

Nœuds installés Où les relations sont définies Section
via HQCenter Admin dans HQCenter Admin : la page Clusters de HQ Monitor ou l’API HQCenter Admin 2.2
via RCM, sans HQCenter Admin dans RCM : Paramètres → Cluster, hqbirdrcm cluster ou la page Clusters de HQ Monitor 2.3
manuellement dans RCM : Paramètres → RCM et Paramètres → Nœuds 2.3

Sur les nœuds installés via HQCenter Admin ou via RCM, changez les relations uniquement dans la description du cluster. fbagent écrase node.json et rcm.json selon la description du cluster. Modifier les relations dans Paramètres → RCM ou Paramètres → Nœuds de RCM est rejeté (409 cluster_managed). Les versions antérieures de RCM l’acceptaient, mais cela était perdu.

2.1. Rôles et schémas

Chaque nœud a un rôle : maître ou réplique. Deux nœuds, un maître et une réplique, peuvent s’exécuter sur une seule instance Firebird.

Schémas pris en charge :

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

Le lien va toujours du maître vers la réplique. RCM relie la base de données du maître à sa réplique par le GUID de base de données, pas par le nom du nœud.

Compagnon. Un nœud maître et un nœud réplique sur la même instance Firebird sont des compagnons. La promotion d’une réplique en maître (chapitre 8) ne fonctionne que pour une telle paire. Dans rcm.json, la paire est marquée par une valeur host identique.

2.2. Liens via HQCenter Admin

Où décrire un cluster

  • HQ Monitor, page Clusters (administrateurs uniquement ; la livraison de la configuration doit être activée). La façon habituelle.
  • API HQCenter Admin : POST /v1/admin/clusters et PUT /v1/admin/clusters/{id}. Le panneau HQCenter Admin n’a pas de page des clusters.

``

Étapes sur la page Clusters

  1. Saisissez un Identifiant du nouveau cluster (lettres latines minuscules, chiffres et -) et cliquez sur Créer.
  2. Ajoutez des membres (Membres). Pour chacun, indiquez :
    • le fbagent de l’hôte ;
    • le rôle : master, replica ou rcm ;
    • les adresses de l’hôte ;
    • le port : pour un nœud, 7051 (un second nœud sur le même hôte, par exemple 7052) ; pour RCM, le port d’entrée des statistiques 7443.
  3. Ajoutez des liens (Liens de réplication) du maître vers la réplique.
  4. Cliquez sur Valider, puis sur Enregistrer.

Si un autre administrateur a modifié le cluster en même temps, la page vous demandera de recharger le cluster et de répéter la modification.

Règles

  • Un fbagent ne peut appartenir qu’à un seul cluster.
  • Sur un seul fbagent : pas plus d’un maître, d’une réplique, d’un RCM et d’un routeur. Le routeur (rôle router, à partir de HQbird 2027.2.30) n’a pas de liens et n’occupe pas de siège de licence (chapitre 8.7).
  • Un cluster a exactement un RCM. Le fbagent de l’hôte RCM exécute l’autorité de certification (CA) du cluster.
  • Le nom du membre (member_id) : lettres latines, chiffres, -. Le nom, le fbagent et le rôle d’un membre ne peuvent pas être changés. Pour déplacer un membre vers un autre hôte, créez un nouveau membre avec un nouveau nom. Ne réutilisez pas l’ancien nom.
  • Chaque réplique doit avoir un lien vers le maître.
  • HQCenter Admin construit lui-même l’adresse du nœud : https://<première adresse>:<port>.
  • HQbird 2.5/3.0 : définissez la date replconf_valid_till du cluster (YYYY-MM-DD) : la configuration du greffon replconf est valable jusqu’à cette date.

Exemple via 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"}]}
  • Créer : POST /v1/admin/clusters (le document peut être envoyé avec les membres). Remplacer tout le document : PUT /v1/admin/clusters/{id}.
  • PUT exige l’en-tête If-Match: <revision> (la révision est fournie par GET et ETag). Sans l’en-tête : 428 ; avec une ancienne révision : 409 ; avec une erreur dans le document : 422 avec une liste d’erreurs.
  • POST /v1/admin/clusters/{id}/validate valide le document sans l’enregistrer.
  • GET /v1/admin/clusters/{id}/status affiche l’état des membres et les dates d’expiration des certificats.

Ce qui se passe après l’enregistrement

  1. Le fbagent de chaque membre reçoit le cluster. Dans le cluster, une vérification toutes les 60 secondes (le fbagent de l’hôte RCM, toutes les 30 secondes). Hors d’un cluster, un fbagent apprend l’existence du cluster à son prochain sondage de configuration. Si ce sondage n’atteint pas le serveur, la vérification a lieu toutes les 10 minutes.
  2. Chaque fbagent crée une clé et envoie une demande de certificat. Le fbagent de l’hôte RCM la signe. RCM signe son propre certificat sans demande.
  3. fbagent écrit dans node.json : nom, rôle, adresse, peers (à partir des liens), l’adresse RCM, les chemins des certificats, les données Firebird et fbagent. Dans rcm.json : la liste des nœuds (nodes), la liste des routeurs (routers), l’adresse d’entrée des statistiques et les chemins des certificats. fbagent ne touche pas aux autres champs des fichiers.
  4. fbagent installe et démarre les services (chapitre 1).

Modification d’un cluster :

Ce qui a changé Ce que fait fbagent
seulement les peers d’un nœud en cours d’exécution les transmet au nœud sans redémarrage
d’autres champs d’un nœud arrête le nœud, écrit le fichier, démarre le nœud, dans windows.transfer_window du nœud (non défini : immédiatement)
rcm.json redémarre RCM immédiatement
certificats ou CA redémarre le service
un membre est retiré arrête et retire le service ; cluster-managed.json → cluster-removed.json, le programme → *.removed ; la configuration, les certificats et les données restent

Après le retrait d’un nœud, sa section # BEGIN managed-by:<name> … # END … reste dans le replication.conf partagé. Supprimez-la à la main et redémarrez Firebird via RCM.

Approbation des certificats du cluster

Par défaut, le fbagent de l’hôte RCM signe lui-même les demandes (auto). L’approbation manuelle peut être activée. Commandes sur l’hôte 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>

En mode manual, un nouveau membre ou une nouvelle clé attend l’approbation. Le renouvellement d’un certificat avec une clé connue est signé automatiquement.

2.3. Liens via RCM

Cluster RCM (sans HQCenter Admin)

Si le cluster a été créé par le programme d’installation HQbird ou par la commande fbagent --cluster-init (chapitre 1.3), la description du cluster est stockée par RCM. La façon la plus simple d’ajouter des hôtes est la page Paramètres → Lier les hôtes (chapitre 1.3, « Lier les hôtes dans RCM ») : RCM crée lui-même les membres et les liens. Les règles sont les mêmes que dans HQCenter Admin (2.2, « Règles »), plus :

  • dans RCM il y a un cluster ; le membre rcm existe toujours et ne peut pas être supprimé ;
  • pas plus de 3 sièges (hôtes avec des nœuds maître ou réplique), sinon l’erreur seats_exceeded se produit ;
  • un membre ne peut être ajouté que sur un fbagent qui s’est connecté à RCM (chapitre 1.3 : « Lier les hôtes » ou « Manuellement », étape 4).

Étapes sur la page Paramètres → Cluster :

  1. Dans la table Agents, cliquez sur Ajouter un membre dans la ligne du fbagent.
  2. Indiquez le rôle (master, replica ou router), member_id, les adresses et le port. La page suggère le nom <host>-<role> et le port : 7051 pour le premier nœud du fbagent, 7061 pour le second. RCM rejette un port déjà pris par un autre membre de l’hôte. Les adresses du fbagent sont des boutons : cliquez pour ajouter une adresse.
  3. Dans la section Liens, cliquez sur Ajouter un lien du maître vers la réplique.
  4. Cliquez sur Valider : RCM affichera les erreurs et les avertissements.
  5. Cliquez sur Enregistrer. La page affichera la liste des modifications et demandera une confirmation. Si des membres sont supprimés, la fenêtre est rouge.

Avant l’enregistrement, les modifications n’existent que sur la page (l’étiquette « Non enregistré »). Si quelqu’un a enregistré le cluster en même temps, la page proposera de le recharger. Si seuls des champs RCM ont changé (révision, CA, commissions), la page enregistrera votre modification elle-même.

Autres sections de la page :

Section Ce qu’il y a
en-tête nom du cluster, révision, CA du cluster et CA de l’agent ; le bouton Exporter pour l’ancienne CA
Jetons de connexion créer un jeton pour un nouveau fbagent, révoquer un jeton inutilisé
Document JSON le document entier dans un champ de texte ; Valider et Enregistrer l’utilisent
Clés et CA commissions : nouvelle clé de membre (rekey), nouvelle CA du cluster (rotate_ca), nouvelle CA de l’agent (rotate_agent_ca) ; indisponibles lorsqu’il y a des modifications non enregistrées
État la révision que chaque membre a appliquée, l’expiration du certificat, le service, la dernière erreur

Depuis la ligne de commande sur l’hôte 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

Le format du document est celui de 2.2, « Exemple via l’API ». apply avec une ancienne révision obtient 409 : exécutez de nouveau show. RCM conserve les 20 dernières révisions dans rcm-data/cluster/history/.

HQ Monitor. La page Clusters fonctionne aussi avec RCM. Sur l’hôte RCM, HQ Monitor accède à RCM par le fbagent de cet hôte, avec le certificat fbagent : l’utilisateur et le mot de passe RCM ne sont pas nécessaires. Dans le journal d’audit RCM, ces actions sont enregistrées comme agent:<id> (<user>). Une autre façon, pour les versions antérieures de RCM : dans la configuration de HQ Monitor, définissez rcm_admin_url (http://127.0.0.1:7444), rcm_admin_user (l’utilisateur RCM) et rcm_admin_password_file (un fichier avec son mot de passe).

Après l’enregistrement, tout se passe comme via HQCenter Admin (2.2, « Ce qui se passe après l’enregistrement »). RCM relit nodes dans rcm.json lui-même, sans redémarrage.

Retirer un fbagent du cluster : supprimez ses membres et enregistrez, puis cliquez sur Révoquer dans la table Agents (ou ./hqbirdrcm cluster revoke -agent <id>). Pour le ramener, un nouveau jeton est nécessaire. Après la révocation, le fbagent (depuis la version 3.1.0) quitte le cluster lui-même : il arrête ses nœuds et supprime les données du cluster. La même chose se fait sur un hôte de nœud avec la commande fbagent --cluster-leave. Sur l’hôte RCM, elle est rejetée.

Installation manuelle : ajouter un nœud à RCM

  1. Paramètres → RCM, la table Nœuds connectés.
  2. Cliquez sur Ajouter un nœud. Remplissez node_id, url (https://<adresse>:7051), le rôle, host (étiquette de l’instance Firebird), server (uniquement pour le regroupement à l’écran).
  3. Cliquez sur Valider dans la ligne du nœud : RCM vérifiera la connexion et les permissions.
  4. Cliquez sur Enregistrer. RCM écrira rcm.json et conservera l’ancien fichier sous rcm.json.<heure UTC>.bak (les 20 derniers).
  5. Redémarrez RCM. Jusqu’au redémarrage, l’ancienne configuration est en vigueur ; la page montre quels champs attendent un redémarrage.
Paramètres → RCM
Paramètres → RCM
Command
sudo systemctl restart hqbirdrcm

Vous pouvez aussi le faire sans l’interface : modifiez rcm.json et redémarrez RCM.

Installation manuelle : lier maître et réplique

Le lien doit être enregistré des deux côtés :

  1. Paramètres → Nœuds, sélectionnez le nœud maître.
  2. Dans la section Pairs, cliquez sur Ajouter un pair : le node_id de la réplique, son url, la compression (zstd).
  3. Cliquez sur Enregistrer. RCM affichera la liste des modifications et demandera une confirmation. La modification de peers prend effet immédiatement.
  4. Répétez pour le nœud réplique : son pair est le maître.
Section Pairs du nœud maître
Section Pairs du nœud maître

Si le pair n’est pas enregistré d’un des côtés, RCM ne proposera pas ce nœud réplique lors de l’initialisation de la base de données.

2.4. Paramètres du nœud

Paramètres → Nœuds affiche les paramètres de node.json que le nœud autorise à modifier depuis RCM. Seuls les champs modifiés sont enregistrés, après une fenêtre qui énumère les modifications.

Paramètres → Nœuds : sélection d'un nœud
Paramètres → Nœuds : sélection d'un nœud
Paramètres de bases de données du nœud avec des marques « après analyse »
Paramètres de bases de données du nœud avec des marques « après analyse »

Chaque ligne indique quand la modification prendra effet :

Quand Quels paramètres
Immédiatement channel_a_mbps, channel_a_burst_mbps, windows.restart_window, peers ; depuis HQbird 2027.2.24, paramètres de vérification des données (limits.data_check_*) ; depuis HQbird 2027.2.31, advertise_addr
Après le redémarrage du nœud les autres limites, windows.transfer_window ; la page les affiche sur une ligne séparée jusqu’au redémarrage du nœud
Après l’analyse databases.*, exclude_filter ; si replication.conf a changé, un redémarrage de Firebird est nécessaire (chapitre 3.5)

Lecture seule (modifiés dans node.json sur l’hôte du nœud) : firebird (y compris le mot de passe et auto_restart), rcm, tls, segments, l’adresse listen_addr.

Paramètres principaux :

Paramètre Par défaut Signification
windows.restart_window maître 22:00-05:00, réplique : toujours quand le nœud peut redémarrer Firebird ; le Firebird maître ne se redémarre jamais lui-même
windows.transfer_window 23:00-05:00 fenêtre pendant laquelle l’initialisation s’exécute au débit reinit_window_mbps
limits.channel_a_mbps 50 débit de transfert des segments, Mo/s (channel_a_burst_mbps : pic de courte durée, 200)
limits.reinit_window_mbps 100 débit d’initialisation dans la fenêtre de transfert, Mo/s
limits.reinit_day_disk_fraction 0.5 fraction de la vitesse de disque mesurée pour l’initialisation hors de la fenêtre
limits.retention_days 2 combien de jours conserver les segments envoyés dans l’archive du maître
limits.free_space_floor_gb 1 espace libre minimum, Go ; en dessous, la réplique n’accepte pas les segments
limits.max_concurrent_reinits 1 combien d’initialisations le nœud exécute en même temps

Les détails sur la vitesse et la conservation de l’archive sont aux chapitres 5 et 7.

firebird.auto_restart (dans node.json uniquement) détermine si un nœud réplique peut redémarrer Firebird lui-même :

Valeur Comportement
auto (par défaut) peut, si ce Firebird ne sert pas de bases de données maîtres
never jamais
always toujours, même si ce Firebird héberge des bases de données maîtres

Via HQCenter Admin. Le windows.transfer_window du nœud fbagent sert aussi de fenêtre pour redémarrer le service du nœud lui-même lorsque le cluster change. Si la fenêtre n’est pas définie dans node.json, fbagent redémarre le service immédiatement.

2.5. Plusieurs instances HQbird sur un hôte

fbagent redémarre les services énumérés dans firebird.update.services de sa configuration. Une liste vide signifie tous les services HQbird de l’hôte. Ne laissez dans la liste que le service de votre propre instance. Le nœud ne voit pas ce paramètre et écrit un avertissement fbagent_shared dans le journal si fbagent connaît plus d’une instance.

2.6. Mot de passe SYSDBA

Le nœud se connecte à Firebird avec l’utilisateur et le mot de passe de firebird.user et firebird.password dans node.json. fbagent conserve sa propre copie du mot de passe. Si vous avez changé le mot de passe SYSDBA :

  1. Corrigez firebird.password dans le node.json de chaque nœud de cette instance (maître et réplique).
  2. Corrigez le mot de passe dans la configuration de fbagent et rechargez-la (voir la documentation de fbagent).
  3. Redémarrez les services du nœud.

Sinon, les pages de publication et de vérification de RCM afficheront une erreur de connexion (SQLSTATE 28000).

2.7. Utilisateurs RCM et audit

  • Les utilisateurs sont dans le fichier rcm-data/users.json (chapitre 1.5). Sans rôle, un utilisateur a tous les droits ; le rôle viewer (depuis HQbird 2027.2.31) est la consultation seule.
  • Une session dure 12 heures après la dernière action.
  • Après 10 connexions échouées en 5 minutes, la connexion de cet utilisateur et de cette adresse est temporairement bloquée. Une connexion réussie remet le compteur à zéro.
  • Le journal d’audit est le fichier rcm-data/audit.jsonl : une ligne JSON pour chaque modification, connexion et déconnexion. Il n’y a pas de journal d’audit dans l’interface.
  • La page Commandes montre l’auteur de chaque commande.

2.8. Licence

Une fois par minute, le nœud maître lit la licence fbagent de son hôte. S’il n’y a pas de licence (la période d’essai est terminée, la licence a expiré ou n’est pas valide), le nœud cesse d’envoyer les segments de toutes les bases de données du maître. Firebird et les bases de données continuent de fonctionner, mais les répliques cessent de recevoir les modifications.

Ce que vous voyez dans RCM :

  • le maître est rouge (NEEDS_ATTENTION), avec le badge « pas de licence : envoi arrêté » ;
  • il n’y a pas de bouton Reprendre : seule la licence lève la pause ;
  • sur la réplique : « ne reçoit plus depuis … : le maître n’a pas de licence » ;
  • dans la table Nœuds, un badge « pas de licence » ; dans Paramètres → Nœuds, le bloc de licence fbagent ;
  • les alertes license_paused et license_pause_archive_released ;
  • l’initialisation est interdite (license_paused).
Bloc de licence fbagent dans Paramètres → Nœuds
Bloc de licence fbagent dans Paramètres → Nœuds

Installez la licence dans fbagent. Le nœud lève la pause de lui-même en moins d’une minute. Le maître conserve l’archive pour les répliques pendant limits.retention_days (2 jours par défaut) à partir du début de la pause. Si vous installez la licence plus tard, les répliques devront être initialisées de nouveau.

Cluster via RCM, sans HQCenter Admin. Une licence flottante sans HQCenter Admin cesse de fonctionner après online_check_days plus les jours de grâce. Chaque fbagent du cluster a besoin d’une licence liée (fbagent --license-request, puis fbagent --license-install, chapitre 1.3, « Licence »). Après la période d’essai, fbagent n’ajoutera pas de nouveau nœud ni de RCM sans la fonction cluster dans la licence ; il n’interdit jamais les mises à jour. Pour HQbird 2.5/3.0, la date replconf_valid_till dans RCM ne peut pas être postérieure à la fin de la licence plus les jours de grâce sur les nœuds fbagent (erreur replconf_after_license).

2.9. Comment vérifier

  • Vue d’ensemble : tous les nœuds sont présents et regroupés par serveur.

    Vue d'ensemble du cluster
    Vue d'ensemble du cluster
  • Paramètres → Nœuds : le maître a une réplique dans Pairs, et la réplique a le maître.

  • Paramètres → RCM : le bouton Vérifier de la ligne de chaque nœud réussit.

  • Rapport du cluster en un seul fichier :

    Command
    ./hqbirdrcm report -o report.json

2.10 Erreurs fréquentes

Ce que vous voyez Cause Que faire
La modification des pairs dans RCM est rejetée (409 cluster_managed) ou perdue après le redémarrage du nœud le nœud a été installé via HQCenter Admin ou via RCM changez les liens dans la description du cluster (2.2, 2.3)
seats_exceeded lors de l’enregistrement du cluster dans RCM des nœuds sur un quatrième hôte pas plus de 3 hôtes avec des nœuds
Paramètres → RCM : rcm_config_read_only cluster via RCM sous Linux : rcm.json appartient à fbagent modifiez rcm.json en tant qu’utilisateur fbagent et redémarrez RCM
Révoquer l’agent ne fonctionne pas (agent_has_members) fbagent a des membres supprimez d’abord les membres et enregistrez
Le nœud réplique n’est pas proposé pendant l’initialisation le pair n’est pas enregistré d’un des côtés ajoutez le pair des deux côtés (2.3)
Une modification dans Paramètres → RCM ne prend pas effet RCM n’a pas été redémarré redémarrez RCM
422 lors de l’enregistrement du cluster dans HQCenter Admin une erreur dans le document corrigez-la selon la liste errors, vérifiez via validate
409 lors de l’enregistrement du cluster le cluster a été modifié par quelqu’un d’autre relisez le cluster et réessayez
Un nouveau membre du cluster HQCenter Admin ne reçoit pas de certificat approbation manuelle sur l’hôte RCM fbagent --cluster-ca-approve <id>
Erreur SQLSTATE 28000 sur les pages de publication le mot de passe SYSDBA a été changé 2.6

3. Ajouter une base de données au maître

Dans ce chapitre, la base de données maître passe sous le contrôle du nœud. Le nœud l’inscrit dans replication.conf et crée les dossiers des segments. Après le redémarrage de Firebird, la base de données est prête pour la réplication.

La création de la réplique correspond aux étapes suivantes (publication, initialisation). Elles sont décrites aux chapitres 4 à 6.

Les noms des boutons sont donnés selon l’interface russe de RCM, avec les noms anglais entre parenthèses.

3.1. Comment un nœud découvre les bases de données

Le nœud maître cherche les bases de données dans un seul dossier, la racine des bases de données (databases.root). Ce qui passe sous gestion est décidé par des règles :

Règle Champ Par défaut
Dossier des bases de données root non défini
Chercher dans les sous-dossiers recursive oui
Masque d’inclusion template *.fdb
Masque d’exclusion exclude_mask aucun
Taille du fichier, Mo min_size_mb, max_size_mb pas de limites (0)
Tables pour la comparaison des données sync_tables avec HQbird 2027.2.24, tables de la publication de la base ; s’il n’y en a pas, RDB$FIELDS ; en 2027.5.7, RDB$FIELDS
Liste d’inclusion include_paths vide (mode modèle)
Liste d’exclusion exclude_paths vide

Le chemin root est un chemin sur l’hôte du nœud, pas sur l’hôte RCM. Le nœud applique d’abord le masque d’inclusion, puis le masque d’exclusion, puis la taille.

Les règles sont les mêmes pour tout le nœud. La liste sync_tables est aussi partagée : la vérification (chapitre 5.10) cherche chaque table de la liste dans chaque base du nœud qui n’a pas sa propre liste.

Tables pour la comparaison, avec HQbird 2027.2.24. Chaque base peut avoir sa propre liste (Tables de suivi de la synchronisation). Le nœud la stocke dans databases.sync_tables_by_db. La vérification prend la première liste qui est définie :

  1. la liste propre de la base ;
  2. la liste partagée sync_tables du nœud ;
  3. les tables de la publication de la base ;
  4. RDB$FIELDS.

Une liste partagée enregistrée plus tôt a priorité sur la publication : une base sans liste propre l’utilise. La page de la base du maître montre quelle liste est en vigueur (3.3).

Une table absente à la fois de la base primaire et de la réplique reçoit l’état « pas dans la base » (absent) : elle n’est pas comparée, et la vérification n’affichera pas « Pas correct » à cause d’elle. Une table qui manque d’un seul côté est un écart.

RCM et nœud 2027.5.7. Il y a une seule liste pour tout le nœud (sync_tables) ; sans liste, la vérification utilise RDB$FIELDS. Une table absente est une erreur, et la vérification de la base affichera « Pas correct ».

Toutes les règles sont stockées dans le node.json du nœud. Le nœud les applique à chaque analyse.

Mode modèle et mode liste :

  • Mode modèle (liste d’inclusion vide) : le nœud prend tous les fichiers correspondant au masque, sauf ceux qui sont exclus. Un nouveau fichier du dossier sera pris automatiquement par le nœud à l’analyse suivante.
  • Mode liste (liste d’inclusion non vide) : le nœud ne prend que les fichiers de la liste. Un nouveau fichier ne passera pas sous gestion automatiquement : il faut l’ajouter.

Choisissez le mode liste si le dossier contient des copies de bases, des bases de test ou d’autres fichiers qui n’ont pas besoin d’être répliqués.

3.2. Avant de commencer : vérifier les permissions

L’utilisateur sous lequel s’exécutent Firebird et le nœud (firebird sous Linux, LocalSystem sous Windows) doit avoir les permissions de lecture et d’écriture sur :

  • le dossier racine des bases et les fichiers des bases ;
  • replication.conf et son dossier (le nœud remplace le fichier via un fichier temporaire) ;
  • les dossiers de segments <database>.ReplLog et <database>.LogArch (le nœud les crée lui-même).

RCM vérifie les permissions avant l’enregistrement (preflight). Si la vérification échoue, la commande se termine avec l’erreur preflight failed on <node> et une liste de chemins.

Vérification sur l’hôte du nœud (Linux) :

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

3.3. Page d’inscription des bases de données

Inscription des bases de données : formulaire et aperçu
Inscription des bases de données : formulaire et aperçu
  1. Ouvrez la page d’inscription du nœud maître. Le lien est disponible à deux endroits :

    • Bases de données → table Nœuds → colonne des actions → Inscrire ;
    • Vue d’ensemble → carte du nœud maître → Inscrire des bases de données.

    Un nœud réplique n’a pas cette page.

  2. Le formulaire affiche les règles actuelles du nœud (le nœud les a envoyées lui-même). Si le nœud ne répond pas, les boutons d’aperçu et d’inscription sont désactivés : sans les règles actuelles ils remettraient à zéro les listes d’inclusion et d’exclusion.

  3. Remplissez ou corrigez les champs : Chemin du dossier sur ce serveur, récursif, masques, Filtre de taille, Tables de suivi de la synchronisation.

    Le champ Tables de suivi de la synchronisation :

    • avec HQbird 2027.2.24 et ultérieur, la liste est par base que cette action inscrira. Champ vide : la base utilise les tables de sa propre publication. L’inscription ne change pas la liste partagée du nœud (sync_tables). Si elle existe, le formulaire le dit : une base sans liste propre l’utilise plutôt que la publication. La liste d’une base déjà gérée se définit sur sa page : Bases de données → base maître → bloc Tables de suivi de la synchronisation. Le bloc montre quelle liste est en vigueur. Un champ vide retire la liste propre de la base ;
    • dans RCM et le nœud 2027.5.7, une seule liste pour toutes les bases du nœud (sync_tables).
  4. Cliquez sur Aperçu. Le nœud affichera tous les fichiers correspondant au masque d’inclusion. Il ne change rien.

  5. Vérifiez la liste. Chaque fichier a une case :

    • cochée : le fichier sera géré ;
    • cochée, verrouillée, marquée déjà géré : la base est déjà inscrite ;
    • verrouillée avec un motif : le fichier est exclu par le masque, la taille ou la liste d’exclusion. Pour le prendre, changez la règle.
  6. Cochez les bases nécessaires et cliquez sur Inscrire la sélection. RCM demandera une confirmation et affichera le nombre de fichiers.

Confirmation de l'inscription
Confirmation de l'inscription

Ce que fait ce bouton :

  • en mode modèle, les fichiers sans case sont ajoutés à la liste d’exclusion, les fichiers avec une case en sont retirés ;
  • en mode liste, les fichiers avec une case sont ajoutés à la liste d’inclusion.

Le bouton ajoute des bases à celles qui sont déjà sous gestion. Il ne change pas les lignes verrouillées. 7. Le bouton Inscrire applique le formulaire sans changer les listes. 8. Attendez le message de fin et le nombre de bases ajoutées. S’il n’y a pas de réponse pendant longtemps, vérifiez le résultat sur la page Commandes.

Avec HQbird 2027.2.24 et ultérieur, le message est « Inscrites : N ». S’il faut redémarrer le Firebird du maître, RCM indique quel bouton presser (en général Redémarrer le Firebird du maître dans la ligne de la base) et fournit un lien vers les bases maîtres. RCM 2027.5.7 peut dire « Aucune nouvelle base adaptée », même si des bases ont été ajoutées : vérifiez la page Bases de données.

Résultat de l'inscription
Résultat de l'inscription

Si aucune base n’a été trouvée après l’inscription, mais que le nœud avait déjà des bases, le nœud refuse (409) et rend les anciennes règles. Ainsi, une erreur de chemin ne désactive pas la réplication de toutes les bases.

La même chose depuis la ligne de commande

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

Remarque : la commande n’envoie que les champs de ses paramètres. Le nœud remettra à zéro les autres règles (masques, tailles, listes d’inclusion et d’exclusion, sync_tables). La commande n’a pas de paramètres pour ces règles. Avant d’exécuter la commande, vérifiez les règles actuelles (hqbirdrcm getconfig -node node-a). Si elles sont définies, utilisez la page d’inscription.

3.4. Ce qui se passe après l’enregistrement

  1. Le nœud écrit les règles dans node.json.
  2. Le nœud analyse le dossier (scansync).
  3. Pour chaque base trouvée, le nœud écrit un bloc dans sa propre zone de replication.conf (entre les lignes # BEGIN managed-by:node-a role:master et # END …) et crée les dossiers <database>.ReplLog et <database>.LogArch. Le nœud ne modifie pas le texte en dehors de sa propre zone.
  4. Avant de faire une modification, le nœud enregistre une copie du fichier : replication_YYYYMMDD_hhmmss_NNN.conf.
  5. Si replication.conf a changé, les bases passent à l’état PENDING_RESTART : Firebird ne lira le nouveau fichier qu’après un redémarrage. Dans la table Nœuds, cela apparaît dans la colonne Redémarrage en attente.
La colonne « Redémarrage en attente » dans la table « Nœuds »
La colonne « Redémarrage en attente » dans la table « Nœuds »

États d’une nouvelle base :

État Groupe dans RCM Signification
UNCONFIGURED En attente base trouvée, configuration pas encore écrite
PENDING_RESTART En attente configuration écrite, redémarrage de Firebird nécessaire
CONFIGURED En attente Firebird redémarré, base prête pour la publication et l’initialisation

3.5. Redémarrer le Firebird du maître

Le nœud maître ne redémarre jamais Firebird de lui-même. RCM non plus. Redémarrer le maître est la décision de l’opérateur : un redémarrage coupe toutes les connexions vers toutes les bases de cette instance Firebird.

Choisissez un moment de faible charge et cliquez sur l’un des boutons :

  • Redémarrer le Firebird du maître, sur la page Bases de données, dans la ligne du maître de la base qui attend un redémarrage ;
  • le même bouton dans la fenêtre Initialiser, chapitre 5 ;
  • Redémarrer Firebird, sur la page de la base.

RCM demandera une confirmation. Il affiche le nom du nœud et un avertissement : Firebird redémarrera immédiatement, sans fenêtre de redémarrage, et toutes les connexions seront coupées.

Confirmation du redémarrage du Firebird du maître
Confirmation du redémarrage du Firebird du maître

La même chose depuis la ligne de commande

Command
hqbirdrcm restartfirebird -node node-a

Cette commande redémarre aussi immédiatement, sans fenêtre de redémarrage.

Comment le nœud redémarre Firebird :

  1. Il vérifie que fbagent répond et gère la même instance (identifiant, port, nom du service de node.json). Si une valeur ne correspond pas, le nœud refuse.
  2. Il demande à fbagent de redémarrer Firebird.
  3. Il attend que Firebird réponde sur son port.
  4. Il fait passer les bases de PENDING_RESTART à CONFIGURED.

Plusieurs instances HQbird sur un hôte. fbagent redémarre les services énumérés dans firebird.update.services de sa configuration. Une liste vide signifie tous les services HQbird de l’hôte. S’il y a deux instances HQbird sur l’hôte, ne laissez dans la liste que le service de votre instance. Sinon, le redémarrage d’un nœud arrêtera aussi l’autre instance.

Sous Windows. Si replication.log a atteint log_portion_mb ou plus, le redémarrage se déroule ainsi : arrêter Firebird → archiver le journal → démarrer.

3.6. Une base déjà répliquée à la main

Si la réplication est déjà configurée à la main pour une base (son propre bloc dans replication.conf, publication activée, segments en circulation), elle peut être mise sous gestion sans réinitialiser la réplique. Pour cela il existe un mode detect_existing (maître uniquement).

  1. Lancez un aperçu :

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

    Dans la réponse, taken_over énumère les bases qui seront migrées. Ajoutez -verbose pour voir les bases ignorées avec le motif.

  2. Si la liste est correcte, exécutez la commande sans -dry-run.

Le nœud ne migre un bloc que si :

  • les dossiers de segments s’appellent exactement <database>.ReplLog et <database>.LogArch ;
  • des segments existent déjà dans l’archive ;
  • la publication est activée dans la base.

Le nœud ne migre pas un bloc avec des chemins différents et le signale comme « trouvé mais non pris en charge ».

Après la migration, les bases reçoivent PENDING_RESTART, même si les paramètres de réplication ne changent pas : seule la position du bloc dans le fichier change. Redémarrez Firebird dans une fenêtre de maintenance.

3.7. Comment vérifier

  • Bases de données : la base est visible dans la ligne du nœud maître, état CONFIGURED (après le redémarrage).

  • À côté de la base, il peut y avoir une icône publication désactivée : la publication n’est pas encore activée. C’est normal ; la publication est l’étape suivante (chapitre 6).

    Nouvelle base dans la ligne du maître
    Nouvelle base dans la ligne du maître
  • Sur l’hôte du nœud : le bloc de la base est présent dans replication.conf à l’intérieur de la zone managed-by:node-a, et à côté de la base se trouvent les dossiers .ReplLog et .LogArch.

3.8. Retirer une base de la gestion

La façon habituelle est le bouton. Sur la page Bases de données, cochez les bases, sélectionnez l’action groupée Retirer de la gestion et cliquez sur Appliquer à la sélection. RCM :

  1. ajoute les fichiers à la liste d’exclusion du nœud ;
  2. analyse le dossier une fois : les blocs de la base sont retirés de replication.conf ;
  3. supprime les enregistrements de la base dans le nœud.

Les fichiers de la base et les dossiers de segments restent sur le disque. Firebird n’est pas redémarré. Firebird continue d’écrire les segments de la base jusqu’à son prochain redémarrage ; RCM dira si un redémarrage est nécessaire.

RCM refusera (has_replicas) pour une base maître qui a une réplique vivante : sinon la réplique s’arrêterait en silence. Transformez d’abord la réplique en base ordinaire ou retirez-la (chapitre 8).

Ne supprimez pas à la main le bloc de la base dans replication.conf : à l’analyse suivante, le nœud l’écrira de nouveau.

Si le fichier de la base a disparu ou a été exclu par une règle. Alors la base reçoit l’état ORPHANED (le groupe Orphelines). Le nœud conserve son enregistrement et l’archive des segments : une base absente est plus souvent une erreur qu’une décision. Si le fichier revient, la base fonctionne de nouveau et l’alerte est effacée. Pour supprimer définitivement une telle base, effectuez deux étapes dans cet ordre :

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>

Après forgetdatabase, la commande cleanuparchive ne trouvera plus la base. Les deux commandes ne fonctionnent que pour une base à l’état ORPHANED et ne touchent pas au fichier de la base.

Attention. Après la promotion d’une réplique en maître (chapitre 8), n’exécutez pas cleanuparchive -orphaned pour l’ancien enregistrement : le nouveau maître utilise le même dossier .LogArch, et la commande supprimera son archive de travail.

3.9. Changer la racine des bases de données

L’enregistrement avec un autre chemin est autorisé. Le nœud :

  • ajoute les bases du nouveau dossier ;
  • passe à ORPHANED les bases de l’ancien dossier qui ne sont pas dans le nouveau (notification orphaned_database) et conserve leurs archives.

Si vous avez choisi le mauvais dossier, enregistrez de nouveau le bon dossier. Une base avec le même chemin complet continuera de fonctionner sous le même db_id. Une base à un chemin différent est une nouvelle base (nouveau db_id) ; sa réplique doit être initialisée de nouveau.

3.10. Erreurs fréquentes

Ce que vous voyez Cause Que faire
preflight failed on node-a pas de permissions sur les dossiers corrigez les permissions, réessayez (3.2)
409 scan_would_empty_region le nouveau dossier ne contient pas de bases, mais le nœud en avait vérifiez le chemin et le masque
L’aperçu est vide le masque ne correspond pas ou le dossier est faux vérifiez le chemin, le masque, « récursif »
Les boutons sont désactivés, « Impossible de lire la configuration du nœud » le nœud ne répond pas vérifiez le service du nœud et le réseau (chapitre 1)
La base reste longtemps en PENDING_RESTART le maître ne redémarre pas Firebird de lui-même redémarrez Firebird (3.5)
Redémarrage rejeté à cause de fbagent fbagent n’est pas en cours d’exécution ou ses données ne correspondent pas à node.json chapitre 1, vérification de fbagent
Le nouveau fichier n’est pas apparu le nœud est en mode liste ajoutez le fichier via « Inscrire la sélection »

4. Comment faire d'une base de données une réplique : étapes et emplacement sur le disque

Ce chapitre couvre tout le parcours d’une base, de la primaire à une réplique en fonctionnement, plus le calcul de l’espace disque. L’initialisation elle-même est décrite en détail au chapitre 5.

4.1. La règle principale

Une base apparaît sur une réplique uniquement par initialisation depuis le maître (reinit) : le nœud maître transfère lui-même une copie via nbackup.

Ne faites pas de copie à la main :

  • gbak crée un nouveau GUID de base et remet le numéro de segment à zéro. Le lien maître-réplique est rompu.
  • Une copie de fichier d’une base en cours d’exécution n’est pas cohérente, et RCM verra deux bases avec le même GUID (duplicate_guid) et interdira l’initialisation.

Une réplique déjà en fonctionnement, configurée à la main, peut être prise sous gestion sans nouvelle copie : voir 4.6.

4.2. Étapes

N° Étape Où État de la base maître après l’étape
1 Enregistrement de la base sur le maître chapitre 3.3 PENDING_RESTART
2 Redémarrage du Firebird du maître chapitre 3.5 CONFIGURED
3 Synchronisation de la publication chapitre 6 CONFIGURED, publication activée
4 Préparation de la réplique : dossier, permissions, version de Firebird 4.3 —
5 Vérification de l’espace libre sur le maître et sur la réplique 4.4 —
6 Initialisation chapitre 5 SEEDING → IN_SYNC
7 Redémarrage du Firebird de la réplique (si nécessaire) chapitre 5.6 la réplique commence à appliquer les segments
8 Vérification des données chapitre 5.10 —

L’étape 3 est obligatoire pour Firebird 4/5. Sans publication, le Firebird du maître n’écrit pas les modifications des tables dans les segments, et la réplique prend du retard sur le maître en silence. Sur la page Bases de données, une telle base est marquée de l’icône publication désactivée. Cliquez sur Synchroniser la publication avant l’initialisation.

À partir de HQbird 2027.2.24, la fenêtre Initialiser avertit de cela et propose un bouton Synchroniser la publication et initialiser, tandis que le nœud maître refuse l’initialisation avec l’erreur publication_off (chapitre 5.1). RCM et le nœud 2027.5.7 ne vérifient pas la publication.

HQbird 2.5/3.0. Il n’y a pas de publications, donc l’étape 3 est sautée. L’ensemble des tables est défini par les filtres du greffon replconf (chapitre 6).

États de la base :

État Groupe dans RCM Signification
CONFIGURED En attente Firebird a lu les paramètres, il n’y a pas encore de réplique
PUBLISHING En attente la synchronisation de la publication est en cours
SEEDING En attente l’initialisation est en cours
IN_SYNC Correct la réplique a reçu tous les segments
LAGGING En attente la réplique est en retard, des segments sont en file
NEEDS_REINIT Erreur la réplique doit être initialisée de nouveau
FAILED Erreur la dernière initialisation a échoué

4.3. Préparation de la réplique

Dossier de la base de la réplique

Le nœud réplique place chaque base dans son propre dossier databases.root, au chemin :

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

Exemple : maître node-a avec la racine /databases/master et la base /databases/master/sales/employee.fdb. Sur la réplique node-b avec la racine /databases/replica, la base sera ici :

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

Ainsi, des bases de même nom venant de maîtres différents ne se heurtent pas.

Personne ne crée le dossier racine automatiquement : ni le programme d’installation, ni HQCenter Admin, ni le nœud au démarrage. Créez-le de l’une des façons suivantes :

  • dans la fenêtre Initialiser : le champ Dossier de la réplique, le bouton Créer le dossier. Le bouton n’est visible que lorsque le dossier n’existe pas. Avec HQbird 2027.2.24, si le nœud réplique n’a pas encore de databases.root, le champ contient déjà /databases/replica/<id du nœud réplique>. Pour une réplique sous Windows, le champ est vide : saisissez un dossier avec une lettre de lecteur. Chaque nœud réplique sur le même hôte a besoin de son propre dossier. Le dossier est créé par le nœud réplique : propriétaire firebird (ou l’utilisateur du service du nœud), permissions 2770. Si le nœud ne peut pas le créer, la fenêtre affichera la commande pour l’hôte de la réplique. Si vous indiquez un autre dossier, RCM l’écrira dans databases.root du nœud réplique avant l’initialisation ;

  • à la main sur l’hôte de la réplique (Linux) :

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

    Le bit setgid (2770) est nécessaire pour que tous les fichiers à l’intérieur reçoivent le groupe Firebird.

Vous ne pouvez changer la racine de la réplique que tant qu’elle n’a pas de bases : sinon les anciennes bases se retrouveront hors de l’analyse. Pour placer une seule base ailleurs, utilisez Déplacer sur la page de la base.

Permissions

Le nœud réplique et Firebird doivent pouvoir écrire dans la racine des bases. Le nœud vérifie que les fichiers placés recevront le groupe du dossier. S’il ne le peut pas, il refuse avec ownership_unfixable et un texte sur la façon de corriger (en général le service du nœud s’exécute avec Group=root).

Avec HQbird 2027.2.24, la fenêtre Initialiser montre aussi un dossier qui existe mais dans lequel le service du nœud ne peut pas écrire : le texte du nœud avec la commande de correction et un bouton Vérifier de nouveau. RCM 2027.5.7 dit dans ce cas « Le dossier existe » : vérifiez vous-même les permissions (hqbirdrcm checkpermissions -node <replica> -root <folder>).

Version de Firebird

La version majeure de Firebird sur la réplique doit correspondre au maître (5.0 → 5.0, 4.0 → 4.0). Sinon la réplique refusera avant tout transfert de données : incompatible_engine.

Connectivité

Le nœud réplique doit être un pair du maître, et le maître doit être un pair de la réplique (chapitre 2). Sinon RCM ne proposera pas ce nœud dans la fenêtre Initialiser.

4.4. Combien d’espace faut-il

En bref

Où Quoi Combien
Maître, volume de la base libre avant l’initialisation ≥ 105 % de la taille de la base
Réplique, volume du dossier de la base libre avant l’initialisation ≥ 105 % de la taille de la base, avec HQbird 2027.2.24, plus free_space_floor_gb (plus l’ancien fichier, si la réplique existait déjà ; avec la case Supprimer l’ancienne réplique, sans lui)
Maître, <database>.ReplLog segments de travail de Firebird jusqu’à 64 segments × taille du segment (16 Mo par défaut) ≈ 1 Go par base
Maître, <database>.LogArch archive des segments pour les répliques modifications sur retention_days (par défaut 2 jours) + ce que les répliques n’ont pas encore confirmé
Réplique, <database>.Incoming file des segments à appliquer jusqu’à 256 segments × 16 Mo ≈ 4 Go par base dans le pire cas
Réplique, volume entier marge au moins free_space_floor_gb (par défaut 1 Go)

Vérification de l’espace avant l’initialisation

L’initialisation vérifie l’espace deux fois et seulement avant de verrouiller la base :

  1. RCM, à partir des dernières statistiques du nœud, avant d’envoyer la commande. Si l’espace est clairement insuffisant, RCM renvoie immédiatement l’erreur 507.
  2. Nœud maître, une mesure en direct sur son propre volume, puis une demande à la réplique pour qu’elle mesure le sien. S’il en manque d’au moins un côté, l’initialisation s’arrête à l’étape SPACE CHECK avec l’erreur insufficient disk space on master ou … on replica.

L’exigence des deux côtés est 105 % de la taille de la base maître.

Avec HQbird 2027.2.24, le nœud réplique calcule ainsi :

  • il lui faut 105 % de la taille de la base plus le free_space_floor_gb de la réplique (7.3) : après l’initialisation, une réserve pour les segments reste sur le volume ;
  • les restes des initialisations précédentes (<database>.hqcluster-part, <database>.new) comptent comme espace libre : le nœud les supprime avant la nouvelle copie ;
  • le texte de l’erreur nomme tous les nombres. Il nomme aussi les fichiers <database>.pre-reinit-*.fdb et <database>.failed-seed-*.fdb avec leur taille. Le nœud ne les supprime jamais : supprimez-les vous-même s’ils ne sont pas nécessaires.

force (forcé) saute seulement la vérification dans RCM. La vérification du nœud ne peut pas être contournée : elle protège le nœud d’un manque de disque au milieu de la copie. Si l’espace est insuffisant seulement à cause de l’ancienne copie de la réplique, RCM 2027.2.24 dans l’erreur 507 nomme la case Supprimer l’ancienne réplique plutôt que force. Pour cela, les deux nœuds doivent être HQbird 2027.2.24 ou plus récent. Sinon l’erreur nomme le nœud à mettre à jour, et force.

Pourquoi autant

Maître. Pendant la copie, la base est verrouillée par nbackup -L. Toutes les modifications sont écrites dans le fichier <database>.delta à côté de la base. La taille de .delta dépend de la charge d’écriture pendant la copie. Sous forte charge et transfert lent, elle peut beaucoup grossir : surveillez l’espace pendant la première initialisation.

Réplique. La copie est écrite directement dans le fichier <database>.hqcluster-part à côté de l’emplacement de la base. Le nœud réserve la taille complète à l’avance. Le fichier est ensuite vérifié, réparé (nbackup -FIXUP -SEQUENCE) et renommé en place. Une seconde copie n’est pas nécessaire : la taille de la base est nécessaire une fois, sur le volume de la base.

Si la réplique existait déjà (initialisation répétée), l’ancien fichier reste sur le disque jusqu’à la dernière étape. Cela signifie que l’ancien fichier et la nouvelle copie sont nécessaires sur le volume en même temps. L’espace libre est calculé sans l’ancien fichier, donc l’exigence est la même : 105 % de la taille de la base libres.

Supprimer l’ancienne réplique (avec HQbird 2027.2.24). S’il n’y a pas de place sur le volume de la réplique pour la nouvelle copie à côté de l’ancienne, cochez cette case dans la fenêtre d’initialisation (chapitre 5.1). Le nœud réplique supprime alors l’ancienne copie et ses segments entrants (.Incoming) avant le transfert, et le volume a assez pour 105 % de la taille de la base plus free_space_floor_gb. Le nœud ne supprime la copie que si toutes les conditions sont vraies :

  • sans suppression il n’y a pas assez de place, et avec suppression il y en a assez ;
  • c’est une copie installée par l’initialisation de ce nœud : l’en-tête est lisible, le mode est réplique en lecture seule ;
  • la base n’a pas été rendue normale (pas de fichier <database>.hqcluster-normal.json, chapitre 8) ;
  • overwrite_non_replica n’est pas défini (5.9).

Sinon le nœud ne supprime rien et refuse avec le motif dans le texte. Pour supprimer, le nœud arrête le Firebird de la réplique pendant la suppression (5.6).

La case est désactivée par défaut. Risque : pendant le transfert, il n’y a pas de copie de la base sur la réplique. Si la base n’a qu’une réplique, le maître n’est pas protégé pendant tout ce temps. Tant qu’il n’y a pas de nouvelle copie, la base sur la réplique est à l’état NEEDS_REINIT (pas FAILED et pas ORPHANED), et la réplique émet l’alerte replica_removed_for_reinit (avertissement). Une fois la nouvelle copie en place, l’alerte est effacée. Si l’initialisation échoue après la suppression, la paire reste NEEDS_REINIT : relancez l’initialisation (ou la réinitialisation automatique la lancera, 5.8). Une nouvelle initialisation transfère la base depuis le début.

Archive du maître (.LogArch). Le nœud conserve les segments envoyés pendant retention_days jours afin que la réplique puisse les redemander. Les segments que la réplique n’a pas encore appliqués sont conservés plus longtemps. Si l’espace est bas, le nœud nettoie l’archive par étapes :

  1. segments appliqués par toutes les répliques plus anciens que retention_days ;
  2. segments appliqués plus récents (quand l’espace manque) ;
  3. segments non appliqués, seulement en dernier recours. Alors la réplique perd les segments dont elle a besoin et reçoit NEEDS_REINIT.

Si une réplique est indisponible longtemps, l’archive grossit. Son volume correspond aux modifications de la base sur la période d’arrêt.

Exemple de calcul

Base de 100 Go. Charge : 5 Go de segments par jour. L’initialisation s’exécute la nuit, la copie prend 2 heures, pendant lesquelles environ 2 Go finissent dans .delta.

Où Calcul Total libre
Maître, volume de la base 105 Go pour les vérifications (inclut la croissance de .delta) + .ReplLog 1 Go + .LogArch 2 jours × 5 Go = 10 Go ≥ 116 Go
Réplique, nouvelle base 105 Go + .Incoming jusqu’à 4 Go + 1 Go de réserve ≥ 110 Go
Réplique, initialisation répétée ancien fichier de 100 Go déjà sur le disque + 110 Go libres volume ≥ 210 Go
Réplique, initialisation répétée avec la case Supprimer l’ancienne réplique (avec HQbird 2027.2.24) ancien fichier supprimé avant le transfert : 105 Go + .Incoming jusqu’à 4 Go + 1 Go de réserve volume ≥ 110 Go

Ajoutez une réserve pour la croissance de la base et pour l’arrêt de la réplique (l’archive du maître grossit de 5 Go par jour d’arrêt).

Segments sur un volume séparé

Les dossiers .ReplLog, .LogArch et .Incoming sont par défaut à côté de la base. Ils peuvent être déplacés vers un autre volume : le paramètre segments.storage dans node.json (avec mirror_hierarchy: true, le nœud reproduit la structure des dossiers des bases). Alors l’archive ne prend pas de place aux bases. La vérification des 105 % s’applique toujours au volume de la base.

Où regarder l’espace

  • Bases de données → Nœuds et Vue d’ensemble : l’icône d’espace libre du volume databases.root. Jaune : moins de 20 %, rouge : moins de 10 %.

    Page Bases de données : la colonne Disque dans la table Nœuds
    Page Bases de données : la colonne Disque dans la table Nœuds
  • Rapport du cluster : hqbirdrcm report.

4.5. Plusieurs répliques d’une base

La deuxième réplique et les suivantes se créent de la même façon : Initialiser dans la ligne du maître, en choisissant un nœud réplique libre.

  • Pendant l’initialisation d’une nouvelle réplique, le maître ne transmet pas non plus cette base aux répliques déjà en fonctionnement. Elles rattraperont le maître après la fin de l’initialisation. La fenêtre de confirmation le dit.
  • Une base : une initialisation à la fois, même pour des répliques différentes.
  • L’espace sur le maître est vérifié séparément pour chaque initialisation.
Base maître avec deux répliques
Base maître avec deux répliques

4.6. Réplique configurée à la main

Si une réplique fonctionne déjà à partir d’un replication.conf écrit à la main, vous pouvez la prendre sous gestion et ne pas recopier la base :

  1. Maître : enregistrez les bases avec detect_existing (chapitre 3.6).
  2. Réplique : Bases de données → nœud réplique → Prendre en charge, ou hqbirdrcm takeover-replica. RCM trouvera les blocs de la réplique, associera les fichiers aux bases maîtres par GUID et affichera pour chacun : in_sync, resumable ou needs_reinit.
  3. Confirmez les lignes. Le nœud déplacera les blocs dans sa propre zone de replication.conf.
  4. Redémarrez le Firebird de la réplique pour qu’il lise les blocs déplacés.
  5. Initialisez uniquement les lignes needs_reinit : l’archive du maître ne contient plus les segments exigés par ces répliques.

4.7. Erreurs fréquentes

Ce que vous voyez Cause Que faire
insufficient disk space on master / on replica pas assez d’espace (4.4). Lors d’une réinitialisation, l’ancienne copie occupe de l’espace jusqu’à la fin (4.4) libérez de l’espace, réessayez. La seconde issue sur la réplique (depuis HQbird 2027.2.24) est la case Supprimer l’ancienne réplique (4.4, 5.1)
507 de RCM immédiatement selon les statistiques d’espace, il n’y en a clairement pas assez idem. S’il y a de l’espace sans l’ancienne copie, RCM 2027.2.24 nomme la case Supprimer l’ancienne réplique
incompatible_engine versions majeures de Firebird différentes mettez à niveau le Firebird de la réplique
Dossier absent sur le nœud réplique racine non créée Créer le dossier dans la fenêtre d’initialisation (4.3)
Le dossier existe, mais le service du nœud ne peut pas y écrire (depuis HQbird 2027.2.24) pas de permissions d’écriture exécutez la commande de la fenêtre, cliquez sur Vérifier de nouveau (4.3)
publication_off (depuis HQbird 2027.2.24) la publication du maître est désactivée ou n’a pas de tables Synchroniser la publication et initialiser (5.1)
ownership_unfixable le service du nœud a un groupe étranger corrigez le groupe du service comme indiqué dans le texte de l’erreur
duplicate_guid deux bases avec le même GUID (une copie de fichier) retirez la copie ou donnez-lui un nouveau GUID (nbackup -F)
Nœud réplique absent de la liste Initialiser pas de connexion dans les pairs chapitre 2
Réplique IN_SYNC, mais les données divergent la publication était désactivée synchronisez la publication, puis répétez l’initialisation

5. Initialisation (reinit)

L’initialisation est le transfert d’une copie de la base maître vers la réplique. Le premier transfert s’appelle initialisation (le bouton Initialiser) ; un transfert répété est la réinitialisation (le bouton Réinitialiser). Le mécanisme est le même.

Avant de commencer, terminez les étapes 1 à 5 du chapitre 4 : la base est enregistrée, le Firebird du maître a été redémarré, la publication est activée, le dossier de la réplique existe et il y a assez d’espace. L’espace nécessaire sur le maître et sur la réplique est décrit au chapitre 4.4.

5.1. Comment démarrer

D’abord la publication. Enregistrer une base n’inclut pas la publication. Sans publication, la réplique ne reçoit aucune modification. Avant l’initialisation, exécutez Synchroniser la publication (chapitre 6) ou hqbirdrcm setpublication -node <master>.

  • Avec HQbird 2027.2.24, la fenêtre d’initialisation vérifie la publication. Si elle est désactivée ou n’a pas de tables avec une clé, la fenêtre affiche un avertissement et un bouton Synchroniser la publication et initialiser. RCM synchronise la publication, attend la fin de la commande et démarre l’initialisation avec la sélection de la fenêtre.
  • Un nœud maître 2027.2.24 refuse lui-même une telle initialisation (y compris la première) avec l’erreur publication_off et émet la notification master_publication_off (chapitre 6.1). Après le refus, la cellule de la base a de nouveau le bouton Synchroniser la publication et initialiser.
  • Si l’opérateur a désactivé la publication (6.4) ou en a retiré toutes les tables avec une clé (6.3), la synchronisation conserve cela. RCM ne démarre pas l’initialisation et fournit un lien vers la page Tables de la publication.
  • RCM et le nœud 2027.5.7 ne vérifient pas la publication : l’initialisation réussit, la base affiche « Correct » dans RCM, mais la réplique ne reçoit aucune modification. Si la publication a été activée après l’initialisation, réinitialisez la base.
La fenêtre « Réinitialiser la base ? »
La fenêtre « Réinitialiser la base ? »
  1. Ouvrez Bases de données.
  2. Dans la ligne de la base maître, dans la colonne du nœud réplique, cliquez sur Initialiser. Le nœud réplique est fixé par la colonne : il n’est pas choisi dans la fenêtre. Pour une paire existante, Réinitialiser dans la carte développée du maître.
  3. Dans la fenêtre (avec HQbird 2027.2.24, le titre pour une nouvelle paire est « Initialiser la base ? » ; dans RCM 2027.5.7, « Réinitialiser la base ? » aussi pour la première initialisation) :
    • vérifiez le Dossier de la réplique. La fenêtre indique si le dossier existe. S’il n’existe pas, cliquez sur Créer le dossier : le nœud réplique le créera (4.3). Si le nœud ne peut pas le créer, la fenêtre affiche la commande pour l’hôte de la réplique. Avec HQbird 2027.2.24, la fenêtre montre aussi un dossier dans lequel le service du nœud ne peut pas écrire : la commande de correction et un bouton Vérifier de nouveau ;
    • sélectionnez la Méthode de réinitialisation : Douce (recommandée) ou Standard (5.4). Avec HQbird 2027.2.24, si l’archive du maître n’a pas encore de segments (en général avant la première initialisation), la fenêtre affiche une indication : sur une base chargée, Standard est plus rapide ;
    • si la base maître attend encore un redémarrage de Firebird, la fenêtre le dira et affichera un bouton Redémarrer le Firebird du maître. Sans le redémarrage, la base n’est pas répliquée ;
    • Supprimer l’ancienne réplique (avec HQbird 2027.2.24, désactivée par défaut) n’est nécessaire que pour une réinitialisation lorsque le volume de la réplique n’a pas de place pour une nouvelle copie à côté de l’ancienne (4.4). La fenêtre affiche les nombres à l’avance : combien il faut, combien est libre, combien occupe l’ancienne copie. S’il y a de la place sans l’ancienne copie, la fenêtre demande de cocher la case. La case est inactive si le nœud maître ou réplique est une ancienne version : la fenêtre indique quel nœud mettre à jour. Tant que la nouvelle copie n’est pas prête, la réplique n’a pas de copie de cette base (4.4).
  4. Confirmez. RCM indiquera que la base sera verrouillée sur le maître et copiée vers la réplique.

La progression de l’initialisation est visible dans la carte développée du maître sur la page Bases de données : étapes et pourcentages. Avec HQbird 2027.2.24, la progression reste visible après l’actualisation de la page : à la première initialisation, dans la cellule du nœud réplique, et aussi dans la ligne Progression de la réinitialisation de la page de la base maître. Le bouton Initialiser est inactif pendant que le nœud maître copie la base. Si RCM ne suit pas cette initialisation (par exemple, elle a été lancée depuis la ligne de commande du nœud), les étapes sont prises de l’état du nœud, sans pourcentages. Dans RCM 2027.5.7, après l’actualisation de la page, la progression de la première initialisation n’est pas visible : attendez que la base maître quitte SEEDING.

Étapes d'initialisation dans la ligne du maître
Étapes d'initialisation dans la ligne du maître

Chaque commande RCM (initialisation, redémarrage de Firebird, synchronisation de la publication) est enregistrée sur la page Commandes avec son résultat.

La page « Commandes »
La page « Commandes »

La même chose depuis la ligne de commande

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

Paramètres : -mode smooth|standard (par défaut smooth), -hold=false (ne pas retenir l’archive pendant les transactions longues), -allow-restart (5.6), -force (5.9).

-remove-old-replica (avec HQbird 2027.2.24) est la même chose que la case Supprimer l’ancienne réplique. Pour une seule base : -db et -to sont obligatoires ; avec -all la commande refuse. Si le nœud maître ou réplique est une ancienne version, RCM refuse avec node_too_old et n’envoie rien.

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

-all essaie toutes les bases et rassemble les erreurs au lieu de s’arrêter à la première.

5.2. Étapes

N° Étape (dans RCM) Ce qui se passe
1 SPACE CHECK vérifie l’espace sur le maître et sur la réplique (chapitre 4.4) ; la réplique vérifie à l’avance qu’elle peut accepter le fichier
2 LOCKING nbackup -L : le fichier de la base maître est figé, les modifications vont dans <database>.delta
3 COPYING TO NODE le fichier est transféré par parties : lecture → somme de contrôle → compression → envoi
4 UNLOCKING nbackup -N juste après le transfert : les modifications de .delta reviennent dans la base
5 SEEDING sur la réplique : vérification de la somme du fichier, nbackup -FIXUP -SEQUENCE, installation du fichier, gfix -replica, écriture du bloc dans replication.conf
6 RESTARTING REPLICA redémarrage du Firebird de la réplique, s’il est nécessaire (5.6)

Après l’étape 6, la base reçoit l’état IN_SYNC. Le maître continue d’envoyer les segments à partir du point où la copie s’arrête.

Ce qu’il faut savoir :

  • Le maître fonctionne tout le temps. Les utilisateurs écrivent dans la base, les modifications vont dans .delta. Le verrou est libéré juste après le transfert.
  • Les transactions qui ont coïncidé avec le verrou ne sont pas perdues. Le nœud trouve les transactions ouvertes au moment de nbackup -L, et la réplique les rejoue à partir des segments.
  • Le transfert continue après une interruption. Si la connexion ou le nœud réplique a redémarré, le maître reprendra à partir de la dernière partie reçue. Un transfert inachevé est conservé sur la réplique pendant 24 heures (reinit_partial_keep_hours).
  • En cas d’erreur, le nœud libère le verrou, supprime le fichier inachevé sur la réplique et met la base à FAILED. La tentative suivante part d’un état connu.
  • Avec la case « Supprimer l’ancienne réplique » (depuis HQbird 2027.2.24), la réplique supprime l’ancienne copie après l’étape LOCKING, avant le transfert. L’étape COPYING TO NODE affiche alors « suppression de l’ancienne copie de la réplique pour faire de la place ». Une erreur après la suppression donne à la paire NEEDS_REINIT plutôt que FAILED (chapitre 4.4).
  • nbackup uniquement. gbak n’est pas utilisé : il change le GUID de la base.

5.3. Effet sur le fonctionnement

Quoi Effet
Utilisateurs du maître continuent de travailler ; pendant la copie .delta grossit, après -N les modifications sont transférées dans la base
Autres répliques de cette base ne reçoivent pas les segments de cette base pendant l’initialisation ; elles rattrapent ensuite
Autres bases du maître non affectées
Firebird de la réplique, nouvelle base non arrêté ; redémarrage selon 5.6
Firebird de la réplique, initialisation répétée est arrêté pendant le remplacement du fichier : toutes les bases de ce Firebird sont indisponibles pendant quelques secondes
Firebird de la réplique, le nœud supprime l’ancienne copie (case « Supprimer l’ancienne réplique », depuis HQbird 2027.2.24) est arrêté plus tôt, pendant la suppression, avant le transfert. Le nœud installe la nouvelle copie sans second arrêt si le bloc de la base dans replication.conf n’a pas changé. S’il y a assez de place et qu’aucune suppression n’est nécessaire, le nœud ne supprime rien, et tout se passe comme pour une initialisation répétée normale
Réseau et disque charge selon les limites de vitesse (5.5)

Sous Windows. Un fichier ouvert par Firebird ne peut pas être remplacé. Pendant une initialisation répétée, le nœud arrête le Firebird de la réplique via fbagent, installe le fichier et redémarre Firebird. Sous Linux, Firebird est aussi arrêté avant le remplacement : sinon il continuerait de travailler avec l’ancien fichier déjà supprimé.

5.4. Méthodes douce et standard

Douce (par défaut). Avant le verrouillage, le nœud cherche les transactions longues : des transactions d’écriture utilisateur commencées avant le segment le plus ancien de l’archive du maître. Après l’initialisation, la réplique ne pourra pas les rejouer et s’arrêtera à leur première modification (« Transaction … is not found »). Les transactions sans modification ne sont pas comptées.

Si de telles transactions existent, l’initialisation ne démarre pas : RCM affiche La réinitialisation douce attend des transactions longues et fournit un lien Ouvrir la liste.

Page des transactions longues : aucune transaction longue
Page des transactions longues : aucune transaction longue

Sur la page Transactions longues :

  • résumé : combien de transactions et de connexions, le segment le plus ancien ;
  • Les 5 premières connexions avec les transactions les plus anciennes : utilisateur, client, début, âge, modifications, requête en cours ;
  • Retenir les segments / Libérer la retenue : tant que la retenue est activée, l’archive du maître n’est pas purgée et l’historique n’est pas tronqué ;
  • Déconnecter la sélection et réessayer la réinitialisation : déconnecte les connexions (leurs transactions sont annulées) et démarre immédiatement une réinitialisation douce ;
  • Réessayer la réinitialisation, Vérifier de nouveau.

La retenue est activée automatiquement lorsqu’une réinitialisation est refusée à cause de transactions longues. Elle est libérée après une initialisation réussie, à la main, ou lorsque l’archive atteint reinit_hold_max_segments (1000 segments par défaut, notification retention_hold_released).

Standard verrouille la base immédiatement, sans vérification. Ne l’utilisez que si vous savez qu’il n’y a pas de longues transactions d’écriture.

Première initialisation sous charge. Tant que l’archive du maître est vide, il n’y a pas de segment auquel comparer.

Avec un nœud maître HQbird 2027.2.24 : si le nœud a activé la publication lui-même et que l’archive n’a pas changé depuis, l’historique commence au moment où la publication a été activée. Une transaction commencée plus tard entre dans le journal dès sa première modification et ne gêne pas la méthode douce. Une transaction commencée plus tôt n’est pas entrée dans le journal : la réinitialisation l’attend avant le verrouillage (6 tentatives toutes les 10 s), et l’étape locking affiche son numéro, la connexion et l’utilisateur. Si elle n’est pas terminée, la réinitialisation se termine avec l’erreur reinit_pre_publication_transactions : terminez-la et réessayez. La page Transactions longues montre ces transactions dans la table Transactions commencées avant l’activation de la publication.

Si la publication a été activée à la main, pas via le nœud, ou si l’archive a déjà changé, le début de l’historique est inconnu. Dans ce cas, la méthode douce refuse si une transaction d’écriture est ouverte, et le message dit que l’archive ne contient pas encore de segment. Dans ce cas, RCM 2027.2.24 n’ouvre pas la liste mais écrit quoi faire dans la cellule de la base. Choisissez Standard ou réessayez une fois que Firebird a archivé le premier segment.

Avec un nœud maître 2027.5.7, la méthode douce refuse immédiatement à la première initialisation d’une base dans laquelle on écrit : long_transactions … segment 0 (0001-01-01T00:00:00Z). Pour la première initialisation d’une telle base, choisissez Standard.

Pour les réinitialisations suivantes, la méthode douce fonctionne comme d’habitude (l’archive existe déjà).

La même chose depuis la ligne de commande

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

Transactions plus anciennes que la publication. Firebird n’écrit pas dans les segments une transaction commencée avant l’activation de la publication. Si le nœud a activé la publication, l’initialisation attend (6 tentatives toutes les 10 secondes) que ces transactions se terminent ; sinon elle se termine avec l’erreur reinit_pre_publication_transactions en les énumérant. Après la synchronisation d’une publication qui a ajouté des tables, reconnectez les applications, puis démarrez l’initialisation.

5.5. Vitesse

Quand Vitesse Paramètre
Dans la fenêtre de transfert windows.transfer_window (par défaut 23:00-05:00) constante limits.reinit_window_mbps, par défaut 100 Mo/s
Hors de la fenêtre fraction de la vitesse de disque mesurée limits.reinit_day_disk_fraction, par défaut 0.5

Le nœud recalcule le mode toutes les 30 secondes : une initialisation commencée le jour s’accélérera d’elle-même la nuit.

Le nœud mesure la vitesse du disque par un test. Pour répéter le test sur l’hôte du maître :

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

Durée d’initialisation ≈ taille de la base ÷ vitesse. Exemple : 100 Go à 100 Mo/s, environ 17 minutes de transfert pur ; en pratique, le réseau ou le disque limitent.

5.6. Redémarrage du Firebird de la réplique

Une nouvelle base sur la réplique. Le fichier est placé sans arrêter Firebird. Firebird ne lira le nouveau bloc de replication.conf qu’après un redémarrage. Jusque-là, la réplique n’applique rien. L’étape RESTARTING REPLICA affiche l’attente :

Libellé Ce que cela signifie
en attente d’un redémarrage de Firebird sur la réplique, il est prévu pour … le nœud redémarrera Firebird lui-même après la dernière initialisation (reinit_restart_delay_sec), une fois les autres initialisations terminées
… la fenêtre de redémarrage est fermée, la prochaine s’ouvrira à … attente de restart_window de la réplique
… la dernière tentative a échoué, la prochaine à … réessayera plus tard
la réplique ne peut pas redémarrer Firebird elle-même : redémarrez-le à la main auto_restart: never, ou ce Firebird sert aussi les bases du maître

Le nœud redémarre Firebird une fois après une série d’initialisations, pas après chaque base.

Pour redémarrer à la main, cliquez sur Redémarrer le Firebird de la réplique. L’attente se termine après tout redémarrage réussi de Firebird ou lorsque la réplique a appliqué un segment plus récent que la copie.

Réinitialisation sur un Firebird qui sert aussi les bases du maître. Le nœud n’arrête pas un tel Firebird lui-même et refuse avec restart_not_allowed. Relancez l’initialisation et cochez Autoriser à arrêter Firebird pour cette réinitialisation (-allow-restart sur la ligne de commande), à un moment où les connexions de ce Firebird peuvent être coupées, y compris vers ses bases maîtres. Exécutez de telles initialisations une par une par hôte.

Suppression de l’ancienne copie (la case Supprimer l’ancienne réplique, avec HQbird 2027.2.24) arrête aussi le Firebird de la réplique, selon les mêmes règles. Si le nœud ne peut pas arrêter ce Firebird lui-même, il ne supprime rien et refuse avec restart_not_allowed : cochez aussi Autoriser à arrêter Firebird pour cette réinitialisation. Si à ce moment une autre initialisation se termine sur la réplique ou si Firebird redémarre, le nœud ne supprime rien et refuse avec engine_busy : le maître libère le verrou, réessayez plus tard.

5.7. File et initialisations simultanées

  • Une base : une initialisation à la fois (même pour des répliques différentes). Le bouton Initialiser est désactivé pendant qu’une initialisation de cette base est en cours.
  • Le nœud maître impose limits.max_concurrent_reinits initialisations de bases différentes en même temps (par défaut 1). Le reste attend dans la file ; la réponse contient la position dans la file.
  • N’exécutez pas votre propre nbackup -L (ni ALTER DATABASE BEGIN BACKUP) sur une base pendant son initialisation, et ne démarrez pas une initialisation pendant une telle sauvegarde : une base ne peut avoir qu’un seul verrou. L’initialisation le vérifie et refuse avec nbackup backup lock already active.

La file et les transferts en cours sont visibles sur la page Transfert.

Page Transfert / files
Page Transfert / files
- Si un fichier `.delta` reste après un échec, assurez-vous qu'aucune sauvegarde n'est en cours et exécutez `nbackup -N `. Ne supprimez pas le `.delta` à la main.

5.8. Réinitialisation automatique

RCM peut réinitialiser lui-même une base à l’état NEEDS_REINIT, seulement dans une fenêtre configurée. Désactivée par défaut.

Lorsqu’une base entre en NEEDS_REINIT :

Cause Où c’est visible
erreur d’application irrécupérable qui se répète (violation de PK, UNIQUE, FK), 3 fois de suite réplique, alerte replication_unrecoverable_error
le GUID de la base maître a changé (restauration, remplacement du fichier) réplique, alerte replication_guid_mismatch
l’archive du maître ne contient plus les segments dont la réplique a besoin maître
la réplique a supprimé l’ancienne copie pour l’initialisation et il n’y a pas encore de nouvelle copie (depuis HQbird 2027.2.24) réplique, alerte replica_removed_for_reinit ; maître

Pour l’activer : Paramètres → RCM (ou rcm.json, la section 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" } }
  }
}
  • Fenêtre : par base → par nœud → globale. "always" : à tout moment.
  • Les fenêtres sont calculées selon l’horloge de l’hôte RCM.
  • max_concurrent : combien d’initialisations (manuelles et automatiques) peuvent être en cours dans le cluster pour que RCM en démarre une autre automatique.
  • L’initialisation automatique passe par les mêmes vérifications d’espace et de GUID que l’initialisation manuelle. L’auteur de la commande est system:autoreinit.
  • remove_old_replica_when_short (depuis HQbird 2027.2.24, la ligne Supprimer l’ancienne réplique en cas de manque d’espace) : désactivé par défaut. Si c’est activé, l’initialisation automatique envoie le drapeau Supprimer l’ancienne réplique (4.4). RCM ne l’envoie que si la réplique elle-même est en NEEDS_REINIT ou si la cause NEEDS_REINIT du maître la nomme. Pour une réplique qui est IN_SYNC ou LAGGING, le drapeau n’est jamais envoyé. Si le nœud est une version plus ancienne, RCM démarre la même initialisation sans le drapeau.
  • Après la modification, redémarrez RCM.

Reporter dans la carte du maître désactive l’initialisation automatique d’une seule base pendant 1 heure, 4 heures, 24 heures ou jusqu’à annulation. L’initialisation manuelle reste disponible.

5.9. Erreurs

Erreur Cause Que faire
insufficient disk space on master / on replica, 507 pas assez d’espace. Pendant la réinitialisation, l’ancienne copie occupe de l’espace jusqu’à la fin chapitre 4.4 ; sur la réplique (depuis HQbird 2027.2.24), la case Supprimer l’ancienne réplique (5.1)
node_too_old (depuis HQbird 2027.2.24) la case Supprimer l’ancienne réplique est cochée, mais le nœud maître ou réplique est une ancienne version mettez le nœud à niveau comme indiqué dans le texte de l’erreur ou exécutez sans la case
engine_busy, reclaim_in_progress (depuis HQbird 2027.2.24) la réplique ne peut pas supprimer l’ancienne copie maintenant : Firebird ou cette base est occupé réessayez plus tard (5.6)
replica_removed_for_reinit, paire NEEDS_REINIT (depuis HQbird 2027.2.24) la réplique a supprimé l’ancienne copie, mais l’initialisation ne s’est pas terminée relancez l’initialisation (4.4)
publication_off (depuis HQbird 2027.2.24) la publication du maître est désactivée ou ne contient pas de tables avec une clé Synchroniser la publication et initialiser (5.1)
long_transactions, « La réinitialisation douce attend des transactions longues » des transactions d’écriture longues sont ouvertes 5.4
long_transactions, « l’archive du maître ne contient pas encore un seul segment » première initialisation sous charge Standard (5.4)
reinit_pre_publication_transactions transactions commencées avant l’activation de la publication reconnectez les applications, réessayez
duplicate_guid deux bases maîtres avec le même GUID retirez la copie ; si l’étape NEW GUID a été sautée lors de la promotion en maître, -force (chapitre 8.4)
license_paused le fbagent du maître n’a pas de licence chapitre 2.8
409 orphaned la base est hors de l’analyse du maître chapitre 3.8
incompatible_engine versions majeures de Firebird différentes chapitre 4.3
target_not_replica une base de travail occupe la place de la réplique (elle a été rendue normale) voir ci-dessous
target_other_replica (depuis HQbird 2027.2.24) une copie d’une autre base de ce nœud occupe la place de la réplique voir ci-dessous
restart_not_allowed le Firebird de la réplique sert aussi des bases maîtres 5.6, la case « Autoriser … à arrêter Firebird »
fbagent_required fbagent n’est pas installé sur la réplique chapitre 1
nbackup backup lock already active une sauvegarde nbackup est en cours 5.7
… -L did not finish in 2m0s and was stopped nbackup -L sur le maître ne s’est pas terminé en 2 minutes, le nœud l’a donc arrêté réessayez ; si l’erreur se répète, vérifiez le Firebird du maître (firebird.log)
reinit already in progress for this database l’initialisation de cette base est déjà en cours attendez qu’elle se termine

target_not_replica. Une base de travail occupe la place de la copie : elle a été rendue normale (le fichier <database>.hqcluster-normal.json existe) ou elle n’est pas en mode réplique. Le nœud n’écrase pas une base de travail. S’il faut la remplacer, une requête à l’API du nœud avec overwrite_non_replica: true (il n’y a pas de bouton pour cela dans RCM) remplacera le fichier et conservera l’ancien sous <database>.pre-reinit-<heure UTC>.fdb.

target_other_replica (depuis HQbird 2027.2.24). La réplique place la copie dans <databases.root>/<id du maître>/<chemin de la base>. L’id du maître n’est unique qu’à l’intérieur de son propre cluster, donc deux bases peuvent se retrouver avec le même chemin. Le nœud réplique n’écrase pas une copie qui appartient à une autre de ses bases : l’erreur nomme cette base et son maître. Le nœud reconnaît aussi une copie dont le chemin est enregistré autrement (un lien symbolique ou une jonction dans le chemin, un nom court de dossier Windows). overwrite_non_replica n’efface pas cette erreur. Déplacez l’une des copies vers un autre dossier ou retirez cette base de la réplique, puis relancez l’initialisation. Le nœud ne voit que ses propres bases : deux nœuds réplique sur le même hôte doivent avoir des dossiers de réplique différents (databases.root).

5.10. Comment vérifier le résultat

  1. Bases de données : la paire maître-réplique du groupe est Correct, état IN_SYNC.

  2. Vérifier dans la carte du maître : les nœuds comptent les lignes des tables de la liste de tables de la base (chapitre 3.1) sur le maître et sur la réplique et les comparent. Vérifiez pendant un moment calme : avec des écritures actives, les nombres peuvent différer.

    Avec HQbird 2027.2.24, la page de résultat nomme la liste de chaque côté (par exemple, « la liste propre de cette base » ou « tables de la publication (liste non définie) »). RCM compte la réplique avec la liste du maître. Une table absente des deux bases est affichée comme « pas dans la base » et n’est pas comptée comme erreur. Si aucune table n’a été comparée, le résultat est « Aucune table à comparer », pas un écart. Si la comparaison ne s’est pas terminée dans le temps imparti, le résultat est « Non comparé (limite de temps) », ce qui n’est pas non plus un écart.

Résultat de la vérification
Résultat de la vérification
Command
hqbirdrcm verifydata -master node-a -master-db <db_id> -replica node-b -replica-db <db_id>
  1. Vérification périodique (facultative) : la page Vérification des données, Activer pour tous les nœuds. Avec HQbird 2027.2.24, le nœud applique les paramètres immédiatement, aucun redémarrage du service du nœud n’est nécessaire : après Enregistrer, RCM écrit « Enregistré et déjà en vigueur ». Le nœud 2027.5.7 a besoin que le service hqclusternode soit redémarré, et RCM 2027.2.24 le dit. Les nœuds comparent eux-mêmes le nombre de lignes lorsque le maître et la réplique sont sur le même segment. Un écart lève l’alerte data_mismatch ; exécutez alors Vérifier.

Une table que l’opérateur a retirée de la publication est affichée comme « non publiée », pas comme un écart.

6. Configuration de la publication

La publication indique au Firebird maître les tables dont les modifications doivent être écrites dans les segments. Sans elle, la réplique ne reçoit rien.

6.1. Ce qu’est la publication

Dans Firebird 4 et 5, les tables à répliquer sont définies par la publication RDB$DEFAULT :

  • Publication activée : dans RDB$PUBLICATIONS, elle a RDB$ACTIVE_FLAG = 1 (la commande ALTER DATABASE ENABLE PUBLICATION).
  • Tables publiées : la liste dans RDB$PUBLICATION_TABLES.

Firebird n’écrit des modifications dans les segments que pour les tables publiées et seulement lorsque la publication est activée. Enregistrer la base (chapitre 3) n’active pas la publication. Elle est activée par Synchroniser la publication (6.2).

Le nœud maître vérifie la publication toutes les heures (limits.publication_check_interval_sec, 3600 par défaut). Si elle est désactivée, le nœud la vérifie toutes les 2 minutes.

Sur la page Bases de données, la base maître a une icône :

Icône Signification
publication activée publication activée
publication désactivée Firebird n’écrit rien dans les segments, les répliques ne reçoivent aucune modification
publication inconnue le nœud n’a pas pu lire l’état

Le filtre Publication désactivée affiche les bases dont la publication est désactivée ou inconnue.

Si une base dont la publication est désactivée a déjà une réplique, le maître lève l’alerte master_publication_off.

Avec HQbird 2027.2.24, le maître lève aussi cette alerte lorsqu’il a refusé d’initialiser une base avec l’erreur publication_off (chapitre 5.1) : la publication est désactivée ou ne contient aucune table avec une clé. Le niveau de l’alerte :

  • avertissement : la base n’a pas encore de réplique : l’initialisation attend la publication ;
  • grave : la base a déjà une réplique ;
  • information : l’opérateur a désactivé la publication.

L’alerte est effacée lorsque la publication est corrigée ou qu’une autre initialisation a commencé.

6.2. Synchroniser la publication

Ligne du maître : publication désactivée
Ligne du maître : publication désactivée

Où cliquer :

  • dans la ligne de la base maître sur la page Bases de données. Lorsque la publication est désactivée, le bouton est à côté de l’icône ;
  • sur la page de la base ;
  • pour plusieurs bases : cochez les lignes, dans la liste Action sélectionnez Synchroniser la publication. RCM enverra une commande distincte pour chaque base.
Confirmation de la synchronisation de la publication
Confirmation de la synchronisation de la publication

Ce que fait le nœud (une seule transaction) :

  1. Active la publication. Si l’opérateur l’a désactivée lui-même (6.4), il ne l’active pas.
  2. Ajoute à la publication toutes les tables avec une clé qui n’y sont pas encore.
  3. Retire de la publication les tables sans clé et les tables que l’opérateur a exclues (6.3).
  4. Désactive l’ajout automatique des nouvelles tables (EXCLUDE ALL FROM PUBLICATION, puis ajoute les tables nécessaires). Seul le nœud définit la composition de la publication.
Ligne du maître après synchronisation : publication activée
Ligne du maître après synchronisation : publication activée

Une table avec une clé est une table permanente utilisateur qui a une clé primaire ou un index unique actif. Les tables système et temporaires ne sont pas publiées.

La synchronisation retire aussi de la publication les tables sans clé que le DBA a ajoutées à la main.

Si la composition est déjà correcte, le nœud ne change rien.

Quand le nœud refuse :

Code Motif
no_publications HQbird 2.5/3.0 (6.6)
not_master le nœud n’est pas le maître
reinit_in_progress l’initialisation de cette base est en cours
orphaned, database_failed, file_missing la base est hors analyse, en erreur, ou n’a pas de fichier

Toutes les bases du nœud à la fois, depuis la ligne de commande uniquement. Sur la page Commandes, le résultat est affiché par base : fait, ignorée ou erreur. Les bases à l’état FAILED ou SEEDING et les bases sans fichier sont ignorées.

La même chose depuis la ligne de commande

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

La commande attend jusqu’à 5 minutes et affiche une ligne pour chaque base. En cas d’erreur, le code de sortie est 1. -nowait : ne pas attendre le résultat.

6.3. Tables de la publication

La page « Tables de la publication »
La page « Tables de la publication »

Ouvrez Tables de la publication dans la ligne de la base maître.

La page affiche :

  • l’état de la publication (activée/désactivée, désactivée par l’opérateur) et les compteurs ;
  • chaque table : nom, clé et état.
État Signification
publiée les modifications vont dans les segments
pas encore publiée une table avec une clé, sera ajoutée à la synchronisation
exclue l’opérateur l’a retirée de la publication
pas de clé ne peut pas être publiée

Dans la colonne de la clé : la clé primaire ou, s’il n’y en a pas, l’index unique avec le plus petit nombre de champs.

Pourquoi une table sans clé ne peut pas être publiée. La réplique recherche la ligne pour UPDATE et DELETE par la clé. Sans clé, elle ne trouvera pas la ligne. Ajoutez une clé primaire ou un index unique, puis synchronisez la publication.

Exclure de la publication / Remettre dans la publication :

  1. Cochez les tables.
  2. Cliquez sur Exclure de la publication ou Remettre dans la publication.
  3. Le nœud enregistre la liste et synchronise immédiatement la publication.
Confirmation de « Exclure de la publication »
Confirmation de « Exclure de la publication »

La liste des tables exclues est stockée sur le nœud maître. La synchronisation ne la change pas. Lorsqu’une réplique est promue en maître (chapitre 8), la liste passe au nouveau maître.

Vérifier (chapitre 5.10) affiche une table exclue comme « non publiée », pas comme un écart.

6.4. Activer et désactiver la publication

Sur la page Tables de la publication : Désactiver la publication / Activer la publication.

  • La désactivation est le choix de l’opérateur. La synchronisation ne réactive pas la publication.
  • Les modifications faites pendant que la publication est désactivée (ou pendant qu’une table est exclue) ne sont pas envoyées à la réplique, même après l’activation.
  • Après l’activation, cliquez sur Vérifier (chapitre 5.10). Si les données divergent, réinitialisez la réplique (chapitre 5).

6.5. Une nouvelle table

Une nouvelle table n’entre pas d’elle-même dans la publication : le nœud désactive l’ajout automatique.

Après le DDL :

  1. Créez une clé primaire ou un index unique sur la table.
  2. Cliquez sur Synchroniser la publication.
  3. Demandez aux applications de se reconnecter si une réinitialisation est nécessaire. Firebird n’écrit pas dans les segments les transactions commencées avant l’activation de la publication ; COMMIT RETAINING maintient une telle transaction ouverte. L’initialisation attend ces transactions puis échoue avec reinit_pre_publication_transactions (chapitre 5.4).
Une nouvelle table à l'état « pas encore publiée »
Une nouvelle table à l'état « pas encore publiée »

Les lignes écrites dans la nouvelle table avant la synchronisation n’atteindront pas la réplique. S’il y en a, vérifiez les données et, si nécessaire, réinitialisez la réplique.

6.6. HQbird 2.5 et 3.0

HQbird 2.5 et 3.0 n’ont pas de publications. Firebird écrit des segments si le fichier du greffon replconf contient un bloc maître. Les boutons de publication de ces nœuds sont masqués, et l’API répond no_publications.

L’ensemble des tables est défini par les paramètres du moteur :

Paramètre Signification
include_filter quelles tables répliquer : noms ou motifs séparés par des virgules ; vide : toutes
exclude_filter quelles tables ne pas répliquer

Les paramètres se changent dans Paramètres → Paramètres de réplication (chapitre 7.1). La page Tables de la publication les affiche en lecture seule, avec un lien Modifier dans les paramètres du moteur. Firebird lit les nouvelles valeurs après un redémarrage.

Tables de la publication sur HQbird 3.0 : filtres du moteur
Tables de la publication sur HQbird 3.0 : filtres du moteur

Le greffon replconf. Le nœud écrit son propre fichier replconf.hqcluster.hqbird dans le dossier Firebird. Firebird ne le lit que lorsque replconf.properties pointe vers lui. Le greffon doit être activé une fois :

  1. Paramètres → Nœuds, le bloc Greffon de réplication (HQbird 2.5 / 3.0). Le bloc montre vers où pointe replconf.properties et les problèmes que le nœud a trouvés.

Greffon non activé : replconf.properties pointe vers le fichier HQbird DataGuard
Greffon non activé : replconf.properties pointe vers le fichier HQbird DataGuard
  1. Activer… La fenêtre énumère ce que fera le nœud : installer le greffon, faire pointer replconf.properties vers le fichier du nœud, migrer les entrées de l’ancien fichier. Choisissez quand : Uniquement dans la fenêtre de redémarrage du nœud ou Maintenant, en ignorant la fenêtre de redémarrage.

Fenêtre d'activation du greffon
Fenêtre d'activation du greffon
  1. Après le redémarrage de Firebird, le champ Activé affiche « oui : le moteur lit le fichier du nœud ».

Greffon activé
Greffon activé

L’activation redémarre Firebird et concerne toutes les bases de ce Firebird. Faites-la pendant une période calme.

7. Autres options de réplication

7.1. Paramètres de réplication

Paramètres → Paramètres de réplication, formulaire de l'assistant
Paramètres → Paramètres de réplication, formulaire de l'assistant

La page Paramètres → Paramètres de réplication change les clés de replication.conf pour les bases sélectionnées ou pour le nœud dans son ensemble.

  1. Ajouter maître et répliques : sélectionnez les bases. RCM les regroupe par version de Firebird et rôle : un formulaire distinct pour les maîtres et pour les répliques.

  2. Pour chaque paramètre, choisissez une action :

    Action Ce qu’elle fait
    aucun changement la valeur n’est pas changée
    définir la valeur une nouvelle valeur
    réinitialiser (au niveau supérieur) retirer sa propre valeur, prendre la valeur du niveau au-dessus
    ne pas écrire (valeur Firebird) la clé n’est pas écrite, la valeur Firebird s’applique
  3. Choisissez où l’appliquer : Aux bases sélectionnées ou Comme valeur par défaut de leurs nœuds.

  4. Aperçu : les nœuds vérifient les valeurs sans rien changer.

Aperçu des modifications
Aperçu des modifications
  1. Appliquer. RCM envoie la commande à chaque nœud.

D’où vient la valeur (la colonne Actuel) :

Origine Valeur
cette base définie pour la base
valeur du nœud définie comme valeur par défaut du nœud
valeur intégrée du nœud la valeur du nœud issue du code
valeur Firebird la clé n’est pas écrite
depuis le fichier (pas encore définie ici) la valeur de replication.conf, RCM ne l’a pas encore changée
définie par le nœud lecture seule (chemins, préfixes)

Un nœud qui ne répond pas affiche ses bases comme indisponibles à la sélection. Les modifications exigent fbagent (sinon fbagent_required).

Qui redémarre Firebird (Firebird ne lit replication.conf qu’au démarrage) :

Nœud Qui
maître vous le redémarrez : le maître ne redémarre jamais Firebird lui-même
réplique avec firebird.auto_restart: never vous
réplique dont le Firebird sert aussi les bases du maître vous
les autres répliques le nœud le redémarre dans sa propre fenêtre de redémarrage

Pour un redémarrage manuel, la page a un bouton Redémarrer Firebird.

7.2. Paramètres principaux

Maître, Firebird 4/5 :

Paramètre Libellé dans RCM Valeur du nœud Firebird Conseil
journal_archive_timeout Délai d’archive 10 s 60 s combien de secondes Firebird attend avant de fermer un segment incomplet. Plus bas : la réplique est plus proche du maître. Doit être inférieur à limits.data_check_quiet_sec (90)
journal_segment_count Nombre de segments 64 8 combien de segments peuvent résider dans .ReplLog. Doit être supérieur à limits.backlog_critical (48)
journal_segment_size Taille du segment — 16 Mo de 1 Mo à 512 Mo ; le récepteur n’acceptera pas plus de 512 Mo
buffer_size — 1 Mo

Le nœud écrit aussi log_errors = true (ne peut pas être changé) et disable_on_error = true.

Réplique, Firebird 4/5 :

Paramètre Libellé dans RCM Firebird Valeur
apply_idle_timeout Pause d’inactivité 10 s pause lorsqu’il n’y a pas de nouveaux segments
apply_error_timeout Pause après une erreur d’application 60 s pause avant un nouvel essai après une erreur
verbose_logging nœud : true replication.log détaillé ; il n’est pas recommandé de le désactiver
skip_upddel_without_pk nœud : true ignorer UPDATE/DELETE sur les tables sans clé

Firebird 5 uniquement : include_filter, exclude_filter, cascade_replication.

HQbird 2.5/3.0 : clés log_* avec la même signification : log_archive_timeout, log_segment_count, log_segment_size (pas inférieur à 2 × buffer_size). La clé alert_command n’est définie que dans node.json.

Une indication pour chaque paramètre est disponible dans le formulaire RCM.

7.3. Stockage de l’archive

L’archive <database>.LogArch du maître est nettoyée par étapes :

  1. Segments qui ont été appliqués par toutes les répliques et qui sont plus anciens que retention_days.
  2. Si l’espace libre est inférieur à free_space_floor_gb, segments appliqués plus récents que la période de conservation. Alerte disk_serious_cleanup.
  3. Si l’espace est encore bas, segments non appliqués, en commençant par les plus anciens. La réplique reçoit NEEDS_REINIT, alerte replication_paused_reinit_scheduled.
Paramètre (Paramètres → Nœuds, Stockage et fichiers) Par défaut
limits.retention_days : Conservation de l’archive, jours 2
limits.retention_min_kept_segments : Toujours conserver les derniers segments 0 (désactivé)
limits.free_space_floor_gb : Espace libre minimum 1 Go
Paramètres → Nœuds, « Stockage et fichiers »
Paramètres → Nœuds, « Stockage et fichiers »

Nettoyer l’archive à la main :

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 (seulement avec -db) supprime tous les segments de la base à l’état ORPHANED (chapitre 3.8). Pour toute autre base, le nœud répondra not_orphaned. N’exécutez jamais -orphaned sur le donneur de la promotion (chapitre 8.5).

7.4. Transfert : compression, vitesse, fenêtres

La compression se définit par pair : Paramètres → Nœuds → Pairs, colonne compress.

Valeur Signification
vide ou none pas de compression (par défaut)
zstd compression zstd

La modification prend effet immédiatement. La compression est utile sur un réseau lent.

Vitesse de transfert des segments (Paramètres → Nœuds, Transfert et réinitialisation) :

Paramètre Par défaut Quand cela prend effet
limits.channel_a_mbps : Vitesse de transfert des segments 50 Mo/s immédiatement
limits.channel_a_burst_mbps : Rafale de transfert des segments 200 Mo immédiatement

L’unité est le mébioctet (Mio), même si le nom dit « mbps ». La rafale ne peut pas être inférieure à la vitesse.

Paramètres → Nœuds, « Transfert et réinitialisation »
Paramètres → Nœuds, « Transfert et réinitialisation »

Fenêtres de temps (Fenêtres de temps) :

Paramètre Par défaut Quand cela prend effet Ce que cela affecte
windows.restart_window : Fenêtre de redémarrage de Firebird maître 22:00-05:00, réplique always immédiatement quand le nœud réplique peut redémarrer Firebird
windows.transfer_window : Fenêtre de transfert 23:00-05:00 après le redémarrage du nœud vitesse pleine d’initialisation (chapitre 5.5)

Le libellé à côté de chaque champ montre quand la modification prend effet : immédiatement ou redémarrage du nœud.

Paramètres → Nœuds, « Fenêtres de temps »
Paramètres → Nœuds, « Fenêtres de temps »

7.5. Vérification des données

  • Vérifier : une comparaison ponctuelle du nombre de lignes sur le maître et la réplique (chapitre 5.10).
  • Vérification des données : une comparaison périodique (chapitre 5.10). Le nœud effectue la comparaison lorsque le maître et la réplique sont sur le même segment.
  • Avec HQbird 2027.2.24, les paramètres de vérification prennent effet immédiatement après Enregistrer ; le redémarrage du service du nœud n’est pas nécessaire. RCM affiche « Enregistré et déjà en vigueur ». Après l’activation, la première vérification s’exécute après un intervalle. Après la désactivation, une vérification en cours est interrompue et n’écrit rien. Le nouvel intervalle est compté à partir de la fin de la dernière vérification. Conserver, jours, Limite de requête, Calme et Générateur de progression prennent effet à partir de la vérification suivante.
  • Le nœud 2027.5.7 ne lit ces paramètres qu’au démarrage : après Enregistrer, redémarrez le service hqclusternode de ce nœud. RCM 2027.2.24 affiche « Enregistré, mais pas encore en vigueur » et indique le motif.
  • Quelles tables comparer est défini par la liste de tables de la base (chapitre 3.1). Avec HQbird 2027.2.24, chaque base peut avoir sa propre liste : le champ à l’enregistrement ou le bloc Tables de suivi de la synchronisation sur la page de la base du maître (chapitre 3.3). La page Vérification des données montre quelle liste a été utilisée, et le nombre de tables « pas dans la base ». En 2027.5.7, la liste est par nœud (sync_tables).
  • Les tables exclues de la publication sont affichées comme « non publiée » (chapitre 6.3).
Page de vérification des données
Page de vérification des données

7.6. Alertes

Page des alertes
Page des alertes

La page Alertes. Actions :

  • Accuser réception : l’alerte reste visible mais est marquée accusée ;
  • Mettre en sourdine pendant 60 min : masquer pendant une heure ;
  • Supprimer / Supprimer toutes avec ce code : RCM transmet la suppression au nœud qui a levé l’alerte. Si la cause demeure, l’alerte réapparaîtra.
Command
hqbirdrcm clearalerts -code backlog_warn   # also -id, -acked, -all

À partir de HQbird 2027.2.33, RCM envoie les alertes vers Telegram, vers un webhook (Slack, Teams, JSON) et par courriel. Les canaux se configurent dans la section notify.channels du fichier rcm.json. Le bloc Canaux de notification de la page Alertes montre les canaux et envoie un message de test. RCM signale les problèmes de niveau warn et au-dessus : un problème est apparu, est devenu plus grave, ou a été effacé. Sans canaux, RCM n’envoie rien. Les versions antérieures n’envoient pas : surveillez la page Alertes ou interrogez l’API RCM.

Codes principaux :

Code Signification
backlog_warn / backlog_critical 32 / 48 segments non archivés dans .ReplLog
disk_serious_cleanup l’archive est nettoyée à l’étape 2 (7.3)
replication_paused_reinit_scheduled segments non appliqués supprimés, initialisation nécessaire
shipping_paused l’envoi vers le pair est suspendu (7.7)
apply_error, replication_stopped, replication_unrecoverable_error la réplique ne peut pas appliquer un segment
replication_guid_mismatch le GUID de la base maître a changé
segment_missing, segment_rejected, sequence_gap problèmes de séquence des segments
firebird_down, firebird_log_error Firebird n’est pas en cours d’exécution ou journalise des erreurs
firebird_not_answering à partir de HQbird 2027.2.30 : Firebird n’a pas répondu à une connexion de base pendant une minute (blocage). Cela inclut aussi une connexion qui n’a pas pu s’établir à cause d’un délai ; firebird_down est seulement un refus de connexion
master_publication_off la publication est désactivée (chapitre 6) ; à partir de HQbird 2027.2.24 et après un échec publication_off (chapitre 6.1)
replica_removed_for_reinit à partir de HQbird 2027.2.24 : la réplique a supprimé l’ancienne copie pour l’initialisation, et il n’y a pas encore de nouvelle copie (chapitre 4.4)
orphaned_database base hors analyse (chapitre 3.8)
restart_required_after_reinit le Firebird de la réplique a besoin d’un redémarrage (chapitre 5.6)
data_mismatch la vérification périodique a trouvé un écart
license_paused fbagent n’a pas de licence (chapitre 2.8)

7.7. Mettre l’envoi en pause

Sur la page Bases de données, dans la ligne du maître : Mettre l’envoi en pause / Reprendre l’envoi. Pour plusieurs bases, via la liste Action.

Command
hqbirdrcm pauseshipping  -node node-a -db <db_id>
hqbirdrcm resumeshipping -node node-a -db <db_id>
Confirmation de la mise en pause de l'envoi
Confirmation de la mise en pause de l'envoi
Ligne du maître pendant une pause
Ligne du maître pendant une pause
  • La pause reste en vigueur jusqu’à Reprendre l’envoi ou jusqu’à l’initialisation.
  • Le Firebird maître continue d’écrire des segments. L’archive .LogArch grossit : tant que la réplique est arrêtée, l’étape 1 (7.3) ne supprime pas ses segments.
  • Une longue pause peut atteindre l’étape 3 et NEEDS_REINIT. Surveillez l’espace.
  • Le bouton est absent si la base n’a pas de réplique ou si la publication est désactivée. L’icône Pause : pas de licence signifie une pause liée à la licence (chapitre 2.8) ; seule une licence l’efface.

7.8. Journaux

Journal Où
Nœud <dossier d'installation>/logs/node-YYYYMMDD.jsonl (/opt/hqclusternode ou C:\hqclusternode), 32 Mo chacun, 20 fichiers
replication.log et firebird.log de Firebird chemins dans node.json : firebird.replication_log, firebird.firebird_log
RCM Linux : journalctl -u hqbirdrcm
Audit RCM rcm-data/audit.jsonl

Journal distant du nœud : la page Journaux : sélectionnez un nœud et une source (replication.log, firebird.log, agent du nœud).

Page des journaux
Page des journaux
Command
hqbirdrcm getlogs -node node-b -source replication -tail 200

8. Comment faire passer une réplique à une base de données ordinaire

Il y a deux chemins :

Chemin Quand Ce que vous obtenez
Rendre normale, 8.1 vous avez besoin d’une copie de travail séparée : rapports, tests, une panne sans nouveau maître une base ordinaire hors réplication
Promouvoir en maître, 8.3 la réplique doit devenir le nouveau maître une base gérée par un nœud compagnon avec le rôle maître

Aucun des deux chemins ne peut être annulé depuis l’interface.

8.1. Rendre normale

Liste « Action » de la réplique : l'élément « Rendre normale »
Liste « Action » de la réplique : l'élément « Rendre normale »
  1. Bases de données, côté réplique : cochez les lignes de la réplique.

  2. Dans la liste Action, sélectionnez Rendre normale et confirmez. Il n’y a pas de bouton distinct dans la ligne. Il n’y a pas non plus de commande en ligne de commande.

Confirmation de « Rendre normale »
Confirmation de « Rendre normale »
3. Le nœud réplique : - exécute `gfix -replica none` (HQbird 2.5/3.0 : `gfix -replica {}`). Si la base est occupée à appliquer des segments, le nœud la met en arrêt `single` pendant quelques secondes (`gfix -shut single -force 0`), retire le mode réplique et la remet avec `gfix -online normal`. **Toutes les connexions à cette base sont coupées** ; - écrit le fichier marqueur `.hqcluster-normal.json` (heure, auteur, db_id, GUID) ; - commence à vider la file `.Incoming` (8.2). 4. RCM affiche la base dans le groupe **Pas une réplique (normale)**.
La page « Bases de données » après « Rendre normale »
La page « Bases de données » après « Rendre normale »

Après cela, la base est ouverte en écriture.

Retirez le bloc de la réplique de replication.conf. Le nœud le retire à l’analyse suivante, et Firebird lit le fichier au démarrage :

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

Jusque-là, les erreurs « la base n’est pas en mode réplique » pour cette base ne sont pas levées comme alertes.

Le fichier marqueur protège la base. L’initialisation n’écrasera pas une telle base : elle est refusée avec target_not_replica (chapitre 5.9). Supprimer seulement le marqueur ne suffit pas : le nœud vérifie aussi le mode réplique dans l’en-tête de la base. La case Supprimer l’ancienne réplique (chapitre 4.4) ne supprime pas non plus une telle base.

Avec HQbird 2027.2.24, pendant que la réplique supprime l’ancienne copie de cette base pour l’initialisation, Rendre normale est refusé avec reclaim_in_progress : réessayez plus tard.

Si la base doit redevenir une réplique, seule une nouvelle initialisation avec écrasement le permettra. Cela se fait via l’API du nœud (overwrite_non_replica: true) ; il n’y a pas ce bouton dans RCM. L’ancien fichier est conservé sous <database>.pre-reinit-<heure UTC>.fdb, et le marqueur est supprimé.

8.2. Ce qui arrive aux segments

  • Tant que le nœud n’a pas analysé les bases, le maître continue d’envoyer des segments. Toutes les 30 secondes, le nœud réplique supprime les anciens segments et ne conserve que les 100 derniers (keep_segments).
  • Après l’analyse, l’enregistrement de la base sur la réplique reçoit l’état ORPHANED. Le nœud réplique répond au maître avec unknown_database. Le maître cesse d’envoyer des segments à cette réplique, cesse de conserver une archive pour elle, et la revérifie toutes les 10 minutes.
  • Les autres répliques de cette base ne sont pas affectées.
  • L’enregistrement ORPHANED peut être supprimé (chapitre 3.8) : hqbirdrcm forgetdatabase. Le fichier de la base lui-même n’est pas supprimé.

8.3. Promouvoir en maître

La réplique devient le nouveau maître. Son fichier reste en place, et le contrôle passe au nœud compagnon.

Conditions :

Condition Refus
la base est une réplique bad_request
un nœud avec le rôle maître, le compagnon, est en cours d’exécution sur le même hôte (même étiquette host dans rcm.json, chapitre 2.1) no_companion
la promotion de cette base n’est pas déjà en cours already_running
il n’y a pas d’initialisation vers cette base ni depuis son maître reinit_running

RCM ne crée pas le nœud compagnon : installez-le à l’avance (chapitre 1).

Comment démarrer :

  • dans la ligne de la réplique, Promouvoir en maître, ou dans la liste Action ;

  • depuis la ligne de commande :

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

RCM demandera une confirmation et nommera le nœud compagnon.

Confirmation « Promouvoir en maître ? »
Confirmation « Promouvoir en maître ? »

Étapes (visibles dans la ligne de la réplique, noms en anglais) :

N° Étape Ce qu’elle fait
1 TURN TO NORMAL comme en 8.1 ; sautée si la base est déjà normale
2 NEW GUID un nouveau GUID de base sur place (8.4)
3 EXCLUDE ON DONOR le nœud réplique (donneur) exclut le fichier de son analyse (exclude_paths)
4 ENROLL ON le nœud compagnon enregistre le fichier comme base maître
5 PUBLICATION SYNC synchronisation de la publication ; la liste des tables exclues est reprise de l’ancien maître (chapitre 6.3)
6 RESTART DONOR FIREBIRD redémarrage du Firebird du donneur, sans attendre une fenêtre
7 RESTART FIREBIRD redémarrage du Firebird du compagnon, sans attendre une fenêtre
8 FINALIZE la ligne du donneur devient Réplique fantôme ; l’ancien maître peut devenir Maître dégradé (8.5)
Étapes de la promotion dans la ligne de la réplique
Étapes de la promotion dans la ligne de la réplique

Sur HQbird 2.5 et 3.0, il n’y a pas de publications : l’étape PUBLICATION SYNC se termine avec le texte « ce moteur n’a pas de publication ».

Étapes de la promotion sur HQbird 3.0 (Windows)
Étapes de la promotion sur HQbird 3.0 (Windows)

Si le donneur et le compagnon utilisent le même Firebird, ce Firebird est redémarré : les connexions vers toutes ses bases sont coupées.

Si une étape échoue, le travail reçoit failed avec le texte de l’erreur. Corrigez la cause et cliquez de nouveau sur Promouvoir en maître : les étapes terminées ne sont pas répétées. Si RCM redémarre pendant la promotion, le travail passera aussi à failed : vérifiez l’état des nœuds et réessayez.

Licence. Si le fbagent de l’hôte du maître n’a pas de licence, le maître a mis l’envoi en pause. La promotion reste possible. RCM vous avertira : les modifications faites après le début de la pause seront perdues.

8.4. Nouveau GUID

Après la promotion, la base doit recevoir son propre GUID. Sinon le nouveau maître écrit des segments sous le GUID de l’ancien maître, et ses répliques sont rejetées avec duplicate_guid.

L’étape NEW GUID sur le nœud :

  1. gfix -shut single -force 0 : toutes les connexions à la base sont terminées ;
  2. nbackup -L, puis nbackup -F sans -SEQUENCE ;
  3. supprime <database>.delta ;
  4. vérifie l’en-tête : nouveau GUID, REPLICATION_SEQUENCE = 0 ;
  5. gfix -online normal.

Firebird n’est pas redémarré. La méthode fonctionne sur toutes les versions (2.5, 3.0, 4.0, 5.0).

Si l’étape a été interrompue, le nœud émet l’alerte newguid_interrupted. La base peut rester en arrêt single. Répétez Promouvoir en maître : l’étape continuera.

L’étape est sautée (le texte commence par skipped:) si le nœud donneur est une ancienne version ou si le fichier a déjà son propre GUID.

Après un nouveau GUID, l’ancienne chaîne nbackup ne convient plus. Faites une nouvelle copie nbackup de niveau 0.

Si la base a été créée avec ADD DIFFERENCE FILE, son .delta se trouve ailleurs : supprimez-le à la main.

8.5. Après la promotion

Enregistrement du donneur. Sur le nœud réplique, la base reste ORPHANED, le chemin reste dans exclude_paths, et le dossier .Incoming ainsi que l’étiquette restent. Dans RCM, c’est la ligne Réplique fantôme avec les boutons Ouvrir sur le nouveau maître et Effacer.

Ligne du donneur : « Réplique fantôme »
Ligne du donneur : « Réplique fantôme »
  • Pour retirer la ligne, cliquez sur Effacer. Cela ne change que RCM.
  • Pour retirer l’enregistrement du donneur du nœud réplique, exécutez forgetdatabase. Le fichier et le dossier .Incoming restent. HQbird 2027.2.30 et ultérieur ne rejette pas la commande (mailbox_active), parce que le chemin du donneur est dans exclude_paths. Les nœuds des versions antérieures la rejettent tant que le fichier et le dossier .Incoming sont présents.
  • N’exécutez jamais cleanuparchive -orphaned sur le donneur. Le donneur et le compagnon partagent le même dossier <database>.LogArch. La commande supprimera l’archive vivante du nouveau maître.

Ancien maître.

  • Si le donneur était sa dernière réplique en fonctionnement, RCM met l’ancien maître à Maître dégradé et met en pause l’envoi vers le donneur (« envoi en pause : … (promotion en maître) »). Ne reprenez pas l’envoi vers le donneur : il contient déjà une base de travail. Pour effacer cet état, initialisez la base vers une autre réplique.

    Ancien maître : « Maître dégradé », envoi en pause
    Ancien maître : « Maître dégradé », envoi en pause
  • L’initialisation depuis l’ancien maître vers le nœud donneur sera rejetée (target_not_replica) : il contient déjà une base de travail.
  • Si l’étape NEW GUID a été sautée, l’ancien et le nouveau maître ont le même GUID. Dans ce cas, l’initialisation depuis l’ancien maître exige -force (chapitre 5.9).
  • Après une promotion manuelle, RCM ne transforme pas l’ancien maître en réplique du nouveau maître. Arrêtez les applications sur l’ancien maître et retirez sa base de la gestion (chapitre 3.8). Pour une base décrite comme service, c’est Réintégrer qui le fait (8.7).

Nouveau maître. Configurez une réplique pour lui : nœud réplique, pairs (chapitre 2), publication (chapitre 6), initialisation (chapitre 5).

Nouveau maître : base avec un nouveau GUID, pas encore de réplique
Nouveau maître : base avec un nouveau GUID, pas encore de réplique

8.6. Bascule planifiée : liste de contrôle

C’est la procédure d’une bascule manuelle. Pour une base décrite comme service, RCM change le maître lui-même (8.7). Une promotion manuelle ne vérifie pas si les applications écrivent sur l’ancien maître. Procédure :

  1. À l’avance. Sur l’hôte de la réplique, un nœud compagnon avec le rôle maître est en cours d’exécution, et les deux nœuds ont la même étiquette host (chapitre 2.1). Un nœud pour la future réplique est prêt pour le nouveau maître.
  2. Arrêtez les écritures des applications vers la base de l’ancien maître.
  3. Attendez que la réplique ait tout reçu et appliqué : Bases de données → IN_SYNC, pas de file.
  4. Vérifier (chapitre 5.10) : les nombres de lignes correspondent.
  5. Promouvoir en maître (8.3). Attendez l’étape FINALIZE.
  6. Vérifiez : la base est dans la liste des maîtres du compagnon, publication activée.
  7. Basculez les applications vers le nouveau maître.
  8. Faites une copie nbackup de niveau 0 de la nouvelle base (8.4).
  9. Effacez l’enregistrement fantôme de la ligne du donneur (8.5).
  10. Connectez la réplique au nouveau maître et initialisez-la (chapitre 5).
  11. Ancien maître : retirez la base de la gestion ou laissez-la comme archive (8.5).

8.7. Services : bascule et basculement dans RCM

Avec HQbird 2027.2.30, RCM déplace lui-même le maître vers un autre hôte. Pour cela, la base est décrite comme un service : une base logique sur plusieurs hôtes. Sur chaque hôte du service, il y a un nœud maître et un nœud réplique, et le chemin du fichier de la base est le même. Le service se crée sur la page Services (à partir de HQbird 2027.2.31) ou avec la commande hqbirdrcm services put -id <id> -file <file>.json.

Action Ce qu’elle fait Commandes
Bascule transfert planifié du maître sans perte de données. Ensuite l’ancien maître devient automatiquement une réplique du nouveau maître hqbirdrcm switchover -service <id> -check, puis hqbirdrcm switchover -service <id> -to <host>
Basculement l’hôte du maître est perdu : RCM promeut la réplique. Les modifications les plus récentes du maître peuvent être perdues hqbirdrcm failover -service <id> -check, puis hqbirdrcm failover -service <id> -to <host> -accept-data-loss
Réintégrer après un basculement, ramène l’ancien hôte comme réplique du nouveau maître hqbirdrcm rejoin -service <id>
Reprendre sort le service de l’état failed hqbirdrcm resume -service <id> -check, puis hqbirdrcm resume -service <id>

Les mêmes actions sont disponibles sur la page du service : les boutons Bascule…, Basculement…, Réintégrer… et Reprendre….

  • Le basculement automatique est désactivé par défaut. Il s’active pour chaque service séparément : hqbirdrcm policy -service <id> -auto-failover on -max-data-loss 30. Il exige des routeurs. RCM ne démarre un basculement que lorsque le nœud maître est silencieux, la majorité des routeurs ne voit pas le Firebird du maître, et le retard de la réplique ne dépasse pas max_data_loss_sec.
  • Un routeur (hqclusternode router, Linux) maintient HAProxy sur le maître actuel du service. Les applications se connectent à <hôte du routeur>:<router_port> et ne changent pas la chaîne de connexion lors d’une bascule.
  • Après un basculement, RCM isole l’ancien maître (rôle fenced) dès qu’il répond de nouveau. Ramenez-le avec la commande rejoin.