Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Timeouts - Issue #507 #508

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Timeouts - Issue #507 #508

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3ec9a5b
Issue #507
kirjaamo Nov 14, 2024
b9e8a0d
Language improvements.
kirjaamo Nov 14, 2024
1c2e3bd
sst_special_dirs marked as deprecated.
kirjaamo Nov 15, 2024
50e84ed
Language improved
kirjaamo Nov 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 43 additions & 45 deletions galeracluster/source/documentation/xtrabackup-options.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
:title: XtraBackup-v2 Parameters
:description:
:language: en-US
:keywords: galera cluster, xtradb, xtrabackup, parameters
:keywords: galera cluster, xtradb, xtrabackup-v2, parameters
:copyright: Codership Oy, 2014 - 2024. All Rights Reserved.


Expand Down Expand Up @@ -54,7 +54,7 @@
XtraBackup-v2 Parameters
======================

When using ``xtrabackup-v2`` as your :term:`State Snapshot Transfer` method, you can fine tune how the script operates using the ``[sst]`` unit in the ``my.cnf`` configuration file.
When using ``xtrabackup-v2`` as your :term:`State Snapshot Transfer` method, you can fine-tune how the script operates using the ``[sst]`` unit in the ``my.cnf`` configuration file.

.. code-block:: ini

Expand All @@ -71,31 +71,32 @@ When using ``xtrabackup-v2`` as your :term:`State Snapshot Transfer` method, you
tcert="/path/to/cert.pem"
tca="/path/to/ca.pem"

Bear in mind, some XtraBackup parameters require that you match the configuration on donor and joiner nodes, (as designated in the table below).
Bear in mind, some ``XtraBackup-v2`` parameters require that you match the configuration on donor and joiner nodes, as designated in the table below.


.. csv-table::
:class: doc-options
:header: "Option", "Default", "Match"
:widths: 30, 20, 20

":ref:`compressor <xtra-compressor>`", "", ""
":ref:`cpat <xtra-cpat>`", "``0``", ""
":ref:`decompressor <xtra-decompressor>`", "", ""
":ref:`compressor <xtra-compressor>`", "", "No"
":ref:`compact <xtra-compact>`", "OFF", "No"
":ref:`cpat <xtra-cpat>`", "``0``", "No"
":ref:`decompressor <xtra-decompressor>`", "", "No"
":ref:`encrypt <xtra-encrypt>`", "``0``", "Yes"
":ref:`encrypt-algo <xtra-encrypt-algo>`", "", ""
":ref:`progress <xtra-progress>`", "", ""
":ref:`rebuild <xtra-rebuild>`", "``0``", ""
":ref:`rlimit <xtra-rlimit>`", "", ""
":ref:`sst_special_dirs <xtra-sst_special_dirs>`", "``1``", ""
":ref:`sockopt <xtra-sockopt>`", "", ""
":ref:`encrypt-algo <xtra-encrypt-algo>`", "0", "No"
":ref:`progress <xtra-progress>`", "", "No"
":ref:`rebuild <xtra-rebuild>`", "``OFF``", "No"
":ref:`rlimit <xtra-rlimit>`", "", "No"
":ref:`sockopt <xtra-sockopt>`", "", "No"
":ref:`sst_special_dirs <xtra-sst_special_dirs>`", "``1``", "No"
":ref:`streamfmt <xtra-streamfmt>`", "``xbstream``", "Yes"
":ref:`tca <xtra-tca>`", "", ""
":ref:`tcert <xtra-tcert>`", "", ""
":ref:`time <xtra-time>`", "``0``", ""
":ref:`tca <xtra-tca>`", "", "No"
":ref:`tcert <xtra-tcert>`", "", "No"
":ref:`time <xtra-time>`", "``OFF``", "No"
":ref:`transferfmt <xtra-transferfmt>`", "``socat``", "Yes"
":ref:`joiner_timeout <xtra-joiner_timeout>`", "``60``", ""
":ref:`donor_timeout <xtra-donor_timeout>`", "``10``", ""
":ref:`joiner_timeout <xtra-joiner_timeout>`", "``60``", "No"
":ref:`donor_timeout <xtra-donor_timeout>`", "``10``", "No"


.. _`xtra-compressor`:
Expand Down Expand Up @@ -238,7 +239,7 @@ Defines the SSL encryption type the node uses for XtraBackup state transfers.
"**Permitted Values**", "Type:", "Integer"
"", "Default Value:", "``0``"

When using the :ref:`encrypt <xtra-encrypt>` parameter in both the ``[xtrabackup]`` and ``[sst]`` units, there is a potential issue in it having different meanings according to the unit under which it occurs. That is, in ``[xtrabackup]``, it turns encryption on while in ``[sst]`` it both turns it on as specifies the algorithm.
When using the :ref:`encrypt <xtra-encrypt>` parameter in both the ``[xtrabackup]`` and ``[sst]`` units, there is a potential issue in it having different meanings according to the unit under which it occurs. That is, in ``[xtrabackup]``, it turns encryption on while in ``[sst]`` it both turns it on and specifies the algorithm.

In the event that you need to clarify the meaning, this parameter allows you to define the encryption algorithm separately from turning encryption on. It is only read in the event that :ref:`encrypt <xtra-encrypt>` is set to ``1``

