Configuration in code

Specifying several URIs

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" }
    }
}

Configuration

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 Supported 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'
    }
}}

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'
    }
}}

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

Server-client configuration details

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.