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.

To configure URIs used to listen for incoming requests, use the iproto.listen configuration 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'

In this example, instance001 listens on two IP addresses:

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

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.

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 configuration_connections_ssl.

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'

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.

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

If required, you can specify an advertise URI explicitly by setting up the iproto.advertise. 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 configuration_connections_ssl_advertise_uri.

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.

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:

You can find the full example here: ssl_without_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.

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'

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.