`fbguard` on Linux systems

From Firebird 2.5 onwards the use of fbmgr is deprecated and from Firebird 3.0, it will be removed. The fbguard utility, which was actually used by fbmgr, should be used instead. The system start and stop scripts, as described in the previous chapter, use fbguard to start and stop the Firebird engine at system startup and shutdown.

`fbguard` commands

Warning: For best results and security, you are advised to always start and stop the Firebird engine using the default scripts /etc/init.d/firebird or the alias rcfirebird. These scripts carry out various checks to ensure that the engine runs as the correct user, makes sure that the guardian process watches over the engine and so on. Running fbguard on its own makes no such checks and can lead to databases becoming unavailable due to being owned by root, for example - because this command always runs the Firebird engine as the root user.

fguard cannot be run interactively, you must supply the required commands on the command line when executing fbguard. fbguard can be run as the firebird user, for example, but will always cause the engine itself to run as root. This may be a cause of serious concern for system administrators. If you create any databases while the engine is running as root then those databases will be owned by root and you will not be able to access it at some future point when the engine runs - correctly - as the firebird user.

If you always use the /etc/init.d.firebird (or rcfirebird) command to start and stop the engine, it will always run as the firebird user, regardless of which user you actually run the command as.

Note: You cannot mix and match the various methods of starting and stopping the engine. If you use fbguard to start the engine, you need to kill the fbserver process to stop it. If you use /etc/init.d/firebird (or rcfirebird) to start the engine, you must use the corresponding stop script. You cannot shut down the engine with rcfirebird stop, for example, if you started it with fbguard.

Getting help

To see a list of all the commands run fbguard passing the -help command. The resulting output is as follows:

 tux> cd /opt/firebird/bin
 tux> ./fbguard -help
 Usage: fbguard [-signore|-onetime|-forever (default)][-daemon][-pidfile filename]

The use of the -daemon option forces the engine to run as a daemon. If you run the fbguard command to start the engine from a terminal session, your terminal will hang.

By default, fbguard will use its own default location to store the file that holds the process id of the running Firebird engine. You may tell it to use a specific pidfile, if you wish, by specifying the -pidfile option. The default is /var/run/firebird/default.pid.

Note: In Firebird 2.50 and 2.5.1, on the OpenSuse platform, the default pidfile is named /var/run/firebird/.pid because of a bug in the /etc/init.d/firebird script where the variable INSTANCE is not defined. It should be defined with a value of default.

Starting up

When the Firebird engine is started at system boot or by the /etc/init.d/firebird script, it runs under the watchful eyes of the guardian process. The guardian will restart the engine any time it determines that the engine has crashed and in doing so, will hopefully reduce the downtime that the users may suffer as a result of a crashed engine. It is possible, however, to force the engine to be started up and the guardian will allow it to stay down if it detects a crash.

As mentioned above, regardless of the user you are logged in as when you execute the fbguard command, the engine always runs as the root user.

Regardless of the start mode chosen, the -signore option can be used to indicate that startup errors are to be ignored, and fbguard is to continue to attempt to startup the engine. Startup errors include problems such as port 3050 already being used, etc. Normally, on a startup error fbguard will make no further attempt to start the engine.

Start and stay running

At system boot time, the engine is started in the mode that allows the guardian to restart it in the event of a crash. To perform this task manually using fbguard you would carry out the following process:

 tux> fguard -forever -daemon

The command defaults to -forever if nothing is specified.

 tux> fguard -daemon

Start and stop running

Under normal circumstances you would wish for the database engine to remain running as long as possible. At other times, however, you may wish for any crashes to be investigated prior to restarting the engine. This is possible using fbguard as the following shows:

 tux> fguard -onetime -daemon

Shutting down

There is no fbguard command line option that shuts down the running Firebird engine. To do so requires that you kill the running process as root.

 tux> ps -ef| grep -i fire[b]ird
 root 11556 11555 0 12:18 ? 00:00:00 /opt/firebird/bin/fbserver

 tux> kill 11556

 tux> ps -ef| grep -i fire[b]ird
 ## No output shown ##

Note: The fbserver process is always listed as running from /opt/firebird as per the output from the various grep commands above. The fbguard process, on the other hand, doesn't show the full path unless it was started using the full path, as follows:

 tux> cd /opt/firebird/bin
 tux> ./fbguard -forever -daemon

 tux> ps -ef | grep -i fire[b]ird
 root 11794 11793 0 12:32 ? 00:00:00 /opt/firebird/bin/fbserver

 tux> ps -ef|grep -i fb[g]uard
 root 11793 1 0 12:32 ? 00:00:00 ./fbguard -forever -daemon

 tux> kill 11794

 tux> /opt/firebird/bin/fbguard -forever -daemon

 tux> ps -ef | grep -i fire[b]ird
 root 11838 1 0 12:34 ? 00:00:00 /opt/firebird/bin/fbguard -forever -daemon
 root 11839 11838 0 12:34 ? 00:00:00 /opt/firebird/bin/fbserver