Parameters of Firebird Configuration File - Firebird

Firebird does not require the intense and constant reconfiguration that many other heavy-duty RDBMSs do. However, a range of configuration options is available for customizing a Firebird server and the host system on which it runs when special needs must be met.

The Firebird configuration file is named firebird.conf in all Firebird versions from 1.5 onward. In prior versions, its name depends on the operating system:

  • On Linux/UNIX, the name is isc_config.
  • On Windows, the name is ibconfig.

Several new parameters were added to version 1.5.

When the Firebird server startup process reads the configuration file, it adjusts its runtime flags to any non -default values contained in the configuration file. The file will not be read again until next time the server is restarted. The default configuration parameters and their values are listed in the configuration file, commented out by # comment markers. It is not necessary to uncomment the defaults in order to make them visible to the server’s startup procedure.

The configuration file can be edited with any plain text editor, for example, vim (Linux) or Notepad (Windows). Do not copy the file from a Windows machine to a Linux one or vice versa, because the two systems store line breaks differently.

Parameters

Entries are in the form

parameter_name =value
  • parameter_name is a string that contains no white space and names a property of the server being configured.
  • value is a number, Boolean (1=True, 0=False), or string that specifies the value for the parameter.

To set any parameter to a non-default setting, delete the comment (#) marker and edit the value.

The Firebird 1.0.x ibconfig/isc_config parameter names and syntaxes are not interchangeable with those in firebird.conf. The format, size, and number of parameters are more restrictive.

The ibconfig/isc_config format is

parameter_namevalue

where the white space between the name and the value can be tabs or spaces, as desired, to please the eye. Each line of the file is limited to 80 characters. Unused parameters and nstallation defaults are commented with '#'.

On Linux, you should assume that parameter names are case sensitive.

You can edit the configuration file while the server is running. To activate configuration changes, it is necessary to stop and restart the service.

“Missing” Parameters in Firebird 1.0.x

In pre–version 1.5 installations, some optional parameters, requiring settings that could not be configured as defaults, were omitted from the configuration file.

  • If a missing parameter pertinent to ibconfig or isc_config is needed, it can be added.
  • If you include a parameter that is not supported in the release version you are running, it will be ignored.
  • The ibconfig/isc_config parameter names and syntaxes are not interchangeable with those in firebird.conf.

Lock Manager Settings

The advanced lock manager configuration settings are discussed toward the end of Chapter Understanding the Lock Manager.

Filesystem-Related Parameters

RootDirectory

Version 1.5 forward

This value is a string, the absolute path to a directory root on the local filesystem. It should remain commented unless you want to force the startup procedure to override the path to the root directory of the Firebird server installation, that it would otherwise detect for itself. Firebird 1.5 and higher servers follow a predefined route to find the root directory.

DatabaseAccess

Version 1.5 forward

In Firebird 1.0.x, the server can attach to any database in its local filesystem and is always accessed by applications passing the file’s absolute filesystem path. This parameter was introduced in version 1.5 to provide tighter security controls on access to database files and to support the database-aliasing feature. This parameter provides options to restrict the server’s access to only aliased databases or to only databases located in specific filesystem trees.

DatabaseAccess may be Full, None, or Restrict.

  • Full (the default) permits database files to be accessed anywhere on the local filesystem.
  • None permits the server to attach only databases that are listed in aliases.conf.
  • Restrict allows you to configure the locations of attachable database files to a specified list of filesystem tree roots. Supply a list of one or more tree roots, separated by semicolons, to define one or more permissible locations, for example:
POSIX:/db/databases;/userdir/data Windows:D:\data

Relative paths are treated as relative to the path that the running server recognizes as the root directory. For example, on Windows, if the root directory is C:\Program Files\Firebird, then the following value will restrict the server to accessing database files located under C:\Program Files\Firebird\userdata:

ExternalFileAccess = Restrict userdata

Parameters for Configuring Temporary Sort Space

When the size of the internal sort buffer is too small to accommodate the rows involved in a sort operation, Firebird needs to create temporary sort files on the server’s filesystem. By default, it will look for the path specified in the environment variable INTERBASE_TMP. If that variable is not present, it will try to use the root of the /tmp filesystem on Linux/UNIX, or C:\Temp on Windows NT/2000/XP. None of these locations can be configured for size.

Firebird provides a parameter for configuring the disk space that will be used for storing these temporary files. It is prudent to use it, to ensure that sufficient sort space will be available under all conditions.

All CONNECT or CREATE DATABASE requests share the same list of temporary file directories and each creates its own temporary files. Sort files are released when the sort is finished or the request is released.

In release 1.5, the name of the parameter changed from tmp _directory to TempDirectories, and the syntax of the parameter value also changed.

TempDirectories

Version 1.5 forward

Supply a list of one or more directories, separated by semicolons (;), under which sort files may be stored. Each item may include an optional size argument, in bytes, to limit its storage. If the argument is omitted or is invalid, Firebird will use the space in that directory until it is exhausted, before moving on to the next listed directory, for example:

POSIX:/db/sortfiles1 100000000;/firebird/sortfiles2 Windows:E:\sortfiles 500000000

Relative paths are treated as relative to the path that the running server recognizes as the root directory of the Firebird installation. For example, on Windows, if the root directory is C:\Program Files\Firebird, then the following value will tell the server to store temporary files in C:\Program Files\Firebird\userdata\sortfiles, up to a limit of about 477MB:

TempDirectories = userdata\sortfiles 500000000

tmp_directory

Versions prior to Firebird 1.5

The syntax for the older tmp_directory value is to include one tmp_directory line for each directory in which you want temporary sort files to be stored. Specify the number of bytes available in the directory and, within double quotes, the path to a directory that exists on a physical drive with sufficient spare capacity. There is no restriction on the name used for the directory. You can list multiple entries, one per line, and the spaces do not need to be contiguous or confined to a single storage device.

For example, the following entries constitute a list in a single configuration file:

tmp_directory 6000000 "d:\fbtemp" tmp_directory 12000000 "f:\fbtemp" tmp_directory 4000000 "w:\backwash"

pathname must be enclosed in double quotes, or the server will ignore this entry. Space will be used according to the order specified. If space runs out in a particular directory, Firebird creates a new temporary file in the next directory from the directory list. If there are no more entries in the directory list, Firebird displays an error message and stops processing the current request.

Resource-Related Parameters

CpuAffinityMask

Windows versions 1.5 forward

cpu_affinity

Windows versions prior to Firebird 1.5

With Firebird Superserver on Windows, there can be a problem with the operating system continually swapping the entire Superserver process back and forth between processors on SMP machines. In support lists, this is referred to as “the see-saw effect” and, on affected systems, it can have a severe effect on performance. This parameter must be used to set Firebird Superserver’s processor affinity to one or more specific CPUs.

CpuAffinityMask and cpu_affinity take one integer: the CPU mask. For example:

CpuAffinityMask = 1 cpu_affinity = 1

only runs on the first CPU (CPU 0).

CpuAffinityMask = 2 cpu_affinity = 2

only runs on the second CPU (CPU 1).

CpuAffinityMask = 3 cpu_affinity = 3

runs on both first and second CPU.

Calculating the Affinity Mask Value

You can use this parameter to set Firebird’s affinity to any single processor or (on Classic server) any combination of the CPUs installed in the system.

Consider the CPUs as an array numbered from 0 to n–1, where n is the number of processors installed and i is the array number of a CPU. Mis another array, containing the MaskValue of each selected CPU. The value A is the sum of the values in M.

Use the following formula to arrive at Mand calculate the MaskValue A:

Mi = 2I
A = M1 + M2 + M3. . .

For example, to select the first and fourth processors (processor 0 and processor 3) calculate as follows:

A = 20 + 23 = 1 + 8 = 9

The default CPU affinity mask is 1 (processor 0).

DefaultDbCachePages

Version 1.5 forward

database_cache_pages

Versions prior to Firebird 1.5

This sets the global server default (integer) number of database pages to allocate in memory for each database. The configured value can be overridden at database level.

The default value for Superserver is 2048 pages. For Classic server, it is 75.

Superserver and Classic server allocate and use cache memory differently. There is no “formula” that can be applied to set an optimal default cache size to suit all needs. However, the factors are discussed in greater detail in Chapter Creating and Maintaining a Database in the section “The Database Cache.”

EventMemSize

Version 1.5 forward

This is an integer representing the number of bytes of memory reserved for the event manager. The default is 65536 (64K).

SortMemBlockSize

Version 1.5 forward

This parameter allows you to configure, in bytes, the size of each memory block used by the in-memory sorting module. The installation default is 1MB, which you can reconfigure to any size up to the currently configured maximum value set by the SortMemUpperLimit parameter (see the next section).

SortMemUpperLimit

Version 1.5 forward

The maximum amount of memory, in bytes, to be allocated by the in-memory sorting module. The installation default is 67108864 bytes (64MB) for Superserver and 8388608 (8MB) for Classic server.

Communications-Related Parameters

ConnectionTimeout Version 1.5 forward

connection_timeout

Versions prior to Firebird 1.5

This is the number of seconds to wait before abandoning an attempt to connect. The default is 180.

DummyPacketInterval

Version 1.5 forward

dummy_packet_interval

Versions prior to Firebird 1.5

This is an old InterBase timeout parameter that sets the number of seconds (integer) the server should wait on a silent client connection before sending dummy packets to request acknowledgment. It is set by default to 0 on Firebird 1.5 (disabled) and to 60 on Firebird 1.0.x.

On Firebird 1.0.x, open ibconfig (Windows) or isc_config (other systems) and add the line:

dummy_packet_interval=0

Normally, Firebird keeps track of active connections using the SO_KEEPALIVE socket option, with a default timeout period of 2 hours. If you need to alter the timeout period, adjust server settings to suit:

  • On POSIX servers, modify the contents of proc/sys/net/ipv4/tcp_keepalive_*.
  • For Windows, obtain instructions from the article

RemoteServiceName

Version 1.5 forward

This is the name of the service as broadcast by the server. If the firebird.conf file is optionally included in a client-only installation, the client will use it to find the service name if necessary. See also RemoteServicePort (described in the next section). For more information, refer to the section “Configuring the Port Service” in Chapter Network Setup.

Default = gds_db

RemoteServicePort

Version 1.5 forward

This parameter and RemoteServiceName provide the ability to override either the TCP/IP service name or the TCP/IP port number used to listen for client database connection requests, if one of them differs from the installed defaults (gds_db and port 3050).

Change one of the entries, not both. RemoteServiceName is checked first for a matching entry in the services file. If there is a match, the port number configured for RemoteServicePort is used. If there is not a match, then the installation default, port 3050, is used.

RemoteAuxPort

Version 1.5 forward

The inherited InterBase behavior of passing event notification messages back to the network layer through randomly selected TCP/IP ports shows up in some types of installations as a persistent source of network errors and conflicts with firewalls, sometimes to the extent of causing the server to crash. This parameter allows you to configure a single TCP port for all event notification traffic.

The installation default (0) retains the traditional random port behavior. To dedicate one specific port for event notifications, use an integer that is an available port number.

RemoteBindAddress

Version 1.5 forward

By default, clients may connect from any network interface through which the host server accepts traffic. This parameter allows you to bind the Firebird service to incoming requests through a single IP address (e.g., network card) and to reject connection requests from any other network interfaces. This helps to solve problems in some networks when the server is hosting multiple subnets.

This is a string, in a valid dotted IP format. The default value (not bound) is an empty setting.

TcpRemoteBufferSize

Version 1.5 forward

The engine reads ahead of the client and can send several rows of data in a single packet. The larger the packet size, the more rows are sent per transfer. Use this parameter (with caution and complete comprehension of its effects on network performance) if you need to enlarge or reduce the TCP/IP packet size for send and receive buffers. It affects both the client and server.

The value is an integer (the size of the packet in bytes) in the range 1448 to 32768. The installation default is 8192.

POSIX-Specific Parameters

RemoteFileOpenAbility

Version 1.5 forward, POSIX only

This is a Boolean parameter that, if set to True, allows the engine to open files that reside on a networked filesystem (NFS) mounted partition. It is intended to allow shadows on NFS drives that have high availability. It is not safe for database files —except possibly a read-only database—because the filesystem is beyond the control of the local system. It should not be enabled for the purpose of opening any read/write database whose survival matters to you. The default is 0 (False, disabled) and you should leave it that way unless you are very clear about its effects.

TcpNoNagle

Version 1.5 forward, Linux only

tcp_no_nagle

Versions prior to Firebird 1.5, Linux only

On Linux, by default, the socket library will minimize physical writes by buffering writes before actually sending the data, using an internal algorithm (implemented as the TCP _NODELAY option of the socket connection) known as Nagle’s algorithm. It was designed to avoid problems with small packets, called tinygrams, on slow networks.

By default, TCP_NODELAY is enabled (value 0) when Firebird Superserver is installed on Linux. On slow networks, disabling it can actually improve speed. Watch out for the double negative—set the parameter to True to disable TCP _NODELAY and False to enable it. In releases up to and including v.1.5, this feature is active only for Superserver.

Windows-Specific Parameters

CreateInternalWindow

Version 1.5 forward, Windows only

The “Windows local” protocol uses a hidden window for IPC between the local client and the server. This IPC window is created at server startup when CreateInternalWindow is true (1, the default). Set it to 0 (off ) to run the server without a window and thus to disable local protocol. With local protocol disabled, it is possible to run multiple instances of the server simultaneously.

DeadThreadsCollection

Version 1.5 forward, Windows only

A setting for the thread scheduler on Windows, this integer parameter establishes the number of priority switching cycles (see the section “PrioritySwitchDelay”) that the scheduler is to execute before a thread is destroyed (or closed).

Immediate destruction (or closure) of worker threads would require a semaphore and blocking call, generating significant overhead. Instead, a thread scheduler maintains threads in a pool. When a thread has completed its task, it is marked as idle. The idle thread is destroyed (or closed) after n iterations of the scheduler loop, where n is the value of the DeadThreadsCollection parameter.

For a server handling a very large number of connections—in the high hundreds or more—the parameter value will need to be raised from its default setting of 50.

GuardianOption

Version 1.5 forward, Windows only

This is a Boolean parameter used on Windows servers to determine whether the Guardian should restart the server every time it terminates abnormally. The installation default is to do so (1=True). To disable the restart behavior, set this parameter off (0=False).

IpcMapSize

Version 1.5 forward

server_client_mapping

Versions prior to Firebird 1.5

This is the size in bytes of one client’s portion of the memory-mapped file used for IPC in the connection model used for the “Windows local” connection. It has no equivalent on other platforms. It is an integer, from 1024 to 8192. The default is 4096.

Increasing the map size may improve performance when retrieving very wide or large data row sets, such as those returning graphics BLOBs.

IpcName

Version 1.5 forward, applicable only on Windows platforms

The default value is FirebirdIPI.

This is the name of the shared memory area used as a transport channel in local protocol.

The release 1.5 default value, FirebirdIPI, is not compatible with older releases of Firebird nor with InterBase. Use the value InterBaseIPI, if necessary, to retain compatibility with an existing application that refers to the shared memory (IPC space) by name.

MaxUnflushedWrites

Version 1.5 forward

Applicable on Windows servers only

This parameter was introduced in version 1.5 to handle a bug in the Windows server operating systems, whereby asynchronous writes were never flushed to disk except when the Firebird server underwent a controlled shutdown. (Asynchronous writes are not supported in Windows 9 x or ME.) Hence, on 24/7 systems, asynchronous writes were never flushed at all.

This parameter determines how frequently the withheld pages are flushed to disk when Forced Writes are disabled (asynchronous writing is enabled). Its value is an integer that sets the number of pages to be withheld before a flush is flagged to be done the next time a transaction commits. The default is 100 in Windows installations and –1 (disabled) in installations for all other platforms.

If the end of the MaxUnflushedWriteTime cycle (see the next section) is reached before the count of withheld pages reaches the MaxUnflushedWrites count, the flush is flagged immediately and the count of withheld pages is reset to zero.

MaxUnflushedWriteTime

Version 1.5 forward

Applicable on Windows servers only

This parameter determines the maximum length of time that pages withheld for asynchronous writing are flushed to disk when Forced Writes are disabled (asynchronous writing is enabled). Its value is an integer that sets the interval, in seconds, between the last flush to disk and the setting of a flag to perform a flush the next time a transaction commits. The default is 5 seconds in Windows installations and –1 (disabled) in installations for all other platforms.

PrioritySwitchDelay

Version 1.5 forward, Windows only

A setting for the thread scheduler on Windows, this integer establishes the time, in milliseconds, to elapse before the priority of an inactive thread is reduced to LOW or the priority of an active thread is advanced to HIGH. One iteration of this switching sequence represents one thread-scheduler cycle.

The default value is 100 milliseconds, chosen on the basis of experiments on Intel PIII/P4 processors. For processors with lower clock speeds, a longer delay will be required.

PriorityBoost

Version 1.5 forward, Windows only

This integer sets the number of extra cycles given to a thread when its priority is switched to HIGH. The installation default is 5.

ProcessPriorityLevel

Version 1.5 forward, applicable only on Windows platforms This is a parameter for setting a priority level/class for the server process, replacing the server_priority_class parameter of pre-1.5 releases with a new implementation.

The values are integer, as follows:

  • 0: Normal priority
  • Positive value: High priority (same as the –B[oostPriority] switch on instsvc.exe Configure and start options)
  • Negative value: Low priority

server_priority_class

Versions prior to Firebird 1.5

This setting assigns a priority class for the Firebird service on Windows NT or Windows 2000 only. The possible values are: 1 = low priority, 2 = high priority. The default is 1.

RemotePipeName

Version 1.5 forward, applicable only on Windows platforms for Named Pipes Connections

This string parameter is the name of the pipe used as a transport channel for Windows Named Pipes networking. The named pipe is equivalent to a port number for TCP/IP. The default value, interbas, is compatible with older releases of Firebird and with InterBase.

server_working_size_max and server_working_size_min

Versions prior to Firebird 1.5

These are two old, deprecated memory parameters that were inherited in ibconfig for older Firebird releases and were unsupported. They have been excluded from firebird.conf.

Compatibility Parameters

CompleteBooleanEvaluation

Version 1.5 forward

This establishes the Boolean evaluation method (complete or shortcut). The default (0=False) is to “shortcut” a Boolean evaluation expression involving the AND or OR predicates by returning as soon as a result of True or False is obtained that cannot be affected by the results of any further evaluation.

Under very rare (usually avoidable) conditions, it might happen that an operation inside an OR or an AND condition that remains unevaluated due to the shortcut behavior has the potential to affect the outcome of the original result. If you have the misfortune to inherit an application that has such characteristics in its SQL logic, you might wish to use this parameter to force complete evaluation until you have the opportunity to perform surgery on it. The parameter type is Boolean.

OldParameterOrdering

Version 1.5 forward

Version 1.5 addressed an old InterBase bug that caused output parameters to be returned to the client with an idiosyncratic ordering in the XSQLDA structure. The bug was of such longevity that many existing applications, drivers, and interface components had built-in workarounds to correct the problem on the client side.

Releases 1.5 and later reflect the corrected condition in the API and are installed with OldParameterOrdering=0 (False). Set this Boolean parameter to True (1) if you need to revert to the old condition for compatibility with existing code.

Parameters Relating to External Objects

Locality and access parameter settings for external code modules and data files are discussed at the end of the section “Configuring External Locations.”


All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

Firebird Topics