Chapter 8. Environment variables

Firebird supports a number of environment variables to configure Firebird server and/or fbclient.

8.1. Standard environment variables

The following are the environment variables Firebird supports in normal builds. This documentation does not cover environment variables for debug builds.

8.1.1. EDITOR

Default text editor for isql.

ConfigurationClient

On Linux and other non-Windows OSes, EDITOR is only used if Section 8.1.13, “VISUAL” is not set.

Table 8.1. Default if neither VISUAL nor EDITOR is set:

Windows

Notepad

Linux and other OSes

vi

This is not a Firebird-specific environment variable, but a common convention for applications.

See alsoSection 8.1.13, “VISUAL”

8.1.2. FB_EXPECTED_DB

Default value of the expected database for Services Manager connections for use of a non-default security database.

ConfigurationClient

The value of this environment variable is a database alias or path. It is used — client-side — to set the value of SPB item isc_spb_expected_db if it was not explicitly set.

When establishing a Services Manager connection, the server looks up the databases.conf entry of the expected database, and uses its value of Section 3.1.67, “SecurityDatabase” as the security database. If there is no databases.conf entry, or the entry has no value for SecurityDatabase, the value from firebird.conf is used.

8.1.3. FIREBIRD

Overrides the Firebird root directory.

ConfigurationClient, Server/Embedded

The Firebird root directory determines where the server or client reads other configuration (e.g. firebird.conf) from. It also serves as the default location for firebird.msg1, if not overridden by Section 8.1.5, “FIREBIRD_MSG” or Section 8.1.9, “ISC_MSGS”

In general, this should only be set or changed to configure clients and embedded instances, not servers. An incorrect root directory for the server may result in the server using incorrect configuration, or not being able to load required plugins and other components.

8.1.4. FIREBIRD_LOCK

Overrides the location of the Firebird lock files and other shared memory files.

ConfigurationServer/Embedded

The value must be set to an absolute path on the physical filesystem of the host. The user running Firebird (or its embedded engine) needs to have sufficient privileges to create and delete files and subdirectories.

If there are multiple processes and/or different OS users accessing the same database files, they all need to use the same lock directory, and they all need sufficient privileges to this lock directory. On Linux, this is generally achieved by giving the permissions to the firebird group and adding the users to this group.

🛑
Incorrect use of FIREBIRD_LOCK can result in database corruption or other forms of data loss.

Database corruption can happen when multiple processes and/or multiple OS users open the same database with different lock directories. When using different lock directories, these processes cannot coordinate their access.

When in doubt, do not set this and use the server defaults.

This risk exists primarily when using Classic or SuperClassic (see also Section 3.1.76, “ServerMode”); SuperServer opens databases with exclusive access.

The default lock directory is:

Windows

Subdirectory firebird in the common appdata directory (CSIDL_COMMON_APPDATA) — for example C:\ProgramData\firebird — with a fallback to the Firebird root directory2.

Android

/data/local/tmp/firebird.

macOS

/tmp/firebird of or — if sandboxed — subdirectory firebird of the temporary directory of the current user.

Linux and other OSes

/tmp/firebird

8.1.5. FIREBIRD_MSG

Location of Firebird message files.

ConfigurationClient, Server/Embedded

This setting is primarily a client-side setting, but may get used by the server if it formats and prints messages itself.

How Firebird resolves a message file

  1. File specified by Section 8.1.9, “ISC_MSGS”

  2. Locale-specific file with relative path intl/locale.msg in the Firebird message directory (see The Firebird message directory)

    The value of locale is derived from the first 10 characters of the last segment of environment variable LC_MESSAGES (after the last /, or otherwise after the last \, otherwise the entire value)

  3. File firebird.msg in the Firebird message directory (see The Firebird message directory)

The Firebird message directory

  • The directory specified by environment variable FIREBIRD_MSG, or

  • the default Firebird message directory (if FB_MSGDIR was defined in the build configuration), or

  • the Firebird root directory (see Section 8.1.3, “FIREBIRD”).

See alsoSection 8.1.3, “FIREBIRD”, Section 8.1.9, “ISC_MSGS”

8.1.6. FIREBIRD_TMP

Default location for temporary files.

ConfigurationServer/Embedded

The directory specified in the FIREBIRD_TMP environment variables is used as the default location for temporary files.

The values of configuration items Section 3.1.5, “TempDirectories” and Section 3.1.6, “TempTableDirectory” take precedence.

The specified directory must exist. The user of the Firebird process — or the process running embedded — must have sufficient privileges to create, write, and delete files and directories in that directory.

If FIREBIRD_TMP is not specified, Firebird will fall back as follows:

Fallback on Android

  1. TMP (environment variable)

  2. Use /data/local/tmp

Fallback on macOS

  1. TMP (environment variable)

  2. Use /tmp or — if sandboxed — the temporary directory of the current user

Fallback on Linux and other non-Windows OSes

  1. TMP (environment variable)

  2. Use /tmp

Fallback on Windows

  1. Result of GetTempPath

    According to the Microsoft documentation, this determines its location on the first path found in:

    1. TMP (environment variable)

    2. TEMP (environment variable)

    3. USERPROFILE (environment variable)

    4. The Windows directory

  2. Use C:\temp\3

See alsoSection 3.1.5, “TempDirectories”, Section 3.1.6, “TempTableDirectory”

8.1.7. ICU_TIMEZONE_FILES_DIR

Override location of ICU timezone data files.

ConfigurationServer/Embedded, Client

Most Firebird builds will look for the ICU timezone data files in directory tzdata in the Firebird root directory (on Android, in the root directory itself). Builds can have overridden this default location with the FB_TZDATADIR define in their build configuration.

If for some reason you need to use an alternative location for these files, you can configure this with environment variable ICU_TIMEZONE_FILES_DIR.

In general, updating the timezone database should be done by replacing the *.res files in this tzdata directory. For more information, see Updating the Time Zone Database in the Firebird 5.0 Language Reference.

8.1.8. ISC_INET_SERVER_HOME

Sets the current working directory of the server (non-Windows only).

ConfigurationServer

⚠
Use of ISC_INET_SERVER_HOME is not recommended

The exact use case of this environment variable is unclear. It may affect how some relative paths are resolved. We recommend not to set it.

The Firebird sources (remote/inet.cpp) have the following comment on this environment variable:

If the environment variable ISC_INET_SERVER_HOME is set, change the home directory to the specified directory. Note that this will overrule the normal setting of the current directory to the effective user’s home directory. This feature was added primarily for testing via remote loopback - but does seem to be of good general use, so is activated for the release version. 1995-February-27 David Schnepper

David Schnepper remote/inet.cpp

The Firebird Book (Second Edition) by Helen Borrie says about this environment variable:

Sets the working directory for Classic server ONLY. Make certain this variable is not set if you are running Superserver or Superclassic.

Helen Borrie The Firebird Book (Second Edition)

We can’t corroborate that this is for Classic only, but it will reset the current working directory on each connection received by the server, which seems odd to say the least.

8.1.9. ISC_MSGS

Path of the Firebird message file.

ConfigurationClient, Server/Embedded

This setting is primarily a client-side setting, but may get used by the server if it formats and prints messages itself.

The ISC_MSGS — if set — must point to a Firebird message file, not to a directory.

For details on resolution of Firebird message files, see How Firebird resolves a message file in Section 8.1.5, “FIREBIRD_MSG”.

See alsoSection 8.1.5, “FIREBIRD_MSG”

8.1.10. ISC_PASSWORD

Default password for a connection.

ConfigurationClient

The value of ISC_PASSWORD is used by fbclient as the default value for isc_dpb_password and isc_spb_password when no explicit password was set and isc_dpb_trusted_auth/isc_spb_trusted_auth is not included.

See alsoSection 8.1.12, “ISC_USER”

8.1.11. ISC_PATH

Path for resolving databases with a filename without a path component.

ConfigurationServer/Embedded

Firebird will resolve filenames without a path component in the directory specified by ISC_PATH. This is done only when the name did not match an alias.

To determine if a file has a path component, Firebird checks if a file contains a :, / or \.

If ISC_PATH is not set, and Section 3.1.1, “DatabaseAccess” is set to Restrict, filenames without a path component are resolved against its list of directories.

See alsoSection 3.1.1, “DatabaseAccess”

8.1.12. ISC_USER

Default user for a connection.

ConfigurationClient

The value of ISC_USER is used by fbclient as the default value for isc_dpb_user_name and isc_spb_user_name when no explicit username was set and isc_dpb_trusted_auth/isc_spb_trusted_auth is not included.

See alsoSection 8.1.10, “ISC_PASSWORD”

8.1.13. VISUAL

Default text editor for isql (non-Windows OSes only).

ConfigurationClient

If VISUAL is not set, the value of Section 8.1.1, “EDITOR” is checked before using the default.

The environment variable VISUAL is ignored on Windows.

Table 8.2. Default if neither VISUAL nor EDITOR is set:

Windows

Notepad

Linux and other OSes

vi

This is not a Firebird-specific environment variable, but a common convention for applications.

See alsoSection 8.1.1, “EDITOR”