diff --git a/doc/reference/configuration/cfg_basic.rst b/doc/reference/configuration/cfg_basic.rst index 3ddbd9f046..35fea4ea4e 100644 --- a/doc/reference/configuration/cfg_basic.rst +++ b/doc/reference/configuration/cfg_basic.rst @@ -61,20 +61,29 @@ .. confval:: listen Since version 1.6.4. + The read/write data port number or :ref:`URI ` (Universal Resource Identifier) string. Has no default value, so **must be specified** - if connections will occur from remote clients that do not use the - :ref:`“admin port” `. Connections made with + if connections occur from the remote clients that don't use the + :ref:`"admin port" `. Connections made with :samp:`listen = {URI}` are called "binary port" or "binary protocol" connections. A typical value is 3301. - .. NOTE:: + .. code-block:: lua + + box.cfg { listen = 3301 } + + box.cfg { listen = "127.0.0.1:3301" } + + .. NOTE:: A replica also binds to this port, and accepts connections, but these connections can only serve reads until the replica becomes a master. + Starting from version 2.10.0, you can specify :ref:`several URIs `. + | Type: integer or string | Default: null | Dynamic: yes diff --git a/doc/reference/configuration/cfg_replication.rst b/doc/reference/configuration/cfg_replication.rst index 0fca1c419f..cec9c67c21 100644 --- a/doc/reference/configuration/cfg_replication.rst +++ b/doc/reference/configuration/cfg_replication.rst @@ -32,9 +32,13 @@ :extsamp:`box.cfg{ replication = { {*{'uri1'}*}, {*{'uri2'}*} } }` - If one of the URIs is "self" -- that is, if one of the URIs is for the - instance where ``box.cfg{}`` is being executed on -- then it is ignored. - Thus it is possible to use the same ``replication`` specification on + .. note:: + + Starting from version 2.10.0, there is a number of other ways for specifying several URIs. See :ref:`syntax examples `. + + If one of the URIs is "self"---that is, if one of the URIs is for the + instance where ``box.cfg{}`` is being executed on---then it is ignored. + Thus, it is possible to use the same ``replication`` specification on multiple server instances, as shown in :ref:`these examples `. diff --git a/doc/reference/configuration/index.rst b/doc/reference/configuration/index.rst index 1ead50e661..6c5fdcd7b7 100644 --- a/doc/reference/configuration/index.rst +++ b/doc/reference/configuration/index.rst @@ -69,20 +69,25 @@ Command options URI -------------------------------------------------------------------------------- -Some configuration parameters and some functions depend on a URI, or -"Universal Resource Identifier". The URI string format is similar to the +Some configuration parameters and some functions depend on a URI (Universal Resource Identifier). +The URI string format is similar to the `generic syntax for a URI schema `_. -So it may contain (in order) a user name -for login, a password, a host name or host IP address, and a port number. Only -the port number is always mandatory. The password is mandatory if the user +It may contain (in order): + +* user name for login +* password +* host name or host IP address +* port number. + +Only a port number is always mandatory. A password is mandatory if a user name is specified, unless the user name is 'guest'. Formally, the URI syntax is ``[host:]port`` or ``[username:password@]host:port``. -If host is omitted, then '0.0.0.0' or '[::]' is assumed, -meaning respectively any IPv4 address or any IPv6 address, +If host is omitted, then "0.0.0.0" or "[::]" is assumed +meaning respectively any IPv4 address or any IPv6 address on the local machine. -If ``username:password`` is omitted, then 'guest' is assumed. Some examples: +If ``username:password`` is omitted, then the "guest" user is assumed. Some examples: .. container:: table @@ -99,40 +104,76 @@ If ``username:password`` is omitted, then 'guest' is assumed. Some examples: | username:password@host:port | notguest:sesame@mail.ru:3301 | +-----------------------------+------------------------------+ +In code, the URI value can be passed as a number (if only a port is specified) or a string: + +.. code-block:: lua + + box.cfg { listen = 3301 } + + box.cfg { listen = "127.0.0.1:3301" } + In certain circumstances, a Unix domain socket may be used where a URI is expected, for example, "unix/:/tmp/unix_domain_socket.sock" or simply "/tmp/unix_domain_socket.sock". +A method for parsing URIs is illustrated in :ref:`Module uri `. + +.. _index-uri-several: + +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 :ref:`box.cfg.listen ` and :ref:`box.cfg.replication `. +and, consequently, can specify several URIs in the configuration parameters +such as :ref:`box.cfg.listen ` and :ref:`box.cfg.replication `. -In addition to specifying URI as a number or a string, a number of other ways to pass URI values is available starting from Tarantool 2.10.0: +URI values can be set in a number of ways: -* As a string with one or several URIs separated by commas (provides backward compatibility) +* As a string with URI values separated by commas - code-block:: lua + .. code-block:: lua - box.cfg { listen = "127.0.0.1:3301, /unix.sock, 3302" } + box.cfg { listen = "127.0.0.1:3301, /unix.sock, 3302" } * As an array that contains URIs in a string format - code-block:: lua + .. code-block:: lua - box.cfg { listen = {"127.0.0.1:3301", "/unix.sock", "3302"} } + box.cfg { listen = {"127.0.0.1:3301", "/unix.sock", "3302"} } * As an array of tables with the ``uri`` field - code-block:: lua + .. code-block:: lua - box.cfg { listen = { - {uri = "127.0.0.1:3301"}, - {uri = "/unix.sock"}, - {uri = 3302} + box.cfg { listen = { + {uri = "127.0.0.1:3301"}, + {uri = "/unix.sock"}, + {uri = 3302} + } } + +Also, you can specify additional URI parameters. The recommended syntax: + +.. code-block:: lua + +box.cfg { listen = { + {uri = "127.0.0.1:3301", params = {param1 = "value1"}}, + {uri = "/unix.sock", params = {param2 = "value2"}}, + {uri = 3302, params = {param3 = "value3"}} } +} +In case of a single URI, the following syntax also works: -A method for parsing URIs is illustrated in :ref:`Module uri `. +.. code-block:: lua + + box.cfg { listen = { + uri = "127.0.0.1:3301", + params = { + param1 = "value1", + param2 = "value2" + } + }} .. _index-init_label: