Connection settings: update per review

Author: andreyaksenov

doc/concepts/configuration/configuration_connections.rst

@@ -3,18 +3,18 @@
 Connections
 ===========
 
-Communicating to Tarantool instances is required for different purposes, for example:
+Configuring connections is required for different purposes, for example:
 
--   Communicating between replica set peers or cluster members.
+-   Communicating between cluster members.
 -   Connecting to cluster members for administration using :ref:`tt <tt-cli>`.
 -   Managing clusters using :ref:`Tarantool Cluster Manager <tcm>`.
 -   Connecting to an instance using the :ref:`net.box <net_box-module>` module or :ref:`connectors <index-box_connectors>` for different languages.
 
-For communication to and between cluster instances, Tarantool uses a binary protocol called :ref:`iproto <box_protocol>`.
+To communicate to and between cluster instances, Tarantool uses a :ref:`binary protocol <box_protocol>` called iproto.
 The corresponding :ref:`iproto <configuration_reference_iproto>` section in :ref:`YAML configuration <configuration>` lets you configure various connection settings:
 
 -   One or several URIs used to listen for incoming requests.
--   Settings used advertise an instance to other cluster members.
+-   An URI used advertise an instance to other cluster members.
 -   SSL settings used to secure connections.
 
 
@@ -72,7 +72,7 @@ In this case, this port is used for all IP addresses the server listens on.
 SSL parameters
 ~~~~~~~~~~~~~~
 
-You can enable :ref:`traffic encryption <configuration_connections_ssl>` for a connection using the ``params`` section of the specified URI:
+In the Enterprise Edition, you can enable :ref:`traffic encryption <configuration_connections_ssl>` for a connection using the ``params`` section of the specified URI:
 
 ..  literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl_without_ca/config.yaml
     :language: yaml
@@ -99,18 +99,20 @@ For local development, you can enable communication between cluster members by u
 
 .. _configuration_connections_advertise:
 
-Advertise settings
-------------------
+Advertise URI
+-------------
 
-Advertise settings (:ref:`iproto.advertise.* <configuration_reference_iproto_advertise>`) let other cluster members or clients know how to connect to the current Tarantool instance.
-These settings might include the credentials required to connect to this instance, a URI used to listen for incoming requests, and SSL settings.
+An advertise URI (:ref:`iproto.advertise.* <configuration_reference_iproto_advertise>`) lets other cluster members or clients know how to connect to the current Tarantool instance:
 
-If an advertise URI is not specified explicitly, a :ref:`listen URI <configuration_connections_listen_uri>` of this instance is used.
-In this case, you need at least to specify credentials for connecting to this 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.
 
-..  NOTE::
+``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 :ref:`listen URI <configuration_connections_listen_uri>` of this instance is used.
+In this case, you need at least to specify credentials for connecting to this instance.
 
-    If several listen URIs are specified, the first one is used as an advertise URI.
 
 .. _configuration_connections_advertise_credentials:
 
@@ -136,8 +138,8 @@ In a sharded cluster, ``iproto.advertise.sharding`` specifies that a router and
 
 .. _configuration_connections_advertise_explicitly:
 
-Advertise URI
-~~~~~~~~~~~~~
+URI
+~~~
 
 If required, you can specify an advertise URI explicitly by setting up the :ref:`iproto_advertise.\<peer_or_sharding\>.uri <configuration_reference_iproto_advertise.peer_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:
@@ -160,55 +162,9 @@ The ``iproto_advertise.<peer_or_sharding>.uri`` option can also accept an FQDN i
           peer:
             uri: 'server001.example.com:3301'
 
+To learn about the specifics of configuring an advertise URI’s SSL settings, see :ref:`configuration_connections_ssl_advertise_uri`.
 
-.. _configuration_connections_advertise_uri_ssl:
 
-SSL parameters
-~~~~~~~~~~~~~~
-
-:ref:`SSL parameters <configuration_connections_ssl>` for an advertise URI should be set only if this :ref:`advertise URI is specified explicitly <configuration_connections_advertise_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:
-
-..  code-block:: yaml
-
-    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:
-
-..  code-block:: yaml
-
-    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'
 
 
 .. _configuration_connections_ssl:
@@ -226,9 +182,6 @@ Securing connections with SSL
 Tarantool supports the use of SSL connections to encrypt client-server communications for increased security.
 To enable SSL, use the :ref:`<uri>.params.* <configuration_reference_iproto_uri_params>` options, which can be applied to both listen and advertise URIs.
 
-This section shows how to configure SSL settings for a listen URI.
-To learn about the specifics of configuring an advertise URI's SSL settings, see :ref:`SSL parameters <configuration_connections_advertise_uri_ssl>`.
-
 
 .. _configuration_connections_ssl_without_ca:
 
@@ -238,12 +191,12 @@ 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.
+-   :ref:`ssl_cert_file <configuration_reference_iproto_uri_params_ssl_cert_file>`: a path to an SSL certificate file.
+-   :ref:`ssl_key_file <configuration_reference_iproto_uri_params_ssl_key_file>`: a path to a private SSL key file.
 
 ..  literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl_without_ca/config.yaml
     :language: yaml
-    :start-at: replicaset001:
+    :start-at: instances:
     :dedent:
 
 You can find the full example here: `ssl_without_ca <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca>`_.
@@ -259,22 +212,72 @@ 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.
+-   :ref:`ssl_ca_file <configuration_reference_iproto_uri_params_ssl_ca_file>`: a path to a trusted certificate authorities (CA) file.
+-   :ref:`ssl_cert_file <configuration_reference_iproto_uri_params_ssl_cert_file>`: a path to an SSL certificate file.
+-   :ref:`ssl_key_file <configuration_reference_iproto_uri_params_ssl_key_file>`: a path to a private SSL key file.
+-   :ref:`ssl_password <configuration_reference_iproto_uri_params_ssl_password>` (``instance001``): a password for an encrypted private SSL key.
+-   :ref:`ssl_password_file <configuration_reference_iproto_uri_params_ssl_password_file>` (``instance002`` and ``instance003``): a text file containing passwords for encrypted SSL keys.
+-   :ref:`ssl_ciphers <configuration_reference_iproto_uri_params_ssl_ciphers>`: a colon-separated list of SSL cipher suites the connection can use.
 
 ..  literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl_with_ca/config.yaml
     :language: yaml
-    :start-at: replicaset001:
+    :start-at: instances:
     :end-before: app:
     :dedent:
 
 You can find the full example here: `ssl_with_ca <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca>`_.
 
 
+.. _configuration_connections_ssl_advertise_uri:
+
+Advertise URI specifics
+~~~~~~~~~~~~~~~~~~~~~~~
+
+SSL parameters for an advertise URI should be set only if this :ref:`advertise URI is specified explicitly <configuration_connections_advertise_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:
+
+..  code-block:: yaml
+
+    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:
+
+..  code-block:: yaml
+
+    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'
+
+
 
 .. _configuration_connections_ssl_reloading_certificates: