This guide is for the administrator who removes HQbird 2027 from a server. It covers the Windows setup hqbird2027-fbNN-setup-<version>.exe and the Linux installer hqbird2027-fbNN-linux-<version>.run.

The examples show Firebird 5.0 (fb50). For Firebird 2.5, 3.0 and 4.0 use fb25, fb30, fb40 in the file, folder and service names. The installation is described in Windows installation and Linux setup.

HQbird 2024 is removed with the previous instructions.

1. Before you start

  1. Make a backup of every database (gbak or nbackup) and copy it to another disk or server. The removal does not delete database files, but a backup protects you from a mistake.
  2. Stop the applications that use the databases. On Windows the removal stops the Firebird that the setup installed.
  3. Cluster servers: if this server runs the cluster console RCM, delete the cluster in RCM and unlink its agents first (section 4).
  4. HQCenter: the removal does not delete the server record in your HQCenter. Remove the agent there after the removal, if you do not plan to install HQbird again.
  5. License: removal with the data deletes the license state of the agent. Keep your license file if you plan to install HQbird again.

2. What is removed and what stays

Item Windows Linux
HQbird agent (service or unit, programs) removed removed
HQbird Monitor (service or unit, firewall rule) removed removed
Firebird that HQbird 2027 installed new removed (service, program files, firewall rule) stays
Firebird that existed before and was only updated stays stays
Database files (*.fdb, *.gdb, *.fbk, *.nbk) always stay always stay
Agent configuration, logs, license state, HQbird Monitor data stay; removed with the data option stay; removed with --remove-data
Security database and *.conf files of Firebird stay; removed with the data option stay
Services of an older HQbird (2024 and earlier) that the update turned off stay off stay off

The data option on Windows removes only what an HQbird 2027 setup made. The data of an agent that was there before the first HQbird 2027 setup stay.

3. Windows

One entry in Apps & features = one Firebird line. The uninstaller of a line removes all instances of that line. Run it as an administrator.

3.1. Remove a whole line

  1. Open Settings → Apps → Apps & features (or Programs and Features).
  2. Select HQbird 2027 (Firebird 5.0) and click Uninstall.
  3. Confirm the removal.
  4. Answer the question about the data: No keeps the configuration and the security database, Yes removes them too.
  5. Wait for the message that HQbird was removed.

Repeat these steps for every Firebird line on the server (one entry per line).

3.2. Remove one instance

Use this when a line has several instances and you remove only one.

  1. Open Start → HQbird 2027 (Firebird 5.0) maintenance.
  2. Select Remove an instance and select the instance.
  3. Confirm, then answer the question about the data.

When you remove the last instance, HQbird 2027 of this line is removed.

3.3. Silent removal

Command
# programs and services; databases, configs and the security database stay
& 'C:\HQbird\setup\fb50\unins000.exe' /VERYSILENT
# the same, and the agent data, HQbird Monitor data, the security database and *.conf too
& 'C:\HQbird\setup\fb50\unins000.exe' /VERYSILENT /REMOVEDATA
# remove also an instance that runs the RCM of a cluster (section 4)
& 'C:\HQbird\setup\fb50\unins000.exe' /VERYSILENT /FORCE

The uninstaller folder is <HQbird folder>\setup\fb50. Lines installed by setups before 2027.2.8 have it in C:\Program Files\IBSurgeon\HQbird 2027\fb50. The exact folder is the InstallLocation value of the Apps entry:

Command
Get-ItemProperty 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*' | Where-Object DisplayName -like 'HQbird 2027*' | Select-Object DisplayName, InstallLocation, UninstallString

3.4. Check the result

Command
Get-Service | Where-Object Name -match 'HQbird|Firebird|hqbirdrcm|hqclusternode'
Test-Path 'HKLM:\SOFTWARE\IBSurgeon\HQbird2027\fb50'
Get-NetFirewallRule -DisplayName 'HQbird Monitor*', 'Firebird *' -ErrorAction SilentlyContinue

Expected: no HQbird services of this line, and False for the registry key. The uninstaller deletes the registry key only after a complete removal. If the key is still there, run the uninstaller again.

3.5. What remains on the disk

Folder Content Delete by hand?
C:\HQbird\Firebird50\ Database files, and without the data option the security database and *.conf After you moved the databases
C:\HQbird\fbagent-fb50\ Agent configuration and logs, when you kept the data Yes, if you do not need them
C:\HQbirdData\ Agent working data, HQbird Monitor data and sign-in file, when you kept the data Yes, if you do not need them
C:\HQbird\hqbirdrcm\ RCM data (goes only with the data option) Yes, after the cluster is gone
C:\ProgramData\fbagent\ install.log, result of the last setup run Yes
C:\ProgramData\HQbird\fbagent\ SYSDBA password file of a silent install Yes
<Firebird folder>.old_<time> Copy of the old Firebird program folder from an update Yes, when the update is confirmed

The fbmcp service is shared by all lines of the server. It stays while another line uses it, and it is removed with the last line.

4. Servers in a cluster

The agent that runs the RCM holds the cluster CA. When other agents use that RCM, the removal is refused and nothing is changed.

Recommended order:

  1. Delete the cluster in the RCM console and unlink its agents.
  2. Remove HQbird from the member servers.
  3. Remove HQbird from the server that runs the RCM.

