|Firebird Documentation Index → Firebird 1.5.6 Release Notes → New Configuration Files → Server Configuration File--firebird.conf|
Default values are applicable to most parameters. Parameter names and values are case-sensitive on Linux but not on Windows. To set any parameter to a non-default setting, delete the comment (#) marker and edit the value. You can edit the configuration file while the server is running. To activate configuration changes, it is necessary to stop and restart the service.
Entries are in the form:
parameter_name is a string that contains no whitespace 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
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.
Supports the database-aliasing feature. In previous versions, the server could attach to any database in its local filesystem and was accessed by applications passing the file's absolute filesystem path. This parameter provides options to restrict the server's access to aliased databases only, or to only databases located in specific filesystem trees.
DatabaseAccess may be None, Restrict or Full.
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 semi-colons, to define one or more permissible locations.
For example,Unix: /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 only if they are located under C:\Program Files\Firebird\userdata:
DatabaseAccess = Restrict userdata
Database shadowing - the current DatabaseAccess handling has a bug that means you must use the Restrict option if you are shadowing any database on the server.
Was external_file_directory in isc_config/ibconfig but syntax has changed.
Provides three levels of security regarding EXTERNAL FILES (fixed format text files that are to be accessed as database tables). The value is a string, which may be None, Full or Restrict.
None (the default value) disables any use of external files on your server.
Restrict provides the ability to restrict the location of external files for database access to specific path-trees. Supply a list of one or more tree-roots, separated by semi-colons (;), within and beneath which external files may be stored.
For example,Unix: /db/extern;/mnt/extern Windows: C:\ExternalTables
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 that the running server recognizes as the root directory of the Firebird installation is C:\Program Files\Firebird, then the following value will restrict the server to accessing external files only if they are located in C:\Program Files\Firebird\userdata\ExternalTables:ExternalFileAccess = Restrict userdata\ExternalTables
Full permits external files to be accessed anywhere on the system.
See the CAUTION below the next entry, UdfAccess.
Was as external_function_directory in isc_config/ibconfig but syntax has changed. It replaces not just the name of the earlier parameter, but also the form in which the values are presented. The purpose of the changes was to enable optional levels of protection for external user-defined library modules, a recognized target for malicious intruder attacks. UdfAccess may be None, Restrict or Full.
Restrict (the default setting) retains the functionality provided by the external_function_directory parameter in Firebird 1.0, to restrict the location of callable external libraries to specific filesystem locations. Supply a list of one or more tree-roots, separated by semi-colons (;), within and beneath which UDF, BLOB filter and character set definitions may be stored.
For example,Unix: /db/extern;/mnt/extern Windows: C:\ExternalModules
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 of the Firebird installation is C:\Program Files\Firebird, then the following value will restrict the server to accessing external libraries only if they are located in C:\Program Files\Firebird\userdata\ExternalModules:UDFAccess = Restrict userdata\ExternalModules
None disallows all use of user-defined external libraries.
Full permits external libraries to be accessed anywhere on the system.
Avoid setting up custom directory trees for UdfAccess and ExternalFileAccess such that they share a parent tree-root. The default settings are safe. If you are setting up your own and you don't make separated directory trees for them, the server can be easily hacked to execute unauthorised code. An example of what to avoid:
UdfAccess = UDF; /bad_dir ExternalFileAccess = /external; /bad_dir/files
UdfAccess & ExternalFileAccess here have a common sub-tree, /bad_dir/files, where someone could place his external file /bad_dir/files/hackudf.so and execute his own code on the compromised system.
(was cpu_affinity in isc_config/ibconfig). With Firebird SuperServer on Windows, there is a problem with the operating system continually swapping the entire SuperServer process back and forth between processors on SMP machines. This ruins performance. This parameter can be used on SMP systems on Windows to set Firebird SuperServer's processor affinity to a single CPU.
Firebird Superservers, up to and including Release 1.5, may not support the Hyperthreading feature of some later-model motherboards on Windows. To avoid balancing problems, you may need to disable hyperthreading at system BIOS level.
CpuAffinityMask takes one integer, the CPU mask.
CpuAffinityMask = 1
only runs on the first CPU (CPU 0).
CpuAffinityMask = 2
only runs on the second CPU (CPU 1).
CpuAffinityMask = 3
runs on both first and second CPU.
Calculating the affinity mask value
You can use this flag 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. M is 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 M and 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
(was deadlock_timeout in isc_config/ibconfig). Number of seconds (integer) that the lock manager will wait after a conflict has been encountered, before purging locks from dead processes and doing a further deadlock scan cycle. Normally, the engine detects deadlocks instantly. The deadlock timeout kicks in only if something goes wrong.
The default of 10 seconds is about right for most conditions. Setting it lower does not necessarily improve the speed with which problem deadlocks return a conflict exception. If it is too low, the effect may be unnecessary extra scans which degrade system performance.
(was database_cache_pages in isc_config/ibconfig). Server-wide default (integer) number of database pages to allocate in memory, per database. The configured value can be overridden at database level.
The default value for SuperServer is 2048 pages. For Classic, it is 75.
SuperServer and Classic use the cache differently. SS pools its cache for use by all connections; Classic allocates a static cache to each connection.
Integer, representing number of bytes of memory reserved for the event manager. Default is 65536 (64 Kb).
(was lock_acquire_spins). Relevant only on SMP machines running Classic server. In Classic server, only one client process may access the lock table at any time. A mutex governs access to the lock table. Client processes may request the mutex conditionally or unconditionally. If it is conditional, the request fails and must be retried. If it is unconditional, the request will wait until it is satisfied. LockAcquireSpins establishes the number of attempts that will be made if the mutex request is conditional.
Integer. The default is 0 (unconditional). There is no recommended minimum or maximum.
(was lock_hash_slots in isc_config/ibconfig). Use this parameter for tuning the lock hash list. Under heavy load, throughput might be improved by raising the number of hash slots to disperse the list in shorter hash chains.
Integer-prime number values are recommended. The default is 101.
(was lock_grant_order in isc_config/ibconfig). When a connection wants to lock an object, it gets a lock request block which specifies the object and the lock level requested. Each locked object has a lock block. Request blocks are connected to those lock blocks either as requests that have been granted, or as pending requests.
The LockGrantOrder parameter is a Boolean. The default (1=True) indicates that locks are to be granted on a first-come-first-served basis. The False setting (0), emulating InterBase v3.3 behavior, grants the lock as soon as it becomes available. It can result in lock requests being "starved".
This integer parameter represents the number of bytes of shared memory allocated for the lock manager. For a Classic server, the LockMemSize gives the initial allocation, which will grow dynamically until memory is exhausted ("Lock manager is out of room"). If there are a lot of connections or big page caches, increase this parameter to avoid these errors.
In SuperServer, the memory allocated for the lock manager does not grow.
The default size on Linux and Solaris is 98304 bytes (96 Kb). On Windows, it is 262144 (256 Kb).
Integer parameter, specifying the number of semaphores available for interprocess communication (IPC). The default is 32. Set this parameter in non-threading environments to raise or lower the number of available semaphores.
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 1 Mb; you can reconfigure it to any size up to the currently configured maximum value set by the SortMemUpperLimit parameter (see below).
The maximum amount of memory, in bytes, to be allocated by the in-memory sorting module. The installation default is 67108864 bytes (64 Mb) for SuperServer and 8388608 (8 Mb) for the Classic server.
For Classic, bear in mind that increasing either the block size or the maximum limit affects each client connection/server instance and will ramp up the server's memory consumption accordingly.
(was connection_timeout in isc_config/ibconfig). Number of seconds to wait before abandoning an attempt to connect. Default 180.
(was dummy_packet_interval in isc_config/ibconfig). This is the number of seconds (integer) the server should wait on a silent client connection before sending dummy packets to request acknowledgment.
DO NOT USE THIS OPTION on a Win32 server running TCP/IP clients. It causes a persistent increase in usage of kernel non-paged memory which may hang or crash Windows on the client side as explained at http://support.microsoft.com/default.aspx?kbid=296265.
Win32-with-TCP/IP apart, it's the only way to detect and disconnect inactive clients when either NamedPipes (NetBEUI), XNET or IPC protocols are used. There are no known issues on POSIX systems.
Normally, Firebird uses the SO_KEEPALIVE socket option to keep track of active connections. If you do not like the default two-hour keepalive timeout, adjust your server OS settings appropriately:
On UNIX-like OS's, modify the contents of /proc/sys/net/ipv4/tcp_keepalive_*.
On Windows, follow instructions in this article.
Default should be 0 - not 60 which was the old default in Firebird 1.0 and most of the 1.5 release candidates. A setting of 60 should be treated as the default on systems where you need to make use of this dummy packet polling.
Default = gds_db. See RemoteServicePort, next.
These two parameters 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/tcp 3050).
Change one of the entries, not both. The 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.
If a port number is provided in the TCP/IP connection string, it will always take precedence over RemoteServicePort.
The inherited InterBase behavior, of passing event notification messages back to the network layer through randomly selected TCP/IP ports, has been a persistent source of network errors and conflicts with firewalls, sometimes to the extent of causing the server to crash under some conditions. This parameter allows you to configure a single TCP Port for all event notification traffic.
The installation default (0) retains the traditional random port behaviour. To dedicate one specific port for event notifications, use an integer which is an available port number.
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 one NIC and to reject connection requests from any other network interfaces. This should help to overcome problems in some subnetworks where the server is handling traffic through multiple NICs.
String, in a valid dotted IP format. Default value (not bound) is no value.
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.
Value is an integer (size of packet in bytes) in the range 1448 to 32768. The installation default is 8192.
Integer parameter, UNIX signal to use for interprocess communication. Default: 16
USE ONLY WITH EXTREME CAUTION
Boolean parameter which, if set True, allows the engine to open database files which reside on a networked filesystem (NFS) mounted partition. Because the filesystem is beyond the control of the local system, this is a very risky feature that 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.
(was tcp_no_nagle in isc_config/ibconfig). 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 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.
The "Windows local" protocol uses a hidden window for inter-process communication 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.
A setting for the thread scheduler on Windows, this integer parameter establishes the number of priority switching cycles (see PrioritySwitchDelay, below) 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.
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).
(was server_client_mapping in ibconfig). Size in bytes of one client's portion of the memory-mapped file used for interprocess communication (IPC) in the connection model used for "Windows local" connection. It has no equivalent on other platforms.
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.
NOTE This can no longer be modified in the Guardian's system tray icon dialog.
Default value: FirebirdIPI
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 to restore compatibility, if necessary.
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 9x 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 which sets the number of pages to be withheld before a flush is flagged to be done next time a transaction commits.
Default is 100 in Windows installations and -1 (disabled) in installations for all other platforms.
If the end of the MaxUnflushedWriteTime cycle (see below) 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.
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 which sets the interval, in seconds, between the last flush to disk and the setting of a flag to perform a flush next time a transaction commits. Default is 5 seconds in Windows installations and -1 (disabled) in installations for all other platforms.
A setting for the thread scheduler on Windows, this integer establishes the time, in milliseconds, which is 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 ms, chosen on the basis of experiments on Intel PIII/P4 processors. For processors with lower clock speeds, a longer delay will be required.
Integer, sets the number of extra cycles given to a thread when its priority is switched to HIGH. The installation default is 5.
(was server_priority_class in ibconfig). Priority level/class for the server process. This parameter replaces the server_priority_class parameter of pre-1.5 releases-see below-with a new implementation.
The values are integer, as follows:
0 - normal priority
positive value - high priority (same as -B[oostPriority] switch on instsvc.exe configure and start options)
negative value - low priority
All changes to this value should be carefully tested to ensure that they actually cause the engine to be more responsive to requests.
Applicable only for NetBEUI connections.
String parameter, the name of the pipe used as a transport channel in NetBEUI protocol. 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®.
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 FIREBIRD_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.
(replaces tmp_directory entries in isc_config/ibconfig). Supply a list of one or more directories, separated by semi-colons (;), 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.
Unix: /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 500 Mb:
TempDirectories = userdata\sortfiles 500000000
No quoted paths (as was required in Firebird 1.0).
Establishes the Boolean evaluation method (complete or shortcut). The default (0=False) is to "short-cut" 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.
Parameter type is Boolean.
Don't overlook the fact that this flag affects all Boolean evaluations performed in any databases on the server.
Version 1.5 addressed and fixed 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 have 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 True if you need to revert to the old condition for compatibility with existing code.
Don't overlook the fact that this setting affects all databases on the server and will potentially produce exceptions or wrong results if set on in an environment where applications are not compensating for the expected bug.
New parameter added at v.1.5.3
This parameter allow users to revert to pre-V1.5 column naming behaviour in SELECT expressions. If
this parameter changed from its default 0 setting, the engine will not attempt to supply run-time
CONCATENATION for derived fields where the developer has neglected
to provide identifiers.
This setting affects all databases on the server and will potentially produce exceptions or unpredicted results where mixed applications are implemented.
|Firebird Documentation Index → Firebird 1.5.6 Release Notes → New Configuration Files → Server Configuration File--firebird.conf|