Chapter 2. An overview of Firebird configuration

In its most basic form, configuration is expressed as a list of key-value pairs, or — in some files — keyword-value pairs:

Syntax

key-name = value

Example

DatabaseAccess = None

Allowed values depend on the specific key, but broadly has the following types:

integer

Integer values, or integers followed by K (kilo: 1024), M (mega: 1024² or 1,048,576) or G (giga: 1024³ or 1,073,741,824).

Boolean

Truth values, where 0 is false and 1 (and any other non-zero integer value) is true. Strings true, y and yes are also interpreted as true, everything else as false.

We recommend only using 0/1 or true/false for Boolean values.

Currently, a non-numeric suffix of an integer prefix is ignored, so 123text is interpreted as 123 → true, not false. This is an implementation artefact that may change in the future.

string

String values; individual properties may require a specific syntax in their string values, or a limited set of values, etc.

list

List of values; a list is a string value with values separated by a space ( ), comma (,), or semicolon (;). The order is usually significant. Some lists may use only a subset of separators; this will be mentioned explicitly if relevant.

scoped values

Some configuration files (Chapter 4, databases.conf, Chapter 5, plugins.conf, Chapter 6, replication.conf, trace configuration) allow or require keys with a string value followed by additional key-value pairs enclosed in braces.

See Section 2.1.2, “Scope” for more information.

A (non-scoped) value or the simple value of a scoped value can optionally be enclosed in double quotes. The entire value must be quoted, and anything other than a comment or whitespace after the closing double quote is considered an error. This can — for example — be used if the value contains a # (e.g. Key = "some#value"), or braces ({/}). Unquoted, the # is interpreted as the start of a comment, and the braces as the start or end of a scoped value.

For braces, it’s also possible to escape them by doubling them ({{/}}); doubled braces are always undoubled, even if the value is enclosed in double quotes.

Some configuration files use scopes. Scopes are key-value pairs or keyword-value pairs enclosed in braces ({ and }). Their exact usage and syntax depend on the specific configuration file.

In general, the syntax is:

Key or keyword + scoped value syntax

<key-or-keyword> [ = <simple-value> ]
{
  { <key> = <simple-value> <new-line> }...
}

We call the part after the = (equals) a scoped value¹.

Some configuration files allow a scoped value without a simple value; this — for example — establishes a default configuration. In that case, both the equals (=) and the simple value are absent.

For example, databases.conf has key-value pairs, where the value is either a string (simple value), or a scoped value (string value + scope):

Scoped value in databases.conf

# key employee with simple value
employee = $(dir_sampleDb)/employee.fdb
 
# key security.db with scoped value
security.db = $(dir_secDb)/security4.fdb
{
	RemoteAccess = false
	DefaultDbCachePages = 256
}

In this example, security.db is the key, and the string $(dir_secDb)/security4.fdb and the key-value pairs between braces are the value of security.db. The configuration options RemoteAccess and DefaultDbCachePages are applied specifically to the security database (alias security.db).

As another example, trace configuration, plugins.conf and replication.conf have keyword-value pairs, where the value is (always) a scoped value

Scoped value in replication.conf:

database = /your/db.fdb
{
  journal_source_directory = /your/db/source
}

Here database = /your/db.fdb identifies this as replication configuration specific to the database /your/db.fdb, with the actual configuration listed within the braces.

A # starts a comment, until the end of that line. Comments are ignored by the configuration parser.

Comments are used in the default configuration files for documentation, and to show default values without explicitly configuring those values.

For your own use, you can use comments to temporarily disable a configuration item or revert to the default. You can also use comments to record why a specific configuration value was chosen (e.g. by specifying a rationale, or a link to an external document, etc.).

If you need to specify a value that contains the # symbol, enclose the value in double quotes (e.g. Key = "some#value").

Firebird provides a number of predefined macros which can be used in configuration values to substitute directory locations.

The syntax to use these macros is $(macro-name) (e.g. $(dir_plugins)).

It is not possible to define your own custom macros.

The macro names are case-insensitive.

For replication, additional macros are available for specific configuration items; these are covered in Chapter 6, replication.conf.

The include statement allows you to include the content of another file when the configuration file is read.

Syntax

include path-expression

Where path-expression is a string identifying the file or files to include. The path-expression supports:

• Relative paths (resolved against the parent directory of the current configuration file)

• Absolute paths

• Section 2.1.4, “Macro substitution”

• Wildcards (* for zero or more characters, and ? for one character)

Examples

# Relative path
include some_file.conf
 
# Which is equivalent to
include $(this)/some_file.conf
 
# Absolute path (Windows)
include C:\Firebird\default.conf
 
# Absolute path (Linux)
include /opt/firebird/default.conf
 
# Path with macro substitution
include $(dir_plugins)/some_file.conf
 
# Wildcard to include multiple files
include databases/*.conf