persistence: update topic and reference section

Author: xuniq

doc/book/admin/backups.rst

@@ -37,15 +37,15 @@ that are made after the last snapshot are incremental backups. Therefore taking
 a backup is a matter of copying the snapshot and WAL files.
 
 1. Use ``tar`` to make a (possibly compressed) copy of the latest .snap and .xlog
-   files on the :ref:`memtx_dir <cfg_basic-memtx_dir>` and
-   :ref:`wal_dir <cfg_basic-wal_dir>` directories.
+   files on the :ref:`snapshot.dir <configuration_reference_snapshot_dir>` and
+   :ref:`wal.dir <configuration_reference_wal_dir>` directories.
 
 2. If there is a security policy, encrypt the .tar file.
 
 3. Copy the .tar file to a safe place.
 
 Later, restoring the database is a matter of taking the .tar file and putting
-its contents back in the ``memtx_dir`` and ``wal_dir`` directories.
+its contents back in the ``snapshot.dir`` and ``wal.dir`` directories.
 
 .. _admin-backups-hot_backup_vinyl_memtx:
 

doc/code_snippets/snippets/config/instances.enabled/persistence/config.yaml

@@ -0,0 +1,30 @@
+wal:
+  ext:
+    new: true
+    old: true
+    spaces:
+      bands:
+        new: false
+  mode: 'write'
+  dir: ''
+  dir_rescan_delay: 3
+  cleanup_delay: 18000
+  max_size: 268435456
+
+snapshot:
+  dir:
+  snap_io_rate_limit:
+  by:
+    interval: 60
+    count: 10
+
+
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            iproto:
+              listen:
+              - uri: '127.0.0.1:3301'

doc/code_snippets/snippets/config/instances.enabled/persistence/instances.yml

@@ -0,0 +1 @@
+instance001:

doc/concepts/configuration.rst

@@ -429,7 +429,8 @@ When the limit is reached, ``INSERT`` or ``UPDATE`` requests fail with :ref:`ER_
 Snapshots and write-ahead logs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``snapshot.dir`` and ``wal.dir`` options can be used to configure directories for storing snapshots and write-ahead logs.
+The :ref:`snapshot.dir <configuration_reference_snapshot_dir>` and :ref:`wal.dir <configuration_reference_wal_dir>`
+options can be used to configure directories for storing snapshots and write-ahead logs.
 For example, you can place snapshots and write-ahead logs on different hard drives for better reliability.
 
 .. code-block:: yaml
@@ -450,6 +451,7 @@ To learn more about the persistence mechanism in Tarantool, see the :ref:`Persis
 
     configuration/configuration_etcd
     configuration/configuration_code
+    configuration/configuration_persistence
     configuration/configuration_connections
     configuration/configuration_authentication
     .. configuration/configuration_migrating

doc/concepts/configuration/configuration_persistence.rst

@@ -0,0 +1,65 @@
+..  _configuration_persistence:
+
+Persistence
+===========
+
+**Example on GitHub**: `persistence <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/persistence>`_
+
+To ensure data persistence, Tarantool provides the abilities to:
+
+*   record each data change request into a write-ahead log (WAL) file
+*   take snapshots that contain on-disk copy of the entire data set for a given moment
+
+During the recovery process, Tarantool can load the latest snapshot file and then read the requests from the WAL files,
+produced after this snapshot was made.
+
+..  _configuration_persistence_wal:
+
+Configure the write-ahead log
+-----------------------------
+
+..  _configuration_persistence_wal_mode:
+
+Set the WAL mode
+~~~~~~~~~~~~~~~~
+
+To be able to recover data in case of a possible instance restart, enable recording to the write-ahead log.
+To do it, set the :ref:`wal.mode <configuration_reference_wal_mode>` configuration option to ``write`` or ``fsync``:
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence/config.yaml
+    :language: yaml
+    :start-at: mode:
+    :end-at: 'write'
+    :dedent:
+
+An exclusion from this is when the instance is processing data that can be freely rejected.
+For example, when Tarantool is used for caching, WAL can be disabled to reduce i/o load.
+
+To turn the WAL writer off, set the ``wal.mode`` option to ``none``.
+
+..  _configuration_persistence_wal_dir:
+
+Specify a directory for WAL files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+
+..  _configuration_persistence_snapshot:
+
+Configure the snapshots
+-----------------------
+
+
+
+The :ref:`snapshot.by.interval <cfg_checkpoint_daemon-checkpoint_interval>` and
+:ref:`checkpoint_count <cfg_checkpoint_daemon-checkpoint_count>` configuration
+settings determine how long the intervals are, and how many snapshots should
+exist before deletions occur.
+-   One or several URIs used to listen for incoming requests.
+-   An URI used to advertise an instance to other cluster members. This URI lets other cluster members know how to connect to the current Tarantool instance.
+-   (Optional) SSL settings used to secure connections between instances.
+
+Configuring connection settings is also required to enable communication of a Tarantool cluster to external systems.
+For example, this might be administering cluster members using :ref:`tt <tt-cli>`, managing clusters using :ref:`Tarantool Cluster Manager <tcm>`, or using :ref:`connectors <index-box_connectors>` for different languages.
+
+This topic describes how to define connection settings in the :ref:`iproto <configuration_reference_iproto>` section of a YAML configuration.

