:tocdepth: 0








.. _/plugins/provision:

Provision Plugins
~~~~~~~~~~~~~~~~~



.. include:: provision-header.inc.rst

.. _/plugins/provision/common-keys:

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



The following keys are accepted by all plugins of the ``provision`` step.


name
    The name of the step phase.

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_NAME``

    In plan metadata:

    .. code-block:: yaml

       name:

    On command-line:

    .. code-block:: shell

       --name ...
       export TMT_PLUGIN_PROVISION_ARTEMIS_NAME=...



order
    Order in which the phase should be handled.

    Default: ``50``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_ORDER``

    In plan metadata:

    .. code-block:: yaml

       order:

    On command-line:

    .. code-block:: shell

       --order ...
       export TMT_PLUGIN_PROVISION_ARTEMIS_ORDER=...



summary
    Concise summary describing purpose of the phase.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_SUMMARY``

    In plan metadata:

    .. code-block:: yaml

       summary:

    On command-line:

    .. code-block:: shell

       --summary ...
       export TMT_PLUGIN_PROVISION_ARTEMIS_SUMMARY=...



when
    If specified, phase is run only if any rule matches plan context.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_WHEN``

    In plan metadata:

    .. code-block:: yaml

       when: RULE


    On command-line:

    .. code-block:: shell

       --when RULE
       export TMT_PLUGIN_PROVISION_ARTEMIS_WHEN=RULE



.. _/plugins/provision/artemis:

artemis
-------



.. 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.

Provision guest using Artemis backend.

Reserve a machine using the Artemis service.
Users can specify many requirements, mostly regarding the
desired OS, RAM, disk size and more. Most of the HW specifications
defined in the :tmt:story:`/spec/hardware` are supported. Including the
:tmt:story:`/spec/plans/provision/kickstart`.

Artemis takes machines from AWS, OpenStack, Beaker or Azure.
By default, Artemis handles the selection of a cloud provider
to its best abilities and the required specification. However, it
is possible to specify the keyword ``pool`` and select the
desired cloud provider.

Artemis project:
https://gitlab.com/testing-farm/artemis

Minimal configuration could look like this:

.. code-block:: yaml

    provision:
        how: artemis
        image: Fedora
        api-url: https://your-artemis.com/

.. note::

    When used together with the :ref:`testing-farm` infrastructure
    some of the options from the first example below will be filled
    for you by the Testing Farm service.

.. note::

    The actual value of ``image`` depends on what images - or "composes" as
    Artemis calls them - supports and can deliver.

.. note::

    The ``api-url`` can be also given via ``TMT_PLUGIN_PROVISION_ARTEMIS_API_URL``
    environment variable.

Full configuration example:

.. code-block:: yaml

    provision:
        how: artemis

        # Artemis API
        api-url: https://your-artemis.com/
        api-version: 0.0.32

        # Mandatory environment properties
        image: Fedora

        # Optional environment properties
        arch: aarch64
        pool: optional-pool-name

        # Provisioning process control (optional)
        priority-group: custom-priority-group
        keyname: custom-SSH-key-name

        # Labels to be attached to guest request (optional)
        user-data:
            foo: bar

        # Timeouts and deadlines (optional)
        provision-timeout: 3600
        provision-tick: 10
        api-timeout: 600
        api-retries: 5
        api-retry-backoff-factor: 1




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



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


ansible
    Ansible configuration for individual guest inventory generation.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_ANSIBLE``

    In plan metadata:

    .. code-block:: yaml

       ansible:

    On command-line:

    .. code-block:: shell

       --ansible ...
       export TMT_PLUGIN_PROVISION_ARTEMIS_ANSIBLE=...



api-retries
    How many attempts to use when talking to API,
    10 by default.

    Default: ``10``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_API_RETRIES``

    In plan metadata:

    .. code-block:: yaml

       api-retries: COUNT


    On command-line:

    .. code-block:: shell

       --api-retries COUNT
       export TMT_PLUGIN_PROVISION_ARTEMIS_API_RETRIES=COUNT



api-retry-backoff-factor
    A factor for exponential API retry backoff,
    1 by default.

    Default: ``1``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_API_RETRY_BACKOFF_FACTOR``

    In plan metadata:

    .. code-block:: yaml

       api-retry-backoff-factor: COUNT


    On command-line:

    .. code-block:: shell

       --api-retry-backoff-factor COUNT
       export TMT_PLUGIN_PROVISION_ARTEMIS_API_RETRY_BACKOFF_FACTOR=COUNT



api-timeout
    How long to wait for API operations to complete,
    10 seconds by default.

    Default: ``10``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_API_TIMEOUT``

    In plan metadata:

    .. code-block:: yaml

       api-timeout: SECONDS


    On command-line:

    .. code-block:: shell

       --api-timeout SECONDS
       export TMT_PLUGIN_PROVISION_ARTEMIS_API_TIMEOUT=SECONDS



api-url
    Artemis API URL.

    Default: ``http://127.0.0.1:8001``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_API_URL``

    In plan metadata:

    .. code-block:: yaml

       api-url: URL


    On command-line:

    .. code-block:: shell

       --api-url URL
       export TMT_PLUGIN_PROVISION_ARTEMIS_API_URL=URL



api-version
    Artemis API version to use.

    Default: ``0.0.84``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_API_VERSION``

    In plan metadata:

    .. code-block:: yaml

       api-version: X.Y.Z


    On command-line:

    .. code-block:: shell

       --api-version X.Y.Z
       export TMT_PLUGIN_PROVISION_ARTEMIS_API_VERSION=X.Y.Z



arch
    Architecture to provision.

    Default: ``x86_64``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_ARCH``

    In plan metadata:

    .. code-block:: yaml

       arch: ARCH


    On command-line:

    .. code-block:: shell

       --arch ARCH
       export TMT_PLUGIN_PROVISION_ARTEMIS_ARCH=ARCH



become
    Whether to run tests and shell scripts in prepare and
    finish steps with ``sudo``.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_BECOME``

    In plan metadata:

    .. code-block:: yaml

       become: true|false

    On command-line:

    .. code-block:: shell

       --become
       export TMT_PLUGIN_PROVISION_ARTEMIS_BECOME=1|0


environment
    Environment variables to be defined for this guest. These will be available
    during test execution and can be used to customize behavior on a per-guest basis.
    Note that variables defined here can be overridden by test-level environment variables.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_ENVIRONMENT``

    In plan metadata:

    .. code-block:: yaml

       environment: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --environment KEY=VALUE
       export TMT_PLUGIN_PROVISION_ARTEMIS_ENVIRONMENT=KEY=VALUE



hardware
    Hardware requirements the provisioned guest must satisfy.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_HARDWARE``

    In plan metadata:

    .. code-block:: yaml

       hardware: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --hardware KEY=VALUE
       export TMT_PLUGIN_PROVISION_ARTEMIS_HARDWARE=KEY=VALUE



image
    Image (or "compose" in Artemis terminology) to provision.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_IMAGE``

    In plan metadata:

    .. code-block:: yaml

       image: COMPOSE


    On command-line:

    .. code-block:: shell

       --image COMPOSE
       export TMT_PLUGIN_PROVISION_ARTEMIS_IMAGE=COMPOSE



key
    Private key to use as SSH identity for key-based
    authentication.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_KEY``

    In plan metadata:

    .. code-block:: yaml

       key: PATH


    On command-line:

    .. code-block:: shell

       --key PATH
       export TMT_PLUGIN_PROVISION_ARTEMIS_KEY=PATH



keyname
    SSH key name.

    Default: ``master-key``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_KEYNAME``

    In plan metadata:

    .. code-block:: yaml

       keyname: NAME


    On command-line:

    .. code-block:: shell

       --keyname NAME
       export TMT_PLUGIN_PROVISION_ARTEMIS_KEYNAME=NAME



