[pbs-devel] [PATCH proxmox-backup v2 4/5] docs: add documentation about the 'sync-level' tuning

[Matthias Heiserer]

On 07.10.2022 13:54, Dominik Csapak wrote:
> Signed-off-by: Dominik Csapak <d.csapak at proxmox.com>
> ---
>   docs/storage.rst | 36 ++++++++++++++++++++++++++++++++++++
>   1 file changed, 36 insertions(+)
> 
> diff --git a/docs/storage.rst b/docs/storage.rst
> index 1909bd84..d7e19ec1 100644
> --- a/docs/storage.rst
> +++ b/docs/storage.rst
> @@ -338,3 +338,39 @@ and only available on the CLI:
>   
>     # proxmox-backup-manager datastore update <storename> --tuning 'chunk-order=none'
>   
> +* ``sync-level``: Datastore fsync level:
> +
> +  You can set the level of syncing on the datastore for chunks, which influences
> +  the crash resistancy of backups in case of a powerloss or hard shutoff.
> +  There are currently three levels:
> +
> +  - `none` (default): Does not do any syncing when writing chunks. This is fast
> +    and normally ok, since the kernel eventually flushes writes onto the disk.
> +    The kernel sysctls `dirty_expire_centisecs` and `dirty_writeback_centisecs`
> +    are used to tune that behaviour, while the default is to flush old data
> +    after ~30s.
> +
> +  - `filesystem` : This triggers a ``syncfs(2)`` after a backup, but before
> +    the task returns `OK`. This way it is ensured that the written backups
> +    are on disk. This is a good balance between speed and consistency,.
> +    Note that the underlying storage device sitll needs to protect itself against
typo: still
> +    powerloss to flush its internal ephemeral caches to the permanent storage layer.
> +
> +  - `file` With this mode, a fsync is triggered on every chunk insertion, which
> +    makes sure each and every chunk reaches the disk as soon as possible. While
> +    this reaches the hightest level of consistency, for many storages (especially
typo: highest
> +    slower ones) this comes at the cost of speed. For many users the `filesystem`
> +    mode is better suited, but for very fast storages this mode can be ok.
> +
> +  This can be set with:
> +
> +.. code-block:: console
> +
> +  # proxmox-backup-manager datastore update <storename> --tuning 'sync-level=filesystem'
> +
> +If you want to set multiple tuning options simultaniously, you can seperate them
typo: simultaneously
> +with a comma, like this:
> +
> +.. code-block:: console
> +
> +  # proxmox-backup-manager datastore update <storename> --tuning 'sync-level=filesystem,chunk-order=none'