HQbird 2027 for Linux: installation guide
This guide is for the administrator who installs HQbird 2027 on a Linux
server with the offline installer hqbird2027-fbNN-linux-<version>.run. It
covers a new installation, the update of an older HQbird and of an earlier
HQbird 2027, the maintenance commands, the connection to your HQCenter, the
unattended (scripted) installation, and where the files are after the
installation.
The examples show the installer for Firebird 5.0 on Ubuntu 24.04. The installers for Firebird 2.5, 3.0 and 4.0 work the same way; only the version, the default port and the folder names differ. The Windows setup is described in Windows installation.
Contents
- 1. What the installer installs
- 2. The installation at a glance
- 3. New installation
- 4. After the installation
- 5. Update of an older HQbird (2024 and earlier)
- 6. Update of HQbird 2027 to a new version
- 7. Maintenance commands
- 8. Attach to your HQCenter
- 9. Unattended installation and scripts
- 10. Troubleshooting
1. What the installer installs
One .run file = one Firebird line. Pick the installer of the Firebird
version your databases use:
| Installer | Firebird it installs or updates | First Firebird on the host | Size |
|---|---|---|---|
hqbird2027-fb50-linux-<version>.run |
Firebird 5.0 (HQbird build) | /opt/firebird, port 3050 |
about 250 MB |
hqbird2027-fb40-linux-<version>.run |
Firebird 4.0 (HQbird build) | /opt/firebird, port 3050 |
about 220 MB |
hqbird2027-fb30-linux-<version>.run |
Firebird 3.0 (HQbird build) | /opt/firebird, port 3050 |
about 130 MB |
hqbird2027-fb25-linux-<version>.run |
Firebird 2.5 (HQbird build) | /opt/firebird, port 3050 |
about 80 MB |
Every installer contains, and installs without the Internet:
- Firebird (the HQbird build of that line): a new server, or an in-place
update of the Firebird of that line that is already on the host. Your
firebird.conf,databases.conf(aliases.conffor 2.5), the security database and the SYSDBA password are kept. - Firebird debug files (symbols for crash analysis), installed into the
Firebird folder.
--no-debugskips them. - HQbird agent (
fbagent): the systemd unithqbirdfbagent-fb50, running as the userfirebird, that does the backups, monitoring, maintenance jobs and the updates. The name ends with the Firebird line (-fb25…-fb50); a second instance of the line has-fb50-2. - HQ Monitor: the web console of this HQbird instance, unit
hqbirdmonitor-fb50, addresshttp://<server>:<20000 + Firebird port>/(for Firebird on port 3050:http://localhost:23050/). - Cluster components: the cluster console RCM (
hqbirdrcm) and the cluster node (hqclusternode) are copied into the agent’s cache. Kits with agent (fbagent) 3.1.0 and later make no cluster by default: no RCM, no pairing window, no cluster port in the firewall. Two questions (or--rcm on,--cluster-pairing on) turn them on (“Next: cluster” in section 3). With RCM, it is installed in/opt/hqbirdrcmand runs as the unithqbirdrcm; the summary prints its address in theRCM:line. The node gets its unit (for examplehqclusternode-master-p3050) when you link the host in RCM. Kits from 2027.2.19 with an older agent install RCM on each server (--rcm offleaves it in the cache) and open the pairing window. Kits before 2027.2.19 only copy both components into the agent’s cache: there is no unithqbirdrcmand noRCM:line.
Instances installed before 2027.2.9 have the Firebird port in the agent
names: folder /opt/hqbird/fbagent-p3050, units hqbirdfbagent-p3050 and
hqbirdmonitor-p3050. An update does not change these names. Only new
instances get the -fb<NN> names, so one host can have both forms.
Requirements: x86_64, kernel 3.2 or newer, systemd; a Linux with apt,
dnf/yum or zypper (Ubuntu, Debian, AlmaLinux, Rocky, RHEL, Oracle
Linux, openSUSE, RED OS and others); root. About 300 MB free in /var/tmp
during the installation (a folder where programs may run; see --tmpdir).
A few OS libraries (libtommath, ICU) are taken from the distribution’s
repository; a server without Internet gets the exact commands to prepare
them (section 9).
Not supported: a Firebird installed from the distribution’s packages
(firebird3.0-server, firebird rpm). The installer stops before it changes
anything (exit code 7); remove the packages first (keep a gbak backup of
your databases) or use the online installer with --import-firebird.
Several Firebird lines on one server: each line has its own installer.
The first Firebird on the host goes to /opt/firebird; a second line goes to
/opt/fb<NN> (/opt/fb50, /opt/fb40, /opt/fb30) on the port of its line:
3053 for 3.0, 3054 for 4.0, 3055 for 5.0. When that port is in use, the
installer stops and asks for --port N. Several instances of one line
(a second Firebird 5.0 on another port) are installed with
--fb-root <new folder> --port <port> (section 7). Firebird 2.5 has one
instance only, in /opt/firebird; for a second server next to it use another
line (for example Firebird 5.0 in /opt/fb50).
A step-by-step runbook for two instances on ports 3050 and 3051, for every
line, with copy-paste commands, is in
hqbird2027-linux-two-instances-runbook.ru.md
(Russian) and
hqbird2027-linux-two-instances-runbook.pt.md
(Portuguese).
Trial: without a license the agent runs a 7-day trial. The trial email
(--email) extends it to 30 days. A license file (--license) or the
connection to your HQCenter (section 8) replaces the trial.
Updates: from kit 2027.2.31 (agent 3.3.0) a server that is attached to
no HQCenter checks the vendor’s update server. By default the agent, HQ
Monitor and fbmcp update by themselves, and a new Firebird package is
downloaded and waits for you. --auto-update all|agent|off or the Updates
line of the text interface changes this (“Updates without HQCenter” in
section 4). A server attached to an HQCenter takes its updates from that
HQCenter.
2. The installation at a glance
The server check and the installation itself are done by the HQbird agent
that the installer carries (fbagent --install-plan,
fbagent --setup-install). Nothing is downloaded except the missing OS
packages. Nothing is changed before the plan is confirmed: the OS packages
are installed after the confirmation. In a terminal, kits after 2027.2.30
open the text interface (step 3 of section 3); --no-tui runs the plain
installer, which asks its questions as lines of text. Without a terminal and
without --yes the installer stops at the confirmation with exit code 4. If the installation fails before the agent unit
starts, the agent rolls the units back to the state they had before (exit
code 2; code 3 when the rollback was not complete, the summary says what to
check).
3. New installation
Step 1: Download the installer and check it
KIT=hqbird2027-fb50-linux-2027.2.9.run
curl -fL -O https://ib-aid.com/download/hqbird/v2027/$KIT -O https://ib-aid.com/download/hqbird/v2027/$KIT.sha256
sha256sum -c $KIT.sha256The other lines have the same names with fb40, fb30, fb25. Expected:
hqbird2027-fb50-linux-2027.2.9.run: OK. A server without Internet: download
the two files on a PC with the same links and copy them to the server (scp,
a USB drive, a share).
The installer also checks its own payload before it unpacks anything: a cut or damaged download stops with exit code 5 (“download it again”).
Step 2: Check the host without changing it (optional)
sudo sh hqbird2027-fb50-linux-2027.2.9.run --check--check runs the host check, reports the missing OS libraries (and the
commands to get them on a server without Internet), shows what the agent
found and what it would do, and exits. Nothing is installed.
Step 3: Run the installer
sudo sh hqbird2027-fb50-linux-2027.2.9.runKits after 2027.2.30 open the text interface when you start them in a terminal: full-screen pages with the plan and the settings. Kits up to 2027.2.30, and the cases in “The plain installer” below, ask their questions as lines of text. Both do the same installation with the same options.
The text interface
The installer checks the host, unpacks itself, reads the plan, and shows the first page. Nothing on the host is changed until you start the installation on the Install page.
HQbird 2027 setup <version> | Firebird 5.0 (5.0.5.1917)
Plan M1: New Firebird and HQbird agent
Firebird: new /opt/firebird (unit firebird, port 3050)
Agent: new, in /opt/hqbird/fbagent-fb50
OS packages to install: libtommath1 (see Plan details)
Language English (auto)
Firebird folder automatic (/opt/firebird)
Firebird port automatic (3050)
Agent id automatic (srv1261114-fb50)
SYSDBA password generated (for a new Firebird)
HQ Monitor port automatic, login admin
License not now (add it later in HQ Monitor)
HQCenter not attached
Cluster RCM off, discovery mode off
Components debug files: yes, fbmcp: yes
Updates HQbird only (recommended)
> Install
Plan details
About plans
Quit
Up/Down: move Enter: change or start Esc: quitThe top lines are the plan for the settings of now: its code and what the installer will do with Firebird and the agent. A plan that is not possible is red, with the reason, and the cursor stands on the setting that fixes it. After each change the installer reads the plan again.
| Key | What it does |
|---|---|
| Up, Down | Move the cursor (also k, j) |
| Enter | Open the setting under the cursor, select an item, accept a typed value |
| Space | Turn a component on or off (the Components page) |
| Esc | Back to the page before; on the first page: leave the installer (it asks first) |
| Ctrl+C | Stop the installer at once (exit code 2). Nothing was changed before the Install page |
On a page where you type a value (a folder, a port, an address), Enter accepts it and an empty value means “automatic”. Esc does not leave such a page.
| Setting | What you choose | The same as the option |
|---|---|---|
| Language | English, Russian, Brazilian Portuguese, German; the pages change at once | --lang |
| Firebird folder | The folder of a new Firebird, or of the Firebird to update. Firebird 2.5 has one folder, so its installer has no such line | --fb-root |
| Firebird port | The TCP port of Firebird | --port |
| Agent id | Automatic, the host name, the host name and the instance, or your own value. Only for a new agent: an installed agent keeps its id, and the line is not shown | --agent-id |
| SYSDBA password | For a new Firebird: generated, or your own | --sysdba-pass-file |
| HQ Monitor | The port and the sign-in of the web console | --hqmonitor-port, --hqmonitor-login, --hqmonitor-password-file |
| License | Not now, a 30-day trial by e-mail (address, privacy notice, zone), or a license file | --email --accept-privacy --trial-zone, --license |
| HQCenter | The attach.json file of your HQCenter |
--attach |
| Cluster | The cluster manager RCM (cluster id, admin password), discovery mode, the pairing port | --rcm, --cluster-id, --rcm-password-file, --cluster-pairing, --pairing-port |
| Components | Firebird debug files; fbmcp and the addresses of its remote mode | --no-debug, --no-fbmcp, --fbmcp-allow-from |
| Updates | HQbird only (the agent, HQ Monitor and fbmcp update by themselves, a new Firebird waits for you), HQbird and Firebird (Firebird also updates by itself, at night from 03:30 to 04:00, with a restart of Firebird), or Off. Kits from 2027.2.31; only for a new agent with no attach.json file: an HQCenter controls the updates of an attached agent |
--auto-update |
Options on the command line are the values the pages start with:
sudo sh hqbird2027-fb50-linux-<ver>.run --rcm on --port 3055 opens the
first page with RCM on and port 3055.
The four lines under the settings:
- Install shows the plan in full, then asks
Start the install now?with the cursor on No. The questions of the plan (an older HQbird, a running Firebird to stop) are on the same page: Yes answers them all. After Yes the pages close, and the installation prints its log and the summary on the normal screen, as in the plain installer below. - Plan details shows what the code of the plan means, what the installer found on the host, the warnings and the OS packages it will install.
- About plans lists all the codes (M1 … M17). Enter on a code explains
it. A
*marks the code of the plan of now. - Quit leaves the installer (exit code 1). Nothing was changed.
The plain installer
The plain installer runs when one of these is true:
- the option
--no-tui, or the variableHQBIRD_NO_TUI=1; --yes,--check,--uninstall,--extract,--plan-help,--help;- stdin or stdout is not a terminal: a script,
ssh host 'command'without a terminal, or a pipe such as... 2>&1 | tee install.log; TERMisdumbor not set;- the window is smaller than 80 columns by 24 rows (inside
tmuxwith its status line an 80x24 terminal has 23 rows: make the window larger, or use--no-tui); - bash on the host is older than 4.4 (RHEL 7, CentOS 7);
- the kit is 2027.2.30 or older.
For the window and for bash, the first line of the output says why the pages did not open.
A typical run of the plain installer on a server without Firebird:
[install] HQbird 2027 setup 2027.2.9, Firebird 5.0 (5.0.5.1916)
[install] host: Ubuntu 24.04.5 LTS, kernel 6.8.0-142-generic
[install] checking the payload (sha256) ...
[install] unpacking into /var/tmp/hqbird2027.k3Qf1x ...
[install] OS libraries missing: libtommath.so.1 (packages: libtommath1)
[install] plan M1: Firebird new /opt/firebird (unit firebird, port 3050)
[install] agent new in /opt/hqbird/fbagent-fb50 (unit hqbirdfbagent-fb50), HQ Monitor hqbirdmonitor-fb50
[install] OS packages to install: libtommath1
[install] Install as planned? Yes/No y
[install] installing from the package repository: libtommath1
[install] OS libraries: installed
[install] installing (fbagent --setup-install; log /var/log/fbagent/install.log) ...
...
Done: agent hqbirdfbagent-fb50 in /opt/hqbird/fbagent-fb50, Firebird 5.0.5.1916 in /opt/firebird (port 3050).
HQ Monitor: http://localhost:23050/ (login admin; password in /opt/hqbird/conf/access.properties)
[install] done. Uninstall: sudo sh hqbird2027-fb50-linux-2027.2.9.run --uninstallThis example is from kit 2027.2.9. From kit 2027.2.19 the summary also has
the RCM: and Pairing: lines of the cluster console (“Next: cluster”
below). With agent 3.1.0 and later and no cluster chosen, they are:
RCM: off; turn it on in HQbird Monitor or with fbagent --cluster-init <id>
Pairing: off; turn it on in HQbird Monitor or with fbagent --cluster-pairing on (port 7450)What the lines mean:
- host: the distribution and kernel; the installer refuses a host that is not x86_64, has no systemd, or runs a kernel older than 3.2.
- OS libraries: what the Firebird of this line needs from the OS
(section 9). The plan lists the missing packages (
OS packages to install); after the confirmation the installer takes them from the distribution’s repository. Without a repository it stops with exit code 6 and prints the commands. - plan: what the agent found (
found Firebird ...,HQbird: ...lines) and what it will do:Firebird new(a new server),update(the Firebird of this line is updated in place), or a refusal with the reason (exit code 1, nothing changed). - Install as planned? Yes/No: the last question before anything is
changed. Answer
y. When the plan has questions of its own (an older HQbird, another version), they come instead (section 5). Without a terminal, pass--yes; otherwise the installer stops with exit code 4. - Cluster questions (agent 3.1.0 and later):
Install the cluster manager (RCM) on this host and make a new cluster? [y/N]andTurn on discovery mode for 24 hours (an RCM on the network may invite this agent into its cluster; port 7450)? [y/N]. The default is No. The first is asked only when the host has no RCM and the agent is in no cluster; the second not when the agent is in a cluster or runs the RCM.--yesand a run without a terminal answer No (no exit code 4). - HQ Monitor: the address and the login. A new installation gets the
login
admin; its generated password is in/opt/hqbird/conf/access.properties(mode 0600, readable byrootand the agent only). All HQbird 2027 instances of the host share this file. Change the password in HQ Monitor.
The SYSDBA password of a new Firebird is generated and saved in
/root/fbagent-install-sysdba.txt (mode 0600): a comment line, then the line
SYSDBA_PASS=<password>. A further Firebird installed on the same host later
gets the same password from this file. To set your own, pass
--sysdba-pass-file <file> (first line of the file) or --sysdba-pass <password>.
Language of the installer
Kits after 2027.2.30 speak four languages: English, Russian (ru),
Brazilian Portuguese (pt-BR) and German (de). The installer picks the
language in this order:
- the option
--lang en|ru|pt-BR|de; - the variable
HQBIRD_LANG; - the locale of the console (
LC_ALL, thenLC_MESSAGES, thenLANG), when it is a UTF-8 locale; - English.
The second line of the output says which language it is and how to change it. This line is always English:
[install] Language: Русский (auto). Use --lang en to change.Notes:
- PuTTY does not send
LANGto the server. The server’s own locale counts, so the language is often English. Use--lang. - With
--yes, and without a terminal, the automatic language is English: scripts read that output.--langstill works there. - The installer needs a UTF-8 locale on the host for the other languages
(
C.UTF-8oren_US.UTF-8). It sets one for itself. Without one it speaks English. - In the text interface the Language line of the first page changes the language at once. The terminal must show UTF-8 (PuTTY: Window, Translation, Remote character set UTF-8, which is its default).
- English stays in: the progress lines of the install itself, the
Done:summary,/var/log/fbagent/install.log, and the warnings of the host scan.
The code of the plan
The plan has a code: M1, M2, … It names the case the installer found
on the host. The installer prints what the code means:
[install] plan M1: New Firebird and HQbird agent
[install] This host has no Firebird and no older HQbird. Setup installs a new Firebird and a new HQbird agent.
[install] plan M1: Firebird new /opt/firebird (unit firebird, port 3050)--plan-help prints all the codes and exits. It changes nothing. In the
text interface the first page shows the code and its title, “Plan details”
shows the text, and “About plans” lists all the codes.
| Code | What the installer found | Firebird | Agent | Older HQbird |
|---|---|---|---|---|
| M1 | nothing | new | new | — |
| M2 | Firebird of this line, no older HQbird | update | new | — |
| M3 | Firebird of another line, no older HQbird | new, port 305N | new | — |
| M4 | older HQbird that serves the Firebird of this line | update | new | turned off, its jobs imported as enabled |
| M5 | older HQbird of another line; a Firebird of this line is there | update, after a question | new | keeps working |
| M6 | older HQbird of another line; no Firebird of this line | new, after a question | new | keeps working |
| M7 | older HQbird without a local Firebird of a known version | update or new | new | keeps working, a warning |
| M8 | an HQbird 2027 agent for another Firebird | update or new | new, beside the first | not changed |
| M9 | as M8, and an older HQbird serves this line | update | new, beside the first | turned off, its jobs imported as enabled |
| M10 | an agent already serves this Firebird (a repeated run) | update | in place | turned off when it runs |
| M11 | --fb-root is a Firebird of this line |
update | new or in place | as above |
| M13 | --fb-root is an empty or new folder |
new in that folder | new | as above |
Codes of a refusal (exit code 1, nothing changed): M12 the folder has a
Firebird the installer cannot update (another line, a version it cannot
read, a disabled service); M14 the folder is not empty and has no
Firebird; M16 several Firebird servers of this line, give --fb-root;
M17 Firebird 2.5 works only in /opt/firebird. M15 is the
agent-only kit: Firebird is not installed and not updated.
The agent id
The agent id names the agent in HQCenter, in the license and in the cluster. It is set at the first install only:
- Default: host name + date + instance, for example
srv1261114-fb50. --agent-id IDgives your own id (1-128 letters, digits,.,_or-; the first one a letter or digit).- The installer refuses an id that another agent of the host has.
- In the text interface the Agent id page offers the automatic id, the host name, the host name with the instance, and your own value, and lists the ids the host already has.
- An installed agent keeps its id. A repeated run shows it in the plan
(
id srv1 (kept)), the text interface has no Agent id line then, and--agent-idthere gives only a warning. A new agent in a folder that an earlier install left with its configuration keeps the id of that configuration too.
Step 4: Check the result
systemctl status firebird hqbirdfbagent-fb50 hqbirdmonitor-fb50 --no-pager
ss -ltnp | grep -E ':3050|:23050'
ISC_PASSWORD="$(sed -n 's/^SYSDBA_PASS=//p' /root/fbagent-install-sysdba.txt)" \
/opt/firebird/bin/isql -user SYSDBA localhost/3050:/opt/firebird/examples/empbuild/employee.fdbUse the full path of the sample database: it works for every line and also
after an update, while the kept databases.conf of an older installation may
have no employee alias (a new installation of 2027.2.3 has it).
Open http://<server>:23050/ in a browser and sign in as admin with the
password from /opt/hqbird/conf/access.properties. The Firebird port and
the HQ Monitor port are opened in firewalld (zone public) when it runs,
else in ufw when it is active; with another firewall open them yourself.
Cluster ports are opened only for a cluster option: 7443, 7444 and the node
port with --rcm on; the node port and the pairing port with
--cluster-pairing on. Without an active firewall the installer prints one
line with the ports it did not open. A port that was open before the
installation is left as it is.
Next: cluster
To replicate your databases from a master server to a replica server, link
the two servers in the cluster console RCM. With agent 3.1.0 and later,
install RCM only on the master (--rcm on, or answer y) and turn on
discovery mode on the replica (--cluster-pairing on). Discovery mode opens
the pairing window for 24 hours: the pairing port of the agent’s slot (7450
for the first instance, 7451 for the second, up to 7459) is open in the
firewall, and the RCM may invite the agent. One host has one RCM (ports 7443
and 7444); the agent that made it runs it and opens no pairing window.
Later, without the installer: HQ Monitor → Clusters → Cluster on this
server, or fbagent --cluster-init <id> and fbagent --cluster-pairing on. Kits from 2027.2.19 with an older agent start RCM on each server and
print its address in the RCM: line of the summary; an installation before
2027.2.19 gets RCM when you update it with a newer kit (section 6). The
cluster guide (for kit 2027.2.33) goes step
by step from two new servers to a working replica, with screenshots:
Linux cluster guide
(also in Russian and
Portuguese). The same steps as
commands only:
hqbird2027-linux-cluster-runbook.md
(hqbird2027-linux-cluster-runbook.ru.md,
hqbird2027-linux-cluster-runbook.pt.md).
4. After the installation
Units
| Unit | What | Runs as |
|---|---|---|
firebird (2.5, 4.0, 5.0 in /opt/firebird); firebird-superserver (3.0 in /opt/firebird); for another folder the folder name with / → _: firebird.opt_fb50, firebird.opt_fb40-2 (4.0, 5.0 in /opt/fb50, /opt/fb40-2), firebird.opt_fb30-superserver (3.0 in /opt/fb30) |
Firebird server | firebird |
hqbirdfbagent-fb50 (second instance hqbirdfbagent-fb50-2; before 2027.2.9 hqbirdfbagent-p<Firebird port>) |
HQbird agent | firebird |
hqbirdmonitor-fb50 (hqbirdmonitor-fb50-2; before 2027.2.9 hqbirdmonitor-p<Firebird port>) |
HQ Monitor | firebird |
All three are enabled and start at boot. journalctl -u hqbirdfbagent-fb50
shows the agent’s unit log. Firebird 3.0 also has the units
firebird-classic.socket and [email protected]
(firebird.opt_fb30-classic.* in another folder), and Firebird 2.5 has
firebird.socket: they stay inactive, this is normal. The Firebird 2.5
process is fb_smp_server (SuperClassic).
Where the files are
The example is the first Firebird 5.0 instance in /opt/firebird on port
3050. A second instance of the line has -2 in the agent names
(fbagent-fb50-2, hqbirdfbagent-fb50-2, hqbirdmonitor-fb50-2).
Instances installed before 2027.2.9 have the port in these names
(fbagent-p3050, hqbirdfbagent-p3050, hqbirdmonitor-p3050).
/opt/firebird/ Firebird 5.0 server: bin/, lib/, plugins/, firebird.conf,
databases.conf, security5.fdb, *.debug files (symbols)
/opt/fb50/ a Firebird 5.0 next to another line (/opt/fb40, /opt/fb30)
/opt/hqbird/ root of the HQbird agents
conf/access.properties HQ Monitor sign-in, shared by all instances of the host (0600)
fbagent-fb50/ HQbird agent of this Firebird
fbagent the agent (unit hqbirdfbagent-fb50)
hqmonitor HQ Monitor (unit hqbirdmonitor-fb50)
agent_config.json agent configuration (encrypted secrets: config_secret.key)
config.properties HQ Monitor configuration
hqbird2027-firebird.json the Firebird this installer installed
hqbird2027-hqmonitor-firewall.json the HQ Monitor port this installer opened in firewalld or ufw
conf/ trace and job settings
logs/ agent log (firebird-agent_<date>.jsonl), license_state.json;
journal.log and server_status.json after the first checks
bak/ backups of the configuration
outcoming/ status reports for HQCenter
update/ update cache: hqmonitor/, hqclusternode/, hqbirdrcm/
certs/ certificates after the attach to HQCenter
fbagent-hqbird-takeover.json state of the older HQbird units before the takeover (section 5)
/opt/hqbirdrcm/ the cluster console RCM (unit hqbirdrcm, owner firebird):
with agent 3.1.0 only after --rcm on (or HQ Monitor);
kits 2027.2.19+ with an older agent: unless --rcm off
/opt/hqclusternode/ the cluster node (owner firebird), empty until the host is
linked in RCM or HQCenter adds it to a cluster
/var/lib/hqmonitor/<server id>/ HQ Monitor data
/var/log/fbagent/install.log log of the installer's steps (passwords are hidden)
/root/fbagent-install-sysdba.txt SYSDBA password of a new Firebird (root only, 0600)
/etc/sysctl.d/90-hqbird-firebird.conf kernel settings for Firebird (vm.max_map_count), only when
the system value is lower (Ubuntu 24.04 needs none)
/etc/sudoers.d/ the agent's sudoers rules for its root helpers (updates, HQ Monitor)The installer keeps nothing in /var/tmp: its working folder
/var/tmp/hqbird2027.XXXXXX is removed at the end, also after an error.
Logs
| Log | Where |
|---|---|
| Installer | the terminal; /var/log/fbagent/install.log |
| Agent | /opt/hqbird/fbagent-fb50/logs/firebird-agent_<date>.jsonl, journal.log; journalctl -u hqbirdfbagent-fb50 |
| HQ Monitor | journalctl -u hqbirdmonitor-fb50; audit log /opt/hqbird/fbagent-fb50/hqmonitor_audit.log |
| Firebird | /opt/firebird/firebird.log |
Updates without HQCenter
From kit 2027.2.31 (agent 3.3.0) an agent that is attached to no HQCenter
takes new versions from the vendor’s update server. The update mode is the
key update.mode of agent_config.json:
| Mode | What updates by itself |
|---|---|
agent (default) |
The agent, HQ Monitor and fbmcp. A new Firebird package is downloaded and waits for the administrator |
all |
The same, and Firebird too, in its apply window (at night from 03:30 to 04:00; the update restarts Firebird) |
off |
Nothing: the agent makes no update checks. To update, run the installer of a new version (section 6) |
- At the installation: the Updates line of the text interface, or
--auto-update all|agent|off. Without them the installer does not change the mode. - Later: the Updates page of HQ Monitor, or the installer again with
--auto-update <mode>. - The state:
sudo /opt/hqbird/fbagent-fb50/fbagent --update-status(add--jsonfor a script). It prints the release source, the zone and the last answer of the update server.
The agent opens outgoing HTTPS connections to these addresses only. No incoming port is needed.
| Purpose | Address |
|---|---|
| Updates, zone EU | liceu.ibsurgeon.com:9443 |
| Updates, zone BR | licbr.ibsurgeon.com:9443 |
| Updates, zone RU | licru.ibsurgeon.com:20943 |
| Trial license | trialeu.ibsurgeon.com:9443, trialbr.ibsurgeon.com:19443, trialru.ibsurgeon.com:23943 |
A server that is attached to an HQCenter does not use the update addresses: it takes its updates from that HQCenter (section 8).
Notifications
From kit 2027.2.33 (agent 3.4.0) the agent sends messages about server
problems to a Telegram bot of your own, a webhook or e-mail (SMTP). The
installer sets no channel, and nothing is sent until you add one: HQ
Monitor → Servers → Notifications. To test a channel from the
command line: sudo -u firebird /opt/hqbird/fbagent-fb50/fbagent --notify-test <channel>; --notify-history prints the last deliveries.
5. Update of an older HQbird (2024 and earlier)
The installer finds an installed HQbird (FBDataGuard) in /opt/hqbird and
its units, and the Firebird servers it manages. It then follows the same
rules as the HQbird install scripts:
What you see on the terminal:
[install] found Firebird 5.0.5.1878: /opt/firebird, port 3050, unit firebird, no agent
[install] plan M4: Firebird update /opt/firebird (unit firebird, port 3050)
[install] agent new in /opt/hqbird/fbagent-fb50 (unit hqbirdfbagent-fb50), HQ Monitor hqbirdmonitor-fb50
[install] HQbird services to turn off: hqbird
[install] Firebird 5.0.5.1878: unit firebird, port 3050, 0 TCP connections
[install] Confirm to stop running Firebird 5.0.5.1878? Yes/No y- The plan names the Firebird that is updated;
--fb-rootand--portcannot move it (its unit is taken). - The question Confirm to stop running Firebird? is asked when the
engine must be stopped; the line before it shows the open connections.
Another versionis asked when the older HQbird manages a Firebird of another version (update that one, or a new one next to it).--yesanswers all questions with Yes; without a terminal and without--yesthe installer stops with exit code 4 and changes nothing. --disable-hqbirdturns the older HQbird units off in any case;--no-hqbirdleaves the older HQbird alone (it keeps running next to HQbird 2027).- The SYSDBA password is not asked: the agent takes it from the older HQbird.
- HQ Monitor uses the sign-in of the older HQbird: its file
/opt/hqbird/conf/access.propertiesis kept, so sign in with the login and password you used before. The installer gives the file tofirebirdwith mode 0600 (the older HQbird left it readable by every user). The guest login of the older HQbird (access.guest-login) is not used by HQ Monitor.
What is kept: firebird.conf, databases.conf / aliases.conf, the
security database, the SYSDBA password, the databases, the backups and the
files of the older HQbird. The update replaces the Firebird program files in
place; the files it replaced are kept in
/opt/fbagent-update-backup/<folder name>-<id>/<time>_<old version>_to_<new version>/
(the two newest updates stay). The HQbird jobs (backups, sweeps, monitoring)
are imported into the new agent. The HQbird license of the older HQbird is
not transferred: the new agent runs the trial until a license is installed
or the server is attached to your HQCenter.
From kit 2027.2.33 (agent 3.4.0) the import of the older HQbird’s configuration does two more things:
- It registers the databases of the older HQbird in the Firebird aliases
file (
databases.conf, oraliases.conffor 2.5) asname = pathlines. The old file is copied first. A database is left out when its path is already in the file, or when its file does not exist. A file with anincludedirective is not changed. - It removes the old monitoring logs of the older HQbird: the content of
the folders
mon/outcomingandmon/outtraceof its output folder (the folders stay). Nothing is removed while a service of the older HQbird runs. The removal cannot be undone: if you need these logs, copy them before the installation.
Both are on by default. The keys hqbird_import.register_databases and
hqbird_import.clean_mon_logs of agent_config.json (both are in the
config editor of HQ Monitor) turn them off for a later import; the installer
has no option for them.
The state of the older HQbird units before the takeover is saved in
/opt/hqbird/fbagent-hqbird-takeover.json. --uninstall does not turn
them back on.
Unattended form:
sudo sh hqbird2027-fb50-linux-2027.2.9.run --yes --disable-hqbird6. Update of HQbird 2027 to a new version
A newer installer of the same line, run on a host with HQbird 2027, updates the installed instance in place: Firebird, the debug files, the agent and HQ Monitor. The configuration, the databases, the trial or license state, the HQ Monitor port and sign-in are kept.
sudo sh hqbird2027-fb50-linux-2027.2.9.runIn the text interface the first page shows Plan M10: Update of an installed HQbird 2027, the agent with its id (kept), and no Agent id line; Install
starts the update. The plain installer prints:
[install] HQbird 2027 setup 2027.2.9, Firebird 5.0 (5.0.5.1916)
[install] found Firebird 5.0.5.1880: /opt/firebird, port 3050, unit firebird, agent hqbirdfbagent-p3050
[install] plan M10: Firebird update /opt/firebird (unit firebird, port 3050)
[install] agent in_place in /opt/hqbird/fbagent-p3050 (unit hqbirdfbagent-p3050), HQ Monitor hqbirdmonitor-p3050
[install] Firebird 5.0.5.1880: unit firebird, port 3050, 2 TCP connections
[install] Confirm to stop running Firebird 5.0.5.1880? Yes/No y
...
Firebird updated: 5.0.5.1880 -> 5.0.5.1916
HQ Monitor updated 1.31.0 -> 1.33.0 (...)
Done: agent hqbirdfbagent-p3050 in /opt/hqbird/fbagent-p3050, Firebird 5.0.5.1916 in /opt/firebird (port 3050).An update does not change the names of the agent folder and units: the
instance in this example was installed before 2027.2.9 and keeps
fbagent-p3050.
When the Firebird build of the installer is the one already installed (for
example Firebird 2.5.9.27194 in every HQbird 2027 for 2.5), only the agent
and HQ Monitor are updated: Firebird is not stopped and there is no
Confirm to stop question.
The kept databases.conf of an instance installed by an older HQbird 2027
may have no employee alias; connect to the sample database by its full path
(section 3, step 4). On Firebird 3.0 an update from 2027.2.0 leaves
/opt/firebird/examples/empbuild/employee.fdb with mode 0444, and Firebird
cannot open it (no permission for read-write access); if you need the
sample database: sudo chmod 660 /opt/firebird/examples/empbuild/employee.fdb.
Your own databases are not touched.
- With several instances of the line, name the one to update:
--fb-root /opt/fb50-2 --port 3056. - The same installer run again over the installed version is a repair: the program files and units are written again, the data stays.
- After the connection to an HQCenter (section 8) the agent, HQ Monitor, Firebird and the cluster components are updated from the HQCenter catalog; a new installer is then not needed.
- A server attached to no HQCenter with agent 3.3.0 or later (kits from
2027.2.31) updates the agent, HQ Monitor and fbmcp by itself, unless the
update mode is
off(“Updates without HQCenter” in section 4). An installation made before 2027.2.31 gets this after one update with a newer installer. An update with the installer keeps the update mode;--auto-update <mode>changes it.
7. Maintenance commands
Every maintenance action is a run of the installer with options, or an
agent command in the agent folder. In a terminal a run without --yes opens
the text interface with these options already set (kits after 2027.2.30):
check the plan on the first page, then choose Install.
| Action | Command |
|---|---|
| Another instance of this line | sudo sh hqbird2027-fb50-linux-<ver>.run --fb-root /opt/fb50-2 --port 3056 |
| Repair / update | sudo sh hqbird2027-fb50-linux-<ver>.run (with several instances: --fb-root <folder> --port <port>) |
| Attach to HQCenter | sudo sh hqbird2027-fb50-linux-<ver>.run --attach attach.json during the installation, or later cd /opt/hqbird/fbagent-fb50 && sudo ./fbagent --attach --file /path/attach.json |
| Send the trial email | cd /opt/hqbird/fbagent-fb50 && sudo -u firebird ./fbagent --trial-email [email protected] --accept-privacy |
| Confirm the trial code from the mail | cd /opt/hqbird/fbagent-fb50 && sudo -u firebird ./fbagent --trial-confirm <code> (or in HQ Monitor) |
| Install a license file | --license <file> during the installation, or cd /opt/hqbird/fbagent-fb50 && sudo -u firebird ./fbagent --license-install /path/license.json |
| State of the installation | sudo /opt/hqbird/fbagent-fb50/fbagent --install-state --json |
| State of the updates (no HQCenter) | sudo /opt/hqbird/fbagent-fb50/fbagent --update-status |
| Change the update mode (no HQCenter) | HQ Monitor, the Updates page; or sudo sh hqbird2027-fb50-linux-<ver>.run --auto-update all|agent|off |
| Remove | sudo sh hqbird2027-fb50-linux-<ver>.run --uninstall [--remove-data] [--force] [--agent-dir /opt/hqbird/fbagent-fb50] |
Another instance
sudo sh hqbird2027-fb50-linux-2027.2.9.run --fb-root /opt/fb50-2 --port 3056The new Firebird goes to /opt/fb50-2 (a new or empty folder), unit
firebird.opt_fb50-2, with its own agent (/opt/hqbird/fbagent-fb50-2, unit
hqbirdfbagent-fb50-2) and its own HQ Monitor (http://localhost:23056/,
unit hqbirdmonitor-fb50-2). The agent gets the lowest free number of the
line: fb50-2 for the second instance, also next to an agent installed
before 2027.2.9 (fbagent-p3050). The HQ Monitor sign-in file
/opt/hqbird/conf/access.properties is shared by the instances of the host:
a new instance without --hqmonitor-login keeps the existing sign-in, and
--hqmonitor-login/--hqmonitor-password-file on any instance change the
sign-in of all of them (the old file is kept as
access.properties.bak-<time>). Firebird 2.5 does not support a second
instance: the installer stops with refused (M17): Firebird 2.5 works only in /opt/firebird, not in <folder> (exit code 1, nothing changed). Install a
Firebird of another line next to it, for example
sudo sh hqbird2027-fb50-linux-<ver>.run --fb-root /opt/fb50 --port 3051.
Remove
The removal on Windows and Linux, servers in a cluster and what remains on the disk are described in full in removal guide. In short:
# the agent and HQ Monitor of this instance; Firebird, the databases, configs and logs stay
sudo sh hqbird2027-fb50-linux-2027.2.9.run --uninstall
# the same, and the agent's configuration, logs, license state and HQ Monitor data too
sudo sh hqbird2027-fb50-linux-2027.2.9.run --uninstall --remove-dataWithout --agent-dir the installer removes the only agent in
/opt/hqbird. With several agents on the host it stops (exit code 1),
lists their folders and asks for --agent-dir:
sudo sh hqbird2027-fb50-linux-2027.2.9.run --uninstall --agent-dir /opt/hqbird/fbagent-fb50-2--uninstall stops and removes the units of the agent and its HQ Monitor
(hqbirdfbagent-fb50, hqbirdmonitor-fb50), the sudoers rules of the agent and its programs
(fbagent, hqmonitor), and closes the HQ Monitor port that the
installation opened in firewalld or ufw. The agent folder stays with the configuration and
logs; --remove-data removes the folder and the HQ Monitor data in
/var/lib/hqmonitor/ too. Firebird stays installed (unit, program
folder, databases); the older HQbird units that were turned off stay off.
With several agents on the host, the shared HQ Monitor sign-in file stays
until the last agent is removed.
If the agent runs the RCM of the host and other agents use that RCM,
--uninstall refuses with exit code 5 and changes nothing:
this agent runs the RCM of the host, and other agents use it: remove the cluster in the RCM console, or run again with --force. --force removes
the agent anyway; the cluster then loses its CA (no new certificates, no new
members). The RCM unit stays while other agents of the host use it. To make
another agent the owner of a new RCM when the old owner is gone:
fbagent --cluster-init <id> --rcm-takeover (a new CA: link the members
again).
The hint at the end of an installation (Uninstall: sudo sh ... --uninstall)
has no --agent-dir: with several instances add it as shown above.
To remove the Firebird of an instance too (the installer does not do it;
make gbak backups of its databases first), for example the Firebird in
/opt/fb50-2:
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 $B8. Attach to your HQCenter
HQCenter is the central server of your company that manages the HQbird agents: licenses, configuration, updates, backups overview. Without an HQCenter the agent works on its own with the versions of the installer and the trial or license file.
- In the HQCenter admin panel open Tokens
(
https://<hqcenter>:8443/admin/tokens). In the Install script form choose the license (or none), the mode, the number of servers and the validity (1 to 365 days); the platform and Firebird fields are not used. Click Download connection file and saveattach.json. The file contains a secret token: keep it safe (chmod 600), delete it after use and revoke the token in the list on the same page. The form is shown only whenadmin_panel.install_script_urlis set. - Copy
attach.jsonto the server. - Attach in one of two ways:
# during the installation
sudo sh hqbird2027-fb50-linux-2027.2.9.run --yes --attach /root/attach.json
# later, for an installed agent
cd /opt/hqbird/fbagent-fb50 && sudo ./fbagent --attach --file /root/attach.jsonWith an ordinary token the command waits until the HQCenter administrator approves the request (up to 30 minutes). With a license token the agent is attached at once and gets the license. After the attach the trial ends when HQCenter gives the agent a license; the agent, HQ Monitor, Firebird and the cluster components are then updated from the HQCenter catalog. A failed attach during the installation does not undo the installation: the summary says so, and the command above repeats it.
Requirements: HQCenter (goafts) 1.15.0 or newer (older versions have no connection file button); the server reaches the HQCenter bootstrap port once for the attach and then the agents’ port (443 by default). HQCenter can be without Internet. A second attach of the same server to the same HQCenter needs the administrator’s approval even with a license token.
9. Unattended installation and scripts
Every option works on the terminal too. An unattended run needs --yes
(answers the questions of the plan; without a terminal and without --yes
the installer stops with exit code 4). --yes never opens the text
interface. A script that starts the installer in a terminal and answers its
questions itself (for example with expect) must add --no-tui or set
HQBIRD_NO_TUI=1: kits after 2027.2.30 open the pages there. The exit code tells the result; the
details are on the terminal and in /var/log/fbagent/install.log.
Options
| Option | Meaning | Default |
|---|---|---|
--fb-root DIR |
Folder of the new Firebird (new or empty); or the folder of the Firebird to update | /opt/firebird, then /opt/fb<NN> |
--port N |
Firebird port | 3050 for the first Firebird; for another line the port of the line (3053 for 3.0, 3054 for 4.0, 3055 for 5.0) |
--sysdba-pass-file F, --sysdba-pass P |
SYSDBA password of a new Firebird (first line of F; P is written to a 0600 file) |
generated, saved in /root/fbagent-install-sysdba.txt; a further Firebird on the host takes the password from that file |
--agent-id ID |
agent.id of the new agent; only at the first install, an installed agent keeps its id (“The agent id” in section 3) |
host name + date + instance |
--hqmonitor-port N |
HQ Monitor port | 20000 + Firebird port |
--hqmonitor-login L --hqmonitor-password-file F |
HQ Monitor sign-in, shared by all instances of the host: given on one instance, it changes the sign-in of all | admin + generated password; an update or a further instance keeps the existing sign-in |
--email ADDR --accept-privacy [--trial-zone RU|EU|BR] |
Trial email (30 days); the address is sent to the vendor’s trial server | none |
--auto-update all|agent|off |
Updates of a server attached to no HQCenter (kits from 2027.2.31): agent = the agent, HQ Monitor and fbmcp update by themselves, a Firebird package waits for you; all = Firebird too, in its window; off = no update checks (“Updates without HQCenter” in section 4) |
the mode is not changed; a new agent has agent |
--license F |
License file to install | none |
--attach F |
Attach to your HQCenter (attach.json) |
none |
--no-hqbird, --disable-hqbird |
Leave the older HQbird alone / turn all its units off | automatic |
--no-debug |
Do not install the Firebird debug files | installed |
--no-fbmcp |
Do not install fbmcp (the MCP server for AI clients) and do not change the fbmcp of this host | installed |
--fbmcp-allow-from A,B |
Turn on the remote mode of fbmcp for these admin addresses (IP or CIDR) | local only |
--fbmcp-port N, --fbmcp-dns NAME,..., --fbmcp-ip ADDR |
The remote port of fbmcp; extra names for its certificate; the address for the certificate and the listener | port 8650 |
--rcm on|off |
Install the cluster console RCM on this host and make a new cluster (agent 3.1.0 and later) | asked; No |
--rcm-password-file F |
RCM admin password with --rcm on (first line of F) |
generated, shown at the end |
--cluster-id ID |
Cluster id with --rcm on |
the host name |
--cluster-pairing on|off |
Discovery mode: the pairing window for 24 hours, an RCM may invite this agent | asked; No |
--rcm-allow A,B,... |
Only these RCMs may invite this host in discovery mode (IP, CIDR or host name) | any RCM |
--pairing-port N |
Pairing port 7450–7459 of a new agent; it picks the slot (node ports 7051+k, 7061+k). A later setup keeps the slot | the first free slot |
--cluster-node on|off |
Put the cluster node service into the agent’s cache | on |
--yes |
Answer Yes to the questions of the plan (No to the cluster questions) | ask |
--check |
Only the checks, the libraries and the plan; nothing is changed | — |
--plan-help |
Print what the codes of the plan mean (M1, M2, …) and exit | — |
--no-tui |
The plain installer, without the text interface; also the variable HQBIRD_NO_TUI=1 (“The plain installer” in section 3) |
the text interface in a terminal |
--lang en|ru|pt-BR|de |
Language of the installer; also the variable HQBIRD_LANG (“Language of the installer” in section 3) |
the UTF-8 locale of the console, else English |
--tmpdir DIR |
Unpack here (a folder where programs may run) | /var/tmp |
--extract DIR |
Only unpack the payload into DIR/payload and exit |
— |
--uninstall [--remove-data] [--force] [--agent-dir DIR] |
Remove the agent and HQ Monitor (Firebird stays); --force also removes the agent that runs the RCM of the host while other agents use it |
— |
Options can be written as --port 3055 or --port=3055. Relative paths
count from the current folder.
Examples
New installation with the defaults:
sudo sh hqbird2027-fb50-linux-2027.2.9.run --yes
echo "exit code $?"New installation into a chosen folder and port, with a SYSDBA password from a file and an HQ Monitor sign-in:
umask 077
printf '%s\n' 'S3cret-Sysdba' > /root/sysdba.txt
printf '%s\n' 'S3cret-Monitor' > /root/hqm.txt
sudo sh hqbird2027-fb50-linux-2027.2.9.run --yes \
--fb-root /opt/firebird --port 3050 \
--sysdba-pass-file /root/sysdba.txt \
--hqmonitor-port 24000 --hqmonitor-login ops --hqmonitor-password-file /root/hqm.txt
rm -f /root/sysdba.txt /root/hqm.txtNew installation with the trial email, a license file and the attach file:
sudo sh hqbird2027-fb50-linux-2027.2.9.run --yes \
--email [email protected] --accept-privacy --trial-zone EU \
--license /root/hqbird-license.json \
--attach /root/attach.jsonUpdate of an older HQbird, all older HQbird units off:
sudo sh hqbird2027-fb50-linux-2027.2.9.run --yes --disable-hqbirdUpdate of HQbird 2027 to a new version (one instance; with several, add
--fb-root and --port):
sudo sh hqbird2027-fb50-linux-2027.2.9.run --yesA second Firebird 5.0 instance on port 3056:
sudo sh hqbird2027-fb50-linux-2027.2.9.run --yes --fb-root /opt/fb50-2 --port 3056Removal:
sudo sh hqbird2027-fb50-linux-2027.2.9.run --uninstall
sudo sh hqbird2027-fb50-linux-2027.2.9.run --uninstall --remove-dataA script that stops on a failed installation:
#!/bin/sh
set -e
sh hqbird2027-fb50-linux-2027.2.9.run --yes || {
rc=$?
echo "HQbird setup failed with code $rc, see /var/log/fbagent/install.log" >&2
exit $rc
}
echo "HQbird 2027 installed"Server without Internet: OS libraries
The Firebird of a line needs these libraries from the OS (besides glibc):
| Line | Packages (Debian/Ubuntu) | Packages (RHEL family) |
|---|---|---|
| 5.0 | libtommath1, libicu<NN>, libgssapi-krb5-2 |
libtommath (EPEL), libicu, krb5-libs |
| 4.0 | libtommath1, libicu<NN> |
libtommath (EPEL), libicu |
| 3.0 | libtommath1, libicu<NN> |
libtommath (EPEL), libicu |
| 2.5 | usually nothing (libstdc++6 is in the base system) |
usually nothing |
Kits after 2027.2.30 of the lines 3.0, 4.0 and 5.0 also need the program
colrm, which the Firebird install script uses: package bsdextrautils
(bsdmainutils on older Debian and Ubuntu). A minimal Debian has none; the
RHEL family has it in util-linux, which is always there.
When a package is missing and the repository is not reachable, the installer stops with exit code 6 and nothing is changed:
[install] ERROR: no access to the package repository, or a package is not there; nothing was changed.
[install] Missing: libtommath1
[install] Install them, then run this file again:
[install] apt-get install -y libtommath1
[install] On a server without internet: on a PC with the same Ubuntu 24.04.5 LTS
[install] apt-get download libtommath1
[install] copy the .deb files here and run: apt-get install -y ./*.debOn the RHEL family libtommath is in EPEL: with a reachable repository the
installer adds epel-release itself. Without one, the commands are dnf install -y epel-release, dnf download --resolve <packages> and dnf install -y ./*.rpm. --check prints
the same list in advance, so the packages can be prepared before the
installation window.
Exit codes
| Code | Meaning | Changes on the host |
|---|---|---|
| 0 | Done (warnings about the trial email, the attach or the license are in the summary) | yes |
| 1 | Refused: the host, an option, a file, or the plan (the reason is printed). Also: Quit in the text interface | none |
| 2 | The installation failed and was rolled back. Also: the installer was stopped by a signal (Ctrl+C) | rolled back; none when stopped before the installation |
| 3 | The installation failed and the rollback was not complete (the summary says what to check) | partly |
| 4 | A question of the plan was not confirmed (no terminal, no --yes). |
none |
| 5 | The payload did not pass the check (sha256, signatures): download the file again. With --uninstall: refused, the agent runs the RCM of the host and other agents use it (section 7) |
none |
| 6 | OS libraries are missing and the package repository is not reachable | none |
| 7 | A Firebird from the distribution’s packages is installed | none |
10. Troubleshooting
| Problem | What to do |
|---|---|
run as root (sudo sh ...) |
Run the installer with sudo or as root |
| The pages of the text interface do not open | The first line says why: needs a window of 80x24 or larger (make the window larger; tmux with a status line takes one row) or needs bash 4.4 or newer. The plain installer that runs then does the same installation |
| Wrong characters or broken lines on the pages | Set the terminal to UTF-8, or run with --lang en; --no-tui runs the plain installer |
/var/tmp is mounted noexec |
Run again with --tmpdir /root (any folder where programs may run) |
is damaged or cut (exit code 5) |
Copy the .run file again and compare its sha256sum with the published value |
| Exit code 6, libraries missing | Prepare the packages as printed (section 9), then run the installer again |
| Exit code 7, Firebird from the distro packages | Remove the packages (apt-get remove firebird3.0-server, keep a gbak backup) or use the online installer with --import-firebird |
refused (M17): Firebird 2.5 works only in /opt/firebird |
A second Firebird 2.5 is not possible; install another line next to it (section 7) |
--uninstall refused (exit code 1) with several agents |
Add --agent-dir with a folder from the list, for example --agent-dir /opt/hqbird/fbagent-fb50-2 |
--uninstall refused (exit code 5): this agent runs the RCM of the host |
Remove the cluster in the RCM console first, or run again with --force (section 7) |
no permission for read-write access to employee.fdb after an update (3.0) |
sudo chmod 660 /opt/firebird/examples/empbuild/employee.fdb (section 6) |
refused (M14): the folder is not empty |
Choose an empty or new folder with --fb-root, or name the Firebird to update |
| Exit code 2 or 3 | Read /var/log/fbagent/install.log; the units are back to their state before the run (code 2) or need a check (code 3) |
| HQ Monitor does not open | systemctl status hqbirdmonitor-fb50 (hqbirdmonitor-p<port> before 2027.2.9); check that nothing else listens on the port; open the port in the firewall; --hqmonitor-port for another port |
| Lost the HQ Monitor password | Run the installer again (repair) with --hqmonitor-login admin --hqmonitor-password-file <file>; the old /opt/hqbird/conf/access.properties is kept as access.properties.bak-<time>. The new sign-in holds for all instances of the host |
| The trial email was not sent (no network) | Send it later: cd /opt/hqbird/fbagent-fb50 && sudo -u firebird ./fbagent --trial-email <address> --accept-privacy |
| SELinux (AlmaLinux, RHEL) | Supported in enforcing mode: the installer restores the contexts of the files it writes; nothing to do |