kickstart
    Optional Beaker kickstart to use when provisioning the guest.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_KICKSTART``

    In plan metadata:

    .. code-block:: yaml

       kickstart: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --kickstart KEY=VALUE
       export TMT_PLUGIN_PROVISION_ARTEMIS_KICKSTART=KEY=VALUE



log-type
    Log types the guest must support.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_LOG_TYPE``

    In plan metadata:

    .. code-block:: yaml

       log-type: console:dump/blob|console:dump/url|console:interactive/url|sys.log:dump/url|flasher-debug:dump/url|flasher-debug:dump/blob|flasher-event:dump/url|flasher-event:dump/blob|anaconda.log:dump/blob|storage.log:dump/blob|program.log:dump/blob|packaging.log:dump/blob|ks.cfg:dump/blob


    On command-line:

    .. code-block:: shell

       --log-type 'console:dump/blob|console:dump/url|console:interactive/url|sys.log:dump/url|flasher-debug:dump/url|flasher-debug:dump/blob|flasher-event:dump/url|flasher-event:dump/blob|anaconda.log:dump/blob|storage.log:dump/blob|program.log:dump/blob|packaging.log:dump/blob|ks.cfg:dump/blob'
       export TMT_PLUGIN_PROVISION_ARTEMIS_LOG_TYPE='console:dump/blob|console:dump/url|console:interactive/url|sys.log:dump/url|flasher-debug:dump/url|flasher-debug:dump/blob|flasher-event:dump/url|flasher-event:dump/blob|anaconda.log:dump/blob|storage.log:dump/blob|program.log:dump/blob|packaging.log:dump/blob|ks.cfg:dump/blob'



password
    Password to use for password-based authentication.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_PASSWORD``

    In plan metadata:

    .. code-block:: yaml

       password: PASSWORD


    On command-line:

    .. code-block:: shell

       --password PASSWORD
       export TMT_PLUGIN_PROVISION_ARTEMIS_PASSWORD=PASSWORD



pool
    Pool to enforce.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_POOL``

    In plan metadata:

    .. code-block:: yaml

       pool: NAME


    On command-line:

    .. code-block:: shell

       --pool NAME
       export TMT_PLUGIN_PROVISION_ARTEMIS_POOL=NAME



port
    Port to use for SSH connections instead of the default
    one.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_PORT``

    In plan metadata:

    .. code-block:: yaml

       port: PORT


    On command-line:

    .. code-block:: shell

       --port PORT
       export TMT_PLUGIN_PROVISION_ARTEMIS_PORT=PORT



post-install-script
    If set, the script provided or fetched will be executed.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_POST_INSTALL_SCRIPT``

    In plan metadata:

    .. code-block:: yaml

       post-install-script: SCRIPT|URL


    On command-line:

    .. code-block:: shell

       --post-install-script 'SCRIPT|URL'
       export TMT_PLUGIN_PROVISION_ARTEMIS_POST_INSTALL_SCRIPT='SCRIPT|URL'



priority-group
    Provisioning priority group.

    Default: ``default-priority``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_PRIORITY_GROUP``

    In plan metadata:

    .. code-block:: yaml

       priority-group: NAME


    On command-line:

    .. code-block:: shell

       --priority-group NAME
       export TMT_PLUGIN_PROVISION_ARTEMIS_PRIORITY_GROUP=NAME



provision-tick
    How often check Artemis API for provisioning status,
    60 seconds by default.

    Default: ``60``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_PROVISION_TICK``

    In plan metadata:

    .. code-block:: yaml

       provision-tick: SECONDS


    On command-line:

    .. code-block:: shell

       --provision-tick SECONDS
       export TMT_PLUGIN_PROVISION_ARTEMIS_PROVISION_TICK=SECONDS



provision-timeout
    How long to wait for provisioning to complete,
    600 seconds by default.

    Default: ``600``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_PROVISION_TIMEOUT``

    In plan metadata:

    .. code-block:: yaml

       provision-timeout: SECONDS


    On command-line:

    .. code-block:: shell

       --provision-timeout SECONDS
       export TMT_PLUGIN_PROVISION_ARTEMIS_PROVISION_TIMEOUT=SECONDS



role
    Marks guests with the same purpose so that common actions
    can be applied to all such guests at once.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_ROLE``

    In plan metadata:

    .. code-block:: yaml

       role: NAME


    On command-line:

    .. code-block:: shell

       --role NAME
       export TMT_PLUGIN_PROVISION_ARTEMIS_ROLE=NAME



skip-prepare-verify-ssh
    If set, skip verifiction of SSH connection in prepare state.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_SKIP_PREPARE_VERIFY_SSH``

    In plan metadata:

    .. code-block:: yaml

       skip-prepare-verify-ssh: true|false

    On command-line:

    .. code-block:: shell

       --skip-prepare-verify-ssh
       export TMT_PLUGIN_PROVISION_ARTEMIS_SKIP_PREPARE_VERIFY_SSH=1|0


ssh-option
    Additional SSH option. Value is passed to the ``-o``
    option of ``ssh``, see ``ssh_config(5)`` for supported
    options. Can be specified multiple times.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_SSH_OPTION``

    In plan metadata:

    .. code-block:: yaml

       ssh-option: OPTION


    On command-line:

    .. code-block:: shell

       --ssh-option OPTION
       export TMT_PLUGIN_PROVISION_ARTEMIS_SSH_OPTION=OPTION



user
    A username to use for all guest operations.

    Default: ``root``

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_USER``

    In plan metadata:

    .. code-block:: yaml

       user: NAME


    On command-line:

    .. code-block:: shell

       --user NAME
       export TMT_PLUGIN_PROVISION_ARTEMIS_USER=NAME



user-data
    Optional data to attach to guest.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_USER_DATA``

    In plan metadata:

    .. code-block:: yaml

       user-data: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --user-data KEY=VALUE
       export TMT_PLUGIN_PROVISION_ARTEMIS_USER_DATA=KEY=VALUE



watchdog-dispatch-delay
    How long (seconds) before the guest "is-alive" watchdog is dispatched. The dispatch
    timer starts once the guest is successfully provisioned.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_WATCHDOG_DISPATCH_DELAY``

    In plan metadata:

    .. code-block:: yaml

       watchdog-dispatch-delay: SECONDS


    On command-line:

    .. code-block:: shell

       --watchdog-dispatch-delay SECONDS
       export TMT_PLUGIN_PROVISION_ARTEMIS_WATCHDOG_DISPATCH_DELAY=SECONDS



watchdog-period-delay
    How often (seconds) check that the guest "is-alive".

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_ARTEMIS_WATCHDOG_PERIOD_DELAY``

    In plan metadata:

    .. code-block:: yaml

       watchdog-period-delay: SECONDS


    On command-line:

    .. code-block:: shell

       --watchdog-period-delay SECONDS
       export TMT_PLUGIN_PROVISION_ARTEMIS_WATCHDOG_PERIOD_DELAY=SECONDS



----


.. _/plugins/provision/beaker:

beaker
------



.. 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.

Provision guest on Beaker system using mrack.

Reserve a machine from the Beaker pool using the ``mrack``
plugin. ``mrack`` is a multicloud provisioning library
supporting multiple cloud services including Beaker.

The following two files are used for configuration:

``/etc/tmt/mrack.conf`` for basic configuration

``/etc/tmt/provisioning-config.yaml`` configuration per supported provider

Beaker installs distribution specified by the ``image``
key. If the image can not be translated using the
``provisioning-config.yaml`` file mrack passes the image
value to Beaker hub and tries to request distribution
based on the image value. This way we can bypass default
translations and use desired distribution specified like
the one in the example below.

Minimal configuration could look like this:

.. code-block:: yaml

    provision:
        how: beaker
        image: fedora

To trigger a hard reboot of a guest, ``bkr system-power --action reboot``
command is executed.

.. warning::

    ``bkr system-power`` command is executed on the runner, not
    on the guest.

