:tocdepth: 0


.. _/plugins/test-checks:

Test checks Plugins
~~~~~~~~~~~~~~~~~~~

.. include:: test-checks-header.inc.rst

.. _/plugins/test-checks/common-keys:

Common Keys
-----------

The following keys are accepted by all plugins of the ``test-checks`` step.


enabled: ``true|false``
    Whether the check is enabled or not.

    Default: ``true``


result: ``info|respect|xfail``
    How to interpret the check result.

    Default: ``respect``


.. _/plugins/test-checks/avc:

avc
---


Check for SELinux AVC denials raised during the test.

The check collects SELinux AVC denials from the audit log,
gathers details about them, and together with versions of
the ``selinux-policy`` and related packages stores them in
a report file after the test.

.. code-block:: yaml

    check:
      - name: avc

.. note::

    To work correctly, the check requires SELinux to be enabled on the
    guest, and ``auditd`` must be running. Without SELinux, the
    check will turn into no-op, reporting
    :ref:`skip</spec/plans/results/outcomes>` result, and
    without ``auditd``, the check will discover no AVC denials,
    reporting :ref:`pass</spec/plans/results/outcomes>`.

    If the test manipulates ``auditd`` or SELinux in general, the
    check may report unexpected results.

.. versionadded:: 1.28



.. _/plugins/test-checks/dmesg:

dmesg
-----


Save the content of kernel ring buffer (aka "console") into a file.

The check saves one file before the test, and then again
when test finishes.

.. code-block:: yaml

    check:
      - how: dmesg

Check will identify patterns that signal kernel crashes and
core dumps, and when detected, it will report as failed result.
It is possible to define custom patterns:

.. code-block:: yaml

    check:
      - how: dmesg
        failure-pattern:
          # These are default patterns
          - 'Call Trace:
          - '\ssegfault\s'

          # More patterns to look for
          - '\[Firmware Bug\]'

.. versionadded:: 1.28

.. versionchanged:: 1.33
   ``failure-pattern`` has been added.


Configuration
^^^^^^^^^^^^^

See also :ref:`Common Keys</plugins/test-checks/common-keys>` accepted by the plugin.


failure-pattern: ``PATTERN``
    List of regular expressions to look for in ``dmesg``
    output. If any of patterns is found, ``dmesg`` check will
    report ``fail`` result.

    Default: ``Call Trace:``, ``\ssegfault\s``

----

.. _/plugins/test-checks/watchdog:

watchdog
--------

.. warning::

    Please, be aware that the documentation below is a work in progress. We are
    working on fixing it, adding missing bits and generally making it better.
    Also, it was originally used for command line help only, therefore the
    formatting is often suboptimal.

Take various actions when guest becomes unresponsive.

Watchdog runs selected probes every now and then, and when a given
number of `probes` fail, watchdog would run one or more of the
predefined `actions`.

Check comes with two probes, "ping" and "SSH ping", and single
action, "reboot".

* "ping" uses the classic ICMP echo to check whether the guest is
  still up and running,
* "SSH ping" tries to establish SSH connection,
* "reboot" action issues a hard reboot of the guest.

.. warning::

    Be aware that this feature may be limited depending on how the
    guest was provisioned. See :ref:`/plugins/provision/hard-reboot`.

Each probe has a "budget" of allowed failures, and when it runs out,
the action is taken. A successful probe replenishes its budget to
the original level.

Multiple probes can be enabled at the same time, for the action to
happen it's enough if just one of them runs out of its budget.

.. code-block:: yaml

    check:
      - how: watchdog
        ping: true
        reboot: true

.. code-block:: yaml

    check:
      - how: watchdog

        # Use only SSH ping.
        ping: false
        ssh-ping: true

        # Try every 5 minutes, allow 7 failed attempts, and reboot
        # the guest when we run out of attempts.
        interval: 300
        reboot: true
        ssh-ping-threshold: 7

.. versionadded:: 1.32


Configuration
^^^^^^^^^^^^^

See also :ref:`Common Keys</plugins/test-checks/common-keys>` accepted by the plugin.


interval:
    How often should the watchdog run, in seconds.

    Default: ``60``


ping: ``true|false``
    If enabled, watchdog would probe guest's responsiveness with ICMP packets.

    Default: ``false``


ping-packets:
    How many ICMP packates to send as one probe.

    Default: ``1``


ping-threshold:
    How many failed ping probes before taking any further action.

    Default: ``10``


reboot: ``true|false``
    If enabled, watchdog would reboot the guest after enough failed probes.

    Default: ``false``


ssh-ping: ``true|false``
    If enabled, watchdog would probe guest's responsiveness by connecting
    to its SSH port.

    Default: ``false``


ssh-ping-threshold:
    How many failed SSH connections before taking any further action.

    Default: ``10``