fbmgr on Linux systems

<< Introduction | Firebird Superserver Manager | Fbguard on Linux systems >>

fbmgr on Linux systems

  1. fbmgr commands
    1. Getting help
    2. Starting up
      1. Start and stay running
      2. Start and stop running
    3. Shutting down
    4. Showing details
    5. Exiting

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: 

 tux> /etc/init.d/firebird <parameter>

or 

 tux> rcfirebird <parameter>

This script can take one of the following parameters:

  • start

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.

  • stop

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.

  • status

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 {start|stop|status|try-restart|restart|
 force-reload|reload}

The command will list all the options available for your particular installation.

  • try-restart

Restarts the Firebird engine but only if it is currently running, otherwise, does nothing.

  • restart

Stops and restarts the Firebird engine, whether it was running or not.

  • force-reload

This is exactly the same as the restart command.

  • reload

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.

back to top of page

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<RETURN>
                 FBMGR> command [-option [parameter]]

                 shut [-now] shutdown server
                 show show host and user
                 user <user_name> set user name
                 password <password> set DBA password
                 pidfile <filename> 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 like start or shut. 
 For example, to shutdown the server you can:

 fbmgr -shut -password <password>

 or

 fbmgr<RETURN>
 FBMGR> shut -password <password>

 or

 fbmgr<RETURN>
 FBMGR> password <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.

back to top of page

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

Or, in interactive mode: 

 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:

  • root
  • firebird
  • interbase
  • interbas (without the 'e')

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 -start -once

Or, running interactively: 

 tux> fbmgr
 FBMGR> start -once

back to top of page

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

back to top of page

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.

See also:
Download and install Firebird: POSIX platforms
Installing IBExpert under Linux
Firebird 2 migration and installation: Installing Firebird on POSIX platforms
Tracking down crashes on Linux
Choosing a file system on Linux for Firebird

back to top of page
<< Introduction | Firebird Superserver Manager | Fbguard on Linux systems >>