.. code-block:: yaml

    # Specify the distro directly
    provision:
        how: beaker
        image: Fedora-37%

.. code-block:: yaml

    # Set custom whiteboard description (added in 1.30)
    provision:
        how: beaker
        whiteboard: Just a smoke test for now




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



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


ansible
    Ansible configuration for individual guest inventory generation.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_ANSIBLE``

    In plan metadata:

    .. code-block:: yaml

       ansible:

    On command-line:

    .. code-block:: shell

       --ansible ...
       export TMT_PLUGIN_PROVISION_BEAKER_ANSIBLE=...



api-session-refresh-tick
    How often should Beaker session be refreshed to pick up-to-date Kerberos ticket,
    3600 seconds by default.

    Default: ``3600``

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_API_SESSION_REFRESH_TICK``

    In plan metadata:

    .. code-block:: yaml

       api-session-refresh-tick: SECONDS


    On command-line:

    .. code-block:: shell

       --api-session-refresh-tick SECONDS
       export TMT_PLUGIN_PROVISION_BEAKER_API_SESSION_REFRESH_TICK=SECONDS



arch
    Architecture to provision.

    Default: ``x86_64``

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_ARCH``

    In plan metadata:

    .. code-block:: yaml

       arch: ARCH


    On command-line:

    .. code-block:: shell

       --arch ARCH
       export TMT_PLUGIN_PROVISION_BEAKER_ARCH=ARCH



beaker-job-group
    If set, Beaker jobs will be submitted on behalf of ``GROUPNAME``.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_BEAKER_JOB_GROUP``

    In plan metadata:

    .. code-block:: yaml

       beaker-job-group: GROUPNAME


    On command-line:

    .. code-block:: shell

       --beaker-job-group GROUPNAME
       export TMT_PLUGIN_PROVISION_BEAKER_BEAKER_JOB_GROUP=GROUPNAME



beaker-job-owner
    If set, Beaker jobs will be submitted on behalf of ``USERNAME``.
    Submitting user must be a submission delegate for the ``USERNAME``.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_BEAKER_JOB_OWNER``

    In plan metadata:

    .. code-block:: yaml

       beaker-job-owner: USERNAME


    On command-line:

    .. code-block:: shell

       --beaker-job-owner USERNAME
       export TMT_PLUGIN_PROVISION_BEAKER_BEAKER_JOB_OWNER=USERNAME



become
    Whether to run tests and shell scripts in prepare and
    finish steps with ``sudo``.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_BECOME``

    In plan metadata:

    .. code-block:: yaml

       become: true|false

    On command-line:

    .. code-block:: shell

       --become
       export TMT_PLUGIN_PROVISION_BEAKER_BECOME=1|0


bootc
    If set, bootc on Beaker installation will be performed.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_BOOTC``

    In plan metadata:

    .. code-block:: yaml

       bootc: true|false

    On command-line:

    .. code-block:: shell

       --bootc
       export TMT_PLUGIN_PROVISION_BEAKER_BOOTC=1|0


bootc-check-system-url
    URL to ``check-system`` task, which is needed for bootc on Beaker installation.

    Default: ``https://gitlab.com/fedora/bootc/tests/bootc-beaker-test/-/archive/1.8/bootc-beaker-test-1.8.tar.gz#check-system``

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_BOOTC_CHECK_SYSTEM_URL``

    In plan metadata:

    .. code-block:: yaml

       bootc-check-system-url: URL


    On command-line:

    .. code-block:: shell

       --bootc-check-system-url URL
       export TMT_PLUGIN_PROVISION_BEAKER_BOOTC_CHECK_SYSTEM_URL=URL



bootc-image-url
    Select bootc image to be used to perform the installation.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_BOOTC_IMAGE_URL``

    In plan metadata:

    .. code-block:: yaml

       bootc-image-url: URL


    On command-line:

    .. code-block:: shell

       --bootc-image-url URL
       export TMT_PLUGIN_PROVISION_BEAKER_BOOTC_IMAGE_URL=URL



bootc-registry-secret
    Specify bootc secret, which will be used for fetching from registry.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_BOOTC_REGISTRY_SECRET``

    In plan metadata:

    .. code-block:: yaml

       bootc-registry-secret: SECRET


    On command-line:

    .. code-block:: shell

       --bootc-registry-secret SECRET
       export TMT_PLUGIN_PROVISION_BEAKER_BOOTC_REGISTRY_SECRET=SECRET



environment
    Environment variables to be defined for this guest. These will be available
    during test execution and can be used to customize behavior on a per-guest basis.
    Note that variables defined here can be overridden by test-level environment variables.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_ENVIRONMENT``

    In plan metadata:

    .. code-block:: yaml

       environment: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --environment KEY=VALUE
       export TMT_PLUGIN_PROVISION_BEAKER_ENVIRONMENT=KEY=VALUE



hardware
    Hardware requirements the provisioned guest must satisfy.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_HARDWARE``

    In plan metadata:

    .. code-block:: yaml

       hardware: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --hardware KEY=VALUE
       export TMT_PLUGIN_PROVISION_BEAKER_HARDWARE=KEY=VALUE



image
    Image (distro or "compose" in Beaker terminology) to provision.

    Default: ``fedora``

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_IMAGE``

    In plan metadata:

    .. code-block:: yaml

       image: COMPOSE


    On command-line:

    .. code-block:: shell

       --image COMPOSE
       export TMT_PLUGIN_PROVISION_BEAKER_IMAGE=COMPOSE



key
    Private key to use as SSH identity for key-based
    authentication.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_KEY``

    In plan metadata:

    .. code-block:: yaml

       key: PATH


    On command-line:

    .. code-block:: shell

       --key PATH
       export TMT_PLUGIN_PROVISION_BEAKER_KEY=PATH



kickstart
    Optional Beaker kickstart to use when provisioning the guest.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_KICKSTART``

    In plan metadata:

    .. code-block:: yaml

       kickstart: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --kickstart KEY=VALUE
       export TMT_PLUGIN_PROVISION_BEAKER_KICKSTART=KEY=VALUE



password
    Password to use for password-based authentication.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_PASSWORD``

    In plan metadata:

    .. code-block:: yaml

       password: PASSWORD


    On command-line:

    .. code-block:: shell

       --password PASSWORD
       export TMT_PLUGIN_PROVISION_BEAKER_PASSWORD=PASSWORD



port
    Port to use for SSH connections instead of the default
    one.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_PORT``

    In plan metadata:

    .. code-block:: yaml

       port: PORT


    On command-line:

    .. code-block:: shell

       --port PORT
       export TMT_PLUGIN_PROVISION_BEAKER_PORT=PORT



provision-tick
    How often check Beaker for provisioning status,
    60 seconds by default.

    Default: ``60``

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_PROVISION_TICK``

    In plan metadata:

    .. code-block:: yaml

       provision-tick: SECONDS


    On command-line:

    .. code-block:: shell

       --provision-tick SECONDS
       export TMT_PLUGIN_PROVISION_BEAKER_PROVISION_TICK=SECONDS



provision-timeout
    How long to wait for provisioning to complete,
    3600 seconds by default.

    Default: ``3600``

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_PROVISION_TIMEOUT``

    In plan metadata:

    .. code-block:: yaml

       provision-timeout: SECONDS


    On command-line:

    .. code-block:: shell

       --provision-timeout SECONDS
       export TMT_PLUGIN_PROVISION_BEAKER_PROVISION_TIMEOUT=SECONDS



public-key
    Public keys to add among authorized SSH keys.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_PUBLIC_KEY``

    In plan metadata:

    .. code-block:: yaml

       public-key: PUBKEY


    On command-line:

    .. code-block:: shell

       --public-key PUBKEY
       export TMT_PLUGIN_PROVISION_BEAKER_PUBLIC_KEY=PUBKEY



