fbmgr on Linux systems
On Linux, the Firebird engine is started whenever you carry out an install — from an RPM or via a script — and at system boot time. This means that Firebird is available whenever your system is running once you have Firebird installed.
At boot time, the script /etc/init.d/firebird is executed to start up the Firebird engine on Suse servers, other Linux servers use the script /etc/rc.d/init.d/firebird instead. The same script is executed just before the server shuts down to stop the Firebird engine. The engine runs as the firebird user and not as root.
The script is installed to the location described above, and a symbolic link is created to /usr/sbin/rcfirebird and the script can therefore be called in both ways, whichever you find easiest, but you must be the root user:
This script can take one of the following parameters:
Starts the Firebird engine. If already running, does nothing. The engine is started under the watchful eye of the guardian process ( fbguard ) and is set to automatically restart if the engine fails for any reason. The engine runs under the firebird user even though you have to be root to run the rcfirebird script.
Stops the Firebird engine. If already stopped, does nothing. It kills the process for the running engine by reading the pidfile (by default /var/run/firebird/firebird.pid ). If the process is not running, no error is reported.
Checks the current status of the Firebird engine. This command can return a status code (in $? ) as follows:
tux> rcfirebird status ; echo $?
- — 0 — the engine is running.
- — 1 — the engine was not running but the pidfile was found.
- — 2 — the engine was not running but the lock file was found.
- — 3 — the engine was not running.
Note: The status parameter is not available on every Linux distribution. You can check if it is available on your installation by running the rcfirebird command with no parameters:
tux> rcfirebird Usage: /usr/sbin/rcfirebird
The command will list all the options available for your particular installation.
Restarts the Firebird engine but only if it is currently running, otherwise, does nothing.
Stops and restarts the Firebird engine, whether it was running or not.
This is exactly the same as the restart command.
Reload is not implemented.
It might be necessary for you to manually shut down the engine from time to time, and to restart it again afterwards. To do this, and assuming that either none of the options to rcfirebird are suitable or you do not have root privileges, fbmgr is your tool. fbmgr is, by default, available to all users of the system to execute — however, in order to start and stop the Firebird engine, root or SYSDBA rights are required.
Caution: It is noted that the default shell for the firebird user (at least of Suse systems) defaults to /bin/false and so, you cannot log in as the firebird user. This means that you must use rcfirebird to start and stop the engine because if you use fbmgr as root, then all databases created by the engine will be owned by root.
In order to allow the firebird user the ability to start and stop the database engine, you need to alter the default shell from /bin/false to something like /bin/bash and set a password, while logged in as root, as follows:
tux> usermod --shell /bin/bash firebird tux> passwd firebird
fbmgr is a very short shell script which currently — as of version 2.1.3 — exports the FIREBIRD environment variable and calls fmbgr.bin passing all supplied parameters over, so fbmgr.bin does all the hard work.
As the two are interchangeable, I shall use the former (and shorter!) fbmgr in the remainder of this chapter.
fbmgr commands
fbmgr can be run interactively or in batch mode. The commands are identical whichever mode you use and the following section describes the commands and shows examples of each, running in both modes.
To enter interactive mode, simply log in as the firebird user and type the command fbmgr . If /opt/firebird/bin is not on your path, type the command bin/fbmgr instead.
Note: When you log in as the firebird user, the home directory ( $HOME ) is set to be /opt/firebird . The bin subdirectory, where all the firebird binaries live, is immediately beneath $HOME .
Getting help
To see a list of all the commands — except, for some reason, the start command — run fbmgr and pass the — help command (in batch mode) or type help at the prompt in interactive mode. The resulting output is the same regardless, including the grammatical error «. also be used as an option switches . » :
tux> fbmgr -help Usage: fbmgr -command [-option [parameter]] or fbmgr FBMGR> command [-option [parameter]] shut [-now] shutdown server show show host and user user set user name password set DBA password pidfile file to save fbserver's PID help prints help text quit quit prompt mode Command switches 'user' and 'password' can also be used as optional switches for commands likestartorshut. For example, to shutdown the server you can: fbmgr -shut -password or fbmgr FBMGR> shut -password or fbmgr FBMGR> password FBMGR> shut
Note: When using this option under Firebird 2.5, an additional line is printed at the beginning of the output advising you that fbmgr is deprecated and will be removed soon.
Starting up
When the Firebird engine is started, it normally runs under the watchful eyes of the guardian process — fbguard . 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. fbmgr allows the DBA or System Administrator to decide which of the two startup methods will be used.
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 fbmgr you would carry out one of the following:
tux> fbmgr -start -forever server has been successfully started
tux> fbmgr FBMGR> start -forever server has been successfully started
If you are logged in as a privileged user then you don’t need to specify a -user as these login accounts default to SYSDBA when fbmgr is run. If you log in as any other user, even supplying a user name will not be enough to allow you to restart a closed database engine.
Note: A privileged user is one that the Firebird engine considers to be privileged enough to automatically be given SYSDBA rights. This means that it can start and stop the engine without being required to authenticate as SYSDBA. At present there are four login names that are assumed to be privileged, these are:
The start command defaults to -forever if nothing is specified.
tux> fbmgr -start server has been successfully started
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 fbmgr as the following shows:
tux> fbmgr FBMGR> start -once
Shutting down
Shutting down the engine stops the guardian process from restarting it. If this was not the case, it would be very difficult to actually stop the Firebird engine!
Warning: Any user who has logged on to the database server and who is armed with the SYSDBA password, can close the engine down. This is a slight inconsistency as only the privileged users can start the engine.
If you are logged in as a privileged user, you do not need to supply a user name to shut down the engine, you are only required to supply the SYSDBA password.
tux> fbmgr -shut -password secret server shutdown completed
You are required to supply a user name if you log in as your own account.
tux> fbmgr -shut -password secret no permissions to perform operation tux> fbmgr -shut -user sysdba -password secret server shutdown completed
Showing details
The SHOW command displays the name of the server that you are running on and details of the user you are currently using. If you are running fbmgr as a privileged user, then the user will be SYSDBA unless you specified a different one with the -user parameter.
tux> fbmgr -show Host: localhost User: SYSDBA
You can supply a different user name on the command line if desired:
tux> fbmgr -show -username norman Host: localhost User: NORMAN
In interactive mode, the process is almost identical:
tux> fbmgr FBMGR> show Host: localhost User: SYSDBA
Or, using a different user name:
tux> fbmgr -user norman FBMGR> show Host: localhost User: NORMAN
It appears that the SHOW command always displays the hostname as localhost while you are logged onto that server. It is unfortunate that the SHOW command doesn’t show any details about the running (or otherwise) Firebird engine. You can find this out as follows:
tux> ps -ef|grep -i fire[b]ird firebird 3752 1 0 14:13 ? 00:00:00 /opt/firebird/bin/fbguard -o firebird 3753 3752 0 14:13 ? 00:00:00 /opt/firebird/bin/fbserver
Look closely at the process details for the guardian, you can see a -o parameter. This indicates that the engine is running and is in -once mode. If it crashes at any time, it will not be restarted by the guardian. In -forever mode, the parameter is -f .
If you don’t see either the guardian or the server processes, then you can assume that the (Superserver) engine is not running.
Tip: When using grep to filter out the interesting processes from a call to ps -ef , for example, using a character class for one single character prevents the grep process itself from being listed. The following two grep commands produce identical results but using the character class in the first saves having to call grep -v grep to filter out the unwanted grep process.
ps -ef | grep -i fire[b]ird ps -ef | grep -i firebird | grep -v grep
Exiting
The quit command gets you out of an interactive session. There is no quit command for batch mode.