Connection settings #3985

andreyaksenov · 2024-01-10T14:55:07Z

Main changes

Created a new Connections topic that describes iproto settings:
https://docs.d.tarantool.io/en/doc/3.0-connection-settings/concepts/configuration/configuration_connections/
Updated some descriptions in iproto reference:
https://docs.d.tarantool.io/en/doc/3.0-connection-settings/reference/configuration/configuration_reference/#iproto
Removed the old Traffic encryption section from Security hardening guide:
https://docs.d.tarantool.io/en/doc/3.0-connection-settings/enterprise/security/
Now this topic doesn't include how-to/reference information and describes only general recommendations. We can think about merging Security hardening guide with the Security audit topic at some point.
Removed duplicated information from the main Configuration topic and added the link to the new Connections topic:
https://docs.d.tarantool.io/en/doc/3.0-connection-settings/concepts/configuration/#connection-settings
Note that the whole Configuration options overview section will be removed when corresponding topics for specific subsystems are ready (missing topics: Access control, In-memory storage, Persistence). The Configuration topic will be renamed to Configuration overview. So, the idea of future structure is smth like this:
- Configuration
  - Configuration overview
    - Storing configuration in etcd
    - Storing configuration in Tarantool
    - ...
  - In-memory storage
  - Persistence
  - Replication
  - Sharding
  - Connections
  - Access control
  - Authentication
  - Logging
  - ...
Added several runnable samples:
- Single-instance iproto.listen samples.
- Advertise URI sample (replica set, uses two listen URIs and one advertise URI).
- SSL examples (without and with CA).

Fixed links in other documents

Updated a link in the Getting Started guide:
https://docs.d.tarantool.io/en/doc/3.0-connection-settings/how-to/getting_started_db/#connecting-remotely
Updated links in TCM docs:
https://docs.d.tarantool.io/en/doc/3.0-connection-settings/reference/tooling/tcm/tcm_configuration_reference/#confval-storage.tarantool.ssl.key-file

Totktonada · 2024-01-18T16:54:03Z

doc/enterprise/security.rst

-To configure traffic encryption, you need to set the special :ref:`URI parameters <index-uri-several-params>` for a particular connection.
-The parameters can be set for the following ``box.cfg`` options and ``nex.box`` method:
-
-*   :ref:`box.cfg.listen <cfg_basic-listen>` -- on the server side.


Shouldn't we add it into the box.cfg options description (and net.box too)?

Totktonada

I have no strict objections here. There are thoughts around the URIs topic in my comments above, but I guess that you may want to move forward in smaller iterations and I'm OK with it.

p7nov

Please see my thoughts about connections.

Skipped the authentication part as we discussed.

doc/concepts/configuration/configuration_connections.rst

p7nov · 2024-01-22T10:12:26Z

doc/concepts/configuration/configuration_connections.rst

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


Can we explicitly map these settings to connection types (the first list on this page): which settings are used for which connections?

Not exactly. iproto.listen is used for all purposes: communicating between instances, administration using tt/TCM, and so on. Advertise URI is only applied to replication and sharding. In the new intro, I've converted the first list to a regular sentence. Looks like the list with connection settings is more important and the second list shouldn't add additional distraction.

doc/concepts/configuration/configuration_connections.rst

p7nov · 2024-01-22T10:18:13Z

doc/concepts/configuration/configuration_connections.rst

+Listen URI
+----------
+
+To configure URIs used to listen for incoming requests, use the :ref:`iproto.listen <configuration_reference_iproto_listen>` configuration option.


As a non-expert reader, I don't quite understand from this wording, what requests are we talking about. Are these data requests (select from spaces)? Internal cluster requests? Or just any network requests from whoever connects to this URI?

Good point. I'm not sure that we should give examples of requests right here. From the intro, it should be clear a high-level idea on why connections are required. There are too many request types that can come from other instances and external systems: internal replication requests, sharding requests, data definition and data manipulation requests, and so on. I feel that concrete info should live in corresponding topics. A user can open the Binary protocol section linked in a note to see a tons of request types :)

I don't mean that we should describe all possible requests, but maybe provide general conceptual info in an explicit human-friendly form.
Like, this is the basic option. It is required on any instance to enable external connections to it.
Also, we can add a navigating link to Advertise URI by writing a sentence about the relation between the two URI types. Why do we need the two at all?

As an idea: we can expand the intro to explain all key entities in it (listen URI, advertise URI, secure connections) and then leave all subsections as is - just showing the usage examples.

I hope, the current description should work better - it adds the information about how an advertise URI is used and also tells that SSL settings are optional.

p7nov · 2024-01-22T10:25:50Z

doc/concepts/configuration/configuration_connections.rst

+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:


