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
En el maestro, Firebird escribe los cambios de la base de datos en segmentos (archivos
del registro de replicación).
El nodo maestro envía los segmentos al nodo réplica por un canal protegido (mTLS).
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.
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.
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
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
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 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:
En un plazo de 10 minutos fbagent recibe el clúster de HQCenter Admin (después comprueba
si hay cambios cada 60 segundos).
El fbagent del host de RCM crea la autoridad de certificación (CA) del clúster y firma
los certificados de todos los nodos.
Cada fbagent escribe node.json o rcm.json para los miembros
de su clúster.
En la siguiente comprobación de productos (cada 3 minutos) fbagent instala e
inicia los servicios.
<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.jsonfbagent --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 hostsudo 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:
crea el clúster de este host (fbagent --cluster-init); el nombre del clúster es el
nombre del host;
instala e inicia RCM; la consola de RCM funciona por HTTPS en el puerto 7444;
crea el primer administrador de RCM rcmadmin con una contraseña aleatoria;
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-fb50sudo -u firebird ./fbagent --cluster-init <name> # RCM host; open ports 7443 and 7444 yourselfsudo -u firebird ./fbagent --cluster-pairing on # window for 24 hourssudo -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.
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.
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:).
Seleccione el Maestro (de forma predeterminada, el primer host) y pulse Vincular.
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
Lo mismo desde la línea de comandos:
Command
cd /opt/hqbirdrcm
exportRCM_USER=rcmadmin RCM_PASSWORD='<password>'./hqbirdrcm cluster link -hosts db1,db2,db3 -master db1
Qué ocurre a continuación:
RCM envía una invitación a cada host libre.
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.
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.
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.
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:
crea la CA del clúster y la CA del agente (en la carpeta de fbagent, clusterca/<name>/);
escribe el certificado de RCM, rcm.json y cluster-init.json en la carpeta de RCM;
instala RCM y registra el servicio hqbirdrcm. En Linux el servicio se ejecuta como
un usuario aparte hqbirdrcm;
cambia fbagent a RCM (cluster.source = rcm) y lo reinicia;
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
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
exportRCM_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.
En el host del nodo ejecute este comando como el usuario de fbagent:
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.
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):
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).
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ó
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:
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.
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.
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
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:
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
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 passwordde inmediato (el enlace Contraseña en la cabecera).
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>").
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.
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 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
exportRCM_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)
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
Introduzca un Id del nuevo clúster (letras latinas minúsculas, dígitos y -) y pulse
Crear.
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.
Añada enlaces (Enlaces de replicación) del maestro a la réplica.
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
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.
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.
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.
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 autofbagent --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:
En la tabla Agentes, pulse Añadir miembro en la fila del fbagent.
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.
En la sección Enlaces, pulse Añadir enlace del maestro a la réplica.
Pulse Validar: RCM mostrará errores y advertencias.
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
exportRCM_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
Configuración → RCM, la tabla Nodos conectados.
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).
Pulse Validar en la fila del nodo: RCM comprobará la conexión y los permisos.
Pulse Guardar. RCM escribirá rcm.json y guardará el archivo antiguo como
rcm.json.<hora UTC>.bak (los últimos 20).
Reinicie RCM. Hasta el reinicio sigue vigente la configuración antigua;
la página muestra qué campos esperan un reinicio.
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:
Configuración → Nodos, seleccione el nodo maestro.
En la sección Pares, pulse Añadir par: el node_id de la réplica, su url,
la compresión (zstd).
Pulse Guardar. RCM mostrará la lista de cambios y pedirá
confirmación. El cambio de peers surte efecto de inmediato.
Repita para el nodo réplica: su par es el 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 nodoAjustes 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:
Corrija firebird.password en el node.json de cada nodo de esta
instancia (maestro y réplica).
Corrija la contraseña en la configuración de fbagent y vuelva a cargarla (véase la
documentación de fbagent).
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
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
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:
la lista propia de la base de datos;
la lista compartida sync_tables del nodo;
las tablas de la publicación de la base de datos;
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.
Inscripción de bases de datos: formulario y vista previa
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.
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.
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).
Pulse Vista previa. El nodo mostrará todos los archivos que coinciden con la máscara de
inclusión. No cambia nada.
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.
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
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
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.
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
El nodo escribe las reglas en node.json.
El nodo analiza la carpeta (scansync).
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.
Antes de hacer un cambio, el nodo guarda una copia del archivo:
replication_YYYYMMDD_hhmmss_NNN.conf.
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»
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
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:
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.
Pide a fbagent que reinicie Firebird.
Espera a que Firebird responda en su puerto.
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).
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.
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
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:
añade los archivos a la lista de exclusión del nodo;
analiza la carpeta una vez: los bloques de la base de datos se quitan de replication.conf;
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:
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;
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:
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.
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:
segmentos aplicados por todas las réplicas más antiguos que retention_days;
segmentos aplicados más recientes (cuando falta espacio);
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
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
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:
Maestro: registre las bases de datos con detect_existing (capítulo 3.6).
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.
Confirme las filas. El nodo moverá los bloques a su propia zona de replication.conf.
Reinicie el Firebird de la réplica para que lea los bloques movidos.
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?»
Abra Bases de datos.
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.
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).
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
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»
Lo mismo desde la línea de comandos
Command
# one databasehqbirdrcm reinit -node node-a -db <db_id> -to node-b
# all master databaseshqbirdrcm 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.
-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
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).
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)
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
- 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)
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
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
Bases de datos: el par maestro-réplica del grupo está Correcto, estado
IN_SYNC.
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.
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
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
Qué hace el nodo (una sola transacción):
Activa la publicación. Si el operador la desactivó él mismo (6.4), no la activa.
Añade a la publicación todas las tablas con clave que aún no están.
Quita de la publicación las tablas sin clave y las tablas que el operador
excluyó (6.3).
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
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 databasehqbirdrcm 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»
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:
Marque las tablas.
Pulse Excluir de la publicación o Devolver a la publicación.
El nodo guarda la lista y sincroniza la publicación de inmediato.
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:
Cree una clave primaria o un índice único en la tabla.
Pulse Sincronizar la publicación.
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»
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
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:
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
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
Después del reinicio de Firebird, el campo Activado muestra «sí: el motor
lee el archivo del nodo».
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
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.
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.
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
Elija dónde aplicarlo: A las bases de datos seleccionadas o Como valor predeterminado
de sus nodos.
Vista previa: los nodos comprueban los valores sin cambiar nada.
Vista previa de los cambios
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:
Segmentos que todas las réplicas han aplicado y que son más antiguos que
retention_days.
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.
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»
Limpiar el archivo a mano:
Command
hqbirdrcm cleanuparchive -node node-a # stages for all databases on the nodehqbirdrcm 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).
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»
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»
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
7.6. 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
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.
Confirmación de pausar el envíoFila 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).
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»
Bases de datos, lado de la réplica: marque las filas de la réplica.
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»
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»
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:
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;
RCM pedirá confirmación y nombrará el nodo compañero.
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
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)
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:
gfix -shut single -force 0: se terminan todas las conexiones a la base de datos;
nbackup -L, y después nbackup -F sin -SEQUENCE;
borra <database>.delta;
comprueba la cabecera: GUID nuevo, REPLICATION_SEQUENCE = 0;
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»
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
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
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:
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.
Detenga las escrituras de las aplicaciones en la base de datos del maestro antiguo.
Espere a que la réplica haya recibido y aplicado todo: Bases de datos → IN_SYNC, sin cola.
Comprobar (capítulo 5.10): los números de filas coinciden.
Promover a maestro (8.3). Espere el paso FINALIZE.
Compruebe: la base de datos está en la lista de maestros del compañero, publicación activada.
Pase las aplicaciones al maestro nuevo.
Haga una copia nbackup de nivel 0 de la base de datos nueva (8.4).
Borre el registro fantasma de la fila del donante (8.5).
Conecte la réplica al maestro nuevo e inicialícela (capítulo 5).
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
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.
Este sitio utiliza cookies para mejorar tu experiencia y recordar preferencias.