Configuration reference

This topic describes all configuration parameters provided by Tarantool.

Most of the configuration options described in this reference can be applied to a specific instance, replica set, group, or to all instances globally. To do so, you need to define the required option at the specified level.

app

Using Tarantool as an application server, you can run your own Lua applications. In the app section, you can load the application and provide an application configuration in the app.cfg section.

Note

app can be defined in any scope.

Note

Note that an application specified using app is loaded after application roles specified using the roles option.

app.cfg
app.file
app.module

app.cfg¶

A configuration of the application loaded using app.file or app.module.

Example

In the example below, the application is loaded from the myapp.lua file placed next to the YAML configuration file:

app:
  file: 'myapp.lua'
  cfg:
    greeting: 'Hello'

Example on GitHub: application

Tip

The experimental.config.utils.schema built-in module provides an API for managing user-defined configurations of applications (app.cfg) and roles (roles_cfg).

Type: map
Default: nil
Environment variable: TT_APP_CFG

app.file¶: A path to a Lua file to load an application from.

Type: string

Default: nil

Environment variable: TT_APP_FILE

app.module¶

A Lua module to load an application from.

Example

The app section can be placed in any configuration scope. As an example use case, you can provide different applications for storages and routers in a sharded cluster:

groups:
  storages:
    app:
      module: storage
      # ...
  routers:
    app:
      module: router
      # ...

Type: string
Default: nil
Environment variable: TT_APP_MODULE

audit_log

Enterprise Edition

Configuring audit_log parameters is available in the Enterprise Edition only.

The audit_log section defines configuration parameters related to audit logging.

Note

audit_log can be defined in any scope.

audit_log.extract_key
audit_log.file
audit_log.filter
audit_log.format
audit_log.nonblock
audit_log.pipe
audit_log.spaces
audit_log.to
audit_log.syslog.*

audit_log.extract_key¶: If set to true, the audit subsystem extracts and prints only the primary key instead of full tuples in DML events (space_insert, space_replace, space_delete). Otherwise, full tuples are logged. The option may be useful in case tuples are big.

Type: boolean

Default: false

Environment variable: TT_AUDIT_LOG_EXTRACT_KEY

audit_log.file¶: Specify a file for the audit log destination. You can set the file type using the audit_log.to option. If you write logs to a file, Tarantool reopens the audit log at SIGHUP.

Type: string

Default: ‘var/log/{{ instance_name }}/audit.log’

Environment variable: TT_AUDIT_LOG_FILE

audit_log.filter¶

Enable logging for a specified subset of audit events. This option accepts the following values:

Event names (for example, password_change). For details, see Audit log events.
Event groups (for example, audit). For details, see Event groups.

The option contains either one value from Possible values section (see below) or a combination of them.

To enable custom audit log events, specify the custom value in this option.

Example

filter: [ user_create,data_operations,ddl,custom ]

Type: array
Possible values: ‘all’, ‘audit’, ‘auth’, ‘priv’, ‘ddl’, ‘dml’, ‘data_operations’, ‘compatibility’,
‘audit_enable’, ‘auth_ok’, ‘auth_fail’, ‘disconnect’, ‘user_create’, ‘user_drop’, ‘role_create’, ‘role_drop’,
‘user_disable’, ‘user_enable’, ‘user_grant_rights’, ‘role_grant_rights’, ‘role_revoke_rights’, ‘password_change’,
‘access_denied’, ‘eval’, ‘call’, ‘space_select’, ‘space_create’, ‘space_alter’, ‘space_drop’, ‘space_insert’,
‘space_replace’, ‘space_delete’, ‘custom’
Default: ‘nil’
Environment variable: TT_AUDIT_LOG_FILTER

audit_log.format¶

Specify a format that is used for the audit log.

Example

If you set the option to plain,

audit_log:
  to: file
  format: plain

the output in the file might look as follows:

2024-01-17T00:12:27.155+0300
4b5a2624-28e5-4b08-83c7-035a0c5a1db9
INFO remote:unix/:(socket)
session_type:console
module:tarantool
user:admin
type:space_create
tag:
description:Create space Bands

Type: string
Possible values: ‘json’, ‘csv’, ‘plain’
Default: ‘json’
Environment variable: TT_AUDIT_LOG_FORMAT

audit_log.nonblock¶: Specify the logging behavior if the system is not ready to write. If set to true, Tarantool does not block during logging if the system is non-writable and writes a message instead. Using this value may improve logging performance at the cost of losing some log messages.

Note

The option only has an effect if the audit_log.to is set to syslog or pipe.

Type: boolean

Default: false

Environment variable: TT_AUDIT_LOG_NONBLOCK

audit_log.pipe¶

Specify a pipe for the audit log destination. You can set the pipe type using the audit_log.to option. If log is a program, its pid is stored in the audit.pid field. You need to send it a signal to rotate logs.

Example

This starts the cronolog program when the server starts and sends all audit_log messages to cronolog standard input (stdin).

audit_log:
  to: pipe
  pipe: 'cronolog audit_tarantool.log'

Type: string
Default: box.NULL
Environment variable: TT_AUDIT_LOG_PIPE

audit_log.spaces¶

The array of space names for which data operation events (space_select, space_insert, space_replace, space_delete) should be logged. The array accepts string values. If set to box.NULL, the data operation events are logged for all spaces.

Example

In the example, only the events of bands and singers spaces are logged:

audit_log:
  spaces: [bands, singers]

Type: array
Default: box.NULL
Environment variable: TT_AUDIT_LOG_SPACES

audit_log.to¶

Enable audit logging and define the log location. This option accepts the following values:

devnull: disable audit logging.
file: write audit logs to a file (see audit_log.file).
pipe: start a program and write audit logs to it (see audit_log.pipe).
syslog: write audit logs to a system logger (see audit_log.syslog.*).

By default, audit logging is disabled.

Example

The basic audit log configuration might look as follows:

audit_log:
  to: file
  file: 'audit_tarantool.log'
  filter: [ user_create,data_operations,ddl,custom ]
  format: json
  spaces: [ bands ]
  extract_key: true

Type: string
Possible values: ‘devnull’, ‘file’, ‘pipe’, ‘syslog’
Default: ‘devnull’
Environment variable: TT_AUDIT_LOG_TO

audit_log.syslog.facility¶

Specify a system logger keyword that tells syslogd where to send the message. You can enable logging to a system logger using the audit_log.to option.

compat

The compat section defines values of the compat module options.

Note

compat can be defined in any scope.

compat.binary_data_decoding
compat.box_cfg_replication_sync_timeout
compat.box_error_serialize_verbose
compat.box_error_unpack_type_and_code
compat.box_info_cluster_meaning
compat.box_session_push_deprecation
compat.box_space_execute_priv
compat.box_space_max
compat.box_tuple_extension
compat.box_tuple_new_vararg
compat.c_func_iproto_multireturn
compat.fiber_channel_close_mode
compat.fiber_slice_default
compat.json_escape_forward_slash
compat.sql_priv
compat.sql_seq_scan_default
compat.yaml_pretty_multiline

compat.binary_data_decoding¶

Define how to store binary data fields in Lua after decoding:

new: as varbinary objects
old: as plain strings

conditional

The conditional section defines the configuration parts that apply to instances that meet certain conditions.

Note

conditional can be defined in the global scope only.

conditional.if

conditional.if¶

Specify a conditional section of the configuration. The configuration options defined inside a conditional.if section apply only to instances on which the specified condition is true.

Conditions can include one variable – tarantool_version: a three-number Tarantool version running on the instance, for example, 3.1.0. It compares to version literal values that include three numbers separated by periods (x.y.z).

The following operators are available in conditions:

comparison: >, <, >=, <=, ==, !=
logical operators || (OR) and && (AND)
parentheses ()

Example:

In this example, different configuration parts apply to instances running Tarantool versions above and below 3.1.0:

On versions less than 3.1.0, the upgraded label is set to false.
On versions 3.1.0 or newer, the upgraded label is set to true. Additionally, new compat options are defined. These options were introduced in version 3.1.0, so on older versions they would cause an error.

conditional:
  - if: tarantool_version < 3.1.0
    labels:
      upgraded: 'false'
  - if: tarantool_version >= 3.1.0
    labels:
      upgraded: 'true'
    compat:
      box_error_serialize_verbose: 'new'
      box_error_unpack_type_and_code: 'new'

config

The config section defines various parameters related to centralized configuration.

Note

config can be defined in the global scope only.

config.reload
config.context.*
config.etcd.*
config.storage.*

config.reload¶

Specify how the configuration is reloaded. This option accepts the following values:

auto: configuration is reloaded automatically when it is changed.
manual: configuration should be reloaded manually. In this case, you can reload the configuration in the application code using config:reload().

config.context.*

This section describes options related to loading configuration settings from external storage such as external files or environment variables.

config.context
- config.context.<name>

config.context¶: Specify how to load settings from external storage. For example, this option can be used to load passwords from safe storage. You can find examples in the Loading secrets from safe storage section.

Type: map

Default: nil

Environment variable: TT_CONFIG_CONTEXT

config.context.<name>¶: The name of an entity that identifies a configuration value to load.

config.context.<name>.env¶

The name of an environment variable to load a configuration value from. To load a configuration value from an environment variable, set config.context.<name>.from to env.

Example

In this example, passwords are loaded from the DBADMIN_PASSWORD and SAMPLEUSER_PASSWORD environment variables:

config:
  context:
    dbadmin_password:
      from: env
      env: DBADMIN_PASSWORD
    sampleuser_password:
      from: env
      env: SAMPLEUSER_PASSWORD

config.context.<name>.from¶

The type of storage to load a configuration value from. There are the following storage types:

file: load a configuration value from a file. In this case, you need to specify the path to the file using config.context.<name>.file.
env: load a configuration value from an environment variable. In this case, specify the environment variable name using config.context.<name>.env.

config.context.<name>.file¶

The path to a file to load a configuration value from. To load a configuration value from a file, set config.context.<name>.from to file.

Example

In this example, passwords are loaded from the dbadmin_password.txt and sampleuser_password.txt files:

config:
  context:
    dbadmin_password:
      from: file
      file: secrets/dbadmin_password.txt
      rstrip: true
    sampleuser_password:
      from: file
      file: secrets/sampleuser_password.txt
      rstrip: true

config.context.<name>.rstrip¶: (Optional) Whether to strip whitespace characters and newlines from the end of data.

config.etcd.*

Enterprise Edition

Centralized configuration storages are supported by the Enterprise Edition only.

This section describes options related to providing connection settings to a centralized etcd-based storage. If replication.failover is set to supervised, Tarantool also uses etcd to maintain the state of failover coordinators.

Note

Note that a centralized cluster configuration cannot contain the config.etcd section.

config.etcd.endpoints
config.etcd.prefix
config.etcd.username
config.etcd.password
config.etcd.ssl.ca_file
config.etcd.ssl.ca_path
config.etcd.ssl.ssl_cert
config.etcd.ssl.ssl_key
config.etcd.ssl.verify_host
config.etcd.ssl.verify_peer
config.etcd.http.request.timeout
config.etcd.http.request.unix_socket
config.etcd.watchers.reconnect_max_attempts
config.etcd.watchers.reconnect_timeout

config.etcd.endpoints¶

The list of endpoints used to access an etcd server.

Type: array
Default: nil
Environment variable: TT_CONFIG_ETCD_ENDPOINTS

config.etcd.prefix¶

