From c1319f712777bdbb715d7a8953ee14662323e2db Mon Sep 17 00:00:00 2001 From: andreyaksenov Date: Fri, 19 Jan 2024 14:48:29 +0300 Subject: [PATCH 1/5] Add box.cfg settings: flight recorder --- .../configuration/cfg_flight_recorder.rst | 157 ++++++++++++++++++ doc/reference/configuration/index.rst | 5 + 2 files changed, 162 insertions(+) create mode 100644 doc/reference/configuration/cfg_flight_recorder.rst diff --git a/doc/reference/configuration/cfg_flight_recorder.rst b/doc/reference/configuration/cfg_flight_recorder.rst new file mode 100644 index 0000000000..364f6588f6 --- /dev/null +++ b/doc/reference/configuration/cfg_flight_recorder.rst @@ -0,0 +1,157 @@ +.. _cfg_flight_recorder: + +.. admonition:: Enterprise Edition + :class: fact + + The flight recorder is available in the `Enterprise Edition `_ only. + +* :ref:`flightrec_enabled ` +* :ref:`flightrec_logs_size ` +* :ref:`flightrec_logs_max_msg_size ` +* :ref:`flightrec_logs_log_level ` +* :ref:`flightrec_metrics_period ` +* :ref:`flightrec_metrics_interval ` +* :ref:`flightrec_requests_size ` +* :ref:`flightrec_requests_max_req_size ` +* :ref:`flightrec_requests_max_res_size ` + + +.. _cfg_flightrec_enabled: + +.. confval:: flightrec_enabled + + Since :doc:`2.11.0 `. + + Enable the :ref:`flight recorder `. + + | Type: boolean + | Default: false + | Environment variable: TT_FLIGHTREC_ENABLED + | Dynamic: yes + + +.. _cfg_flightrec_logs_size: + +.. confval:: flightrec_logs_size + + Since :doc:`2.11.0 `. + + Specifies the size (in bytes) of the log storage. + You can set this option to ``0`` to disable the log storage. + + | Type: integer + | Default: 10485760 + | Environment variable: TT_FLIGHTREC_LOGS_SIZE + + +.. _cfg_flightrec_logs_max_msg_size: + +.. confval:: flightrec_logs_max_msg_size + + Since :doc:`2.11.0 `. + + Specifies the maximum size (in bytes) of the log message. + The log message is truncated if its size exceeds this limit. + + | Type: integer + | Default: 4096 + | Maximum: 16384 + | Environment variable: TT_FLIGHTREC_LOGS_MAX_MSG_SIZE + + +.. _cfg_flightrec_logs_log_level: + +.. confval:: flightrec_logs_log_level + + Since :doc:`2.11.0 `. + + Specifies the level of detail the log has. + You can learn more about log levels from the :ref:`log_level ` + option description. + Note that the ``flightrec_logs_log_level`` value might differ from ``log_level``. + + | Type: integer + | Default: 6 + | Environment variable: TT_FLIGHTREC_LOGS_LOG_LEVEL + + +.. _cfg_flightrec_metrics_period: + +.. confval:: flightrec_metrics_period + + Since :doc:`2.11.0 `. + + Specifies the time period (in seconds) that defines how long metrics are stored from the moment of dump. + So, this value defines how much historical metrics data is collected up to the moment of crash. + The frequency of metric dumps is defined by :ref:`flightrec_metrics_interval `. + + | Type: integer + | Default: 180 + | Environment variable: TT_FLIGHTREC_METRICS_PERIOD + + +.. _cfg_flightrec_metrics_interval: + +.. confval:: flightrec_metrics_interval + + Since :doc:`2.11.0 `. + + Specifies the time interval (in seconds) that defines the frequency of dumping metrics. + This value shouldn't exceed :ref:`flightrec_metrics_period `. + + .. NOTE:: + + Given that the average size of a metrics entry is 2 kB, + you can estimate the size of the metrics storage as follows: + + .. code-block:: console + + (flightrec_metrics_period / flightrec_metrics_interval) * 2 kB + + | Type: number + | Default: 1.0 + | Minimum: 0.001 + | Environment variable: TT_FLIGHTREC_METRICS_INTERVAL + + +.. _cfg_flightrec_requests_size: + +.. confval:: flightrec_requests_size + + Since :doc:`2.11.0 `. + + Specifies the size (in bytes) of storage for the request and response data. + You can set this parameter to ``0`` to disable a storage of requests and responses. + + | Type: integer + | Default: 10485760 + | Environment variable: TT_FLIGHTREC_REQUESTS_SIZE + + + +.. _cfg_flightrec_requests_max_req_size: + +.. confval:: flightrec_requests_max_req_size + + Since :doc:`2.11.0 `. + + Specifies the maximum size (in bytes) of a request entry. + A request entry is truncated if this size is exceeded. + + | Type: integer + | Default: 16384 + | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_REQ_SIZE + + +.. _cfg_flightrec_requests_max_res_size: + +.. confval:: flightrec_requests_max_res_size + + Since :doc:`2.11.0 `. + + Specifies the maximum size (in bytes) of a response entry. + A response entry is truncated if this size is exceeded. + + | Type: integer + | Default: 16384 + | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_RES_SIZE diff --git a/doc/reference/configuration/index.rst b/doc/reference/configuration/index.rst index 1840ce5ecc..4bf67bc3cb 100644 --- a/doc/reference/configuration/index.rst +++ b/doc/reference/configuration/index.rst @@ -60,6 +60,11 @@ Logging .. include:: cfg_logging.rst +Flight recorder +--------------- + +.. include:: cfg_flight_recorder.rst + Feedback -------- From 5d5267746c8eee6139bc85d924eeeeeb06efa1ef Mon Sep 17 00:00:00 2001 From: andreyaksenov Date: Fri, 19 Jan 2024 15:09:56 +0300 Subject: [PATCH 2/5] Add box.cfg settings: authentication --- .../configuration/cfg_authentication.rst | 227 ++++++++++++++++++ doc/reference/configuration/index.rst | 5 + 2 files changed, 232 insertions(+) create mode 100644 doc/reference/configuration/cfg_authentication.rst diff --git a/doc/reference/configuration/cfg_authentication.rst b/doc/reference/configuration/cfg_authentication.rst new file mode 100644 index 0000000000..5cb8bdcae7 --- /dev/null +++ b/doc/reference/configuration/cfg_authentication.rst @@ -0,0 +1,227 @@ +.. _cfg_authentication: + +.. admonition:: Enterprise Edition + :class: fact + + Authentication features are supported by the `Enterprise Edition `_ only. + +* :ref:`auth_delay ` +* :ref:`auth_retries ` +* :ref:`auth_type ` +* :ref:`disable_guest ` +* :ref:`password_min_length ` +* :ref:`password_enforce_uppercase ` +* :ref:`password_enforce_lowercase ` +* :ref:`password_enforce_digits ` +* :ref:`password_enforce_specialchars ` +* :ref:`password_lifetime_days ` +* :ref:`password_history_length ` + + +.. _cfg_auth_delay: + +.. confval:: auth_delay + + Since :doc:`2.11.0 `. + + Specifies a period of time (in seconds) that a specific user should wait + for the next attempt after failed authentication. + + With the configuration below, Tarantool refuses the authentication attempt if the previous + attempt was less than 5 seconds ago. + + .. code-block:: lua + + box.cfg{ auth_delay = 5 } + + + | Type: number + | Default: 0 + | Environment variable: TT_AUTH_DELAY + | Dynamic: yes + +.. _cfg_auth_retries: + +.. confval:: auth_retries + + Since :doc:`3.0.0 `. + + Specify the maximum number of authentication retries allowed before ``auth_delay`` is enforced. + The default value is 0, which means ``auth_delay`` is enforced after the first failed authentication attempt. + + The retry counter is reset after ``auth_delay`` seconds since the first failed attempt. + For example, if a client tries to authenticate fewer than ``auth_retries`` times within ``auth_delay`` seconds, no authentication delay is enforced. + The retry counter is also reset after any successful authentication attempt. + + | Type: number + | Default: 0 + | Environment variable: TT_AUTH_RETRIES + | Dynamic: yes + + +.. _cfg_auth_type: + +.. confval:: auth_type + + Since :doc:`2.11.0 `. + + Specify an authentication protocol: + + - 'chap-sha1': use the `CHAP `_ protocol to authenticate users with ``SHA-1`` hashing applied to :ref:`passwords `. + - 'pap-sha256': use `PAP `_ authentication with the ``SHA256`` hashing algorithm. + + For new users, the :doc:`box.schema.user.create ` method + will generate authentication data using ``PAP-SHA256``. + For existing users, you need to reset a password using + :doc:`box.schema.user.passwd ` + to use the new authentication protocol. + + | Type: string + | Default value: 'chap-sha1' + | Environment variable: TT_AUTH_TYPE + | Dynamic: yes + + +.. _cfg_disable_guest: + +.. confval:: disable_guest + + Since :doc:`2.11.0 `. + + If **true**, disables access over remote connections + from unauthenticated or :ref:`guest access ` users. + This option affects both + :doc:`net.box ` and + :ref:`replication ` connections. + + | Type: boolean + | Default: false + | Environment variable: TT_DISABLE_GUEST + | Dynamic: yes + +.. _cfg_password_min_length: + +.. confval:: password_min_length + + Since :doc:`2.11.0 `. + + Specifies the minimum number of characters for a password. + + The following example shows how to set the minimum password length to 10. + + .. code-block:: lua + + box.cfg{ password_min_length = 10 } + + | Type: integer + | Default: 0 + | Environment variable: TT_PASSWORD_MIN_LENGTH + | Dynamic: yes + + +.. _cfg_password_enforce_uppercase: + +.. confval:: password_enforce_uppercase + + Since :doc:`2.11.0 `. + + If **true**, a password should contain uppercase letters (A-Z). + + | Type: boolean + | Default: false + | Environment variable: TT_PASSWORD_ENFORCE_UPPERCASE + | Dynamic: yes + + +.. _cfg_password_enforce_lowercase: + +.. confval:: password_enforce_lowercase + + Since :doc:`2.11.0 `. + + If **true**, a password should contain lowercase letters (a-z). + + | Type: boolean + | Default: false + | Environment variable: TT_PASSWORD_ENFORCE_LOWERCASE + | Dynamic: yes + + +.. _cfg_password_enforce_digits: + +.. confval:: password_enforce_digits + + Since :doc:`2.11.0 `. + + If **true**, a password should contain digits (0-9). + + | Type: boolean + | Default: false + | Environment variable: TT_PASSWORD_ENFORCE_DIGITS + | Dynamic: yes + + +.. _cfg_password_enforce_specialchars: + +.. confval:: password_enforce_specialchars + + Since :doc:`2.11.0 `. + + If **true**, a password should contain at least one special character (such as ``&|?!@$``). + + | Type: boolean + | Default: false + | Environment variable: TT_PASSWORD_ENFORCE_SPECIALCHARS + | Dynamic: yes + + +.. _cfg_password_lifetime_days: + +.. confval:: password_lifetime_days + + Since :doc:`2.11.0 `. + + Specifies the maximum period of time (in days) a user can use the same password. + When this period ends, a user gets the "Password expired" error on a login attempt. + To restore access for such users, use :doc:`box.schema.user.passwd `. + + .. note:: + + The default 0 value means that a password never expires. + + The example below shows how to set a maximum password age to 365 days. + + .. code-block:: lua + + box.cfg{ password_lifetime_days = 365 } + + | Type: integer + | Default: 0 + | Environment variable: TT_PASSWORD_LIFETIME_DAYS + | Dynamic: yes + + +.. _cfg_password_history_length: + +.. confval:: password_history_length + + Since :doc:`2.11.0 `. + + Specifies the number of unique new user passwords before an old password can be reused. + + In the example below, a new password should differ from the last three passwords. + + .. code-block:: lua + + box.cfg{ password_history_length = 3 } + + | Type: integer + | Default: 0 + | Environment variable: TT_PASSWORD_HISTORY_LENGTH + | Dynamic: yes + + .. note:: + Tarantool uses the ``auth_history`` field in the + :doc:`box.space._user ` + system space to store user passwords. + diff --git a/doc/reference/configuration/index.rst b/doc/reference/configuration/index.rst index 4bf67bc3cb..55b828cb4f 100644 --- a/doc/reference/configuration/index.rst +++ b/doc/reference/configuration/index.rst @@ -60,6 +60,11 @@ Logging .. include:: cfg_logging.rst +Authentication +-------------- + +.. include:: cfg_authentication.rst + Flight recorder --------------- From b37accf1e795075b75dc9facb3ae0da7b380e0f4 Mon Sep 17 00:00:00 2001 From: andreyaksenov Date: Fri, 19 Jan 2024 15:22:29 +0300 Subject: [PATCH 3/5] Add box.cfg settings: new WAL settings --- .../cfg_binary_logging_snapshots.rst | 77 ++++++++++++++++++- 1 file changed, 75 insertions(+), 2 deletions(-) diff --git a/doc/reference/configuration/cfg_binary_logging_snapshots.rst b/doc/reference/configuration/cfg_binary_logging_snapshots.rst index 3d0bcdb1b1..5aea18c9ec 100644 --- a/doc/reference/configuration/cfg_binary_logging_snapshots.rst +++ b/doc/reference/configuration/cfg_binary_logging_snapshots.rst @@ -5,12 +5,15 @@ * :ref:`wal_dir_rescan_delay ` * :ref:`wal_queue_max_size ` * :ref:`wal_cleanup_delay ` +* :ref:`wal_ext ` +* :ref:`secure_erasing ` .. _cfg_binary_logging_snapshots-force_recovery: .. confval:: force_recovery Since version 1.7.4. + If ``force_recovery`` equals true, Tarantool tries to continue if there is an error while reading a :ref:`snapshot file` (at server instance start) or a :ref:`write-ahead log file` @@ -31,6 +34,7 @@ .. confval:: wal_max_size Since version 1.7.4. + The maximum number of bytes in a single write-ahead log file. When a request would cause an .xlog file to become larger than ``wal_max_size``, Tarantool creates another WAL file. @@ -45,6 +49,7 @@ .. confval:: snap_io_rate_limit Since version 1.4.9. + Reduce the throttling effect of :doc:`box.snapshot() ` on INSERT/UPDATE/DELETE performance by setting a limit on how many megabytes per second it can write to disk. The same can be @@ -64,7 +69,9 @@ .. confval:: wal_mode - Since version 1.6.2. Specify fiber-WAL-disk synchronization mode as: + Since version 1.6.2. + + Specify fiber-WAL-disk synchronization mode as: * ``none``: write-ahead log is not maintained. A node with ``wal_mode = none`` can't be replication master; @@ -83,6 +90,7 @@ .. confval:: wal_dir_rescan_delay Since version 1.6.2. + Number of seconds between periodic scans of the write-ahead-log file directory, when checking for changes to write-ahead-log files for the sake of :ref:`replication ` or :ref:`hot standby `. @@ -97,6 +105,7 @@ .. confval:: wal_queue_max_size Since version :doc:`2.8.1 `. + The size of the queue (in bytes) used by a :ref:`replica ` to submit new transactions to a :ref:`write-ahead log` (WAL). This option helps limit the rate at which a replica submits transactions to the WAL. @@ -118,6 +127,7 @@ .. confval:: wal_cleanup_delay Since version :doc:`2.6.3 `. + The delay (in seconds) used to prevent the :ref:`Tarantool garbage collector ` from immediately removing :ref:`write-ahead log` files after a node restart. This delay eliminates possible erroneous situations when the master deletes WALs @@ -136,4 +146,67 @@ | Type: number | Default: 14400 seconds | Environment variable: TT_WAL_CLEANUP_DELAY - | Dynamic: **yes** \ No newline at end of file + | Dynamic: **yes** + + +.. _cfg_binary_logging_snapshots-wal_ext: + +.. confval:: wal_ext + + Since version :doc:`2.11.0 `. + + (Enterprise Edition only) Allows you to add auxiliary information to each :ref:`write-ahead log ` record. + For example, you can enable storing an old and new tuple for each CRUD operation performed. + This information might be helpful for implementing a CDC (Change Data Capture) utility that transforms a data replication stream. + + You can enable storing old and new tuples as follows: + + * Set the ``old`` and ``new`` options to ``true`` to store old and new tuples in a write-ahead log for all spaces. + + .. code-block:: lua + + box.cfg { + wal_ext = { old = true, new = true } + } + + * To adjust these options for specific spaces, use the ``spaces`` option. + + .. code-block:: lua + + box.cfg { + wal_ext = { + old = true, new = true, + spaces = { + space1 = { old = false }, + space2 = { new = false } + } + } + } + + + The configuration for specific spaces has priority over the global configuration, + so only new tuples are added to the log for ``space1`` and only old tuples for ``space2``. + + Note that records with additional fields are :ref:`replicated ` as follows: + + * If a replica doesn't support the extended format configured on a master, auxiliary fields are skipped. + * If a replica and master have different configurations for WAL records, a master's configuration is ignored. + + | Type: map + | Default: nil + | Environment variable: TT_WAL_EXT + + +.. _cfg_binary_logging_secure_erasing: + +.. confval:: secure_erasing + + Since version :doc:`3.0.0 `. + + (Enterprise Edition only) If **true**, forces Tarantool to overwrite a data file a few times before deletion to render recovery of a deleted file impossible. + The option applies to both ``.xlog`` and ``.snap`` files as well as Vinyl data files. + + | Type: boolean + | Default: false + | Environment variable: TT_SECURE_ERASING + | Dynamic: **yes** From 19fa93241895779f0f69f28fe2b39d8dcd8006ca Mon Sep 17 00:00:00 2001 From: andreyaksenov Date: Fri, 19 Jan 2024 16:08:14 +0300 Subject: [PATCH 4/5] Add box.cfg settings: bootstrap_leader --- .../configuration/cfg_replication.rst | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/doc/reference/configuration/cfg_replication.rst b/doc/reference/configuration/cfg_replication.rst index 6ac7e48e3c..7e5bc501a4 100644 --- a/doc/reference/configuration/cfg_replication.rst +++ b/doc/reference/configuration/cfg_replication.rst @@ -1,5 +1,6 @@ * :ref:`replication ` * :ref:`replication_anon ` +* :ref:`bootstrap_leader ` * :ref:`bootstrap_strategy ` * :ref:`replication_connect_timeout ` * :ref:`replication_connect_quorum ` @@ -206,6 +207,31 @@ | Dynamic: **yes** +.. _cfg_replication-bootstrap_leader: + +.. confval:: bootstrap_leader + + Since :doc:`3.0.0 `. + + A bootstrap leader for a replica set. + You can pass a bootstrap leader's URI, UUID, or name. + + To specify a bootstrap leader manually, you need to set :ref:`bootstrap_strategy ` to ``config``, for example: + + .. code-block:: lua + + box.cfg{ + bootstrap_strategy = 'config', + bootstrap_leader = '127.0.0.1:3301', + replication = {'127.0.0.1:3301'}, + } + + | Type: string + | Default: null + | Environment variable: TT_BOOTSTRAP_LEADER + | Dynamic: **yes** + + .. _cfg_replication-bootstrap_strategy: .. confval:: bootstrap_strategy @@ -221,6 +247,11 @@ In the case of 4 or 5 nodes, at least 3 connected instances are required. Moreover, a bootstrap leader fails to boot unless every connected node has chosen it as a bootstrap leader. + * ``config``: use the specified node to bootstrap a replica set. + To specify the bootstrap leader, use the :ref:`bootstrap_leader ` option. + + * ``supervised``: a bootstrap leader isn't chosen automatically but should be appointed using :ref:`box.ctl.make_bootstrap_leader() ` on the desired node. + * ``legacy`` (deprecated since :doc:`2.11.0 `): a node requires the :ref:`replication_connect_quorum ` number of other nodes to be connected. This option is added to keep the compatibility with the current versions of Cartridge and might be removed in the future. From 8de2e421f83e6b44ffb934c9e11ecfcea9d8810d Mon Sep 17 00:00:00 2001 From: andreyaksenov Date: Fri, 19 Jan 2024 17:08:55 +0300 Subject: [PATCH 5/5] Add box.cfg settings: update per review --- .../configuration/cfg_binary_logging_snapshots.rst | 5 +++-- doc/reference/configuration/cfg_flight_recorder.rst | 8 ++++++++ 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/doc/reference/configuration/cfg_binary_logging_snapshots.rst b/doc/reference/configuration/cfg_binary_logging_snapshots.rst index 5aea18c9ec..39e95ec7fa 100644 --- a/doc/reference/configuration/cfg_binary_logging_snapshots.rst +++ b/doc/reference/configuration/cfg_binary_logging_snapshots.rst @@ -155,7 +155,7 @@ Since version :doc:`2.11.0 `. - (Enterprise Edition only) Allows you to add auxiliary information to each :ref:`write-ahead log ` record. + (**Enterprise Edition only**) Allows you to add auxiliary information to each :ref:`write-ahead log ` record. For example, you can enable storing an old and new tuple for each CRUD operation performed. This information might be helpful for implementing a CDC (Change Data Capture) utility that transforms a data replication stream. @@ -195,6 +195,7 @@ | Type: map | Default: nil | Environment variable: TT_WAL_EXT + | Dynamic: **yes** .. _cfg_binary_logging_secure_erasing: @@ -203,7 +204,7 @@ Since version :doc:`3.0.0 `. - (Enterprise Edition only) If **true**, forces Tarantool to overwrite a data file a few times before deletion to render recovery of a deleted file impossible. + (**Enterprise Edition only**) If **true**, forces Tarantool to overwrite a data file a few times before deletion to render recovery of a deleted file impossible. The option applies to both ``.xlog`` and ``.snap`` files as well as Vinyl data files. | Type: boolean diff --git a/doc/reference/configuration/cfg_flight_recorder.rst b/doc/reference/configuration/cfg_flight_recorder.rst index 364f6588f6..36c333db0d 100644 --- a/doc/reference/configuration/cfg_flight_recorder.rst +++ b/doc/reference/configuration/cfg_flight_recorder.rst @@ -42,6 +42,7 @@ | Type: integer | Default: 10485760 | Environment variable: TT_FLIGHTREC_LOGS_SIZE + | Dynamic: yes .. _cfg_flightrec_logs_max_msg_size: @@ -57,6 +58,7 @@ | Default: 4096 | Maximum: 16384 | Environment variable: TT_FLIGHTREC_LOGS_MAX_MSG_SIZE + | Dynamic: yes .. _cfg_flightrec_logs_log_level: @@ -73,6 +75,7 @@ | Type: integer | Default: 6 | Environment variable: TT_FLIGHTREC_LOGS_LOG_LEVEL + | Dynamic: yes .. _cfg_flightrec_metrics_period: @@ -88,6 +91,7 @@ | Type: integer | Default: 180 | Environment variable: TT_FLIGHTREC_METRICS_PERIOD + | Dynamic: yes .. _cfg_flightrec_metrics_interval: @@ -112,6 +116,7 @@ | Default: 1.0 | Minimum: 0.001 | Environment variable: TT_FLIGHTREC_METRICS_INTERVAL + | Dynamic: yes .. _cfg_flightrec_requests_size: @@ -126,6 +131,7 @@ | Type: integer | Default: 10485760 | Environment variable: TT_FLIGHTREC_REQUESTS_SIZE + | Dynamic: yes @@ -141,6 +147,7 @@ | Type: integer | Default: 16384 | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_REQ_SIZE + | Dynamic: yes .. _cfg_flightrec_requests_max_res_size: @@ -155,3 +162,4 @@ | Type: integer | Default: 16384 | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_RES_SIZE + | Dynamic: yes