From e98d56a26f507f424bba130b92568587e720df92 Mon Sep 17 00:00:00 2001 From: Andrey Aksenov <38073144+andreyaksenov@users.noreply.github.com> Date: Mon, 22 Jan 2024 12:47:52 +0300 Subject: [PATCH] box.cfg: add the 'Traffic encryption' section (#4009) Add the 'Traffic encryption' section and made 'Since version' and 'Dynamic: yes' consistent --- .../configuration/configuration_code.rst | 276 ++++++++++++++++++ doc/reference/configuration/cfg_basic.rst | 20 +- .../cfg_binary_logging_snapshots.rst | 10 +- doc/reference/configuration/cfg_feedback.rst | 18 +- .../configuration/cfg_hot_standby.rst | 4 +- doc/reference/configuration/cfg_logging.rst | 17 +- .../configuration/cfg_networking.rst | 13 +- .../configuration/cfg_replication.rst | 49 +++- .../configuration/cfg_snapshot_daemon.rst | 6 +- doc/reference/configuration/cfg_storage.rst | 28 +- 10 files changed, 395 insertions(+), 46 deletions(-) diff --git a/doc/concepts/configuration/configuration_code.rst b/doc/concepts/configuration/configuration_code.rst index 09263fea9f..779a973a2e 100644 --- a/doc/concepts/configuration/configuration_code.rst +++ b/doc/concepts/configuration/configuration_code.rst @@ -319,6 +319,282 @@ In case of a single URI, the following syntax also works: } +.. _configuration_code_iproto-encryption: + +Traffic encryption +------------------ + +.. admonition:: Enterprise Edition + :class: fact + + Traffic encryption is supported by the `Enterprise Edition `_ only. + +Since version 2.10.0, Tarantool Enterprise Edition has the built-in support for using SSL to encrypt the client-server communications over :ref:`binary connections `, +that is, between Tarantool instances in a cluster or connecting to an instance via connectors using :doc:`net.box `. + +Tarantool uses the OpenSSL library that is included in the delivery package. +Note that SSL connections use only TLSv1.2. + +.. _configuration_code_iproto-encryption-config: + +Configuration +~~~~~~~~~~~~~ + +To configure traffic encryption, you need to set the special :ref:`URI parameters ` for a particular connection. +The parameters can be set for the following ``box.cfg`` options and ``net.box`` method: + +* :ref:`box.cfg.listen ` -- on the server side. +* :ref:`box.cfg.replication ` -- on the client side. +* :ref:`net_box_object.connect() ` -- on the client side. + +Below is the list of the parameters. +In the :ref:`next section `, you can find details and examples on what should be configured on both the server side and the client side. + +* ``transport`` -- enables SSL encryption for a connection if set to ``ssl``. + The default value is ``plain``, which means the encryption is off. If the parameter is not set, the encryption is off too. + Other encryption-related parameters can be used only if the ``transport = 'ssl'`` is set. + + Example: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl/myapp.lua + :language: lua + :start-at: net.box + :end-before: return connection + :dedent: + +* ``ssl_key_file`` -- a path to a private SSL key file. + Mandatory for a server. + For a client, it's mandatory if the ``ssl_ca_file`` parameter is set for a server; otherwise, optional. + If the private key is encrypted, provide a password for it in the ``ssl_password`` or ``ssl_password_file`` parameter. + +* ``ssl_cert_file`` -- a path to an SSL certificate file. + Mandatory for a server. + For a client, it's mandatory if the ``ssl_ca_file`` parameter is set for a server; otherwise, optional. + +* ``ssl_ca_file`` -- a path to a trusted certificate authorities (CA) file. Optional. If not set, the peer won't be checked for authenticity. + + Both a server and a client can use the ``ssl_ca_file`` parameter: + + * If it's on the server side, the server verifies the client. + * If it's on the client side, the client verifies the server. + * If both sides have the CA files, the server and the client verify each other. + +* ``ssl_ciphers`` -- a colon-separated (``:``) list of SSL cipher suites the connection can use. See the :ref:`configuration_code_iproto-encryption-ciphers` section for details. Optional. + Note that the list is not validated: if a cipher suite is unknown, Tarantool just ignores it, doesn't establish the connection and writes to the log that no shared cipher found. + +* ``ssl_password`` -- a password for an encrypted private SSL key. Optional. Alternatively, the password + can be provided in ``ssl_password_file``. + +* ``ssl_password_file`` -- a text file with one or more passwords for encrypted private SSL keys + (each on a separate line). Optional. Alternatively, the password can be provided in ``ssl_password``. + + Tarantool applies the ``ssl_password`` and ``ssl_password_file`` parameters in the following order: + + 1. If ``ssl_password`` is provided, Tarantool tries to decrypt the private key with it. + 2. If ``ssl_password`` is incorrect or isn't provided, Tarantool tries all passwords from ``ssl_password_file`` + one by one in the order they are written. + 3. If ``ssl_password`` and all passwords from ``ssl_password_file`` are incorrect, + or none of them is provided, Tarantool treats the private key as unencrypted. + +Configuration example: + +.. code-block:: lua + + box.cfg{ listen = { + uri = 'localhost:3301', + params = { + transport = 'ssl', + ssl_key_file = '/path_to_key_file', + ssl_cert_file = '/path_to_cert_file', + ssl_ciphers = 'HIGH:!aNULL', + ssl_password = 'topsecret' + } + }} + +.. _configuration_code_iproto-encryption-ciphers: + +Supported ciphers +***************** + +Tarantool Enterprise supports the following cipher suites: + +* ECDHE-ECDSA-AES256-GCM-SHA384 +* ECDHE-RSA-AES256-GCM-SHA384 +* DHE-RSA-AES256-GCM-SHA384 +* ECDHE-ECDSA-CHACHA20-POLY1305 +* ECDHE-RSA-CHACHA20-POLY1305 +* DHE-RSA-CHACHA20-POLY1305 +* ECDHE-ECDSA-AES128-GCM-SHA256 +* ECDHE-RSA-AES128-GCM-SHA256 +* DHE-RSA-AES128-GCM-SHA256 +* ECDHE-ECDSA-AES256-SHA384 +* ECDHE-RSA-AES256-SHA384 +* DHE-RSA-AES256-SHA256 +* ECDHE-ECDSA-AES128-SHA256 +* ECDHE-RSA-AES128-SHA256 +* DHE-RSA-AES128-SHA256 +* ECDHE-ECDSA-AES256-SHA +* ECDHE-RSA-AES256-SHA +* DHE-RSA-AES256-SHA +* ECDHE-ECDSA-AES128-SHA +* ECDHE-RSA-AES128-SHA +* DHE-RSA-AES128-SHA +* AES256-GCM-SHA384 +* AES128-GCM-SHA256 +* AES256-SHA256 +* AES128-SHA256 +* AES256-SHA +* AES128-SHA +* GOST2012-GOST8912-GOST8912 +* GOST2001-GOST89-GOST89 + +Tarantool Enterprise static build has the embedded engine to support the GOST cryptographic algorithms. +If you use these algorithms for traffic encryption, specify the corresponding cipher suite in the ``ssl_ciphers`` parameter, for example: + +.. code-block:: lua + + box.cfg{ listen = { + uri = 'localhost:3301', + params = { + transport = 'ssl', + ssl_key_file = '/path_to_key_file', + ssl_cert_file = '/path_to_cert_file', + ssl_ciphers = 'GOST2012-GOST8912-GOST8912' + } + }} + +For detailed information on SSL ciphers and their syntax, refer to `OpenSSL documentation `__. + +Using environment variables +*************************** + +The URI parameters for traffic encryption can also be set via :ref:`environment variables `, for example: + +.. code-block:: bash + + export TT_LISTEN="localhost:3301?transport=ssl&ssl_cert_file=/path_to_cert_file&ssl_key_file=/path_to_key_file" + + +.. _configuration_code_iproto-encryption-config-sc: + +Server-client configuration details +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When configuring the traffic encryption, you need to specify the necessary parameters on both the server side and the client side. +Below you can find the summary on the options and parameters to be used and :ref:`examples of configuration `. + +**Server side** + +* Is configured via the ``box.cfg.listen`` option. +* Mandatory URI parameters: ``transport``, ``ssl_key_file`` and ``ssl_cert_file``. +* Optional URI parameters: ``ssl_ca_file``, ``ssl_ciphers``, ``ssl_password``, and ``ssl_password_file``. + + +**Client side** + +* Is configured via the ``box.cfg.replication`` option (see :ref:`details `) or ``net_box_object.connect()``. + +Parameters: + +* If the server side has only the ``transport``, ``ssl_key_file`` and ``ssl_cert_file`` parameters set, + on the client side, you need to specify only ``transport = ssl`` as the mandatory parameter. + All other URI parameters are optional. + +* If the server side also has the ``ssl_ca_file`` parameter set, + on the client side, you need to specify ``transport``, ``ssl_key_file`` and ``ssl_cert_file`` as the mandatory parameters. + Other parameters -- ``ssl_ca_file``, ``ssl_ciphers``, ``ssl_password``, and ``ssl_password_file`` -- are optional. + + +.. _configuration_code_iproto-encryption-config-example: + +Configuration examples +********************** + +Suppose, there is a :ref:`master-replica ` set with two Tarantool instances: + +* 127.0.0.1:3301 -- master (server) +* 127.0.0.1:3302 -- replica (client). + +Examples below show the configuration related to connection encryption for two cases: +when the trusted certificate authorities (CA) file is not set on the server side and when it does. +Only mandatory URI parameters are mentioned in these examples. + +1. **Without CA** + +* 127.0.0.1:3301 -- master (server) + + .. code-block:: lua + + box.cfg{ + listen = { + uri = '127.0.0.1:3301', + params = { + transport = 'ssl', + ssl_key_file = '/path_to_key_file', + ssl_cert_file = '/path_to_cert_file' + } + } + } + +* 127.0.0.1:3302 -- replica (client) + + .. code-block:: lua + + box.cfg{ + listen = { + uri = '127.0.0.1:3302', + params = {transport = 'ssl'} + }, + replication = { + uri = 'username:password@127.0.0.1:3301', + params = {transport = 'ssl'} + }, + read_only = true + } + +2. **With CA** + +* 127.0.0.1:3301 -- master (server) + + .. code-block:: lua + + box.cfg{ + listen = { + uri = '127.0.0.1:3301', + params = { + transport = 'ssl', + ssl_key_file = '/path_to_key_file', + ssl_cert_file = '/path_to_cert_file', + ssl_ca_file = '/path_to_ca_file' + } + } + } + +* 127.0.0.1:3302 -- replica (client) + + .. code-block:: lua + + box.cfg{ + listen = { + uri = '127.0.0.1:3302', + params = { + transport = 'ssl', + ssl_key_file = '/path_to_key_file', + ssl_cert_file = '/path_to_cert_file' + } + }, + replication = { + uri = 'username:password@127.0.0.1:3301', + params = { + transport = 'ssl', + ssl_key_file = '/path_to_key_file', + ssl_cert_file = '/path_to_cert_file' + } + }, + read_only = true + } + + .. _configuration_code_run_instance_tarantool: diff --git a/doc/reference/configuration/cfg_basic.rst b/doc/reference/configuration/cfg_basic.rst index acb08806e5..495b7f1eb2 100644 --- a/doc/reference/configuration/cfg_basic.rst +++ b/doc/reference/configuration/cfg_basic.rst @@ -19,6 +19,7 @@ .. confval:: background Since version 1.6.2. + Run the server as a background task. The :ref:`log ` and :ref:`pid_file ` parameters must be non-null for this to work. @@ -33,6 +34,7 @@ .. confval:: custom_proc_title Since version 1.6.7. + Add the given string to the server's process title (what’s shown in the COMMAND column for ``ps -ef`` and ``top -c`` commands). @@ -97,6 +99,7 @@ .. confval:: memtx_dir Since version 1.7.4. + A directory where memtx stores snapshot (.snap) files. Can be relative to :ref:`work_dir `. If not specified, defaults to ``work_dir``. See also :ref:`wal_dir `. @@ -111,6 +114,7 @@ .. confval:: pid_file Since version 1.4.9. + Store the process id in this file. Can be relative to :ref:`work_dir `. A typical value is “:file:`tarantool.pid`”. @@ -124,6 +128,7 @@ .. confval:: read_only Since version 1.7.1. + Say ``box.cfg{read_only=true...}`` to put the server instance in read-only mode. After this, any requests that try to change persistent data will fail with error :errcode:`ER_READONLY`. Read-only mode should be used for master-replica @@ -160,6 +165,7 @@ .. confval:: sql_cache_size Since version 2.3.1. + The maximum number of bytes in the cache for :ref:`SQL prepared statements `. (The number of bytes that are actually used can be seen with @@ -175,6 +181,7 @@ .. confval:: vinyl_dir Since version 1.7.1. + A directory where vinyl files or subdirectories will be stored. Can be relative to :ref:`work_dir `. If not specified, defaults to ``work_dir``. @@ -189,6 +196,7 @@ .. confval:: vinyl_timeout Since version 1.7.5. + The vinyl storage engine has a scheduler which does compaction. When vinyl is low on available memory, the compaction scheduler may be unable to keep up with incoming update requests. @@ -207,7 +215,9 @@ .. confval:: username - Since version 1.4.9. UNIX user name to switch to after start. + Since version 1.4.9. + + UNIX user name to switch to after start. | Type: string | Default: null @@ -219,6 +229,7 @@ .. confval:: wal_dir Since version 1.6.2. + A directory where write-ahead log (.xlog) files are stored. Can be relative to :ref:`work_dir `. Sometimes ``wal_dir`` and :ref:`memtx_dir ` are specified with different values, so @@ -235,6 +246,7 @@ .. confval:: work_dir Since version 1.4.9. + A directory where database working files will be stored. The server instance switches to ``work_dir`` with :manpage:`chdir(2)` after start. Can be relative to the current directory. If not specified, defaults to @@ -263,6 +275,7 @@ .. confval:: worker_pool_threads Since version 1.7.5. + The maximum number of threads to use during execution of certain internal processes (currently :ref:`socket.getaddrinfo() ` and @@ -277,7 +290,9 @@ .. confval:: strip_core - Since version 2.2.2. Whether coredump files should include memory allocated for tuples. + Since version 2.2.2. + + Whether coredump files should include memory allocated for tuples. (This can be large if Tarantool runs under heavy load.) Setting to ``true`` means "do not include". In an older version of Tarantool the default value of this parameter was ``false``. @@ -292,6 +307,7 @@ .. confval:: memtx_use_mvcc_engine Since version :doc:`2.6.1 `. + Enables :ref:`transactional manager ` if set to ``true``. | Type: boolean diff --git a/doc/reference/configuration/cfg_binary_logging_snapshots.rst b/doc/reference/configuration/cfg_binary_logging_snapshots.rst index 39e95ec7fa..83f29695b6 100644 --- a/doc/reference/configuration/cfg_binary_logging_snapshots.rst +++ b/doc/reference/configuration/cfg_binary_logging_snapshots.rst @@ -63,7 +63,7 @@ | Type: float | Default: null | Environment variable: TT_SNAP_IO_RATE_LIMIT - | Dynamic: **yes** + | Dynamic: yes .. _cfg_binary_logging_snapshots-wal_mode: @@ -120,7 +120,7 @@ | Type: number | Default: 16777216 bytes | Environment variable: TT_WAL_QUEUE_MAX_SIZE - | Dynamic: **yes** + | Dynamic: yes .. _cfg_binary_logging_snapshots-wal_cleanup_delay: @@ -146,7 +146,7 @@ | Type: number | Default: 14400 seconds | Environment variable: TT_WAL_CLEANUP_DELAY - | Dynamic: **yes** + | Dynamic: yes .. _cfg_binary_logging_snapshots-wal_ext: @@ -195,7 +195,7 @@ | Type: map | Default: nil | Environment variable: TT_WAL_EXT - | Dynamic: **yes** + | Dynamic: yes .. _cfg_binary_logging_secure_erasing: @@ -210,4 +210,4 @@ | Type: boolean | Default: false | Environment variable: TT_SECURE_ERASING - | Dynamic: **yes** + | Dynamic: yes diff --git a/doc/reference/configuration/cfg_feedback.rst b/doc/reference/configuration/cfg_feedback.rst index e91b5de398..cd7b1d02e8 100644 --- a/doc/reference/configuration/cfg_feedback.rst +++ b/doc/reference/configuration/cfg_feedback.rst @@ -15,7 +15,9 @@ adjust or turn off this feature. .. confval:: feedback_enabled - Since version 1.10.1. Whether to send feedback. + Since version 1.10.1. + + Whether to send feedback. If this is set to ``true``, feedback will be sent as described above. If this is set to ``false``, no feedback will be sent. @@ -23,27 +25,31 @@ adjust or turn off this feature. | Type: boolean | Default: true | Environment variable: TT_FEEDBACK_ENABLED - | Dynamic: **yes** + | Dynamic: yes .. _cfg_logging-feedback_host: .. confval:: feedback_host - Since version 1.10.1. The address to which the packet is sent. + Since version 1.10.1. + + The address to which the packet is sent. Usually the recipient is Tarantool, but it can be any URL. | Type: string | Default: ``https://feedback.tarantool.io`` | Environment variable: TT_FEEDBACK_HOST - | Dynamic: **yes** + | Dynamic: yes .. _cfg_logging-feedback_interval: .. confval:: feedback_interval - Since version 1.10.1. The number of seconds between sendings, usually 3600 (1 hour). + Since version 1.10.1. + + The number of seconds between sendings, usually 3600 (1 hour). | Type: float | Default: 3600 | Environment variable: TT_FEEDBACK_INTERVAL - | Dynamic: **yes** + | Dynamic: yes diff --git a/doc/reference/configuration/cfg_hot_standby.rst b/doc/reference/configuration/cfg_hot_standby.rst index 3d4481f861..7202f0027a 100644 --- a/doc/reference/configuration/cfg_hot_standby.rst +++ b/doc/reference/configuration/cfg_hot_standby.rst @@ -1,6 +1,8 @@ .. confval:: hot_standby - Since version 1.7.4. Whether to start the server in **hot standby** mode. + Since version 1.7.4. + + Whether to start the server in **hot standby** mode. Hot standby is a feature which provides a simple form of failover without :ref:`replication `. diff --git a/doc/reference/configuration/cfg_logging.rst b/doc/reference/configuration/cfg_logging.rst index c256e1ff2c..4a738f39ec 100644 --- a/doc/reference/configuration/cfg_logging.rst +++ b/doc/reference/configuration/cfg_logging.rst @@ -16,6 +16,7 @@ application. .. confval:: log_level Since version 1.6.2. + Specifies the level of detail the :ref:`log ` has. There are seven levels: * 1 – ``SYSERROR`` @@ -34,7 +35,7 @@ application. | Type: integer | Default: 5 | Environment variable: TT_LOG_LEVEL - | Dynamic: **yes** + | Dynamic: yes .. note:: Prior to Tarantool 1.7.5 there were only six levels and ``DEBUG`` was @@ -47,6 +48,7 @@ application. .. confval:: log Since version 1.7.4. + By default, Tarantool sends the log to the standard error stream (``stderr``). If ``log`` is specified, Tarantool can send the log to a: @@ -130,6 +132,7 @@ application. .. confval:: log_nonblock Since version 1.7.4. + If ``log_nonblock`` equals **true**, Tarantool does not block during logging when the system is not ready for writing, and drops the message instead. If :ref:`log_level ` is high, and many @@ -158,6 +161,7 @@ application. .. confval:: too_long_threshold Since version 1.6.2. + If processing a request takes longer than the given value (in seconds), warn about it in the log. Has effect only if :ref:`log_level ` is greater than or equal to 4 (WARNING). @@ -165,13 +169,15 @@ application. | Type: float | Default: 0.5 | Environment variable: TT_TOO_LONG_THRESHOLD - | Dynamic: **yes** + | Dynamic: yes .. _cfg_logging-log_format: .. confval:: log_format - Since version 1.7.6. Log entries have two possible formats: + Since version 1.7.6. + + Log entries have two possible formats: * 'plain' (the default), or * 'json' (with more detail and with JSON labels). @@ -207,7 +213,7 @@ application. | Type: string | Default: 'plain' | Environment variable: TT_LOG_FORMAT - | Dynamic: **yes** + | Dynamic: yes .. _cfg_logging-log_modules: @@ -215,6 +221,7 @@ application. .. confval:: log_modules Since version :doc:`2.11.0 `. + Configure the specified log levels (:ref:`log_level `) for different modules. You can specify a logging level for the following module types: @@ -231,7 +238,7 @@ application. | Type: table | Default: blank | Environment variable: TT_LOG_MODULES - | Dynamic: **yes** + | Dynamic: yes | diff --git a/doc/reference/configuration/cfg_networking.rst b/doc/reference/configuration/cfg_networking.rst index 5993d6755a..cdf8f7c4d0 100644 --- a/doc/reference/configuration/cfg_networking.rst +++ b/doc/reference/configuration/cfg_networking.rst @@ -8,6 +8,7 @@ .. confval:: io_collect_interval Since version 1.4.9. + The instance will sleep for io_collect_interval seconds between iterations of the event loop. Can be used to reduce CPU load in deployments in which the number of client connections is large, but requests are not so frequent @@ -16,13 +17,15 @@ | Type: float | Default: null | Environment variable: TT_IO_COLLECT_INTERVAL - | Dynamic: **yes** + | Dynamic: yes .. _cfg_networking-net_msg_max: .. confval:: net_msg_max - Since version 1.10.1. To handle messages, Tarantool allocates fibers. + Since version 1.10.1. + + To handle messages, Tarantool allocates fibers. To prevent fiber overhead from affecting the whole system, Tarantool restricts how many messages the fibers handle, so that some pending requests are blocked. @@ -53,13 +56,14 @@ | Type: integer | Default: 768 | Environment variable: TT_NET_MSG_MAX - | Dynamic: **yes** + | Dynamic: yes .. _cfg_networking-readahead: .. confval:: readahead Since version 1.6.2. + The size of the read-ahead buffer associated with a client connection. The larger the buffer, the more memory an active connection consumes and the more requests can be read from the operating system buffer in a single @@ -72,13 +76,14 @@ | Type: integer | Default: 16320 | Environment variable: TT_READAHEAD - | Dynamic: **yes** + | Dynamic: yes .. _cfg_networking-iproto_threads: .. confval:: iproto_threads Since version :doc:`2.8.1 `. + The number of :ref:`network threads `. There can be unusual workloads where the network thread is 100% loaded and the transaction processor thread is not, so the network diff --git a/doc/reference/configuration/cfg_replication.rst b/doc/reference/configuration/cfg_replication.rst index 7e5bc501a4..c71d9c4dcc 100644 --- a/doc/reference/configuration/cfg_replication.rst +++ b/doc/reference/configuration/cfg_replication.rst @@ -22,6 +22,7 @@ .. confval:: replication Since version 1.7.4. + If ``replication`` is not an empty string, the instance is considered to be a Tarantool :ref:`replica `. The replica will try to connect to the master specified in ``replication`` with a @@ -58,13 +59,14 @@ | Type: string | Default: null | Environment variable: TT_REPLICATION - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_anon: .. confval:: replication_anon Since version 2.3.1. + A Tarantool replica can be anonymous. This type of replica is read-only (but you still can write to temporary and replica-local spaces), and it isn't present in the ``_cluster`` table. @@ -204,7 +206,7 @@ | Type: boolean | Default: false | Environment variable: TT_REPLICATION_ANON - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-bootstrap_leader: @@ -229,7 +231,7 @@ | Type: string | Default: null | Environment variable: TT_BOOTSTRAP_LEADER - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-bootstrap_strategy: @@ -258,7 +260,7 @@ | Type: string | Default: auto | Environment variable: TT_BOOTSTRAP_STRATEGY - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_connect_timeout: @@ -266,6 +268,7 @@ .. confval:: replication_connect_timeout Since version 1.9.0. + The number of seconds that a replica will wait when trying to connect to a master in a cluster. See :ref:`orphan status ` for details. @@ -278,13 +281,14 @@ | Type: float | Default: 30 | Environment variable: TT_REPLICATION_CONNECT_TIMEOUT - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_connect_quorum: .. confval:: replication_connect_quorum Deprecated since :doc:`2.11.0 `. + This option is in effect if :ref:`bootstrap_strategy ` is set to ``legacy``. Specifies the number of nodes to be up and running to start a replica set. @@ -303,13 +307,14 @@ | Type: integer | Default: null | Environment variable: TT_REPLICATION_CONNECT_QUORUM - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_skip_conflict: .. confval:: replication_skip_conflict Since version 1.10.1. + By default, if a replica adds a unique key that another replica has added, replication :ref:`stops ` with error = ER_TUPLE_FOUND. @@ -327,7 +332,7 @@ | Type: boolean | Default: false | Environment variable: TT_REPLICATION_SKIP_CONFLICT - | Dynamic: **yes** + | Dynamic: yes .. NOTE:: @@ -340,6 +345,7 @@ .. confval:: replication_sync_lag Since version 1.9.0. + The maximum :ref:`lag ` allowed for a replica. When a replica :ref:`syncs ` (gets updates from a master), it may not catch up completely. @@ -358,13 +364,14 @@ | Type: float | Default: 10 | Environment variable: TT_REPLICATION_SYNC_LAG - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_sync_timeout: .. confval:: replication_sync_timeout Since version 1.10.2. + The number of seconds that a node waits when trying to sync with other nodes in a replica set (see :ref:`bootstrap_strategy `), after connecting or during :ref:`configuration update `. @@ -376,7 +383,7 @@ | Type: float | Default: 300 | Environment variable: TT_REPLICATION_SYNC_TIMEOUT - | Dynamic: **yes** + | Dynamic: yes .. NOTE:: @@ -388,6 +395,7 @@ .. confval:: replication_timeout Since version 1.7.5. + If the master has no updates to send to the replicas, it sends heartbeat messages every ``replication_timeout`` seconds, and each replica sends an ACK packet back. @@ -400,13 +408,15 @@ | Type: integer | Default: 1 | Environment variable: TT_REPLICATION_TIMEOUT - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replicaset_uuid: .. confval:: replicaset_uuid - Since version 1.9.0. As described in section + Since version 1.9.0. + + As described in section :ref:`"Replication architecture" `, each replica set is identified by a `universally unique identifier `_ @@ -457,6 +467,7 @@ .. confval:: instance_uuid Since version 1.9.0. + For replication administration purposes, it is possible to set the `universally unique identifiers `_ of the instance (``instance_uuid``) and the replica set @@ -481,6 +492,7 @@ .. confval:: replication_synchro_quorum Since version :doc:`2.5.1 `. + For :ref:`synchronous replication ` only. This option tells how many replicas should confirm the receipt of a synchronous transaction before it can finish its commit. @@ -519,13 +531,14 @@ | Type: number | Default: N / 2 + 1 (before version :doc:`2.10.0 `, the default value was 1) | Environment variable: TT_REPLICATION_SYNCHRO_QUORUM - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_synchro_timeout: .. confval:: replication_synchro_timeout Since version :doc:`2.5.1 `. + For :ref:`synchronous replication ` only. Tells how many seconds to wait for a synchronous transaction quorum replication until it is declared failed and is rolled back. @@ -537,13 +550,14 @@ | Type: number | Default: 5 | Environment variable: TT_REPLICATION_SYNCHRO_TIMEOUT - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_replication_threads: .. confval:: replication_threads Since version :doc:`2.10.0 `. + The number of threads spawned to decode the incoming replication data. The default value is `1`. @@ -565,6 +579,7 @@ .. confval:: election_mode Since version :doc:`2.6.1 `. + Specifies the role of a replica set node in the :ref:`leader election process `. @@ -607,13 +622,14 @@ | Type: string | Default: 'off' | Environment variable: TT_ELECTION_MODE - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-election_timeout: .. confval:: election_timeout Since version :doc:`2.6.1 `. + Specifies the timeout between election rounds in the :ref:`leader election process ` if the previous round ended up with a split-vote. @@ -638,13 +654,14 @@ | Type: number | Default: 5 | Environment variable: TT_ELECTION_TIMEOUT - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-election_fencing_mode: .. confval:: election_fencing_mode Since version :doc:`2.11.0 `. + In earlier Tarantool versions, use :ref:`election_fencing_enabled ` instead. Specifies the :ref:`leader fencing mode ` that @@ -672,4 +689,4 @@ | Type: string | Default: 'soft' | Environment variable: TT_ELECTION_FENCING_MODE - | Dynamic: **yes** + | Dynamic: yes diff --git a/doc/reference/configuration/cfg_snapshot_daemon.rst b/doc/reference/configuration/cfg_snapshot_daemon.rst index 3f12de315c..0f24fc4495 100644 --- a/doc/reference/configuration/cfg_snapshot_daemon.rst +++ b/doc/reference/configuration/cfg_snapshot_daemon.rst @@ -51,6 +51,7 @@ The checkpoint daemon and the Tarantool garbage collector will not delete a file .. confval:: checkpoint_interval Since version 1.7.4. + The interval between actions by the checkpoint daemon, in seconds. If ``checkpoint_interval`` is set to a value greater than zero, and there is activity which causes change to a database, then the checkpoint daemon will @@ -76,7 +77,9 @@ The checkpoint daemon and the Tarantool garbage collector will not delete a file .. confval:: checkpoint_count - Since version 1.7.4. The maximum number of snapshots that may exist on the + Since version 1.7.4. + + The maximum number of snapshots that may exist on the :ref:`memtx_dir ` directory before the checkpoint daemon will delete old snapshots. If ``checkpoint_count`` equals zero, then the checkpoint daemon @@ -107,6 +110,7 @@ The checkpoint daemon and the Tarantool garbage collector will not delete a file .. confval:: checkpoint_wal_threshold Since version 2.1.2. + The threshold for the total size in bytes of all WAL files created since the last checkpoint. Once the configured threshold is exceeded, the WAL thread notifies the checkpoint daemon that it must make a new checkpoint and delete old WAL files. diff --git a/doc/reference/configuration/cfg_storage.rst b/doc/reference/configuration/cfg_storage.rst index 5d88d3db28..78d1e624d5 100644 --- a/doc/reference/configuration/cfg_storage.rst +++ b/doc/reference/configuration/cfg_storage.rst @@ -20,6 +20,7 @@ .. confval:: memtx_memory Since version 1.7.4. + How much memory Tarantool allocates to actually store tuples. When the limit is reached, :ref:`INSERT ` or :ref:`UPDATE ` requests begin failing with @@ -33,13 +34,14 @@ | Default: 256 * 1024 * 1024 = 268435456 bytes | Minimum: 33554432 bytes (32 MB) | Environment variable: TT_MEMTX_MEMORY - | Dynamic: **yes** but it cannot be decreased + | Dynamic: yes but it cannot be decreased .. _cfg_storage-memtx_max_tuple_size: .. confval:: memtx_max_tuple_size Since version 1.7.4. + Size of the largest allocation unit, for the memtx storage engine. It can be increased if it is necessary to store large tuples. See also: :ref:`vinyl_max_tuple_size `. @@ -47,13 +49,14 @@ | Type: integer | Default: 1024 * 1024 = 1048576 bytes | Environment variable: TT_MEMTX_MAX_TUPLE_SIZE - | Dynamic: **yes** + | Dynamic: yes .. _cfg_storage-memtx_min_tuple_size: .. confval:: memtx_min_tuple_size Since version 1.7.4. + Size of the smallest allocation unit. It can be decreased if most of the tuples are very small. The value must be between 8 and 1048280 inclusive. @@ -68,6 +71,7 @@ .. confval:: memtx_allocator Since version :doc:`2.10.0 `. + Specifies the allocator used for memtx tuples. The possible values are ``system`` and ``small``: @@ -104,6 +108,7 @@ .. confval:: slab_alloc_granularity Since version :doc:`2.8.1 `. + Specifies the granularity (in bytes) of memory allocation in the :ref:`small allocator `. The value of ``slab_alloc_granularity`` should be a power of two and should be greater than or equal to 4. Below are few recommendations on how to adjust the ``slab_alloc_granularity`` value: @@ -125,6 +130,7 @@ .. confval:: vinyl_bloom_fpr Since version 1.7.4. + Bloom filter false positive rate -- the suitable probability of the `bloom filter `_ to give a wrong result. @@ -147,13 +153,15 @@ | Type: integer | Default: 128 * 1024 * 1024 = 134217728 bytes | Environment variable: TT_VINYL_CACHE - | Dynamic: **yes** + | Dynamic: yes .. _cfg_storage-vinyl_max_tuple_size: .. confval:: vinyl_max_tuple_size - Since version 1.7.5. Size of the largest allocation unit, + Since version 1.7.5. + + Size of the largest allocation unit, for the vinyl storage engine. It can be increased if it is necessary to store large tuples. See also: :ref:`memtx_max_tuple_size `. @@ -167,18 +175,21 @@ .. confval:: vinyl_memory - Since version 1.7.4. The maximum number of in-memory bytes that vinyl uses. + Since version 1.7.4. + + The maximum number of in-memory bytes that vinyl uses. | Type: integer | Default: 128 * 1024 * 1024 = 134217728 bytes | Environment variable: TT_VINYL_MEMORY - | Dynamic: **yes** but it cannot be decreased + | Dynamic: yes but it cannot be decreased .. _cfg_storage-vinyl_page_size: .. confval:: vinyl_page_size Since version 1.7.4. + Page size. Page is a read/write unit for vinyl disk operations. The ``vinyl_page_size`` setting is a default value for one of the options in the :ref:`Options for space_object:create_index() ` chart. @@ -193,6 +204,7 @@ .. confval:: vinyl_range_size Since version 1.7.4. + The default maximum range size for a vinyl index, in bytes. The maximum range size affects the decision whether to :ref:`split ` a range. @@ -219,6 +231,7 @@ .. confval:: vinyl_run_count_per_level Since version 1.7.4. + The maximal number of runs per level in vinyl LSM tree. If this number is exceeded, a new level is created. The ``vinyl_run_count_per_level`` setting is a default value for one of the @@ -234,6 +247,7 @@ .. confval:: vinyl_run_size_ratio Since version 1.7.4. + Ratio between the sizes of different levels in the LSM tree. The ``vinyl_run_size_ratio`` setting is a default value for one of the options in the :ref:`Options for space_object:create_index() ` chart. @@ -248,6 +262,7 @@ .. confval:: vinyl_read_threads Since version 1.7.5. + The maximum number of read threads that vinyl can use for some concurrent operations, such as I/O and compression. @@ -261,6 +276,7 @@ .. confval:: vinyl_write_threads Since version 1.7.5. + The maximum number of write threads that vinyl can use for some concurrent operations, such as I/O and compression.