A key prefix used to search a configuration on an etcd server. Tarantool searches keys by the following path: <prefix>/config/*. Note that <prefix> should start with a slash (/).

Type: string
Default: nil
Environment variable: TT_CONFIG_ETCD_PREFIX

config.etcd.username¶

A username used for authentication.

Type: string
Default: nil
Environment variable: TT_CONFIG_ETCD_USERNAME

config.etcd.password¶

A password used for authentication.

Type: string
Default: nil
Environment variable: TT_CONFIG_ETCD_PASSWORD

config.etcd.ssl.ca_file¶: A path to a trusted certificate authorities (CA) file.

Type: string

Default: nil

Environment variable: TT_CONFIG_ETCD_SSL_CA_FILE

config.etcd.ssl.ca_path¶: A path to a directory holding certificates to verify the peer with.

Type: string

Default: nil

Environment variable: TT_CONFIG_ETCD_SSL_CA_PATH

config.etcd.ssl.ssl_cert¶

Since: 3.2.0

A path to an SSL certificate file.

Type: string
Default: nil
Environment variable: TT_CONFIG_ETCD_SSL_SSL_CERT

config.etcd.ssl.ssl_key¶: A path to a private SSL key file.

Type: string

Default: nil

Environment variable: TT_CONFIG_ETCD_SSL_SSL_KEY

config.etcd.ssl.verify_host¶: Enable verification of the certificate’s name (CN) against the specified host.

Type: boolean

Default: nil

Environment variable: TT_CONFIG_ETCD_SSL_VERIFY_HOST

config.etcd.ssl.verify_peer¶: Enable verification of the peer’s SSL certificate.

Type: boolean

Default: nil

Environment variable: TT_CONFIG_ETCD_SSL_VERIFY_PEER

config.etcd.http.request.timeout¶

A time period required to process an HTTP request to an etcd server: from sending a request to receiving a response.

Type: number
Default: nil
Environment variable: TT_CONFIG_ETCD_HTTP_REQUEST_TIMEOUT

config.etcd.http.request.unix_socket¶: A Unix domain socket used to connect to an etcd server.

Type: string

Default: nil

Environment variable: TT_CONFIG_ETCD_HTTP_REQUEST_UNIX_SOCKET

config.etcd.watchers.reconnect_max_attempts¶

Since: 3.1.0

The maximum number of attempts to reconnect to an etcd server in case of connection failure.

Type: integer
Default: nil
Environment variable: TT_CONFIG_ETCD_WATCHERS_RECONNECT_MAX_ATTEMPTS

config.etcd.watchers.reconnect_timeout¶

Since: 3.1.0

The timeout (in seconds) between attempts to reconnect to an etcd server in case of connection failure.

Type: number
Default: nil
Environment variable: TT_CONFIG_ETCD_WATCHERS_RECONNECT_TIMEOUT

config.storage.*

Enterprise Edition

Centralized configuration storages are supported by the Enterprise Edition only.

This section describes options related to providing connection settings to a centralized Tarantool-based storage.

Note

Note that a centralized cluster configuration cannot contain the config.storage section.

config.storage.endpoints
config.storage.prefix
config.storage.reconnect_after
config.storage.timeout

config.storage.endpoints¶

An array of endpoints used to access a configuration storage. Each endpoint can include the following fields:

uri: a URI of the configuration storage’s instance.
login: a username used to connect to the instance.
password: a password used for authentication.
params: SSL parameters required for encrypted connections (<uri>.params.*).

Type: array
Default: nil
Environment variable: TT_CONFIG_STORAGE_ENDPOINTS

config.storage.prefix¶

A key prefix used to search a configuration in a centralized configuration storage. Tarantool searches keys by the following path: <prefix>/config/*. Note that <prefix> should start with a slash (/).

Type: string
Default: nil
Environment variable: TT_CONFIG_STORAGE_PREFIX

config.storage.reconnect_after¶: A number of seconds to wait before reconnecting to a configuration storage.

Type: number

Default: 3

Environment variable: TT_CONFIG_STORAGE_RECONNECT_AFTER

config.storage.timeout¶

The interval (in seconds) to perform the status check of a configuration storage.

Type: number
Default: 3
Environment variable: TT_CONFIG_STORAGE_TIMEOUT

console

Configure the administrative console. A client to the console is tt connect.

Note

console can be defined in any scope.

console.enabled
console.socket

console.enabled¶

Whether to listen on the Unix socket provided in the console.socket option.

If the option is set to false, the administrative console is disabled.

Type: boolean
Default: true
Environment variable: TT_CONSOLE_ENABLED

console.socket¶

The Unix socket for the administrative console.

Mind the following nuances:

Only a Unix domain socket is allowed. A TCP socket can’t be configured this way.
console.socket is a file path, without any unix: or unix/: prefixes.
If the file path is a relative path, it is interpreted relative to process.work_dir.

Type: string
Default: ‘var/run/{{ instance_name }}/tarantool.control’
Environment variable: TT_CONSOLE_SOCKET

credentials

The credentials section allows you to create users and grant them the specified privileges. Learn more in Credentials.

Note

credentials can be defined in any scope.

credentials.roles.*
credentials.users.*
<user_or_role_name>.privileges.*

credentials.roles.*

credentials.roles
- credentials.roles.<role_name>.roles
- credentials.roles.<role_name>.privileges

credentials.roles¶

An array of roles that can be granted to users or other roles.

Example

In the example below, the writers_space_reader role gets privileges to select data in the writers space:

roles:
  writers_space_reader:
    privileges:
    - permissions: [ read ]
      spaces: [ writers ]

See also: Managing users and roles

Type: map
Default: nil
Environment variable: TT_CREDENTIALS_ROLES

credentials.roles.<role_name>.roles¶: An array of roles granted to this role.

credentials.roles.<role_name>.privileges¶

An array of privileges granted to this role.

See <user_or_role_name>.privileges.*.

credentials.users.*

credentials.users

credentials.users¶

An array of users.

Example

In this example, sampleuser gets the following privileges:

Privileges granted to the writers_space_reader role.
Privileges to select and modify data in the books space.

sampleuser:
  password: '123456'
  roles: [ writers_space_reader ]
  privileges:
  - permissions: [ read, write ]
    spaces: [ books ]

See also: Managing users and roles

Type: map
Default: nil
Environment variable: TT_CREDENTIALS_USERS

credentials.users.<username>.password¶

A user’s password.

Example

In the example below, a password for the dbadmin user is set:

credentials:
  users:
    dbadmin:
      password: 'T0p_Secret_P@$$w0rd'

credentials.users.<username>.roles¶: An array of roles granted to this user.

credentials.users.<username>.privileges¶

An array of privileges granted to this user.

See <user_or_role_name>.privileges.*.

<user_or_role_name>.privileges.*

<user_or_role_name>.privileges

<user_or_role_name>.privileges¶

Privileges that can be granted to a user or role using the following options:

credentials.users.<username>.privileges
credentials.roles.<role_name>.privileges

<user_or_role_name>.privileges.permissions¶

Permissions assigned to this user or a user with this role.

Example

In this example, sampleuser gets privileges to select and modify data in the books space:

sampleuser:
  password: '123456'
  roles: [ writers_space_reader ]
  privileges:
  - permissions: [ read, write ]
    spaces: [ books ]

See also: Managing users and roles

<user_or_role_name>.privileges.spaces¶

Spaces to which this user or a user with this role gets the specified permissions.

Example

In this example, sampleuser gets privileges to select and modify data in the books space:

sampleuser:
  password: '123456'
  roles: [ writers_space_reader ]
  privileges:
  - permissions: [ read, write ]
    spaces: [ books ]

See also: Managing users and roles

<user_or_role_name>.privileges.functions¶: Functions to which this user or a user with this role gets the specified permissions.

<user_or_role_name>.privileges.sequences¶: Sequences to which this user or a user with this role gets the specified permissions.

<user_or_role_name>.privileges.lua_eval¶: Whether this user or a user with this role can execute arbitrary Lua code.

<user_or_role_name>.privileges.lua_call¶

A list of global user-defined Lua functions that this user or a user with this role can call. To allow calling a specific function, specify its name as the value. To allow calling all global Lua functions except built-in ones functions, specify the all value.

This option should be configured together with the execute permission.

Since version 3.3.0, the lua_call option allows granting users privileges to call specified lua function on the instance in runtime (thus it doesn’t require an ability to write to the database).

Example to grant custom functions to the ‘alice’ user:

credentials:
  users:
    alice:
      privileges:
        - permissions: [execute]
          lua_call: [my_func, my_func2]

<user_or_role_name>.privileges.sql¶: Whether this user or a user with this role can execute an arbitrary SQL expression.

database

The database section defines database-specific configuration parameters, such as an instance’s read-write mode or transaction isolation level.

Note

database can be defined in any scope.

database.hot_standby
database.instance_uuid
database.mode
database.replicaset_uuid
database.txn_isolation
database.txn_timeout
database.use_mvcc_engine

database.hot_standby¶

Whether to start the server in the hot standby mode. This mode can be used to provide failover without replication.

Suppose there are two cluster applications. Each cluster has one instance with the same configuration:

groups:
  group001:
    replicasets:
      replicaset001:
        instances:
          instance001:
            database:
              hot_standby: true
            wal:
              dir: /tmp/wals
            snapshot:
              dir: /tmp/snapshots
            iproto:
              listen:
              - uri: '127.0.0.1:3301'

In particular, both instances use the same directory for storing write-ahead logs and snapshots.

When you start both cluster applications on the same machine, the instance from the first one will be the primary instance and the second will be the standby instance. In the logs of the second cluster instance, you should see a notification:

main/104/interactive I> Entering hot standby mode

This means that the standby instance is ready to take over if the primary instance goes down. The standby instance initializes and tries to take a lock on a directory for storing write-ahead logs but fails because the primary instance has made a lock on this directory.

If the primary instance goes down for any reason, the lock is released. In this case, the standby instance succeeds in taking the lock and becomes the primary instance.

database.hot_standby has no effect:

If wal.mode is set to none.
If wal.dir_rescan_delay is set to a large value on macOS or FreeBSD. On these platforms, the hot standby mode is designed so that the loop repeats every wal.dir_rescan_delay seconds.
For spaces created with engine set to vinyl.

Examples on GitHub: hot_standby_1, hot_standby_2

Type: boolean
Default: false
Environment variable: TT_DATABASE_HOT_STANDBY

database.instance_uuid¶

An instance UUID.

By default, instance UUIDs are generated automatically. database.instance_uuid can be used to specify an instance identifier manually.

UUIDs should follow these rules:

The values must be true unique identifiers, not shared by other instances or replica sets within the common infrastructure.
The values must be used consistently, not changed after the initial setup. The initial values are stored in snapshot files and are checked whenever the system is restarted.
The values must comply with RFC 4122. The nil UUID is not allowed.

failover

The failover section defines parameters related to a supervised failover.

Note

failover can be defined in the global scope only.

failover.log.to
failover.log.file
failover.call_timeout
failover.connect_timeout
failover.lease_interval
failover.probe_interval
failover.renew_interval
failover.stateboard.*

failover.log.to¶

Since: 3.3.0

Enterprise Edition

Configuring failover.log.to and failover.log.file parameters is available in the Enterprise Edition only.

Define a location Tarantool sends failover logs to. This option accepts the following values:

stderr: write logs to the standard error stream.
file: write logs to a file (see failover.log.file).

Type: string
Default: ‘stderr’
Environment variable: TT_FAILOVER_LOG_TO

failover.log.file¶

Since: 3.3.0

Specify a file for failover logs destination. To write logs to a file, set failover.log.to to file. Otherwise, failover.log.file is ignored.

Example

The example below shows how to write failover logs to a file placed in the specified directory:

failover:
  log:
    to: file
    file: var/log/failover.log

Type: string
Default: nil
Environment variable: TT_FAILOVER_LOG_FILE

failover.call_timeout¶

Since: 3.1.0

A call timeout (in seconds) for monitoring and failover requests to an instance.

Type: number
Default: 1
Environment variable: TT_FAILOVER_CALL_TIMEOUT

failover.connect_timeout¶

Since: 3.1.0

A connection timeout (in seconds) for monitoring and failover requests to an instance.

Type: number
Default: 1
Environment variable: TT_FAILOVER_CONNECT_TIMEOUT

failover.lease_interval¶

Since: 3.1.0

A time interval (in seconds) that specifies how long an instance should be a leader without renew requests from a coordinator. When this interval expires, the leader switches to read-only mode. This action is performed by the instance itself and works even if there is no connectivity between the instance and the coordinator.

Type: number
Default: 30
Environment variable: TT_FAILOVER_LEASE_INTERVAL

failover.probe_interval¶

Since: 3.1.0

A time interval (in seconds) that specifies how often a monitoring service of the failover coordinator polls an instance for its status.

Type: number
Default: 10
Environment variable: TT_FAILOVER_PROBE_INTERVAL

failover.renew_interval¶

Since: 3.1.0

A time interval (in seconds) that specifies how often a failover coordinator sends read-write deadline renewals.

Type: number
Default: 10
Environment variable: TT_FAILOVER_RENEW_INTERVAL

failover.stateboard.*

failover.stateboard.* options define configuration parameters related to maintaining the state of failover coordinators in a remote etcd-based storage.

failover.stateboard.keepalive_interval
failover.stateboard.renew_interval

failover.stateboard.keepalive_interval¶

Since: 3.1.0

A time interval (in seconds) that specifies how long a transient state information is stored and how quickly a lock expires.

Note

failover.stateboard.keepalive_interval should be smaller than failover.lease_interval. Otherwise, switching of a coordinator causes a replica set leader to go to read-only mode for some time.

Type: number
Default: 10
Environment variable: TT_FAILOVER_STATEBOARD_KEEPALIVE_INTERVAL

failover.stateboard.renew_interval¶

Since: 3.1.0

A time interval (in seconds) that specifies how often a failover coordinator writes its state information to etcd. This option also determines the frequency at which an active coordinator reads new commands from etcd.

Type: number
Default: 2
Environment variable: TT_FAILOVER_STATEBOARD_RENEW_INTERVAL

feedback

The feedback section describes configuration parameters for sending information about a running Tarantool instance to the specified feedback server.

Note

feedback can be defined in any scope.

feedback.crashinfo
feedback.enabled
feedback.host
feedback.interval
feedback.metrics_collect_interval
feedback.metrics_limit
feedback.send_metrics

feedback.crashinfo¶

Whether to send crash information in the case of an instance failure. This information includes:

General information from the uname output.
Build information.
The crash reason.
The stack trace.

To turn off sending crash information, set this option to false.

Type: boolean
Default: true
Environment variable: TT_FEEDBACK_CRASHINFO

feedback.enabled¶: Whether to send information about a running instance to the feedback server. To turn off sending feedback, set this option to false.

Type: boolean

Default: true

Environment variable: TT_FEEDBACK_ENABLED

feedback.host¶: The address to which information is sent.

Type: string

Default: https://feedback.tarantool.io

Environment variable: TT_FEEDBACK_HOST

feedback.interval¶: The interval (in seconds) of sending information.

Type: number

Default: 3600

Environment variable: TT_FEEDBACK_INTERVAL

feedback.metrics_collect_interval¶: The interval (in seconds) for collecting metrics.

Type: number

Default: 60

Environment variable: TT_FEEDBACK_METRICS_COLLECT_INTERVAL

feedback.metrics_limit¶: The maximum size of memory (in bytes) used to store metrics before sending them to the feedback server. If the size of collected metrics exceeds this value, earlier metrics are dropped.

Type: integer

Default: 1024 * 1024 (1048576)

Environment variable: TT_FEEDBACK_METRICS_LIMIT

feedback.send_metrics¶: Whether to send metrics to the feedback server. Note that all collected metrics are dropped after sending them to the feedback server.

Type: boolean

Default: true

Environment variable: TT_FEEDBACK_SEND_METRICS

fiber

The fiber section describes options related to configuring fibers, yields, and cooperative multitasking.

Note

fiber can be defined in any scope.

fiber.io_collect_interval
fiber.too_long_threshold
fiber.worker_pool_threads
fiber.slice.*
fiber.top.*

fiber.io_collect_interval¶

The time period (in seconds) a fiber sleeps between iterations of the event loop.

fiber.io_collect_interval can be used to reduce CPU load in deployments where the number of client connections is large, but requests are not so frequent (for example, each connection issues just a handful of requests per second).

Type: number
Default: box.NULL
Environment variable: TT_FIBER_IO_COLLECT_INTERVAL

fiber.too_long_threshold¶

If processing a request takes longer than the given period (in seconds), the fiber warns about it in the log.

fiber.too_long_threshold has effect only if log.level is greater than or equal to 4 (warn).

Type: number
Default: 0.5
Environment variable: TT_FIBER_TOO_LONG_THRESHOLD

fiber.worker_pool_threads¶: The maximum number of threads to use during execution of certain internal processes (for example, socket.getaddrinfo() and coio_call()).

Type: number

Default: 4

Environment variable: TT_FIBER_WORKER_POOL_THREADS

fiber.slice.*

This section describes options related to configuring time periods for fiber slices. See fiber.set_max_slice for details and examples.

fiber.slice.warn
fiber.slice.err

fiber.slice.warn¶: Set a time period (in seconds) that specifies the warning slice.

Type: number

Default: 0.5

Environment variable: TT_FIBER_SLICE_WARN

fiber.slice.err¶: Set a time period (in seconds) that specifies the error slice.

Type: number

Default: 1

Environment variable: TT_FIBER_SLICE_ERR

fiber.top.*

This section describes options related to configuring the fiber.top() function, normally used for debug purposes. fiber.top() shows all alive fibers and their CPU consumption.

fiber.top.enabled

fiber.top.enabled¶

Enable or disable the fiber.top() function.

Enabling fiber.top() slows down fiber switching by about 15%, so it is disabled by default.

Type: boolean
Default: false
Environment variable: TT_FIBER_TOP_ENABLED

flightrec

Enterprise Edition

Configuring flightrec parameters is available in the Enterprise Edition only.

The flightrec section describes options related to the flight recorder configuration.

Note

flightrec can be defined in any scope.

flightrec.enabled
flightrec.logs_size
flightrec.logs_max_msg_size
flightrec.logs_log_level
flightrec.metrics_period
flightrec.metrics_interval
flightrec.requests_size
flightrec.requests_max_req_size
flightrec.requests_max_res_size

flightrec.enabled¶: Enable the flight recorder.

Type: boolean

Default: false

Environment variable: TT_FLIGHTREC_ENABLED

flightrec.logs_size¶: Specify the size (in bytes) of the log storage. You can set this option to 0 to disable the log storage.

Type: integer

Default: 10485760

Environment variable: TT_FLIGHTREC_LOGS_SIZE

flightrec.logs_max_msg_size¶: Specify the maximum size (in bytes) of the log message. The log message is truncated if its size exceeds this limit.

Type: integer

Default: 4096

Maximum: 16384

Environment variable: TT_FLIGHTREC_LOGS_MAX_MSG_SIZE

flightrec.logs_log_level¶: Specify the level of detail the log has. The default value is 6 (VERBOSE). You can learn more about log levels from the log_level option description. Note that the flightrec.logs_log_level value might differ from log_level.

Type: integer

Default: 6

Environment variable: TT_FLIGHTREC_LOGS_LOG_LEVEL

flightrec.metrics_period¶: Specify the time period (in seconds) that defines how long metrics are stored from the moment of dump. So, this value defines how much historical metrics data is collected up to the moment of crash. The frequency of metric dumps is defined by flightrec.metrics_interval.

Type: integer

Default: 180

Environment variable: TT_FLIGHTREC_METRICS_PERIOD

flightrec.metrics_interval¶

Specify the time interval (in seconds) that defines the frequency of dumping metrics. This value shouldn’t exceed flightrec.metrics_period.

Type: number
Default: 1.0
Minimum: 0.001
Environment variable: TT_FLIGHTREC_METRICS_INTERVAL

Note

Given that the average size of a metrics entry is 2 kB, you can estimate the size of the metrics storage as follows:

(flightrec_metrics_period / flightrec_metrics_interval) * 2 kB

flightrec.requests_size¶: Specify the size (in bytes) of storage for the request and response data. You can set this parameter to 0 to disable a storage of requests and responses.

Type: integer

Default: 10485760

Environment variable: TT_FLIGHTREC_REQUESTS_SIZE

flightrec.requests_max_req_size¶: Specify the maximum size (in bytes) of a request entry. A request entry is truncated if this size is exceeded.

Type: integer

Default: 16384

Environment variable: TT_FLIGHTREC_REQUESTS_MAX_REQ_SIZE

flightrec.requests_max_res_size¶: Specify the maximum size (in bytes) of a response entry. A response entry is truncated if this size is exceeded.

Type: integer

Default: 16384

Environment variable: TT_FLIGHTREC_REQUESTS_MAX_RES_SIZE

iproto

The iproto section is used to configure parameters related to communicating to and between cluster instances.

Note

iproto can be defined in any scope.

iproto.listen
iproto.net_msg_max
iproto.readahead
iproto.threads
iproto.advertise.*
<uri>.params.*

iproto.listen¶

An array of URIs used to listen for incoming requests. If required, you can enable SSL for specific URIs by providing additional parameters (<uri>.params.*).

Note that a URI value can’t contain parameters, a login, or a password.

Example

In the example below, iproto.listen is set explicitly for each instance in a cluster:

groups:
  group001:
    replicasets:
      replicaset001:
        instances:
          instance001:
            iproto:
              listen:
              - uri: '127.0.0.1:3301'
          instance002:
            iproto:
              listen:
              - uri: '127.0.0.1:3302'
          instance003:
            iproto:
              listen:
              - uri: '127.0.0.1:3303'

iproto.advertise.*

iproto.advertise.client
iproto.advertise.peer
iproto.advertise.sharding
iproto.advertise.<peer_or_sharding>.*

iproto.advertise.client¶

A URI used to advertise the current instance to clients.

The iproto.advertise.client option accepts a URI in the following formats:

An address: host:port.
A Unix domain socket: unix/:.

Note that this option doesn’t allow to set a username and password. If a remote client needs this information, it should be delivered outside of the cluster configuration.

Note

The host value cannot be 0.0.0.0/[::] and the port value cannot be 0.

Type: string
Default: box.NULL
Environment variable: TT_IPROTO_ADVERTISE_CLIENT

iproto.advertise.peer¶

Settings used to advertise the current instance to other cluster members. The format of these settings is described in iproto.advertise.<peer_or_sharding>.*.

Example

In the example below, the following configuration options are specified:

In the credentials section, the replicator user with the replication role is created.
iproto.advertise.peer specifies that other instances should connect to an address defined in iproto.listen using the replicator user.

credentials:
  users:
    replicator:
      password: 'topsecret'
      roles: [replication]

iproto:
  advertise:
    peer:
      login: replicator

replication:
  failover: election

groups:
  group001:
    replicasets:
      replicaset001:
        instances:
          instance001:
            iproto:
              listen:
              - uri: '127.0.0.1:3301'
          instance002:
            iproto:
              listen:
              - uri: '127.0.0.1:3302'
          instance003:
            iproto:
              listen:
              - uri: '127.0.0.1:3303'

Type: map
Environment variable: see iproto.advertise.<peer_or_sharding>.*

iproto.advertise.sharding¶

Settings used to advertise the current instance to a router and rebalancer. The format of these settings is described in iproto.advertise.<peer_or_sharding>.*.

Note

If iproto.advertise.sharding is not specified, advertise settings from iproto.advertise.peer are used.

Example

In the example below, the following configuration options are specified:

In the credentials section, the replicator and storage users are created.
iproto.advertise.peer specifies that other instances should connect to an address defined in iproto.listen with the replicator user.
iproto.advertise.sharding specifies that a router should connect to storages using an address defined in iproto.listen with the storage user.

credentials:
  users:
    replicator:
      password: 'topsecret'
      roles: [replication]
    storage:
      password: 'secret'
      roles: [sharding]

iproto:
  advertise:
    peer:
      login: replicator
    sharding:
      login: storage

Type: map
Environment variable: see iproto.advertise.<peer_or_sharding>.*

iproto.advertise.<peer_or_sharding>.*

iproto.advertise.<peer_or_sharding>.uri
iproto.advertise.<peer_or_sharding>.login
iproto.advertise.<peer_or_sharding>.password
iproto.advertise.<peer_or_sharding>.params

iproto.advertise.<peer_or_sharding>.uri¶: (Optional) A URI used to advertise the current instance. By default, the URI defined in iproto.listen is used to advertise the current instance.

Note

The host value cannot be 0.0.0.0/[::] and the port value cannot be 0.

Type: string

Default: nil

Environment variable: TT_IPROTO_ADVERTISE_PEER_URI, TT_IPROTO_ADVERTISE_SHARDING_URI

iproto.advertise.<peer_or_sharding>.login¶: (Optional) A username used to connect to the current instance. If a username is not set, the guest user is used.

Type: string

Default: nil

Environment variable: TT_IPROTO_ADVERTISE_PEER_LOGIN, TT_IPROTO_ADVERTISE_SHARDING_LOGIN

iproto.advertise.<peer_or_sharding>.password¶: (Optional) A password for the specified user. If a login is specified but a password is missing, it is taken from the user’s credentials.

Type: string

Default: nil

Environment variable: TT_IPROTO_ADVERTISE_PEER_PASSWORD, TT_IPROTO_ADVERTISE_SHARDING_PASSWORD

iproto.advertise.<peer_or_sharding>.params¶: (Optional) URI parameters (<uri>.params.*) required for connecting to the current instance.

<uri>.params.*

Enterprise Edition

TLS traffic encryption is supported by the Enterprise Edition only.

URI parameters that can be used in the iproto.listen.<uri>.params and iproto.advertise.<peer_or_sharding>.params options.

<uri>.params.transport
<uri>.params.ssl_ca_file
<uri>.params.ssl_cert_file
<uri>.params.ssl_ciphers
<uri>.params.ssl_key_file
<uri>.params.ssl_password
<uri>.params.ssl_password_file

Note

Note that <uri>.params.* options don’t have corresponding environment variables for URIs specified in iproto.listen.

<uri>.params.transport¶

Allows you to enable traffic encryption for client-server communications over binary connections. In a Tarantool cluster, one instance might act as the server that accepts connections from other instances and the client that connects to other instances.

<uri>.params.transport accepts one of the following values:

plain (default): turn off traffic encryption.
ssl: encrypt traffic by using the TLS 1.2 protocol (Enterprise Edition only).

Example

The example below demonstrates how to enable traffic encryption by using a self-signed server certificate. The following parameters are specified for each instance:

ssl_cert_file: a path to an SSL certificate file.
ssl_key_file: a path to a private SSL key file.

replicaset001:
  replication:
    failover: manual
  leader: instance001
  iproto:
    advertise:
      peer:
        login: replicator
  instances:
    instance001:
      iproto:
        listen:
        - uri: '127.0.0.1:3301'
          params:
            transport: 'ssl'
            ssl_cert_file: 'certs/server.crt'
            ssl_key_file: 'certs/server.key'
    instance002:
      iproto:
        listen:
        - uri: '127.0.0.1:3302'
          params:
            transport: 'ssl'
            ssl_cert_file: 'certs/server.crt'
            ssl_key_file: 'certs/server.key'
    instance003:
      iproto:
        listen:
        - uri: '127.0.0.1:3303'
          params:
            transport: 'ssl'
            ssl_cert_file: 'certs/server.crt'
            ssl_key_file: 'certs/server.key'

Example on Github: ssl_without_ca

Type: string
Default: ‘plain’
Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_TRANSPORT, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_TRANSPORT

<uri>.params.ssl_ca_file¶

(Optional) A path to a trusted certificate authorities (CA) file. If not set, the peer won’t be checked for authenticity.

Both a server and a client can use the ssl_ca_file parameter:

If it’s on the server side, the server verifies the client.
If it’s on the client side, the client verifies the server.
If both sides have the CA files, the server and the client verify each other.

See also: <uri>.params.transport

Type: string
Default: nil
Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_CA_FILE, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_CA_FILE

<uri>.params.ssl_cert_file¶

A path to an SSL certificate file:

For a server, it’s mandatory.
For a client, it’s mandatory if the ssl_ca_file parameter is set for a server; otherwise, optional.

See also: <uri>.params.transport

Type: string
Default: nil
Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_CERT_FILE, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_CERT_FILE

<uri>.params.ssl_ciphers¶

(Optional) A colon-separated (:) list of SSL cipher suites the connection can use. Note that the list is not validated: if a cipher suite is unknown, Tarantool ignores it, doesn’t establish the connection, and writes to the log that no shared cipher was found.

The supported cipher suites are:

ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384
DHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-CHACHA20-POLY1305
ECDHE-RSA-CHACHA20-POLY1305
DHE-RSA-CHACHA20-POLY1305
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-GCM-SHA256
DHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES256-SHA384
ECDHE-RSA-AES256-SHA384
DHE-RSA-AES256-SHA256
ECDHE-ECDSA-AES128-SHA256
ECDHE-RSA-AES128-SHA256
DHE-RSA-AES128-SHA256
ECDHE-ECDSA-AES256-SHA
ECDHE-RSA-AES256-SHA
DHE-RSA-AES256-SHA
ECDHE-ECDSA-AES128-SHA
ECDHE-RSA-AES128-SHA
DHE-RSA-AES128-SHA
AES256-GCM-SHA384
AES128-GCM-SHA256
AES256-SHA256
AES128-SHA256
AES256-SHA
AES128-SHA
GOST2012-GOST8912-GOST8912
GOST2001-GOST89-GOST89

For detailed information on SSL ciphers and their syntax, refer to OpenSSL documentation.

See also: <uri>.params.transport

Type: string
Default: nil
Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_CIPHERS, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_CIPHERS

<uri>.params.ssl_key_file¶

A path to a private SSL key file:

For a server, it’s mandatory.
For a client, it’s mandatory if the ssl_ca_file parameter is set for a server; otherwise, optional.

If the private key is encrypted, provide a password for it in the ssl_password or ssl_password_file parameter.

See also: <uri>.params.transport

Type: string
Default: nil
Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_KEY_FILE, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_KEY_FILE

<uri>.params.ssl_password¶

(Optional) A password for an encrypted private SSL key provided using ssl_key_file. Alternatively, the password can be provided in ssl_password_file.

Tarantool applies the ssl_password and ssl_password_file parameters in the following order:

If ssl_password is provided, Tarantool tries to decrypt the private key with it.
If ssl_password is incorrect or isn’t provided, Tarantool tries all passwords from ssl_password_file one by one in the order they are written.
If ssl_password and all passwords from ssl_password_file are incorrect, or none of them is provided, Tarantool treats the private key as unencrypted.

See also: <uri>.params.transport

Type: string
Default: nil
Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_PASSWORD, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_PASSWORD

<uri>.params.ssl_password_file¶

(Optional) A text file with one or more passwords for encrypted private SSL keys provided using ssl_key_file (each on a separate line). Alternatively, the password can be provided in ssl_password.

See also: <uri>.params.transport

Type: string
Default: nil
Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_PASSWORD_FILE, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_PASSWORD_FILE

groups

The groups section provides the ability to define the full topology of a Tarantool cluster.

Note

groups can be defined in the global scope only.

groups.<group_name>
groups.<group_name>.replicasets
groups.<group_name>.<config_parameter>

groups.<group_name>¶

A group name.

The following rules are applied to group names:

The maximum number of symbols is 63.
Should start with a letter.
Can contain lowercase letters (a-z).
Can contain digits (0-9).
Can contain the following characters: -, _.

groups.<group_name>.replicasets¶: Replica sets that belong to this group. See replicasets.

groups.<group_name>.<config_parameter>¶: Any configuration parameter that can be defined in the group scope. For example, iproto and database configuration parameters defined at the group level are applied to all instances in this group.

replicasets

Note

replicasets can be defined in the group scope only.

replicasets.<replicaset_name>
replicasets.<replicaset_name>.leader
replicasets.<replicaset_name>.bootstrap_leader
replicasets.<replicaset_name>.instances
replicasets.<replicaset_name>.<config_parameter>

replicasets.<replicaset_name>¶

A replica set name.

Note that the rules applied to a replica set name are the same as for groups. Learn more in groups.<group_name>.

replicasets.<replicaset_name>.leader¶

A replica set leader. This option can be used to set a replica set leader when manual replication.failover is used.

To perform controlled failover, <replicaset_name>.leader can be temporarily removed or set to null.

Example

replication:
  failover: manual

groups:
  group001:
    replicasets:
      replicaset001:
        leader: instance001
        instances:
          instance001:
            iproto:
              listen:
              - uri: '127.0.0.1:3301'
          instance002:
            iproto:
              listen:
              - uri: '127.0.0.1:3302'
          instance003:
            iproto:
              listen:
              - uri: '127.0.0.1:3303'

replicasets.<replicaset_name>.bootstrap_leader¶

A bootstrap leader for a replica set. To specify a bootstrap leader manually, you need to set replication.bootstrap_strategy to config.

Example

groups:
  group001:
    replicasets:
      replicaset001:
        replication:
          bootstrap_strategy: config
        bootstrap_leader: instance001
        instances:
          instance001:
            iproto:
              listen:
              - uri: '127.0.0.1:3301'
          instance002:
            iproto:
              listen:
              - uri: '127.0.0.1:3302'
          instance003:
            iproto:
              listen:
              - uri: '127.0.0.1:3303'

replicasets.<replicaset_name>.instances¶: Instances that belong to this replica set. See instances.

replicasets.<replicaset_name>.<config_parameter>¶: Any configuration parameter that can be defined in the replica set scope. For example, iproto and database configuration parameters defined at the replica set level are applied to all instances in this replica set.

instances

Note

instances can be defined in the replica set scope only.

instances.<instance_name>
instances.<instance_name>.<config_parameter>

instances.<instance_name>¶

An instance name.

Note that the rules applied to an instance name are the same as for groups. Learn more in groups.<group_name>.

instances.<instance_name>.<config_parameter>¶: Any configuration parameter that can be defined in the instance scope. For example, iproto and database configuration parameters defined at the instance level are applied to this instance only.

isolated mode

Since version 3.3.0, a new isolated option is added to instance configuration.

The option takes boolean values, by default it is set to false. isolated: true moves the instance it has been applied at to the isolated mode.

The isolated mode allows the user to temporarily isolate an instance and perform maintenance activities on it.

In the isolated mode:

The instance is moved to the read-only state
iproto stops listening for new connections
iproto drops all the current connections
The instance is disconnected from all the replication upstreams
Other replicaset members exclude the isolated instance from the replication upstreams

Note

Isolated instance can’t be bootstrapped (a local snapshot is required to start).

Example

The example below shows how to isolate an instance:

groups:
  g:
    replicasets:
      r:
        instances:
          i-001: {}
          i-002: {}
          i-003: {}
          i-004:
            isolated: true

labels

The labels section allows adding custom attributes to the configuration. Attributes must be key: value pairs with string keys and values.

Note

labels can be defined in any scope.

labels.<label_name>

labels.<label_name>¶

A value of the label with the specified name.

Example

The example below shows how to define labels on the replica set and instance levels:

groups:
  group001:
    replicasets:
      replicaset001:
        labels:
          dc: 'east'
          production: 'false'
        instances:
          instance001:
            labels:
              rack: '10'
              production: 'true'

log

The log section defines configuration parameters related to logging. To handle logging in your application, use the log module.

Note

log can be defined in any scope.

log.to
log.file
log.format
log.level
log.modules
log.nonblock
log.pipe
log.syslog.*

log.to¶

Define a location Tarantool sends logs to. This option accepts the following values:

stderr: write logs to the standard error stream.
file: write logs to a file (see log.file).
pipe: start a program and write logs to its standard input (see log.pipe).
syslog: write logs to a system logger (see log.syslog.*).

Type: string
Default: ‘stderr’
Environment variable: TT_LOG_TO

log.file¶

Specify a file for logs destination. To write logs to a file, you need to set log.to to file. Otherwise, log.file is ignored.

Example

The example below shows how to write logs to a file placed in the specified directory:

log:
  to: file
  file: var/log/{{ instance_name }}/instance.log

Example on GitHub: log_file

Type: string
Default: ‘var/log/{{ instance_name }}/tarantool.log’
Environment variable: TT_LOG_FILE

log.format¶

Specify a format that is used for a log entry. The following formats are supported:

plain: a log entry is formatted as plain text. Example:

2024-04-09 11:00:10.369 [12089] main/104/interactive I> log level 5 (INFO)

json: a log entry is formatted as JSON and includes additional fields. Example:

{
  "time": "2024-04-09T11:00:57.174+0300",
  "level": "INFO",
  "message": "log level 5 (INFO)",
  "pid": 12160,
  "cord_name": "main",
  "fiber_id": 104,
  "fiber_name": "interactive",
  "file": "src/main.cc",
  "line": 498
}

Type: string
Default: ‘plain’
Environment variable: TT_LOG_FORMAT

log.level¶

Specify the level of detail logs have. There are the following levels:

0 – fatal
1 – syserror
2 – error
3 – crit
4 – warn
5 – info
6 – verbose
7 – debug

By setting log.level, you can enable logging of all events with severities above or equal to the given level.

Example

The example below shows how to log all events with severities above or equal to the VERBOSE level.

log:
  level: 'verbose'

Example on GitHub: log_level

Type: number, string
Default: 5
Environment variable: TT_LOG_LEVEL

log.modules¶

Configure the specified log levels (log.level) for different modules.

You can specify a logging level for the following module types:

Modules (files) that use the default logger. Example: Set log levels for files that use the default logger.
Modules that use custom loggers created using the log.new() function. Example: Set log levels for modules that use custom loggers.
The tarantool module that enables you to configure the logging level for Tarantool core messages. Specifically, it configures the logging level for messages logged from non-Lua code, including C modules. Example: Set a log level for C modules.

Example 1: Set log levels for files that use the default logger

Suppose you have two identical modules placed by the following paths: test/module1.lua and test/module2.lua. These modules use the default logger and look as follows:

return {
    say_hello = function()
        local log = require('log')
        log.info('Info message from module1')
    end
}

To configure logging levels, you need to provide module names corresponding to paths to these modules:

log:
  modules:
    test.module1: 'verbose'
    test.module2: 'error'
app:
  file: 'app.lua'

To load these modules in your application (app.lua), you need to add the corresponding require directives:

module1 = require('test.module1')
module2 = require('test.module2')

Given that module1 has the verbose logging level and module2 has the error level, calling module1.say_hello() shows a message but module2.say_hello() is swallowed:

-- Prints 'info' messages --
module1.say_hello()
--[[
[92617] main/103/interactive/test.logging.module1 I> Info message from module1
---
...
--]]

-- Swallows 'info' messages --
module2.say_hello()
--[[
---
...
--]]

Example on GitHub: log_existing_modules

Example 2: Set log levels for modules that use custom loggers

This example shows how to set the verbose level for module1 and the error level for module2:

log:
  modules:
    module1: 'verbose'
    module2: 'error'
app:
  file: 'app.lua'

To create custom loggers in your application (app.lua), call the log.new() function:

-- Creates new loggers --
module1_log = require('log').new('module1')
module2_log = require('log').new('module2')

Given that module1 has the verbose logging level and module2 has the error level, calling module1_log.info() shows a message but module2_log.info() is swallowed:

-- Prints 'info' messages --
module1_log.info('Info message from module1')
--[[
[16300] main/103/interactive/module1 I> Info message from module1
---
...
--]]

-- Swallows 'debug' messages --
module1_log.debug('Debug message from module1')
--[[
---
...
--]]

-- Swallows 'info' messages --
module2_log.info('Info message from module2')
--[[
---
...
--]]

Example on GitHub: log_new_modules

Example 3: Set a log level for C modules

This example shows how to set the info level for the tarantool module:

log:
  modules:
    tarantool: 'info'
app:
  file: 'app.lua'

The specified level affects messages logged from C modules:

ffi = require('ffi')

-- Prints 'info' messages --
ffi.C._say(ffi.C.S_INFO, nil, 0, nil, 'Info message from C module')
--[[
[6024] main/103/interactive I> Info message from C module
---
...
--]]

-- Swallows 'debug' messages --
ffi.C._say(ffi.C.S_DEBUG, nil, 0, nil, 'Debug message from C module')
--[[
---
...
--]]

The example above uses the LuaJIT ffi library to call C functions provided by the say module.

Example on GitHub: log_existing_c_modules

Type: map
Default: box.NULL
Environment variable: TT_LOG_MODULES

log.nonblock¶: Specify the logging behavior if the system is not ready to write. If set to true, Tarantool does not block during logging if the system is non-writable and writes a message instead. Using this value may improve logging performance at the cost of losing some log messages.

Note

The option only has an effect if the log.to is set to syslog or pipe.

Type: boolean

Default: false

Environment variable: TT_LOG_NONBLOCK

log.pipe¶

Start a program and write logs to its standard input (stdin). To send logs to a program’s standard input, you need to set log.to to pipe.

Example

In the example below, Tarantool writes logs to the standard input of cronolog:

log:
  to: pipe
  pipe: 'cronolog tarantool.log'

Example on GitHub: log_pipe

Type: string
Default: box.NULL
Environment variable: TT_LOG_PIPE

log.syslog.*

log.syslog.facility
log.syslog.identity
log.syslog.server

log.syslog.facility¶: Specify the syslog facility to be used when syslog is enabled. To write logs to syslog, you need to set log.to to syslog.

Type: string

Possible values: ‘auth’, ‘authpriv’, ‘cron’, ‘daemon’, ‘ftp’, ‘kern’, ‘lpr’, ‘mail’, ‘news’, ‘security’, ‘syslog’, ‘user’, ‘uucp’, ‘local0’, ‘local1’, ‘local2’, ‘local3’, ‘local4’, ‘local5’, ‘local6’, ‘local7’

Default: ‘local7’

Environment variable: TT_LOG_SYSLOG_FACILITY

log.syslog.identity¶: Specify an application name used to identify Tarantool messages in syslog logs. To write logs to syslog, you need to set log.to to syslog.

Type: string

Default: ‘tarantool’

Environment variable: TT_LOG_SYSLOG_IDENTITY

log.syslog.server¶

Set a location of a syslog server. This option accepts one of the following values:

An IPv4 address. Example: 127.0.0.1:514.
A Unix socket path starting with unix:. Examples: unix:/dev/log on Linux or unix:/var/run/syslog on macOS.

To write logs to syslog, you need to set log.to to syslog.

Example

In the example below, Tarantool writes logs to a syslog server that listens for logging messages on the 127.0.0.1:514 address:

log:
  to: syslog
  syslog:
    server: '127.0.0.1:514'

Example on GitHub: log_syslog

Type: string
Default: box.NULL
Environment variable: TT_LOG_SYSLOG_SERVER

lua

The lua section outlines the configuration parameters related to the Lua environment within Tarantool.

Note

lua can be defined in any scope.

lua.memory

lua.memory¶

Specifies the maximum memory amount available to Lua scripts, measured in bytes.

When the specified value exceeds the current memory usage, the new limit takes effect immediately without a restart. However, when the specified value is lower than the current memory usage, a restart of the instance is required for the change to take effect.

Example to set the Lua memory limit to 4 GB:

lua:
    memory: 4294967296

Type: integer
Default: 2147483648 (2GB)
Environment variable: TT_LUA_MEMORY

memtx

The memtx section is used to configure parameters related to the memtx engine.

Note

memtx can be defined in any scope.

memtx.allocator
memtx.max_tuple_size
memtx.memory
memtx.min_tuple_size
memtx.slab_alloc_factor
memtx.slab_alloc_granularity
memtx.sort_threads

memtx.allocator¶

Specify the allocator that manages memory for memtx tuples. Possible values:

system – the memory is allocated as needed, checking that the quota is not exceeded. THe allocator is based on the malloc function.
small – a slab allocator. The allocator repeatedly uses a memory block to allocate objects of the same type. Note that this allocator is prone to unresolvable fragmentation on specific workloads, so you can switch to system in such cases.

Type: string
Default: ‘small’
Environment variable: TT_MEMTX_ALLOCATOR

memtx.max_tuple_size¶: Size of the largest allocation unit for the memtx storage engine in bytes. It can be increased if it is necessary to store large tuples.

Type: integer

Default: 1048576

Environment variable: TT_MEMTX_MAX_TUPLE_SIZE

memtx.memory¶

The amount of memory in bytes that Tarantool allocates to store tuples. When the limit is reached, INSERT and UPDATE requests fail with the ER_MEMORY_ISSUE error. The server does not go beyond the memtx.memory limit to allocate tuples, but there is additional memory used to store indexes and connection information.

Example

In the example below, the memory size is set to 1 GB (1073741824 bytes).

memtx:
  memory: 1073741824

Type: integer
Default: 268435456
Environment variable: TT_MEMTX_MEMORY

memtx.min_tuple_size¶: Size of the smallest allocation unit in bytes. It can be decreased if most of the tuples are very small.

Type: integer

Default: 16

Possible values: between 8 and 1048280 inclusive

Environment variable: TT_MEMTX_MIN_TUPLE_SIZE

memtx.slab_alloc_factor¶

The multiplier for computing the sizes of memory chunks that tuples are stored in. A lower value may result in less wasted memory depending on the total amount of memory available and the distribution of item sizes.

metrics

The metrics section defines configuration parameters for metrics.

Note

metrics can be defined in any scope.

metrics.exclude
metrics.include
metrics.labels

metrics.exclude¶

An array containing the metrics to turn off. The array can contain the same values as the exclude configuration parameter passed to metrics.cfg().

Example

metrics:
  include: [ all ]
  exclude: [ vinyl ]
  labels:
    alias: '{{ instance_name }}'

Type: array
Default: []
Environment variable: TT_METRICS_EXCLUDE

metrics.include¶: An array containing the metrics to turn on. The array can contain the same values as the include configuration parameter passed to metrics.cfg().

Type: array

Default: [ all ]

Environment variable: TT_METRICS_INCLUDE

metrics.labels¶: Global labels to be added to every observation.

Type: map

Default: { alias = names.instance_name }

Environment variable: TT_METRICS_LABELS

process

The process section defines configuration parameters of the Tarantool process in the system.

Note

process can be defined in any scope.

process.background
process.coredump
process.title
process.pid_file
process.strip_core
process.username
process.work_dir

process.background¶

Run the server as a daemon process.

If this option is set to true, Tarantool log location defined by the log.to option should be set to file, pipe, or syslog – anything other than stderr, the default, because a daemon process is detached from a terminal and it can’t write to the terminal’s stderr.

Important

Do not enable the background mode for applications intended to run by the tt utility. For more information, see the tt start reference.

Type: boolean
Default: false
Environment variable: TT_PROCESS_BACKGROUND

process.coredump¶

Create coredump files.

Usually, an administrator needs to call ulimit -c unlimited (or set corresponding options in systemd’s unit file) before running a Tarantool process to get core dumps. If process.coredump is enabled, Tarantool sets the corresponding resource limit by itself and the administrator doesn’t need to call ulimit -c unlimited (see man 3 setrlimit).

This option also sets the state of the dumpable attribute, which is enabled by default, but may be dropped in some circumstances (according to man 2 prctl, see PR_SET_DUMPABLE).

Type: boolean
Default: false
Environment variable: TT_PROCESS_COREDUMP

process.title¶

Add the given string to the server’s process title (it is shown in the COMMAND column for the Linux commands ps -ef and top -c).

For example, if you set the option to myservice - {{ instance_name }}:

process:
  title: myservice - {{ instance_name }}

ps -ef might show the Tarantool server process like this:

$ ps -ef | grep tarantool
503      68100 68098  0 10:33 pts/2    00:00.10 tarantool <running>: myservice instance1

Type: string
Default: ‘tarantool - {{ instance_name }}’
Environment variable: TT_PROCESS_TITLE

process.pid_file¶

Store the process id in this file.

This option may contain a relative file path. In this case, it is interpreted as relative to process.work_dir.

Type: string
Default: ‘var/run/{{ instance_name }}/tarantool.pid’
Environment variable: TT_PROCESS_PID_FILE

process.strip_core¶: Whether coredump files should not include memory allocated for tuples – this memory can be large if Tarantool runs under heavy load. Setting to true means “do not include”.

Type: boolean

Default: true

Environment variable: TT_PROCESS_STRIP_CORE

process.username¶: The name of the system user to switch to after start.

Type: string

Default: box.NULL

Environment variable: TT_PROCESS_USERNAME

process.work_dir¶

A directory where Tarantool working files will be stored (database files, logs, a PID file, a console Unix socket, and other files if an application generates them in the current directory). The server instance switches to process.work_dir with chdir(2) after start.

If set as a relative file path, it is relative to the current working directory, from where Tarantool is started. If not specified, defaults to the current working directory.

Other directory and file parameters, if set as relative paths, are interpreted as relative to process.work_dir, for example, directories for storing snapshots and write-ahead logs.

Type: string
Default: box.NULL
Environment variable: TT_PROCESS_WORK_DIR

replication

The replication section defines configuration parameters related to replication.

replication.anon
replication.autoexpel
replication.anon
replication.bootstrap_strategy
replication.connect_timeout
replication.election_mode
replication.election_timeout
replication.election_fencing_mode
replication.failover
replication.peers
replication.skip_conflict
replication.sync_lag
replication.sync_timeout
replication.synchro_queue_max_size
replication.synchro_quorum
replication.synchro_timeout
replication.threads
replication.timeout

replication.anon¶

Whether to make the current instance act as an anonymous replica. Anonymous replicas are read-only and can be used, for example, for backups.

To make the specified instance act as an anonymous replica, set replication.anon to true:

instance003:
  replication:
    anon: true

You can find the full example on GitHub: anonymous_replica.

Anonymous replicas are not displayed in the box.info.replication section. You can check their status using box.info.replication_anon().

While anonymous replicas are read-only, you can write data to replication-local and temporary spaces (created with is_local = true and temporary = true, respectively). Given that changes to replication-local spaces are allowed, an anonymous replica might increase the 0 component of the vclock value.

Here are the limitations of having anonymous replicas in a replica set:

A replica set must contain at least one non-anonymous instance.
An anonymous replica can’t be configured as a writable instance by setting database.mode to rw or making it a leader using <replicaset_name>.leader.
If replication.failover is set to election, an anonymous replica can have replication.election_mode set to off only.
If replication.failover is set to supervised, an external failover coordinator doesn’t consider anonymous replicas when selecting a bootstrap or replica set leader.

Note

Anonymous replicas are not registered in the _cluster space. This means that there is no limitation on the number of anonymous replicas in a replica set.

Type: boolean
Default: false
Environment variable: TT_REPLICATION_ANON

replication.autoexpel¶

Since: 3.3.0

The replication.autoexpel option designed for managing dynamic clusters using YAML-based configurations. It enables the automatic expulsion of instances that are removed from the YAML configuration.

Only instances with names that match the specified prefix are considered for expulsion; all others are excluded. Additionally, instances without a persistent name are ignored.

If an instance is in read-write mode and has the latest database schema, it initiates the expulsion of instances that:

Match the specified prefix

Absent from the updated YAML configuration

The expulsion process follows the standard procedure, involving the removal of the instance from the _cluster system space.

The autoexpel logic is activated during specific events:

Startup. When the cluster starts, autoexpel checks and removes instances not matching the updated configuration.

Reconfiguration. When the YAML configuration is reloaded, autoexpel compares the current state to the updated configuration and performs necessary expulsions.

box.status watcher event. Changes detected by the box.status watcher also trigger the autoexpel mechanism.

autoexpel does not take any actions on newly joined instances unless one of the triggering events occurs. This means that an instance meeting the autoexpel criterion can still join the cluster, but it may be removed later during reconfiguration or on subsequent triggering events.

Note

The replication.autoexpel option governs the expelling process and is configurable at the replicaset, group, and global levels. It is not applicable at the instance level.

Configuration fields

by (string, default: nil): specifies the autoexpel criterion. Currently, only prefix is supported and must be explicitly set.
enabled (boolean, default: false): enables or disables the autoexpel logic.
prefix (string, default: nil): defines the pattern for instance names that are considered part of the cluster.

replication.autoexpel_by.*

replication.autoexpel_by purpose is to define the criterion used for determining which instances in a cluster are subject to the autoexpel process.

The by field helps differentiate between:

Instances that are part of the cluster and should adhere to the YAML configuration.

Instances or tools (e.g., CDC tools) that use the replication channel but are not part of the cluster configuration.

The default value of by is nil, meaning no autoexpel criterion is applied unless explicitly set.

Currently, the only supported value for by is prefix. The prefix value instructs the system to identify instances based on their names, matching them against a prefix pattern defined in the configuration.

If the autoexpel feature is enabled (enabled: true), the by field must be explicitly set to prefix.

The absence of this field or an unsupported value will result in configuration errors.
replication:
  autoexpel:
    enabled: true
    by: prefix
    prefix: '{{ replicaset_name }}'
Type: string

Default: nil

Environment variable: TT_REPLICATION_AUTOEXPEL_BY

replication.autoexpel_enabled.*

The replication.autoexpel_enabled field is a boolean configuration option that determines whether the autoexpel logic is active for the cluster. This feature is designed to automatically manage dynamic cluster configurations by removing instances that are no longer present in the YAML configuration.

Note

By default, the enabled field is set to false, meaning the autoexpel logic is turned off. This ensures that no instances are automatically removed unless explicitly configured.

Enabling autoexpel logic

To enable autoexpel, you should set enabled to true in the replication.autoexpel section of your YAML configuration:
replication:
  autoexpel:
    enabled: true
    by: prefix
    prefix: '{{ replicaset_name }}'
To disable autoexpel, set enabled to false.

Dependencies

If enabled is set to true, the following fields are required:

by: specifies the criterion for autoexpel (e.g., prefix).

prefix: defines the pattern used to match instance names for expulsion.

Failure to configure these fields when enabled is true will result in a configuration error.

Type: boolean

Default: false

Environment variable: TT_REPLICATION_AUTOEXPEL_ENABLED

replication.autoexpel_prefix.*

The prefix field filters instances for expulsion by differentiating cluster instances (from the YAML configuration) from external services (e.g., CDC tools). Only instances matching the prefix are considered.

A consistent naming pattern ensures the _cluster system space automatically aligns with the YAML configuration.

If the prefix field is not set (nil), the autoexpel logic cannot identify instances for expulsion, and the feature will not function. This field is mandatory when replication.autoexpel_enabled is set to true.

How it works:

The prefix filters instance names (e.g., {{ replicaset_name }} for replicaset-specific names or i- for names starting with i-).

Instances matching the prefix and removed from the YAML configuration are expelled.

Unnamed instances or those not matching the prefix are ignored.

Dynamic prefix based on replicaset name:
replication:
  autoexpel:
    enabled: true
    by: prefix
    prefix: '{{ replicaset_name }}'
In this setup:

Instances are grouped by replicaset names (e.g., r-001-i-001 for replicaset r-001).

The prefix ensures that only instances with names matching the replicaset name are auto expelled when removed from the configuration.

Static prefix for matching patterns:
replication:
  autoexpel:
    enabled: true
    by: prefix
    prefix: 'i-'
In this setup:

All instances with names starting with i- (e.g., i-001, i-002) are considered for expulsion.

This is useful when instances follow a uniform naming convention.

Type: string

Default: nil

Environment variable: TT_REPLICATION_AUTOEXPEL_PREFIX

autoexpel full example

Create a config.yaml file with the following content:
credentials:
  users:
    guest:
      roles: [super]

replication:
  failover: manual
  autoexpel:
    enabled: true
    by: prefix
    prefix: '{{ replicaset_name }}'

iproto:
  listen:
    - uri: 'unix/:./var/run/{{ instance_name }}.iproto'

groups:
  g-001:
    replicasets:
      r-001:
        leader: r-001-i-001
        instances:
          r-001-i-001: {}
          r-001-i-002: {}
          r-001-i-003: {}
This configuration:

Sets up authentication with a guest user assigned the super role.

Enables the autoexpel option to automatically expel instances not present in the YAML file.

Defines instance names based on a prefix pattern: {{ replicaset_name }}.

Lists three instances: r-001-i-001, r-001-i-002, and r-001-i-003.

Open terminal window and start three instances using the following commands:
tarantool --name r-001-i-001 --config config.yaml -i
tarantool --name r-001-i-002 --config config.yaml -i
tarantool --name r-001-i-003 --config config.yaml -i
Edit config.yaml and remove the following entry for r-001-i-003:

The updated config.yaml should look like this:
groups:
  g-001:
    replicasets:
      r-001:
        leader: r-001-i-001
        instances:
          r-001-i-001: {}
          r-001-i-002: {}
Save the file.

For the leader instance (r-001-i-001), check the _cluster space:

Hint

The _cluster system space in Tarantool stores metadata about all instances currently recognized as part of the cluster. It shows which instances are registered and active.

You should see r-001-i-003 still listed in the _cluster system space.

Reload the configuration:
config = require('config')
config:reload()
Verify the changes:
box.space._cluster:fselect()
After the reload, r-001-i-003 should no longer appear in the _cluster system space.

replication.bootstrap_strategy¶

Specifies a strategy used to bootstrap a replica set. The following strategies are available:

auto: a node doesn’t boot if half or more of the other nodes in a replica set are not connected. For example, if a replica set contains 2 or 3 nodes, a node requires 2 connected instances. In the case of 4 or 5 nodes, at least 3 connected instances are required. Moreover, a bootstrap leader fails to boot unless every connected node has chosen it as a bootstrap leader.
config: use the specified node to bootstrap a replica set. To specify the bootstrap leader, use the <replicaset_name>.bootstrap_leader option.
supervised: a bootstrap leader isn’t chosen automatically but should be appointed using box.ctl.make_bootstrap_leader() on the desired node.
legacy (deprecated since 2.11.0): a node requires the replication_connect_quorum number of other nodes to be connected. This option is added to keep the compatibility with the current versions of Cartridge and might be removed in the future.

Type: string
Default: auto
Environment variable: TT_REPLICATION_BOOTSTRAP_STRATEGY

replication.connect_timeout¶

A timeout (in seconds) a replica waits when trying to connect to a master in a cluster. See orphan status for details.

This parameter is different from replication.timeout, which a master uses to disconnect a replica when the master receives no acknowledgments of heartbeat messages.

Type: number
Default: 30
Environment variable: TT_REPLICATION_CONNECT_TIMEOUT

replication.election_mode¶

A role of a replica set node in the leader election process.

The possible values are:

off: a node doesn’t participate in the election activities.
voter: a node can participate in the election process but can’t be a leader.
candidate: a node should be able to become a leader.
manual: allow to control which instance is the leader explicitly instead of relying on automated leader election. By default, the instance acts like a voter – it is read-only and may vote for other candidate instances. Once box.ctl.promote() is called, the instance becomes a candidate and starts a new election round. If the instance wins the elections, it becomes a leader but won’t participate in any new elections.

Note

You can set replication.election_mode to a value other than off if the replication.failover mode is election.

Type: string
Default: box.NULL (the actual default value depends on replication.failover)
Environment variable: TT_REPLICATION_ELECTION_MODE

replication.election_timeout¶

Specifies the timeout (in seconds) between election rounds in the leader election process if the previous round ended up with a split vote.

It is quite big, and for most of the cases, it can be lowered to 300-400 ms.

To avoid the split vote repeat, the timeout is randomized on each node during every new election, from 100% to 110% of the original timeout value. For example, if the timeout is 300 ms and there are 3 nodes started the election simultaneously in the same term, they can set their election timeouts to 300, 310, and 320 respectively, or to 305, 302, and 324, and so on. In that way, the votes will never be split because the election on different nodes won’t be restarted simultaneously.

Type: number
Default: 5
Environment variable: TT_REPLICATION_ELECTION_TIMEOUT

replication.election_fencing_mode¶

Specifies the leader fencing mode that affects the leader election process. When the parameter is set to soft or strict, the leader resigns its leadership if it has less than replication.synchro_quorum of alive connections to the cluster nodes. The resigning leader receives the status of a follower in the current election term and becomes read-only.

In soft mode, a connection is considered dead if there are no responses for 4 * replication.timeout seconds both on the current leader and the followers.
In strict mode, a connection is considered dead if there are no responses for 2 * replication.timeout seconds on the current leader and 4 * replication.timeout seconds on the followers. This improves the chances that there is only one leader at any time.

Fencing applies to the instances that have the replication.election_mode set to candidate or manual. To turn off leader fencing, set election_fencing_mode to off.

Type: string
Default: soft
Possible values: off, soft, strict
Environment variable: TT_REPLICATION_ELECTION_FENCING_MODE

replication.failover¶

A failover mode used to take over a master role when the current master instance fails. The following modes are available:

off

Leadership in a replica set is controlled using the database.mode option. In this case, you can set the database.mode option to rw on all instances in a replica set to make a master-master configuration.

The default database.mode is determined as follows: rw if there is one instance in a replica set; ro if there are several instances.
manual

Leadership in a replica set is controlled using the <replicaset_name>.leader option. In this case, a master-master configuration is forbidden.

In the manual mode, the database.mode option cannot be set explicitly. The leader is configured in the read-write mode, all the other instances are read-only.
election

Automated leader election is used to control leadership in a replica set.

In the election mode, database.mode and <replicaset_name>.leader shouldn’t be set explicitly.
supervised (Enterprise Edition only)

Leadership in a replica set is controlled using an external failover coordinator.

In the supervised mode, database.mode and <replicaset_name>.leader shouldn’t be set explicitly.

roles

This section describes configuration parameters related to application roles.

Note

Configuration parameters related to roles can be defined in any scope.

roles
roles_cfg

roles¶

Specify the roles of an instance. To specify a role’s configuration, use the roles_cfg option.

Type: array
Default: nil
Environment variable: TT_ROLES

roles_cfg¶

Specify a role’s configuration. This option accepts a role name as the key and a role’s configuration as the value. To specify the roles of an instance, use the roles option.

Tip

The experimental.config.utils.schema built-in module provides an API for managing user-defined configurations of applications (app.cfg) and roles (roles_cfg).

Type: map
Default: nil
Environment variable: TT_ROLES_CFG

security

Enterprise Edition

Configuring security parameters is available in the Enterprise Edition only.

The security section defines configuration parameters related to various security settings.

Note

security can be defined in any scope.

security.auth_delay
security.auth_retries
security.auth_type
security.disable_guest
security.password_enforce_digits
security.password_enforce_lowercase
security.password_enforce_specialchars
security.password_enforce_uppercase
security.password_history_length
security.password_lifetime_days
security.password_min_length
security.secure_erasing

security.auth_delay¶

Specify a period of time (in seconds) that a specific user should wait for the next attempt after failed authentication.

The security.auth_retries option lets a client try to authenticate the specified number of times before security.auth_delay is enforced.

In the configuration below, Tarantool lets a client try to authenticate with the same username three times. At the fourth attempt, the authentication delay configured with security.auth_delay is enforced. This means that a client should wait 10 seconds after the first failed attempt.

security:
  auth_delay: 10
  auth_retries: 2

Type: number
Default: 0
Environment variable: TT_SECURITY_AUTH_DELAY

security.auth_retries¶

Specify the maximum number of authentication retries allowed before security.auth_delay is enforced. The default value is 0, which means security.auth_delay is enforced after the first failed authentication attempt.

The retry counter is reset after security.auth_delay seconds since the first failed attempt. For example, if a client tries to authenticate fewer than security.auth_retries times within security.auth_delay seconds, no authentication delay is enforced. The retry counter is also reset after any successful authentication attempt.

Type: integer
Default: 0
Environment variable: TT_SECURITY_AUTH_RETRIES

security.auth_type¶

Specify a protocol used to authenticate users. The possible values are:

chap-sha1: use the CHAP protocol with SHA-1 hashing applied to passwords.
pap-sha256: use PAP authentication with the SHA256 hashing algorithm.

Note that CHAP stores password hashes in the _user space unsalted. If an attacker gains access to the database, they may crack a password, for example, using a rainbow table. For PAP, a password is salted with a user-unique salt before saving it in the database, which keeps the database protected from cracking using a rainbow table.

To enable PAP, specify the security.auth_type option as follows:

security:
  auth_type: 'pap-sha256'

Type: string
Default: ‘chap-sha1’
Environment variable: TT_SECURITY_AUTH_TYPE

security.disable_guest¶: If true, turn off access over remote connections from unauthenticated or guest users. This option affects connections between cluster members and net.box connections.

Type: boolean

Default: false

Environment variable: TT_SECURITY_DISABLE_GUEST

security.password_enforce_digits¶: If true, a password should contain digits (0-9).

Type: boolean

Default: false

Environment variable: TT_SECURITY_PASSWORD_ENFORCE_DIGITS

security.password_enforce_lowercase¶: If true, a password should contain lowercase letters (a-z).

Type: boolean

Default: false

Environment variable: TT_SECURITY_PASSWORD_ENFORCE_LOWERCASE

security.password_enforce_specialchars¶: If true, a password should contain at least one special character (such as &|?!@$).

Type: boolean

Default: false

Environment variable: TT_SECURITY_PASSWORD_ENFORCE_SPECIALCHARS

security.password_enforce_uppercase¶: If true, a password should contain uppercase letters (A-Z).

Type: boolean

Default: false

Environment variable: TT_SECURITY_PASSWORD_ENFORCE_UPPERCASE

security.password_history_length¶: Specify the number of unique new user passwords before an old password can be reused.

Note

Tarantool uses the auth_history field in the box.space._user system space to store user passwords.

Type: integer

Default: 0

Environment variable: TT_SECURITY_PASSWORD_HISTORY_LENGTH

security.password_lifetime_days¶: Specify the maximum period of time (in days) a user can use the same password. When this period ends, a user gets the “Password expired” error on a login attempt. To restore access for such users, use box.schema.user.passwd.

Note

The default 0 value means that a password never expires.

Type: integer

Default: 0

Environment variable: TT_SECURITY_PASSWORD_LIFETIME_DAYS

security.password_min_length¶: Specify the minimum number of characters for a password.

Type: integer

Default: 0

Environment variable: TT_SECURITY_PASSWORD_MIN_LENGTH

security.secure_erasing¶: If true, forces Tarantool to overwrite a data file a few times before deletion to render recovery of a deleted file impossible. The option applies to both .xlog and .snap files as well as Vinyl data files.

Type: boolean

Default: false

Environment variable: TT_SECURITY_SECURE_ERASING

sharding

The sharding section defines configuration parameters related to sharding.

Note

Sharding support requires installing the vshard module. The minimum required version of vshard is 0.1.25.

sharding.bucket_count
sharding.discovery_mode
sharding.failover_ping_timeout
sharding.lock
sharding.rebalancer_disbalance_threshold
sharding.rebalancer_max_receiving
sharding.rebalancer_max_sending
sharding.rebalancer_mode
sharding.roles
sharding.sched_move_quota
sharding.sched_ref_quota
sharding.shard_index
sharding.sync_timeout
sharding.weight
sharding.zone

sharding.bucket_count¶

The total number of buckets in a cluster. Learn more in Bucket count.

Note

This option should be defined at the global level.

Example

sharding:
  bucket_count: 1000

Type: integer
Default: 3000
Environment variable: TT_SHARDING_BUCKET_COUNT

sharding.discovery_mode¶: A mode of the background discovery fiber used by the router to find buckets. Learn more in vshard.router.discovery_set().

Note

This option should be defined at the global level.

Type: string

Default: ‘on’

Possible values: ‘on’, ‘off’, ‘once’

Environment variable: TT_SHARDING_DISCOVERY_MODE

sharding.failover_ping_timeout¶: The timeout (in seconds) after which a node is considered unavailable if there are no responses during this period. The failover fiber is used to detect if a node is down.

Note

This option should be defined at the global level.

Type: number

Default: 5

Environment variable: TT_SHARDING_FAILOVER_PING_TIMEOUT

sharding.lock¶: Whether a replica set is locked. A locked replica set cannot receive new buckets nor migrate its own buckets.

Note

sharding.lock can be specified at the replica set level or higher.

Type: boolean

Default: nil

Environment variable: TT_SHARDING_LOCK

sharding.rebalancer_disbalance_threshold¶

The maximum bucket disbalance threshold (in percent). The disbalance is calculated for each replica set using the following formula:

|etalon_bucket_count - real_bucket_count| / etalon_bucket_count * 100

Note

This option should be defined at the global level.

Type: number
Default: 1
Environment variable: TT_SHARDING_REBALANCER_DISBALANCE_THRESHOLD

sharding.rebalancer_max_receiving¶

The maximum number of buckets that can be received in parallel by a single replica set. This number must be limited because the rebalancer sends a large number of buckets from the existing replica sets to the newly added one. This produces a heavy load on the new replica set.

Note

This option should be defined at the global level.

Example

Suppose, rebalancer_max_receiving is equal to 100 and bucket_count is equal to 1000. There are 3 replica sets with 333, 333, and 334 buckets on each respectively. When a new replica set is added, each replica set’s etalon_bucket_count becomes equal to 250. Rather than receiving all 250 buckets at once, the new replica set receives 100, 100, and 50 buckets sequentially.

Type: integer
Default: 100
Environment variable: TT_SHARDING_REBALANCER_MAX_RECEIVING

sharding.rebalancer_max_sending¶: The degree of parallelism for parallel rebalancing.

Note

This option should be defined at the global level.

Type: integer

Default: 1

Maximum: 15

Environment variable: TT_SHARDING_REBALANCER_MAX_SENDING

sharding.rebalancer_mode¶

Since: 3.1.0

Configure how a rebalancer is selected:

auto (default): if there are no replica sets with the rebalancer sharding role (sharding.roles), a replica set with the rebalancer is selected automatically among all replica sets.
manual: one of the replica sets should have the rebalancer sharding role. The rebalancer is in this replica set.
off: rebalancing is turned off regardless of whether a replica set with the rebalancer sharding role exists or not.

Note

This option should be defined at the global level.

Type: string
Default: ‘auto’
Environment variable: TT_SHARDING_REBALANCER_MODE

sharding.roles¶

Roles of a replica set in regard to sharding. A replica set can have the following roles:

router: a replica set acts as a router.
storage: a replica set acts as a storage.
rebalancer: a replica set acts as a rebalancer.

The rebalancer role is optional. If it is not specified, a rebalancer is selected automatically from the master instances of replica sets.

There can be at most one replica set with the rebalancer role. Additionally, this replica set should have a storage role.

Example

replicasets:
  storage-a:
    sharding:
      roles: [storage, rebalancer]

snapshot

The snapshot section defines configuration parameters related to the snapshot files. To learn more about the snapshots’ configuration, check the Persistence page.

Note

snapshot can be defined in any scope.

snapshot.dir
snapshot.snap_io_rate_limit
snapshot.count
snapshot.by.*

snapshot.dir¶

A directory where memtx stores snapshot (.snap) files. A relative path in this option is interpreted as relative to process.work_dir.

By default, snapshots and WAL files are stored in the same directory. However, you can set different values for the snapshot.dir and wal.dir options to store them on different physical disks for performance matters.

Type: string
Default: ‘var/lib/{{ instance_name }}’
Environment variable: TT_SNAPSHOT_DIR

snapshot.snap_io_rate_limit¶: Reduce the throttling effect of box.snapshot() on INSERT/UPDATE/DELETE performance by setting a limit on how many megabytes per second it can write to disk. The same can be achieved by splitting wal.dir and snapshot.dir locations and moving snapshots to a separate disk. The limit also affects what box.stat.vinyl().regulator may show for the write rate of dumps to .run and .index files.

Type: number

Default: box.NULL

Environment variable: TT_SNAPSHOT_SNAP_IO_RATE_LIMIT

snapshot.count¶

The maximum number of snapshots that are stored in the snapshot.dir directory. If the number of snapshots after creating a new one exceeds this value, the Tarantool garbage collector deletes old snapshots. If snapshot.count is set to zero, the garbage collector does not delete old snapshots.

Example

In the example, the checkpoint daemon creates a snapshot every two hours until it has created three snapshots. After creating a new snapshot (the fourth one), the oldest snapshot and any associated write-ahead-log files are deleted.

snapshot:
  by:
    interval: 7200
  count: 3

Note

Snapshots will not be deleted if replication is ongoing and the file has not been relayed to a replica. Therefore, snapshot.count has no effect unless all replicas are alive.

Type: integer
Default: 2
Environment variable: TT_SNAPSHOT_COUNT

snapshot.by.*

snapshot.by.interval
snapshot.by.wal_size

snapshot.by.interval¶

The interval in seconds between actions by the checkpoint daemon. If the option is set to a value greater than zero, and there is activity that causes change to a database, then the checkpoint daemon calls box.snapshot() every snapshot.by.interval seconds, creating a new snapshot file each time. If the option is set to zero, the checkpoint daemon is disabled.

Example

In the example, the checkpoint daemon creates a new database snapshot every two hours, if there is activity.

by:
  interval: 7200

Type: number
Default: 3600
Environment variable: TT_SNAPSHOT_BY_INTERVAL

snapshot.by.wal_size¶: The threshold for the total size in bytes for all WAL files created since the last snapshot taken. Once the configured threshold is exceeded, the WAL thread notifies the checkpoint daemon that it must make a new snapshot and delete old WAL files.

Type: integer

Default: 10^18

Environment variable: TT_SNAPSHOT_BY_WAL_SIZE

sql

The sql section defines configuration parameters related to SQL.

Note

sql can be defined in any scope.

sql.cache_size

sql.cache_size¶: The maximum cache size (in bytes) for all SQL prepared statements. To see the actual cache size, use box.info.sql().cache.size.

Type: integer

Default: 5242880

Environment variable: TT_SQL_CACHE_SIZE

vinyl

The vinyl section defines configuration parameters related to the vinyl storage engine.

Note

vinyl can be defined in any scope.

vinyl.bloom_fpr
vinyl.cache
vinyl.defer_deletes
vinyl.dir
vinyl.max_tuple_size
vinyl.memory
vinyl.page_size
vinyl.range_size
vinyl.read_threads
vinyl.run_count_per_level
vinyl.run_size_ratio
vinyl.timeout
vinyl.write_threads

vinyl.bloom_fpr¶: A bloom filter’s false positive rate – the suitable probability of the bloom filter to give a wrong result. The vinyl.bloom_fpr setting is a default value for the bloom_fpr option passed to space_object:create_index().

Type: number

Default: 0.05

Environment variable: TT_VINYL_BLOOM_FPR

vinyl.cache¶: The cache size for the vinyl storage engine. The cache can be resized dynamically.

Type: integer

Default: 128 * 1024 * 1024

Environment variable: TT_VINYL_CACHE

vinyl.defer_deletes¶: Enable the deferred DELETE optimization in vinyl. It was disabled by default since Tarantool version 2.10 to avoid possible performance degradation of secondary index reads.

Type: boolean

Default: false

Environment variable: TT_VINYL_DEFER_DELETES

vinyl.dir¶

A directory where vinyl files or subdirectories will be stored.

This option may contain a relative file path. In this case, it is interpreted as relative to process.work_dir.

Type: string
Default: ‘var/lib/{{ instance_name }}’
Environment variable: TT_VINYL_DIR

vinyl.max_tuple_size¶: The size of the largest allocation unit, for the vinyl storage engine. It can be increased if it is necessary to store large tuples.

Type: integer

Default: 1024 * 1024

Environment variable: TT_VINYL_MAX_TUPLE_SIZE

vinyl.memory¶: The maximum number of in-memory bytes that vinyl uses.

Type: integer

Default: 128 * 1024 * 1024

Environment variable: TT_VINYL_MEMORY

vinyl.page_size¶: The page size. A page is a read/write unit for vinyl disk operations. The vinyl.page_size setting is a default value for the page_size option passed to space_object:create_index().

Type: integer

Default: 8 * 1024

Environment variable: TT_VINYL_PAGE_SIZE

vinyl.range_size¶

The default maximum range size for a vinyl index, in bytes. The maximum range size affects the decision of whether to split a range.

If vinyl.range_size is specified (but the value is not null or 0), then it is used as the default value for the range_size option passed to space_object:create_index().

If vinyl.range_size is not specified (or is explicitly set to null or 0), and range_size is not specified when the index is created, then Tarantool sets a value later depending on performance considerations. To see the actual value, use index_object:stat().range_size.

Type: integer
Default: box.NULL (means that an effective default is determined in runtime)
Environment variable: TT_VINYL_RANGE_SIZE

vinyl.read_threads¶: The maximum number of read threads that vinyl can use for concurrent operations, such as I/O and compression.

Type: integer

Default: 1

Environment variable: TT_VINYL_READ_THREADS

vinyl.run_count_per_level¶: The maximum number of runs per level in the vinyl LSM tree. If this number is exceeded, a new level is created. The vinyl.run_count_per_level setting is a default value for the run_count_per_level option passed to space_object:create_index().

Type: integer

Default: 2

Environment variable: TT_VINYL_RUN_COUNT_PER_LEVEL

vinyl.run_size_ratio¶: The ratio between the sizes of different levels in the LSM tree. The vinyl.run_size_ratio setting is a default value for the run_size_ratio option passed to space_object:create_index().

Type: number

Default: 3.5

Environment variable: TT_VINYL_RUN_SIZE_RATIO

vinyl.timeout¶: The vinyl storage engine has a scheduler that performs compaction. When vinyl is low on available memory, the compaction scheduler may be unable to keep up with incoming update requests. In that situation, queries may time out after vinyl.timeout seconds. This should rarely occur, since normally vinyl throttles inserts when it is running low on compaction bandwidth. Compaction can also be initiated manually with index_object:compact().

Type: integer

Default: 60

Environment variable: TT_VINYL_TIMEOUT

vinyl.write_threads¶: The maximum number of write threads that vinyl can use for some concurrent operations, such as I/O and compression.

Type: integer

Default: 4

Environment variable: TT_VINYL_WRITE_THREADS

wal

The wal section defines configuration parameters related to write-ahead log. To learn more about the WAL configuration, check the Persistence page.

Note

wal can be defined in any scope.

wal.cleanup_delay
wal.dir
wal.dir_rescan_delay
wal.max_size
wal.mode
wal.queue_max_size
wal.retention_period
wal.ext.*

wal.cleanup_delay¶

The delay in seconds used to prevent the Tarantool garbage collector from immediately removing write-ahead log files after a node restart. This delay eliminates possible erroneous situations when the master deletes WALs needed by replicas after restart. As a consequence, replicas sync with the master faster after its restart and don’t need to download all the data again. Once all the nodes in the replica set are up and running, a scheduled garbage collection is started again even if wal.cleanup_delay has not expired.

Note

The option has no effect on nodes running as anonymous replicas.

wal.ext.*

Enterprise Edition

Configuring wal.ext.* parameters is available in the Enterprise Edition only.

This section describes options related to WAL extensions.

wal.ext.new
wal.ext.old
wal.ext.spaces

wal.ext.new¶: Enable storing a new tuple for each CRUD operation performed. The option is in effect for all spaces. To adjust the option for specific spaces, use the wal.ext.spaces option.

Type: boolean

Default: false

Environment variable: TT_WAL_EXT_NEW

wal.ext.old¶: Enable storing an old tuple for each CRUD operation performed. The option is in effect for all spaces. To adjust the option for specific spaces, use the wal.ext.spaces option.

Type: boolean

Default: false

Environment variable: TT_WAL_EXT_OLD

wal.ext.spaces¶

Enable or disable storing an old and new tuple in the WAL record for a given space explicitly. The configuration for specific spaces has priority over the configuration in the wal.ext.new and wal.ext.old options.

The option is a key-value pair:

The key is a space name (string).
The value is a table that includes two optional boolean options: old and new. The format and the default value of these options are described in wal.ext.old and wal.ext.new.

Example

In the example, only new tuples are added to the log for the bands space.

ext:
  new: true
  old: true
  spaces:
    bands:
      old: false

Type: map
Default: nil
Environment variable: TT_WAL_EXT_SPACES

Version:

Configuration reference

app

audit_log

audit_log.syslog.*

compat

conditional

config

config.context.*

config.etcd.*

config.storage.*

console

credentials

credentials.roles.*

credentials.users.*

<user_or_role_name>.privileges.*

database

failover

failover.stateboard.*

feedback

fiber

fiber.slice.*

fiber.top.*

flightrec

iproto

iproto.advertise.*

iproto.advertise.<peer_or_sharding>.*

<uri>.params.*

groups

replicasets

instances

isolated mode

labels

log

log.syslog.*

lua

memtx

metrics

process

replication

replication.autoexpel_by.*

replication.autoexpel_enabled.*

replication.autoexpel_prefix.*

autoexpel full example

roles

security

sharding

snapshot

snapshot.by.*

sql

vinyl

wal

wal.ext.*