role
    Marks guests with the same purpose so that common actions
    can be applied to all such guests at once.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_ROLE``

    In plan metadata:

    .. code-block:: yaml

       role: NAME


    On command-line:

    .. code-block:: shell

       --role NAME
       export TMT_PLUGIN_PROVISION_BEAKER_ROLE=NAME



ssh-option
    Additional SSH option. Value is passed to the ``-o``
    option of ``ssh``, see ``ssh_config(5)`` for supported
    options. Can be specified multiple times.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_SSH_OPTION``

    In plan metadata:

    .. code-block:: yaml

       ssh-option: OPTION


    On command-line:

    .. code-block:: shell

       --ssh-option OPTION
       export TMT_PLUGIN_PROVISION_BEAKER_SSH_OPTION=OPTION



user
    A username to use for all guest operations.

    Default: ``root``

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_USER``

    In plan metadata:

    .. code-block:: yaml

       user: NAME


    On command-line:

    .. code-block:: shell

       --user NAME
       export TMT_PLUGIN_PROVISION_BEAKER_USER=NAME



whiteboard
    Text description of the beaker job which is displayed in the list of jobs.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BEAKER_WHITEBOARD``

    In plan metadata:

    .. code-block:: yaml

       whiteboard: WHITEBOARD


    On command-line:

    .. code-block:: shell

       --whiteboard WHITEBOARD
       export TMT_PLUGIN_PROVISION_BEAKER_WHITEBOARD=WHITEBOARD



----


.. _/plugins/provision/bootc:

bootc
-----



.. 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.

Provision a local virtual machine using a bootc container image

Minimal config which uses the CentOS Stream 9 bootc image:

.. code-block:: yaml

    provision:
        how: bootc
        container-image: quay.io/centos-bootc/centos-bootc:stream9
        rootfs: xfs

Here's a config example using a Containerfile:

.. code-block:: yaml

    provision:
        how: bootc
        container-file: "./my-custom-image.containerfile"
        container-file-workdir: .
        image-builder: quay.io/centos-bootc/bootc-image-builder:stream9
        rootfs: ext4
        disk: 100

Another config example using an image that already includes tmt
dependencies:

.. code-block:: yaml

    provision:
        how: bootc
        add-tmt-dependencies: false
        container-image: localhost/my-image-with-deps
        rootfs: btrfs

This plugin is an extension of the virtual.testcloud plugin.
Essentially, it takes a container image as input, builds a
bootc disk image from the container image, then uses the virtual.testcloud
plugin to create a virtual machine using the bootc disk image.

The bootc disk creation requires running podman as root. The plugin will
automatically check if the current podman connection is rootless. If it is,
a podman machine will be spun up and used to build the bootc disk.

To trigger hard reboot of a guest, plugin uses testcloud API. It is
also used to trigger soft reboot unless a custom reboot command was
specified via ``tmt-reboot -c ...``.




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



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


add-tmt-dependencies
    Add tmt dependencies to the supplied container image or image built
    from the supplied Containerfile.
    This will cause a derived image to be built from the supplied image.

    Default: ``true``

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_ADD_TMT_DEPENDENCIES``

    In plan metadata:

    .. code-block:: yaml

       add-tmt-dependencies: true|false

    On command-line:

    .. code-block:: shell

       --add-tmt-dependencies
       export TMT_PLUGIN_PROVISION_BOOTC_ADD_TMT_DEPENDENCIES=1|0


ansible
    Ansible configuration for individual guest inventory generation.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_ANSIBLE``

    In plan metadata:

    .. code-block:: yaml

       ansible:

    On command-line:

    .. code-block:: shell

       --ansible ...
       export TMT_PLUGIN_PROVISION_BOOTC_ANSIBLE=...



arch
    What architecture to virtualize, host arch by default.

    Default: ``x86_64``

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_ARCH``

    In plan metadata:

    .. code-block:: yaml

       arch: x86_64|aarch64|s390x|ppc64le


    On command-line:

    .. code-block:: shell

       --arch 'x86_64|aarch64|s390x|ppc64le'
       export TMT_PLUGIN_PROVISION_BOOTC_ARCH='x86_64|aarch64|s390x|ppc64le'



become
    Whether to run tests and shell scripts in prepare and
    finish steps with ``sudo``.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_BECOME``

    In plan metadata:

    .. code-block:: yaml

       become: true|false

    On command-line:

    .. code-block:: shell

       --become
       export TMT_PLUGIN_PROVISION_BOOTC_BECOME=1|0


build-disk-image-only
    Only build a bootc disk image from a container image and quit.
    Guest VM will not start.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_BUILD_DISK_IMAGE_ONLY``

    In plan metadata:

    .. code-block:: yaml

       build-disk-image-only: true|false

    On command-line:

    .. code-block:: shell

       --build-disk-image-only
       export TMT_PLUGIN_PROVISION_BOOTC_BUILD_DISK_IMAGE_ONLY=1|0


connection
    What session type to use, 'session' by default.

    Default: ``session``

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_CONNECTION``

    In plan metadata:

    .. code-block:: yaml

       connection: session|system


    On command-line:

    .. code-block:: shell

       --connection 'session|system'
       export TMT_PLUGIN_PROVISION_BOOTC_CONNECTION='session|system'



container-file
    Select container file to be used to build a container image
    that is then used by bootc image builder to create a disk image.

    Cannot be used with container-image.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_CONTAINER_FILE``

    In plan metadata:

    .. code-block:: yaml

       container-file: CONTAINER_FILE


    On command-line:

    .. code-block:: shell

       --container-file CONTAINER_FILE
       export TMT_PLUGIN_PROVISION_BOOTC_CONTAINER_FILE=CONTAINER_FILE



container-file-workdir
    Select working directory for the podman build invocation.

    Default: ``.``

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_CONTAINER_FILE_WORKDIR``

    In plan metadata:

    .. code-block:: yaml

       container-file-workdir: CONTAINER_FILE_WORKDIR


    On command-line:

    .. code-block:: shell

       --container-file-workdir CONTAINER_FILE_WORKDIR
       export TMT_PLUGIN_PROVISION_BOOTC_CONTAINER_FILE_WORKDIR=CONTAINER_FILE_WORKDIR



container-image
    Select container image to be used to build a bootc disk.
    This takes priority over Containerfile.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_CONTAINER_IMAGE``

    In plan metadata:

    .. code-block:: yaml

       container-image: CONTAINER_IMAGE


    On command-line:

    .. code-block:: shell

       --container-image CONTAINER_IMAGE
       export TMT_PLUGIN_PROVISION_BOOTC_CONTAINER_IMAGE=CONTAINER_IMAGE



disk
    Specify disk size in GB, 10 GB by default.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_DISK``

    In plan metadata:

    .. code-block:: yaml

       disk: SIZE


    On command-line:

    .. code-block:: shell

       --disk SIZE
       export TMT_PLUGIN_PROVISION_BOOTC_DISK=SIZE



environment
    Environment variables to be defined for this guest. These will be available
    during test execution and can be used to customize behavior on a per-guest basis.
    Note that variables defined here can be overridden by test-level environment variables.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_ENVIRONMENT``

    In plan metadata:

    .. code-block:: yaml

       environment: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --environment KEY=VALUE
       export TMT_PLUGIN_PROVISION_BOOTC_ENVIRONMENT=KEY=VALUE



hardware
    Hardware requirements the provisioned guest must satisfy.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_HARDWARE``

    In plan metadata:

    .. code-block:: yaml

       hardware: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --hardware KEY=VALUE
       export TMT_PLUGIN_PROVISION_BOOTC_HARDWARE=KEY=VALUE



image
    Select image to be used. Provide a short name, full path to a local file
    or a complete url.

    Default: ``fedora``

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_IMAGE``

    In plan metadata:

    .. code-block:: yaml

       image: IMAGE


    On command-line:

    .. code-block:: shell

       --image IMAGE
       export TMT_PLUGIN_PROVISION_BOOTC_IMAGE=IMAGE



