Guía del administrador para el clúster de replicación de HQbird: hqclusternode y hqbirdrcm (RCM). Instaladores: Descarga de HQbird 2027.

Contenido


0. Introducción

Esta guía describe cómo instalar y usar el clúster de replicación de HQbird: los nodos hqclusternode y el gestor del clúster hqbirdrcm (RCM).

Es una guía para el administrador de Firebird. Se supone que conoce Firebird, gfix y nbackup. No necesita conocer el funcionamiento interno de un nodo.

De qué se compone el clúster

Componente Cuántos Dónde se ejecuta Qué hace
Firebird (HQbird) una o varias instancias en cada servidor de bases de datos almacena las bases de datos y escribe los segmentos de replicación
fbagent uno por instancia de Firebird junto a Firebird detiene e inicia Firebird a petición de un nodo
hqclusternode (nodo) uno por instancia y rol junto a Firebird configura la replicación, transfiere los segmentos y realiza la inicialización de la réplica
hqbirdrcm (RCM) uno por clúster en cualquier host que pueda ver todos los nodos interfaz web, comandos, alertas y estadísticas

Un nodo tiene un rol: master o replica. En una misma instancia de Firebird pueden ejecutarse dos nodos: un nodo maestro y un nodo réplica. En ese caso, algunas bases de datos de este Firebird son maestras y otras son réplicas.

Cómo funciona

  1. En el maestro, Firebird escribe los cambios de la base de datos en segmentos (archivos del registro de replicación).
  2. El nodo maestro envía los segmentos al nodo réplica por un canal protegido (mTLS).
  3. El nodo réplica coloca los segmentos en la carpeta de segmentos entrantes. El Firebird de la réplica los aplica a su copia de la base de datos.
  4. El propio nodo maestro transfiere la primera copia de la base de datos a la réplica. Esto se llama inicialización (reinit). Se hace mediante nbackup, y el maestro sigue en funcionamiento durante ese tiempo.
  5. Los nodos envían estadísticas a RCM. RCM muestra el estado del clúster y envía los comandos del operador a los nodos.
Cómo funciona el clúster: segmentos, inicialización, estadísticas y comandos del operador
Cómo funciona el clúster: segmentos, inicialización, estadísticas y comandos del operador

Versiones compatibles

  • Firebird / HQbird 5.0 y 4.0: todas las funciones.
  • HQbird 3.0 y 2.5: replicación mediante el complemento replconf. No hay publicaciones; el conjunto de tablas se define mediante filtros. Las diferencias se describen en los recuadros «HQbird 2.5/3.0».

La versión mayor de Firebird en el maestro y en la réplica debe coincidir. De lo contrario, el nodo réplica rechazará la inicialización.

Puertos

Puerto Quién escucha Quién se conecta Para qué
7051 nodo los demás nodos y RCM API del nodo, transferencia de segmentos y de copias de la base de datos
7443 RCM todos los nodos recepción de estadísticas de los nodos
7444 RCM operador interfaz web y API del operador. Instalación mediante RCM (capítulo 1.3): HTTPS en todas las direcciones. Instalación mediante HQCenter Admin o manual: HTTP, solo 127.0.0.1
7450–7459 fbagent, mientras la ventana de vinculación está abierta RCM vinculación de hosts (capítulo 1.3)
13050 fbagent, solo 127.0.0.1 nodo en el mismo host gestión de Firebird
3050 Firebird aplicaciones funcionamiento normal de la base de datos

Si hay dos nodos en un mismo host (maestro y réplica), el segundo nodo tiene otro puerto. Cuando se instala mediante RCM, el segundo nodo recibe el puerto 7061. En los demás casos usted mismo define el puerto, por ejemplo 7052.

El puerto 13050 no debe quedar expuesto a la red. El puerto 7444 con HTTP (instalación mediante HQCenter Admin o manual) tampoco: conéctese a la interfaz web de RCM a través de un túnel SSH (capítulo 1). Cuando se instala mediante RCM, el puerto 7444 funciona por HTTPS, y el instalador lo abre en el cortafuegos.

La regla principal: sin fbagent, no hay cambios

Un nodo cambia la configuración de replicación solo a través de fbagent: necesita reiniciar Firebird. Si fbagent no está disponible, el nodo rechaza cualquier acción que cambie la configuración. No trabaja «a medias».

Términos

Término Significado
Segmento archivo del registro de replicación con los cambios de la base de datos
Publicación lista de tablas del maestro cuyos cambios entran en los segmentos (Firebird 4/5)
Inicialización (reinit) transferencia de una copia de la base de datos del maestro a la réplica mediante nbackup
GUID de la base de datos identificador de la base de datos de Firebird; RCM lo usa para vincular el maestro y la réplica
Par nodo asociado: para un maestro, sus réplicas
Compañero el segundo nodo de la misma instancia de Firebird (maestro y réplica en un mismo host)
Inscripción registro de las bases de datos maestras en el nodo

Cómo leer la guía

Capítulo Tema
1. Instalación instalación de los nodos y de RCM mediante HQCenter Admin, mediante RCM sin HQCenter Admin y de forma manual, Linux y Windows
2. Configuración del clúster enlaces maestro → réplica, ajustes de los nodos, usuarios de RCM
3. Añadir una base de datos al maestro inscripción, reinicio de Firebird, comprobación
4. Cómo convertir una base de datos en réplica etapas, preparación de la réplica, espacio en disco
5. Inicialización pasos de la reinicialización, efecto sobre el funcionamiento, transacciones largas, velocidad, errores
6. Configuración de la publicación publicación de Firebird 4/5, tablas, tablas nuevas, HQbird 2.5/3.0
7. Otras opciones de replicación parámetros de replication.conf, archivo, transferencia, alertas, pausa, registros
8. Conversión de una réplica en una base de datos normal Hacer normal, Promover a maestro, GUID nuevo, servicios (conmutación, conmutación por error), lista de comprobación de la conmutación

Todos los capítulos usan un mismo ejemplo:

Qué Valor
node-a nodo maestro, bases de datos en /databases/master
node-b nodo réplica, bases de datos en /databases/replica
RCM un host aparte (también puede ser uno de los servidores de bases de datos)
base de datos employee.fdb

1. Instalación de los nodos y de hqbirdrcm

Hay tres métodos de instalación:

Método Cuándo elegirlo Qué hace usted mismo
Mediante HQCenter Admin (1.2) el camino habitual: el servidor de actualizaciones de HQCenter Admin es accesible y se necesitan actualizaciones automáticas ejecuta el script de instalación de fbagent, aprueba la solicitud y describe el clúster
Mediante RCM, sin HQCenter Admin (1.3) no hay HQCenter Admin, pero necesita certificados, configuración y actualizaciones sin trabajo manual; hasta 3 servidores de bases de datos instala HQbird en cada host, inicia sesión en RCM y, en Configuración → Vincular hosts, indica las direcciones de los hosts
Manual (1.4) sin acceso a HQCenter Admin, red cerrada, requisitos especiales instala los archivos, crea los certificados, escribe node.json y rcm.json, y registra los servicios

Mediante HQCenter Admin y mediante RCM usted no instala los nodos ni RCM. Los instala fbagent cuando lo añade al clúster (capítulo 2). Los certificados y la configuración también se crean automáticamente.

Linux y Windows se describen en un solo capítulo. Las diferencias de Windows están en los recuadros «En Windows».

1.1. Requisitos

En cada servidor de bases de datos:

  • Firebird / HQbird 5.0, 4.0, 3.0 o 2.5 (2.5, solo Linux).
  • fbagent junto a cada instancia de Firebird. Sin fbagent el nodo no funciona.
  • Sincronización horaria (NTP, chrony, w32time) en todos los servidores y en el host de RCM. Las ventanas de reinicio y de transferencia, la estimación del retraso y la comprobación de «nodo que no responde» dependen de los relojes.
  • Espacio libre para el archivo de segmentos y para la inicialización de la réplica (capítulo 4).
  • Red según la tabla de puertos (capítulo 0).

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

Windows: privilegios de administrador, x64, Windows 10 / Server 2016 o posterior, Windows PowerShell de 64 bits 5.1. En Windows 10 y Server 2016–2022 se necesita 7-Zip.

Dónde se ejecutará RCM. Se necesita un RCM por clúster. Puede instalarse en cualquier servidor que pueda ver todos los nodos, incluido uno de los servidores de bases de datos.

1.2. Instalación mediante HQCenter Admin

Paso 1. Ejecutar el script de instalación de fbagent

El script instala Firebird (la compilación de HQbird), fbagent, y registra fbagent en el servidor de HQCenter Admin. Elija el script que corresponda a su versión de Firebird: fb25, fb30, fb40, fb50.

Linux (como root):

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

En Windows (PowerShell como administrador):

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

En Windows no existe el parámetro -Cluster: fbagent se ejecuta como LocalSystem y crea él mismo las carpetas del clúster.

Parámetros principales:

Linux Windows Significado
--goafts <name> -Goafts servidor de HQCenter Admin desde el que se descarga; el nombre lo facilita su proveedor
--enroll -Enroll registrar fbagent en HQCenter Admin (solicitud de certificado)
--cluster — crear las carpetas /opt/hqclusternode y /opt/hqbirdrcm (solo necesario para fbagent 2.55.2 y anteriores; inofensivo en versiones más recientes)
--channel -Channel canal de actualización de fbagent, stable de forma predeterminada
--token -Token token de licencia: HQCenter Admin aprobará la solicitud automáticamente
--port -Port puerto de Firebird
--yes -Yes no hacer preguntas (necesario cuando no hay terminal)

La lista completa de parámetros está en el README del script de instalación de fbagent.

Paso 2. Aprobar la solicitud de fbagent

Con el parámetro --enroll, fbagent envía una solicitud de certificado (CSR) a HQCenter Admin y espera hasta 30 minutos la aprobación. Puede aprobarla así:

  • automáticamente, si la instalación se ejecutó con un token de licencia (--token) y la licencia tiene un puesto libre;
  • en el panel de HQCenter Admin, sección de solicitudes CSR, la solicitud de este host, botón de aprobar y firmar;
  • mediante la API de HQCenter Admin: POST /v1/admin/csr-requests/{id}/approve.

Si el registro no tuvo éxito (por ejemplo, se agotó el tiempo de espera), fbagent sigue funcionando, pero el script termina con el código 2. Vuelva a ejecutar el script con los mismos parámetros: solo se repetirá el registro.

Unos minutos después del registro, fbagent instala HQ Monitor por sí mismo.

Paso 3. Describir el clúster

Los nodos y RCM aparecen cuando añade fbagent al clúster de HQCenter Admin. Cómo describir el clúster se explica en el capítulo 2.

Después de guardar el clúster:

  1. En un plazo de 10 minutos fbagent recibe el clúster de HQCenter Admin (después comprueba si hay cambios cada 60 segundos).
  2. El fbagent del host de RCM crea la autoridad de certificación (CA) del clúster y firma los certificados de todos los nodos.
  3. Cada fbagent escribe node.json o rcm.json para los miembros de su clúster.
  4. En la siguiente comprobación de productos (cada 3 minutos) fbagent instala e inicia los servicios.

Qué se instala y dónde:

Qué Linux Windows
Nodo maestro /opt/hqclusternode/master/, servicio hqclusternode-master-p<port> <HQbird>\hqclusternode\master\, servicio HQClusterNode-master-p<port>
Nodo réplica /opt/hqclusternode/replica/, servicio hqclusternode-replica-p<port> <HQbird>\hqclusternode\replica\, servicio HQClusterNode-replica-p<port>
RCM /opt/hqbirdrcm/, servicio hqbirdrcm <HQbird>\hqbirdrcm\, servicio hqbirdrcm

<port> es el puerto de Firebird, por ejemplo 3050. Un mismo fbagent no puede alojar más de un nodo maestro, un nodo réplica, un RCM y un enrutador (hqclusternode router, a partir de HQbird 2027.2.30, capítulo 8.7).

En Windows. Las versiones de fbagent anteriores a 2.83.0 instalaban los nodos en C:\hqclusternode y RCM en C:\hqbirdrcm. Si esas carpetas existen, fbagent sigue usándolas.

Actualizaciones

  • fbagent comprueba si hay versiones nuevas del nodo y de RCM cada 3 minutos; el canal predeterminado es stable. Primero se actualiza el nodo réplica y después el nodo maestro.
  • Si, tras una actualización, el servicio no arranca o informa de una versión incorrecta, fbagent vuelve a la versión anterior y bloquea la nueva. La lista de bloqueos: <carpeta de fbagent>/update/<product>/blocked-versions.json. Para volver a probar la versión, borre su línea de este archivo.
  • Estado del producto: fbagent --product-status hqclusternode (o hqbirdrcm).

1.3. Instalación mediante RCM (sin HQCenter Admin)

El clúster lo gestiona RCM. El fbagent de cada host recibe la descripción del clúster desde RCM, el fbagent del host de RCM firma los certificados, y el nodo y RCM se actualizan desde las versiones almacenadas por RCM.

Limitaciones:

  • Un clúster por RCM.
  • No más de 3 puestos. Un puesto es un host que ejecuta un nodo maestro o réplica. Un maestro y una réplica en el mismo host cuentan como un puesto. Un host que solo ejecuta RCM no ocupa un puesto. Un cuarto host produce el error seats_exceeded.
  • RCM no actualiza fbagent ni Firebird. fbagent los actualiza él mismo y no toca replication.conf, node.json, rcm.json ni los certificados.

Hay dos métodos:

  • Vincular hosts en RCM: el método habitual. Tres acciones: el instalador en cada host (RCM en un host, modo de descubrimiento en los demás), inicio de sesión en RCM, el formulario Vincular hosts.
  • Manualmente desde la línea de comandos: tokens de unión y fbagent --cluster-join. Hace falta cuando el puerto 7450 está cerrado entre hosts o la ventana de emparejamiento ya se ha cerrado.

Licencia. La licencia de prueba incluye la función cluster. Después del periodo de prueba, fbagent no instala un nodo ni RCM si la licencia no tiene cluster. Nunca bloquea las actualizaciones de los nodos y de RCM ya instalados. Sin HQCenter Admin, una licencia flotante deja de funcionar después de online_check_days más los días de gracia. Por eso instale una licencia vinculada en cada fbagent:

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

Sin licencia, el maestro deja de enviar segmentos (capítulo 2.8).

Puertos:

Puerto Dónde Quién se conecta
7443 host de RCM fbagent y nodos de todos los hosts del clúster
7444 host de RCM navegador del operador (consola de RCM, HTTPS)
7450 (en el segundo fbagent y los siguientes del host: 7451…7459) host en modo de descubrimiento, mientras la ventana de emparejamiento está abierta RCM en el host de RCM
7051 (segundo nodo del mismo fbagent: 7061) hosts de los nodos los demás nodos y RCM (1.4, paso 7)

Vincular hosts en RCM

Ejemplo desde cero. Dos servidores Linux, el instalador .run, vinculación, registro, publicación, inicialización y reinicialización bajo carga, con capturas de pantalla y mediciones: la guía hqbird2027-linux-cluster-guide.ru.md y el runbook hqbird2027-linux-cluster-runbook.ru.md (repositorio goafts, carpeta de documentación).

Paso 1. Instalar HQbird en cada host

Instale HQbird con el instalador completo en cada servidor de bases de datos. No se registre en HQCenter Admin (--enroll).

De forma predeterminada el instalador no configura un clúster. Coloca los programas del nodo y de RCM en la carpeta de fbagent (update/<product>/staged/), pero no instala RCM, no abre la ventana de emparejamiento y no abre los puertos del clúster en el cortafuegos. El clúster se activa con dos parámetros:

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: en un host, donde se ejecutará el RCM del clúster. El instalador:

  1. crea el clúster de este host (fbagent --cluster-init); el nombre del clúster es el nombre del host;
  2. instala e inicia RCM; la consola de RCM funciona por HTTPS en el puerto 7444;
  3. crea el primer administrador de RCM rcmadmin con una contraseña aleatoria;
  4. abre los puertos 7443, 7444 y el puerto del nodo 7051 en el cortafuegos.

--cluster-pairing on (modo de descubrimiento): en cada uno de los demás hosts. El instalador abre la ventana de emparejamiento de fbagent durante 24 horas: el puerto 7450 y el puerto del nodo 7051. Mientras la ventana está abierta, un RCM de la red puede invitar a este host a su clúster. fbagent empieza a escuchar en el puerto 7450 en el plazo de un minuto.

Sin estos parámetros el instalador pregunta por sí mismo: en la interfaz de texto es la página Clúster, con --no-tui son dos preguntas. La respuesta predeterminada es «no». --yes sin parámetros de clúster también responde «no» a ambas preguntas.

Al final el instalador imprime las líneas RCM: y Pairing:. En el host de 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

En otro host:

text
RCM:        off; turn it on in HQbird Monitor or with fbagent --cluster-init <id>
Pairing:    port 7450 open until 2026-11-17T17:49:18Z (fingerprint sha256:0439e44a…91a2f9b9); an RCM may invite this host

No hay contraseña en la salida: está en el archivo de la línea Password:. Anote la fingerprint de cada host en modo de descubrimiento.

Parámetros de clúster del instalador de Linux:

Parámetro Qué hace
--rcm on|off instalar RCM y crear un clúster en este host; predeterminado off
--cluster-pairing on|off modo de descubrimiento: abrir la ventana de emparejamiento durante 24 horas; predeterminado off
--pairing-port N puerto de emparejamiento del nuevo fbagent, 7450–7459; predeterminado, el primer libre
--rcm-password-file F contraseña del administrador de RCM tomada de la primera línea del archivo F, en lugar de una aleatoria
--cluster-id ID nombre de clúster ID en lugar del nombre del host (con --rcm on)
--cluster-node on|off instalar el programa del nodo; predeterminado on
--rcm-allow A,B solo estos RCM pueden invitar a este host: dirección, red CIDR o nombre

El primer fbagent de un host recibe el puerto de emparejamiento 7450 y los puertos de nodo 7051 y 7061. La segunda instancia del mismo host: 7451, 7052 y 7062.

RCM y la ventana de emparejamiento pueden activarse más tarde, sin el instalador: en HQ Monitor, la página Clústeres, o con comandos como el usuario de 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

Instaladores antiguos (fbagent anterior a 3.1.0) no preguntan por el clúster: instalan RCM en cada host y abren la ventana de emparejamiento en todas partes. Usted necesita el RCM de un host; los RCM de los demás hosts se detienen solos después de la vinculación.

En Windows. Las mismas dos opciones existen en el instalador de Windows: los parámetros /RCM y /DISCOVERY.

Paso 2. Iniciar sesión en RCM

