| Firebird Documentation Index → Firebird Superserver Manager → 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.
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.
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 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.
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.
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 an option switches for commands like start or shut.
For example, to shutdown server you can:
fbmgr -shut -password <password>
or
fbmgr<RETURN>
FBMGR> shut -password <password>
or
fbmgr<RETURN>
FBMGR> password <password>
FBMGR> shut
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.
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.
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.
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
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
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!
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
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 host name 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.
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
|
| Firebird Documentation Index → Firebird Superserver Manager → Fbmgr on Linux Systems. |