image-builder
    The full repo:tag url of the bootc image builder image to use for
    building the bootc disk image.

    Default: ``quay.io/centos-bootc/bootc-image-builder:latest``

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_IMAGE_BUILDER``

    In plan metadata:

    .. code-block:: yaml

       image-builder: IMAGE_BUILDER


    On command-line:

    .. code-block:: shell

       --image-builder IMAGE_BUILDER
       export TMT_PLUGIN_PROVISION_BOOTC_IMAGE_BUILDER=IMAGE_BUILDER



key
    Private key to use as SSH identity for key-based
    authentication.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_KEY``

    In plan metadata:

    .. code-block:: yaml

       key: PATH


    On command-line:

    .. code-block:: shell

       --key PATH
       export TMT_PLUGIN_PROVISION_BOOTC_KEY=PATH



list-local-images
    List locally available images.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_LIST_LOCAL_IMAGES``

    In plan metadata:

    .. code-block:: yaml

       list-local-images: true|false

    On command-line:

    .. code-block:: shell

       --list-local-images
       export TMT_PLUGIN_PROVISION_BOOTC_LIST_LOCAL_IMAGES=1|0


memory
    Set available memory in MB, 2048 MB by default.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_MEMORY``

    In plan metadata:

    .. code-block:: yaml

       memory: SIZE


    On command-line:

    .. code-block:: shell

       --memory SIZE
       export TMT_PLUGIN_PROVISION_BOOTC_MEMORY=SIZE



password
    Password to use for password-based authentication.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_PASSWORD``

    In plan metadata:

    .. code-block:: yaml

       password: PASSWORD


    On command-line:

    .. code-block:: shell

       --password PASSWORD
       export TMT_PLUGIN_PROVISION_BOOTC_PASSWORD=PASSWORD



port
    Port to use for SSH connections instead of the default
    one.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_PORT``

    In plan metadata:

    .. code-block:: yaml

       port: PORT


    On command-line:

    .. code-block:: shell

       --port PORT
       export TMT_PLUGIN_PROVISION_BOOTC_PORT=PORT



role
    Marks guests with the same purpose so that common actions
    can be applied to all such guests at once.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_ROLE``

    In plan metadata:

    .. code-block:: yaml

       role: NAME


    On command-line:

    .. code-block:: shell

       --role NAME
       export TMT_PLUGIN_PROVISION_BOOTC_ROLE=NAME



rootfs
    Select root filesystem type. Overrides the default from the source
    container.

    Default: ``xfs``

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_ROOTFS``

    In plan metadata:

    .. code-block:: yaml

       rootfs: ext4|xfs|btrfs


    On command-line:

    .. code-block:: shell

       --rootfs 'ext4|xfs|btrfs'
       export TMT_PLUGIN_PROVISION_BOOTC_ROOTFS='ext4|xfs|btrfs'



ssh-option
    Additional SSH option. Value is passed to the ``-o``
    option of ``ssh``, see ``ssh_config(5)`` for supported
    options. Can be specified multiple times.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_SSH_OPTION``

    In plan metadata:

    .. code-block:: yaml

       ssh-option: OPTION


    On command-line:

    .. code-block:: shell

       --ssh-option OPTION
       export TMT_PLUGIN_PROVISION_BOOTC_SSH_OPTION=OPTION



stop-retries
    Number of attempts to stop a VM.

    Default: ``10``

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_STOP_RETRIES``

    In plan metadata:

    .. code-block:: yaml

       stop-retries: N


    On command-line:

    .. code-block:: shell

       --stop-retries N
       export TMT_PLUGIN_PROVISION_BOOTC_STOP_RETRIES=N



stop-retry-delay
    Time to wait between attempts to stop a VM.

    Default: ``1``

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_STOP_RETRY_DELAY``

    In plan metadata:

    .. code-block:: yaml

       stop-retry-delay: SECONDS


    On command-line:

    .. code-block:: shell

       --stop-retry-delay SECONDS
       export TMT_PLUGIN_PROVISION_BOOTC_STOP_RETRY_DELAY=SECONDS



user
    A username to use for all guest operations.

    Default: ``root``

    Environment variable: ``TMT_PLUGIN_PROVISION_BOOTC_USER``

    In plan metadata:

    .. code-block:: yaml

       user: NAME


    On command-line:

    .. code-block:: shell

       --user NAME
       export TMT_PLUGIN_PROVISION_BOOTC_USER=NAME



----


.. _/plugins/provision/connect:

connect
-------




Connect to a provisioned guest using SSH.

Do not provision any system, tests will be executed directly on the
machine that has been already provisioned. Use provided
authentication information to connect to it over SSH.



Private key authentication (using ``sudo`` to run scripts):

.. code-block:: yaml

    provision:
        how: connect
        guest: host.example.org
        user: fedora
        become: true
        key: /home/psss/.ssh/example_rsa

Password authentication:

.. code-block:: yaml

    provision:
        how: connect
        guest: host.example.org
        user: root
        password: secret

User defaults to ``root``, so if you have private key correctly set
the minimal configuration can look like this:

.. code-block:: yaml

    provision:
        how: connect
        guest: host.example.org

To support hard reboot of a guest, ``hard-reboot`` must be set to
an executable command or script. Without this key set, hard reboot
will remain unsupported and result in an error. In comparison,
``soft-reboot`` and ``systemd-soft-reboot`` are optional, but if set,
the given commands will be preferred over the default soft and systemd
soft-reboot commands:

.. code-block:: yaml

    provision:
      how: connect
      hard-reboot: virsh reboot my-example-vm
      systemd-soft-reboot: ssh root@my-example-vm 'systemd soft-reboot'
      soft-reboot: ssh root@my-example-vm 'shutdown -r now'

.. code-block:: shell

    provision --how connect \
              --hard-reboot="virsh reboot my-example-vm" \
              --systemd-soft-reboot="ssh root@my-example-vm 'systemd soft-reboot'"
              --soft-reboot="ssh root@my-example-vm 'shutdown -r now'"

.. warning::

    ``hard-reboot``, ``systemd-soft-reboot``, and ``soft-reboot``
    commands are executed on the runner, not on the guest.




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



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


ansible
    Ansible configuration for individual guest inventory generation.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_ANSIBLE``

    In plan metadata:

    .. code-block:: yaml

       ansible:

    On command-line:

    .. code-block:: shell

       --ansible ...
       export TMT_PLUGIN_PROVISION_CONNECT_ANSIBLE=...



become
    Whether to run tests and shell scripts in prepare and
    finish steps with ``sudo``.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_BECOME``

    In plan metadata:

    .. code-block:: yaml

       become: true|false

    On command-line:

    .. code-block:: shell

       --become
       export TMT_PLUGIN_PROVISION_CONNECT_BECOME=1|0


environment
    Environment variables to be defined for this guest. These will be available
    during test execution and can be used to customize behavior on a per-guest basis.
    Note that variables defined here can be overridden by test-level environment variables.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_ENVIRONMENT``

    In plan metadata:

    .. code-block:: yaml

       environment: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --environment KEY=VALUE
       export TMT_PLUGIN_PROVISION_CONNECT_ENVIRONMENT=KEY=VALUE



guest
    A preexisting machine to connect to.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_GUEST``

    In plan metadata:

    .. code-block:: yaml

       guest: HOSTNAME|IP


    On command-line:

    .. code-block:: shell

       --guest 'HOSTNAME|IP'
       export TMT_PLUGIN_PROVISION_CONNECT_GUEST='HOSTNAME|IP'



hard-reboot
    If specified, the command, executed on the runner, would be used
    for hard reboot of the guest.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_HARD_REBOOT``

    In plan metadata:

    .. code-block:: yaml

       hard-reboot: COMMAND


    On command-line:

    .. code-block:: shell

       --hard-reboot COMMAND
       export TMT_PLUGIN_PROVISION_CONNECT_HARD_REBOOT=COMMAND