Abra la dirección de la línea RCM: del host de RCM (https://<host>:7444). Inicie sesión con el usuario rcmadmin y la contraseña del archivo de la línea Password:. RCM pide de inmediato una contraseña nueva (1.5).

Paso 3. Vincular los hosts

En RCM abra Configuración → Vincular hosts.

  1. En el campo Hosts introduzca las direcciones o los nombres de los hosts, uno por línea. La primera línea es el host de RCM; ya está en el clúster.
  2. Pulse Comprobar hosts. RCM sondea los puertos de emparejamiento 7450–7459 de cada host y muestra la plataforma, la versión de Firebird, la huella y el estado. El host de RCM no necesita una ventana de emparejamiento. Compare las huellas con la salida del instalador (la línea Pairing:).
  3. Seleccione el Maestro (de forma predeterminada, el primer host) y pulse Vincular.
Vincular hosts: resultado de la comprobación
Vincular hosts: resultado de la comprobación

RCM pide confirmación y muestra el progreso en la sección Progreso. Cuando todos los nodos están en ejecución, dice «Hecho» y muestra el número de revisión del clúster:

Vincular hosts: todos los nodos en ejecución
Vincular hosts: todos los nodos en ejecución

Lo mismo desde la línea de comandos:

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

Qué ocurre a continuación:

  1. RCM envía una invitación a cada host libre.
  2. El fbagent del host se une al clúster y cierra el puerto de emparejamiento. Si el host tiene su propio RCM sin nodos, fbagent lo detiene y lo desactiva, y traslada su clúster vacío a cluster/left/ en la carpeta de fbagent.
  3. RCM guarda el clúster: el nodo <host>-master en el maestro, <host>-replica en los demás hosts, puerto 7051, enlaces maestro → réplica.
  4. El fbagent de cada host instala e inicia el nodo. RCM espera hasta que todos los nodos estén en ejecución y muestra En ejecución para cada host.

Estados del host después de Comprobar hosts:

Estado Qué hacer
Listo para vincular nada. Si debajo dice «El RCM propio de este host se detendrá después de la vinculación», es normal
En el clúster el host ya está en este clúster
Error unreachable el puerto 7450 está cerrado: la ventana de emparejamiento está apagada (como de forma predeterminada) o han pasado las 24 horas. Justo después de la instalación espere un minuto y pulse Comprobar hosts otra vez. Si no, abra la ventana (--cluster-pairing on) y compruebe el cortafuegos
Error in_other_cluster el host está en otro clúster
Error claimed otro RCM está vinculando este host ahora mismo
Error seats_exceeded más de 3 puestos

Versiones. fbagent instala el nodo solo desde RCM. RCM toma las versiones firmadas de su carpeta import/ (junto a rcm.json) al arrancar y cada 5 minutos. El instalador deja allí las versiones del host de RCM, y los fbagent de los demás hosts descargan ellos mismos la versión de su plataforma. La lista de versiones está al final de la página Vincular hosts. Una versión también puede importarse manualmente (paso 5, más abajo).

Manualmente desde la línea de comandos

Orden: pasos 1–3 en el host de RCM, paso 4 en cada uno de los demás hosts, pasos 5–6 en RCM.

Paso 1. Instalar HQbird con fbagent

Instale HQbird en cada servidor de bases de datos y en el host de RCM con el instalador completo. En el host de RCM puede indicar --rcm on desde el principio (entonces el paso 3 no hace falta). En los demás hosts no indique parámetros de clúster: de forma predeterminada no hay RCM ni ventana de emparejamiento. No se registre en HQCenter Admin (--enroll).

En el host de RCM el instalador deja el programa de RCM en la carpeta de fbagent (update/hqbirdrcm/staged/). Sin él, el paso 3 falla con el error no hqbirdrcm to install.

Paso 2. Instalar la licencia vinculada

Como al principio de la sección, «Licencia».

Paso 3. Crear el clúster en el host de RCM

Si el instalador ya ha creado el clúster (--rcm on: una línea RCM: con una dirección en su salida), omita este paso.

Ejecute el comando como el usuario de fbagent (en Linux, firebird), no como root: de lo contrario los archivos de la CA y rcm.json pertenecerán a root.

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

En Windows (PowerShell como administrador): .\fbagent.exe --cluster-init shop-prod --address 10.0.0.7

  • shop-prod: nombre del clúster: letras latinas minúsculas, dígitos y -.
  • --address: la dirección del host de RCM por la que los demás hosts se conectan a él. Puede repetirse varias veces. Sin el parámetro, se usan las direcciones y el nombre del host.

El comando:

  1. crea la CA del clúster y la CA del agente (en la carpeta de fbagent, clusterca/<name>/);
  2. escribe el certificado de RCM, rcm.json y cluster-init.json en la carpeta de RCM;
  3. instala RCM y registra el servicio hqbirdrcm. En Linux el servicio se ejecuta como un usuario aparte hqbirdrcm;
  4. cambia fbagent a RCM (cluster.source = rcm) y lo reinicia;
  5. imprime la dirección de RCM y la huella de la CA:
Code
Cluster:    shop-prod
RCM URL:    https://10.0.0.7:7443
CA hash:    sha256:9f86d0...

Anote RCM URL y CA hash: hacen falta en los demás hosts. Volver a ejecutarlo para el mismo clúster es seguro: la CA y las claves siguen siendo las mismas.

Inicie sesión en RCM de inmediato y cambie la contraseña de rcmadmin (1.5).

En Linux. El usuario hqbirdrcm está en el grupo de fbagent. RCM lee rcm.json a través de este grupo, pero no puede escribirlo. Por eso Configuración → RCM no guarda los cambios (error rcm_config_read_only). Edite rcm.json en el host como el usuario de fbagent y reinicie RCM.

Paso 4. Conectar los fbagent de los demás hosts

  1. En el host de RCM cree un token de unión para cada fbagent: en RCM Configuración → Clúster, el botón Crear token de unión. O desde la línea de comandos:

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

    El token es válido durante 24 horas, para un solo fbagent y una sola vez. RCM lo muestra una vez, junto con un comando ya preparado.

  2. En el host del nodo ejecute este comando como el usuario de 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

    En lugar de --token-file puede usar --token <token>. En Windows, lo mismo con .\fbagent.exe en PowerShell como administrador.

fbagent comprueba la CA de RCM por la huella. Si la huella no coincide, se detiene y no escribe nada. Después fbagent recibe su certificado (90 días, se renueva automáticamente) y se reinicia. Un fbagent conectado se ve en RCM en la tabla Agentes. Mientras no tiene miembros, no se instala nada en el host.

Paso 5. Importar versiones en RCM

fbagent toma el nodo y RCM solo desde RCM. Si la versión necesaria no está en la lista Versiones en el espejo (Configuración → Vincular hosts), importe cada producto (hqclusternode, hqbirdrcm) para cada plataforma de sus hosts (linux-amd64, windows-amd64). El archivo de la versión y la firma .sig los facilita el proveedor.

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 busca la firma en <file>.sig, o indíquela con -sig. Sin una firma válida del proveedor, RCM no aceptará el archivo.
  • Una versión nueva sustituye a la anterior. No hace falta reiniciar RCM.
  • fbagent comprueba si hay versiones nuevas cada 3 minutos. El orden de actualización y el bloqueo son como mediante HQCenter Admin (1.2, «Actualizaciones»).

Paso 6. Describir el clúster

Defina los miembros y los enlaces en RCM, Configuración → Clúster (capítulo 2.3). Después de guardar, fbagent instala los nodos del mismo modo que mediante HQCenter Admin (1.2, paso 3): escribe certificados, node.json y rcm.json, instala e inicia los servicios.

Los puertos están al principio de la sección.

1.4. Instalación manual

Paso 1. Instalar HQbird con fbagent

Instale HQbird en cada servidor de bases de datos (con el mismo script, pero sin --enroll, o con el instalador completo de HQbird). Compruebe que fbagent está en ejecución.

Anote tres valores del agent_config.json de fbagent. Hacen falta para node.json:

Campo de fbagent Campo de node.json Ejemplo
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 —

Comprobación de fbagent (la respuesta es el JSON de la instancia de Firebird):

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

Si el host tiene varias instancias de HQbird, deje solo el servicio de su instancia en firebird.update.services de la configuración de fbagent (véase 3.5).

Paso 2. Colocar los archivos

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

En Windows. La carpeta predeterminada es C:\hqclusternode con la misma disposición. Se permite una ruta que contenga un espacio.

Si un host tiene dos nodos (maestro y réplica), dé a cada uno su propia carpeta, por ejemplo /opt/hqclusternode/master y /opt/hqclusternode/replica.

Paso 3. Crear los certificados

Los nodos y RCM se comunican solo por mTLS. Hace falta una CA y un certificado para cada participante. Ejecute esto una vez en cualquier máquina:

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

El comando crea ca.crt y ca.key, node-a.crt/.key, node-b.crt/.key y rcm.crt/.key. En -hosts, indique todos los nombres y direcciones por los que se conectará a los participantes.

gencerts y los archivos que creó
gencerts y los archivos que creó

ca.key es la clave de la CA. No la copie a los hosts; guárdela aparte.

Un nodo nuevo se añade más tarde con -add: firma el par con la misma CA y deja los demás archivos sin cambios:

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

Los certificados son válidos durante 90 días. gencerts -out certs -list muestra las fechas de caducidad, y gencerts -out certs -renew los renueva con la misma clave. Copie el .crt nuevo a su host: el nodo lo tomará sin reinicio.

Copie ca.crt y solo su propio certificado y clave a cada host.

Paso 4. Escribir node.json

Un archivo por nodo. Ejemplo para el maestro (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" } ]
}

El nodo réplica (node-b) tiene el mismo archivo, pero con "role": "replica", sus propios certificados y el maestro node-a en peers.

Campos principales:

Campo Valor
node_id nombre del nodo; el mismo en el certificado, en rcm.json y en los peers de los demás nodos
role master o replica
listen_addr dirección de la API del nodo; un segundo nodo en el mismo host usa otro puerto (:7052)
rcm.url dirección para recibir las estadísticas de RCM; none: sin RCM
firebird.* el Firebird y el fbagent de esta instancia; los valores de fbagent deben coincidir exactamente
firebird.auto_restart si el nodo réplica puede reiniciar Firebird por sí mismo: auto (predeterminado), never, always
windows.restart_window ventana de reinicio de Firebird; para el maestro el valor predeterminado es 22:00-05:00, para la réplica es siempre
windows.transfer_window ventana en la que la inicialización va a plena velocidad
peers para el maestro, sus réplicas; para la réplica, su maestro
databases carpeta de las bases de datos; es mejor no escribirla a mano, sino definirla mediante RCM (capítulo 3)

Los demás campos tienen valores predeterminados. El nodo no arrancará si los campos de fbagent no están definidos.

Proteja el archivo: contiene la contraseña y el token.

Command
chmod 600 /opt/hqclusternode/node.json

En Windows. Escriba las rutas en formato JSON: "C:\\HQbird\\replication.conf". service_name es el nombre del servicio de Windows de Firebird.

Paso 5. Escribir 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: dirección del nodo tal como la ve el host de RCM. Solo https.
  • host: etiqueta de la instancia de Firebird. Un nodo maestro y un nodo réplica con la misma etiqueta se ejecutan en el mismo Firebird (compañero, necesario para promover una réplica a maestro, capítulo 8). Una etiqueta: no más de un maestro y una réplica.
  • Las rutas relativas se resuelven desde la carpeta de rcm.json.

Paso 6. Registrar los servicios

Orden de arranque: primero RCM, después las réplicas y después el maestro.

RCM (Linux):

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

Nodo (Linux):

Command
cd /opt/hqclusternode
sudo ./hqclusternode svc install -config /opt/hqclusternode/node.json -certs /opt/hqclusternode/certs
sudo ./hqclusternode svc start -config /opt/hqclusternode/node.json
systemctl status hqclusternode-master-p3050

svc install crea el servicio hqclusternode-<role>-p<port>, que se ejecuta como el usuario firebird. Si la carpeta de Firebird pertenece a root, el comando concede al grupo firebird acceso de escritura (con el bit sticky) e imprime cada cambio: el nodo necesita sustituir replication.conf.

Para svc start, svc stop y svc uninstall, indique el mismo node.json: el nombre del servicio se obtiene del rol y del puerto de Firebird.

En Windows (PowerShell como administrador):

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

El servicio HQClusterNode-<role>-p<port> se ejecuta como LocalSystem, arranca automáticamente y se reinicia tras un fallo. El servicio del nodo no depende del servicio de Firebird. Si el nodo se instaló con la versión 2027.1.2–2027.1.9, quite la dependencia una vez: .\hqclusternode.exe svc fix-deps -config C:\hqclusternode\node.json.

svc install y svc start en Windows
svc install y svc start en Windows

Paso 7. Abrir los puertos

En el host del nodo, permita las conexiones entrantes en 7051 (el puerto de listen_addr) desde los demás nodos y desde RCM. En el host de RCM, permita las conexiones entrantes en 7443 desde todos los nodos. No exponga al exterior los puertos 7444 y 13050.

Ejemplo de ufw en el host del nodo:

Command
sudo ufw allow from <ip-rcm> to any port 7051 proto tcp
sudo ufw allow from <ip-partner-node> to any port 7051 proto tcp

Actualización manual

Detenga el servicio, sustituya el programa e inicie el servicio:

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

La configuración y los certificados no cambian con esto.

1.5. Primer inicio de sesión en RCM

La dirección y la contraseña dependen de cómo se instaló RCM.

Cómo se instaló RCM Dirección Usuario y contraseña
Por el instalador de HQbird o fbagent --cluster-init (1.3) https://<host de RCM>:7444 desde cualquier ordenador rcmadmin y la contraseña impresa por el instalador (o la suya, de --rcm-password-file)
Mediante HQCenter Admin (1.2) o manualmente (1.4) http://127.0.0.1:7444, solo en el host de RCM rcmadmin, contraseña strong password (con un espacio)

HTTPS (1.3). El certificado de RCM está firmado por la CA del clúster, que el navegador no conoce, así que le avisa. En la página de inicio de sesión RCM muestra la huella de la CA. Compárela con el CA hash impreso por el instalador, e importe la CA en el navegador o en el sistema como raíz de confianza: el enlace Descargar el certificado de la CA en la página de inicio de sesión (https://<host de RCM>:7444/ca.crt, archivo hqcluster-ca.crt). Para que RCM escuche solo en localhost, ponga "operator_addr": "127.0.0.1:7444" en rcm.json y reinicie RCM.

HTTP (1.2, 1.4). Desde otro ordenador, conéctese mediante un túnel SSH:

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

Después abra http://127.0.0.1:7444 en el navegador.

Página de inicio de sesión de RCM
Página de inicio de sesión de RCM

Contraseña generada. RCM le pide que la cambie en el primer inicio de sesión: hasta que la cambie, las demás páginas no se abrirán. Cambie strong password de inmediato (el enlace Contraseña en la cabecera).

Cambio de la contraseña en el primer inicio de sesión
Cambio de la contraseña en el primer inicio de sesión

Idioma. Seleccione Ruso en la lista de idiomas de la cabecera de la página (también está disponible en la página de inicio de sesión). Si no selecciona uno, el idioma se toma del navegador.

Cambio de contraseñas y usuarios nuevos

Cada usuario cambia su propia contraseña: el enlace Contraseña en la cabecera de la página. Hace falta la contraseña actual y una nueva de al menos 12 caracteres. Después del cambio, se cierran las demás sesiones de ese usuario.

Si el instalador generó una contraseña, se escribe en el archivo clusterca/<name>/rcm-initial-password de la carpeta de fbagent. Después de cambiar la contraseña, fbagent borra este archivo él mismo. No borre el archivo initial-admin.json de la carpeta de RCM: solo contiene un hash. Si se pierde el archivo de usuarios y este archivo no está, RCM creará un usuario con la contraseña predeterminada.

Usuarios nuevos. No hay una página de usuarios en la interfaz. Los usuarios se guardan en el archivo rcm-data/users.json. La contraseña se guarda como un hash HA1: MD5("<name>:hqbirdrcm:<password>").

  1. Calcule el hash:

    Command
    printf '%s' 'rcmadmin:hqbirdrcm:<new password>' | md5sum
  2. Escríbalo en el campo ha1 del usuario en users.json. Para añadir un usuario, añada otro elemento a users:

    json
    { "username": "ivanov", "ha1": "<hash>", "algo": "MD5", "created_at": "2026-11-03T00:00:00Z" }
  3. Reinicie RCM de inmediato: lee el archivo solo al arrancar. Cuando se cambia una contraseña en la interfaz, RCM reescribe el archivo desde la memoria, y se perderán las ediciones que aún no haya leído.

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

Sin un campo role, un usuario tiene todos los permisos. Desde HQbird 2027.2.31 existe el rol "role": "viewer": solo lectura; cualquier solicitud de modificación recibe 403.

1.6. Cómo comprobar la instalación

  • Los servicios del nodo y de RCM están en ejecución y no se reinician en bucle: systemctl status hqclusternode-master-p3050, systemctl status hqbirdrcm.

    systemctl status del nodo
    systemctl status del nodo
systemctl status de RCM
systemctl status de RCM
  • RCM responde (sin contraseña): curl http://127.0.0.1:7444/healthz. Cuando se instaló mediante RCM (1.3), la consola funciona por HTTPS: curl -k https://127.0.0.1:7444/healthz.

  • En RCM, la página Resumen muestra todos los nodos, sin la marca «no responde».

  • Desde la línea de comandos en el host de RCM:

    Command
    export RCM_USER=rcmadmin RCM_PASSWORD='<password>'
    ./hqbirdrcm nodes
    ./hqbirdrcm status
  • El clúster mediante RCM: Configuración → Clúster, la sección Estado: cada miembro ha aplicado la última revisión y no informa de ningún error. Desde la línea de comandos: ./hqbirdrcm cluster status.

1.7. Registros

Qué Dónde
Registro del nodo <carpeta de node.json>/logs/node-YYYYMMDD.jsonl
Salida del servicio del nodo (Linux) journalctl -u hqclusternode-<role>-p<port>
Salida del servicio de RCM (Linux) journalctl -u hqbirdrcm
Registro de replicación de Firebird firebird.replication_log de node.json
Registros de cualquier nodo sin SSH RCM, página Registros

1.8. Errores frecuentes

Qué ve Causa Qué hacer
El nodo no arranca: un error sobre fbagent_url, fbagent_token o instance_id fbagent no está en ejecución o los valores no coinciden con agent_config.json compruebe fbagent con el comando curl del 1.4, paso 1
El script de instalación terminó con el código 2 la solicitud de fbagent no se aprobó a tiempo apruebe la solicitud y vuelva a ejecutar el script
Los nodos no aparecen mediante HQCenter Admin fbagent no está en el clúster, o el clúster aún no se ha obtenido compruebe el clúster (capítulo 2), espere hasta 10 minutos
El nodo en RCM está «sin respuesta» el puerto 7051 está cerrado, el url de rcm.json es incorrecto, la dirección no está en el certificado compruebe los puertos y el -hosts de los certificados
No hay inicio de sesión en RCM: «Demasiados intentos de inicio de sesión fallidos» 10 inicios de sesión fallidos en 5 minutos espere unos minutos
La versión nueva no se instala la versión está en blocked-versions.json quite la línea de la versión del archivo
--cluster-init: no hqbirdrcm to install el instalador no dejó el programa de RCM instale HQbird con el instalador completo (1.3, «Manualmente», paso 1)
--cluster-join: token_used, token_expired, token_revoked el token ya se ha usado, tiene más de 24 horas o se ha revocado cree un token nuevo (1.3, «Manualmente», paso 4)
--cluster-join: hostname_conflict el clúster tiene un fbagent con el mismo nombre de host y direcciones distintas dé nombres distintos a los hosts
--cluster-join: this agent is in cluster … from goafts fbagent ya está en el clúster de HQCenter Admin quítelo del clúster de HQCenter Admin
El nodo no se instala mediante RCM RCM no tiene una versión para esta plataforma hqbirdrcm release list, importe la versión (1.3, «Manualmente», paso 5)

2. Configuración del clúster

En este capítulo define qué nodos hay en el clúster y qué maestro envía segmentos a qué réplica. Después configura los nodos y los usuarios de RCM.

Las relaciones se definen de una de estas tres formas:

Nodos instalados Dónde se definen las relaciones Sección
mediante HQCenter Admin en HQCenter Admin: la página Clústeres de HQ Monitor o la API de HQCenter Admin 2.2
mediante RCM, sin HQCenter Admin en RCM: Configuración → Clúster, hqbirdrcm cluster o la página Clústeres de HQ Monitor 2.3
manualmente en RCM: Configuración → RCM y Configuración → Nodos 2.3

En los nodos instalados mediante HQCenter Admin o mediante RCM, cambie las relaciones solo en la descripción del clúster. fbagent sobrescribe node.json y rcm.json según la descripción del clúster. Editar las relaciones en Configuración → RCM o Configuración → Nodos de RCM se rechaza (409 cluster_managed). Las versiones anteriores de RCM lo aceptaban, pero se perdía.

2.1. Roles y esquemas

Cada nodo tiene un rol: maestro o réplica. En una sola instancia de Firebird pueden ejecutarse dos nodos, un maestro y una réplica.

Esquemas compatibles:

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

El enlace va siempre del maestro a la réplica. RCM vincula la base de datos del maestro con su réplica por el GUID de la base de datos, no por el nombre del nodo.

Compañero. Un nodo maestro y un nodo réplica en la misma instancia de Firebird son compañeros. La promoción de una réplica a maestro (capítulo 8) solo funciona para ese par. En rcm.json el par se marca con un valor host idéntico.

2.2. Enlaces mediante HQCenter Admin

Dónde describir un clúster

  • HQ Monitor, página Clústeres (solo administradores; la entrega de la configuración debe estar activada). La forma habitual.
  • API de HQCenter Admin: POST /v1/admin/clusters y PUT /v1/admin/clusters/{id}. El panel de HQCenter Admin no tiene página de clústeres.

``

Pasos en la página Clústeres

  1. Introduzca un Id del nuevo clúster (letras latinas minúsculas, dígitos y -) y pulse Crear.
  2. Añada miembros (Miembros). Para cada uno indique:
    • el fbagent del host;
    • el rol: master, replica o rcm;
    • las direcciones del host;
    • el puerto: para un nodo, 7051 (un segundo nodo en el mismo host, por ejemplo 7052); para RCM, el puerto de entrada de estadísticas 7443.
  3. Añada enlaces (Enlaces de replicación) del maestro a la réplica.
  4. Pulse Validar y después Guardar.

Si otro administrador cambió el clúster al mismo tiempo, la página le pedirá que vuelva a cargar el clúster y repita el cambio.

Reglas

  • Un fbagent solo puede pertenecer a un clúster.
  • En un mismo fbagent, no más de un maestro, una réplica, un RCM y un enrutador. El enrutador (rol router, a partir de HQbird 2027.2.30) no tiene enlaces y no ocupa un puesto de licencia (capítulo 8.7).
  • Un clúster tiene exactamente un RCM. El fbagent del host de RCM ejecuta la autoridad de certificación (CA) del clúster.
  • El nombre del miembro (member_id): letras latinas, dígitos, -. El nombre, el fbagent y el rol de un miembro no se pueden cambiar. Para mover un miembro a otro host, cree un miembro nuevo con un nombre nuevo. No vuelva a usar el nombre antiguo.
  • Cada réplica debe tener un enlace con el maestro.
  • HQCenter Admin construye él mismo la dirección del nodo: https://<primera dirección>:<port>.
  • HQbird 2.5/3.0: defina la fecha replconf_valid_till del clúster (YYYY-MM-DD): la configuración del complemento replconf es válida hasta esa fecha.

Ejemplo mediante la 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"}]}
  • Crear: POST /v1/admin/clusters (el documento puede enviarse junto con los miembros). Sustituir el documento entero: PUT /v1/admin/clusters/{id}.
  • PUT exige la cabecera If-Match: <revision> (la revisión la proporcionan GET y ETag). Sin la cabecera, 428; con una revisión antigua, 409; con un error en el documento, 422 con una lista de errores.
  • POST /v1/admin/clusters/{id}/validate valida el documento sin guardarlo.
  • GET /v1/admin/clusters/{id}/status muestra el estado de los miembros y las fechas de caducidad de los certificados.

Qué ocurre después de guardar

  1. El fbagent de cada miembro recibe el clúster. Dentro del clúster, una comprobación cada 60 segundos (el fbagent del host de RCM, cada 30 segundos). Fuera de un clúster, un fbagent se entera del clúster en su siguiente sondeo de configuración. Si ese sondeo no llega al servidor, la comprobación se ejecuta cada 10 minutos.
  2. Cada fbagent crea una clave y envía una solicitud de certificado. El fbagent del host de RCM la firma. RCM firma su propio certificado sin solicitud.
  3. fbagent escribe en node.json: nombre, rol, dirección, peers (a partir de los enlaces), la dirección de RCM, las rutas de los certificados, los datos de Firebird y de fbagent. En rcm.json: la lista de nodos (nodes), la lista de enrutadores (routers), la dirección de entrada de estadísticas y las rutas de los certificados. fbagent no toca los demás campos de los archivos.
  4. fbagent instala e inicia los servicios (capítulo 1).

Cambio de un clúster:

Qué cambió Qué hace fbagent
solo los peers de un nodo en ejecución se los pasa al nodo sin reinicio
otros campos de un nodo detiene el nodo, escribe el archivo, inicia el nodo, dentro de windows.transfer_window del nodo (si no está definida, de inmediato)
rcm.json reinicia RCM de inmediato
certificados o CA reinicia el servicio
se elimina un miembro detiene y elimina el servicio; cluster-managed.json → cluster-removed.json, el programa → *.removed; la configuración, los certificados y los datos permanecen

Después de eliminar un nodo, su sección # BEGIN managed-by:<name> … # END … permanece en el replication.conf compartido. Bórrela a mano y reinicie Firebird mediante RCM.

Aprobación de los certificados del clúster

De forma predeterminada, el fbagent del host de RCM firma las solicitudes él mismo (auto). Se puede activar la aprobación manual. Comandos en el host de 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 el modo manual, un miembro nuevo o una clave nueva esperan la aprobación. La renovación de un certificado con una clave conocida se firma automáticamente.

2.3. Enlaces mediante RCM

Clúster de RCM (sin HQCenter Admin)

Si el clúster lo creó el instalador de HQbird o el comando fbagent --cluster-init (capítulo 1.3), la descripción del clúster la guarda RCM. La forma más fácil de añadir hosts es la página Configuración → Vincular hosts (capítulo 1.3, «Vincular hosts en RCM»): RCM crea los miembros y los enlaces él mismo. Las reglas son las mismas que en HQCenter Admin (2.2, «Reglas»), y además:

  • en RCM hay un clúster; el miembro rcm existe siempre y no se puede borrar;
  • no más de 3 puestos (hosts con nodos maestro o réplica); si no, se produce el error seats_exceeded;
  • un miembro solo se puede añadir en un fbagent que se haya conectado a RCM (capítulo 1.3: «Vincular hosts» o «Manualmente», paso 4).

Pasos en la página Configuración → Clúster:

  1. En la tabla Agentes, pulse Añadir miembro en la fila del fbagent.
  2. Indique el rol (master, replica o router), member_id, las direcciones y el puerto. La página sugiere el nombre <host>-<role> y el puerto: 7051 para el primer nodo del fbagent, 7061 para el segundo. RCM rechaza un puerto que ya esté ocupado por otro miembro del host. Las direcciones del fbagent son botones: pulse para añadir una dirección.
  3. En la sección Enlaces, pulse Añadir enlace del maestro a la réplica.
  4. Pulse Validar: RCM mostrará errores y advertencias.
  5. Pulse Guardar. La página mostrará la lista de cambios y pedirá confirmación. Si se van a borrar miembros, la ventana es roja.

Antes de guardar, los cambios existen solo en la página (la etiqueta «No guardado»). Si alguien guardó el clúster al mismo tiempo, la página ofrecerá volver a cargarlo. Si solo cambiaron campos de RCM (revisión, CA, encargos), la página guardará el cambio por sí misma.

Otras secciones de la página:

Sección Qué hay
cabecera nombre del clúster, revisión, CA del clúster y CA del agente; el botón Exportar de la CA antigua
Tokens de conexión crear un token para un fbagent nuevo, revocar uno no usado
Documento JSON el documento entero en un campo de texto; Validar y Guardar lo usan
Claves y CA encargos: clave nueva de un miembro (rekey), CA nueva del clúster (rotate_ca), CA nueva del agente (rotate_agent_ca); no disponibles cuando hay cambios sin guardar
Estado la revisión que ha aplicado cada miembro, la caducidad del certificado, el servicio, el último error

Desde la línea de comandos en el host de 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

El formato del documento es el de 2.2, «Ejemplo mediante la API». apply con una revisión antigua obtiene 409: vuelva a ejecutar show. RCM conserva las últimas 20 revisiones en rcm-data/cluster/history/.

HQ Monitor. La página Clústeres también funciona con RCM. En el host de RCM, HQ Monitor accede a RCM a través del fbagent de ese host, con el certificado de fbagent: no hacen falta el usuario ni la contraseña de RCM. En el registro de auditoría de RCM esas acciones se anotan como agent:<id> (<user>). Otra forma, para versiones anteriores de RCM: en la configuración de HQ Monitor defina rcm_admin_url (http://127.0.0.1:7444), rcm_admin_user (el usuario de RCM) y rcm_admin_password_file (un archivo con su contraseña).

Después de guardar, todo sigue como mediante HQCenter Admin (2.2, «Qué ocurre después de guardar»). RCM vuelve a leer nodes en rcm.json él mismo, sin reinicio.

Quitar un fbagent del clúster: borre sus miembros y guarde, después pulse Revocar en la tabla Agentes (o ./hqbirdrcm cluster revoke -agent <id>). Para volver a incorporarlo hace falta un token nuevo. Después de la revocación, el fbagent (desde la versión 3.1.0) abandona el clúster él mismo: detiene sus nodos y borra los datos del clúster. Lo mismo se hace en un host de nodo con el comando fbagent --cluster-leave. En el host de RCM se rechaza.

Instalación manual: añadir un nodo a RCM

  1. Configuración → RCM, la tabla Nodos conectados.
  2. Pulse Añadir nodo. Rellene node_id, url (https://<dirección>:7051), el rol, host (etiqueta de la instancia de Firebird), server (solo para la agrupación en pantalla).
  3. Pulse Validar en la fila del nodo: RCM comprobará la conexión y los permisos.
  4. Pulse Guardar. RCM escribirá rcm.json y guardará el archivo antiguo como rcm.json.<hora UTC>.bak (los últimos 20).
  5. Reinicie RCM. Hasta el reinicio sigue vigente la configuración antigua; la página muestra qué campos esperan un reinicio.
Configuración → RCM
Configuración → RCM
Command
sudo systemctl restart hqbirdrcm

También puede hacerlo sin la interfaz: edite rcm.json y reinicie RCM.

Instalación manual: enlazar maestro y réplica

El enlace debe quedar registrado en ambos lados:

  1. Configuración → Nodos, seleccione el nodo maestro.
  2. En la sección Pares, pulse Añadir par: el node_id de la réplica, su url, la compresión (zstd).
  3. Pulse Guardar. RCM mostrará la lista de cambios y pedirá confirmación. El cambio de peers surte efecto de inmediato.
  4. Repita para el nodo réplica: su par es el maestro.
Sección Pares del nodo maestro
Sección Pares del nodo maestro

Si el par no está registrado en uno de los lados, RCM no ofrecerá ese nodo réplica al inicializar la base de datos.

2.4. Ajustes del nodo

Configuración → Nodos muestra los ajustes de node.json que el nodo permite cambiar desde RCM. Solo se guardan los campos cambiados, después de una ventana que enumera los cambios.

Configuración → Nodos: selección de un nodo
Configuración → Nodos: selección de un nodo
Ajustes de bases de datos del nodo con marcas «después del análisis»
Ajustes de bases de datos del nodo con marcas «después del análisis»

Cada fila indica cuándo surtirá efecto el cambio:

Cuándo Qué ajustes
De inmediato channel_a_mbps, channel_a_burst_mbps, windows.restart_window, peers; desde HQbird 2027.2.24, ajustes de la comprobación de datos (limits.data_check_*); desde HQbird 2027.2.31, advertise_addr
Tras el reinicio del nodo los demás límites, windows.transfer_window; la página los muestra en una línea aparte hasta que se reinicia el nodo
Tras el análisis databases.*, exclude_filter; si replication.conf ha cambiado, hace falta reiniciar Firebird (capítulo 3.5)

Solo lectura (se cambian en node.json en el host del nodo): firebird (incluida la contraseña y auto_restart), rcm, tls, segments, la dirección listen_addr.

Ajustes principales:

Ajuste Predeterminado Significado
windows.restart_window maestro 22:00-05:00, réplica: siempre cuándo puede el nodo reiniciar Firebird; el Firebird maestro nunca se reinicia solo
windows.transfer_window 23:00-05:00 ventana en la que la inicialización va a la velocidad reinit_window_mbps
limits.channel_a_mbps 50 velocidad de transferencia de segmentos, MB/s (channel_a_burst_mbps: pico breve, 200)
limits.reinit_window_mbps 100 velocidad de inicialización dentro de la ventana de transferencia, MB/s
limits.reinit_day_disk_fraction 0.5 fracción de la velocidad de disco medida para la inicialización fuera de la ventana
limits.retention_days 2 cuántos días conservar los segmentos enviados en el archivo del maestro
limits.free_space_floor_gb 1 espacio libre mínimo, GB; por debajo, la réplica no acepta segmentos
limits.max_concurrent_reinits 1 cuántas inicializaciones ejecuta el nodo a la vez

Los detalles de velocidad y de retención del archivo están en los capítulos 5 y 7.

firebird.auto_restart (solo en node.json) determina si un nodo réplica puede reiniciar Firebird por sí mismo:

Valor Comportamiento
auto (predeterminado) puede, si este Firebird no sirve bases de datos maestras
never nunca
always siempre, incluso si este Firebird aloja bases de datos maestras

Mediante HQCenter Admin. El windows.transfer_window del nodo de fbagent también se usa como ventana para reiniciar el propio servicio del nodo cuando cambia el clúster. Si la ventana no está definida en node.json, fbagent reinicia el servicio de inmediato.

2.5. Varias instancias de HQbird en un host

fbagent reinicia los servicios enumerados en firebird.update.services de su configuración. Una lista vacía significa todos los servicios de HQbird del host. Deje en la lista solo el servicio de su propia instancia. El nodo no ve este ajuste y escribe una advertencia fbagent_shared en el registro si fbagent conoce más de una instancia.

2.6. Contraseña de SYSDBA

El nodo se conecta a Firebird con el usuario y la contraseña de firebird.user y firebird.password en node.json. fbagent guarda su propia copia de la contraseña. Si ha cambiado la contraseña de SYSDBA:

  1. Corrija firebird.password en el node.json de cada nodo de esta instancia (maestro y réplica).
  2. Corrija la contraseña en la configuración de fbagent y vuelva a cargarla (véase la documentación de fbagent).
  3. Reinicie los servicios del nodo.

Si no, las páginas de publicación y de comprobación de RCM mostrarán un error de inicio de sesión (SQLSTATE 28000).

2.7. Usuarios de RCM y auditoría

  • Los usuarios están en el archivo rcm-data/users.json (capítulo 1.5). Sin rol, un usuario tiene todos los derechos; el rol viewer (desde HQbird 2027.2.31) es solo lectura.
  • Una sesión dura 12 horas después de la última acción.
  • Después de 10 inicios de sesión fallidos en 5 minutos, el inicio de sesión de ese usuario y esa dirección se bloquea temporalmente. Un inicio de sesión correcto pone el contador a cero.
  • El registro de auditoría es el archivo rcm-data/audit.jsonl: una línea JSON por cada cambio, inicio de sesión y cierre de sesión. No hay registro de auditoría en la interfaz.
  • La página Comandos muestra el autor de cada comando.

2.8. Licencia

Una vez por minuto, el nodo maestro lee la licencia de fbagent de su host. Si no hay licencia (ha terminado el periodo de prueba, la licencia ha caducado o no es válida), el nodo deja de enviar segmentos de todas las bases de datos del maestro. Firebird y las bases de datos siguen en funcionamiento, pero las réplicas dejan de recibir cambios.

Qué ve en RCM:

  • el maestro está en rojo (NEEDS_ATTENTION), con la insignia «sin licencia: envío detenido»;
  • no hay botón Reanudar: solo la licencia quita la pausa;
  • en la réplica: «no recibe desde …: el maestro no tiene licencia»;
  • en la tabla Nodos, una insignia «sin licencia»; en Configuración → Nodos, el bloque de la licencia de fbagent;
  • las alertas license_paused y license_pause_archive_released;
  • la inicialización está prohibida (license_paused).
Bloque de la licencia de fbagent en Configuración → Nodos
Bloque de la licencia de fbagent en Configuración → Nodos

Instale la licencia en fbagent. El nodo quita la pausa por sí mismo en el plazo de un minuto. El maestro conserva el archivo para las réplicas durante limits.retention_days (2 días de forma predeterminada) desde el inicio de la pausa. Si instala la licencia más tarde, habrá que inicializar de nuevo las réplicas.

Clúster mediante RCM, sin HQCenter Admin. Una licencia flotante sin HQCenter Admin deja de funcionar después de online_check_days más los días de gracia. Cada fbagent del clúster necesita una licencia vinculada (fbagent --license-request, después fbagent --license-install, capítulo 1.3, «Licencia»). Después del periodo de prueba, fbagent no añadirá un nodo nuevo ni RCM sin la función cluster en la licencia; nunca prohíbe las actualizaciones. Para HQbird 2.5/3.0, la fecha replconf_valid_till de RCM no puede ser posterior al fin de la licencia más los días de gracia en los nodos de fbagent (error replconf_after_license).

2.9. Cómo comprobar

  • Resumen: todos los nodos están presentes y agrupados por servidor.

    Resumen del clúster
    Resumen del clúster
  • Configuración → Nodos: el maestro tiene una réplica en Pares, y la réplica tiene el maestro.

  • Configuración → RCM: el botón Comprobar de la fila de cada nodo pasa.

  • Informe del clúster en un solo archivo:

    Command
    ./hqbirdrcm report -o report.json

2.10 Errores frecuentes

Qué ve Causa Qué hacer
La edición de los pares en RCM se rechaza (409 cluster_managed) o se pierde después de reiniciar el nodo el nodo se instaló mediante HQCenter Admin o mediante RCM cambie los enlaces en la descripción del clúster (2.2, 2.3)
seats_exceeded al guardar el clúster en RCM nodos en un cuarto host no más de 3 hosts con nodos
Configuración → RCM: rcm_config_read_only clúster mediante RCM en Linux: rcm.json pertenece a fbagent edite rcm.json como el usuario de fbagent y reinicie RCM
Revocar el agente no funciona (agent_has_members) fbagent tiene miembros primero borre los miembros y guarde
El nodo réplica no se ofrece durante la inicialización el par no está registrado en uno de los lados añada el par en ambos lados (2.3)
Un cambio en Configuración → RCM no surte efecto RCM no se ha reiniciado reinicie RCM
422 al guardar el clúster en HQCenter Admin un error en el documento corríjalo según la lista errors, compruebe mediante validate
409 al guardar el clúster otra persona cambió el clúster vuelva a leer el clúster e inténtelo de nuevo
Un miembro nuevo del clúster de HQCenter Admin no recibe un certificado aprobación manual en el host de RCM fbagent --cluster-ca-approve <id>
Error SQLSTATE 28000 en las páginas de publicación se cambió la contraseña de SYSDBA 2.6

3. Añadir una base de datos al maestro

En este capítulo la base de datos maestra pasa bajo el control del nodo. El nodo la anota en replication.conf y crea las carpetas de los segmentos. Después de reiniciar Firebird la base de datos está lista para la replicación.

Crear la réplica son los pasos siguientes (publicación, inicialización). Se describen en los capítulos 4–6.

Los nombres de los botones se dan según la interfaz rusa de RCM, con los ingleses entre paréntesis.

3.1. Cómo descubre las bases de datos un nodo

El nodo maestro busca las bases de datos en una sola carpeta, la raíz de bases de datos (databases.root). Lo que pasa a estar gestionado lo deciden unas reglas:

Regla Campo Predeterminado
Carpeta de bases de datos root no definida
Buscar en subcarpetas recursive sí
Máscara de inclusión template *.fdb
Máscara de exclusión exclude_mask ninguna
Tamaño del archivo, MB min_size_mb, max_size_mb sin límites (0)
Tablas para la comparación de datos sync_tables con HQbird 2027.2.24, tablas de la publicación de la base de datos; si no hay, RDB$FIELDS; en 2027.5.7, RDB$FIELDS
Lista de inclusión include_paths vacía (modo de plantilla)
Lista de exclusión exclude_paths vacía

La ruta root es una ruta en el host del nodo, no en el host de RCM. El nodo aplica primero la máscara de inclusión, después la de exclusión y después el tamaño.

Las reglas son las mismas para todo el nodo. La lista sync_tables también es compartida: la comprobación (capítulo 5.10) busca cada tabla de la lista en cada base de datos del nodo que no tiene su propia lista.

Tablas para la comparación, con HQbird 2027.2.24. Cada base de datos puede tener su propia lista (Tablas de seguimiento de la sincronización). El nodo la guarda en databases.sync_tables_by_db. La comprobación toma la primera lista que esté definida:

  1. la lista propia de la base de datos;
  2. la lista compartida sync_tables del nodo;
  3. las tablas de la publicación de la base de datos;
  4. RDB$FIELDS.

Una lista compartida guardada antes tiene prioridad sobre la publicación: una base de datos sin lista propia la usa. La página de la base de datos del maestro muestra qué lista está en vigor (3.3).

Una tabla ausente tanto en la base de datos primaria como en la réplica recibe el estado «no está en la base de datos» (absent): no se compara, y la comprobación no mostrará «No correcto» por ella. Una tabla que falta solo en un lado es una discrepancia.

RCM y nodo 2027.5.7. Hay una sola lista para todo el nodo (sync_tables); sin lista, la comprobación usa RDB$FIELDS. Una tabla ausente es un error, y la comprobación de la base de datos mostrará «No correcto».

Todas las reglas se guardan en el node.json del nodo. El nodo las aplica en cada análisis.

Modo de plantilla y modo de lista:

  • Modo de plantilla (lista de inclusión vacía): el nodo toma todos los archivos que coinciden con la máscara, excepto los excluidos. El nodo recogerá un archivo nuevo de la carpeta automáticamente en el siguiente análisis.
  • Modo de lista (lista de inclusión no vacía): el nodo toma solo los archivos de la lista. Un archivo nuevo no pasará a estar gestionado automáticamente: hay que añadirlo.

Elija el modo de lista si la carpeta contiene copias de bases de datos, bases de datos de prueba u otros archivos que no hay que replicar.

3.2. Antes de empezar: comprobar los permisos

El usuario con el que se ejecutan Firebird y el nodo (firebird en Linux, LocalSystem en Windows) debe tener permisos de lectura y escritura sobre:

  • la carpeta raíz de las bases de datos y los archivos de las bases de datos;
  • replication.conf y su carpeta (el nodo sustituye el archivo mediante un archivo temporal);
  • las carpetas de segmentos <database>.ReplLog y <database>.LogArch (el nodo las crea él mismo).

RCM comprueba los permisos antes del registro (preflight). Si la comprobación falla, el comando termina con el error preflight failed on <node> y una lista de rutas.

Comprobación en el host del nodo (Linux):

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

3.3. Página de inscripción de bases de datos

Inscripción de bases de datos: formulario y vista previa
Inscripción de bases de datos: formulario y vista previa
  1. Abra la página de inscripción del nodo maestro. El enlace está en dos sitios:

    • Bases de datos → tabla Nodos → columna de acciones → Inscribir;
    • Resumen → tarjeta del nodo maestro → Inscribir bases de datos.

    Un nodo réplica no tiene esta página.

  2. El formulario muestra las reglas actuales del nodo (el nodo las envió él mismo). Si el nodo no responde, los botones de vista previa y de inscripción están desactivados: sin las reglas actuales pondrían a cero las listas de inclusión y de exclusión.

  3. Rellene o corrija los campos: Ruta de la carpeta en este servidor, recursivo, máscaras, Filtro de tamaño, Tablas de seguimiento de la sincronización.

    El campo Tablas de seguimiento de la sincronización:

    • con HQbird 2027.2.24 y posterior, la lista es por base de datos que esta acción inscribirá. Campo vacío: la base de datos usa las tablas de su propia publicación. La inscripción no cambia la lista compartida del nodo (sync_tables). Si existe, el formulario lo dice: una base de datos sin lista propia la usa en lugar de la publicación. La lista de una base de datos ya gestionada se define en su página: Bases de datos → base de datos maestra → bloque Tablas de seguimiento de la sincronización. El bloque muestra qué lista está en vigor. Un campo vacío quita la lista propia de la base de datos;
    • en RCM y el nodo 2027.5.7, una sola lista para todas las bases de datos del nodo (sync_tables).
  4. Pulse Vista previa. El nodo mostrará todos los archivos que coinciden con la máscara de inclusión. No cambia nada.

  5. Revise la lista. Cada archivo tiene una casilla:

    • marcada: el archivo quedará gestionado;
    • marcada, bloqueada, con la marca ya gestionada: la base de datos ya está inscrita;
    • bloqueada con un motivo: el archivo está excluido por máscara, tamaño o la lista de exclusión. Para tomarlo, cambie la regla.
  6. Marque las bases de datos necesarias y pulse Inscribir las seleccionadas. RCM pedirá confirmación y mostrará el número de archivos.

Confirmación de la inscripción
Confirmación de la inscripción

Qué hace este botón:

  • en modo de plantilla, los archivos sin casilla se añaden a la lista de exclusión y los archivos con casilla se quitan de ella;
  • en modo de lista, los archivos con casilla se añaden a la lista de inclusión.

El botón añade bases de datos a las que ya están gestionadas. No cambia las filas bloqueadas. 7. El botón Inscribir aplica el formulario sin cambiar las listas. 8. Espere el mensaje de finalización y el número de bases de datos añadidas. Si no hay respuesta durante mucho tiempo, compruebe el resultado en la página Comandos.

Con HQbird 2027.2.24 y posterior el mensaje es «Inscritas: N». Si hay que reiniciar el Firebird del maestro, RCM dice qué botón pulsar (normalmente Reiniciar el Firebird del maestro en la fila de la base de datos) y da un enlace a las bases de datos maestras. RCM 2027.5.7 puede decir «No hay bases de datos nuevas adecuadas», aunque se hayan añadido bases de datos: compruebe la página Bases de datos.

Resultado de la inscripción
Resultado de la inscripción

Si después de la inscripción no se encontró ninguna base de datos, pero el nodo ya tenía bases de datos, el nodo rechaza (409) y devuelve las reglas antiguas. Así, un error en la ruta no desactiva la replicación de todas las bases de datos.

Lo mismo desde la línea de comandos

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

Nota: el comando envía solo los campos de sus parámetros. El nodo pondrá a cero las demás reglas (máscaras, tamaños, listas de inclusión y de exclusión, sync_tables). El comando no tiene parámetros para estas reglas. Antes de ejecutar el comando, compruebe las reglas actuales (hqbirdrcm getconfig -node node-a). Si están definidas, use la página de inscripción.

3.4. Qué ocurre después del registro

  1. El nodo escribe las reglas en node.json.
  2. El nodo analiza la carpeta (scansync).
  3. Para cada base de datos encontrada, el nodo escribe un bloque en su propia zona de replication.conf (entre las líneas # BEGIN managed-by:node-a role:master y # END …) y crea las carpetas <database>.ReplLog y <database>.LogArch. El nodo no modifica el texto fuera de su propia zona.
  4. Antes de hacer un cambio, el nodo guarda una copia del archivo: replication_YYYYMMDD_hhmmss_NNN.conf.
  5. Si replication.conf ha cambiado, las bases de datos pasan al estado PENDING_RESTART: Firebird solo leerá el archivo nuevo después de un reinicio. En la tabla Nodos esto se muestra en la columna Reinicio pendiente.
La columna «Reinicio pendiente» en la tabla «Nodos»
La columna «Reinicio pendiente» en la tabla «Nodos»

Estados de una base de datos nueva:

Estado Grupo en RCM Significado
UNCONFIGURED Pendiente base de datos encontrada, configuración aún no escrita
PENDING_RESTART Pendiente configuración escrita, hace falta reiniciar Firebird
CONFIGURED Pendiente Firebird reiniciado, base de datos lista para la publicación y la inicialización

3.5. Reiniciar el Firebird del maestro

El nodo maestro nunca reinicia Firebird por sí mismo. RCM tampoco. Reiniciar el maestro es una decisión del operador: un reinicio corta todas las conexiones a todas las bases de datos de esa instancia de Firebird.

Elija un momento de poca carga y pulse uno de los botones:

  • Reiniciar el Firebird del maestro, en la página Bases de datos, en la fila del maestro de la base de datos que espera un reinicio;
  • el mismo botón en la ventana Inicializar, capítulo 5;
  • Reiniciar Firebird, en la página de la base de datos.

RCM pedirá confirmación. Muestra el nombre del nodo y una advertencia: Firebird se reiniciará de inmediato, sin ventana de reinicio, y se cortarán todas las conexiones.

Confirmación del reinicio del Firebird del maestro
Confirmación del reinicio del Firebird del maestro

Lo mismo desde la línea de comandos

Command
hqbirdrcm restartfirebird -node node-a

Este comando también reinicia de inmediato, sin ventana de reinicio.

Cómo reinicia Firebird el nodo:

  1. Comprueba que fbagent responde y gestiona la misma instancia (identificador, puerto, nombre del servicio de node.json). Si algún valor no coincide, el nodo rechaza.
  2. Pide a fbagent que reinicie Firebird.
  3. Espera a que Firebird responda en su puerto.
  4. Pasa las bases de datos de PENDING_RESTART a CONFIGURED.

Varias instancias de HQbird en un host. fbagent reinicia los servicios enumerados en firebird.update.services de su configuración. Una lista vacía significa todos los servicios de HQbird del host. Si hay dos instancias de HQbird en el host, deje en la lista solo el servicio de su instancia. Si no, al reiniciar un nodo también se detendrá la otra instancia.

En Windows. Si replication.log ha crecido hasta log_portion_mb o más, el reinicio procede así: detener Firebird → archivar el registro → iniciar.

3.6. Una base de datos que ya se replica a mano

Si la replicación de una base de datos ya está configurada a mano (su propio bloque en replication.conf, publicación activada, segmentos en circulación), se puede poner bajo gestión sin volver a inicializar la réplica. Para eso existe el modo detect_existing (solo maestro).

  1. Ejecute una vista previa:

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

    En la respuesta, taken_over enumera las bases de datos que se migrarán. Añada -verbose para ver las bases de datos omitidas con el motivo.

  2. Si la lista es correcta, ejecute el comando sin -dry-run.

El nodo migra un bloque solo si:

  • las carpetas de segmentos se llaman exactamente <database>.ReplLog y <database>.LogArch;
  • ya hay segmentos en el archivo;
  • la publicación está activada en la base de datos.

El nodo no migra un bloque con rutas distintas y lo informa como «encontrado pero no compatible».

Después de la migración las bases de datos reciben PENDING_RESTART, aunque los ajustes de replicación no cambien: solo cambia la posición del bloque en el archivo. Reinicie Firebird en una ventana de mantenimiento.

3.7. Cómo comprobar

  • Bases de datos: la base de datos se ve en la fila del nodo maestro, estado CONFIGURED (después del reinicio).

  • Junto a la base de datos puede haber un icono publicación desactivada: la publicación aún no está activada. Es normal; la publicación es el paso siguiente (capítulo 6).

    Base de datos nueva en la fila del maestro
    Base de datos nueva en la fila del maestro
  • En el host del nodo: el bloque de la base de datos está en replication.conf dentro de la zona managed-by:node-a, y junto a la base de datos están las carpetas .ReplLog y .LogArch.

3.8. Quitar una base de datos de la gestión

La forma habitual es el botón. En la página Bases de datos, marque las bases de datos, seleccione la acción masiva Quitar de la gestión y pulse Aplicar a la selección. RCM:

  1. añade los archivos a la lista de exclusión del nodo;
  2. analiza la carpeta una vez: los bloques de la base de datos se quitan de replication.conf;
  3. borra los registros de la base de datos en el nodo.

Los archivos de la base de datos y las carpetas de segmentos permanecen en el disco. Firebird no se reinicia. Firebird sigue escribiendo los segmentos de la base de datos hasta su siguiente reinicio; RCM dirá si hace falta un reinicio.

RCM rechazará (has_replicas) una base de datos maestra que tenga una réplica viva: si no, la réplica se detendría en silencio. Primero convierta la réplica en una base de datos normal o quítala (capítulo 8).

No borre a mano el bloque de la base de datos de replication.conf: en el siguiente análisis el nodo lo escribirá otra vez.

Si el archivo de la base de datos ha desaparecido o una regla lo ha excluido. Entonces la base de datos recibe el estado ORPHANED (el grupo Huérfanas). El nodo conserva su registro y el archivo de segmentos: una base de datos ausente es más a menudo un error que una decisión. Si el archivo vuelve, la base de datos vuelve a funcionar y la alerta se borra. Para borrar de forma permanente esa base de datos, haga dos pasos en este orden:

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>

Después de forgetdatabase, el comando cleanuparchive ya no encontrará la base de datos. Ambos comandos solo funcionan para una base de datos en estado ORPHANED y no tocan el archivo de la base de datos.

Precaución. Después de promover una réplica a maestro (capítulo 8), no ejecute cleanuparchive -orphaned para el registro antiguo: el maestro nuevo usa la misma carpeta .LogArch, y el comando borrará su archivo de trabajo.

3.9. Cambiar la raíz de las bases de datos

Se permite el registro con otra ruta. El nodo:

  • añade las bases de datos de la carpeta nueva;
  • pasa a ORPHANED las bases de datos de la carpeta antigua que no están en la nueva (notificación orphaned_database) y conserva sus archivos.

Si eligió la carpeta equivocada, vuelva a registrar la carpeta correcta. Una base de datos con la misma ruta completa seguirá funcionando con el mismo db_id. Una base de datos en una ruta distinta es una base de datos nueva (nuevo db_id); su réplica debe inicializarse otra vez.

3.10. Errores frecuentes

Qué ve Causa Qué hacer
preflight failed on node-a no hay permisos sobre las carpetas corrija los permisos, inténtelo de nuevo (3.2)
409 scan_would_empty_region la carpeta nueva no contiene bases de datos, pero el nodo tenía algunas compruebe la ruta y la máscara
La vista previa está vacía la máscara no coincide o la carpeta es incorrecta compruebe la ruta, la máscara, «recursivo»
Los botones están desactivados, «No se pudo leer la configuración del nodo» el nodo no responde compruebe el servicio del nodo y la red (capítulo 1)
La base de datos permanece mucho tiempo en PENDING_RESTART el maestro no reinicia Firebird por sí mismo reinicie Firebird (3.5)
Reinicio rechazado por fbagent fbagent no está en ejecución o sus datos no coinciden con node.json capítulo 1, comprobación de fbagent
El archivo nuevo no apareció el nodo está en modo de lista añada el archivo mediante «Inscribir las seleccionadas»

4. Cómo convertir una base de datos en réplica: pasos y ubicación en disco

Este capítulo recorre todo el camino de una base de datos desde la primaria hasta una réplica en funcionamiento, más el cálculo del espacio en disco. La inicialización en sí se describe con detalle en el capítulo 5.

4.1. La regla principal

Una base de datos aparece en una réplica solo mediante la inicialización desde el maestro (reinit): el propio nodo maestro transfiere una copia mediante nbackup.

No haga una copia a mano:

  • gbak crea un GUID de base de datos nuevo y pone a cero el número de segmento. El enlace maestro-réplica se rompe.
  • Una copia de archivo de una base de datos en ejecución no es coherente, y RCM verá dos bases de datos con el mismo GUID (duplicate_guid) y prohibirá la inicialización.

Una réplica que ya está en funcionamiento y se configuró a mano se puede poner bajo gestión sin una copia nueva: véase 4.6.

4.2. Etapas

N.º Etapa Dónde Estado de la base de datos maestra después de la etapa
1 Registro de la base de datos en el maestro capítulo 3.3 PENDING_RESTART
2 Reinicio del Firebird del maestro capítulo 3.5 CONFIGURED
3 Sincronización de la publicación capítulo 6 CONFIGURED, publicación activada
4 Preparación de la réplica: carpeta, permisos, versión de Firebird 4.3 —
5 Comprobación del espacio libre en el maestro y en la réplica 4.4 —
6 Inicialización capítulo 5 SEEDING → IN_SYNC
7 Reinicio del Firebird de la réplica (si hace falta) capítulo 5.6 la réplica empieza a aplicar segmentos
8 Verificación de los datos capítulo 5.10 —

La etapa 3 es obligatoria para Firebird 4/5. Sin publicación, el Firebird del maestro no escribe los cambios de las tablas en los segmentos, y la réplica se queda atrás del maestro en silencio. En la página Bases de datos esa base de datos está marcada con el icono publicación desactivada. Pulse Sincronizar la publicación antes de la inicialización.

A partir de HQbird 2027.2.24, la ventana Inicializar avisa de esto y ofrece un botón Sincronizar la publicación e inicializar, mientras que el nodo maestro rechaza la inicialización con el error publication_off (capítulo 5.1). RCM y el nodo 2027.5.7 no comprueban la publicación.

HQbird 2.5/3.0. No hay publicaciones, así que se omite la etapa 3. El conjunto de tablas lo definen los filtros del complemento replconf (capítulo 6).

Estados de la base de datos:

Estado Grupo en RCM Significado
CONFIGURED Pendiente Firebird ha leído los ajustes, aún no hay réplica
PUBLISHING Pendiente la sincronización de la publicación está en curso
SEEDING Pendiente la inicialización está en curso
IN_SYNC Correcto la réplica ha recibido todos los segmentos
LAGGING Pendiente la réplica va retrasada, hay segmentos en cola
NEEDS_REINIT Error la réplica debe inicializarse otra vez
FAILED Error la última inicialización falló

4.3. Preparación de la réplica

Carpeta de la base de datos de la réplica

El nodo réplica coloca cada base de datos en su propia carpeta databases.root, en la ruta:

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

Ejemplo: maestro node-a con raíz /databases/master y base de datos /databases/master/sales/employee.fdb. En la réplica node-b con raíz /databases/replica, la base de datos estará aquí:

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

Así, las bases de datos con los mismos nombres de maestros distintos no chocan.

Nadie crea la carpeta raíz automáticamente: ni el instalador, ni HQCenter Admin, ni el nodo al arrancar. Créela de una de estas formas:

  • en la ventana Inicializar: el campo Carpeta de la réplica, el botón Crear carpeta. El botón solo se ve cuando la carpeta no existe. Con HQbird 2027.2.24, si el nodo réplica aún no tiene databases.root, el campo ya contiene /databases/replica/<id del nodo réplica>. Para una réplica en Windows el campo está vacío: introduzca una carpeta con letra de unidad. Cada nodo réplica del mismo host necesita su propia carpeta. La carpeta la crea el nodo réplica: propietario firebird (o el usuario del servicio del nodo), permisos 2770. Si el nodo no puede crearla, la ventana mostrará el comando para el host de la réplica. Si indica otra carpeta, RCM la escribirá en databases.root del nodo réplica antes de la inicialización;

  • a mano en el host de la réplica (Linux):

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

    El bit setgid (2770) hace falta para que todos los archivos de dentro reciban el grupo de Firebird.

La raíz de la réplica solo se puede cambiar mientras no tiene bases de datos: si no, las bases de datos antiguas quedarán fuera del análisis. Para poner una sola base de datos en otro sitio, use Mover en la página de la base de datos.

Permisos

El nodo réplica y Firebird deben poder escribir en la raíz de las bases de datos. El nodo comprueba que los archivos colocados recibirán el grupo de la carpeta. Si no puede, rechaza con ownership_unfixable y un texto sobre cómo corregirlo (normalmente el servicio del nodo se ejecuta con Group=root).

Con HQbird 2027.2.24, la ventana Inicializar también muestra una carpeta que existe pero en la que el servicio del nodo no puede escribir: el texto del nodo con el comando de corrección y un botón Comprobar de nuevo. RCM 2027.5.7 en este caso dice «La carpeta existe»: compruebe usted los permisos (hqbirdrcm checkpermissions -node <replica> -root <folder>).

Versión de Firebird

La versión mayor de Firebird en la réplica debe coincidir con la del maestro (5.0 → 5.0, 4.0 → 4.0). Si no, la réplica rechazará antes de cualquier transferencia de datos: incompatible_engine.

Conectividad

El nodo réplica debe ser un par del maestro, y el maestro debe ser un par de la réplica (capítulo 2). Si no, RCM no ofrecerá este nodo en la ventana Inicializar.

4.4. Cuánto espacio hace falta

En resumen

Dónde Qué Cuánto
Maestro, volumen de la base de datos libre antes de la inicialización ≥ 105 % del tamaño de la base de datos
Réplica, volumen de la carpeta de la base de datos libre antes de la inicialización ≥ 105 % del tamaño de la base de datos, con HQbird 2027.2.24, más free_space_floor_gb (más el archivo antiguo, si la réplica ya existía; con la casilla Eliminar la réplica antigua, sin él)
Maestro, <database>.ReplLog segmentos de trabajo de Firebird hasta 64 segmentos × tamaño del segmento (16 MB de forma predeterminada) ≈ 1 GB por base de datos
Maestro, <database>.LogArch archivo de segmentos para las réplicas cambios durante retention_days (de forma predeterminada 2 días) + lo que las réplicas aún no hayan confirmado
Réplica, <database>.Incoming cola de segmentos por aplicar hasta 256 segmentos × 16 MB ≈ 4 GB por base de datos en el peor caso
Réplica, volumen entero margen al menos free_space_floor_gb (de forma predeterminada 1 GB)

Comprobación del espacio antes de la inicialización

La inicialización comprueba el espacio dos veces y solo antes de bloquear la base de datos:

  1. RCM, a partir de las últimas estadísticas del nodo, antes de enviar el comando. Si el espacio es claramente insuficiente, RCM devuelve de inmediato el error 507.
  2. Nodo maestro, una medición en vivo en su propio volumen, y después una petición a la réplica para que mida el suyo. Si falta en al menos un lado, la inicialización termina en el paso SPACE CHECK con el error insufficient disk space on master o … on replica.

El requisito en ambos lados es el 105 % del tamaño de la base de datos maestra.

Con HQbird 2027.2.24 el nodo réplica calcula así:

  • necesita el 105 % del tamaño de la base de datos más el free_space_floor_gb de la réplica (7.3): después de la inicialización queda una reserva para los segmentos en el volumen;
  • los restos de inicializaciones anteriores (<database>.hqcluster-part, <database>.new) cuentan como espacio libre: el nodo los borra antes de la copia nueva;
  • el texto del error nombra todos los números. También nombra los archivos <database>.pre-reinit-*.fdb y <database>.failed-seed-*.fdb con su tamaño. El nodo nunca los borra: bórrelos usted si no hacen falta.

force (forzado) omite solo la comprobación de RCM. La comprobación del nodo no se puede saltar: protege al nodo de quedarse sin disco a mitad de la copia. Si el espacio es insuficiente solo por la copia antigua de la réplica, RCM 2027.2.24 en el error 507 nombra la casilla Eliminar la réplica antigua en lugar de force. Para eso, ambos nodos deben ser HQbird 2027.2.24 o posterior. Si no, el error nombra el nodo que hay que actualizar, y force.

Por qué tanto

Maestro. Durante la copia la base de datos está bloqueada por nbackup -L. Todos los cambios se escriben en el archivo <database>.delta junto a la base de datos. El tamaño de .delta depende de la carga de escritura durante la copia. Con mucha carga y una transferencia lenta puede crecer bastante: vigile el espacio durante la primera inicialización.

Réplica. La copia se escribe directamente en el archivo <database>.hqcluster-part junto al lugar de la base de datos. El nodo reserva el tamaño completo por adelantado. Después el archivo se comprueba, se repara (nbackup -FIXUP -SEQUENCE) y se renombra en su sitio. No hace falta una segunda copia: el tamaño de la base de datos se necesita una vez, en el volumen de la base de datos.

Si la réplica ya existía (inicialización repetida), el archivo antiguo permanece en el disco hasta el último paso. Eso significa que el archivo antiguo y la copia nueva se necesitan en el volumen al mismo tiempo. El espacio libre se calcula sin el archivo antiguo, por eso el requisito es el mismo: el 105 % del tamaño de la base de datos libre.

Eliminar la réplica antigua (con HQbird 2027.2.24). Si en el volumen de la réplica no hay espacio para la copia nueva junto a la antigua, marque esta casilla en la ventana de inicialización (capítulo 5.1). Entonces el nodo réplica borra la copia antigua y sus segmentos entrantes (.Incoming) antes de la transferencia, y el volumen tiene bastante para el 105 % del tamaño de la base de datos más free_space_floor_gb. El nodo borra la copia solo si se cumplen todas las condiciones:

  • sin el borrado no hay espacio suficiente, y con el borrado sí lo hay;
  • es una copia instalada por la inicialización de este nodo: la cabecera se puede leer, el modo es réplica de solo lectura;
  • la base de datos no se ha convertido en normal (no hay archivo <database>.hqcluster-normal.json, capítulo 8);
  • overwrite_non_replica no está definido (5.9).

Si no, el nodo no borra nada y rechaza con el motivo en el texto. Para borrar, el nodo detiene el Firebird de la réplica durante el borrado (5.6).

La casilla está desactivada de forma predeterminada. Riesgo: mientras la transferencia está en curso, no hay copia de la base de datos en la réplica. Si la base de datos solo tiene una réplica, el maestro queda desprotegido todo el tiempo. Mientras no hay copia nueva, la base de datos de la réplica está en estado NEEDS_REINIT (no FAILED ni ORPHANED), y la réplica emite la alerta replica_removed_for_reinit (advertencia). Cuando la copia nueva está en su sitio, la alerta se borra. Si la inicialización falla después del borrado, el par permanece en NEEDS_REINIT: inicie la inicialización otra vez (o la reinicialización automática la iniciará, 5.8). Una inicialización nueva transfiere la base de datos desde el principio.

Archivo del maestro (.LogArch). El nodo conserva los segmentos enviados durante retention_days días para que la réplica pueda volver a pedirlos. Los segmentos que la réplica aún no ha aplicado se conservan más tiempo. Si queda poco espacio, el nodo limpia el archivo por etapas:

  1. segmentos aplicados por todas las réplicas más antiguos que retention_days;
  2. segmentos aplicados más recientes (cuando falta espacio);
  3. segmentos no aplicados, solo como último recurso. Entonces la réplica pierde los segmentos que necesita y recibe NEEDS_REINIT.

Si una réplica no está disponible durante mucho tiempo, el archivo crece. Su volumen es los cambios de la base de datos durante el periodo de inactividad.

Ejemplo de cálculo

Base de datos de 100 GB. Carga: 5 GB de segmentos al día. La inicialización se ejecuta de noche, la copia tarda 2 horas, durante las cuales unos 2 GB acaban en .delta.

Dónde Cálculo Total libre
Maestro, volumen de la base de datos 105 GB para las comprobaciones (incluye el crecimiento de .delta) + .ReplLog 1 GB + .LogArch 2 días × 5 GB = 10 GB ≥ 116 GB
Réplica, base de datos nueva 105 GB + .Incoming hasta 4 GB + 1 GB de reserva ≥ 110 GB
Réplica, inicialización repetida archivo antiguo de 100 GB ya en el disco + 110 GB libres volumen ≥ 210 GB
Réplica, inicialización repetida con la casilla Eliminar la réplica antigua (con HQbird 2027.2.24) archivo antiguo borrado antes de la transferencia: 105 GB + .Incoming hasta 4 GB + 1 GB de reserva volumen ≥ 110 GB

Añada una reserva para el crecimiento de la base de datos y para la inactividad de la réplica (el archivo del maestro crece 5 GB por día de inactividad).

Segmentos en un volumen aparte

Las carpetas .ReplLog, .LogArch y .Incoming están de forma predeterminada junto a la base de datos. Se pueden mover a otro volumen: el parámetro segments.storage en node.json (con mirror_hierarchy: true el nodo replica la estructura de las carpetas de las bases de datos). Entonces el archivo no quita espacio a las bases de datos. La comprobación del 105 % sigue aplicándose al volumen de la base de datos.

Dónde mirar el espacio

  • Bases de datos → Nodos y Resumen: el icono de espacio libre del volumen de databases.root. Amarillo: menos del 20 %, rojo: menos del 10 %.

    Página Bases de datos: la columna Disco en la tabla Nodos
    Página Bases de datos: la columna Disco en la tabla Nodos
  • Informe del clúster: hqbirdrcm report.

4.5. Varias réplicas de una base de datos

La segunda réplica y las siguientes se crean del mismo modo: Inicializar en la fila del maestro, seleccionando un nodo réplica libre.

  • Mientras se inicializa una réplica nueva, el maestro tampoco transmite esta base de datos a las réplicas que ya están en funcionamiento. Alcanzarán al maestro cuando termine la inicialización. La ventana de confirmación lo dice.
  • Una base de datos: una inicialización a la vez, incluso para réplicas distintas.
  • El espacio del maestro se comprueba por separado para cada inicialización.
Base de datos maestra con dos réplicas
Base de datos maestra con dos réplicas

4.6. Réplica configurada a mano

Si una réplica ya está en funcionamiento a partir de un replication.conf escrito a mano, puede ponerla bajo gestión y no copiar la base de datos otra vez:

  1. Maestro: registre las bases de datos con detect_existing (capítulo 3.6).
  2. Réplica: Bases de datos → nodo réplica → Tomar el control, o hqbirdrcm takeover-replica. RCM encontrará los bloques de la réplica, emparejará los archivos con las bases de datos maestras por GUID y mostrará para cada uno: in_sync, resumable o needs_reinit.
  3. Confirme las filas. El nodo moverá los bloques a su propia zona de replication.conf.
  4. Reinicie el Firebird de la réplica para que lea los bloques movidos.
  5. Inicialice solo las filas needs_reinit: el archivo del maestro ya no contiene los segmentos que necesitan estas réplicas.

4.7. Errores frecuentes

Qué ve Causa Qué hacer
insufficient disk space on master / on replica no hay espacio suficiente (4.4). En una reinicialización la copia antigua ocupa espacio hasta el final (4.4) libere espacio, inténtelo de nuevo. La segunda salida en la réplica (desde HQbird 2027.2.24) es la casilla Eliminar la réplica antigua (4.4, 5.1)
507 de RCM de inmediato según las estadísticas de espacio, claramente no hay bastante lo mismo. Si hay espacio sin la copia antigua, RCM 2027.2.24 nombra la casilla Eliminar la réplica antigua
incompatible_engine versiones mayores de Firebird distintas actualice el Firebird de la réplica
Falta la carpeta en el nodo réplica la raíz no se ha creado Crear carpeta en la ventana de inicialización (4.3)
La carpeta existe, pero el servicio del nodo no puede escribir en ella (desde HQbird 2027.2.24) no hay permisos de escritura ejecute el comando de la ventana, pulse Comprobar de nuevo (4.3)
publication_off (desde HQbird 2027.2.24) la publicación del maestro está desactivada o no tiene tablas Sincronizar la publicación e inicializar (5.1)
ownership_unfixable el servicio del nodo tiene un grupo ajeno corrija el grupo del servicio como dice el texto del error
duplicate_guid dos bases de datos con el mismo GUID (una copia de archivo) quite la copia o déle un GUID nuevo (nbackup -F)
El nodo réplica no está en la lista Inicializar no hay conexión en los pares capítulo 2
Réplica IN_SYNC, pero los datos divergen la publicación estaba desactivada sincronice la publicación y después repita la inicialización

5. Inicialización (reinit)

La inicialización es la transferencia de una copia de la base de datos maestra a la réplica. La primera transferencia se llama inicialización (el botón Inicializar); una transferencia repetida es la reinicialización (el botón Reinicializar). El mecanismo es el mismo.

Antes de empezar, complete los pasos 1–5 del capítulo 4: la base de datos está registrada, el Firebird del maestro se ha reiniciado, la publicación está activada, existe la carpeta de la réplica y hay espacio suficiente. Cuánto espacio hace falta en el maestro y en la réplica se describe en el capítulo 4.4.

5.1. Cómo empezar

Primero la publicación. Registrar una base de datos no incluye la publicación. Sin publicación, la réplica no recibe cambios. Antes de la inicialización, ejecute Sincronizar la publicación (capítulo 6) o hqbirdrcm setpublication -node <master>.

  • Con HQbird 2027.2.24, la ventana de inicialización comprueba la publicación. Si está desactivada o no tiene tablas con clave, la ventana muestra una advertencia y un botón Sincronizar la publicación e inicializar. RCM sincroniza la publicación, espera a que termine el comando e inicia la inicialización con la selección de la ventana.
  • Un nodo maestro 2027.2.24 rechaza él mismo esa inicialización (también la primera) con el error publication_off y emite la notificación master_publication_off (capítulo 6.1). Después del rechazo, la celda de la base de datos vuelve a tener el botón Sincronizar la publicación e inicializar.
  • Si el operador desactivó la publicación (6.4) o quitó de ella todas las tablas con clave (6.3), la sincronización lo conserva. RCM no inicia la inicialización y da un enlace a la página Tablas de la publicación.
  • RCM y el nodo 2027.5.7 no comprueban la publicación: la inicialización tiene éxito, la base de datos muestra «Correcto» en RCM, pero la réplica no recibe cambios. Si la publicación se activó después de la inicialización, reinicialice la base de datos.
La ventana «¿Reinicializar la base de datos?»
La ventana «¿Reinicializar la base de datos?»
  1. Abra Bases de datos.
  2. En la fila de la base de datos maestra, en la columna del nodo réplica, pulse Inicializar. El nodo réplica lo fija la columna: no se elige en la ventana. Para un par existente, Reinicializar en la tarjeta expandida del maestro.
  3. En la ventana (con HQbird 2027.2.24 el título para un par nuevo es «¿Inicializar la base de datos?»; en RCM 2027.5.7, «¿Reinicializar la base de datos?» también en la primera inicialización):
    • compruebe la Carpeta de la réplica. La ventana muestra si la carpeta existe. Si no existe, pulse Crear carpeta: el nodo réplica la creará (4.3). Si el nodo no puede crearla, la ventana muestra el comando para el host de la réplica. Con HQbird 2027.2.24 la ventana también muestra una carpeta en la que el servicio del nodo no puede escribir: el comando de corrección y un botón Comprobar de nuevo;
    • seleccione el Método de reinicialización: Suave (recomendado) o Estándar (5.4). Con HQbird 2027.2.24, si el archivo del maestro aún no tiene segmentos (normalmente antes de la primera inicialización), la ventana muestra una pista: en una base de datos ocupada Estándar es más rápido;
    • si la base de datos maestra aún espera un reinicio de Firebird, la ventana lo dirá y mostrará un botón Reiniciar el Firebird del maestro. Sin el reinicio la base de datos no se replica;
    • Eliminar la réplica antigua (con HQbird 2027.2.24, desactivada de forma predeterminada) solo hace falta en una reinicialización cuando el volumen de la réplica no tiene espacio para una copia nueva junto a la antigua (4.4). La ventana muestra los números por adelantado: cuánto hace falta, cuánto hay libre, cuánto ocupa la copia antigua. Si hay espacio sin la copia antigua, la ventana pide marcar la casilla. La casilla está inactiva si el nodo maestro o el réplica es una versión antigua: la ventana indica qué nodo actualizar. Hasta que la copia nueva esté lista, la réplica no tiene copia de esta base de datos (4.4).
  4. Confirme. RCM indicará que la base de datos se bloqueará en el maestro y se copiará a la réplica.

El progreso de la inicialización se ve en la tarjeta expandida del maestro en la página Bases de datos: pasos y porcentajes. Con HQbird 2027.2.24 el progreso también se ve después de actualizar la página: en la primera inicialización, en la celda del nodo réplica, y también en la fila Progreso de la reinicialización de la página de la base de datos maestra. El botón Inicializar está inactivo mientras el nodo maestro copia la base de datos. Si RCM no sigue esta inicialización (por ejemplo, se inició desde la línea de comandos del nodo), los pasos se toman del estado del nodo, sin porcentajes. En RCM 2027.5.7, después de actualizar la página, el progreso de la primera inicialización no se ve: espere a que la base de datos maestra salga de SEEDING.

Pasos de la inicialización en la fila del maestro
Pasos de la inicialización en la fila del maestro

Cada comando de RCM (inicialización, reinicio de Firebird, sincronización de la publicación) queda registrado en la página Comandos con su resultado.

La página «Comandos»
La página «Comandos»

Lo mismo desde la línea de comandos

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

Parámetros: -mode smooth|standard (predeterminado smooth), -hold=false (no retener el archivo durante las transacciones largas), -allow-restart (5.6), -force (5.9).

-remove-old-replica (con HQbird 2027.2.24) es lo mismo que la casilla Eliminar la réplica antigua. Solo para una base de datos: -db y -to son obligatorios; con -all el comando rechaza. Si el nodo maestro o el réplica es una versión antigua, RCM rechaza con node_too_old y no envía nada.

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

-all prueba todas las bases de datos y reúne los errores en lugar de detenerse en el primero.

5.2. Pasos

N.º Paso (en RCM) Qué ocurre
1 SPACE CHECK comprueba el espacio en el maestro y en la réplica (capítulo 4.4); la réplica comprueba por adelantado que puede aceptar el archivo
2 LOCKING nbackup -L: el archivo de la base de datos maestra se congela, los cambios van a <database>.delta
3 COPYING TO NODE el archivo se transfiere por partes: lectura → suma de comprobación → compresión → envío
4 UNLOCKING nbackup -N justo después de la transferencia: los cambios de .delta vuelven a la base de datos
5 SEEDING en la réplica: verificación de la suma del archivo, nbackup -FIXUP -SEQUENCE, instalación del archivo, gfix -replica, escritura del bloque en replication.conf
6 RESTARTING REPLICA reinicio del Firebird de la réplica, si hace falta (5.6)

Después del paso 6 la base de datos recibe el estado IN_SYNC. El maestro sigue enviando segmentos desde el punto en que termina la copia.

Qué conviene saber:

  • El maestro funciona todo el tiempo. Los usuarios escriben en la base de datos, los cambios van a .delta. El bloqueo se libera justo después de la transferencia.
  • Las transacciones que coincidieron con el bloqueo no se pierden. El nodo encuentra las transacciones abiertas en el momento de nbackup -L, y la réplica las reproduce desde los segmentos.
  • La transferencia continúa después de una interrupción. Si la conexión o el nodo réplica se reinició, el maestro continuará desde la última parte recibida. Una transferencia inconclusa se conserva en la réplica durante 24 horas (reinit_partial_keep_hours).
  • Ante un error el nodo libera el bloqueo, borra el archivo inconcluso en la réplica y pone la base de datos en FAILED. El siguiente intento empieza desde un estado conocido.
  • Con la casilla «Eliminar la réplica antigua» (desde HQbird 2027.2.24) la réplica borra la copia antigua después del paso LOCKING, antes de la transferencia. El paso COPYING TO NODE muestra en ese momento «eliminando la copia antigua de la réplica para hacer espacio». Un error después del borrado da al par NEEDS_REINIT en lugar de FAILED (capítulo 4.4).
  • Solo nbackup. No se usa gbak: cambia el GUID de la base de datos.

5.3. Efecto sobre el funcionamiento

Qué Efecto
Usuarios del maestro siguen trabajando; durante la copia .delta crece, después de -N los cambios se transfieren a la base de datos
Otras réplicas de esta base de datos no reciben segmentos de esta base de datos mientras la inicialización está en curso; se ponen al día después
Otras bases de datos del maestro no se ven afectadas
Firebird de la réplica, base de datos nueva no se detiene; reinicio según 5.6
Firebird de la réplica, inicialización repetida se detiene mientras se sustituye el archivo: todas las bases de datos de este Firebird no están disponibles durante unos segundos
Firebird de la réplica, el nodo borra la copia antigua (casilla «Eliminar la réplica antigua», desde HQbird 2027.2.24) se detiene antes, mientras dura el borrado, antes de la transferencia. El nodo instala la copia nueva sin una segunda parada si el bloque de la base de datos en replication.conf no ha cambiado. Si hay espacio suficiente y no hace falta borrar, el nodo no borra nada, y todo sigue como en una inicialización repetida normal
Red y disco carga según los límites de velocidad (5.5)

En Windows. Un archivo abierto por Firebird no se puede sustituir. Durante una inicialización repetida el nodo detiene el Firebird de la réplica mediante fbagent, instala el archivo e inicia Firebird otra vez. En Linux Firebird también se detiene antes de la sustitución: si no, seguiría trabajando con el archivo antiguo ya borrado.

5.4. Métodos suave y estándar

Suave (predeterminado). Antes de bloquear, el nodo busca transacciones largas: transacciones de escritura de usuario que empezaron antes del segmento más antiguo del archivo del maestro. Después de la inicialización la réplica no podrá reproducirlas y se detendrá en su primer cambio («Transaction … is not found»). Las transacciones sin cambios no se cuentan.

Si existen esas transacciones, la inicialización no empieza: RCM muestra La reinicialización suave espera transacciones largas y da un enlace Abrir la lista.

Página de transacciones largas: no hay transacciones largas
Página de transacciones largas: no hay transacciones largas

En la página Transacciones largas:

  • resumen: cuántas transacciones y conexiones, el segmento más antiguo;
  • Las 5 conexiones principales con las transacciones más antiguas: usuario, cliente, inicio, antigüedad, cambios, consulta actual;
  • Retener segmentos / Liberar la retención: mientras la retención está activada, el archivo del maestro no se purga y el historial no se trunca;
  • Desconectar las seleccionadas y reintentar la reinicialización: desconecta las conexiones (sus transacciones se revierten) e inicia de inmediato una reinicialización suave;
  • Reintentar la reinicialización, Comprobar de nuevo.

La retención se activa automáticamente cuando se rechaza una reinicialización por transacciones largas. Se libera después de una inicialización correcta, a mano, o cuando el archivo crece hasta reinit_hold_max_segments (1000 segmentos de forma predeterminada, notificación retention_hold_released).

Estándar bloquea la base de datos de inmediato, sin comprobar. Úselo solo si sabe que no hay transacciones de escritura largas.

Primera inicialización bajo carga. Mientras el archivo del maestro está vacío, no hay segmento con el que comparar.

Con un nodo maestro HQbird 2027.2.24: si el nodo activó la publicación él mismo y el archivo no ha cambiado desde entonces, el historial empieza en el momento en que se activó la publicación. Una transacción iniciada después entra en el diario desde su primer cambio y no estorba al método suave. Una transacción iniciada antes no entró en el diario: la reinicialización la espera antes de bloquear (6 intentos cada 10 s), y el paso locking muestra su número, la conexión y el usuario. Si no ha terminado, la reinicialización acaba con el error reinit_pre_publication_transactions: termínela e inténtelo de nuevo. La página Transacciones largas muestra esas transacciones en la tabla Transacciones iniciadas antes de que se activara la publicación.

Si la publicación se activó a mano, no mediante el nodo, o el archivo ya ha cambiado, el inicio del historial es desconocido. En ese caso el método suave rechaza si hay alguna transacción de escritura abierta, y el mensaje dice que el archivo aún no contiene un segmento. En este caso RCM 2027.2.24 no abre la lista, sino que escribe qué hacer en la celda de la base de datos. Elija Estándar o inténtelo de nuevo cuando Firebird archive el primer segmento.

Con un nodo maestro 2027.5.7, el método suave rechaza de inmediato en la primera inicialización de una base de datos en la que se está escribiendo: long_transactions … segment 0 (0001-01-01T00:00:00Z). Para la primera inicialización de esa base de datos, elija Estándar.

Para las reinicializaciones siguientes el método suave funciona como de costumbre (el archivo ya existe).

Lo mismo desde la línea de comandos

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

Transacciones más antiguas que la publicación. Firebird no escribe en los segmentos una transacción que empezó antes de que se activara la publicación. Si el nodo activó la publicación, la inicialización espera (6 intentos cada 10 segundos) a que terminen esas transacciones; si no, acaba con el error reinit_pre_publication_transactions enumerándolas. Después de sincronizar una publicación que añadió tablas, reconecte las aplicaciones y después inicie la inicialización.

5.5. Velocidad

Cuándo Velocidad Ajuste
Dentro de la ventana de transferencia windows.transfer_window (predeterminado 23:00-05:00) constante limits.reinit_window_mbps, predeterminado 100 MB/s
Fuera de la ventana fracción de la velocidad de disco medida limits.reinit_day_disk_fraction, predeterminado 0.5

El nodo recalcula el modo cada 30 segundos: una inicialización empezada de día se acelerará sola por la noche.

El nodo mide la velocidad del disco con una prueba. Para repetir la prueba en el host del maestro:

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

Tiempo de inicialización ≈ tamaño de la base de datos ÷ velocidad. Ejemplo: 100 GB a 100 MB/s, unos 17 minutos de transferencia pura; en la práctica lo limitan la red o el disco.

5.6. Reinicio del Firebird de la réplica

Una base de datos nueva en la réplica. El archivo se coloca sin detener Firebird. Firebird solo leerá el bloque nuevo de replication.conf después de un reinicio. Hasta entonces la réplica no aplica nada. El paso RESTARTING REPLICA muestra la espera:

Etiqueta Qué significa
esperando un reinicio de Firebird en la réplica, está programado para … el nodo reiniciará Firebird él mismo después de la última inicialización (reinit_restart_delay_sec), cuando hayan terminado las demás inicializaciones
… la ventana de reinicio está cerrada, la siguiente se abrirá a las … espera de restart_window de la réplica
… el último intento falló, el siguiente a las … lo intentará más tarde
la réplica no puede reiniciar Firebird ella misma: reinícielo a mano auto_restart: never, o este Firebird también sirve las bases de datos del maestro

El nodo reinicia Firebird una vez después de una serie de inicializaciones, no después de cada base de datos.

Para reiniciar a mano, pulse Reiniciar el Firebird de la réplica. La espera termina después de cualquier reinicio correcto de Firebird o cuando la réplica ha aplicado un segmento más nuevo que la copia.

Reinicialización en un Firebird que también sirve las bases de datos del maestro. El nodo no detiene ese Firebird él mismo y rechaza con restart_not_allowed. Inicie la inicialización otra vez y marque Permitir que detenga Firebird para esta reinicialización (-allow-restart en la línea de comandos), en un momento en que se puedan cortar las conexiones de este Firebird, incluidas las de sus bases de datos maestras. Ejecute esas inicializaciones de una en una por host.

Borrar la copia antigua (la casilla Eliminar la réplica antigua, con HQbird 2027.2.24) también detiene el Firebird de la réplica, con las mismas reglas. Si el nodo no puede detener este Firebird él mismo, no borra nada y rechaza con restart_not_allowed: marque también Permitir que detenga Firebird para esta reinicialización. Si en ese momento otra inicialización está terminando en la réplica o Firebird se está reiniciando, el nodo no borra nada y rechaza con engine_busy: el maestro libera el bloqueo, inténtelo más tarde.

5.7. Cola e inicializaciones simultáneas

  • Una base de datos: una inicialización a la vez (incluso para réplicas distintas). El botón Inicializar está desactivado mientras hay una inicialización de esta base de datos en curso.
  • El nodo maestro impone limits.max_concurrent_reinits inicializaciones de bases de datos distintas a la vez (de forma predeterminada 1). El resto espera en la cola; la respuesta contiene la posición en la cola.
  • No ejecute su propio nbackup -L (ni ALTER DATABASE BEGIN BACKUP) en una base de datos durante su inicialización, y no inicie una inicialización durante esa copia de seguridad: una base de datos solo puede tener un bloqueo. La inicialización lo comprueba y rechaza con nbackup backup lock already active.

La cola y las transferencias en curso se ven en la página Transferencia.

Página Transferencia / colas
Página Transferencia / colas
- Si después de un fallo queda un archivo `.delta`, asegúrese de que no hay ninguna copia de seguridad en curso y ejecute `nbackup -N `. No borre el `.delta` a mano.

5.8. Reinicialización automática

RCM puede reinicializar él mismo una base de datos en estado NEEDS_REINIT, solo dentro de una ventana configurada. Desactivada de forma predeterminada.

Cuando una base de datos entra en NEEDS_REINIT:

Causa Dónde se ve
error de aplicación irrecuperable que se repite (infracción de PK, UNIQUE, FK), 3 veces seguidas réplica, alerta replication_unrecoverable_error
el GUID de la base de datos maestra ha cambiado (restauración, sustitución del archivo) réplica, alerta replication_guid_mismatch
el archivo del maestro ya no contiene los segmentos que necesita la réplica maestro
la réplica ha borrado la copia antigua para la inicialización y aún no hay copia nueva (desde HQbird 2027.2.24) réplica, alerta replica_removed_for_reinit; maestro

Para activarla: Configuración → RCM (o rcm.json, la sección 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" } }
  }
}
  • Ventana: por base de datos → por nodo → global. "always": en cualquier momento.
  • Las ventanas se calculan por el reloj del host de RCM.
  • max_concurrent: cuántas inicializaciones (manuales y automáticas) pueden estar en curso en el clúster para que RCM inicie otra automática.
  • La inicialización automática pasa por las mismas comprobaciones de espacio y de GUID que la inicialización manual. El autor del comando es system:autoreinit.
  • remove_old_replica_when_short (desde HQbird 2027.2.24, la fila Eliminar la réplica antigua cuando falte espacio): desactivada de forma predeterminada. Si está activada, la inicialización automática envía la marca Eliminar la réplica antigua (4.4). RCM la envía solo si la propia réplica está en NEEDS_REINIT o la causa NEEDS_REINIT del maestro la nombra. Para una réplica que está IN_SYNC o LAGGING la marca no se envía nunca. Si el nodo es una versión anterior, RCM inicia la misma inicialización sin la marca.
  • Después del cambio, reinicie RCM.

Posponer en la tarjeta del maestro desactiva la inicialización automática de una sola base de datos durante 1 hora, 4 horas, 24 horas o hasta que se cancele. La inicialización manual sigue disponible.

5.9. Errores

Error Causa Qué hacer
insufficient disk space on master / on replica, 507 no hay espacio suficiente. Durante la reinicialización la copia antigua ocupa espacio hasta el final capítulo 4.4; en la réplica (desde HQbird 2027.2.24), la casilla Eliminar la réplica antigua (5.1)
node_too_old (desde HQbird 2027.2.24) la casilla Eliminar la réplica antigua está marcada, pero el nodo maestro o el réplica es una versión antigua actualice el nodo como dice el texto del error o ejecute sin la casilla
engine_busy, reclaim_in_progress (desde HQbird 2027.2.24) la réplica no puede borrar la copia antigua ahora: Firebird o esta base de datos está ocupada inténtelo más tarde (5.6)
replica_removed_for_reinit, par NEEDS_REINIT (desde HQbird 2027.2.24) la réplica borró la copia antigua, pero la inicialización no terminó inicie la inicialización otra vez (4.4)
publication_off (desde HQbird 2027.2.24) la publicación del maestro está desactivada o no contiene tablas con clave Sincronizar la publicación e inicializar (5.1)
long_transactions, «La reinicialización suave espera transacciones largas» hay transacciones de escritura largas abiertas 5.4
long_transactions, «el archivo del maestro aún no contiene un solo segmento» primera inicialización bajo carga Estándar (5.4)
reinit_pre_publication_transactions transacciones iniciadas antes de que se activara la publicación reconecte las aplicaciones, inténtelo de nuevo
duplicate_guid dos bases de datos maestras con el mismo GUID quite la copia; si se omitió el paso NEW GUID al promover a maestro, -force (capítulo 8.4)
license_paused el fbagent del maestro no tiene licencia capítulo 2.8
409 orphaned la base de datos está fuera del análisis del maestro capítulo 3.8
incompatible_engine versiones mayores de Firebird distintas capítulo 4.3
target_not_replica hay una base de datos de trabajo en el lugar de la réplica (se convirtió en normal) véase más abajo
target_other_replica (desde HQbird 2027.2.24) hay una copia de otra base de datos de este nodo en el lugar de la réplica véase más abajo
restart_not_allowed el Firebird de la réplica también sirve bases de datos maestras 5.6, la casilla «Permitir … que detenga Firebird»
fbagent_required fbagent no está instalado en la réplica capítulo 1
nbackup backup lock already active hay una copia de seguridad nbackup en curso 5.7
… -L did not finish in 2m0s and was stopped nbackup -L en el maestro no terminó en 2 minutos, así que el nodo lo detuvo inténtelo de nuevo; si el error se repite, compruebe el Firebird del maestro (firebird.log)
reinit already in progress for this database la inicialización de esta base de datos ya está en curso espere a que termine

target_not_replica. Hay una base de datos de trabajo en el lugar de la copia: se convirtió en normal (existe el archivo <database>.hqcluster-normal.json) o no está en modo réplica. El nodo no sobrescribe una base de datos de trabajo. Si hay que sustituirla, una petición a la API del nodo con overwrite_non_replica: true (no hay botón para esto en RCM) sustituirá el archivo y conservará el antiguo como <database>.pre-reinit-<hora UTC>.fdb.

target_other_replica (desde HQbird 2027.2.24). La réplica coloca la copia en <databases.root>/<id del maestro>/<ruta de la base de datos>. El id del maestro solo es único dentro de su propio clúster, así que dos bases de datos pueden acabar con la misma ruta. El nodo réplica no sobrescribe una copia que pertenece a otra de sus bases de datos: el error nombra esa base de datos y su maestro. El nodo también reconoce una copia cuya ruta está registrada de otra forma (un enlace simbólico o un junction en la ruta, un nombre corto de carpeta de Windows). overwrite_non_replica no elimina este error. Mueva una de las copias a otra carpeta o quite esa base de datos de la réplica, y después inicie la inicialización otra vez. El nodo solo ve sus propias bases de datos: dos nodos réplica en el mismo host deben tener carpetas de réplica distintas (databases.root).

5.10. Cómo comprobar el resultado

  1. Bases de datos: el par maestro-réplica del grupo está Correcto, estado IN_SYNC.

  2. Verificar en la tarjeta del maestro: los nodos cuentan las filas de las tablas de la lista de tablas de la base de datos (capítulo 3.1) en el maestro y en la réplica y las comparan. Compruebe en un momento tranquilo: con escrituras activas los números pueden diferir.

    Con HQbird 2027.2.24 la página de resultado nombra la lista de cada lado (por ejemplo, «la lista propia de esta base de datos» o «tablas de la publicación (lista no definida)»). RCM cuenta la réplica usando la lista del maestro. Una tabla ausente de ambas bases de datos se muestra como «no está en la base de datos» y no se cuenta como error. Si no se comparó ninguna tabla, el resultado es «No hay tablas que comparar», no una discrepancia. Si la comparación no terminó en el tiempo asignado, el resultado es «No comparado (límite de tiempo)», que tampoco es una discrepancia.

Resultado de la verificación
Resultado de la verificación
Command
hqbirdrcm verifydata -master node-a -master-db <db_id> -replica node-b -replica-db <db_id>
  1. Comprobación periódica (opcional): la página Comprobación de datos, Activar para todos los nodos. Con HQbird 2027.2.24 el nodo aplica los ajustes de inmediato, no hace falta reiniciar el servicio del nodo: después de Guardar RCM escribe «Guardado y ya en vigor». El nodo 2027.5.7 necesita que se reinicie el servicio hqclusternode, y RCM 2027.2.24 lo dice. Los nodos comparan ellos mismos el número de filas cuando el maestro y la réplica están en el mismo segmento. Una discrepancia eleva la alerta data_mismatch; entonces ejecute Verificar.

Una tabla que el operador ha quitado de la publicación se muestra como «no publicada», no como una discrepancia.

6. Configuración de la publicación

La publicación indica al Firebird maestro de qué tablas escribir los cambios en los segmentos. Sin ella, la réplica no recibe nada.

6.1. Qué es la publicación

En Firebird 4 y 5, las tablas que se replican las define la publicación RDB$DEFAULT:

  • Publicación activada: en RDB$PUBLICATIONS tiene RDB$ACTIVE_FLAG = 1 (el comando ALTER DATABASE ENABLE PUBLICATION).
  • Tablas publicadas: la lista en RDB$PUBLICATION_TABLES.

Firebird escribe cambios en los segmentos solo para las tablas publicadas y solo cuando la publicación está activada. Registrar la base de datos (capítulo 3) no activa la publicación. La activa Sincronizar la publicación (6.2).

El nodo maestro comprueba la publicación cada hora (limits.publication_check_interval_sec, 3600 de forma predeterminada). Si está desactivada, el nodo la comprueba cada 2 minutos.

En la página Bases de datos, la base de datos maestra tiene un icono:

Icono Significado
publicación activada publicación activada
publicación desactivada Firebird no escribe nada en los segmentos, las réplicas no reciben cambios
publicación desconocida el nodo no pudo leer el estado

El filtro Publicación desactivada muestra las bases de datos con la publicación desactivada o desconocida.

Si una base de datos con la publicación desactivada ya tiene una réplica, el maestro eleva la alerta master_publication_off.

Con HQbird 2027.2.24, el maestro eleva esta alerta también cuando rechazó inicializar una base de datos con el error publication_off (capítulo 5.1): la publicación está desactivada o no contiene ninguna tabla con clave. El nivel de la alerta:

  • advertencia: la base de datos aún no tiene réplica: la inicialización espera la publicación;
  • grave: la base de datos ya tiene una réplica;
  • información: el operador desactivó la publicación.

La alerta se borra cuando se corrige la publicación o ha empezado otra inicialización.

6.2. Sincronizar la publicación

Fila del maestro: publicación desactivada
Fila del maestro: publicación desactivada

Dónde pulsar:

  • en la fila de la base de datos maestra de la página Bases de datos. Cuando la publicación está desactivada, el botón está junto al icono;
  • en la página de la base de datos;
  • para varias bases de datos: marque las filas, en la lista Acción seleccione Sincronizar la publicación. RCM enviará un comando aparte para cada base de datos.
Confirmación de la sincronización de la publicación
Confirmación de la sincronización de la publicación

Qué hace el nodo (una sola transacción):

  1. Activa la publicación. Si el operador la desactivó él mismo (6.4), no la activa.
  2. Añade a la publicación todas las tablas con clave que aún no están.
  3. Quita de la publicación las tablas sin clave y las tablas que el operador excluyó (6.3).
  4. Desactiva la adición automática de tablas nuevas (EXCLUDE ALL FROM PUBLICATION, y después añade las tablas necesarias). Solo el nodo define la composición de la publicación.
Fila del maestro después de la sincronización: publicación activada
Fila del maestro después de la sincronización: publicación activada

Una tabla con clave es una tabla permanente de usuario que tiene una clave primaria o un índice único activo. Las tablas de sistema y las temporales no se publican.

La sincronización también quita de la publicación las tablas sin clave que el DBA añadió a mano.

Si la composición ya es correcta, el nodo no cambia nada.

Cuándo rechaza el nodo:

Código Motivo
no_publications HQbird 2.5/3.0 (6.6)
not_master el nodo no es el maestro
reinit_in_progress la inicialización de esta base de datos está en curso
orphaned, database_failed, file_missing la base de datos está fuera del análisis, en error, o no tiene archivo

Todas las bases de datos del nodo a la vez, solo desde la línea de comandos. En la página Comandos el resultado se muestra por base de datos: hecho, omitida o error. Se omiten las bases de datos en estado FAILED o SEEDING y las bases de datos sin archivo.

Lo mismo desde la línea de comandos

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

El comando espera hasta 5 minutos e imprime una línea por cada base de datos. Si hay error, el código de salida es 1. -nowait: no esperar el resultado.

6.3. Tablas de la publicación

La página «Tablas de la publicación»
La página «Tablas de la publicación»

Abra Tablas de la publicación en la fila de la base de datos maestra.

La página muestra:

  • el estado de la publicación (activada/desactivada, desactivada por el operador) y los contadores;
  • cada tabla: nombre, clave y estado.
Estado Significado
publicada los cambios van a los segmentos
aún no publicada una tabla con clave, se añadirá en la sincronización
excluida el operador la quitó de la publicación
sin clave no se puede publicar

En la columna de la clave: la clave primaria o, si no la hay, el índice único con el menor número de campos.

Por qué no se puede publicar una tabla sin clave. La réplica busca la fila para UPDATE y DELETE por la clave. Sin clave no encontrará la fila. Añada una clave primaria o un índice único, y después sincronice la publicación.

Excluir de la publicación / Devolver a la publicación:

  1. Marque las tablas.
  2. Pulse Excluir de la publicación o Devolver a la publicación.
  3. El nodo guarda la lista y sincroniza la publicación de inmediato.
Confirmación de «Excluir de la publicación»
Confirmación de «Excluir de la publicación»

La lista de tablas excluidas se guarda en el nodo maestro. La sincronización no la cambia. Cuando una réplica se promueve a maestro (capítulo 8), la lista pasa al maestro nuevo.

Comprobar (capítulo 5.10) muestra una tabla excluida como «no publicada», no como una discrepancia.

6.4. Activar y desactivar la publicación

En la página Tablas de la publicación: Desactivar la publicación / Activar la publicación.

  • Desactivar es una elección del operador. La sincronización no vuelve a activar la publicación.
  • Los cambios hechos mientras la publicación está desactivada (o mientras una tabla está excluida) no se envían a la réplica, ni siquiera después de activarla.
  • Después de activar, pulse Comprobar (capítulo 5.10). Si los datos divergen, reinicialice la réplica (capítulo 5).

6.5. Una tabla nueva

Una tabla nueva no entra en la publicación por sí sola: el nodo desactiva la adición automática.

Después del DDL:

  1. Cree una clave primaria o un índice único en la tabla.
  2. Pulse Sincronizar la publicación.
  3. Pida a las aplicaciones que se reconecten si hace falta reinicializar. Firebird no escribe en los segmentos las transacciones que empezaron antes de que se activara la publicación; COMMIT RETAINING mantiene abierta esa transacción. La inicialización espera esas transacciones y después falla con reinit_pre_publication_transactions (capítulo 5.4).
Una tabla nueva en el estado «aún no publicada»
Una tabla nueva en el estado «aún no publicada»

Las filas escritas en la tabla nueva antes de la sincronización no llegarán a la réplica. Si las hay, compruebe los datos y, si hace falta, reinicialice la réplica.

6.6. HQbird 2.5 y 3.0

HQbird 2.5 y 3.0 no tienen publicaciones. Firebird escribe segmentos si el archivo del complemento replconf contiene un bloque maestro. Los botones de publicación de esos nodos están ocultos, y la API responde con no_publications.

El conjunto de tablas lo definen los parámetros del motor:

Parámetro Significado
include_filter qué tablas replicar: nombres o patrones separados por comas; vacío: todas
exclude_filter qué tablas no replicar

Los parámetros se cambian en Configuración → Parámetros de replicación (capítulo 7.1). La página Tablas de la publicación los muestra en solo lectura, con un enlace Cambiar en la configuración del motor. Firebird lee los valores nuevos después de un reinicio.

Tablas de la publicación en HQbird 3.0: filtros del motor
Tablas de la publicación en HQbird 3.0: filtros del motor

El complemento replconf. El nodo escribe su propio archivo replconf.hqcluster.hqbird en la carpeta de Firebird. Firebird lo lee solo cuando replconf.properties apunta a él. El complemento debe activarse una vez:

  1. Configuración → Nodos, el bloque Complemento de replicación (HQbird 2.5 / 3.0). El bloque muestra a dónde apunta replconf.properties y los problemas que el nodo encontró.

Complemento no activado: replconf.properties apunta al archivo de HQbird DataGuard
Complemento no activado: replconf.properties apunta al archivo de HQbird DataGuard
  1. Activar… La ventana enumera lo que hará el nodo: instalar el complemento, apuntar replconf.properties al archivo del nodo, migrar las entradas del archivo antiguo. Elija cuándo: Solo dentro de la ventana de reinicio del nodo o Ahora, ignorando la ventana de reinicio.

Ventana de activación del complemento
Ventana de activación del complemento
  1. Después del reinicio de Firebird, el campo Activado muestra «sí: el motor lee el archivo del nodo».

Complemento activado
Complemento activado

La activación reinicia Firebird y afecta a todas las bases de datos de este Firebird. Hágalo en un periodo tranquilo.

7. Otras opciones de replicación

7.1. Parámetros de replicación

Configuración → Parámetros de replicación, formulario del asistente
Configuración → Parámetros de replicación, formulario del asistente

La página Configuración → Parámetros de replicación cambia las claves de replication.conf para las bases de datos seleccionadas o para el nodo en conjunto.

  1. Añadir maestro y réplicas: seleccione las bases de datos. RCM las agrupa por versión de Firebird y rol: un formulario aparte para los maestros y para las réplicas.

  2. Para cada parámetro, elija una acción:

    Acción Qué hace
    sin cambios el valor no se cambia
    establecer valor un valor nuevo
    restablecer (al nivel superior) quitar el valor propio, tomar el valor del nivel de arriba
    no escribir (valor de Firebird) la clave no se escribe, se aplica el valor de Firebird
  3. Elija dónde aplicarlo: A las bases de datos seleccionadas o Como valor predeterminado de sus nodos.

  4. Vista previa: los nodos comprueban los valores sin cambiar nada.

Vista previa de los cambios
Vista previa de los cambios
  1. Aplicar. RCM envía el comando a cada nodo.

De dónde viene el valor (la columna Actual):

Origen Valor
esta base de datos definido para la base de datos
valor del nodo definido como predeterminado del nodo
valor integrado del nodo el valor del nodo que viene del código
valor de Firebird la clave no se escribe
del archivo (aún no definido aquí) el valor de replication.conf, RCM aún no lo ha cambiado
definido por el nodo solo lectura (rutas, prefijos)

Un nodo que no responde muestra sus bases de datos como no disponibles para la selección. Los cambios exigen fbagent (si no, fbagent_required).

Quién reinicia Firebird (Firebird lee replication.conf solo al arrancar):

Nodo Quién
maestro usted lo reinicia: el maestro nunca reinicia Firebird él mismo
réplica con firebird.auto_restart: never usted
réplica cuyo Firebird también sirve las bases de datos del maestro usted
las demás réplicas el nodo lo reinicia en su propia ventana de reinicio

Para un reinicio manual, la página tiene un botón Reiniciar Firebird.

7.2. Parámetros principales

Maestro, Firebird 4/5:

Parámetro Etiqueta en RCM Valor del nodo Firebird Consejo
journal_archive_timeout Tiempo de espera del archivo 10 s 60 s cuántos segundos espera Firebird antes de cerrar un segmento incompleto. Más bajo: la réplica está más cerca del maestro. Debe ser menor que limits.data_check_quiet_sec (90)
journal_segment_count Número de segmentos 64 8 cuántos segmentos pueden residir en .ReplLog. Debe ser mayor que limits.backlog_critical (48)
journal_segment_size Tamaño del segmento — 16 MB de 1 MB a 512 MB; el receptor no aceptará más de 512 MB
buffer_size — 1 MB

El nodo también escribe log_errors = true (no se puede cambiar) y disable_on_error = true.

Réplica, Firebird 4/5:

Parámetro Etiqueta en RCM Firebird Valor
apply_idle_timeout Pausa de inactividad 10 s pausa cuando no hay segmentos nuevos
apply_error_timeout Pausa después de un error de aplicación 60 s pausa antes de reintentar después de un error
verbose_logging nodo: true replication.log detallado; no se recomienda desactivarlo
skip_upddel_without_pk nodo: true omitir UPDATE/DELETE en tablas sin clave

Solo Firebird 5: include_filter, exclude_filter, cascade_replication.

HQbird 2.5/3.0: claves log_* con el mismo significado: log_archive_timeout, log_segment_count, log_segment_size (no menor que 2 × buffer_size). La clave alert_command solo se define en node.json.

En el formulario de RCM hay una pista para cada parámetro.

7.3. Almacenamiento del archivo

El archivo <database>.LogArch del maestro se limpia por etapas:

  1. Segmentos que todas las réplicas han aplicado y que son más antiguos que retention_days.
  2. Si el espacio libre es menor que free_space_floor_gb, segmentos aplicados más recientes que el periodo de retención. Alerta disk_serious_cleanup.
  3. Si el espacio sigue siendo bajo, segmentos no aplicados, empezando por los más antiguos. La réplica recibe NEEDS_REINIT, alerta replication_paused_reinit_scheduled.
Parámetro (Configuración → Nodos, Almacenamiento y archivos) Predeterminado
limits.retention_days: Retención del archivo, días 2
limits.retention_min_kept_segments: Conservar siempre los últimos segmentos 0 (desactivado)
limits.free_space_floor_gb: Espacio libre mínimo 1 GB
Configuración → Nodos, «Almacenamiento y archivos»
Configuración → Nodos, «Almacenamiento y archivos»

Limpiar el archivo a mano:

Command
hqbirdrcm cleanuparchive -node node-a              # stages for all databases on the node
hqbirdrcm cleanuparchive -node node-a -db <db_id>  # a single database

-orphaned (solo junto con -db) borra todos los segmentos de la base de datos en estado ORPHANED (capítulo 3.8). Para cualquier otra base de datos el nodo responderá not_orphaned. Nunca ejecute -orphaned sobre el donante de la promoción (capítulo 8.5).

7.4. Transferencia: compresión, velocidad, ventanas

La compresión se define por par: Configuración → Nodos → Pares, columna compress.

Valor Significado
vacío o none sin compresión (predeterminado)
zstd compresión zstd

El cambio surte efecto de inmediato. La compresión es útil en una red lenta.

Velocidad de transferencia de segmentos (Configuración → Nodos, Transferencia y reinicialización):

Parámetro Predeterminado Cuándo surte efecto
limits.channel_a_mbps: Velocidad de transferencia de segmentos 50 MB/s de inmediato
limits.channel_a_burst_mbps: Ráfaga de transferencia de segmentos 200 MB de inmediato

La unidad es el mebibyte (MiB), aunque el nombre diga «mbps». La ráfaga no puede ser menor que la velocidad.

Configuración → Nodos, «Transferencia y reinicialización»
Configuración → Nodos, «Transferencia y reinicialización»

Ventanas de tiempo (Ventanas de tiempo):

Parámetro Predeterminado Cuándo surte efecto A qué afecta
windows.restart_window: Ventana de reinicio de Firebird maestro 22:00-05:00, réplica always de inmediato cuándo puede el nodo réplica reiniciar Firebird
windows.transfer_window: Ventana de transferencia 23:00-05:00 después del reinicio del nodo velocidad plena de inicialización (capítulo 5.5)

La etiqueta junto a cada campo muestra cuándo surte efecto el cambio: de inmediato o reinicio del nodo.

Configuración → Nodos, «Ventanas de tiempo»
Configuración → Nodos, «Ventanas de tiempo»

7.5. Verificación de datos

  • Verificar: una comparación puntual del número de filas en el maestro y en la réplica (capítulo 5.10).
  • Verificación de datos: una comparación periódica (capítulo 5.10). El nodo hace la comparación cuando el maestro y la réplica están en el mismo segmento.
  • Con HQbird 2027.2.24, los ajustes de verificación surten efecto de inmediato después de Guardar; no hace falta reiniciar el servicio del nodo. RCM muestra «Guardado y ya en vigor». Después de activarla, la primera verificación se ejecuta tras un intervalo. Después de desactivarla, una verificación en curso se interrumpe y no escribe nada. El intervalo nuevo se cuenta desde el final de la última verificación. Conservar, días, Límite de consulta, Silencio y Generador de progreso surten efecto desde la siguiente verificación.
  • El nodo 2027.5.7 lee estos ajustes solo al arrancar: después de Guardar, reinicie el servicio hqclusternode de ese nodo. RCM 2027.2.24 muestra «Guardado, pero aún no en vigor» e indica el motivo.
  • Qué tablas comparar lo define la lista de tablas de la base de datos (capítulo 3.1). Con HQbird 2027.2.24, cada base de datos puede tener su propia lista: el campo en el registro o el bloque Tablas de seguimiento de la sincronización en la página de la base de datos del maestro (capítulo 3.3). La página Verificación de datos muestra qué lista se usó, y el número de tablas «no están en la base de datos». En 2027.5.7 la lista es por nodo (sync_tables).
  • Las tablas excluidas de la publicación se muestran como «no publicada» (capítulo 6.3).
Página de verificación de datos
Página de verificación de datos

7.6. Alertas

Página de alertas
Página de alertas

La página Alertas. Acciones:

  • Confirmar: la alerta sigue visible pero queda marcada como confirmada;
  • Silenciar durante 60 min: ocultar durante una hora;
  • Eliminar / Eliminar todas con este código: RCM pasa el borrado al nodo que elevó la alerta. Si la causa permanece, la alerta volverá a aparecer.
Command
hqbirdrcm clearalerts -code backlog_warn   # also -id, -acked, -all

A partir de HQbird 2027.2.33, RCM envía alertas a Telegram, a un webhook (Slack, Teams, JSON) y por correo electrónico. Los canales se configuran en la sección notify.channels del archivo rcm.json. El bloque Canales de notificación de la página Alertas muestra los canales y envía un mensaje de prueba. RCM informa de problemas de nivel warn y superiores: ha aparecido un problema, se ha vuelto más grave o se ha borrado. Sin canales, RCM no envía nada. Las versiones anteriores no envían: vigile la página Alertas o sondee la API de RCM.

Códigos principales:

Código Significado
backlog_warn / backlog_critical 32 / 48 segmentos sin archivar en .ReplLog
disk_serious_cleanup el archivo se está limpiando en la etapa 2 (7.3)
replication_paused_reinit_scheduled segmentos no aplicados borrados, hace falta inicialización
shipping_paused el envío al par está suspendido (7.7)
apply_error, replication_stopped, replication_unrecoverable_error la réplica no puede aplicar un segmento
replication_guid_mismatch el GUID de la base de datos maestra ha cambiado
segment_missing, segment_rejected, sequence_gap problemas con la secuencia de segmentos
firebird_down, firebird_log_error Firebird no está en ejecución o registra errores
firebird_not_answering a partir de HQbird 2027.2.30: Firebird no ha respondido a una conexión de base de datos durante un minuto (cuelgue). Esto incluye también una conexión que no llegó a establecerse por un tiempo de espera; firebird_down es solo un rechazo de conexión
master_publication_off la publicación está desactivada (capítulo 6); a partir de HQbird 2027.2.24 y después de un fallo publication_off (capítulo 6.1)
replica_removed_for_reinit a partir de HQbird 2027.2.24: la réplica ha borrado la copia antigua para la inicialización, y aún no hay copia nueva (capítulo 4.4)
orphaned_database base de datos fuera del análisis (capítulo 3.8)
restart_required_after_reinit el Firebird de la réplica necesita un reinicio (capítulo 5.6)
data_mismatch la comprobación periódica encontró una discrepancia
license_paused fbagent no tiene licencia (capítulo 2.8)

7.7. Pausar el envío

En la página Bases de datos, en la fila del maestro: Pausar el envío / Reanudar el envío. Para varias bases de datos, mediante la lista Acción.

Command
hqbirdrcm pauseshipping  -node node-a -db <db_id>
hqbirdrcm resumeshipping -node node-a -db <db_id>
Confirmación de pausar el envío
Confirmación de pausar el envío
Fila del maestro durante una pausa
Fila del maestro durante una pausa
  • La pausa sigue en vigor hasta Reanudar el envío o hasta la inicialización.
  • El Firebird maestro sigue escribiendo segmentos. El archivo .LogArch crece: mientras la réplica está detenida, la etapa 1 (7.3) no borra sus segmentos.
  • Una pausa larga puede llegar a la etapa 3 y a NEEDS_REINIT. Vigile el espacio.
  • El botón no está si la base de datos no tiene réplica o la publicación está desactivada. El icono Pausa: sin licencia significa una pausa relacionada con la licencia (capítulo 2.8); solo la quita una licencia.

7.8. Registros

Registro Dónde
Nodo <carpeta de instalación>/logs/node-YYYYMMDD.jsonl (/opt/hqclusternode o C:\hqclusternode), 32 MB cada uno, 20 archivos
replication.log y firebird.log de Firebird rutas en node.json: firebird.replication_log, firebird.firebird_log
RCM Linux: journalctl -u hqbirdrcm
Auditoría de RCM rcm-data/audit.jsonl

Registro remoto del nodo: la página Registros: seleccione un nodo y una fuente (replication.log, firebird.log, agente del nodo).

Página de registros
Página de registros
Command
hqbirdrcm getlogs -node node-b -source replication -tail 200

8. Cómo pasar una réplica a una base de datos normal

Hay dos caminos:

Camino Cuándo Qué se obtiene
Pasar a normal, 8.1 necesita una copia de trabajo aparte: informes, pruebas, un fallo sin un maestro nuevo una base de datos normal fuera de la replicación
Promover a maestro, 8.3 la réplica debe convertirse en el maestro nuevo una base de datos gestionada por un nodo compañero con el rol de maestro

Ninguno de los dos caminos se puede deshacer desde la interfaz.

8.1. Hacer normal

Lista «Acción» de la réplica: el elemento «Hacer normal»
Lista «Acción» de la réplica: el elemento «Hacer normal»
  1. Bases de datos, lado de la réplica: marque las filas de la réplica.

  2. En la lista Acción, seleccione Hacer normal y confirme. No hay un botón aparte en la fila. Tampoco hay un comando de línea de comandos.

Confirmación de «Hacer normal»
Confirmación de «Hacer normal»
3. El nodo réplica: - ejecuta `gfix -replica none` (HQbird 2.5/3.0: `gfix -replica {}`). Si la base de datos está ocupada aplicando segmentos, el nodo la pone en apagado `single` durante unos segundos (`gfix -shut single -force 0`), quita el modo réplica y la devuelve con `gfix -online normal`. **Se cortan todas las conexiones a esta base de datos**; - escribe el archivo marcador `.hqcluster-normal.json` (hora, autor, db_id, GUID); - empieza a vaciar la cola `.Incoming` (8.2). 4. RCM muestra la base de datos en el grupo **No es una réplica (normal)**.
La página «Bases de datos» después de «Hacer normal»
La página «Bases de datos» después de «Hacer normal»

Después de esto, la base de datos está abierta para escritura.

Quite el bloque de la réplica de replication.conf. El nodo lo quita en el siguiente análisis, y Firebird lee el archivo al arrancar:

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

Hasta entonces, los errores «la base de datos no está en modo réplica» de esta base de datos no se elevan como alertas.

El archivo marcador protege la base de datos. La inicialización no sobrescribirá esa base de datos: se rechaza con target_not_replica (capítulo 5.9). Borrar solo el marcador no basta: el nodo también comprueba el modo réplica en la cabecera de la base de datos. La casilla Eliminar la réplica antigua (capítulo 4.4) tampoco borra esa base de datos.

Con HQbird 2027.2.24, mientras la réplica está borrando la copia antigua de esta base de datos para la inicialización, Hacer normal se rechaza con reclaim_in_progress: inténtelo más tarde.

Si la base de datos tiene que volver a ser una réplica, solo servirá una inicialización nueva con sobrescritura. Se hace mediante la API del nodo (overwrite_non_replica: true); no hay ese botón en RCM. El archivo antiguo se guarda como <database>.pre-reinit-<hora UTC>.fdb, y el marcador se borra.

8.2. Qué ocurre con los segmentos

  • Hasta que el nodo haya analizado las bases de datos, el maestro sigue enviando segmentos. Cada 30 segundos el nodo réplica borra los segmentos antiguos y conserva solo los últimos 100 (keep_segments).
  • Después del análisis, el registro de la base de datos en la réplica recibe el estado ORPHANED. El nodo réplica responde al maestro con unknown_database. El maestro deja de enviar segmentos a esta réplica, deja de conservar un archivo para ella y vuelve a comprobarla cada 10 minutos.
  • Las demás réplicas de esta base de datos no se ven afectadas.
  • El registro ORPHANED se puede borrar (capítulo 3.8): hqbirdrcm forgetdatabase. El propio archivo de la base de datos no se borra.

8.3. Promover a maestro

La réplica se convierte en el maestro nuevo. Su archivo se queda en su sitio, y el control pasa al nodo compañero.

Condiciones:

Condición Rechazo
la base de datos es una réplica bad_request
en el mismo host está en ejecución un nodo con el rol de maestro, el compañero (la misma etiqueta host en rcm.json, capítulo 2.1) no_companion
la promoción de esta base de datos no está ya en curso already_running
no hay una inicialización hacia esta base de datos ni desde su maestro reinit_running

RCM no crea el nodo compañero: instálelo de antemano (capítulo 1).

Cómo empezar:

  • en la fila de la réplica, Promover a maestro, o en la lista Acción;

  • desde la línea de comandos:

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

RCM pedirá confirmación y nombrará el nodo compañero.

Confirmación «¿Promover a maestro?»
Confirmación «¿Promover a maestro?»

Pasos (visibles en la fila de la réplica, nombres en inglés):

N.º Paso Qué hace
1 TURN TO NORMAL como en 8.1; se omite si la base de datos ya es normal
2 NEW GUID un GUID nuevo de la base de datos en su sitio (8.4)
3 EXCLUDE ON DONOR el nodo réplica (donante) excluye el archivo de su análisis (exclude_paths)
4 ENROLL ON el nodo compañero registra el archivo como base de datos maestra
5 PUBLICATION SYNC sincronización de la publicación; la lista de tablas excluidas se traslada desde el maestro antiguo (capítulo 6.3)
6 RESTART DONOR FIREBIRD reinicio del Firebird del donante, sin esperar una ventana
7 RESTART FIREBIRD reinicio del Firebird del compañero, sin esperar una ventana
8 FINALIZE la fila del donante pasa a ser Réplica fantasma; el maestro antiguo puede pasar a Maestro degradado (8.5)
Pasos de la promoción en la fila de la réplica
Pasos de la promoción en la fila de la réplica

En HQbird 2.5 y 3.0 no hay publicaciones: el paso PUBLICATION SYNC termina con el texto «este motor no tiene publicación».

Pasos de la promoción en HQbird 3.0 (Windows)
Pasos de la promoción en HQbird 3.0 (Windows)

Si el donante y el compañero usan el mismo Firebird, ese Firebird se reinicia: se cortan las conexiones a todas sus bases de datos.

Si un paso falla, el trabajo recibe failed con el texto del error. Corrija la causa y pulse Promover a maestro otra vez: los pasos completados no se repiten. Si RCM se reinicia durante la promoción, el trabajo también pasará a failed: compruebe el estado de los nodos e inténtelo de nuevo.

Licencia. Si el fbagent del host del maestro no tiene licencia, el maestro ha pausado el envío. La promoción sigue siendo posible. RCM le avisará: se perderán los cambios hechos después de que empezó la pausa.

8.4. GUID nuevo

Después de la promoción, la base de datos debe recibir su propio GUID. Si no, el maestro nuevo escribe segmentos bajo el GUID del maestro antiguo, y sus réplicas se rechazan con duplicate_guid.

El paso NEW GUID en el nodo:

  1. gfix -shut single -force 0: se terminan todas las conexiones a la base de datos;
  2. nbackup -L, y después nbackup -F sin -SEQUENCE;
  3. borra <database>.delta;
  4. comprueba la cabecera: GUID nuevo, REPLICATION_SEQUENCE = 0;
  5. gfix -online normal.

Firebird no se reinicia. El método funciona en todas las versiones (2.5, 3.0, 4.0, 5.0).

Si el paso se interrumpió, el nodo emite la alerta newguid_interrupted. La base de datos puede quedar en apagado single. Repita Promover a maestro: el paso continuará.

El paso se omite (el texto empieza por skipped:) si el nodo donante es una versión antigua o el archivo ya tiene su propio GUID.

Después de un GUID nuevo, la cadena antigua de nbackup ya no sirve. Haga una copia nbackup nueva de nivel 0.

Si la base de datos se creó con ADD DIFFERENCE FILE, su .delta está en otro sitio: bórrelo a mano.

8.5. Después de la promoción

Registro del donante. En el nodo réplica la base de datos permanece ORPHANED, la ruta permanece en exclude_paths, y permanecen la carpeta .Incoming y la etiqueta. En RCM es la fila Réplica fantasma con los botones Abrir en el maestro nuevo y Borrar.

Fila del donante: «Réplica fantasma»
Fila del donante: «Réplica fantasma»
  • Para quitar la fila, pulse Borrar. Esto solo cambia RCM.
  • Para quitar el registro del donante del nodo réplica, ejecute forgetdatabase. El archivo y la carpeta .Incoming permanecen. HQbird 2027.2.30 y posterior no rechaza el comando (mailbox_active), porque la ruta del donante está en exclude_paths. Los nodos de versiones anteriores lo rechazan mientras están presentes el archivo y la carpeta .Incoming.
  • Nunca ejecute cleanuparchive -orphaned sobre el donante. El donante y el compañero comparten la misma carpeta <database>.LogArch. El comando borrará el archivo vivo del maestro nuevo.

Maestro antiguo.

  • Si el donante era su última réplica en funcionamiento, RCM pone el maestro antiguo en Maestro degradado y pausa el envío al donante («envío en pausa: … (promoción a maestro)»). No reanude el envío al donante: ya contiene una base de datos de trabajo. Para quitar este estado, inicialice la base de datos en otra réplica.

    Maestro antiguo: «Maestro degradado», envío en pausa
    Maestro antiguo: «Maestro degradado», envío en pausa
  • La inicialización desde el maestro antiguo hacia el nodo donante se rechazará (target_not_replica): ya contiene una base de datos de trabajo.
  • Si se omitió el paso NEW GUID, el maestro antiguo y el nuevo tienen el mismo GUID. En ese caso la inicialización desde el maestro antiguo exige -force (capítulo 5.9).
  • Después de una promoción manual, RCM no convierte el maestro antiguo en una réplica del maestro nuevo. Detenga las aplicaciones en el maestro antiguo y quite su base de datos de la gestión (capítulo 3.8). Para una base de datos descrita como servicio, esto lo hace Reincorporar (8.7).

Maestro nuevo. Configure una réplica para él: nodo réplica, pares (capítulo 2), publicación (capítulo 6), inicialización (capítulo 5).

Maestro nuevo: base de datos con un GUID nuevo, aún sin réplica
Maestro nuevo: base de datos con un GUID nuevo, aún sin réplica

8.6. Conmutación planificada: lista de comprobación

Este es el procedimiento de una conmutación manual. Para una base de datos descrita como servicio, RCM cambia el maestro él mismo (8.7). Una promoción manual no comprueba si las aplicaciones escriben en el maestro antiguo. Procedimiento:

  1. Por adelantado. En el host de la réplica está en ejecución un nodo compañero con el rol de maestro, y ambos nodos tienen la misma etiqueta host (capítulo 2.1). Un nodo para la réplica futura está listo para el maestro nuevo.
  2. Detenga las escrituras de las aplicaciones en la base de datos del maestro antiguo.
  3. Espere a que la réplica haya recibido y aplicado todo: Bases de datos → IN_SYNC, sin cola.
  4. Comprobar (capítulo 5.10): los números de filas coinciden.
  5. Promover a maestro (8.3). Espere el paso FINALIZE.
  6. Compruebe: la base de datos está en la lista de maestros del compañero, publicación activada.
  7. Pase las aplicaciones al maestro nuevo.
  8. Haga una copia nbackup de nivel 0 de la base de datos nueva (8.4).
  9. Borre el registro fantasma de la fila del donante (8.5).
  10. Conecte la réplica al maestro nuevo e inicialícela (capítulo 5).
  11. Maestro antiguo: quite la base de datos de la gestión o déjela como archivo (8.5).

8.7. Servicios: conmutación y conmutación por error en RCM

Con HQbird 2027.2.30, RCM traslada el maestro a otro host él mismo. Para ello, la base de datos se describe como un servicio: una base de datos lógica en varios hosts. En cada host del servicio hay un nodo maestro y un nodo réplica, y la ruta del archivo de la base de datos es la misma. El servicio se crea en la página Servicios (desde HQbird 2027.2.31) o con el comando hqbirdrcm services put -id <id> -file <file>.json.

Acción Qué hace Comandos
Conmutación traslado planificado del maestro sin pérdida de datos. Después el maestro antiguo se convierte automáticamente en una réplica del maestro nuevo hqbirdrcm switchover -service <id> -check, después hqbirdrcm switchover -service <id> -to <host>
Conmutación por error se ha perdido el host del maestro: RCM promueve la réplica. Los cambios más recientes del maestro pueden perderse hqbirdrcm failover -service <id> -check, después hqbirdrcm failover -service <id> -to <host> -accept-data-loss
Reincorporar después de una conmutación por error, devuelve el host antiguo como réplica del maestro nuevo hqbirdrcm rejoin -service <id>
Reanudar saca el servicio del estado failed hqbirdrcm resume -service <id> -check, después hqbirdrcm resume -service <id>

Las mismas acciones están en la página del servicio: los botones Conmutación…, Conmutación por error…, Reincorporar… y Reanudar….

  • La conmutación por error automática está desactivada de forma predeterminada. Se activa para cada servicio por separado: hqbirdrcm policy -service <id> -auto-failover on -max-data-loss 30. Exige enrutadores. RCM inicia una conmutación por error solo cuando el nodo maestro está en silencio, la mayoría de los enrutadores no puede ver el Firebird del maestro, y el retraso de la réplica no supera max_data_loss_sec.
  • Un enrutador (hqclusternode router, Linux) mantiene HAProxy en el maestro actual del servicio. Las aplicaciones se conectan a <host del enrutador>:<router_port> y no cambian la cadena de conexión cuando hay una conmutación.
  • Después de una conmutación por error, RCM aísla el maestro antiguo (rol fenced) en cuanto vuelve a responder. Vuelva a incorporarlo con el comando rejoin.