To remove the RCM owner anyway:

  • Windows, dialog: the uninstaller asks “Remove this instance anyway? The cluster loses its RCM CA.” Answer Yes.
  • Windows, silent: add /FORCE. Without it the instance that runs the RCM stays, and the log names the reason.
  • Linux: the installer stops with exit code 5. Run it again with --force.

After a forced removal the cluster has no CA: no new certificates and no new members. To make another agent the owner of a new RCM, run fbagent --cluster-init <id> --rcm-takeover there and link the members again.

5. Linux

Run the same .run file that installed HQbird (or a newer one of the same line) as root. The examples use version 2027.2.33.

5.1. Remove the agent and HQbird Monitor

Command
# the agent and HQbird Monitor; Firebird, databases, configuration and logs stay
sudo sh hqbird2027-fb50-linux-2027.2.33.run --uninstall
Command
# the same, and the agent folder (configuration, logs, license state) and HQbird Monitor data too
sudo sh hqbird2027-fb50-linux-2027.2.33.run --uninstall --remove-data

The command stops and removes the units hqbirdfbagent-fb50 and hqbirdmonitor-fb50, the programs fbagent and hqmonitor, and the sudoers rules of the agent. It closes the HQbird Monitor port that the installation opened in firewalld or ufw.

5.2. Several instances on one host

Without --agent-dir the installer removes the only agent in /opt/hqbird. With several agents it stops with exit code 1 and lists their folders. Name the folder:

Command
sudo sh hqbird2027-fb50-linux-2027.2.33.run --uninstall --agent-dir /opt/hqbird/fbagent-fb50-2

Run the command once for every agent. The shared HQbird Monitor sign-in file stays until the last agent is removed.

5.3. Remove Firebird (optional, by hand)

The installer never removes Firebird on Linux. Do it by hand only after you made backups and moved the databases out of the Firebird folder.

Firebird unit names:

Firebird folder Line Unit
/opt/firebird 2.5, 4.0, 5.0 firebird
/opt/firebird 3.0 firebird-superserver
another folder, for example /opt/fb50-2 4.0, 5.0 firebird.opt_fb50-2
another folder, for example /opt/fb30 3.0 firebird.opt_fb30-superserver

Example for the Firebird in /opt/fb50-2:

Command
B=/opt/fb50-2
U=firebird.$(echo ${B#/} | tr / _)          # /opt/fb50-2 -> firebird.opt_fb50-2
systemctl list-unit-files "$U*"             # the units that will be removed
sudo systemctl disable --now $(systemctl list-unit-files "$U*" --no-legend | awk '$1 !~ /@/ {print $1}')
sudo rm -f /usr/lib/systemd/system/$U* /etc/systemd/system/$U*
sudo systemctl daemon-reload
sudo rm -rf $B

Warning: rm -rf deletes everything in the folder, also the databases and the security database that are inside it. Check the folder first.

5.4. Check the result

Command
systemctl list-unit-files 'hqbird*' 'hqclusternode*' 'firebird*' --no-legend
ls /opt/hqbird /var/lib/hqmonitor 2>/dev/null

Expected: no hqbirdfbagent-fb50 and hqbirdmonitor-fb50 units. The Firebird unit is still there unless you removed Firebird by hand.

5.5. What remains on the disk

Path Content Delete by hand?
/opt/hqbird/fbagent-fb50/ Agent configuration and logs (without --remove-data) Yes, if you do not need them
/var/lib/hqmonitor/ HQbird Monitor data (without --remove-data) Yes, if you do not need them
/opt/hqbirdrcm/ RCM, while other agents of the host use it After the cluster is gone
/opt/fbagent-update-backup/ Firebird program files that updates replaced Yes, when the updates are confirmed
/opt/hqbird/fbagent-hqbird-takeover.json State of the older HQbird units before the update Keep it if you plan to go back to the older HQbird
/opt/firebird (or your Firebird folder) Firebird and its databases Section 5.3

5.6. Exit codes of --uninstall

Code Meaning What to do
0 Removed —
1 Refused: several agents on the host, or a wrong option Add --agent-dir with a folder from the list
5 Refused: this agent runs the RCM of the host and other agents use it Section 4

6. An older HQbird after the removal

When HQbird 2027 replaced an older HQbird (2024 and earlier), the update turned the older HQbird services off. The removal of HQbird 2027 does not turn them on again. Their state before the update is saved in:

  • Windows: <HQbird folder>\fbagent-hqbird-takeover.json
  • Linux: /opt/hqbird/fbagent-hqbird-takeover.json

Use this file to see which services were active, and start them by hand if you go back to the older HQbird.

7. Troubleshooting

Problem What to do
Windows: the entry in Apps & features stays after the removal An instance was not removed (often the one that runs the RCM). Run the uninstaller again; for the RCM owner see section 4
Windows: a general error and a command from an old uninstaller The agent updated itself to 3.1.0 or newer and refuses to remove the RCM owner. Add --force to the shown command, or run the uninstaller of a newer setup
Windows: test builds 2027.0.1 and 2027.0.2 They used one entry for all lines. Remove them with their own uninstaller
Linux: --uninstall refused, exit code 1 Several agents on the host: add --agent-dir (section 5.2)
Linux: --uninstall refused, exit code 5 The agent runs the RCM of the host: section 4
Linux: run as root (sudo sh ...) Run the installer with sudo or as root
Linux: the .run file is lost Download the installer of the same line again; a newer version of the same line also works