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/cfg_binary_logging_snapshots.rst b/doc/reference/configuration/cfg_binary_logging_snapshots.rst index 3d0bcdb1b1..39e95ec7fa 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,68 @@ | 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 + | Dynamic: **yes** + + +.. _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** diff --git a/doc/reference/configuration/cfg_flight_recorder.rst b/doc/reference/configuration/cfg_flight_recorder.rst new file mode 100644 index 0000000000..36c333db0d --- /dev/null +++ b/doc/reference/configuration/cfg_flight_recorder.rst @@ -0,0 +1,165 @@ +.. _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 + | Dynamic: yes + + +.. _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 + | Dynamic: yes + + +.. _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 + | Dynamic: yes + + +.. _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 + | Dynamic: yes + + +.. _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 + | Dynamic: yes + + +.. _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 + | Dynamic: yes + + + +.. _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 + | Dynamic: yes + + +.. _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 + | Dynamic: yes 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. diff --git a/doc/reference/configuration/index.rst b/doc/reference/configuration/index.rst index 1840ce5ecc..55b828cb4f 100644 --- a/doc/reference/configuration/index.rst +++ b/doc/reference/configuration/index.rst @@ -60,6 +60,16 @@ Logging .. include:: cfg_logging.rst +Authentication +-------------- + +.. include:: cfg_authentication.rst + +Flight recorder +--------------- + +.. include:: cfg_flight_recorder.rst + Feedback --------