Connections

To set up a Tarantool cluster, you need to enable communication between its instances, regardless of whether they running on one or different hosts. This requires configuring connection settings that include:

One or several URIs used to listen for incoming requests.
An URI used to advertise an instance to other cluster members. This URI lets other cluster members know how to connect to the current Tarantool instance.
(Optional) SSL settings used to secure connections between instances.

Configuring connection settings is also required to enable communication of a Tarantool cluster to external systems. For example, this might be administering cluster members using tt, managing clusters using Tarantool Cluster Manager, or using connectors for different languages.

This topic describes how to define connection settings in the iproto section of a YAML configuration.

Note

iproto is a binary protocol used to communicate between cluster instances and with external systems.

Listen URI

To configure URIs used to listen for incoming requests, use the iproto.listen configuration option.

One listen address

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'

Multiple listen addresses

In this example, instance001 listens on two IP addresses:

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

Listen port

You can pass only a port value to iproto.listen:

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

In this case, this port is used for all IP addresses the server listens on.

SSL parameters

In the Enterprise Edition, you can enable SSL for a connection using the params section of the specified URI:

instance001:
  iproto:
    listen:
    - uri: '127.0.0.1:3301'
      params:
        transport: 'ssl'
        ssl_cert_file: 'certs/server.crt'
        ssl_key_file: 'certs/server.key'

Learn more from Securing connections with SSL.

Unix domain socket

For local development, you can enable communication between cluster members by using Unix domain sockets:

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

Advertise URI

An advertise URI (iproto.advertise.*) lets other cluster members or clients know how to connect to the current Tarantool instance:

iproto.advertise.peer specifies how to advertise the instance to other cluster members.
iproto.advertise.sharding specifies how to advertise the instance to a router and rebalancer.
iproto.advertise.client accepts a URI used to advertise the instance to clients.

iproto.advertise.<peer_or_sharding> might include the credentials required to connect to this instance, a URI used to listen for incoming requests, and SSL settings.

If iproto.advertise.<peer_or_sharding>.uri is not specified explicitly, a listen URI of this instance is used. In this case, you need at least to specify credentials for connecting to this instance.

Connection credentials

In the example below, the iproto.advertise.peer option is used to inform other replica set members that the replicator user should be used to connect to the current instance:

iproto:
  advertise:
    peer:
      login: replicator

In a sharded cluster, iproto.advertise.sharding specifies that a router and rebalancer should use the storage user to connect to storages:

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

URI

If required, you can specify an advertise URI explicitly by setting up the iproto.advertise.<peer_or_sharding>.uri option. In the example below, iproto.listen includes two URIs that can be used to connect to instance001 but only the second one is used to advertise this instance to other replica set peers:

instance001:
  iproto:
    listen:
    - uri: '127.0.0.1:3301'
    - uri: '127.0.0.1:4401'
    advertise:
      peer:
        uri: '127.0.0.1:4401'

The iproto.advertise.<peer_or_sharding>.uri option can also accept an FQDN instead of an IP address:

instance001:
  iproto:
    listen:
    - uri: '192.168.0.101:3301'
    advertise:
      peer:
        uri: 'server001.example.com:3301'

To learn about the specifics of configuring an advertise URI’s SSL settings, see Advertise URI specifics.

Securing connections with SSL

Enterprise Edition

SSL is supported by the Enterprise Edition only.

Tarantool supports the use of SSL connections to encrypt client-server communications for increased security. To enable SSL, use the <uri>.params.* options, which can be applied to both listen and advertise URIs.

Without CA

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.

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'

You can find the full example here: ssl_without_ca.

With CA

The example below demonstrates how to enable traffic encryption by using a server certificate signed by a trusted certificate authority. In this case, all replica set peers verify each other for authenticity.

The following parameters are specified for each instance:

ssl_ca_file: a path to a trusted certificate authorities (CA) file.
ssl_cert_file: a path to an SSL certificate file.
ssl_key_file: a path to a private SSL key file.
ssl_password (instance001): a password for an encrypted private SSL key.
ssl_password_file (instance002 and instance003): a text file containing passwords for encrypted SSL keys.
ssl_ciphers: a colon-separated list of SSL cipher suites the connection can use.

instances:
  instance001:
    iproto:
      listen:
      - uri: '127.0.0.1:3301'
        params:
          transport: 'ssl'
          ssl_ca_file: 'certs/root_ca.crt'
          ssl_cert_file: 'certs/instance001/server001.crt'
          ssl_key_file: 'certs/instance001/server001.key'
          ssl_password: 'qwerty'
          ssl_ciphers: 'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256'
  instance002:
    iproto:
      listen:
      - uri: '127.0.0.1:3302'
        params:
          transport: 'ssl'
          ssl_ca_file: 'certs/root_ca.crt'
          ssl_cert_file: 'certs/instance002/server002.crt'
          ssl_key_file: 'certs/instance002/server002.key'
          ssl_password_file: 'certs/ssl_passwords.txt'
          ssl_ciphers: 'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256'
  instance003:
    iproto:
      listen:
      - uri: '127.0.0.1:3303'
        params:
          transport: 'ssl'
          ssl_ca_file: 'certs/root_ca.crt'
          ssl_cert_file: 'certs/instance003/server003.crt'
          ssl_key_file: 'certs/instance003/server003.key'
          ssl_password_file: 'certs/ssl_passwords.txt'
          ssl_ciphers: 'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256'

You can find the full example here: ssl_with_ca.

Advertise URI specifics

SSL parameters for an advertise URI should be set only if this advertise URI is specified explicitly. Otherwise, SSL parameters of a listen URI are used and no additional configuration is required.

Configuring an advertise URI’s SSL options depends on whether a trusted certificate authorities (CA) file is set or not. Without the CA file, you only need to set iproto.advertise.<peer_or_sharding>.params.transport to ssl as shown below:

instance001:
  iproto:
    listen:
    - uri: '192.168.0.101:3301'
      params:
        transport: 'ssl'
        ssl_cert_file: 'certs/server.crt'
        ssl_key_file: 'certs/server.key'
    advertise:
      peer:
        uri: 'server.example.com:3301'
        params:
          transport: 'ssl'

If the CA file is specified for a listen URI, you also need to configure ssl_cert_file and ssl_key_file for this advertise URI:

instance001:
  iproto:
    listen:
    - uri: '192.168.0.101:3301'
      params:
        transport: 'ssl'
        ssl_ca_file: 'certs/root_ca.crt'
        ssl_cert_file: 'certs/instance001/server001.crt'
        ssl_key_file: 'certs/instance001/server001.key'
    advertise:
      peer:
        uri: 'server001.example.com:3301'
        params:
          transport: 'ssl'
          ssl_cert_file: 'certs/instance001/server001.crt'
          ssl_key_file: 'certs/instance001/server001.key'

Reloading certificates

To reload SSL certificate files specified in the configuration, open an admin console and reload the configuration using config.reload():

require('config'):reload()

New certificates will be used for new connections. Existing connections will continue using old SSL certificates until reconnection is required. For example, certificate expiry or a network issue causes reconnection.

Version:

Connections

Listen URI

One listen address

Multiple listen addresses

Listen port

SSL parameters

Unix domain socket

Advertise URI

Connection credentials

URI

Securing connections with SSL

Without CA

With CA

Advertise URI specifics

Reloading certificates