Configuration in code

This topic covers the specifics of configuring Tarantool in code using the box.cfg API. In this case, a configuration is stored in an initialization file - a Lua script with the specified configuration options. You can find all the available options in the Configuration reference.

If the command to start Tarantool includes an instance file, then Tarantool begins by invoking the Lua program in the file, which may have the name init.lua. The Lua program may get further arguments from the command line or may use operating-system functions, such as getenv(). The Lua program almost always begins by invoking box.cfg(), if the database server will be used or if ports need to be opened. For example, suppose init.lua contains the lines

 
#!/usr/bin/env tarantoolbox.cfg{    listen              = os.getenv("LISTEN_URI"),    memtx_memory        = 33554432,    pid_file            = "tarantool.pid",    wal_max_size        = 2500}print('Starting ', arg[1])

and suppose the environment variable LISTEN_URI contains 3301, and suppose the command line is tarantool init.lua ARG. Then the screen might look like this:

 
$ export LISTEN_URI=3301$ tarantool init.lua ARG... main/101/init.lua C> Tarantool 2.8.3-0-g01023dbc2... main/101/init.lua C> log level 5... main/101/init.lua I> mapping 33554432 bytes for memtx tuple arena...... main/101/init.lua I> recovery start... main/101/init.lua I> recovering from './00000000000000000000.snap'... main/101/init.lua I> set 'listen' configuration option to "3301"... main/102/leave_local_hot_standby I> ready to accept requestsStarting  ARG... main C> entering the event loop

If you wish to start an interactive session on the same terminal after initialization is complete, you can pass the -i command-line option.

Starting from version 2.8.1, you can specify configuration parameters via special environment variables. The name of a variable should have the following pattern: TT_<NAME>, where <NAME> is the uppercase name of the corresponding box.cfg parameter.

For example:

• TT_LISTEN – corresponds to the box.cfg.listen option.
• TT_MEMTX_DIR – corresponds to the box.cfg.memtx_dir option.

In case of an array value, separate the array elements by a comma without space:

 
export TT_REPLICATION="localhost:3301,localhost:3302"

If you need to pass additional parameters for URI, use the ? and & delimiters:

 
export TT_LISTEN="localhost:3301?param1=value1&param2=value2"

An empty variable (TT_LISTEN=) has the same effect as an unset one, meaning that the corresponding configuration parameter won't be set when calling box.cfg{}.

Configuration parameters have the form:

{**{box.cfg}**}{[{*{key = value}*} [, {*{key = value ...}*}]]}

Configuration parameters can be set in a Lua initialization file, which is specified on the Tarantool command line.

Most configuration parameters are for allocating resources, opening ports, and specifying database behavior. All parameters are optional. Most of the parameters are dynamic, that is, they can be changed at runtime by calling box.cfg{} a second time. For example, the command below sets the listen port to 3301.

 
tarantool> box.cfg{ listen = 3301 }2023-05-10 13:28:54.667 [31326] main/103/interactive I> tx_binary: stopped2023-05-10 13:28:54.667 [31326] main/103/interactive I> tx_binary: bound to [::]:33012023-05-10 13:28:54.667 [31326] main/103/interactive/box.load_cfg I> set 'listen' configuration option to 3301---...

To see all the non-null parameters, execute box.cfg (no parentheses).

 
tarantool> box.cfg---- replication_skip_conflict: false  wal_queue_max_size: 16777216  feedback_host: https://feedback.tarantool.io  memtx_dir: .  memtx_min_tuple_size: 16  -- other parameters --...

To see a particular parameter value, call a corresponding box.cfg option. For example, box.cfg.listen shows the specified listen address.

 
tarantool> box.cfg.listen---- 3301...

Some configuration parameters and some functions depend on a URI (Universal Resource Identifier). The URI string format is similar to the generic syntax for a URI schema. It may contain (in order):

• user name for login
• password
• host name or host IP address
• port number
• query parameters

Only a port number is always mandatory. A password is mandatory if a user name is specified unless the user name is 'guest'.

Formally, the URI syntax is [host:]port or [username:password@]host:port. If a host is omitted, then "0.0.0.0" or "[::]" is assumed, meaning respectively any IPv4 address or any IPv6 address on the local machine. If username:password is omitted, then the "guest" user is assumed. Some examples:

In code, the URI value can be passed as a number (if only a port is specified) or a string:

 
box.cfg { listen = 3301 }box.cfg { listen = "127.0.0.1:3301" }