hardware
    Hardware requirements the provisioned guest must satisfy.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_HARDWARE``

    In plan metadata:

    .. code-block:: yaml

       hardware: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --hardware KEY=VALUE
       export TMT_PLUGIN_PROVISION_CONNECT_HARDWARE=KEY=VALUE



key
    Private key to use as SSH identity for key-based
    authentication.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_KEY``

    In plan metadata:

    .. code-block:: yaml

       key: PATH


    On command-line:

    .. code-block:: shell

       --key PATH
       export TMT_PLUGIN_PROVISION_CONNECT_KEY=PATH



password
    Password to use for password-based authentication.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_PASSWORD``

    In plan metadata:

    .. code-block:: yaml

       password: PASSWORD


    On command-line:

    .. code-block:: shell

       --password PASSWORD
       export TMT_PLUGIN_PROVISION_CONNECT_PASSWORD=PASSWORD



port
    Port to use for SSH connections instead of the default
    one.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_PORT``

    In plan metadata:

    .. code-block:: yaml

       port: PORT


    On command-line:

    .. code-block:: shell

       --port PORT
       export TMT_PLUGIN_PROVISION_CONNECT_PORT=PORT



role
    Marks guests with the same purpose so that common actions
    can be applied to all such guests at once.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_ROLE``

    In plan metadata:

    .. code-block:: yaml

       role: NAME


    On command-line:

    .. code-block:: shell

       --role NAME
       export TMT_PLUGIN_PROVISION_CONNECT_ROLE=NAME



soft-reboot
    If specified, the command, executed on the runner, would be used
    for soft reboot of the guest.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_SOFT_REBOOT``

    In plan metadata:

    .. code-block:: yaml

       soft-reboot: COMMAND


    On command-line:

    .. code-block:: shell

       --soft-reboot COMMAND
       export TMT_PLUGIN_PROVISION_CONNECT_SOFT_REBOOT=COMMAND



ssh-option
    Additional SSH option. Value is passed to the ``-o``
    option of ``ssh``, see ``ssh_config(5)`` for supported
    options. Can be specified multiple times.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_SSH_OPTION``

    In plan metadata:

    .. code-block:: yaml

       ssh-option: OPTION


    On command-line:

    .. code-block:: shell

       --ssh-option OPTION
       export TMT_PLUGIN_PROVISION_CONNECT_SSH_OPTION=OPTION



systemd-soft-reboot
    If specified, the command, executed on the runner, would be used
    for systemd soft-reboot of the guest.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_SYSTEMD_SOFT_REBOOT``

    In plan metadata:

    .. code-block:: yaml

       systemd-soft-reboot: COMMAND


    On command-line:

    .. code-block:: shell

       --systemd-soft-reboot COMMAND
       export TMT_PLUGIN_PROVISION_CONNECT_SYSTEMD_SOFT_REBOOT=COMMAND



user
    A username to use for all guest operations.

    Default: ``root``

    Environment variable: ``TMT_PLUGIN_PROVISION_CONNECT_USER``

    In plan metadata:

    .. code-block:: yaml

       user: NAME


    On command-line:

    .. code-block:: shell

       --user NAME
       export TMT_PLUGIN_PROVISION_CONNECT_USER=NAME



----


.. _/plugins/provision/container:

container
---------



.. 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.

Create a new container using ``podman``.

Example config:

.. code-block:: yaml

    provision:
        how: container
        image: fedora:latest

.. code-block:: yaml

    # Use an image with a non-root user with sudo privileges,
    # and run scripts with sudo.
    provision:
        how: container
        image: image with non-root user with sudo privileges
        user: tester
        become: true

In order to always pull the fresh container image use ``pull: true``.

In order to run the container with different user as the default ``root``,
use ``user: USER``.

Container-backed guests do not support soft reboots or custom reboot
commands. Soft reboot or ``tmt-reboot -c ...`` will result in an
error.

.. note::

   Make sure ``podman`` is installed and configured, it is required for container-backed
   guests provided by ``provision/container`` plugin.

   To quickly test ``podman`` functionality, you can try running ``podman images`` or
   ``podman run --rm -it fedora:latest``.

   * Users who installed tmt from system repositories should install
     ``tmt+provision-container`` package.
   * Users who installed tmt from PyPI should also install ``tmt+provision-container``
     package, as it will install required system dependencies. After doing so, they should
     install ``tmt[provision-container]`` extra.



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



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


ansible
    Ansible configuration for individual guest inventory generation.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONTAINER_ANSIBLE``

    In plan metadata:

    .. code-block:: yaml

       ansible:

    On command-line:

    .. code-block:: shell

       --ansible ...
       export TMT_PLUGIN_PROVISION_CONTAINER_ANSIBLE=...



become
    Whether to run tests and shell scripts in prepare and
    finish steps with ``sudo``.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_CONTAINER_BECOME``

    In plan metadata:

    .. code-block:: yaml

       become: true|false

    On command-line:

    .. code-block:: shell

       --become
       export TMT_PLUGIN_PROVISION_CONTAINER_BECOME=1|0


container
    Name or id of an existing container to be used.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONTAINER_CONTAINER``

    In plan metadata:

    .. code-block:: yaml

       container: NAME


    On command-line:

    .. code-block:: shell

       --container NAME
       export TMT_PLUGIN_PROVISION_CONTAINER_CONTAINER=NAME



environment
    Environment variables to be defined for this guest. These will be available
    during test execution and can be used to customize behavior on a per-guest basis.
    Note that variables defined here can be overridden by test-level environment variables.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONTAINER_ENVIRONMENT``

    In plan metadata:

    .. code-block:: yaml

       environment: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --environment KEY=VALUE
       export TMT_PLUGIN_PROVISION_CONTAINER_ENVIRONMENT=KEY=VALUE



force-pull
    Force pulling a fresh container image.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_CONTAINER_FORCE_PULL``

    In plan metadata:

    .. code-block:: yaml

       force-pull: true|false

    On command-line:

    .. code-block:: shell

       --force-pull
       export TMT_PLUGIN_PROVISION_CONTAINER_FORCE_PULL=1|0


hardware
    Hardware requirements the provisioned guest must satisfy.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONTAINER_HARDWARE``

    In plan metadata:

    .. code-block:: yaml

       hardware: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --hardware KEY=VALUE
       export TMT_PLUGIN_PROVISION_CONTAINER_HARDWARE=KEY=VALUE



image
    Select image to use. Short name or complete url.

    Default: ``fedora``

    Environment variable: ``TMT_PLUGIN_PROVISION_CONTAINER_IMAGE``

    In plan metadata:

    .. code-block:: yaml

       image: IMAGE


    On command-line:

    .. code-block:: shell

       --image IMAGE
       export TMT_PLUGIN_PROVISION_CONTAINER_IMAGE=IMAGE



network-prefix
    Custom prefix for container network names to avoid collisions
    between multiple simultaneous tmt invocations.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONTAINER_NETWORK_PREFIX``

    In plan metadata:

    .. code-block:: yaml

       network-prefix: PREFIX


    On command-line:

    .. code-block:: shell

       --network-prefix PREFIX
       export TMT_PLUGIN_PROVISION_CONTAINER_NETWORK_PREFIX=PREFIX



pull-attempts
    How many times to try pulling the image,
    5 attempts by default.

    Default: ``5``

    Environment variable: ``TMT_PLUGIN_PROVISION_CONTAINER_PULL_ATTEMPTS``

    In plan metadata:

    .. code-block:: yaml

       pull-attempts: COUNT


    On command-line:

    .. code-block:: shell

       --pull-attempts COUNT
       export TMT_PLUGIN_PROVISION_CONTAINER_PULL_ATTEMPTS=COUNT