doc/concepts/data_model/persistence.rst

@@ -12,7 +12,7 @@ In such case, Tarantool restores the data from WAL files
 by reading them and redoing the requests.
 This is called the "recovery process".
 You can change the timing of the WAL writer or turn it off by setting
-the :ref:`wal_mode <cfg_binary_logging_snapshots-wal_mode>`.
+the :ref:`wal.mode <configuration_reference_wal_mode>`.
 
 Tarantool also maintains a set of :ref:`snapshot files <internals-snapshot>`.
 These files contain an on-disk copy of the entire data set for a given moment.

doc/enterprise/flight_recorder.rst

@@ -17,8 +17,8 @@ to :ref:`crashing <admin-disaster_recovery>` a Tarantool instance.
 
 .. _enterprise-flight-recorder_enable:
 
-Enabling the flight recorder
-----------------------------
+Enable the flight recorder
+--------------------------
 
 The flight recorder is disabled by default and can be enabled and configured for
 a specific Tarantool instance.
@@ -33,7 +33,7 @@ configuration option to ``true``.
 
 
 After ``flightrec.enabled`` is set to ``true``, the flight recorder starts collecting data in the flight recording file  ``current.ttfr``.
-This file is stored in the ``snapshot.dir`` directory.
+This file is stored in the :ref:`snapshot.dir <configuration_reference_snapshot_dir>` directory.
 By default, the directory is ``var/lib/{{ instance_name }}/<file_name>.ttfr``.
 
 If the instance crashes and reboots, Tarantool rotates the flight recording:
@@ -49,8 +49,8 @@ Tarantool continues writing to the existing ``current.ttfr`` file after restart.
 
 .. _enterprise-flight-recorder_configure:
 
-Configuring a flight recorder
------------------------------
+Configure a flight recorder
+---------------------------
 
 When the flight recorder is enabled, you can set the options related to :ref:`logging <cfg_logging-log>`,
 :ref:`metrics <metrics-reference>`, and storing the :ref:`request and response <internals-requests_responses>` data.

doc/enterprise/wal_extensions.rst

@@ -1,4 +1,4 @@
-.. _wal_extensions:
+..  _wal_extensions:
 
 WAL extensions
 ==============
@@ -8,47 +8,49 @@ For example, you can enable storing an old and new tuple for each CRUD operation
 This information might be helpful for implementing a CDC (Change Data Capture) utility
 that transforms a data replication stream.
 
-.. _wal_extensions_configuration:
+..  _wal_extensions_configuration:
 
 Configuration
 -------------
 
-To configure WAL extensions, use the ``wal.ext`` :ref:`configuration property <configuration_reference_wal>`.
-Inside the ``wal_ext`` block, you can enable storing old and new tuples as follows:
+WAL extensions are disabled by default.
+To configure them, use the :ref:`wal.ext.* <configuration_reference_wal_ext>` configuration options.
+Inside the ``wal.ext`` block, 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.
+*   To store old and new tuples in a write-ahead log for all spaces, set the
+    :ref:`wal.ext.old <configuration_reference_wal_ext_old>` and `wal.ext.new <configuration_reference_wal_ext_new>`
+    options to ``true``:
 
-    ..  code-block:: lua
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence/config.yaml
+        :language: yaml
+        :start-at: wal:
+        :end-at: old: true
+        :dedent:
 
-        box.cfg {
-            wal_ext = { old = true, new = true }
-        }
+*   To adjust these options for specific spaces, specify the :ref:`wal.ext.spaces <configuration_reference_wal_ext_spaces>` option:
 
-*   To adjust these options for specific spaces, use the ``spaces`` option.
+    ..  code-block:: yaml
 
-    ..  code-block:: lua
+        wal:
+          ext:
+            old: true
+            new: true
+            spaces:
+              space1:
+                old: false
+              space2:
+                new: false
 
-        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``.
+    The configuration for specific spaces has priority over the configuration in the ``wal.ext.new`` and ``wal.ext.old``
+    options.
+    It means that 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 <replication-architecture>` 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.
 
-
-.. _wal_extensions_example:
+..  _wal_extensions_example:
 
 Example
 -------