Expand Down Expand Up @@ -312,12 +313,28 @@ Defines the rate limit for the donor node.
"**Permitted Values**", "Type:", "Integer"
"", "Default Value:", ""

This parameter allows you to definite the rate-limit the donor node. This allows you to keep state transfers from blocking regular cluster operations.
This parameter allows you to define the rate-limit for the donor node. This allows you to keep state transfers from blocking regular cluster operations.

.. code-block:: ini

rlimit=300M

.. _`xtra-sockopt`:
.. rst-class:: section-heading
.. rubric:: ``sockopt``

Defines socket options.

.. csv-table::
:class: doc-options
:stub-columns: 1

"**System Variable**", "Name:", "``sockopt``"
"", "Match:", "No"
"**Permitted Values**", "Type:", "String"
"", "Default Value:", ""

This parameter allows you to define one or more socket options for XtraBackup using the Socat transfer format.

.. _`xtra-sst_special_dirs`:
.. rst-class:: section-heading
Expand Down Expand Up @@ -346,25 +363,6 @@ This parameter enables support for ``innodb_data_home_dir`` and ``innodb_log_hom
[sst]
sst_special_dirs=TRUE


.. _`xtra-sockopt`:
.. rst-class:: section-heading
.. rubric:: ``sockopt``

Defines socket options.

.. csv-table::
:class: doc-options
:stub-columns: 1

"**System Variable**", "Name:", "``sockopt``"
"", "Match:", "No"
"**Permitted Values**", "Type:", "String"
"", "Default Value:", ""

This parameter allows you to define one or more socket options for XtraBackup using the Socat transfer format.


.. _`xtra-streamfmt`:
.. rst-class:: section-heading
.. rubric:: ``streamfmt``
Expand All @@ -381,7 +379,7 @@ Defines the stream formatting utility.
"", "Default Value:", "``xbstream``"
"", "Valid Values:", "``tar``; ``xbstream``"

This parameter defines the utility the node uses to archive the node state before the transfer is sent and how to unarchive the state transfers that is receives. There are two methods available: ``tar`` and ``xbstream``. Given that the receiving node needs to know how to read the stream, it is necessary that both nodes use the same values for this parameter.
This parameter defines the utility the node uses to archive the node state before the transfer is sent and how to unarchive the state transfers that it receives. There are two methods available: ``tar`` and ``xbstream``. Given that the receiving node needs to know how to read the stream, it is necessary that both nodes use the same values for this parameter.

The default and recommended utility is ``xbstream`` given that it supports encryption, compression, parallel streaming, incremental backups and compaction. ``tar`` does not support these features.

Expand Down Expand Up @@ -473,12 +471,12 @@ Defines the transfer stream utility.
:stub-columns: 1

"**System Variable**", "Name:", "``transferfmt``"
"", "Match:", YesNo"
"", "Match:", "Yes"
"**Permitted Values**", "Type:", "String"
"", "Default Value:", "``socat`` "
"", "Valid Values:", "``socat``; ``nc``"

This parameter defines the utility that the node uses to format transfers sent from donor to joiner nodes. There are two methods supported: Socat and ``nc``. Given that the receiving node needs to know how to interpret the transfer, it is necessary that both nodes use the same values for this parameter.
This parameter defines the utility that the node uses to format transfers sent from donor to joiner nodes. There are two methods supported: ``socat`` and ``nc``. Given that the receiving node needs to know how to interpret the transfer, it is necessary that both nodes use the same values for this parameter.

The default and recommended utility is Socat, given that it allows for socket options, such as transfer buffer size. For more information, see the `socat Documentation <https://www.dest-unreach.org/socat/doc/socat.html>`_.

Expand All @@ -491,7 +489,7 @@ The default and recommended utility is Socat, given that it allows for socket op
.. rst-class:: section-heading
.. rubric:: ``joiner_timeout``

How soon joiner should timeout waiting for SST (seconds).
How soon the joiner should timeout when waiting for SST (seconds).

.. csv-table::
:class: doc-options
Expand All @@ -502,7 +500,7 @@ How soon joiner should timeout waiting for SST (seconds).
"**Permitted Values**", "Type:", "Integer"
"", "Default Value:", "``60``"

This parameter determines the initial timeout in seconds for the joiner to receive the first packet in a :term:`State Snapshot Transfer`. This keeps the joiner node from hanging in the event that the donor node crashes while starting the operation.
This parameter determines the initial timeout in seconds for the joiner to receive the first packet in a :term:`State Snapshot Transfer`. This keeps the joiner node from hanging, in the event that the donor node crashes while starting the operation.

.. code-block:: ini

Expand All @@ -513,7 +511,7 @@ This parameter determines the initial timeout in seconds for the joiner to recei
.. rst-class:: section-heading
.. rubric:: ``donor_timeout``

How soon donor should timeout on connection to joiner (seconds).
How soon the donor should timeout on connection to joiner (seconds).

.. csv-table::
:class: doc-options
Expand All @@ -524,7 +522,7 @@ How soon donor should timeout on connection to joiner (seconds).
"**Permitted Values**", "Type:", "Integer"
"", "Default Value:", "``10``"

This parameter determines how soon the donor should timeout on connection to joiner and return to normal operation in case the joiner turns to be unresponsive.
This parameter determines how soon the donor should timeout on connection to joiner, and return to normal operation in the event that the joiner turns unresponsive.

.. code-block:: ini

Expand Down