| Firebird Documentation Index → Firebird 2.0.6 Release Notes → INSTALLATION NOTES |
|
|
|
Table of Contents
Please read the previous chapter, Known Compatibility Issues before you set out to install Firebird 2.0.
On Windows, you have three server models to choose from: Superserver, Classic and Embedded Server. This means you have some decisions to make before installing Firebird 2.0.
Make sure you are logged in as Administrator (doesn't apply on Win9x or ME)
Check to make sure that there is no FIREBIRD environment variable defined that is visible to Administrator-level users or to the LocalSystem user--see the section called “The FIREBIRD Variable” at the start of the previous chapter.
The Superserver and Classic models, as well as server tools-only and client-only, can be installed using the Windows installer application. For a full-release install, it is highly recommended to use the installer if there is one available.
Use gbak to back up your old security.fdb (or, for a previous Firebird 1.0 installation, isc4.gdb) security database. You can restore it later as security2.fdb, using the directions in the chapter entitled New Security Features.
If you have special settings in your existing firebird.conf (ibconfig, for Firebird 1.0) there may be some values that you want to transfer to equivalent parameters in the new firebird.conf. When you use the Windows control panel applet “Add/Remove Programs” to uninstall Firebird 1.5.x (recommended!), the uninstaller should preserve your existing firebird.conf and aliases.conf. However, it won't hurt to take the precaution of backing up these files to your home directory. The Firebird 1.0.x ibconfig file (if applicable) should certainly be backed up.
If you are upgrading from Firebird 1.0.x, go to the Downloads/Firebird Database Engine page at the Firebird website and download the Firebird 1.5.3 releasenotes for details of the correlation between settings in ibconfig and firebird.conf. Study the notes about firebird.conf to work out what can be copied directly and what parameters require new syntax.
When reinstalling Firebird 2.0, certain configuration files in the installation directory will be preserved if you run the installer and OVERWRITTEN if you decompress a zip kit into the default location. The files are
security.fdb
firebird.log
firebird.conf
aliases.conf
Each model can be installed from a zipfile. This method will be faster than the installer if you have plenty of experience installing Firebird from zipfiles. It will be highly exasperating if you are a Firebird newbie.
It is assumed that.-
you understand how your network works
you understand why a client/server system needs both a server and clients
you have read the rest of these release notes--or at least realise that you need to read them if something seems to have gone wrong
you know to go to the firebird-support list if you get stuck. Join at http://www.yahoogroups.com/groups/firebird-support
If you already have an earlier version of Firebird or InterBase® on your server and you think you might want to go back to it, set up your fall-back position before you begin.
Use the existing version of GBAK to back up your database files in transportable format
Go to your System directory and make backup copies of fbclient.dll and/or gds32.dll if you have applications that rely on finding those libraries there. You might want to name the backup "gds32.dll.fb15" or "gds32.dll.fb103" or something similarly informative; or hide it in another directory
It might be a good idea to make a backup of the Microsoft C and C++ runtimes, msvcp71.dll and msvcr71.dll, too, if they are present on your system. The installer shouldn't overwrite your versions of these files, but strange things have been known to happen.
STOP ANY FIREBIRD OR INTERBASE SERVER THAT IS RUNNING
The installer will try to detect if an existing version of Firebird or InterBase is installed and/or running. In a non-installer install, you are on your own!
Provided you do not have a FIREBIRD environment variable defined, the default root location of Firebird 2.0 will be C:\Program Files\Firebird\Firebird_2_0.
For installing Firebird as a service: if you want to make use of the secure login feature, create a "firebird service user" on the system--any name and password you like--as an ordinary user with appropriate privileges.
You should read the document named README.instsvc.txt first. If you have a zip kit, you will find it in the /doc directory of the zipfile's root. If you don't have a zip kit available, the file won't be available until after the installation. You can read the same document at this URL: http://firebird.cvs.sourceforge.net/firebird/firebird2/doc/README.instsvc
Note that the recommended extension for database files on Windows ME and XP is ".fdb" to avoid possible conflicts with "System Restore" feature of these Windows versions. Failure to address this issue on these platforms will give rise to the known problem of delay on first connection to a database whose primary file and/or secondary files are named using the ".gdb" extension that used to be the Borland convention for suffixing InterBase database file names.
The issue is described in more detail in Other Win32 Issues at the end of the Windows installation notes.
One of the design goals, since Firebird 1.5, has been to prepare the way for running multiple Firebird servers simultaneously on the same host machine. Firebird 2.0 does support this, although it is not well documented and very much requires intervention from a skilled user. A future sub-release of Firebird 2.0 will make this process far less complicated to install and manage.
If you are experienced with Firebird and have a requirement to run multiple Firebird servers side by side, please consult Chapter 9 the Firebird 1.5.x release notes for details of how to achieve it.
The problems associated with installing different versions of Microsoft system libraries are so notorious that it has acquired the name 'DLL Hell'. From the release of Windows 2000 onwards Microsoft have made it almost impossible to upgrade system dll's. To resolve this Microsoft now recommends that each application installs local copies of any system libraries that are required.
Firebird 1.5 follows this practice and places the required libraries in the \bin directory along with the server.
Since Firebird 1.5, gds32.dll is not the “native” name of the client library. It is now called fbclient.dll. Given the problems that Microsoft have had with DLL hell it wouldn't make much sense if we continued to store the Firebird client library in the system directory. Furthermore, as we want to allow multiple engines to run simultaneously we would be creating our own DLL hell if we continued the practice of using the system directory for the client library.
So, from Firebird 1.5 on, the client library resides in the \bin directory along with all the other binaries. The installer provides the option (unchecked) to copy the client to the system directory for those who have applications that require to load them from there.
A Registry key has been added and all Firebird 2.0 compliant applications should use this key if they need to read a Registry key to locate the correct version of Firebird that they wish to use. The new key is:
HKEY_LOCAL_MACHINE\SOFTWARE\Firebird Project\Firebird Server\Instances
Firebird will guarantee that one entry under this key always exists. It will be known as
"DefaultInstance"
and will store the path to the root directory of (yes, you've guessed it) the default installation. Those who don't care about particular installations can always use the default instance to locate the fbclient.dll.
Future versions of Firebird will see other entries under Instances. Applications will be able to enumerate the Registry entries to determine which Server instance they wish to load.
Traditionally, applications that use InterBase or Firebird have expected to load the gds32.dll client library from the system directory. Firebird 2.0 ships with a tool named 'instclient.exe' that can install a clone of fbclient.dll to the Windows System directory. This clone gets patched on the fly so that its file version information begins with "6.3", to provide compatibility for old applications that check the GDS32.DLL file version and can not make sense of a number string such as "2.0".
This 'instclient.exe' tool can also install the FBCLIENT.DLL itself in the Windows system directory, if required. This will take care of tools or applications that need to load it from there.
The instclient.exe utility should be located in the 'bin' directory of your Firebird installation and must be run from there in a command shell.
Usage of instclient.exe:
instclient i[nstall] [ -f[orce] ] library
q[uery] library
r[emove] library
where library is: fbclient | gds32
'-z' can be used with any other option, prints version.
Version information and shared library counts are handled automatically. You may provide
the -f[orce] option to override version checks.
If you -f[orce] the installation, it could break another Firebird or
InterBase® version already installed. You might have to reboot the machine in order to finalize the
copy.
For more details, see the document README.Win32LibraryInstallation.txt which is located in ..\doc.
Don't overlook the need to have the Microsoft® Visual C and Visual C++ runtimes (msvcr71.dll and msvcp71.dll, respectively) present in the system directory of all Windows servers and clients, including Windows Embedded installations. For your convenience, copies of these libraries will be placed in the \bin directory of the Firebird install. However, you should check first whether later versions of these libraries are already present. Don't overwrite later versions.
This is really the easy part: the actual install. Just run the executable and respond to the dialogs. After you have answered a few dialogs about licensing and installation notes, you should see one where you decide on the location of the Firebird root directory.
The installer should be showing “c:\Program Files\Firebird\Firebird_2_0” by default. If you decide not to use the default root location, browse to a location you have pre-created; or just type in the full path and let the installer find it. The path you type in doesn't have to exist: the installer will prompt you and create it if it doesn't exist.
Here you can also opt not to have the installer create Startup Menu icons by checking off the option. If you are installing on Windows 9x or WinMe, or you plan to run the server as an application in another Win32 environment, keep the icons option checked on.
Next, you should see a screen where you choose the installation you want:
 |
Choose the installation you want and hit the "Next" button to carry on responding to dialogs.
If you're installing a server, you should choose Superserver (preselected by the installer) or Classic (as seen in the image above). Leave “Server components” and “Developer and admin tools components” checked on.
For a client-only install, check off “Server components”, leaving “Client components” and, optionally, “Developer and admin tools components” checked on.
There is also a drop-down for a custom installation which new users can safely ignore.
The next screen of interest enables you to set up how you want the server to run.
 |
Choose the options you want, according to your choice of server model.
Guardian is a utility than can run "over the top" of Superserver and restart it if it crashes for any reason. If you chose the Classic server, the Guardian option should not appear. If it does, check it OFF and report it in Tracker as a bug.
For deployment of Superserver on Win9x, WinME and WinNT 4.0, using Guardian can avoid the situation where the server stops serving and nobody can find the DBA to restart it. On other Win32 platforms, you can set the operating system to restart the service instead and not bother with the Guardian.
If you select to install Superserver or Classic, and your OS version supports services, you will be asked to choose whether to run Firebird as a service or as an application. Unless you have a compelling need to run the server as an application, choose service.
With the automatic option, Firebird will start up whenever you boot the host machine. With the manual option you can start the server on demand from the Services applet in the Settings/Control Panel/ Administration Tools selection.
If Superserver is being installed, you will see an option to “Install Control Panel applet?”. Unless you are installing on Vista, it's a good idea to keep this as it places an applet in the Control Panel from which you can stop and [re]start the server.
The Firebird Control Panel applet will break the Control Panel on Vista. If the installer displays this option you MUST ensure it is checked OFF.
Eventually, the dialogs will stop, you will press “Install” and the server will either silently start the server (if you requested it) or prompt you for permission to reboot. Reboot will be needed if the installer was unable to update a DLL due to its being already loaded when the installer started up.
If you are going to uninstall Firebird, first shut down all connections to databases and then, if you are running Superserver, shut down the server. The Firebird uninstall routine (run from Add/Remove Programs in the Control Panel) preserves and renames the following key files:
preserves security2.fdb or renames it to security2.fbnnnn
preserves firebird.log
preserves firebird.conf or renames it to firebird.confnnnn
preserves aliases.conf or renames it to aliases.confnnnn
"nnnn" is the build number of the old installation.
No attempt is made to uninstall files that were not part of the original installation.
Shared files such as fbclient.dll and gds32.dll will be deleted if the share count indicates that no other application is using them.
The Registry keys that were created will be removed.
The installation of FB 2.0 is similiar in principle to previous versions. If you don't have a special setup program (it's distributed separately) the steps are the following:
unzip the archive into a new directory
change the current directory to $FIREBIRD\bin (here and below, $FIREBIRD refers to the directory where the v.2.0 files are located)
run instreg.exe:
instreg.exe install
It causes the installation path of the directory above to be written into the registry (HKLM\Software\Firebird Project\Firebird Server\Instances\DefaultInstance)
if you want to register a service, also run instsvc.exe:
instsvc.exe install
optionally, you may need to run instclient.exe to copy fbclient.dll or a specially-generated clone as gds32.dll to the OS system directory
To install the CS engine, the only difference is the additional switch for instsvc.exe:
instsvc.exe install -classic
Notice that this means that you may have only one architecture of the engine--either fbserver.exe (Superserver) or fb_inet_server.exe (the parent process for Classic)--installed as a service.
The Control Panel applet is not installed with Classic--deliberately. Don't try to install and use it. The concept of terminating a service does not apply to the Classic model.
If you don't need a registered service, then you may avoid running both instreg.exe and instsvc.exe. In this case you should just unzip the archive into a separate directory and run the server as an application:
fbserver.exe -a
It should treat its parent directory as the root directory in this case.
Firebird requires WinSock2. All Win32 platforms should have this, except for Win95. A test for the Winsock2 library is made during install. If it is not found the install will fail. To find out how to go about upgrading, visit this link.
Windows ME and XP (Home and Professional editions) have a feature called System Restore, that causes auto-updating (backup caching?) of all files on the system having a ".gdb" suffix. The effect is to slow down InterBase/Firebird database access to a virtual standstill as the files are backed up every time an I/O operation occurs. (On XP there is no System Restore on the .NET Servers).
A file in the Windows directory of ME, c:\windows\system\filelist.xml, contains "protected file types". ".gdb" is named there. Charlie Caro originally recommended deleting the GDB extension from the "includes" section of this file. However, since then, it has been demonstrated that WinME might be rebuilding this list. In XP, it is not possible to edit filelist.xml at all.
On ME, the permanent workarounds suggested are one of:
use FDB (Firebird DB) as the extension for your primary database files--RECOMMENDED
move databases to C:\My Documents, which is ignored by System Restore
switch off System Restore entirely (consult Windows doc for instructions).
On Windows XP Home and Professional editions you can move your databases to a separate partition and set System Restore to exclude that volume.
Windows XP uses smart copy, so the overhead seen in Windows ME may be less of an issue on XP, for smaller files at least. For larger files (e.g. Firebird database files, natch!) there doesn't seem to be a better answer as long as you have ".gdb" files located in the general filesystem.
Some changes between Firebird 1.5 and Firebird 2.0 mean the existing docs are slightly out-of-date. For convenience, the following are the updated notes.
The embedded server is a fully functional server linked as a dynamic library (fbembed.dll). It has exactly the same features as the usual Superserver and exports the standard Firebird API entrypoints.
The embedded server acts as a true local server for a single client accessing databases on a local machine. It can also act as a remote gateway that redirects all network calls to other hosts, just as the regular client library does.
The Firebird Registry entries are ignored. The root directory of the embedded server is the same directory as the one where the embedded library binary is located.
Client access can be only via the local (XNET) protocol, i.e. NOT a TCP/IP local loopback connection string that includes the server name “localhost” or the IP address 127.0.0.1. The embedded server supports only the local connect to an absolute database file path without a server name.
Do not try to connect to any mapped location, even one that is physically located on the same machine.
The client program gets exclusive access to the database file after successful connect.
The security database (security2.fdb) is not used in connecting to the embedded server. Hence it is not required. Any user is able to attach to any database. Since both the server and the client run in the same address space, security becomes just an agreement between the accessor and the accessed, which can be easily compromised.
SQL privileges are still checked and enforced. Users that are assigned privileges in a Firebird database are not dependent on the existence of the user in the security database. Applications may still validly pass a user name in the database connection attributes.
You may run any number of applications with the embedded server without any conflicts. Having a full Firebird or InterBase server running on the same machine is not a problem either.
However, be aware that you cannot access a single database from a number of embedded servers simultaneously, regardless of whether they be embedded or full servers. An embedded server has the SuperServer architecture and hence exclusively locks any database it attaches to.
The MS runtime libraries msvcp71.dll and msvcr71.dll must be available in the embedded library's path. You can extract copies of these libraries from the zip kit version of the full Firebird build if they are not already present on your system.
Just copy fbembed.dll, icudt30.dll, icuin30.dll and icuuc30.dll into the directory with your application exectable.
You should also copy firebird.msg and firebird.conf (if necessary) to the same directory.
You will need firebird.conf only if it is necessary to set some non-default configuration parameter for the embedded server.
If external libraries are required for your application, such as INTL support (fbintl.dll and fbintl.conf) or UDF libraries, create subdirectories beneath the application root for them, emulating the Firebird server ones, e.g. /intl or /udf, respectively.
Rename fbembed.dll to either fbclient.dll or gds32.dll, according to which is required by your database connectivity software.
Now start your application and it will use the embedded server as a both a client library and a server and will be able to access local datasases via the XNET network emulation protocol.
c:\my_app\app.exe
c:\my_app\gds32.dll
c:\my_app\ib_util.dll
c:\my_app\icudt30.dll
c:\my_app\icuin30.dll
c:\my_app\icuuc30.dll
c:\my_app\firebird.conf
c:\my_app\firebird.msg
c:\my_app\intl\fbintl.dll
c:\my_app\intl\fbintl.conf
c:\my_app\udf\fbudf.dll
Suppose you want to place the Firebird files (excluding the renamed fbembed.dll) in another directory. In that case, you need to modify your firebird.conf and set RootDirectory to the Firebird directory tree that is parent to the Firebird files.
Example
c:\my_app\app.exe
c:\my_app\gds32.dll
c:\my_app\ib_util.dll
c:\my_app\icudt30.dll
c:\my_app\icuin30.dll
c:\my_app\icuuc30.dll
c:\my_app\firebird.conf
d:\fb\firebird.msg
d:\fb\intl\fbintl.dll
d:\fb\intl\fbintl.conf
d:\fb\udf\fbudf.dll
In firebird.conf:
RootDirectory = d:\fb
|
| Firebird Documentation Index → Firebird 2.0.6 Release Notes → INSTALLATION NOTES |