In certain circumstances, a Unix domain socket may be used where a URI is expected, for example, unix/:/tmp/unix_domain_socket.sock or simply /tmp/unix_domain_socket.sock.

The uri module provides functions that convert URI strings into their components or turn components into URI strings.

Starting from version 2.10.0, a user can open several listening iproto sockets on a Tarantool instance and, consequently, can specify several URIs in the configuration parameters such as box.cfg.listen and box.cfg.replication.

URI values can be set in a number of ways:

• As a string with URI values separated by commas.

   
  box.cfg { listen = "127.0.0.1:3301, /unix.sock, 3302" }

• As a table that contains URIs in the string format.

   
  box.cfg { listen = {"127.0.0.1:3301", "/unix.sock", "3302"} }

• As an array of tables with the uri field.

   
  box.cfg { listen = {        {uri = "127.0.0.1:3301"},        {uri = "/unix.sock"},        {uri = 3302}    }}

• In a combined way – an array that contains URIs in both the string and the table formats.

   
  box.cfg { listen = {        "127.0.0.1:3301",        { uri = "/unix.sock" },        { uri = 3302 }    }}

Also, starting from version 2.10.0, it is possible to specify additional parameters for URIs. You can do this in different ways:

• Using the ? delimiter when URIs are specified in a string format.

   
  box.cfg { listen = "127.0.0.1:3301?p1=value1&p2=value2, /unix.sock?p3=value3" }

• Using the params table: a URI is passed in a table with additional parameters in the "params" table. Parameters in the "params" table overwrite the ones from a URI string ("value2" overwrites "value1" for p1 in the example below).

   
  box.cfg { listen = {        "127.0.0.1:3301?p1=value1",        params = {p1 = "value2", p2 = "value3"}    }}

• Using the default_params table for specifying default parameter values.

  In the example below, two URIs are passed in a table. The default value for the p3 parameter is defined in the default_params table and used if this parameter is not specified in URIs. Parameters in the default_params table are applicable to all the URIs passed in a table.

   
  box.cfg { listen = {        "127.0.0.1:3301?p1=value1",        { uri = "/unix.sock", params = { p2 = "value2" } },        default_params = { p3 = "value3" }    }}

The recommended way for specifying URI with additional parameters is the following:

 
box.cfg { listen = {        {uri = "127.0.0.1:3301", params = {p1 = "value1"}},        {uri = "/unix.sock", params = {p2 = "value2"}},        {uri = 3302, params = {p3 = "value3"}}    }}

In case of a single URI, the following syntax also works:

 
box.cfg { listen = {        uri = "127.0.0.1:3301",        params = { p1 = "value1", p2 = "value2" }    }}

Since version 2.10.0, Tarantool Enterprise Edition has the built-in support for using SSL to encrypt the client-server communications over binary connections, that is, between Tarantool instances in a cluster or connecting to an instance via connectors using net.box.

Tarantool uses the OpenSSL library that is included in the delivery package. Note that SSL connections use only TLSv1.2.

To configure traffic encryption, you need to set the special URI parameters for a particular connection. The parameters can be set for the following box.cfg options and net.box method:

• box.cfg.listen – on the server side.
• box.cfg.replication – on the client side.
• net_box_object.connect() – on the client side.

Below is the list of the parameters. In the next section, you can find details and examples on what should be configured on both the server side and the client side.

• transport – enables SSL encryption for a connection if set to ssl. The default value is plain, which means the encryption is off. If the parameter is not set, the encryption is off too. Other encryption-related parameters can be used only if the transport = 'ssl' is set.

  Example:

 
local connection = require('net.box').connect({    uri = 'admin:topsecret@127.0.0.1:3301',    params = { transport = 'ssl',               ssl_cert_file = 'certs/instance001/server001.crt',               ssl_key_file = 'certs/instance001/server001.key',               ssl_password = 'qwerty' }})

• ssl_key_file – a path to a private SSL key file. Mandatory for a server. 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.

• ssl_cert_file – a path to an SSL certificate file. Mandatory for a server. For a client, it's mandatory if the ssl_ca_file parameter is set for a server; otherwise, optional.

• ssl_ca_file – a path to a trusted certificate authorities (CA) file. Optional. 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.

• ssl_ciphers – a colon-separated (:) list of SSL cipher suites the connection can use. See the configuration_code_iproto-encryption-ciphers section for details. Optional. Note that the list is not validated: if a cipher suite is unknown, Tarantool just ignores it, doesn't establish the connection and writes to the log that no shared cipher found.