Above, these were cluster members instead of replica set members. Does this need a more detailed explanation? If it's obvious for readers - OK.

The behavior of iproto.advertise.peer is a bit complicated. It advertises the instance to other replica set members. If iproto.advertise.sharding is not specified, iproto.advertise.peer is used to advertise the instance to a router and rebalancer. So, both are true if different contexts.

If iproto.advertise.sharding is not specified, iproto.advertise.peer is used

I believe this should be written explicitly, I couldn't ever guess myself)

Added a note to the reference page:

doc/concepts/configuration/configuration_connections.rst

doc/reference/configuration/configuration_reference.rst

p7nov

👍

andreyaksenov marked this pull request as draft January 10, 2024 14:56

andreyaksenov linked an issue Jan 10, 2024 that may be closed by this pull request

[Config] Update the 'Security hardening guide' to using a new config #3665

Closed

2 tasks

andreyaksenov force-pushed the 3.0-connection-settings branch 24 times, most recently from f23f4e3 to 2dde692 Compare January 15, 2024 12:23

andreyaksenov marked this pull request as ready for review January 15, 2024 12:55

andreyaksenov force-pushed the 3.0-connection-settings branch 3 times, most recently from b617c53 to c897016 Compare January 15, 2024 13:25

andreyaksenov force-pushed the 3.0-connection-settings branch from deb84b2 to 766f226 Compare January 18, 2024 14:41

Totktonada reviewed Jan 18, 2024

View reviewed changes

andreyaksenov force-pushed the 3.0-connection-settings branch 2 times, most recently from d06270d to 9a658eb Compare January 19, 2024 08:33

andreyaksenov requested a review from p7nov January 19, 2024 13:09

andreyaksenov force-pushed the 3.0-connection-settings branch from 9a658eb to 15980fa Compare January 19, 2024 14:30

Totktonada approved these changes Jan 19, 2024

View reviewed changes

andreyaksenov force-pushed the 3.0-connection-settings branch 2 times, most recently from cb5c4c6 to ba20c30 Compare January 20, 2024 18:27

Connection settings: update per review

f2df0e8

andreyaksenov force-pushed the 3.0-connection-settings branch from ba20c30 to f2df0e8 Compare January 20, 2024 18:28

andreyaksenov mentioned this pull request Jan 22, 2024

box.cfg: add the 'Traffic encryption' section #4009

Merged

p7nov requested changes Jan 22, 2024

View reviewed changes

andreyaksenov force-pushed the 3.0-connection-settings branch 8 times, most recently from 052adf7 to 6291442 Compare January 22, 2024 15:00

Connection settings: update per review 2

27a2e8b

andreyaksenov force-pushed the 3.0-connection-settings branch from 6291442 to 27a2e8b Compare January 22, 2024 15:24

andreyaksenov requested a review from p7nov January 22, 2024 15:24

andreyaksenov force-pushed the 3.0-connection-settings branch from 8c569e5 to b53b25f Compare January 23, 2024 07:27

p7nov approved these changes Jan 23, 2024

View reviewed changes

Connection settings: update per review 2.1

f4574a8

andreyaksenov force-pushed the 3.0-connection-settings branch from b53b25f to f4574a8 Compare January 23, 2024 08:04

andreyaksenov merged commit 53f36a3 into latest Jan 23, 2024

andreyaksenov deleted the 3.0-connection-settings branch January 23, 2024 08:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Connection settings #3985

Connection settings #3985

andreyaksenov commented Jan 10, 2024 •

edited

Loading

Totktonada Jan 18, 2024

Totktonada left a comment

p7nov left a comment

p7nov Jan 22, 2024

andreyaksenov Jan 22, 2024 •

edited

Loading

p7nov Jan 22, 2024

andreyaksenov Jan 22, 2024 •

edited

Loading

p7nov Jan 23, 2024

andreyaksenov Jan 23, 2024

p7nov Jan 22, 2024

andreyaksenov Jan 22, 2024 •

edited

Loading

p7nov Jan 23, 2024

andreyaksenov Jan 23, 2024

p7nov left a comment

Connection settings #3985

Connection settings #3985

Conversation

andreyaksenov commented Jan 10, 2024 • edited Loading

Main changes

Fixed links in other documents

Choose a reason for hiding this comment

Totktonada left a comment

Choose a reason for hiding this comment

p7nov left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andreyaksenov Jan 22, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andreyaksenov Jan 22, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andreyaksenov Jan 22, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

p7nov left a comment

Choose a reason for hiding this comment

andreyaksenov commented Jan 10, 2024 •

edited

Loading

andreyaksenov Jan 22, 2024 •

edited

Loading

andreyaksenov Jan 22, 2024 •

edited

Loading

andreyaksenov Jan 22, 2024 •

edited

Loading