Installation and updates
Installation with no surprises
One installer per Firebird line. It finds Firebird, old HQbird and agents on the server, shows a plan and changes nothing until you say "Yes". After that, the agent updates itself, the console and Firebird on its own, with checks and rollback.
- 4 installers: Firebird 2.5 · 3.0 · 4.0 · 5.0
- 0 changes before you confirm the plan
- no internet needed everything in one file
- Windows and Linux wizard, silent mode, .run
- rollback if an installation or update fails
setup.exe · .run
What is in the kit
The installer is one file: hqbird2027-fb50-setup-<version>.exe for Windows or hqbird2027-fb50-linux-<version>.run for Linux. It contains everything the server needs. Nothing is downloaded.
Each installer installs one Firebird line. Pick the line your databases run on. The installation is done by the agent inside the kit: it checks the server, builds a plan and runs it.
| Component | What it does | Windows | Linux |
|---|---|---|---|
| Firebird, HQbird build | A new server or an in-place update. For a server that is already installed, one line is added to firebird.conf: MonitoringPlugin = fblwmon. For a new server, the installer also sets the port. databases.conf, the security DB and the SYSDBA password do not change. | service FirebirdServer… | /opt/firebird |
| fbagent agent | Backups, monitoring, maintenance, updates. | HQbirdFBAgent-fb50 | hqbirdfbagent-fb50, user firebird |
| HQbird Monitor | Web console for this server. Port = 20000 + Firebird port: for 3050 it is 23050. The port is chosen at installation and does not change later, even if you change the Firebird port. | HQbirdMonitor-fb50 | hqbirdmonitor-fb50 |
| Cluster components | The cluster programs are put on the server but are not turned on: RCM and the pairing window are off by default. RCM makes the server the center of a new cluster and opens ports 7443 and 7444. The pairing window opens port 7450–7459 for 24 hours: through it, the RCM of another server can invite this server. You can turn on both after installation too. | wizard page "Replication and cluster setup"; /RCM, /DISCOVERY | --rcm on, --cluster-pairing on |
| fbmcp MCP server | Access for AI clients to Firebird. By default, only from this server. | check box in the wizard or /NOFBMCP | --no-fbmcp |
| Firebird debug files | Symbols to analyze Firebird crashes. | — | yes, --no-debug turns it off |
- WindowsSupported: Windows 10 and 11, Windows Server 2016 and later, 64-bit. Administrator rights. The installer is signed by IBSurgeon Software: Windows shows the publisher in the rights prompt.
- Wizard or silent modeEvery wizard page is also available as a switch:
/VERYSILENT /YES /LOG=…. Good for scripts and for a hundred servers. - Wizard in 8 languagesEnglish, Portuguese (Brazil), German, Russian, Spanish, Polish, Turkish, Chinese Simplified. The default is the Windows language. Switch:
/LANG=en|pt_BR|de|ru|es|pl|tr|zh_CN. - Server nameThe wizard asks for the name of the new agent; HQCenter shows the server under this name. The default is the computer name. Silent mode:
/AGENTID=, on Linux--agent-id. An agent that is already installed keeps its name.
- Linuxx86_64, kernel 3.2 or later, systemd, root. Ubuntu, Debian, AlmaLinux, Rocky, RHEL, Oracle Linux, openSUSE, RED OS and others with apt, dnf, yum or zypper.
- Server without internetThe installer gets a few OS libraries (libtommath, ICU) from the repository. If there is no repository, it prints the exact commands and changes nothing.
The kit is checked twice. Before unpacking: the sha256 of the whole kit. Before Firebird and the agent are installed: the signature of each file. A damaged download stops the installation before any change to Firebird, the agent or the console.
fbagent --install-plan
Plan first, changes after
First, the installer only reads: services, the registry, Firebird and HQbird folders. Then it shows what it found and what it will do. Changes start after you say "Yes".
Select what is on the server and look at the plan. The texts are shortened and translated; the order and the decisions are the same as in the Firebird 5.0 installer.
- 1Server checkrights, bitness; on Linux also systemd and the kernel
- 2Kit checksha256 before unpacking; file signatures before installation
- 3Planwhat was found and what will be done
- 4Questionsserver name for HQCenter; stop Firebird? another version?
- 5InstallationFirebird, agent, console, services
- 6✓ Resultservices, console address, login
If something goes wrong
A refusal at the plan stage (port in use, folder not empty) changes nothing: the installer names the reason. In the wizard, you cannot leave a page while a value is wrong.
A failure during installation, before the agent service starts: services return to their previous state. Old HQbird, if it was stopped, starts again.
| Code | Meaning (Linux .run) |
|---|---|
| 0 | Done |
| 1 | Refused: server, switch or plan. Nothing changed |
| 2 | Installation failed, changes rolled back |
| 3 | Rollback incomplete: the result says what to check |
| 4 | Answer needed: no terminal and no --yes |
| 5 | Kit failed the check: download it again |
| 6 | No OS libraries and no repository |
| 7 | Firebird from distribution packages |
| Code | Meaning (Windows setup.exe) |
|---|---|
| 0 | Installed |
| 1 | Refused before installation: wrong switch or file, a newer version is installed, no administrator rights |
| 4 | The installer had a question, but there is no /YES switch |
| 7 | Server check or installation failed. The reason is in the log and in the result file |
| 10 | Installed, but the connection to HQCenter failed |
-p3050); new installations get -fb50.FBDataGuard → fbagent
Moving from HQbird 2024
The installer finds old HQbird and the Firebird it serves. This Firebird is updated in place, FBDataGuard jobs move to the agent, old services are stopped. Databases, configs and passwords stay.
- What does not change
databases.conforaliases.conf, the security DB, the SYSDBA password, databases, backups and old HQbird files. Infirebird.conf, only the lineMonitoringPlugin = fblwmonis added, if it is missing. - Copy of old FirebirdThe program folder of old Firebird is kept next to it as
<folder>.old_<time>. - Jobsgbak and nbackup backups, sweep, index statistics. The import runs once and goes through the check of the new config; the old config is kept.
- Old backupsThe agent takes backups from the FBDataGuard journals into its own records. Retention rules and restore see them the same way as new ones. The names of nbackup levels stay the same.
- Job namesThe job name ends with the database name from FBDataGuard, for example "Verified backup - MANUAL". Group jobs repeat the tree of the source folders.
- Old services: three optionsAutomatic (recommended): disable them when every Firebird served by FBDataGuard has an agent. Disable all:
/DISABLEHQBIRD. Leave as is:/NOHQBIRD. - You can go backThe state of each service before it was disabled is saved in
fbagent-hqbird-takeover.json. With this file, old HQbird can be turned on again. - LicenseThe old HQbird license does not carry over. A trial period runs until you get a new license or connect to HQCenter.
- Unclear pathIf the import cannot expand a substitution in an FBDataGuard path, it keeps it as is and leaves the job disabled. Fix the path and enable the job.
If jobs are imported but old services still run (for example, the server has two Firebird servers under FBDataGuard), the jobs arrive disabled. This way, one job does not run twice.
Ports · folders · services
Several Firebird servers on one machine
One agent per Firebird. A new instance is installed next to the others, on its own port, with its own agent and its own console. Installed instances do not change.
Add Firebird servers and see which names and ports the installer picks.
- Ports by lineThe first Firebird on the server gets 3050. The next one: 3052 for 2.5, 3053 for 3.0, 3054 for 4.0, 3055 for 5.0. The installer does not take a port that is in use.
- Second instance of the same lineNumber
-2in folder and service names. On Windows, this is the wizard option "Install another instance"; the port is the first free one in the line's range.
- Updates only within a line5.0.x → 5.0.y. Moving from 3.0 to 5.0 means a second instance next to the first; a person moves the databases with backup and restore.
- XNET on WindowsA Firebird that is not on port 3050 gets its own name
IpcName = FIREBIRD_<port>. Local XNET connections to the second server work. - One console per agentHQbird Monitor on 20000 + Firebird port: 23050, 23055. One login file for all instances on the server.
- Ports are fixedThe ports of the console and of the agent local API are written at installation. If you change the Firebird port later, they stay the same. The agent does not accept equal ports.
- Cluster: a slot for each agentEach agent on the server gets its own slot from 0 to 9: pairing port 7450 + slot, node ports 7051 + slot and 7061 + slot. So two agents of one server can join a cluster. The
--pairing-portswitch sets the slot explicitly.
Images · compose · ports
HQbird in Docker
There is a ready image for each Firebird line. Firebird, the agent and HQbird Monitor run in the container. The agent installs the cluster node inside the container itself when the server joins a cluster. It installs RCM only when this server is assigned as the cluster RCM.
| Image | Firebird | Firebird port | HQbird Monitor |
|---|---|---|---|
ghcr.io/ibsurgeon/hqbird2027-fb50 | 5.0 | 3050 | 23050 |
ghcr.io/ibsurgeon/hqbird2027-fb40 | 4.0 | 3050 | 23050 |
ghcr.io/ibsurgeon/hqbird2027-fb30 | 3.0 | 3050 | 23050 |
ghcr.io/ibsurgeon/hqbird2027-fb25 | 2.5 | 3050 | 23050 |
- First startCopy
compose.yamlfrom the kit, put the SYSDBA password into a secret file, remove the#from thesecrets:lines and rundocker compose up -d. The server is ready whendocker compose psshowshealthy. - Firebird portThe
HQBIRD_FB_PORTvariable, 3050 by default. HQbird Monitor listens on 20000 + this port. - Image signatureThe images are signed with the cosign tool. The public key for the check is not published yet.
- Several instances on one hostFirebird on 3050 + N, HQbird Monitor on 20000 + Firebird port, cluster node on 7051 + N. Only one instance on the host can have RCM.
- The same port number outside and insidePublish
3051:3051, not3051:3050. The agent and the cluster report the port that they see inside the container. - ClusterThe member address is the address of the Docker host. Publish the node port and, for RCM, ports 7443 and 7444.
Docker publishes ports past ufw. A ufw rule "only port 22" does not close the container ports. Publish the port on one host address or close it with an external firewall.
Cloud and Docker: settings, volumes, ports, updatesAgent · console · cluster · Firebird
Updates after installation
After it connects to HQCenter, the agent updates itself, HQbird Monitor, cluster components, fbmcp and Firebird on its own. A server without HQCenter also updates itself: the agent takes new versions from the IBSurgeon update server.
The agent sees a new version of itself in HQCenter within a minute. New versions of HQbird Monitor, fbmcp and Firebird: within an hour. Every update follows one pattern: check, save a rollback point, replace, make sure it works. If it does not work, restore the old one.
Updates without HQCenter
- What updates by itselfThe agent, HQbird Monitor and the MCP server. The check runs once every 6 hours.
- Firebird waits for a commandThe Firebird package is downloaded and waits. The administrator applies it: with the button on the Updates page or with the command
fbagent --firebird-update --apply. - You choose the modeThe install switch
--auto-update all|agent|off, on Windows/AUTOUPDATE=all|agent|off.agentis the default.allalso installs Firebird, in the update window.offchecks nothing.
- Updates page in HQbird MonitorShows where the agent takes versions from, the mode and the last answer of the server, the state of the Firebird, console and MCP server updates. The administrator changes the mode and applies the Firebird package.
- Source checkThe update server is checked against a pinned key. The vendor signature is always required.
- Cluster goes through the centerA cluster node and RCM do not update this way: HQCenter or RCM updates them.
Agent self-update
- Forward onlyThe agent does not install a version older than its own, even a mandatory one. The check runs before the first byte is downloaded. This way, a fake server cannot bring back an old vulnerable build. The exception is one old version allowed in the agent's own config (
allow_downgrade_to). - SignatureReleases are signed with an Ed25519 key; the public key is built into the agent. A wrong signature is always refused. The "signed only" mode is turned on in the agent's own config, not from the server.
- Manual rollbackNext to the agent there is a script
rollback_to_version_NNN: it restores the previous agent and config and blocks the failed version. The two latest rollback points are kept; older ones are deleted automatically. - Linux: root runs only its own copyThe agent runs as
firebird. The replacement is done by a verified copy in a folder that only root can write to.
Firebird update
Firebird is updated only within its line and only to a newer build. The agent can download and prepare the package at any time, but it stops Firebird only in the update window.
- 1Preparationdownload, signature, build not older than the engine
- 2Windowdaily window; a mandatory release also waits for the window
- 3Jobsgbak, nbackup or an SQL script is running: the attempt is postponed
- 4Replacementold engine files are set aside, configs stay
- 5CheckFirebird starts and answers on its port
- 6✓ or rollbackold files come back, the build is blocked
| What is updated | Protection | If it fails |
|---|---|---|
| fbagent agent | Signature, newer only, ready within 180 s and 45 s of running | Rollback, 30-minute pause; a second failure blocks the version |
| HQbird Monitor, cluster, fbmcp | Signature, newer than installed only | The previous version stays; the 2 latest copies are kept |
| Firebird | Window, wait for backups, check after start | Old engine comes back, the build goes to the block list |
A blocked version is not installed again, but the next version installs as usual. This way, the server does not loop through "update → roll back → update".
Folders · logs · uninstall
Where the files are and how to uninstall
Windows
C:\HQbird\ Firebird50\ Firebird 5.0, configs, security DB fbagent-fb50\ agent and HQbird Monitor agent_config.json agent config logs\ bak\ update\ logs, copies, update cache C:\HQbirdData\ agent and console working data config\access.properties console login C:\ProgramData\fbagent\ installation result and log
Linux
/opt/firebird/ Firebird 5.0 (second line: /opt/fb50) /opt/hqbird/ conf/access.properties console login, 0600 fbagent-fb50/ agent and HQ Monitor agent_config.json agent config logs/ bak/ update/ logs, copies, update cache /var/lib/hqmonitor/ console data /var/log/fbagent/install.log installation log, no passwords
- Uninstall does not touch your databasesYour databases and backups (
*.fdb,*.gdb,*.fbk,*.nbk) always stay. Removing data deletes only the security DB and the samples from the Firebird package. - Windows"Apps": removes the agent, the console, the RCM of this agent, firewall rules and the Firebird that this installer installed as new. If other agents use the RCM of this agent, the wizard asks "Remove this instance anyway?"; a silent uninstall needs
/FORCE. An updated Firebird stays. Configs and the security DB are removed only if you select "remove data".
- Linux
--uninstallremoves the agent and console services, the RCM of this agent, sudoers rules and the ports the installer opened in firewalld or ufw. The agent first leaves the cluster. If other agents use its RCM, you need the--forceswitch. Firebird stays.--remove-dataalso removes the config, logs and console data. - Old HQbirdUninstalling HQbird 2027 does not turn the old services back on: the administrator decides this using the state file.
sudo sh hqbird2027-fb50-linux-<version>.run --uninstall --agent-dir /opt/hqbird/fbagent-fb50-2