• ssl_password – a password for an encrypted private SSL key. Optional. Alternatively, the password can be provided in ssl_password_file.

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

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

  1. If ssl_password is provided, Tarantool tries to decrypt the private key with it.
  2. 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.
  3. 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.

Configuration example:

 
box.cfg{ listen = {    uri = 'localhost:3301',    params = {        transport = 'ssl',        ssl_key_file = '/path_to_key_file',        ssl_cert_file = '/path_to_cert_file',        ssl_ciphers = 'HIGH:!aNULL',        ssl_password = 'topsecret'    }}}

Tarantool Enterprise supports the following cipher suites:

• 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

Tarantool Enterprise static build has the embedded engine to support the GOST cryptographic algorithms. If you use these algorithms for traffic encryption, specify the corresponding cipher suite in the ssl_ciphers parameter, for example:

 
box.cfg{ listen = {    uri = 'localhost:3301',    params = {        transport = 'ssl',        ssl_key_file = '/path_to_key_file',        ssl_cert_file = '/path_to_cert_file',        ssl_ciphers = 'GOST2012-GOST8912-GOST8912'    }}}

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

The URI parameters for traffic encryption can also be set via environment variables, for example:

 
export TT_LISTEN="localhost:3301?transport=ssl&ssl_cert_file=/path_to_cert_file&ssl_key_file=/path_to_key_file"

When configuring the traffic encryption, you need to specify the necessary parameters on both the server side and the client side. Below you can find the summary on the options and parameters to be used and examples of configuration.

Server side

• Is configured via the box.cfg.listen option.
• Mandatory URI parameters: transport, ssl_key_file and ssl_cert_file.
• Optional URI parameters: ssl_ca_file, ssl_ciphers, ssl_password, and ssl_password_file.

Client side

• Is configured via the box.cfg.replication option (see details) or net_box_object.connect().

Parameters:

• If the server side has only the transport, ssl_key_file and ssl_cert_file parameters set, on the client side, you need to specify only transport = ssl as the mandatory parameter. All other URI parameters are optional.
• If the server side also has the ssl_ca_file parameter set, on the client side, you need to specify transport, ssl_key_file and ssl_cert_file as the mandatory parameters. Other parameters – ssl_ca_file, ssl_ciphers, ssl_password, and ssl_password_file – are optional.

Suppose, there is a master-replica set with two Tarantool instances:

• 127.0.0.1:3301 – master (server)
• 127.0.0.1:3302 – replica (client).

Examples below show the configuration related to connection encryption for two cases: when the trusted certificate authorities (CA) file is not set on the server side and when it does. Only mandatory URI parameters are mentioned in these examples.

1. Without CA

• 127.0.0.1:3301 – master (server)

   
  box.cfg{    listen = {        uri = '127.0.0.1:3301',        params = {            transport = 'ssl',            ssl_key_file = '/path_to_key_file',            ssl_cert_file = '/path_to_cert_file'        }    }}

• 127.0.0.1:3302 – replica (client)

   
  box.cfg{    listen = {        uri = '127.0.0.1:3302',        params = {transport = 'ssl'}    },    replication = {        uri = 'username:password@127.0.0.1:3301',        params = {transport = 'ssl'}    },    read_only = true}

2. With CA

• 127.0.0.1:3301 – master (server)

   
  box.cfg{    listen = {        uri = '127.0.0.1:3301',        params = {            transport = 'ssl',            ssl_key_file = '/path_to_key_file',            ssl_cert_file = '/path_to_cert_file',            ssl_ca_file = '/path_to_ca_file'        }    }}

• 127.0.0.1:3302 – replica (client)

   
  box.cfg{    listen = {        uri = '127.0.0.1:3302',        params = {            transport = 'ssl',            ssl_key_file = '/path_to_key_file',            ssl_cert_file = '/path_to_cert_file'        }    },    replication = {        uri = 'username:password@127.0.0.1:3301',        params = {            transport = 'ssl',            ssl_key_file = '/path_to_key_file',            ssl_cert_file = '/path_to_cert_file'        }    },    read_only = true}

Below is the syntax for starting a Tarantool instance configured in a Lua initialization script:

 
$ tarantool LUA_INITIALIZATION_FILE [OPTION ...]

The tarantool command also provides a set of options that might be helpful for development purposes.

The command below starts a Tarantool instance configured in the init.lua file:

 
$ tarantool init.lua