Configuration

Configuration in a file

This section provides an overview on how to configure Tarantool in a YAML file.

groups:
  group001:
    replicasets:
      replicaset001:
        instances:
          instance001:
            iproto:
              listen:
              - uri: '127.0.0.1:3301'

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

iproto:
  advertise:
    peer:
      login: replicator

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'

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

groups:
  group001:
    replicasets:
      replicaset001:
        instances:
          instance001:
            iproto:
              listen:
              - uri: '127.0.0.1:3301'

-- myapp.lua --
local log = require('log').new("myapp")
local config = require('config')
log.info("%s from app, %s!", config:get('app.cfg.greeting'), box.info.name)

main/103/interactive/myapp I> Hello from app, instance001!

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

groups:
  group001:
    replicasets:
      replicaset001:
        instances:
          instance001:
            snapshot:
              dir: ./var/{{ instance_name }}/snapshots
            wal:
              dir: ./var/{{ instance_name }}/wals

Environment variables

For each configuration parameter, Tarantool provides two sets of predefined environment variables:

• TT_<CONFIG_PARAMETER>. These variables are used to substitute parameters specified in a configuration file. This means that these variables have a higher priority than the options specified in a configuration file.
• TT_<CONFIG_PARAMETER>_DEFAULT. These variables are used to specify default values for parameters missing in a configuration file. These variables have a lower priority than the options specified in a configuration file.

For example, TT_IPROTO_LISTEN and TT_IPROTO_LISTEN_DEFAULT correspond to the iproto.listen option. TT_SNAPSHOT_DIR and TT_SNAPSHOT_DIR_DEFAULT correspond to the snapshot.dir option. To see all the supported environment variables, execute the tarantool command with the --help-env-list option.

$ tarantool --help-env-list

Below are a few examples that show how to set environment variables of different types, like string, number, array, or map:

• String. In this example, TT_LOG_LEVEL is used to set a logging level to CRITICAL:

  $ export TT_LOG_LEVEL='crit'
  

• Number. In this example, a logging level is set to CRITICAL using a corresponding numeric value:

  $ export TT_LOG_LEVEL=3
  

• Array. The examples below show how to set the TT_SHARDING_ROLES variable that accepts an array value. Arrays can be passed in two ways: using a simple …

  $ export TT_SHARDING_ROLES=router,storage
  

  … or JSON format:

  $ export TT_SHARDING_ROLES='["router", "storage"]'
  

  The simple format is applicable only to arrays containing scalar values.

• Map. To assign map values to environment variables, you can also use simple or JSON formats. In the example below, TT_LOG_MODULES sets different logging levels for different modules using a simple format:

  $ export TT_LOG_MODULES=module1=info,module2=error
  

  In the next example, TT_APP_CFG is used to specify the value of a custom configuration property for a loaded application using a JSON format:

  $ export TT_APP_CFG='{"greeting":"Hi"}'
  

  The simple format is applicable only to maps containing scalar values.

• Array of maps. In the example below, TT_IPROTO_LISTEN is used to specify a listening host and port values:

  $ export TT_IPROTO_LISTEN=['{"uri":"127.0.0.1:3311"}']
  

  You can also pass several listening addresses:

  $ export TT_IPROTO_LISTEN=['{"uri":"127.0.0.1:3311"}','{"uri":"127.0.0.1:3312"}']
  

Centralized configuration

Tarantool enables you to store configuration data in one place using a Tarantool or etcd-based storage. To achieve this, you need to:

1. Set up a centralized configuration storage.

2. Publish a cluster’s configuration to the storage.

3. Configure a connection to the storage by providing a local YAML configuration with an endpoint address and key prefix in the config section:

   config:
     etcd:
       endpoints:
       - http://localhost:2379
       prefix: /myapp
   

Learn more from the following guide: Centralized configuration storages.

Configuration precedence

Tarantool configuration options are applied from multiple sources with the following precedence, from highest to lowest:

• TT_* environment variables.
• Configuration from a local YAML file.
• Centralized configuration.
• TT_*_DEFAULT environment variables.

If the same option is defined in two or more locations, the option with the highest precedence is applied.

Connection settings

To configure an address used to listen for incoming requests, use the iproto.listen option. The example below shows how to set a listening IP address for instance001 to 127.0.0.1:3301:

instance001:
  iproto:
    listen:
    - uri: '127.0.0.1:3301'

You can learn more from the Connections topic.

Access control

The credentials section allows you to create users and grant them the specified privileges. In the example below, a dbadmin user with the specified password is created:

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

To learn more, see the Credentials section.

Memory

The memtx.memory option specifies how much memory Tarantool allocates to actually store data.

memtx:
  memory: 1073741824

When the limit is reached, INSERT or UPDATE requests fail with ER_MEMORY_ISSUE.

Learn more: In-memory storage configuration.

Snapshots and write-ahead logs

The snapshot.dir and wal.dir options can be used to configure directories for storing snapshots and write-ahead logs. For example, you can place snapshots and write-ahead logs on different hard drives for better reliability.

instance001:
  snapshot:
    dir: '/media/drive1/snapshots'
  wal:
    dir: '/media/drive2/wals'

To learn more about the persistence mechanism in Tarantool, see the Persistence section. Read more about snapshot and WAL configuration: Persistence.