pull-interval
    How long to wait before a new pull attempt,
    5 seconds by default.

    Default: ``5``

    Environment variable: ``TMT_PLUGIN_PROVISION_CONTAINER_PULL_INTERVAL``

    In plan metadata:

    .. code-block:: yaml

       pull-interval: SECONDS


    On command-line:

    .. code-block:: shell

       --pull-interval SECONDS
       export TMT_PLUGIN_PROVISION_CONTAINER_PULL_INTERVAL=SECONDS



role
    Marks guests with the same purpose so that common actions
    can be applied to all such guests at once.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_CONTAINER_ROLE``

    In plan metadata:

    .. code-block:: yaml

       role: NAME


    On command-line:

    .. code-block:: shell

       --role NAME
       export TMT_PLUGIN_PROVISION_CONTAINER_ROLE=NAME



stop-time
    How long to wait before forcibly stopping the container,
    1 seconds by default.

    Default: ``1``

    Environment variable: ``TMT_PLUGIN_PROVISION_CONTAINER_STOP_TIME``

    In plan metadata:

    .. code-block:: yaml

       stop-time: SECONDS


    On command-line:

    .. code-block:: shell

       --stop-time SECONDS
       export TMT_PLUGIN_PROVISION_CONTAINER_STOP_TIME=SECONDS



user
    Username to use for all guest operations.

    Default: ``root``

    Environment variable: ``TMT_PLUGIN_PROVISION_CONTAINER_USER``

    In plan metadata:

    .. code-block:: yaml

       user: USERNAME


    On command-line:

    .. code-block:: shell

       --user USERNAME
       export TMT_PLUGIN_PROVISION_CONTAINER_USER=USERNAME



----


.. _/plugins/provision/local:

local
-----




Use the localhost for the test execution.

Do not provision any system, tests will be executed directly on the
localhost.

.. warning::

    In general, it is not recommended to run tests on your local
    machine as there might be security risks. Run only those tests
    which you know are safe so that you don't destroy your
    workstation ;-)

    From tmt version 1.38, the ``--feeling-safe`` option or
    the ``TMT_FEELING_SAFE=1`` environment variable is
    required in order to use the ``local`` provision plugin.

Using the plugin:

.. code-block:: yaml

    provision:
        how: local

.. code-block:: shell

    provision --how local

.. note::

    ``tmt run`` is expected to be executed under a non-privileged
    user account. For some actions on the localhost, e.g.
    installation of test requirements, ``local`` will require
    elevated privileges, either by running under ``root``
    account, or by using ``sudo`` to run the sensitive commands. You
    may be asked for a password in such cases.

.. note::

    Neither hard nor soft reboot is supported.

.. note::

    Currently the ``TMT_SCRIPTS_DIR`` variable is not supported in
    the ``local`` provision plugin and the default scripts path is
    used instead. See issue #4081 for details.




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



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


ansible
    Ansible configuration for individual guest inventory generation.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_LOCAL_ANSIBLE``

    In plan metadata:

    .. code-block:: yaml

       ansible:

    On command-line:

    .. code-block:: shell

       --ansible ...
       export TMT_PLUGIN_PROVISION_LOCAL_ANSIBLE=...



become
    Whether to run tests and shell scripts in prepare and
    finish steps with ``sudo``.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_LOCAL_BECOME``

    In plan metadata:

    .. code-block:: yaml

       become: true|false

    On command-line:

    .. code-block:: shell

       --become
       export TMT_PLUGIN_PROVISION_LOCAL_BECOME=1|0


environment
    Environment variables to be defined for this guest. These will be available
    during test execution and can be used to customize behavior on a per-guest basis.
    Note that variables defined here can be overridden by test-level environment variables.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_LOCAL_ENVIRONMENT``

    In plan metadata:

    .. code-block:: yaml

       environment: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --environment KEY=VALUE
       export TMT_PLUGIN_PROVISION_LOCAL_ENVIRONMENT=KEY=VALUE



hardware
    Hardware requirements the provisioned guest must satisfy.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_LOCAL_HARDWARE``

    In plan metadata:

    .. code-block:: yaml

       hardware: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --hardware KEY=VALUE
       export TMT_PLUGIN_PROVISION_LOCAL_HARDWARE=KEY=VALUE



role
    Marks guests with the same purpose so that common actions
    can be applied to all such guests at once.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_LOCAL_ROLE``

    In plan metadata:

    .. code-block:: yaml

       role: NAME


    On command-line:

    .. code-block:: shell

       --role NAME
       export TMT_PLUGIN_PROVISION_LOCAL_ROLE=NAME



----


.. _/plugins/provision/mock:

mock
----



.. 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.

Use the mock tool for the test execution.

Tests will be executed inside a mock buildroot.

.. warning::

    This plugin requires the ``--feeling-safe`` option or
    the ``TMT_FEELING_SAFE=1`` environment variable defined.
    While it is roughly as safe as ``container`` provisioning,
    it has access to local filesystem.

Using the plugin:

.. code-block:: yaml

    provision:
        how: mock
        root: fedora-rawhide-x86_64

.. code-block:: shell

    provision --how mock --root fedora-rawhide-x86_64

.. note::

    Neither hard nor soft reboot is supported.

.. note::

   Make sure ``mock`` package is installed.



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



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


ansible
    Ansible configuration for individual guest inventory generation.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_MOCK_ANSIBLE``

    In plan metadata:

    .. code-block:: yaml

       ansible:

    On command-line:

    .. code-block:: shell

       --ansible ...
       export TMT_PLUGIN_PROVISION_MOCK_ANSIBLE=...



become
    Whether to run tests and shell scripts in prepare and
    finish steps with ``sudo``.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_MOCK_BECOME``

    In plan metadata:

    .. code-block:: yaml

       become: true|false

    On command-line:

    .. code-block:: shell

       --become
       export TMT_PLUGIN_PROVISION_MOCK_BECOME=1|0


environment
    Environment variables to be defined for this guest. These will be available
    during test execution and can be used to customize behavior on a per-guest basis.
    Note that variables defined here can be overridden by test-level environment variables.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_MOCK_ENVIRONMENT``

    In plan metadata:

    .. code-block:: yaml

       environment: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --environment KEY=VALUE
       export TMT_PLUGIN_PROVISION_MOCK_ENVIRONMENT=KEY=VALUE



hardware
    Hardware requirements the provisioned guest must satisfy.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_MOCK_HARDWARE``

    In plan metadata:

    .. code-block:: yaml

       hardware: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --hardware KEY=VALUE
       export TMT_PLUGIN_PROVISION_MOCK_HARDWARE=KEY=VALUE



role
    Marks guests with the same purpose so that common actions
    can be applied to all such guests at once.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_MOCK_ROLE``

    In plan metadata:

    .. code-block:: yaml

       role: NAME


    On command-line:

    .. code-block:: shell

       --role NAME
       export TMT_PLUGIN_PROVISION_MOCK_ROLE=NAME



root
    Mock chroot configuration file.
    The `--root` flag to be passed to the mock process.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_MOCK_ROOT``

    In plan metadata:

    .. code-block:: yaml

       root: ROOT


    On command-line:

    .. code-block:: shell

       --root ROOT
       export TMT_PLUGIN_PROVISION_MOCK_ROOT=ROOT



rootdir
    The path for where the chroot should be built.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_MOCK_ROOTDIR``

    In plan metadata:

    .. code-block:: yaml

       rootdir: ROOTDIR


    On command-line:

    .. code-block:: shell

       --rootdir ROOTDIR
       export TMT_PLUGIN_PROVISION_MOCK_ROOTDIR=ROOTDIR



----


.. _/plugins/provision/virtual.testcloud:

virtual.testcloud
-----------------



.. 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.

Local virtual machine using ``testcloud`` library.
Testcloud takes care of downloading an image and
making necessary changes to it for optimal experience
(such as disabling ``UseDNS`` and ``GSSAPI`` for SSH).

Minimal config which uses the latest Fedora image:

.. code-block:: yaml

    provision:
        how: virtual

Here's a full config example:

.. code-block:: yaml

    # Provision a virtual machine from a specific QCOW2 file,
    # using specific memory and disk settings, using the fedora user,
    # and using sudo to run scripts.
    provision:
        how: virtual
        image: https://mirror.vpsnet.com/fedora/linux/releases/41/Cloud/x86_64/images/Fedora-Cloud-Base-Generic-41-1.4.x86_64.qcow2
        user: fedora
        become: true
        # in MB
        memory: 2048
        # in GB
        disk: 30

Images
^^^^^^

As the image use ``fedora`` for the latest released Fedora compose,
``fedora-rawhide`` for the latest Rawhide compose, short aliases such as
``fedora-32``, ``f-32`` or ``f32`` for specific release or a full url to
the qcow2 image for example from https://kojipkgs.fedoraproject.org/compose/.

Short names are also provided for ``centos``, ``centos-stream``, ``alma``,
``rocky``, ``oracle``, ``debian`` and ``ubuntu`` (e.g. ``centos-8`` or ``c8``).

.. note::

    The non-rpm distros are not fully supported yet in tmt as
    the package installation is performed solely using ``dnf``/``yum``
    and ``rpm``.
    But you should be able the login to the provisioned guest and start
    experimenting. Full support is coming in the future :)

Supported Fedora CoreOS images are:

* ``fedora-coreos``
* ``fedora-coreos-stable``
* ``fedora-coreos-testing``
* ``fedora-coreos-next``

Use the full path for images stored on local disk, for example:

.. code-block:: shell

    /var/tmp/images/Fedora-Cloud-Base-31-1.9.x86_64.qcow2

In addition to the qcow2 format, Vagrant boxes can be used as well,
testcloud will take care of unpacking the image for you.

Reboot
^^^^^^

To trigger hard reboot of a guest, plugin uses testcloud API. It is
also used to trigger soft reboot unless a custom reboot command was
specified via ``tmt-reboot -c ...``.

Console
^^^^^^^

The full console log is available, after the guest is booted, in the
``logs`` directory under the provision step workdir, for example:
``plan/provision/client/logs/console.txt``. Enable verbose mode
using ``-vv`` to get the full path printed to the terminal for easy
investigation.

.. note::

   Make sure ``testcloud`` and ``libvirt`` packages are installed and configured, they are
   required for VM-backed guests provided by ``provision/virtual.testcloud`` plugin.

   * Users who installed tmt from system repositories should install ``tmt+provision-virtual``
     package.
   * Users who installed tmt from PyPI should also install ``tmt+provision-virtual`` package,
     as it will install required system dependencies. After doing so, they should install
     ``tmt[provision-virtual]`` extra.



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



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


ansible
    Ansible configuration for individual guest inventory generation.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ANSIBLE``

    In plan metadata:

    .. code-block:: yaml

       ansible:

    On command-line:

    .. code-block:: shell

       --ansible ...
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ANSIBLE=...



arch
    What architecture to virtualize, host arch by default.

    Default: ``x86_64``

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ARCH``

    In plan metadata:

    .. code-block:: yaml

       arch: x86_64|aarch64|s390x|ppc64le


    On command-line:

    .. code-block:: shell

       --arch 'x86_64|aarch64|s390x|ppc64le'
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ARCH='x86_64|aarch64|s390x|ppc64le'



become
    Whether to run tests and shell scripts in prepare and
    finish steps with ``sudo``.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_BECOME``

    In plan metadata:

    .. code-block:: yaml

       become: true|false

    On command-line:

    .. code-block:: shell

       --become
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_BECOME=1|0


connection
    What session type to use, 'session' by default.

    Default: ``session``

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_CONNECTION``

    In plan metadata:

    .. code-block:: yaml

       connection: session|system


    On command-line:

    .. code-block:: shell

       --connection 'session|system'
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_CONNECTION='session|system'



disk
    Specify disk size in GB, 10 GB by default.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_DISK``

    In plan metadata:

    .. code-block:: yaml

       disk: SIZE


    On command-line:

    .. code-block:: shell

       --disk SIZE
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_DISK=SIZE



environment
    Environment variables to be defined for this guest. These will be available
    during test execution and can be used to customize behavior on a per-guest basis.
    Note that variables defined here can be overridden by test-level environment variables.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ENVIRONMENT``

    In plan metadata:

    .. code-block:: yaml

       environment: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --environment KEY=VALUE
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ENVIRONMENT=KEY=VALUE



hardware
    Hardware requirements the provisioned guest must satisfy.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_HARDWARE``

    In plan metadata:

    .. code-block:: yaml

       hardware: KEY=VALUE


    On command-line:

    .. code-block:: shell

       --hardware KEY=VALUE
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_HARDWARE=KEY=VALUE



image
    Select image to be used. Provide a short name, full path to a local file
    or a complete url.

    Default: ``fedora``

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_IMAGE``

    In plan metadata:

    .. code-block:: yaml

       image: IMAGE


    On command-line:

    .. code-block:: shell

       --image IMAGE
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_IMAGE=IMAGE



key
    Private key to use as SSH identity for key-based
    authentication.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_KEY``

    In plan metadata:

    .. code-block:: yaml

       key: PATH


    On command-line:

    .. code-block:: shell

       --key PATH
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_KEY=PATH



list-local-images
    List locally available images.

    Default: ``false``

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_LIST_LOCAL_IMAGES``

    In plan metadata:

    .. code-block:: yaml

       list-local-images: true|false

    On command-line:

    .. code-block:: shell

       --list-local-images
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_LIST_LOCAL_IMAGES=1|0


memory
    Set available memory in MB, 2048 MB by default.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_MEMORY``

    In plan metadata:

    .. code-block:: yaml

       memory: SIZE


    On command-line:

    .. code-block:: shell

       --memory SIZE
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_MEMORY=SIZE



password
    Password to use for password-based authentication.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_PASSWORD``

    In plan metadata:

    .. code-block:: yaml

       password: PASSWORD


    On command-line:

    .. code-block:: shell

       --password PASSWORD
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_PASSWORD=PASSWORD



port
    Port to use for SSH connections instead of the default
    one.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_PORT``

    In plan metadata:

    .. code-block:: yaml

       port: PORT


    On command-line:

    .. code-block:: shell

       --port PORT
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_PORT=PORT



role
    Marks guests with the same purpose so that common actions
    can be applied to all such guests at once.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ROLE``

    In plan metadata:

    .. code-block:: yaml

       role: NAME


    On command-line:

    .. code-block:: shell

       --role NAME
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ROLE=NAME



ssh-option
    Additional SSH option. Value is passed to the ``-o``
    option of ``ssh``, see ``ssh_config(5)`` for supported
    options. Can be specified multiple times.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_SSH_OPTION``

    In plan metadata:

    .. code-block:: yaml

       ssh-option: OPTION


    On command-line:

    .. code-block:: shell

       --ssh-option OPTION
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_SSH_OPTION=OPTION



stop-retries
    Number of attempts to stop a VM.

    Default: ``10``

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_STOP_RETRIES``

    In plan metadata:

    .. code-block:: yaml

       stop-retries: N


    On command-line:

    .. code-block:: shell

       --stop-retries N
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_STOP_RETRIES=N



stop-retry-delay
    Time to wait between attempts to stop a VM.

    Default: ``1``

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_STOP_RETRY_DELAY``

    In plan metadata:

    .. code-block:: yaml

       stop-retry-delay: SECONDS


    On command-line:

    .. code-block:: shell

       --stop-retry-delay SECONDS
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_STOP_RETRY_DELAY=SECONDS



user
    A username to use for all guest operations.

    Default: ``root``

    Environment variable: ``TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_USER``

    In plan metadata:

    .. code-block:: yaml

       user: NAME


    On command-line:

    .. code-block:: shell

       --user NAME
       export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_USER=NAME
