22

✏️ Editing: virt.py

"""
Work with virtual machines managed by libvirt

:depends:
    * libvirt Python module
    * libvirt client
    * qemu-img
    * grep

Connection
==========

The connection to the virtualization host can be either setup in the minion configuration,
pillar data or overridden for each individual call.

By default, the libvirt connection URL will be guessed: the first available libvirt
hypervisor driver will be used. This can be overridden like this:

.. code-block:: yaml

virt:
      connection:
        uri: lxc:///

If the connection requires an authentication like for ESXi, this can be defined in the
minion pillar data like this:

.. code-block:: yaml

virt:
      connection:
        uri: esx://10.1.1.101/?no_verify=1&auto_answer=1
        auth:
          username: user
          password: secret

Connecting with SSH protocol
----------------------------

Libvirt can connect to remote hosts using SSH using one of the ``ssh``, ``libssh`` and
``libssh2`` transports. Note that ``libssh2`` is likely to fail as it doesn't read the
``known_hosts`` file. Libvirt may also have been built without ``libssh`` or ``libssh2``
support.

To use the SSH transport, on the minion setup an SSH agent with a key authorized on
the remote libvirt machine.

Per call connection setup
-------------------------

.. versionadded:: 2019.2.0

All the calls requiring the libvirt connection configuration as mentioned above can
override this configuration using ``connection``, ``username`` and ``password`` parameters.

This means that the following will list the domains on the local LXC libvirt driver,
whatever the ``virt:connection`` is.

.. code-block:: bash

salt 'hypervisor' virt.list_domains connection=lxc:///

The calls not using the libvirt connection setup are:

- ``seed_non_shared_migrate``
- ``virt_type``
- ``is_*hyper``
- all migration functions

- `libvirt ESX URI format <http://libvirt.org/drvesx.html#uriformat>`_
- `libvirt URI format <http://libvirt.org/uri.html#URI_config>`_
- `libvirt authentication configuration <http://libvirt.org/auth.html#Auth_client_config>`_

Units
==========
.. _virt-units:
.. rubric:: Units specification
.. versionadded:: 3002

The string should contain a number optionally followed
by a unit. The number may have a decimal fraction. If
the unit is not given then MiB are set by default.
Units can optionally be given in IEC style (such as MiB),
although the standard single letter style (such as M) is
more convenient.

Valid units include:

========== =====    ==========  ==========  ======
Standard   IEC      Standard    IEC
  Unit     Unit     Name        Name        Factor
========== =====    ==========  ==========  ======
    B               Bytes                   1
    K       KiB     Kilobytes   Kibibytes   2**10
    M       MiB     Megabytes   Mebibytes   2**20
    G       GiB     Gigabytes   Gibibytes   2**30
    T       TiB     Terabytes   Tebibytes   2**40
    P       PiB     Petabytes   Pebibytes   2**50
    E       EiB     Exabytes    Exbibytes   2**60
    Z       ZiB     Zettabytes  Zebibytes   2**70
    Y       YiB     Yottabytes  Yobibytes   2**80
========== =====    ==========  ==========  ======

Additional decimal based units:

======  =======
Unit     Factor
======  =======
KB      10**3
MB      10**6
GB      10**9
TB      10**12
PB      10**15
EB      10**18
ZB      10**21
YB      10**24
======  =======
"""

# Special Thanks to Michael Dehann, many of the concepts, and a few structures
# of his in the virt func module have been used

import base64
import collections
import copy
import datetime
import logging
import os
import re
import shutil
import string  # pylint: disable=deprecated-module
import subprocess
import sys
import time
import urllib.parse
from xml.etree import ElementTree
from xml.sax import saxutils

import jinja2.exceptions

import salt.utils.data
import salt.utils.files
import salt.utils.json
import salt.utils.path
import salt.utils.stringutils
import salt.utils.templates
import salt.utils.virt
import salt.utils.xmlutil as xmlutil
import salt.utils.yaml
from salt._compat import ipaddress
from salt.exceptions import CommandExecutionError, SaltInvocationError

try:
    import libvirt  # pylint: disable=import-error

# pylint: disable=no-name-in-module
    from libvirt import libvirtError

# pylint: enable=no-name-in-module

HAS_LIBVIRT = True
except ImportError:
    HAS_LIBVIRT = False

log = logging.getLogger(__name__)

# Set up template environment
JINJA = jinja2.Environment(
    loader=jinja2.FileSystemLoader(
        os.path.join(salt.utils.templates.TEMPLATE_DIRNAME, "virt")
    )
)

CACHE_DIR = "/var/lib/libvirt/saltinst"

VIRT_STATE_NAME_MAP = {
    0: "running",
    1: "running",
    2: "running",
    3: "paused",
    4: "shutdown",
    5: "shutdown",
    6: "crashed",
}

def __virtual__():
    if not HAS_LIBVIRT:
        return (False, "Unable to locate or import python libvirt library.")
    return "virt"

def __get_request_auth(username, password):
    """
    Get libvirt.openAuth callback with username, password values overriding
    the configuration ones.
    """

# pylint: disable=unused-argument
    def __request_auth(credentials, user_data):
        """Callback method passed to libvirt.openAuth().

The credentials argument is a list of credentials that libvirt
        would like to request. An element of this list is a list containing
        5 items (4 inputs, 1 output):
          - the credential type, e.g. libvirt.VIR_CRED_AUTHNAME
          - a prompt to be displayed to the user
          - a challenge
          - a default result for the request
          - a place to store the actual result for the request

The user_data argument is currently not set in the openAuth call.
        """
        for credential in credentials:
            if credential[0] == libvirt.VIR_CRED_AUTHNAME:
                credential[4] = (
                    username
                    if username
                    else __salt__["config.get"](
                        "virt:connection:auth:username", credential[3]
                    )
                )
            elif credential[0] == libvirt.VIR_CRED_NOECHOPROMPT:
                credential[4] = (
                    password
                    if password
                    else __salt__["config.get"](
                        "virt:connection:auth:password", credential[3]
                    )
                )
            else:
                log.info("Unhandled credential type: %s", credential[0])
        return 0

def __get_conn(**kwargs):
    """
    Detects what type of dom this node is and attempts to connect to the
    correct hypervisor via libvirt.

:param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

"""
    # This has only been tested on kvm and xen, it needs to be expanded to
    # support all vm layers supported by libvirt
    # Connection string works on bhyve, but auth is not tested.

username = kwargs.get("username", None)
    password = kwargs.get("password", None)
    conn_str = kwargs.get("connection", None)
    if not conn_str:
        conn_str = __salt__["config.get"]("virt:connection:uri", conn_str)

try:
        auth_types = [
            libvirt.VIR_CRED_AUTHNAME,
            libvirt.VIR_CRED_NOECHOPROMPT,
            libvirt.VIR_CRED_ECHOPROMPT,
            libvirt.VIR_CRED_PASSPHRASE,
            libvirt.VIR_CRED_EXTERNAL,
        ]
        conn = libvirt.openAuth(
            conn_str, [auth_types, __get_request_auth(username, password), None], 0
        )
    except Exception:  # pylint: disable=broad-except
        raise CommandExecutionError(
            "Sorry, {} failed to open a connection to the hypervisor "
            "software at {}".format(__grains__["fqdn"], conn_str)
        )
    return conn

def _get_domain(conn, *vms, **kwargs):
    """
    Return a domain object for the named VM or return domain object for all VMs.

:params conn: libvirt connection object
    :param vms: list of domain names to look for
    :param iterable: True to return an array in all cases
    """
    ret = list()
    lookup_vms = list()

all_vms = []
    if kwargs.get("active", True):
        for id_ in conn.listDomainsID():
            all_vms.append(conn.lookupByID(id_).name())

if kwargs.get("inactive", True):
        for id_ in conn.listDefinedDomains():
            all_vms.append(id_)

if vms and not all_vms:
        raise CommandExecutionError("No virtual machines found.")

if vms:
        for name in vms:
            if name not in all_vms:
                raise CommandExecutionError(f'The VM "{name}" is not present')
            else:
                lookup_vms.append(name)
    else:
        lookup_vms = list(all_vms)

for name in lookup_vms:
        ret.append(conn.lookupByName(name))

return len(ret) == 1 and not kwargs.get("iterable") and ret[0] or ret

def _parse_qemu_img_info(info):
    """
    Parse qemu-img info JSON output into disk infos dictionary
    """
    raw_infos = salt.utils.json.loads(info)
    disks = []
    for disk_infos in raw_infos:
        disk = {
            "file": disk_infos["filename"],
            "file format": disk_infos["format"],
            "disk size": disk_infos["actual-size"],
            "virtual size": disk_infos["virtual-size"],
            "cluster size": (
                disk_infos["cluster-size"] if "cluster-size" in disk_infos else None
            ),
        }

if "full-backing-filename" in disk_infos.keys():
            disk["backing file"] = format(disk_infos["full-backing-filename"])

if "snapshots" in disk_infos.keys():
            disk["snapshots"] = [
                {
                    "id": snapshot["id"],
                    "tag": snapshot["name"],
                    "vmsize": snapshot["vm-state-size"],
                    "date": datetime.datetime.fromtimestamp(
                        float(
                            "{}.{}".format(snapshot["date-sec"], snapshot["date-nsec"])
                        )
                    ).isoformat(),
                    "vmclock": datetime.datetime.utcfromtimestamp(
                        float(
                            "{}.{}".format(
                                snapshot["vm-clock-sec"], snapshot["vm-clock-nsec"]
                            )
                        )
                    )
                    .time()
                    .isoformat(),
                }
                for snapshot in disk_infos["snapshots"]
            ]
        disks.append(disk)

for disk in disks:
        if "backing file" in disk.keys():
            candidates = [
                info
                for info in disks
                if "file" in info.keys() and info["file"] == disk["backing file"]
            ]
            if candidates:
                disk["backing file"] = candidates[0]

return disks[0]

def _get_uuid(dom):
    """
    Return a uuid from the named vm

CLI Example:

.. code-block:: bash

salt '*' virt.get_uuid <domain>
    """
    return ElementTree.fromstring(get_xml(dom)).find("uuid").text

def _get_on_poweroff(dom):
    """
    Return `on_poweroff` setting from the named vm

CLI Example:

.. code-block:: bash

salt '*' virt.get_on_restart <domain>
    """
    node = ElementTree.fromstring(get_xml(dom)).find("on_poweroff")
    return node.text if node is not None else ""

def _get_on_reboot(dom):
    """
    Return `on_reboot` setting from the named vm

CLI Example:

.. code-block:: bash

salt '*' virt.get_on_reboot <domain>
    """
    node = ElementTree.fromstring(get_xml(dom)).find("on_reboot")
    return node.text if node is not None else ""

def _get_on_crash(dom):
    """
    Return `on_crash` setting from the named vm

CLI Example:

.. code-block:: bash

salt '*' virt.get_on_crash <domain>
    """
    node = ElementTree.fromstring(get_xml(dom)).find("on_crash")
    return node.text if node is not None else ""

def _get_nics(dom):
    """
    Get domain network interfaces from a libvirt domain object.
    """
    nics = {}
    # Don't expose the active configuration since it may be changed by libvirt
    doc = ElementTree.fromstring(dom.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE))
    for iface_node in doc.findall("devices/interface"):
        nic = {}
        nic["type"] = iface_node.get("type")
        for v_node in iface_node:
            if v_node.tag == "mac":
                nic["mac"] = v_node.get("address")
            if v_node.tag == "model":
                nic["model"] = v_node.get("type")
            if v_node.tag == "target":
                nic["target"] = v_node.get("dev")
            # driver, source, and match can all have optional attributes
            if re.match("(driver|source|address)", v_node.tag):
                temp = {}
                for key, value in v_node.attrib.items():
                    temp[key] = value
                nic[v_node.tag] = temp
            # virtualport needs to be handled separately, to pick up the
            # type attribute of the virtualport itself
            if v_node.tag == "virtualport":
                temp = {}
                temp["type"] = v_node.get("type")
                for key, value in v_node.attrib.items():
                    temp[key] = value
                nic["virtualport"] = temp
        if "mac" not in nic:
            continue
        nics[nic["mac"]] = nic
    return nics

def _get_graphics(dom):
    """
    Get domain graphics from a libvirt domain object.
    """
    out = {
        "autoport": "None",
        "keymap": "None",
        "listen": "None",
        "port": "None",
        "type": "None",
    }
    doc = ElementTree.fromstring(dom.XMLDesc(0))
    for g_node in doc.findall("devices/graphics"):
        for key, value in g_node.attrib.items():
            out[key] = value
    return out

def _get_loader(dom):
    """
    Get domain loader from a libvirt domain object.
    """
    out = {"path": "None"}
    doc = ElementTree.fromstring(dom.XMLDesc(0))
    for g_node in doc.findall("os/loader"):
        out["path"] = g_node.text
        for key, value in g_node.attrib.items():
            out[key] = value
    return out

def _get_disks(conn, dom):
    """
    Get domain disks from a libvirt domain object.
    """
    disks = {}
    doc = ElementTree.fromstring(dom.XMLDesc(0))
    # Get the path, pool, volume name of each volume we can
    all_volumes = _get_all_volumes_paths(conn)
    for elem in doc.findall("devices/disk"):
        source = elem.find("source")
        if source is None:
            continue
        target = elem.find("target")
        driver = elem.find("driver")
        if target is None:
            continue
        qemu_target = None
        extra_properties = None
        if "dev" in target.attrib:
            disk_type = elem.get("type")

def _get_disk_volume_data(pool_name, volume_name):
                qemu_target = f"{pool_name}/{volume_name}"
                pool = conn.storagePoolLookupByName(pool_name)
                extra_properties = {}
                try:
                    vol = pool.storageVolLookupByName(volume_name)
                    vol_info = vol.info()
                    extra_properties = {
                        "virtual size": vol_info[1],
                        "disk size": vol_info[2],
                    }

_nodes = elem.findall(  # pylint: disable=cell-var-from-loop
                        ".//backingStore[source]"
                    )
                    backing_files = [
                        {
                            "file": node.find("source").get("file"),
                            "file format": node.find("format").get("type"),
                        }
                        for node in _nodes
                    ]

if backing_files:
                        # We had the backing files in a flat list, nest them again.
                        extra_properties["backing file"] = backing_files[0]
                        parent = extra_properties["backing file"]
                        for sub_backing_file in backing_files[1:]:
                            parent["backing file"] = sub_backing_file
                            parent = sub_backing_file

else:
                        # In some cases the backing chain is not displayed by the domain definition
                        # Try to see if we have some of it in the volume definition.
                        vol_desc = ElementTree.fromstring(vol.XMLDesc())
                        backing_path = vol_desc.find("./backingStore/path")
                        backing_format = vol_desc.find("./backingStore/format")
                        if backing_path is not None:
                            extra_properties["backing file"] = {
                                "file": backing_path.text
                            }
                            if backing_format is not None:
                                extra_properties["backing file"]["file format"] = (
                                    backing_format.get("type")
                                )
                except libvirt.libvirtError:
                    # The volume won't be found if the pool is not started, just output less infos
                    log.info(
                        "Couldn't extract all volume informations: pool is likely not"
                        " running or refreshed"
                    )
                return (qemu_target, extra_properties)

if disk_type == "file":
                qemu_target = source.get("file", "")
                if qemu_target.startswith("/dev/zvol/"):
                    disks[target.get("dev")] = {"file": qemu_target, "zfs": True}
                    continue

if qemu_target in all_volumes:
                    # If the qemu_target is a known path, output a volume
                    volume = all_volumes[qemu_target]
                    qemu_target, extra_properties = _get_disk_volume_data(
                        volume["pool"], volume["name"]
                    )
                elif elem.get("device", "disk") != "cdrom":
                    # Extract disk sizes, snapshots, backing files
                    try:
                        process = subprocess.Popen(
                            [
                                "qemu-img",
                                "info",
                                "-U",
                                "--output",
                                "json",
                                "--backing-chain",
                                qemu_target,
                            ],
                            shell=False,
                            stdout=subprocess.PIPE,
                            stderr=subprocess.PIPE,
                        )
                        stdout, stderr = process.communicate()
                        if process.returncode == 0:
                            qemu_output = salt.utils.stringutils.to_str(stdout)
                            output = _parse_qemu_img_info(qemu_output)
                            extra_properties = output
                        else:
                            extra_properties = {"error": stderr}
                    except FileNotFoundError:
                        extra_properties = {"error": "qemu-img not found"}
            elif disk_type == "block":
                qemu_target = source.get("dev", "")
                # If the qemu_target is a known path, output a volume
                if qemu_target in all_volumes:
                    volume = all_volumes[qemu_target]
                    qemu_target, extra_properties = _get_disk_volume_data(
                        volume["pool"], volume["name"]
                    )
            elif disk_type == "network":
                qemu_target = source.get("protocol")
                source_name = source.get("name")
                if source_name:
                    qemu_target = f"{qemu_target}:{source_name}"

# Reverse the magic for the rbd and gluster pools
                if source.get("protocol") in ["rbd", "gluster"]:
                    for pool_i in conn.listAllStoragePools():
                        pool_i_xml = ElementTree.fromstring(pool_i.XMLDesc())
                        name_node = pool_i_xml.find("source/name")
                        if name_node is not None and source_name.startswith(
                            f"{name_node.text}/"
                        ):
                            qemu_target = "{}{}".format(
                                pool_i.name(), source_name[len(name_node.text) :]
                            )
                            break

# Reverse the magic for cdroms with remote URLs
                if elem.get("device", "disk") == "cdrom":
                    host_node = source.find("host")
                    if host_node is not None:
                        hostname = host_node.get("name")
                        port = host_node.get("port")
                        qemu_target = urllib.parse.urlunparse(
                            (
                                source.get("protocol"),
                                f"{hostname}:{port}" if port else hostname,
                                source_name,
                                "",
                                saxutils.unescape(source.get("query", "")),
                                "",
                            )
                        )
            elif disk_type == "volume":
                pool_name = source.get("pool")
                volume_name = source.get("volume")
                qemu_target, extra_properties = _get_disk_volume_data(
                    pool_name, volume_name
                )

if not qemu_target:
                continue

disk = {
                "file": qemu_target,
                "type": elem.get("device"),
            }
            if driver is not None and "type" in driver.attrib:
                disk["file format"] = driver.get("type")
            if extra_properties:
                disk.update(extra_properties)

disks[target.get("dev")] = disk
    return disks

def _libvirt_creds():
    """
    Returns the user and group that the disk images should be owned by
    """
    g_cmd = ["grep", "^\\s*group", "/etc/libvirt/qemu.conf"]
    u_cmd = ["grep", "^\\s*user", "/etc/libvirt/qemu.conf"]
    try:
        stdout = subprocess.Popen(g_cmd, stdout=subprocess.PIPE).communicate()[0]
        group = salt.utils.stringutils.to_str(stdout).split('"')[1]
    except IndexError:
        group = "root"
    try:
        stdout = subprocess.Popen(u_cmd, stdout=subprocess.PIPE).communicate()[0]
        user = salt.utils.stringutils.to_str(stdout).split('"')[1]
    except IndexError:
        user = "root"
    return {"user": user, "group": group}

def _migrate(dom, dst_uri, **kwargs):
    """
    Migrate the domain object from its current host to the destination
    host given by URI.

:param dom: domain object to migrate
    :param dst_uri: destination URI
    :param kwargs:
        - live:            Use live migration. Default value is True.
        - persistent:      Leave the domain persistent on destination host.
                           Default value is True.
        - undefinesource:  Undefine the domain on the source host.
                           Default value is True.
        - offline:         If set to True it will migrate the domain definition
                           without starting the domain on destination and without
                           stopping it on source host. Default value is False.
        - max_bandwidth:   The maximum bandwidth (in MiB/s) that will be used.
        - max_downtime:    Set maximum tolerable downtime for live-migration.
                           The value represents a number of milliseconds the guest
                           is allowed to be down at the end of live migration.
        - parallel_connections: Specify a number of parallel network connections
                           to be used to send memory pages to the destination host.
        - compressed:      Activate compression.
        - comp_methods:    A comma-separated list of compression methods. Supported
                           methods are "mt" and "xbzrle" and can be  used in any
                           combination. QEMU defaults to "xbzrle".
        - comp_mt_level:   Set compression level. Values are in range from 0 to 9,
                           where 1 is maximum speed and 9 is  maximum compression.
        - comp_mt_threads: Set number of compress threads on source host.
        - comp_mt_dthreads: Set number of decompress threads on target host.
        - comp_xbzrle_cache: Set the size of page cache for xbzrle compression in bytes.
        - copy_storage:    Migrate non-shared storage. It must be one of the following
                           values: all (full disk copy) or incremental (Incremental copy)
        - postcopy:        Enable the use of post-copy migration.
        - postcopy_bandwidth: The maximum bandwidth allowed in post-copy phase. (MiB/s)
        - username:        Username to connect with target host
        - password:        Password to connect with target host
    """
    flags = 0
    params = {}
    migrated_state = libvirt.VIR_DOMAIN_RUNNING_MIGRATED

if kwargs.get("live", True):
        flags |= libvirt.VIR_MIGRATE_LIVE

if kwargs.get("persistent", True):
        flags |= libvirt.VIR_MIGRATE_PERSIST_DEST

if kwargs.get("undefinesource", True):
        flags |= libvirt.VIR_MIGRATE_UNDEFINE_SOURCE

max_bandwidth = kwargs.get("max_bandwidth")
    if max_bandwidth:
        try:
            bandwidth_value = int(max_bandwidth)
        except ValueError:
            raise SaltInvocationError(f"Invalid max_bandwidth value: {max_bandwidth}")
        dom.migrateSetMaxSpeed(bandwidth_value)

max_downtime = kwargs.get("max_downtime")
    if max_downtime:
        try:
            downtime_value = int(max_downtime)
        except ValueError:
            raise SaltInvocationError(f"Invalid max_downtime value: {max_downtime}")
        dom.migrateSetMaxDowntime(downtime_value)

if kwargs.get("offline") is True:
        flags |= libvirt.VIR_MIGRATE_OFFLINE
        migrated_state = libvirt.VIR_DOMAIN_RUNNING_UNPAUSED

if kwargs.get("compressed") is True:
        flags |= libvirt.VIR_MIGRATE_COMPRESSED

comp_methods = kwargs.get("comp_methods")
    if comp_methods:
        params[libvirt.VIR_MIGRATE_PARAM_COMPRESSION] = comp_methods.split(",")

comp_options = {
        "comp_mt_level": libvirt.VIR_MIGRATE_PARAM_COMPRESSION_MT_LEVEL,
        "comp_mt_threads": libvirt.VIR_MIGRATE_PARAM_COMPRESSION_MT_THREADS,
        "comp_mt_dthreads": libvirt.VIR_MIGRATE_PARAM_COMPRESSION_MT_DTHREADS,
        "comp_xbzrle_cache": libvirt.VIR_MIGRATE_PARAM_COMPRESSION_XBZRLE_CACHE,
    }

for comp_option, param_key in comp_options.items():
        comp_option_value = kwargs.get(comp_option)
        if comp_option_value:
            try:
                params[param_key] = int(comp_option_value)
            except ValueError:
                raise SaltInvocationError(f"Invalid {comp_option} value")

parallel_connections = kwargs.get("parallel_connections")
    if parallel_connections:
        try:
            params[libvirt.VIR_MIGRATE_PARAM_PARALLEL_CONNECTIONS] = int(
                parallel_connections
            )
        except ValueError:
            raise SaltInvocationError("Invalid parallel_connections value")
        flags |= libvirt.VIR_MIGRATE_PARALLEL

if __salt__["config.get"]("virt:tunnel"):
        if parallel_connections:
            raise SaltInvocationError(
                "Parallel migration isn't compatible with tunneled migration"
            )
        flags |= libvirt.VIR_MIGRATE_PEER2PEER
        flags |= libvirt.VIR_MIGRATE_TUNNELLED

if kwargs.get("postcopy") is True:
        flags |= libvirt.VIR_MIGRATE_POSTCOPY

postcopy_bandwidth = kwargs.get("postcopy_bandwidth")
    if postcopy_bandwidth:
        try:
            postcopy_bandwidth_value = int(postcopy_bandwidth)
        except ValueError:
            raise SaltInvocationError("Invalid postcopy_bandwidth value")
        dom.migrateSetMaxSpeed(
            postcopy_bandwidth_value,
            flags=libvirt.VIR_DOMAIN_MIGRATE_MAX_SPEED_POSTCOPY,
        )

copy_storage = kwargs.get("copy_storage")
    if copy_storage:
        if copy_storage == "all":
            flags |= libvirt.VIR_MIGRATE_NON_SHARED_DISK
        elif copy_storage in ["inc", "incremental"]:
            flags |= libvirt.VIR_MIGRATE_NON_SHARED_INC
        else:
            raise SaltInvocationError("invalid copy_storage value")
    try:
        state = False
        dst_conn = __get_conn(
            connection=dst_uri,
            username=kwargs.get("username"),
            password=kwargs.get("password"),
        )
        new_dom = dom.migrate3(dconn=dst_conn, params=params, flags=flags)
        if new_dom:
            state = new_dom.state()
        dst_conn.close()
        return state and migrated_state in state
    except libvirt.libvirtError as err:
        dst_conn.close()
        raise CommandExecutionError(err.get_error_message())

def _get_volume_path(pool, volume_name):
    """
    Get the path to a volume. If the volume doesn't exist, compute its path from the pool one.
    """
    if volume_name in pool.listVolumes():
        volume = pool.storageVolLookupByName(volume_name)
        volume_xml = ElementTree.fromstring(volume.XMLDesc())
        return volume_xml.find("./target/path").text

# Get the path from the pool if the volume doesn't exist yet
    pool_xml = ElementTree.fromstring(pool.XMLDesc())
    pool_path = pool_xml.find("./target/path").text
    return pool_path + "/" + volume_name

def _disk_from_pool(conn, pool, pool_xml, volume_name):
    """
    Create a disk definition out of the pool XML and volume name.
    The aim of this function is to replace the volume-based definition when not handled by libvirt.
    It returns the disk Jinja context to be used when creating the VM
    """
    pool_type = pool_xml.get("type")
    disk_context = {}

# handle dir, fs and netfs
    if pool_type in ["dir", "netfs", "fs"]:
        disk_context["type"] = "file"
        disk_context["source_file"] = _get_volume_path(pool, volume_name)

elif pool_type in ["logical", "disk", "iscsi", "scsi"]:
        disk_context["type"] = "block"
        disk_context["format"] = "raw"
        disk_context["source_file"] = _get_volume_path(pool, volume_name)

elif pool_type in ["rbd", "gluster", "sheepdog"]:
        # libvirt can't handle rbd, gluster and sheepdog as volumes
        disk_context["type"] = "network"
        disk_context["protocol"] = pool_type
        # Copy the hosts from the pool definition
        disk_context["hosts"] = [
            {"name": host.get("name"), "port": host.get("port")}
            for host in pool_xml.findall(".//host")
        ]
        dir_node = pool_xml.find("./source/dir")
        # Gluster and RBD need pool/volume name
        name_node = pool_xml.find("./source/name")
        if name_node is not None:
            disk_context["volume"] = f"{name_node.text}/{volume_name}"
        # Copy the authentication if any for RBD
        auth_node = pool_xml.find("./source/auth")
        if auth_node is not None:
            username = auth_node.get("username")
            secret_node = auth_node.find("./secret")
            usage = secret_node.get("usage")
            if not usage:
                # Get the usage from the UUID
                uuid = secret_node.get("uuid")
                usage = conn.secretLookupByUUIDString(uuid).usageID()
            disk_context["auth"] = {
                "type": "ceph",
                "username": username,
                "usage": usage,
            }

return disk_context

def _handle_unit(s, def_unit="m"):
    """
    Handle the unit conversion, return the value in bytes
    """
    ret = salt.utils.stringutils.human_to_bytes(
        s, default_unit=def_unit, handle_metric=True
    )
    if ret == 0:
        raise SaltInvocationError("invalid number or unit")
    return ret

def nesthash(value=None):
    """
    create default dict that allows arbitrary level of nesting
    """
    return collections.defaultdict(nesthash, value or {})

def _gen_xml(
    conn,
    name,
    cpu,
    mem,
    diskp,
    nicp,
    hypervisor,
    os_type,
    arch,
    graphics=None,
    boot=None,
    boot_dev=None,
    numatune=None,
    hypervisor_features=None,
    clock=None,
    serials=None,
    consoles=None,
    stop_on_reboot=False,
    host_devices=None,
    **kwargs,
):
    """
    Generate the XML string to define a libvirt VM
    """
    context = {
        "hypervisor": hypervisor,
        "name": name,
        "hypervisor_features": hypervisor_features or {},
        "clock": clock or {},
        "on_reboot": "destroy" if stop_on_reboot else "restart",
    }

context["to_kib"] = lambda v: int(_handle_unit(v) / 1024)
    context["yesno"] = lambda v: "yes" if v else "no"

context["mem"] = nesthash()
    if isinstance(mem, int):
        context["mem"]["boot"] = mem
        context["mem"]["current"] = mem
    elif isinstance(mem, dict):
        context["mem"] = nesthash(mem)

context["cpu"] = nesthash()
    context["cputune"] = nesthash()
    if isinstance(cpu, int):
        context["cpu"]["maximum"] = str(cpu)
    elif isinstance(cpu, dict):
        context["cpu"] = nesthash(cpu)

if clock:
        offset = "utc" if clock.get("utc", True) else "localtime"
        if "timezone" in clock:
            offset = "timezone"
        context["clock"]["offset"] = offset

if hypervisor in ["qemu", "kvm"]:
        context["numatune"] = numatune if numatune else {}
        context["controller_model"] = False
    elif hypervisor == "vmware":
        # TODO: make bus and model parameterized, this works for 64-bit Linux
        context["controller_model"] = "lsilogic"

# By default, set the graphics to listen to all addresses
    if graphics:
        if "listen" not in graphics:
            graphics["listen"] = {"type": "address", "address": "0.0.0.0"}
        elif (
            "address" not in graphics["listen"]
            and graphics["listen"]["type"] == "address"
        ):
            graphics["listen"]["address"] = "0.0.0.0"

# Graphics of type 'none' means no graphics device at all
        if graphics.get("type", "none") == "none":
            graphics = None
    context["graphics"] = graphics

context["boot_dev"] = boot_dev.split() if boot_dev is not None else ["hd"]

context["boot"] = boot if boot else {}

# if efi parameter is specified, prepare os_attrib
    efi_value = context["boot"].get("efi", None) if boot else None
    if efi_value is True:
        context["boot"]["os_attrib"] = "firmware='efi'"
    elif efi_value is not None and not isinstance(efi_value, bool):
        raise SaltInvocationError("Invalid efi value")

if os_type == "xen":
        # Compute the Xen PV boot method
        if __grains__["os_family"] == "Suse":
            if not boot or not boot.get("kernel", None):
                paths = [
                    path
                    for path in ["/usr/share", "/usr/lib"]
                    if os.path.exists(path + "/grub2/x86_64-xen/grub.xen")
                ]
                if not paths:
                    raise CommandExecutionError("grub-x86_64-xen needs to be installed")
                context["boot"]["kernel"] = paths[0] + "/grub2/x86_64-xen/grub.xen"
                context["boot_dev"] = []

default_port = 23023
    default_chardev_type = "tcp"

chardev_types = ["serial", "console"]
    for chardev_type in chardev_types:
        context[chardev_type + "s"] = []
        parameter_value = locals()[chardev_type + "s"]
        if parameter_value is not None:
            for chardev in parameter_value:
                chardev_context = chardev
                chardev_context["type"] = chardev.get("type", default_chardev_type)

if chardev_context["type"] == "tcp":
                    chardev_context["port"] = chardev.get("port", default_port)
                    chardev_context["protocol"] = chardev.get("protocol", "telnet")
                context[chardev_type + "s"].append(chardev_context)

context["disks"] = []
    disk_bus_map = {"virtio": "vd", "xen": "xvd", "fdc": "fd", "ide": "hd"}
    targets = []
    for i, disk in enumerate(diskp):
        prefix = disk_bus_map.get(disk["model"], "sd")
        disk_context = {
            "device": disk.get("device", "disk"),
            "target_dev": _get_disk_target(targets, len(diskp), prefix),
            "disk_bus": disk["model"],
            "format": disk.get("format", "raw"),
            "index": str(i),
            "io": disk.get("io", "native"),
            "iothread": disk.get("iothread_id", None),
        }
        targets.append(disk_context["target_dev"])
        if disk.get("source_file"):
            url = urllib.parse.urlparse(disk["source_file"])
            if not url.scheme or not url.hostname:
                disk_context["source_file"] = disk["source_file"]
                disk_context["type"] = "file"
            elif url.scheme in ["http", "https", "ftp", "ftps", "tftp"]:
                disk_context["type"] = "network"
                disk_context["protocol"] = url.scheme
                disk_context["volume"] = url.path
                disk_context["query"] = saxutils.escape(url.query)
                disk_context["hosts"] = [{"name": url.hostname, "port": url.port}]

elif disk.get("pool"):
            disk_context["volume"] = disk["filename"]
            # If we had no source_file, then we want a volume
            pool = conn.storagePoolLookupByName(disk["pool"])
            pool_xml = ElementTree.fromstring(pool.XMLDesc())
            pool_type = pool_xml.get("type")

# For Xen VMs convert all pool types (issue #58333)
            if hypervisor == "xen" or pool_type in ["rbd", "gluster", "sheepdog"]:
                disk_context.update(
                    _disk_from_pool(conn, pool, pool_xml, disk_context["volume"])
                )

else:
                if pool_type in ["disk", "logical"]:
                    # The volume format for these types doesn't match the driver format in the VM
                    disk_context["format"] = "raw"
                disk_context["type"] = "volume"
                disk_context["pool"] = disk["pool"]

else:
            # No source and no pool is a removable device, use file type
            disk_context["type"] = "file"

if hypervisor in ["qemu", "kvm", "bhyve", "xen"]:
            disk_context["address"] = False
            disk_context["driver"] = True
        elif hypervisor in ["esxi", "vmware"]:
            disk_context["address"] = True
            disk_context["driver"] = False
        context["disks"].append(disk_context)
    context["nics"] = nicp

# Process host devices passthrough
    hostdev_context = []
    try:
        for hostdev_name in host_devices or []:
            hostdevice = conn.nodeDeviceLookupByName(hostdev_name)
            doc = ElementTree.fromstring(hostdevice.XMLDesc())
            if "pci" in hostdevice.listCaps():
                hostdev_context.append(
                    {
                        "type": "pci",
                        "domain": "0x{:04x}".format(
                            int(doc.find("./capability[@type='pci']/domain").text)
                        ),
                        "bus": "0x{:02x}".format(
                            int(doc.find("./capability[@type='pci']/bus").text)
                        ),
                        "slot": "0x{:02x}".format(
                            int(doc.find("./capability[@type='pci']/slot").text)
                        ),
                        "function": "0x{}".format(
                            doc.find("./capability[@type='pci']/function").text
                        ),
                    }
                )
            elif "usb_device" in hostdevice.listCaps():
                vendor_id = doc.find(".//vendor").get("id")
                product_id = doc.find(".//product").get("id")
                hostdev_context.append(
                    {"type": "usb", "vendor": vendor_id, "product": product_id}
                )
            # For the while we only handle pci and usb passthrough
    except libvirt.libvirtError as err:
        conn.close()
        raise CommandExecutionError(
            "Failed to get host devices: " + err.get_error_message()
        )
    context["hostdevs"] = hostdev_context

context["os_type"] = os_type
    context["arch"] = arch
    fn_ = "libvirt_domain.jinja"
    try:
        template = JINJA.get_template(fn_)
    except jinja2.exceptions.TemplateNotFound:
        log.error("Could not load template %s", fn_)
        return ""
    return template.render(**context)

def _gen_vol_xml(
    name,
    size,
    format=None,
    allocation=0,
    type=None,
    permissions=None,
    backing_store=None,
    nocow=False,
):
    """
    Generate the XML string to define a libvirt storage volume
    """
    size = int(size) * 1024  # MB
    context = {
        "type": type,
        "name": name,
        "target": {"permissions": permissions, "nocow": nocow},
        "format": format,
        "size": str(size),
        "allocation": str(int(allocation) * 1024),
        "backingStore": backing_store,
    }
    fn_ = "libvirt_volume.jinja"
    try:
        template = JINJA.get_template(fn_)
    except jinja2.exceptions.TemplateNotFound:
        log.error("Could not load template %s", fn_)
        return ""
    return template.render(**context)

def _gen_net_xml(
    name,
    bridge,
    forward,
    vport,
    tag=None,
    ip_configs=None,
    mtu=None,
    domain=None,
    nat=None,
    interfaces=None,
    addresses=None,
    physical_function=None,
    dns=None,
):
    """
    Generate the XML string to define a libvirt network
    """
    if isinstance(vport, str):
        vport_context = {"type": vport}
    else:
        vport_context = vport

if isinstance(tag, (str, int)):
        tag_context = {"tags": [{"id": tag}]}
    else:
        tag_context = tag

addresses_context = []
    if addresses:
        matches = [
            re.fullmatch(r"([0-9]+):([0-9A-Fa-f]+):([0-9A-Fa-f]+)\.([0-9])", addr)
            for addr in addresses.lower().split(" ")
        ]
        addresses_context = [
            {
                "domain": m.group(1),
                "bus": m.group(2),
                "slot": m.group(3),
                "function": m.group(4),
            }
            for m in matches
            if m
        ]

context = {
        "name": name,
        "bridge": bridge,
        "mtu": mtu,
        "domain": domain,
        "forward": forward,
        "nat": nat,
        "interfaces": interfaces.split(" ") if interfaces else [],
        "addresses": addresses_context,
        "pf": physical_function,
        "vport": vport_context,
        "vlan": tag_context,
        "dns": dns,
        "ip_configs": [
            {
                "address": ipaddress.ip_network(config["cidr"]),
                "dhcp_ranges": config.get("dhcp_ranges", []),
                "hosts": config.get("hosts", {}),
                "bootp": config.get("bootp", {}),
                "tftp": config.get("tftp"),
            }
            for config in ip_configs or []
        ],
        "yesno": lambda v: "yes" if v else "no",
    }
    fn_ = "libvirt_network.jinja"
    try:
        template = JINJA.get_template(fn_)
    except jinja2.exceptions.TemplateNotFound:
        log.error("Could not load template %s", fn_)
        return ""
    return template.render(**context)

def _gen_pool_xml(
    name,
    ptype,
    target=None,
    permissions=None,
    source_devices=None,
    source_dir=None,
    source_adapter=None,
    source_hosts=None,
    source_auth=None,
    source_name=None,
    source_format=None,
    source_initiator=None,
):
    """
    Generate the XML string to define a libvirt storage pool
    """
    hosts = [host.split(":") for host in source_hosts or []]
    source = None
    if any(
        [
            source_devices,
            source_dir,
            source_adapter,
            hosts,
            source_auth,
            source_name,
            source_format,
            source_initiator,
        ]
    ):
        source = {
            "devices": source_devices or [],
            "dir": (
                source_dir
                if source_format != "cifs" or not source_dir
                else source_dir.lstrip("/")
            ),
            "adapter": source_adapter,
            "hosts": [
                {"name": host[0], "port": host[1] if len(host) > 1 else None}
                for host in hosts
            ],
            "auth": source_auth,
            "name": source_name,
            "format": source_format,
            "initiator": source_initiator,
        }

context = {
        "name": name,
        "ptype": ptype,
        "target": {"path": target, "permissions": permissions},
        "source": source,
    }
    fn_ = "libvirt_pool.jinja"
    try:
        template = JINJA.get_template(fn_)
    except jinja2.exceptions.TemplateNotFound:
        log.error("Could not load template %s", fn_)
        return ""
    return template.render(**context)

def _gen_secret_xml(auth_type, usage, description):
    """
    Generate a libvirt secret definition XML
    """
    context = {
        "type": auth_type,
        "usage": usage,
        "description": description,
    }
    fn_ = "libvirt_secret.jinja"
    try:
        template = JINJA.get_template(fn_)
    except jinja2.exceptions.TemplateNotFound:
        log.error("Could not load template %s", fn_)
        return ""
    return template.render(**context)

def _get_images_dir():
    """
    Extract the images dir from the configuration. First attempts to
    find legacy virt.images, then tries virt:images.
    """
    img_dir = __salt__["config.get"]("virt:images")
    log.debug("Image directory from config option `virt:images` is %s", img_dir)
    return img_dir

def _zfs_image_create(
    vm_name,
    pool,
    disk_name,
    hostname_property_name,
    sparse_volume,
    disk_size,
    disk_image_name,
):
    """
    Clones an existing image, or creates a new one.

When cloning an image, disk_image_name refers to the source
    of the clone. If not specified, disk_size is used for creating
    a new zvol, and sparse_volume determines whether to create
    a thin provisioned volume.

The cloned or new volume can have a ZFS property set containing
    the vm_name. Use hostname_property_name for specifying the key
    of this ZFS property.
    """
    if not disk_image_name and not disk_size:
        raise CommandExecutionError(
            "Unable to create new disk {}, please specify"
            " the disk image name or disk size argument".format(disk_name)
        )

if not pool:
        raise CommandExecutionError(
            "Unable to create new disk {}, please specify the disk pool name".format(
                disk_name
            )
        )

destination_fs = os.path.join(pool, f"{vm_name}.{disk_name}")
    log.debug("Image destination will be %s", destination_fs)

existing_disk = __salt__["zfs.list"](name=pool)
    if "error" in existing_disk:
        raise CommandExecutionError(
            "Unable to create new disk {}. {}".format(
                destination_fs, existing_disk["error"]
            )
        )
    elif destination_fs in existing_disk:
        log.info("ZFS filesystem %s already exists. Skipping creation", destination_fs)
        blockdevice_path = os.path.join("/dev/zvol", pool, vm_name)
        return blockdevice_path

properties = {}
    if hostname_property_name:
        properties[hostname_property_name] = vm_name

if disk_image_name:
        __salt__["zfs.clone"](
            name_a=disk_image_name, name_b=destination_fs, properties=properties
        )

elif disk_size:
        __salt__["zfs.create"](
            name=destination_fs,
            properties=properties,
            volume_size=disk_size,
            sparse=sparse_volume,
        )

blockdevice_path = os.path.join("/dev/zvol", pool, f"{vm_name}.{disk_name}")
    log.debug("Image path will be %s", blockdevice_path)
    return blockdevice_path

def _qemu_image_create(disk, create_overlay=False, saltenv="base"):
    """
    Create the image file using specified disk_size or/and disk_image

Return path to the created image file
    """
    disk_size = disk.get("size", None)
    disk_image = disk.get("image", None)

if not disk_size and not disk_image:
        raise CommandExecutionError(
            "Unable to create new disk {}, please specify"
            " disk size and/or disk image argument".format(disk["filename"])
        )

img_dest = disk["source_file"]
    log.debug("Image destination will be %s", img_dest)
    img_dir = os.path.dirname(img_dest)
    log.debug("Image destination directory is %s", img_dir)
    if not os.path.exists(img_dir):
        os.makedirs(img_dir)

if disk_image:
        log.debug("Create disk from specified image %s", disk_image)
        sfn = __salt__["cp.cache_file"](disk_image, saltenv)

qcow2 = False
        if salt.utils.path.which("qemu-img"):
            res = __salt__["cmd.run"](f'qemu-img info "{sfn}"')
            imageinfo = salt.utils.yaml.safe_load(res)
            qcow2 = imageinfo["file format"] == "qcow2"
        try:
            if create_overlay and qcow2:
                log.info("Cloning qcow2 image %s using copy on write", sfn)
                __salt__["cmd.run"](
                    'qemu-img create -f qcow2 -o backing_file="{}" "{}"'.format(
                        sfn, img_dest
                    ).split()
                )
            else:
                log.debug("Copying %s to %s", sfn, img_dest)
                salt.utils.files.copyfile(sfn, img_dest)

mask = salt.utils.files.get_umask()

if disk_size and qcow2:
                log.debug("Resize qcow2 image to %sM", disk_size)
                __salt__["cmd.run"](f'qemu-img resize "{img_dest}" {disk_size}M')

log.debug("Apply umask and remove exec bit")
            mode = (0o0777 ^ mask) & 0o0666
            os.chmod(img_dest, mode)

except OSError as err:
            raise CommandExecutionError(
                f"Problem while copying image. {disk_image} - {err}"
            )

else:
        # Create empty disk
        try:
            mask = salt.utils.files.get_umask()

if disk_size:
                log.debug("Create empty image with size %sM", disk_size)
                __salt__["cmd.run"](
                    'qemu-img create -f {} "{}" {}M'.format(
                        disk.get("format", "qcow2"), img_dest, disk_size
                    )
                )
            else:
                raise CommandExecutionError(
                    "Unable to create new disk {},"
                    " please specify <size> argument".format(img_dest)
                )

log.debug("Apply umask and remove exec bit")
            mode = (0o0777 ^ mask) & 0o0666
            os.chmod(img_dest, mode)

except OSError as err:
            raise CommandExecutionError(
                f"Problem while creating volume {img_dest} - {err}"
            )

return img_dest

def _seed_image(seed_cmd, img_path, name, config, install, pub_key, priv_key):
    """
    Helper function to seed an existing image. Note that this doesn't
    handle volumes.
    """
    log.debug("Seeding image")
    __salt__[seed_cmd](
        img_path,
        id_=name,
        config=config,
        install=install,
        pub_key=pub_key,
        priv_key=priv_key,
    )

def _disk_volume_create(conn, disk, seeder=None, saltenv="base"):
    """
    Create a disk volume for use in a VM
    """
    if disk.get("overlay_image"):
        raise SaltInvocationError(
            "Disk overlay_image property is not supported when creating volumes,"
            "use backing_store_path and backing_store_format instead."
        )

pool = conn.storagePoolLookupByName(disk["pool"])

# Use existing volume if possible
    if disk["filename"] in pool.listVolumes():
        return

pool_type = ElementTree.fromstring(pool.XMLDesc()).get("type")

backing_path = disk.get("backing_store_path")
    backing_format = disk.get("backing_store_format")
    backing_store = None
    if (
        backing_path
        and backing_format
        and (disk.get("format") == "qcow2" or pool_type == "logical")
    ):
        backing_store = {"path": backing_path, "format": backing_format}

if backing_store and disk.get("image"):
        raise SaltInvocationError(
            "Using a template image with a backing store is not possible, "
            "choose either of them."
        )

vol_xml = _gen_vol_xml(
        disk["filename"],
        disk.get("size", 0),
        format=disk.get("format"),
        backing_store=backing_store,
    )
    _define_vol_xml_str(conn, vol_xml, disk.get("pool"))

if disk.get("image"):
        log.debug("Caching disk template image: %s", disk.get("image"))
        cached_path = __salt__["cp.cache_file"](disk.get("image"), saltenv)

if seeder:
            seeder(cached_path)
        _volume_upload(
            conn,
            disk["pool"],
            disk["filename"],
            cached_path,
            sparse=disk.get("format") == "qcow2",
        )

def _disk_profile(conn, profile, hypervisor, disks, vm_name):
    """
    Gather the disk profile from the config or apply the default based
    on the active hypervisor

This is the ``default`` profile for KVM/QEMU, which can be
    overridden in the configuration:

.. code-block:: yaml

virt:
          disk:
            default:
              - system:
                  size: 8192
                  format: qcow2
                  model: virtio

Example profile for KVM/QEMU with two disks, first is created
    from specified image, the second is empty:

.. code-block:: yaml

virt:
          disk:
            two_disks:
              - system:
                  size: 8192
                  format: qcow2
                  model: virtio
                  image: http://path/to/image.qcow2
              - lvm:
                  size: 32768
                  format: qcow2
                  model: virtio

The ``format`` and ``model`` parameters are optional, and will
    default to whatever is best suitable for the active hypervisor.
    """
    default = [{"system": {"size": 8192}}]
    if hypervisor == "vmware":
        overlay = {"format": "vmdk", "model": "scsi", "device": "disk"}
    elif hypervisor in ["qemu", "kvm"]:
        overlay = {"device": "disk", "model": "virtio"}
    elif hypervisor == "xen":
        overlay = {"device": "disk", "model": "xen"}
    elif hypervisor == "bhyve":
        overlay = {"format": "raw", "model": "virtio", "sparse_volume": False}
    else:
        overlay = {}

# Get the disks from the profile
    disklist = []
    if profile:
        disklist = copy.deepcopy(
            __salt__["config.get"]("virt:disk", {}).get(profile, default)
        )

# Transform the list to remove one level of dictionary and add the name as a property
        disklist = [dict(d, name=name) for disk in disklist for name, d in disk.items()]

# Merge with the user-provided disks definitions
    if disks:
        for udisk in disks:
            if "name" in udisk:
                found = [disk for disk in disklist if udisk["name"] == disk["name"]]
                if found:
                    found[0].update(udisk)
                else:
                    disklist.append(udisk)

# Get pool capabilities once to get default format later
    pool_caps = _pool_capabilities(conn)

for disk in disklist:
        # Set default model for cdrom devices before the overlay sets the wrong one
        if disk.get("device", "disk") == "cdrom" and "model" not in disk:
            disk["model"] = "ide"

# Add the missing properties that have defaults
        for key, val in overlay.items():
            if key not in disk:
                disk[key] = val

# We may have an already computed source_file (i.e. image not created by our module)
        if disk.get("source_file") and os.path.exists(disk["source_file"]):
            disk["filename"] = os.path.basename(disk["source_file"])
            if not disk.get("format"):
                disk["format"] = (
                    "qcow2" if disk.get("device", "disk") != "cdrom" else "raw"
                )
        elif vm_name and disk.get("device", "disk") == "disk":
            _fill_disk_filename(conn, vm_name, disk, hypervisor, pool_caps)

return disklist

def _fill_disk_filename(conn, vm_name, disk, hypervisor, pool_caps):
    """
    Compute the disk file name and update it in the disk value.
    """
    # Compute the filename without extension since it may not make sense for some pool types
    disk["filename"] = "{}_{}".format(vm_name, disk["name"])

# Compute the source file path
    base_dir = disk.get("pool", None)
    if hypervisor in ["qemu", "kvm", "xen"]:
        # Compute the base directory from the pool property. We may have either a path
        # or a libvirt pool name there.
        if not base_dir:
            base_dir = _get_images_dir()

# If the pool is a known libvirt one, skip the filename since a libvirt volume will be created later
        if base_dir not in conn.listStoragePools():
            # For path-based disks, keep the qcow2 default format
            if not disk.get("format"):
                disk["format"] = "qcow2"
            disk["filename"] = "{}.{}".format(disk["filename"], disk["format"])
            disk["source_file"] = os.path.join(base_dir, disk["filename"])
        else:
            if "pool" not in disk:
                disk["pool"] = base_dir
            pool_obj = conn.storagePoolLookupByName(base_dir)
            pool_xml = ElementTree.fromstring(pool_obj.XMLDesc())
            pool_type = pool_xml.get("type")

# Disk pools volume names are partition names, they need to be named based on the device name
            if pool_type == "disk":
                device = pool_xml.find("./source/device").get("path")
                all_volumes = pool_obj.listVolumes()
                if disk.get("source_file") not in all_volumes:
                    indexes = [
                        int(re.sub("[a-z]+", "", vol_name)) for vol_name in all_volumes
                    ] or [0]
                    index = min(
                        idx for idx in range(1, max(indexes) + 2) if idx not in indexes
                    )
                    disk["filename"] = f"{os.path.basename(device)}{index}"

# Is the user wanting to reuse an existing volume?
            if disk.get("source_file"):
                if not disk.get("source_file") in pool_obj.listVolumes():
                    raise SaltInvocationError(
                        "{} volume doesn't exist in pool {}".format(
                            disk.get("source_file"), base_dir
                        )
                    )
                disk["filename"] = disk["source_file"]
                del disk["source_file"]

# Get the default format from the pool capabilities
            if not disk.get("format"):
                volume_options = (
                    [
                        type_caps.get("options", {}).get("volume", {})
                        for type_caps in pool_caps.get("pool_types")
                        if type_caps["name"] == pool_type
                    ]
                    or [{}]
                )[0]
                # Still prefer qcow2 if possible
                if "qcow2" in volume_options.get("targetFormatType", []):
                    disk["format"] = "qcow2"
                else:
                    disk["format"] = volume_options.get("default_format", None)

elif hypervisor == "bhyve" and vm_name:
        disk["filename"] = "{}.{}".format(vm_name, disk["name"])
        disk["source_file"] = os.path.join(
            "/dev/zvol", base_dir or "", disk["filename"]
        )

elif hypervisor in ["esxi", "vmware"]:
        if not base_dir:
            base_dir = __salt__["config.get"]("virt:storagepool", "[0] ")
        disk["filename"] = "{}.{}".format(disk["filename"], disk["format"])
        disk["source_file"] = "{}{}".format(base_dir, disk["filename"])

def _complete_nics(interfaces, hypervisor):
    """
    Complete missing data for network interfaces.
    """

vmware_overlay = {"type": "bridge", "source": "DEFAULT", "model": "e1000"}
    kvm_overlay = {"type": "bridge", "source": "br0", "model": "virtio"}
    xen_overlay = {"type": "bridge", "source": "br0", "model": None}
    bhyve_overlay = {"type": "bridge", "source": "bridge0", "model": "virtio"}
    overlays = {
        "xen": xen_overlay,
        "kvm": kvm_overlay,
        "qemu": kvm_overlay,
        "vmware": vmware_overlay,
        "bhyve": bhyve_overlay,
    }

def _normalize_net_types(attributes):
        """
        Guess which style of definition:

bridge: br0

network: net0

type: network
            source: net0
        """
        for type_ in ["bridge", "network"]:
            if type_ in attributes:
                attributes["type"] = type_
                # we want to discard the original key
                attributes["source"] = attributes.pop(type_)

attributes["type"] = attributes.get("type", None)
        attributes["source"] = attributes.get("source", None)

def _apply_default_overlay(attributes):
        """
        Apply the default overlay to attributes
        """
        for key, value in overlays[hypervisor].items():
            if key not in attributes or not attributes[key]:
                attributes[key] = value

for interface in interfaces:
        _normalize_net_types(interface)
        if hypervisor in overlays:
            _apply_default_overlay(interface)

return interfaces

def _nic_profile(profile_name, hypervisor):
    """
    Compute NIC data based on profile
    """
    config_data = __salt__["config.get"]("virt:nic", {}).get(
        profile_name, [{"eth0": {}}]
    )

interfaces = []

# pylint: disable=invalid-name
    def append_dict_profile_to_interface_list(profile_dict):
        """
        Append dictionary profile data to interfaces list
        """
        for interface_name, attributes in profile_dict.items():
            attributes["name"] = interface_name
            interfaces.append(attributes)

# old style dicts (top-level dicts)
    #
    # virt:
    #    nic:
    #        eth0:
    #            bridge: br0
    #        eth1:
    #            network: test_net
    if isinstance(config_data, dict):
        append_dict_profile_to_interface_list(config_data)

# new style lists (may contain dicts)
    #
    # virt:
    #   nic:
    #     - eth0:
    #         bridge: br0
    #     - eth1:
    #         network: test_net
    #
    # virt:
    #   nic:
    #     - name: eth0
    #       bridge: br0
    #     - name: eth1
    #       network: test_net
    elif isinstance(config_data, list):
        for interface in config_data:
            if isinstance(interface, dict):
                if len(interface) == 1:
                    append_dict_profile_to_interface_list(interface)
                else:
                    interfaces.append(interface)

return _complete_nics(interfaces, hypervisor)

def _get_merged_nics(hypervisor, profile, interfaces=None):
    """
    Get network devices from the profile and merge uer defined ones with them.
    """
    nicp = _nic_profile(profile, hypervisor) if profile else []
    log.debug("NIC profile is %s", nicp)
    if interfaces:
        users_nics = _complete_nics(interfaces, hypervisor)
        for unic in users_nics:
            found = [nic for nic in nicp if nic["name"] == unic["name"]]
            if found:
                found[0].update(unic)
            else:
                nicp.append(unic)
        log.debug("Merged NICs: %s", nicp)
    return nicp

def _handle_remote_boot_params(orig_boot):
    """
    Checks if the boot parameters contain a remote path. If so, it will copy
    the parameters, download the files specified in the remote path, and return
    a new dictionary with updated paths containing the canonical path to the
    kernel and/or initrd

:param orig_boot: The original boot parameters passed to the init or update
    functions.
    """
    saltinst_dir = None
    new_boot = orig_boot.copy()
    keys = orig_boot.keys()
    cases = [
        {"efi"},
        {"kernel", "initrd", "efi"},
        {"kernel", "initrd", "cmdline", "efi"},
        {"loader", "nvram"},
        {"kernel", "initrd"},
        {"kernel", "initrd", "cmdline"},
        {"kernel", "initrd", "loader", "nvram"},
        {"kernel", "initrd", "cmdline", "loader", "nvram"},
    ]

if keys in cases:
        for key in keys:
            if key == "efi" and type(orig_boot.get(key)) == bool:
                new_boot[key] = orig_boot.get(key)
            elif orig_boot.get(key) is not None and salt.utils.virt.check_remote(
                orig_boot.get(key)
            ):
                if saltinst_dir is None:
                    os.makedirs(CACHE_DIR)
                    saltinst_dir = CACHE_DIR
                new_boot[key] = salt.utils.virt.download_remote(
                    orig_boot.get(key), saltinst_dir
                )
        return new_boot
    else:
        raise SaltInvocationError(
            "Invalid boot parameters,It has to follow this combination: [(kernel,"
            " initrd) or/and cmdline] or/and [(loader, nvram) or efi]"
        )

def _handle_efi_param(boot, desc):
    """
    Checks if boot parameter contains efi boolean value, if so, handles the firmware attribute.
    :param boot: The boot parameters passed to the init or update functions.
    :param desc: The XML description of that domain.
    :return: A boolean value.
    """
    efi_value = boot.get("efi", None) if boot else None
    parent_tag = desc.find("os")
    os_attrib = parent_tag.attrib

# newly defined vm without running, loader tag might not be filled yet
    if efi_value is False and os_attrib != {}:
        parent_tag.attrib.pop("firmware", None)
        return True

# check the case that loader tag might be present. This happens after the vm ran
    elif isinstance(efi_value, bool) and os_attrib == {}:
        if efi_value is True and parent_tag.find("loader") is None:
            parent_tag.set("firmware", "efi")
            return True
        if efi_value is False and parent_tag.find("loader") is not None:
            parent_tag.remove(parent_tag.find("loader"))
            parent_tag.remove(parent_tag.find("nvram"))
            return True
    elif not isinstance(efi_value, bool):
        raise SaltInvocationError("Invalid efi value")
    return False

def init(
    name,
    cpu,
    mem,
    nic="default",
    interfaces=None,
    hypervisor=None,
    start=True,  # pylint: disable=redefined-outer-name
    disk="default",
    disks=None,
    saltenv="base",
    seed=True,
    install=True,
    pub_key=None,
    priv_key=None,
    seed_cmd="seed.apply",
    graphics=None,
    os_type=None,
    arch=None,
    boot=None,
    boot_dev=None,
    numatune=None,
    hypervisor_features=None,
    clock=None,
    serials=None,
    consoles=None,
    stop_on_reboot=False,
    host_devices=None,
    **kwargs,
):
    """
    Initialize a new vm

:param name: name of the virtual machine to create
    :param cpu:
        Number of virtual CPUs to assign to the virtual machine or a dictionary with detailed information to configure
        cpu model and topology, numa node tuning, cpu tuning and iothreads allocation. The structure of the dictionary is
        documented in :ref:`init-cpu-def`.

.. code-block:: yaml

cpu:
               placement: static
               cpuset: 0-11
               current: 5
               maximum: 12
               vcpus:
                 0:
                   enabled: True
                   hotpluggable: False
                   order: 1
                 1:
                   enabled: False
                   hotpluggable: True
               match: minimum
               mode: custom
               check: full
               vendor: Intel
               model:
                 name: core2duo
                 fallback: allow
                 vendor_id: GenuineIntel
               topology:
                 sockets: 1
                 cores: 12
                 threads: 1
               cache:
                 level: 3
                 mode: emulate
               features:
                 lahf: optional
                 pcid: require
               numa:
                 0:
                    cpus: 0-3
                    memory: 1g
                    discard: True
                    distances:
                      0: 10     # sibling id : value
                      1: 21
                      2: 31
                      3: 41
                 1:
                    cpus: 4-6
                    memory: 1g
                    memAccess: shared
                    distances:
                      0: 21
                      1: 10
                      2: 21
                      3: 31
               tuning:
                    vcpupin:
                      0: 1-4,^2  # vcpuid : cpuset
                      1: 0,1
                      2: 2,3
                      3: 0,4
                    emulatorpin: 1-3
                    iothreadpin:
                      1: 5,6    # iothread id: cpuset
                      2: 7,8
                    shares: 2048
                    period: 1000000
                    quota: -1
                    global_period: 1000000
                    global_quota: -1
                    emulator_period: 1000000
                    emulator_quota: -1
                    iothread_period: 1000000
                    iothread_quota: -1
                    vcpusched:
                      - scheduler: fifo
                        priority: 1
                        vcpus: 0,3-5
                      - scheduler: rr
                        priority: 3
                    iothreadsched:
                      - scheduler: idle
                      - scheduler: batch
                        iothreads: 2,3
                    emulatorsched:
                      - scheduler: batch
                    cachetune:
                      0-3:      # vcpus set
                        0:      # cache id
                          level: 3
                          type: both
                          size: 4
                        1:
                          level: 3
                          type: both
                          size: 6
                        monitor:
                          1: 3
                          0-3: 3
                      4-5:
                        monitor:
                          4: 3  # vcpus: level
                          5: 3
                    memorytune:
                      0-3:      # vcpus set
                        0: 60   # node id: bandwidth
                      4-5:
                        0: 60
               iothreads: 4

.. versionadded:: 3003

:param mem: Amount of memory to allocate to the virtual machine in MiB. Since 3002, a dictionary can be used to
        contain detailed configuration which support memory allocation or tuning. Supported parameters are ``boot``,
        ``current``, ``max``, ``slots``, ``hard_limit``, ``soft_limit``, ``swap_hard_limit``, ``min_guarantee``,
        ``hugepages`` ,  ``nosharepages``, ``locked``, ``source``, ``access``, ``allocation`` and ``discard``. The structure
        of the dictionary is documented in  :ref:`init-mem-def`. Both decimal and binary base are supported. Detail unit
        specification is documented  in :ref:`virt-units`. Please note that the value for ``slots`` must be an integer.

.. code-block:: python

{
                'boot': 1g,
                'current': 1g,
                'max': 1g,
                'slots': 10,
                'hard_limit': '1024',
                'soft_limit': '512m',
                'swap_hard_limit': '1g',
                'min_guarantee': '512mib',
                'hugepages': [{'nodeset': '0-3,^2', 'size': '1g'}, {'nodeset': '2', 'size': '2m'}],
                'nosharepages': True,
                'locked': True,
                'source': 'file',
                'access': 'shared',
                'allocation': 'immediate',
                'discard': True
            }

.. versionchanged:: 3002

:param nic: NIC profile to use (Default: ``'default'``).
                The profile interfaces can be customized / extended with the interfaces parameter.
                If set to ``None``, no profile will be used.
    :param interfaces:
        List of dictionaries providing details on the network interfaces to create.
        These data are merged with the ones from the nic profile. The structure of
        each dictionary is documented in :ref:`init-nic-def`.

.. versionadded:: 2019.2.0
    :param hypervisor: the virtual machine type. By default the value will be computed according
                       to the virtual host capabilities.
    :param start: ``True`` to start the virtual machine after having defined it (Default: ``True``)
    :param disk: Disk profile to use (Default: ``'default'``). If set to ``None``, no profile will be used.
    :param disks: List of dictionaries providing details on the disk devices to create.
                  These data are merged with the ones from the disk profile. The structure of
                  each dictionary is documented in :ref:`init-disk-def`.

.. versionadded:: 2019.2.0
    :param saltenv: Fileserver environment (Default: ``'base'``).
                    See :mod:`cp module for more details <salt.modules.cp>`
    :param seed: ``True`` to seed the disk image. Only used when the ``image`` parameter is provided.
                 (Default: ``True``)
    :param install: install salt minion if absent (Default: ``True``)
    :param pub_key: public key to seed with (Default: ``None``)
    :param priv_key: public key to seed with (Default: ``None``)
    :param seed_cmd: Salt command to execute to seed the image. (Default: ``'seed.apply'``)
    :param graphics:
        Dictionary providing details on the graphics device to create. (Default: ``None``)
        See :ref:`init-graphics-def` for more details on the possible values.

.. versionadded:: 2019.2.0
    :param os_type:
        type of virtualization as found in the ``//os/type`` element of the libvirt definition.
        The default value is taken from the host capabilities, with a preference for ``hvm``.

.. versionadded:: 2019.2.0
    :param arch:
        architecture of the virtual machine. The default value is taken from the host capabilities,
        but ``x86_64`` is prefed over ``i686``.

.. versionadded:: 2019.2.0
    :param config: minion configuration to use when seeding.
                   See :mod:`seed module for more details <salt.modules.seed>`
    :param boot_dev: String of space-separated devices to boot from (Default: ``'hd'``)
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

:param stop_on_reboot:
        If set to ``True`` the guest will stop instead of rebooting.
        This is specially useful when creating a virtual machine with an installation cdrom or
        an autoinstallation needing a special first boot configuration.
        Defaults to ``False``

.. versionadded:: 3003

:param boot:
        Specifies kernel, initial ramdisk and kernel command line parameters for the virtual machine.
        This is an optional parameter, all of the keys are optional within the dictionary. The structure of
        the dictionary is documented in :ref:`init-boot-def`. If a remote path is provided to kernel or initrd,
        salt will handle the downloading of the specified remote file and modify the XML accordingly.
        To boot VM with UEFI, specify loader and nvram path or specify 'efi': ``True`` if your libvirtd version
        is >= 5.2.0 and QEMU >= 3.0.0.

.. versionadded:: 3000

.. code-block:: python

{
                'kernel': '/root/f8-i386-vmlinuz',
                'initrd': '/root/f8-i386-initrd',
                'cmdline': 'console=ttyS0 ks=http://example.com/f8-i386/os/',
                'loader': '/usr/share/OVMF/OVMF_CODE.fd',
                'nvram': '/usr/share/OVMF/OVMF_VARS.ms.fd'
            }

:param boot_dev:
        Space separated list of devices to boot from sorted by decreasing priority.
        Values can be ``hd``, ``fd``, ``cdrom`` or ``network``.

By default, the value will ``"hd"``.

:param numatune:
        The optional numatune element provides details of how to tune the performance of a NUMA host via controlling NUMA
        policy for domain process. The optional ``memory`` element specifies how to allocate memory for the domain process
        on a NUMA host. ``memnode`` elements can specify memory allocation policies per each guest NUMA node. The definition
        used in the dictionary can be found at :ref:`init-cpu-def`.

.. versionadded:: 3003

.. code-block:: python

{
                'memory': {'mode': 'strict', 'nodeset': '0-11'},
                'memnodes': {0: {'mode': 'strict', 'nodeset': 1}, 1: {'mode': 'preferred', 'nodeset': 2}}
            }

:param hypervisor_features:
        Enable or disable hypervisor-specific features on the virtual machine.

.. versionadded:: 3003

.. code-block:: yaml

hypervisor_features:
              kvm-hint-dedicated: True

:param clock:
        Configure the guest clock.
        The value is a dictionary with the following keys:

adjustment
            time adjustment in seconds or ``reset``

utc
            set to ``False`` to use the host local time as the guest clock. Defaults to ``True``.

timezone
            synchronize the guest to the correspding timezone

timers
            a dictionary associating the timer name with its configuration.
            This configuration is a dictionary with the properties ``track``, ``tickpolicy``,
            ``catchup``, ``frequency``, ``mode``, ``present``, ``slew``, ``threshold`` and ``limit``.
            See `libvirt time keeping documentation <https://libvirt.org/formatdomain.html#time-keeping>`_ for the possible values.

.. versionadded:: 3003

Set the clock to local time using an offset in seconds
        .. code-block:: yaml

clock:
              adjustment: 3600
              utc: False

Set the clock to a specific time zone:

.. code-block:: yaml

clock:
              timezone: CEST

Tweak guest timers:

.. code-block:: yaml

clock:
              timers:
                tsc:
                  frequency: 3504000000
                  mode: native
                rtc:
                  track: wall
                  tickpolicy: catchup
                  slew: 4636
                  threshold: 123
                  limit: 2342
                hpet:
                  present: False

:param serials:
        Dictionary providing details on the serials connection to create. (Default: ``None``)
        See :ref:`init-chardevs-def` for more details on the possible values.

.. versionadded:: 3003

:param consoles:
        Dictionary providing details on the consoles device to create. (Default: ``None``)
        See :ref:`init-chardevs-def` for more details on the possible values.

.. versionadded:: 3003

:param host_devices:
        List of host devices to passthrough to the guest.
        The value is a list of device names as provided by the :py:func:`~salt.modules.virt.node_devices` function.
        (Default: ``None``)

.. versionadded:: 3003

.. _init-cpu-def:

.. rubric:: cpu parameters definition

The cpu parameters dictionary can contain the following properties:

cpuset
        a comma-separated list of physical CPU numbers that domain process and virtual CPUs can be pinned to by default.
        eg. ``1-4,^3`` cpuset 3 is excluded.

current
        the number of virtual cpus available at startup

placement
        indicate the CPU placement mode for domain process. the value can be either ``static`` or ``auto``

vcpus
        specify the state of individual vcpu. Possible attribute for each individual vcpu include: ``id``, ``enabled``,
        ``hotpluggable`` and ``order``. Valid ``ids`` are from 0 to the maximum vCPU count minus 1. ``enabled`` takes
        boolean values which controls the state of the vcpu. ``hotpluggable`` take boolean value which controls whether
        given vCPU can be hotplugged and hotunplugged. ``order`` takes an integer value which specifies the order to add
        the online vCPUs.

match
        The cpu attribute ``match`` attribute specifies how strictly the virtual CPU provided to the guest matches the CPU
        requirements, possible values are ``minimum``, ``exact`` or ``strict``.

check
        Optional cpu attribute ``check`` attribute can be used to request a specific way of checking whether the virtual
        CPU matches the specification, possible values are ``none``, ``partial`` and ``full``.

mode
        Optional cpu attribute ``mode`` attribute may be used to make it easier to configure a guest CPU to be as close
        to host CPU as possible, possible values are ``custom``, ``host-model`` and ``host-passthrough``.

model
        specifies CPU model requested by the guest. An optional ``fallback`` attribute can be used to forbid libvirt falls
        back to the closest model supported by the hypervisor, possible values are ``allow`` or ``forbid``. ``vendor_id``
        attribute can be used to set the vendor id seen by the guest, the length must be exactly 12 characters long.

vendor
        specifies CPU vendor requested by the guest.

topology
        specifies requested topology of virtual CPU provided to the guest. Four possible attributes , ``sockets``, ``dies``,
        ``cores``, and ``threads``, accept non-zero positive integer values. They refer to the number of CPU sockets per
        NUMA node, number of dies per socket, number of cores per die, and number of threads per core, respectively.

features
        A dictionary contains a set of cpu features to fine-tune features provided by the selected CPU model. Use cpu
        feature ``name`` as the key and the ``policy`` as the value. ``policy`` Attribute takes ``force``, ``require``,
        ``optional``, ``disable`` or ``forbid``.

cache
        describes the virtual CPU cache. Optional attribute ``level`` takes an integer value which describes cache level
        ``mode`` attribute supported three possible values: ``emulate``, ``passthrough``, ``disable``

numa
        specify the guest numa topology. ``cell`` element specifies a NUMA cell or a NUMA node, ``cpus`` specifies the
        CPU or range of CPUs that are part of the node, ``memory`` specifies the size of the node memory. All cells
        should have ``id`` attribute in case referring to some cell is necessary in the code. optional attribute
        ``memAccess`` control whether the memory is to be mapped as ``shared`` or ``private``, ``discard`` attribute which
        fine tunes the discard feature for given numa node, possible values are ``True`` or ``False``.  ``distances``
        element define the distance between NUMA cells and ``sibling`` sub-element is used to specify the distance value
        between sibling NUMA cells.

vcpupin
        The optional vcpupin element specifies which of host's physical CPUs the domain vCPU will be pinned to.

emulatorpin
        The optional emulatorpin element specifies which of host physical CPUs the "emulator", a subset of a domain not
        including vCPU or iothreads will be pinned to.

iothreadpin
        The optional iothreadpin element specifies which of host physical CPUs the IOThreads will be pinned to.

shares
        The optional shares element specifies the proportional weighted share for the domain.

period
        The optional period element specifies the enforcement interval (unit: microseconds).

quota
        The optional quota element specifies the maximum allowed bandwidth (unit: microseconds).

global_period
        The optional global_period element specifies the enforcement CFS scheduler interval (unit: microseconds) for the
        whole domain in contrast with period which enforces the interval per vCPU.

global_quota
        The optional global_quota element specifies the maximum allowed bandwidth (unit: microseconds) within a period
        for the whole domain.

emulator_period
        The optional emulator_period element specifies the enforcement interval (unit: microseconds).

emulator_quota
        The optional emulator_quota element specifies the maximum allowed bandwidth (unit: microseconds) for domain's
        emulator threads (those excluding vCPUs).

iothread_period
        The optional iothread_period element specifies the enforcement interval (unit: microseconds) for IOThreads.

iothread_quota
        The optional iothread_quota element specifies the maximum allowed bandwidth (unit: microseconds) for IOThreads.

vcpusched
        specify the scheduler type for vCPUs.
        The value is a list of dictionaries with the ``scheduler`` key (values ``batch``, ``idle``, ``fifo``, ``rr``)
        and the optional ``priority`` and ``vcpus`` keys. The ``priority`` value usually is a positive integer and the
        ``vcpus`` value is a cpu set like ``1-4,^3,6`` or simply the vcpu id.

iothreadsched
        specify the scheduler type for IO threads.
        The value is a list of dictionaries with the ``scheduler`` key (values ``batch``, ``idle``, ``fifo``, ``rr``)
        and the optional ``priority`` and ``vcpus`` keys. The ``priority`` value usually is a positive integer and the
        ``vcpus`` value is a cpu set like ``1-4,^3,6`` or simply the vcpu id.

emulatorsched
        specify the scheduler type (values batch, idle, fifo, rr) for particular the emulator.
        The value is a dictionary with the ``scheduler`` key (values ``batch``, ``idle``, ``fifo``, ``rr``)
        and the optional ``priority`` and ``vcpus`` keys. The ``priority`` value usually is a positive integer.

cachetune
        Optional cachetune element can control allocations for CPU caches using the resctrl on the host.

monitor
        The optional element monitor creates the cache monitor(s) for current cache allocation.

memorytune
        Optional memorytune element can control allocations for memory bandwidth using the resctrl on the host.

iothreads
        Number of threads for supported disk devices to perform I/O requests. iothread id will be numbered from 1 to
        the provided number (Default: None).

.. _init-boot-def:

.. rubric:: Boot parameters definition

The boot parameters dictionary can contains the following properties:

kernel
        The URL or path to the kernel to run the virtual machine with.

initrd
        The URL or path to the initrd file to run the virtual machine with.

cmdline
        The parameters to pass to the kernel provided in the `kernel` property.

loader
        The path to the UEFI binary loader to use.

.. versionadded:: 3001

nvram
        The path to the UEFI data template. The file will be copied when creating the virtual machine.

.. versionadded:: 3001

efi
       A boolean value.

.. versionadded:: 3001

.. _init-mem-def:

.. rubric:: Memory parameter definition

Memory parameter can contain the following properties:

boot
        The maximum allocation of memory for the guest at boot time

current
        The actual allocation of memory for the guest

max
        The run time maximum memory allocation of the guest

slots
         specifies the number of slots available for adding memory to the guest

hard_limit
        the maximum memory the guest can use

soft_limit
        memory limit to enforce during memory contention

swap_hard_limit
        the maximum memory plus swap the guest can use

min_guarantee
        the guaranteed minimum memory allocation for the guest

hugepages
        memory allocated using ``hugepages`` instead of the normal native page size. It takes a list of
        dictionaries with ``nodeset`` and ``size`` keys.
        For example ``"hugepages": [{"nodeset": "1-4,^3", "size": "2m"}, {"nodeset": "3", "size": "1g"}]``.

nosharepages
        boolean value to instruct hypervisor to disable shared pages (memory merge, KSM) for this domain

locked
        boolean value that allows memory pages belonging to the domain will be locked in host's memory and the host will
        not be allowed to swap them out, which might be required for some workloads such as real-time.

source
        possible values are ``file`` which utilizes file memorybacking, ``anonymous`` by default and ``memfd`` backing.
        (QEMU/KVM only)

access
        specify if the memory is to be ``shared`` or ``private``. This can be overridden per numa node by memAccess.

allocation
        specify when to allocate the memory by supplying either ``immediate`` or ``ondemand``.

discard
        boolean value to ensure the memory content is discarded just before guest shuts down (or when DIMM module is
        unplugged). Please note that this is just an optimization and is not guaranteed to work in all cases
        (e.g. when hypervisor crashes). (QEMU/KVM only)

.. _init-nic-def:

.. rubric:: Network Interfaces Definitions

Network interfaces dictionaries can contain the following properties:

name
        Name of the network interface. This is only used as a key to merge with the profile data

type
        Network type. One of ``'bridge'``, ``'network'``

source
        The network source, typically the bridge or network name

mac
        The desired mac address, computed if ``None`` (Default: ``None``).

model
        The network card model (Default: depends on the hypervisor)

.. _init-disk-def:

.. rubric:: Disks Definitions

Disk dictionaries can contain the following properties:

name
        Name of the disk. This is mostly used in the name of the disk image and as a key to merge
        with the profile data.

format
        Format of the disk image, like ``'qcow2'``, ``'raw'``, ``'vmdk'``.
        (Default: depends on the hypervisor)

size
        Disk size in MiB

pool
        Path to the folder or name of the pool where disks should be created.
        (Default: depends on hypervisor and the virt:storagepool configuration)

.. versionchanged:: 3001

If the value contains no '/', it is considered a pool name where to create a volume.
        Using volumes will be mandatory for some pools types like rdb, iscsi, etc.

model
        One of the disk busses allowed by libvirt (Default: depends on hypervisor)

See the libvirt `disk element`_ documentation for the allowed bus types.

image
        Path to the image to use for the disk. If no image is provided, an empty disk will be created
        (Default: ``None``)

Note that some pool types do not support uploading an image. This list can evolve with libvirt
        versions.

overlay_image
        ``True`` to create a QCOW2 disk image with ``image`` as backing file. If ``False``
        the file pointed to by the ``image`` property will simply be copied. (Default: ``False``)

.. versionchanged:: 3001

This property is only valid on path-based disks, not on volumes. To create a volume with a
        backing store, set the ``backing_store_path`` and ``backing_store_format`` properties.

backing_store_path
        Path to the backing store image to use. This can also be the name of a volume to use as
        backing store within the same pool.

.. versionadded:: 3001

backing_store_format
        Image format of the disk or volume to use as backing store. This property is mandatory when
        using ``backing_store_path`` to avoid `problems <https://libvirt.org/kbase/backing_chains.html#troubleshooting>`_

.. versionadded:: 3001

source_file
        Absolute path to the disk image to use. Not to be confused with ``image`` parameter. This
        parameter is useful to use disk images that are created outside of this module. Can also
        be ``None`` for devices that have no associated image like cdroms.

.. versionchanged:: 3001

For volume disks, this can be the name of a volume already existing in the storage pool.

device
        Type of device of the disk. Can be one of 'disk', 'cdrom', 'floppy' or 'lun'.
        (Default: ``'disk'``)

hostname_property
        When using ZFS volumes, setting this value to a ZFS property ID will make Salt store the name of the
        virtual machine inside this property. (Default: ``None``)

sparse_volume
        Boolean to specify whether to use a thin provisioned ZFS volume.

Example profile for a bhyve VM with two ZFS disks. The first is
        cloned from the specified image. The second disk is a thin
        provisioned volume.

.. code-block:: yaml

virt:
              disk:
                two_zvols:
                  - system:
                      image: zroot/bhyve/CentOS-7-x86_64-v1@v1.0.5
                      hostname_property: virt:hostname
                      pool: zroot/bhyve/guests
                  - data:
                      pool: tank/disks
                      size: 20G
                      hostname_property: virt:hostname
                      sparse_volume: True

io
        I/O control policy. String value amongst ``native``, ``threads`` and ``io_uring``.
        (Default: ``native``)

.. versionadded:: 3003

iothread_id
        I/O thread id to assign the disk to.
        (Default: none assigned)

.. versionadded:: 3003

.. _init-graphics-def:

.. rubric:: Graphics Definition

The graphics dictionary can have the following properties:

type
        Graphics type. The possible values are ``none``, ``'spice'``, ``'vnc'`` and other values
        allowed as a libvirt graphics type (Default: ``None``)

See the libvirt `graphics element`_ documentation for more details on the possible types.

port
        Port to export the graphics on for ``vnc``, ``spice`` and ``rdp`` types.

tls_port
        Port to export the graphics over a secured connection for ``spice`` type.

listen
        Dictionary defining on what address to listen on for ``vnc``, ``spice`` and ``rdp``.
        It has a ``type`` property with ``address`` and ``None`` as possible values, and an
        ``address`` property holding the IP or hostname to listen on.

By default, not setting the ``listen`` part of the dictionary will default to
        listen on all addresses.

.. _init-chardevs-def:

.. rubric:: Serials and Consoles Definitions

Serial dictionaries can contain the following properties:

type
        Type of the serial connection, like ``'tcp'``, ``'pty'``, ``'file'``, ``'udp'``, ``'dev'``,
        ``'pipe'``, ``'unix'``.

path
        Path to the source device. Can be a log file, a host character device to pass through,
        a unix socket, a named pipe path.

host
        The serial UDP or TCP host name.
        (Default: 23023)

port
        The serial UDP or TCP port number.
        (Default: 23023)

protocol
        Name of the TCP connection protocol.
        (Default: telnet)

tls
        Boolean value indicating whether to use hypervisor TLS certificates environment for TCP devices.

target_port
        The guest device port number starting from 0

target_type
        The guest device type. Common values are ``serial``, ``virtio`` or ``usb-serial``, but more are documented in
        `the libvirt documentation <https://libvirt.org/formatdomain.html#consoles-serial-parallel-channel-devices>`_.

.. rubric:: CLI Example

.. code-block:: bash

salt 'hypervisor' virt.init vm_name 4 512 salt://path/to/image.raw
        salt 'hypervisor' virt.init vm_name 4 512 /var/lib/libvirt/images/img.raw
        salt 'hypervisor' virt.init vm_name 4 512 nic=profile disk=profile

The disk images will be created in an image folder within the directory
    defined by the ``virt:images`` option. Its default value is
    ``/srv/salt-images/`` but this can changed with such a configuration:

.. code-block:: yaml

virt:
            images: /data/my/vm/images/

.. _disk element: https://libvirt.org/formatdomain.html#elementsDisks
    .. _graphics element: https://libvirt.org/formatdomain.html#elementsGraphics
    """
    try:
        conn = __get_conn(**kwargs)
        caps = _capabilities(conn)
        os_types = sorted({guest["os_type"] for guest in caps["guests"]})
        arches = sorted({guest["arch"]["name"] for guest in caps["guests"]})

virt_hypervisor = hypervisor
        if not virt_hypervisor:
            # Use the machine types as possible values
            # Prefer 'kvm' over the others if available
            hypervisors = sorted(
                {
                    x
                    for y in [
                        guest["arch"]["domains"].keys() for guest in caps["guests"]
                    ]
                    for x in y
                }
            )
            if len(hypervisors) == 0:
                raise SaltInvocationError("No supported hypervisors were found")
            virt_hypervisor = "kvm" if "kvm" in hypervisors else hypervisors[0]

# esxi used to be a possible value for the hypervisor: map it to vmware since it's the same
        virt_hypervisor = "vmware" if virt_hypervisor == "esxi" else virt_hypervisor

log.debug("Using hypervisor %s", virt_hypervisor)

nicp = _get_merged_nics(virt_hypervisor, nic, interfaces)

# the disks are computed as follows:
        # 1 - get the disks defined in the profile
        # 3 - update the disks from the profile with the ones from the user. The matching key is the name.
        diskp = _disk_profile(conn, disk, virt_hypervisor, disks, name)

# Create multiple disks, empty or from specified images.
        for _disk in diskp:
            # No need to create an image for cdrom devices
            if _disk.get("device", "disk") == "cdrom":
                continue

log.debug("Creating disk for VM [ %s ]: %s", name, _disk)

if virt_hypervisor == "vmware":
                if "image" in _disk:
                    # TODO: we should be copying the image file onto the ESX host
                    raise SaltInvocationError(
                        "virt.init does not support image "
                        "template in conjunction with esxi hypervisor"
                    )
                else:
                    # assume libvirt manages disks for us
                    log.debug("Generating libvirt XML for %s", _disk)
                    volume_name = "{}/{}".format(name, _disk["name"])
                    filename = "{}.{}".format(volume_name, _disk["format"])
                    vol_xml = _gen_vol_xml(
                        filename, _disk["size"], format=_disk["format"]
                    )
                    _define_vol_xml_str(conn, vol_xml, pool=_disk.get("pool"))

elif virt_hypervisor in ["qemu", "kvm", "xen"]:

def seeder(path):
                    _seed_image(
                        seed_cmd,
                        path,
                        name,
                        kwargs.get("config"),
                        install,
                        pub_key,
                        priv_key,
                    )

create_overlay = _disk.get("overlay_image", False)
                format = _disk.get("format")
                if _disk.get("source_file"):
                    if os.path.exists(_disk["source_file"]):
                        img_dest = _disk["source_file"]
                    else:
                        img_dest = _qemu_image_create(_disk, create_overlay, saltenv)
                else:
                    _disk_volume_create(conn, _disk, seeder if seed else None, saltenv)
                    img_dest = None

# Seed only if there is an image specified
                if seed and img_dest and _disk.get("image", None):
                    seeder(img_dest)

elif hypervisor in ["bhyve"]:
                img_dest = _zfs_image_create(
                    vm_name=name,
                    pool=_disk.get("pool"),
                    disk_name=_disk.get("name"),
                    disk_size=_disk.get("size"),
                    disk_image_name=_disk.get("image"),
                    hostname_property_name=_disk.get("hostname_property"),
                    sparse_volume=_disk.get("sparse_volume"),
                )

else:
                # Unknown hypervisor
                raise SaltInvocationError(
                    "Unsupported hypervisor when handling disk image: {}".format(
                        virt_hypervisor
                    )
                )

log.debug("Generating VM XML")
        if os_type is None:
            os_type = "hvm" if "hvm" in os_types else os_types[0]
        if arch is None:
            arch = "x86_64" if "x86_64" in arches else arches[0]

if boot is not None:
            boot = _handle_remote_boot_params(boot)

vm_xml = _gen_xml(
            conn,
            name,
            cpu,
            mem,
            diskp,
            nicp,
            virt_hypervisor,
            os_type,
            arch,
            graphics,
            boot,
            boot_dev,
            numatune,
            hypervisor_features,
            clock,
            serials,
            consoles,
            stop_on_reboot,
            host_devices,
            **kwargs,
        )
        log.debug("New virtual machine definition: %s", vm_xml)
        conn.defineXML(vm_xml)
    except libvirt.libvirtError as err:
        conn.close()
        raise CommandExecutionError(err.get_error_message())

if start:
        log.debug("Starting VM %s", name)
        _get_domain(conn, name).create()
    conn.close()

return True

def _disks_equal(disk1, disk2):
    """
    Test if two disk elements should be considered like the same device
    """
    target1 = disk1.find("target")
    target2 = disk2.find("target")

disk1_dict = xmlutil.to_dict(disk1, True)
    disk2_dict = xmlutil.to_dict(disk2, True)

source1_dict = disk1_dict.get("source", {})
    source2_dict = disk2_dict.get("source", {})

io1 = disk1_dict.get("driver", {}).get("io", "native")
    io2 = disk2_dict.get("driver", {}).get("io", "native")

# Remove the index added by libvirt in the source for backing chain
    if source1_dict:
        source1_dict.pop("index", None)
    if source2_dict:
        source2_dict.pop("index", None)

return (
        source1_dict == source2_dict
        and target1 is not None
        and target2 is not None
        and target1.get("bus") == target2.get("bus")
        and disk1.get("device", "disk") == disk2.get("device", "disk")
        and target1.get("dev") == target2.get("dev")
        and io1 == io2
    )

def _nics_equal(nic1, nic2):
    """
    Test if two interface elements should be considered like the same device
    """

def _filter_nic(nic):
        """
        Filter out elements to ignore when comparing nics
        """
        source_node = nic.find("source")
        source_attrib = source_node.attrib if source_node is not None else {}
        source_type = "network" if "network" in source_attrib else nic.attrib["type"]

source_getters = {
            "network": lambda n: n.get("network"),
            "bridge": lambda n: n.get("bridge"),
            "direct": lambda n: n.get("dev"),
            "hostdev": lambda n: _format_pci_address(n.find("address")),
        }
        return {
            "type": source_type,
            "source": (
                source_getters[source_type](source_node)
                if source_node is not None
                else None
            ),
            "model": (
                nic.find("model").attrib["type"]
                if nic.find("model") is not None
                else None
            ),
        }

def _get_mac(nic):
        return (
            nic.find("mac").attrib["address"].lower()
            if nic.find("mac") is not None
            else None
        )

mac1 = _get_mac(nic1)
    mac2 = _get_mac(nic2)
    macs_equal = not mac1 or not mac2 or mac1 == mac2
    return _filter_nic(nic1) == _filter_nic(nic2) and macs_equal

def _graphics_equal(gfx1, gfx2):
    """
    Test if two graphics devices should be considered the same device
    """

def _filter_graphics(gfx):
        """
        When the domain is running, the graphics element may contain additional properties
        with the default values. This function will strip down the default values.
        """
        gfx_copy = copy.deepcopy(gfx)

defaults = [
            {"node": ".", "attrib": "port", "values": ["5900", "-1"]},
            {"node": ".", "attrib": "address", "values": ["127.0.0.1"]},
            {"node": "listen", "attrib": "address", "values": ["127.0.0.1"]},
        ]

for default in defaults:
            node = gfx_copy.find(default["node"])
            attrib = default["attrib"]
            if node is not None and (
                attrib in node.attrib and node.attrib[attrib] in default["values"]
            ):
                node.attrib.pop(attrib)
        return gfx_copy

return xmlutil.to_dict(_filter_graphics(gfx1), True) == xmlutil.to_dict(
        _filter_graphics(gfx2), True
    )

def _hostdevs_equal(dev1, dev2):
    """
    Test if two hostdevs devices should be considered the same device
    """

def _filter_hostdevs(dev):
        """
        When the domain is running, the hostdevs element may contain additional properties.
        This function will only keep the ones we care about
        """
        type_ = dev.get("type")
        definition = {
            "type": type_,
        }
        if type_ == "pci":
            address_node = dev.find("./source/address")
            for attr in ["domain", "bus", "slot", "function"]:
                definition[attr] = address_node.get(attr)
        elif type_ == "usb":
            for attr in ["vendor", "product"]:
                definition[attr] = dev.find("./source/" + attr).get("id")
        return definition

return _filter_hostdevs(dev1) == _filter_hostdevs(dev2)

def _diff_lists(old, new, comparator):
    """
    Compare lists to extract the changes

:param old: old list
    :param new: new list
    :return: a dictionary with ``unchanged``, ``new``, ``deleted`` and ``sorted`` keys

The sorted list is the union of unchanged and new lists, but keeping the original
    order from the new list.
    """

def _remove_indent(node):
        """
        Remove the XML indentation to compare XML trees more easily
        """
        node_copy = copy.deepcopy(node)
        node_copy.text = None
        for item in node_copy.iter():
            item.tail = None
        return node_copy

diff = {"unchanged": [], "new": [], "deleted": [], "sorted": []}
    # We don't want to alter old since it may be used later by caller
    old_devices = copy.deepcopy(old)
    for new_item in new:
        found = [
            item
            for item in old_devices
            if comparator(_remove_indent(item), _remove_indent(new_item))
        ]
        if found:
            old_devices.remove(found[0])
            diff["unchanged"].append(found[0])
            diff["sorted"].append(found[0])
        else:
            diff["new"].append(new_item)
            diff["sorted"].append(new_item)
    diff["deleted"] = old_devices
    return diff

def _get_disk_target(targets, disks_count, prefix):
    """
    Compute the disk target name for a given prefix.

:param targets: the list of already computed targets
    :param disks: the number of disks
    :param prefix: the prefix of the target name, i.e. "hd"
    """
    for i in range(disks_count):
        ret = f"{prefix}{string.ascii_lowercase[i]}"
        if ret not in targets:
            return ret
    return None

def _diff_disk_lists(old, new):
    """
    Compare disk definitions to extract the changes and fix target devices

:param old: list of ElementTree nodes representing the old disks
    :param new: list of ElementTree nodes representing the new disks
    """
    # Change the target device to avoid duplicates before diffing: this may lead
    # to additional changes. Think of unchanged disk 'hda' and another disk listed
    # before it becoming 'hda' too... the unchanged need to turn into 'hdb'.
    targets = []
    prefixes = ["fd", "hd", "vd", "sd", "xvd", "ubd"]
    for disk in new:
        target_node = disk.find("target")
        target = target_node.get("dev")
        prefix = [item for item in prefixes if target.startswith(item)][0]
        new_target = _get_disk_target(targets, len(new), prefix)
        target_node.set("dev", new_target)
        targets.append(new_target)

return _diff_lists(old, new, _disks_equal)

def _diff_interface_lists(old, new):
    """
    Compare network interface definitions to extract the changes

:param old: list of ElementTree nodes representing the old interfaces
    :param new: list of ElementTree nodes representing the new interfaces
    """
    return _diff_lists(old, new, _nics_equal)

def _diff_graphics_lists(old, new):
    """
    Compare graphic devices definitions to extract the changes

:param old: list of ElementTree nodes representing the old graphic devices
    :param new: list of ElementTree nodes representing the new graphic devices
    """
    return _diff_lists(old, new, _graphics_equal)

def _diff_hostdev_lists(old, new):
    """
    Compare hostdev devices definitions to extract the changes

:param old: list of ElementTree nodes representing the old hostdev devices
    :param new: list of ElementTree nodes representing the new hostdev devices
    """
    return _diff_lists(old, new, _hostdevs_equal)

def _expand_cpuset(cpuset):
    """
    Expand the libvirt cpuset and nodeset values into a list of cpu/node IDs
    """
    if cpuset is None:
        return None

if isinstance(cpuset, int):
        return str(cpuset)

result = set()
    toremove = set()
    for part in cpuset.split(","):
        m = re.match("([0-9]+)-([0-9]+)", part)
        if m:
            result |= set(range(int(m.group(1)), int(m.group(2)) + 1))
        elif part.startswith("^"):
            toremove.add(int(part[1:]))
        else:
            result.add(int(part))
    cpus = list(result - toremove)
    cpus.sort()
    cpus = [str(cpu) for cpu in cpus]
    return ",".join(cpus)

def _normalize_cpusets(desc, data):
    """
    Expand the cpusets that can't be expanded by the change_xml() function,
    namely the ones that are used as keys and in the middle of the XPath expressions.
    """
    # Normalize the cpusets keys in the XML
    xpaths = ["cputune/cachetune", "cputune/cachetune/monitor", "cputune/memorytune"]
    for xpath in xpaths:
        nodes = desc.findall(xpath)
        for node in nodes:
            node.set("vcpus", _expand_cpuset(node.get("vcpus")))

# data paths to change:
    #  - cpu:tuning:cachetune:{id}:monitor:{sid}
    #  - cpu:tuning:memorytune:{id}
    if not isinstance(data.get("cpu"), dict):
        return
    tuning = data["cpu"].get("tuning", {})
    for child in ["cachetune", "memorytune"]:
        if tuning.get(child):
            new_item = dict()
            for cpuset, value in tuning[child].items():
                if child == "cachetune" and value.get("monitor"):
                    value["monitor"] = {
                        _expand_cpuset(monitor_cpus): monitor
                        for monitor_cpus, monitor in value["monitor"].items()
                    }
                new_item[_expand_cpuset(cpuset)] = value
            tuning[child] = new_item

def _serial_or_concole_equal(old, new):
    def _filter_serial_or_concole(item):
        """
        Filter out elements to ignore when comparing items
        """
        return {
            "type": item.attrib["type"],
            "port": (
                item.find("source").get("service")
                if item.find("source") is not None
                else None
            ),
            "protocol": (
                item.find("protocol").get("type")
                if item.find("protocol") is not None
                else None
            ),
        }

return _filter_serial_or_concole(old) == _filter_serial_or_concole(new)

def _diff_serial_lists(old, new):
    """
    Compare serial definitions to extract the changes

:param old: list of ElementTree nodes representing the old serials
    :param new: list of ElementTree nodes representing the new serials
    """
    return _diff_lists(old, new, _serial_or_concole_equal)

def _diff_console_lists(old, new):
    """
    Compare console definitions to extract the changes

:param old: list of ElementTree nodes representing the old consoles
    :param new: list of ElementTree nodes representing the new consoles
    """
    return _diff_lists(old, new, _serial_or_concole_equal)

def _format_pci_address(node):
    return "{}:{}:{}.{}".format(
        node.get("domain").replace("0x", ""),
        node.get("bus").replace("0x", ""),
        node.get("slot").replace("0x", ""),
        node.get("function").replace("0x", ""),
    )

def _almost_equal(current, new):
    """
    return True if the parameters are numbers that are almost
    """
    if current is None or new is None:
        return False
    return abs(current - new) / current < 1e-03

def _compute_device_changes(old_xml, new_xml, to_skip):
    """
    Compute the device changes between two domain XML definitions.
    """
    devices_node = old_xml.find("devices")
    changes = {}
    for dev_type in to_skip:
        changes[dev_type] = {}
        if not to_skip[dev_type]:
            old = devices_node.findall(dev_type)
            new = new_xml.findall(f"devices/{dev_type}")
            changes[dev_type] = globals()[f"_diff_{dev_type}_lists"](old, new)
    return changes

def _get_pci_addresses(node):
    """
    Get all the pci addresses in the node in 0000:00:00.0 form
    """
    return {_format_pci_address(address) for address in node.findall(".//address")}

def _correct_networks(conn, desc):
    """
    Adjust the interface devices matching existing networks.
    Returns the network interfaces XML definition as string mapped to the new device node.
    """
    networks = [ElementTree.fromstring(net.XMLDesc()) for net in conn.listAllNetworks()]
    nics = desc.findall("devices/interface")
    device_map = {}
    for nic in nics:
        if nic.get("type") == "hostdev":
            # Do we have a network matching this NIC PCI address?
            addr = _get_pci_addresses(nic.find("source"))
            matching_nets = [
                net
                for net in networks
                if net.find("forward").get("mode") == "hostdev"
                and addr & _get_pci_addresses(net)
            ]
            if matching_nets:
                # We need to store the XML before modifying it
                # since libvirt needs it to detach the device
                old_xml = ElementTree.tostring(nic)
                nic.set("type", "network")
                nic.find("source").set("network", matching_nets[0].find("name").text)
                device_map[nic] = old_xml
    return device_map

def _update_live(domain, new_desc, mem, cpu, old_mem, old_cpu, to_skip, test):
    """
    Perform the live update of a domain.
    """
    status = {}
    errors = []

if not domain.isActive():
        return status, errors

# Do the live changes now that we know the definition has been properly set
    # From that point on, failures are not blocking to try to live update as much
    # as possible.
    commands = []
    if cpu and (isinstance(cpu, int) or isinstance(cpu, dict) and cpu.get("maximum")):
        new_cpu = cpu.get("maximum") if isinstance(cpu, dict) else cpu
        if old_cpu != new_cpu and new_cpu is not None:
            commands.append(
                {
                    "device": "cpu",
                    "cmd": "setVcpusFlags",
                    "args": [new_cpu, libvirt.VIR_DOMAIN_AFFECT_LIVE],
                }
            )
    if mem:
        if isinstance(mem, dict):
            # setMemoryFlags takes memory amount in KiB
            new_mem = (
                int(_handle_unit(mem.get("current")) / 1024)
                if "current" in mem
                else None
            )
        elif isinstance(mem, int):
            new_mem = int(mem * 1024)

if not _almost_equal(old_mem, new_mem) and new_mem is not None:
            commands.append(
                {
                    "device": "mem",
                    "cmd": "setMemoryFlags",
                    "args": [new_mem, libvirt.VIR_DOMAIN_AFFECT_LIVE],
                }
            )

# Compute the changes with the live definition
    old_desc = ElementTree.fromstring(domain.XMLDesc(0))
    changed_devices = {"interface": _correct_networks(domain.connect(), old_desc)}
    changes = _compute_device_changes(old_desc, new_desc, to_skip)

# Look for removable device source changes
    removable_changes = []
    new_disks = []
    for new_disk in changes["disk"].get("new", []):
        device = new_disk.get("device", "disk")
        if device not in ["cdrom", "floppy"]:
            new_disks.append(new_disk)
            continue

target_dev = new_disk.find("target").get("dev")
        matching = [
            old_disk
            for old_disk in changes["disk"].get("deleted", [])
            if old_disk.get("device", "disk") == device
            and old_disk.find("target").get("dev") == target_dev
        ]
        if not matching:
            new_disks.append(new_disk)
        else:
            # libvirt needs to keep the XML exactly as it was before
            updated_disk = matching[0]
            changes["disk"]["deleted"].remove(updated_disk)
            removable_changes.append(updated_disk)
            source_node = updated_disk.find("source")
            new_source_node = new_disk.find("source")
            source_file = (
                new_source_node.get("file") if new_source_node is not None else None
            )

updated_disk.set("type", "file")
            # Detaching device
            if source_node is not None:
                updated_disk.remove(source_node)

# Attaching device
            if source_file:
                ElementTree.SubElement(
                    updated_disk, "source", attrib={"file": source_file}
                )

changes["disk"]["new"] = new_disks

for dev_type in ["disk", "interface", "hostdev"]:
        for added in changes[dev_type].get("new", []):
            commands.append(
                {
                    "device": dev_type,
                    "cmd": "attachDevice",
                    "args": [xmlutil.element_to_str(added)],
                }
            )

for removed in changes[dev_type].get("deleted", []):
            removed_def = changed_devices.get(dev_type, {}).get(
                removed, ElementTree.tostring(removed)
            )
            commands.append(
                {
                    "device": dev_type,
                    "cmd": "detachDevice",
                    "args": [salt.utils.stringutils.to_str(removed_def)],
                }
            )

for updated_disk in removable_changes:
        commands.append(
            {
                "device": "disk",
                "cmd": "updateDeviceFlags",
                "args": [xmlutil.element_to_str(updated_disk)],
            }
        )

for cmd in commands:
        try:
            ret = 0 if test else getattr(domain, cmd["cmd"])(*cmd["args"])
            device_type = cmd["device"]
            if device_type in ["cpu", "mem"]:
                status[device_type] = not ret
            else:
                actions = {
                    "attachDevice": "attached",
                    "detachDevice": "detached",
                    "updateDeviceFlags": "updated",
                }
                device_status = status.setdefault(device_type, {})
                cmd_status = device_status.setdefault(actions[cmd["cmd"]], [])
                cmd_status.append(cmd["args"][0])

except libvirt.libvirtError as err:
            errors.append(str(err))

return status, errors

def update(
    name,
    cpu=0,
    mem=0,
    disk_profile=None,
    disks=None,
    nic_profile=None,
    interfaces=None,
    graphics=None,
    live=True,
    boot=None,
    numatune=None,
    test=False,
    boot_dev=None,
    hypervisor_features=None,
    clock=None,
    serials=None,
    consoles=None,
    stop_on_reboot=False,
    host_devices=None,
    autostart=False,
    **kwargs,
):
    """
    Update the definition of an existing domain.

:param name: Name of the domain to update
    :param cpu:
        Number of virtual CPUs to assign to the virtual machine or a dictionary with detailed information to configure
        cpu model and topology, numa node tuning, cpu tuning and iothreads allocation. The structure of the dictionary is
        documented in :ref:`init-cpu-def`.

To update any cpu parameters specify the new values to the corresponding tag. To remove any element or attribute,
        specify ``None`` object. Please note that ``None`` object is mapped to ``null`` in yaml, use ``null`` in sls file
        instead.
    :param mem: Amount of memory to allocate to the virtual machine in MiB. Since 3002, a dictionary can be used to
        contain detailed configuration which support memory allocation or tuning. Supported parameters are ``boot``,
        ``current``, ``max``, ``slots``, ``hard_limit``, ``soft_limit``, ``swap_hard_limit``, ``min_guarantee``,
        ``hugepages`` ,  ``nosharepages``, ``locked``, ``source``, ``access``, ``allocation`` and ``discard``. The structure
        of the dictionary is documented in  :ref:`init-mem-def`. Both decimal and binary base are supported. Detail unit
        specification is documented  in :ref:`virt-units`. Please note that the value for ``slots`` must be an integer.

To remove any parameters, pass a None object, for instance: 'soft_limit': ``None``. Please note  that ``None``
        is mapped to ``null`` in sls file, pass ``null`` in sls file instead.

.. code-block:: yaml

- mem:
                hard_limit: null
                soft_limit: null

.. versionchanged:: 3002

:param disk_profile: disk profile to use
    :param disks:
        Disk definitions as documented in the :func:`init` function.
        If neither the profile nor this parameter are defined, the disk devices
        will not be changed. However to clear disks set this parameter to empty list.

:param nic_profile: network interfaces profile to use
    :param interfaces:
        Network interface definitions as documented in the :func:`init` function.
        If neither the profile nor this parameter are defined, the interface devices
        will not be changed. However to clear network interfaces set this parameter
        to empty list.

:param graphics:
        The new graphics definition as defined in :ref:`init-graphics-def`. If not set,
        the graphics will not be changed. To remove a graphics device, set this parameter
        to ``{'type': 'none'}``.

:param live:
        ``False`` to avoid trying to live update the definition. In such a case, the
        new definition is applied at the next start of the virtual machine. If ``True``,
        not all aspects of the definition can be live updated, but as much as possible
        will be attempted. (Default: ``True``)

:param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

Refer to :ref:`init-boot-def` for the complete boot parameter description.

To update any boot parameters, specify the new path for each. To remove any boot parameters, pass ``None`` object,
        for instance: 'kernel': ``None``. To switch back to BIOS boot, specify ('loader': ``None`` and 'nvram': ``None``)
        or 'efi': ``False``. Please note that ``None`` is mapped to ``null`` in sls file, pass ``null`` in sls file instead.

SLS file Example:

.. code-block:: yaml

- boot:
                loader: null
                nvram: null

.. versionadded:: 3000

:param boot_dev:
        Space separated list of devices to boot from sorted by decreasing priority.
        Values can be ``hd``, ``fd``, ``cdrom`` or ``network``.

By default, the value will ``"hd"``.

.. versionadded:: 3002

To update any numatune parameters, specify the new value. To remove any ``numatune`` parameters, pass a None object,
        for instance: 'numatune': ``None``. Please note that ``None`` is mapped to ``null`` in sls file, pass ``null`` in
        sls file instead.

.. versionadded:: 3003

:param serials:
        Dictionary providing details on the serials connection to create. (Default: ``None``)
        See :ref:`init-chardevs-def` for more details on the possible values.

.. versionadded:: 3003

:param consoles:
        Dictionary providing details on the consoles device to create. (Default: ``None``)
        See :ref:`init-chardevs-def` for more details on the possible values.

.. versionadded:: 3003

:param test: run in dry-run mode if set to True

.. versionadded:: 3001

:param hypervisor_features:
        Enable or disable hypervisor-specific features on the virtual machine.

.. versionadded:: 3003

.. code-block:: yaml

hypervisor_features:
              kvm-hint-dedicated: True

:param clock:
        Configure the guest clock.
        The value is a dictionary with the following keys:

adjustment
            time adjustment in seconds or ``reset``

utc
            set to ``False`` to use the host local time as the guest clock. Defaults to ``True``.

timezone
            synchronize the guest to the correspding timezone

.. versionadded:: 3003

Set the clock to local time using an offset in seconds
        .. code-block:: yaml

clock:
              adjustment: 3600
              utc: False

Set the clock to a specific time zone:

.. code-block:: yaml

clock:
              timezone: CEST

Tweak guest timers:

.. code-block:: yaml

.. versionadded:: 3003

:param autostart:
        If set to ``True`` the host will start the guest after boot.
        (Default: ``False``)

:return:

Returns a dictionary indicating the status of what has been done. It is structured in
        the following way:

.. code-block:: python

{
              'definition': True,
              'cpu': True,
              'mem': True,
              'disks': {'attached': [list of actually attached disks],
                        'detached': [list of actually detached disks]},
              'nics': {'attached': [list of actually attached nics],
                       'detached': [list of actually detached nics]},
              'errors': ['error messages for failures']
            }

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.update domain cpu=2 mem=1024

"""
    status = {
        "definition": False,
        "disk": {"attached": [], "detached": [], "updated": []},
        "interface": {"attached": [], "detached": []},
    }
    conn = __get_conn(**kwargs)
    domain = _get_domain(conn, name)
    desc = ElementTree.fromstring(domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE))
    need_update = False

# Compute the XML to get the disks, interfaces and graphics
    hypervisor = desc.get("type")
    all_disks = _disk_profile(conn, disk_profile, hypervisor, disks, name)

if boot is not None:
        boot = _handle_remote_boot_params(boot)
        if boot.get("efi", None) is not None:
            need_update = _handle_efi_param(boot, desc)
    new_desc = ElementTree.fromstring(
        _gen_xml(
            conn,
            name,
            cpu,
            mem or 0,
            all_disks,
            _get_merged_nics(hypervisor, nic_profile, interfaces),
            hypervisor,
            domain.OSType(),
            desc.find(".//os/type").get("arch"),
            graphics,
            boot,
            boot_dev,
            numatune,
            serials=serials,
            consoles=consoles,
            stop_on_reboot=stop_on_reboot,
            host_devices=host_devices,
            **kwargs,
        )
    )
    set_autostart(name, "on" if autostart else "off")

if clock:
        offset = "utc" if clock.get("utc", True) else "localtime"
        if "timezone" in clock:
            offset = "timezone"
        clock["offset"] = offset

def _set_loader(node, value):
        salt.utils.xmlutil.set_node_text(node, value)
        if value is not None:
            node.set("readonly", "yes")
            node.set("type", "pflash")

def _set_nvram(node, value):
        node.set("template", value)

def _set_with_byte_unit(attr_name=None):
        def _setter(node, value):
            if attr_name:
                node.set(attr_name, str(value))
            else:
                node.text = str(value)
            node.set("unit", "bytes")

return _setter

def _get_with_unit(node):
        unit = node.get("unit", "KiB")
        # _handle_unit treats bytes as invalid unit for the purpose of consistency
        unit = unit if unit != "bytes" else "b"
        value = node.get("memory") or node.get("size") or node.text
        return _handle_unit(f"{value}{unit}") if value else None

def _set_vcpu(node, value):
        node.text = str(value)
        node.set("current", str(value))

old_mem = int(_get_with_unit(desc.find("memory")) / 1024)
    old_cpu = int(desc.find("./vcpu").text)

def _yesno_attribute(path, xpath, attr_name, ignored=None):
        return xmlutil.attribute(
            path, xpath, attr_name, ignored, lambda v: "yes" if v else "no"
        )

def _memory_parameter(path, xpath, attr_name=None, ignored=None):
        entry = {
            "path": path,
            "xpath": xpath,
            "convert": _handle_unit,
            "get": _get_with_unit,
            "set": _set_with_byte_unit(attr_name),
            "equals": _almost_equal,
        }
        if attr_name:
            entry["del"] = salt.utils.xmlutil.del_attribute(attr_name, ignored)
        return entry

def _cpuset_parameter(path, xpath, attr_name=None, ignored=None):
        def _set_cpuset(node, value):
            if attr_name:
                node.set(attr_name, value)
            else:
                node.text = value

entry = {
            "path": path,
            "xpath": xpath,
            "convert": _expand_cpuset,
            "get": lambda n: _expand_cpuset(n.get(attr_name) if attr_name else n.text),
            "set": _set_cpuset,
        }
        if attr_name:
            entry["del"] = salt.utils.xmlutil.del_attribute(attr_name, ignored)
        return entry

# Update the kernel boot parameters
    data = {k: v for k, v in locals().items() if bool(v)}
    data["stop_on_reboot"] = stop_on_reboot
    if boot_dev:
        data["boot_dev"] = boot_dev.split()

# Set the missing optional attributes and timers to None in timers to help cleaning up
    timer_names = [
        "platform",
        "hpet",
        "kvmclock",
        "pit",
        "rtc",
        "tsc",
        "hypervclock",
        "armvtimer",
    ]
    if data.get("clock", {}).get("timers"):
        attributes = [
            "track",
            "tickpolicy",
            "frequency",
            "mode",
            "present",
            "slew",
            "threshold",
            "limit",
        ]
        for timer in data["clock"]["timers"].values():
            for attribute in attributes:
                if attribute not in timer:
                    timer[attribute] = None

for timer_name in timer_names:
            if timer_name not in data["clock"]["timers"]:
                data["clock"]["timers"][timer_name] = None

_normalize_cpusets(desc, data)

params_mapping = [
        {
            "path": "stop_on_reboot",
            "xpath": "on_reboot",
            "convert": lambda v: "destroy" if v else "restart",
        },
        {"path": "boot:kernel", "xpath": "os/kernel"},
        {"path": "boot:initrd", "xpath": "os/initrd"},
        {"path": "boot:cmdline", "xpath": "os/cmdline"},
        {"path": "boot:loader", "xpath": "os/loader", "set": _set_loader},
        {"path": "boot:nvram", "xpath": "os/nvram", "set": _set_nvram},
        # Update the memory, note that libvirt outputs all memory sizes in KiB
        _memory_parameter("mem", "memory"),
        _memory_parameter("mem", "currentMemory"),
        _memory_parameter("mem:max", "maxMemory"),
        _memory_parameter("mem:boot", "memory"),
        _memory_parameter("mem:current", "currentMemory"),
        xmlutil.attribute("mem:slots", "maxMemory", "slots", ["unit"]),
        _memory_parameter("mem:hard_limit", "memtune/hard_limit"),
        _memory_parameter("mem:soft_limit", "memtune/soft_limit"),
        _memory_parameter("mem:swap_hard_limit", "memtune/swap_hard_limit"),
        _memory_parameter("mem:min_guarantee", "memtune/min_guarantee"),
        xmlutil.attribute("boot_dev:{dev}", "os/boot[$dev]", "dev"),
        _memory_parameter(
            "mem:hugepages:{id}:size",
            "memoryBacking/hugepages/page[$id]",
            "size",
            ["unit", "nodeset"],
        ),
        _cpuset_parameter(
            "mem:hugepages:{id}:nodeset", "memoryBacking/hugepages/page[$id]", "nodeset"
        ),
        {
            "path": "mem:nosharepages",
            "xpath": "memoryBacking/nosharepages",
            "get": lambda n: n is not None,
            "set": lambda n, v: None,
        },
        {
            "path": "mem:locked",
            "xpath": "memoryBacking/locked",
            "get": lambda n: n is not None,
            "set": lambda n, v: None,
        },
        xmlutil.attribute("mem:source", "memoryBacking/source", "type"),
        xmlutil.attribute("mem:access", "memoryBacking/access", "mode"),
        xmlutil.attribute("mem:allocation", "memoryBacking/allocation", "mode"),
        {"path": "mem:discard", "xpath": "memoryBacking/discard"},
        {
            "path": "cpu",
            "xpath": "vcpu",
            "get": lambda n: int(n.text),
            "set": _set_vcpu,
        },
        {"path": "cpu:maximum", "xpath": "vcpu", "get": lambda n: int(n.text)},
        xmlutil.attribute("cpu:placement", "vcpu", "placement"),
        _cpuset_parameter("cpu:cpuset", "vcpu", "cpuset"),
        xmlutil.attribute("cpu:current", "vcpu", "current"),
        xmlutil.attribute("cpu:match", "cpu", "match"),
        xmlutil.attribute("cpu:mode", "cpu", "mode"),
        xmlutil.attribute("cpu:check", "cpu", "check"),
        {"path": "cpu:model:name", "xpath": "cpu/model"},
        xmlutil.attribute("cpu:model:fallback", "cpu/model", "fallback"),
        xmlutil.attribute("cpu:model:vendor_id", "cpu/model", "vendor_id"),
        {"path": "cpu:vendor", "xpath": "cpu/vendor"},
        xmlutil.attribute("cpu:topology:sockets", "cpu/topology", "sockets"),
        xmlutil.attribute("cpu:topology:cores", "cpu/topology", "cores"),
        xmlutil.attribute("cpu:topology:threads", "cpu/topology", "threads"),
        xmlutil.attribute("cpu:cache:level", "cpu/cache", "level"),
        xmlutil.attribute("cpu:cache:mode", "cpu/cache", "mode"),
        xmlutil.attribute(
            "cpu:features:{id}", "cpu/feature[@name='$id']", "policy", ["name"]
        ),
        _yesno_attribute(
            "cpu:vcpus:{id}:enabled", "vcpus/vcpu[@id='$id']", "enabled", ["id"]
        ),
        _yesno_attribute(
            "cpu:vcpus:{id}:hotpluggable",
            "vcpus/vcpu[@id='$id']",
            "hotpluggable",
            ["id"],
        ),
        xmlutil.int_attribute(
            "cpu:vcpus:{id}:order", "vcpus/vcpu[@id='$id']", "order", ["id"]
        ),
        _cpuset_parameter(
            "cpu:numa:{id}:cpus", "cpu/numa/cell[@id='$id']", "cpus", ["id"]
        ),
        _memory_parameter(
            "cpu:numa:{id}:memory", "cpu/numa/cell[@id='$id']", "memory", ["id"]
        ),
        _yesno_attribute(
            "cpu:numa:{id}:discard", "cpu/numa/cell[@id='$id']", "discard", ["id"]
        ),
        xmlutil.attribute(
            "cpu:numa:{id}:memAccess", "cpu/numa/cell[@id='$id']", "memAccess", ["id"]
        ),
        xmlutil.attribute(
            "cpu:numa:{id}:distances:{sid}",
            "cpu/numa/cell[@id='$id']/distances/sibling[@id='$sid']",
            "value",
            ["id"],
        ),
        {"path": "cpu:iothreads", "xpath": "iothreads"},
        {"path": "cpu:tuning:shares", "xpath": "cputune/shares"},
        {"path": "cpu:tuning:period", "xpath": "cputune/period"},
        {"path": "cpu:tuning:quota", "xpath": "cputune/quota"},
        {"path": "cpu:tuning:global_period", "xpath": "cputune/global_period"},
        {"path": "cpu:tuning:global_quota", "xpath": "cputune/global_quota"},
        {"path": "cpu:tuning:emulator_period", "xpath": "cputune/emulator_period"},
        {"path": "cpu:tuning:emulator_quota", "xpath": "cputune/emulator_quota"},
        {"path": "cpu:tuning:iothread_period", "xpath": "cputune/iothread_period"},
        {"path": "cpu:tuning:iothread_quota", "xpath": "cputune/iothread_quota"},
        _cpuset_parameter(
            "cpu:tuning:vcpupin:{id}",
            "cputune/vcpupin[@vcpu='$id']",
            "cpuset",
            ["vcpu"],
        ),
        _cpuset_parameter("cpu:tuning:emulatorpin", "cputune/emulatorpin", "cpuset"),
        _cpuset_parameter(
            "cpu:tuning:iothreadpin:{id}",
            "cputune/iothreadpin[@iothread='$id']",
            "cpuset",
            ["iothread"],
        ),
        xmlutil.attribute(
            "cpu:tuning:vcpusched:{id}:scheduler",
            "cputune/vcpusched[$id]",
            "scheduler",
            ["priority", "vcpus"],
        ),
        xmlutil.attribute(
            "cpu:tuning:vcpusched:{id}:priority", "cputune/vcpusched[$id]", "priority"
        ),
        _cpuset_parameter(
            "cpu:tuning:vcpusched:{id}:vcpus", "cputune/vcpusched[$id]", "vcpus"
        ),
        xmlutil.attribute(
            "cpu:tuning:iothreadsched:{id}:scheduler",
            "cputune/iothreadsched[$id]",
            "scheduler",
            ["priority", "iothreads"],
        ),
        xmlutil.attribute(
            "cpu:tuning:iothreadsched:{id}:priority",
            "cputune/iothreadsched[$id]",
            "priority",
        ),
        _cpuset_parameter(
            "cpu:tuning:iothreadsched:{id}:iothreads",
            "cputune/iothreadsched[$id]",
            "iothreads",
        ),
        xmlutil.attribute(
            "cpu:tuning:emulatorsched:scheduler",
            "cputune/emulatorsched",
            "scheduler",
            ["priority"],
        ),
        xmlutil.attribute(
            "cpu:tuning:emulatorsched:priority", "cputune/emulatorsched", "priority"
        ),
        xmlutil.attribute(
            "cpu:tuning:cachetune:{id}:monitor:{sid}",
            "cputune/cachetune[@vcpus='$id']/monitor[@vcpus='$sid']",
            "level",
            ["vcpus"],
        ),
        xmlutil.attribute(
            "cpu:tuning:memorytune:{id}:{sid}",
            "cputune/memorytune[@vcpus='$id']/node[@id='$sid']",
            "bandwidth",
            ["id", "vcpus"],
        ),
        xmlutil.attribute("clock:offset", "clock", "offset"),
        xmlutil.attribute("clock:adjustment", "clock", "adjustment", convert=str),
        xmlutil.attribute("clock:timezone", "clock", "timezone"),
    ]

for timer in timer_names:
        params_mapping += [
            xmlutil.attribute(
                f"clock:timers:{timer}:track",
                f"clock/timer[@name='{timer}']",
                "track",
                ["name"],
            ),
            xmlutil.attribute(
                f"clock:timers:{timer}:tickpolicy",
                f"clock/timer[@name='{timer}']",
                "tickpolicy",
                ["name"],
            ),
            xmlutil.int_attribute(
                f"clock:timers:{timer}:frequency",
                f"clock/timer[@name='{timer}']",
                "frequency",
                ["name"],
            ),
            xmlutil.attribute(
                f"clock:timers:{timer}:mode",
                f"clock/timer[@name='{timer}']",
                "mode",
                ["name"],
            ),
            _yesno_attribute(
                f"clock:timers:{timer}:present",
                f"clock/timer[@name='{timer}']",
                "present",
                ["name"],
            ),
        ]
        for attr in ["slew", "threshold", "limit"]:
            params_mapping.append(
                xmlutil.int_attribute(
                    f"clock:timers:{timer}:{attr}",
                    f"clock/timer[@name='{timer}']/catchup",
                    attr,
                )
            )

for attr in ["level", "type", "size"]:
        params_mapping.append(
            xmlutil.attribute(
                "cpu:tuning:cachetune:{id}:{sid}:" + attr,
                "cputune/cachetune[@vcpus='$id']/cache[@id='$sid']",
                attr,
                ["id", "unit", "vcpus"],
            )
        )

# update NUMA host policy
    if hypervisor in ["qemu", "kvm"]:
        params_mapping += [
            xmlutil.attribute("numatune:memory:mode", "numatune/memory", "mode"),
            _cpuset_parameter("numatune:memory:nodeset", "numatune/memory", "nodeset"),
            xmlutil.attribute(
                "numatune:memnodes:{id}:mode",
                "numatune/memnode[@cellid='$id']",
                "mode",
                ["cellid"],
            ),
            _cpuset_parameter(
                "numatune:memnodes:{id}:nodeset",
                "numatune/memnode[@cellid='$id']",
                "nodeset",
                ["cellid"],
            ),
            xmlutil.attribute(
                "hypervisor_features:kvm-hint-dedicated",
                "features/kvm/hint-dedicated",
                "state",
                convert=lambda v: "on" if v else "off",
            ),
        ]

need_update = (
        salt.utils.xmlutil.change_xml(desc, data, params_mapping) or need_update
    )

# Update the XML definition with the new disks and diff changes
    devices_node = desc.find("devices")
    func_locals = locals()

def _skip_update(names):
        return all(func_locals.get(n) is None for n in names)

to_skip = {
        "disk": _skip_update(["disks", "disk_profile"]),
        "interface": _skip_update(["interfaces", "nic_profile"]),
        "graphics": _skip_update(["graphics"]),
        "serial": _skip_update(["serials"]),
        "console": _skip_update(["consoles"]),
        "hostdev": _skip_update(["host_devices"]),
    }
    changes = _compute_device_changes(desc, new_desc, to_skip)
    for dev_type in changes:
        if not to_skip[dev_type]:
            old = devices_node.findall(dev_type)
            if changes[dev_type].get("deleted") or changes[dev_type].get("new"):
                for item in old:
                    devices_node.remove(item)
                devices_node.extend(changes[dev_type]["sorted"])
                need_update = True

# Set the new definition
    if need_update:
        # Create missing disks if needed
        try:
            if changes["disk"]:
                for idx, item in enumerate(changes["disk"]["sorted"]):
                    source_file = all_disks[idx].get("source_file")
                    # We don't want to create image disks for cdrom devices
                    if all_disks[idx].get("device", "disk") == "cdrom":
                        continue
                    if (
                        item in changes["disk"]["new"]
                        and source_file
                        and not os.path.exists(source_file)
                    ):
                        _qemu_image_create(all_disks[idx])
                    elif item in changes["disk"]["new"] and not source_file:
                        _disk_volume_create(conn, all_disks[idx])
            if not test:
                xml_desc = xmlutil.element_to_str(desc)
                log.debug("Update virtual machine definition: %s", xml_desc)
                conn.defineXML(xml_desc)
            status["definition"] = True
        except libvirt.libvirtError as err:
            conn.close()
            raise err

if live:
        live_status, errors = _update_live(
            domain, new_desc, mem, cpu, old_mem, old_cpu, to_skip, test
        )
        status.update(live_status)
        if errors:
            status_errors = status.setdefault("errors", [])
            status_errors += errors

conn.close()
    return status

def list_domains(**kwargs):
    """
    Return a list of available domains.

:param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.list_domains
    """
    vms = []
    conn = __get_conn(**kwargs)
    for dom in _get_domain(conn, iterable=True):
        vms.append(dom.name())
    conn.close()
    return vms

def list_active_vms(**kwargs):
    """
    Return a list of names for active virtual machine on the minion

:param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.list_active_vms
    """
    vms = []
    conn = __get_conn(**kwargs)
    for dom in _get_domain(conn, iterable=True, inactive=False):
        vms.append(dom.name())
    conn.close()
    return vms

def list_inactive_vms(**kwargs):
    """
    Return a list of names for inactive virtual machine on the minion

:param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.list_inactive_vms
    """
    vms = []
    conn = __get_conn(**kwargs)
    for dom in _get_domain(conn, iterable=True, active=False):
        vms.append(dom.name())
    conn.close()
    return vms

def vm_info(vm_=None, **kwargs):
    """
    Return detailed information about the vms on this hyper in a
    list of dicts:

:param vm_: name of the domain
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

.. code-block:: python

[
            'your-vm': {
                'cpu': <int>,
                'maxMem': <int>,
                'mem': <int>,
                'state': '<state>',
                'cputime' <int>
                },
            ...
            ]

If you pass a VM name in as an argument then it will return info
    for just the named VM, otherwise it will return all VMs.

CLI Example:

.. code-block:: bash

salt '*' virt.vm_info
    """

def _info(conn, dom):
        """
        Compute the infos of a domain
        """
        raw = dom.info()
        return {
            "cpu": raw[3],
            "cputime": int(raw[4]),
            "disks": _get_disks(conn, dom),
            "graphics": _get_graphics(dom),
            "nics": _get_nics(dom),
            "uuid": _get_uuid(dom),
            "loader": _get_loader(dom),
            "on_crash": _get_on_crash(dom),
            "on_reboot": _get_on_reboot(dom),
            "on_poweroff": _get_on_poweroff(dom),
            "maxMem": int(raw[1]),
            "mem": int(raw[2]),
            "state": VIRT_STATE_NAME_MAP.get(raw[0], "unknown"),
        }

info = {}
    conn = __get_conn(**kwargs)
    if vm_:
        info[vm_] = _info(conn, _get_domain(conn, vm_))
    else:
        for domain in _get_domain(conn, iterable=True):
            info[domain.name()] = _info(conn, domain)
    conn.close()
    return info

def vm_state(vm_=None, **kwargs):
    """
    Return list of all the vms and their state.

If you pass a VM name in as an argument then it will return info
    for just the named VM, otherwise it will return all VMs.

:param vm_: name of the domain
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.vm_state <domain>
    """

def _info(dom):
        """
        Compute domain state
        """
        state = ""
        raw = dom.info()
        state = VIRT_STATE_NAME_MAP.get(raw[0], "unknown")
        return state

info = {}
    conn = __get_conn(**kwargs)
    if vm_:
        info[vm_] = _info(_get_domain(conn, vm_))
    else:
        for domain in _get_domain(conn, iterable=True):
            info[domain.name()] = _info(domain)
    conn.close()
    return info

def _node_info(conn):
    """
    Internal variant of node_info taking a libvirt connection as parameter
    """
    raw = conn.getInfo()
    info = {
        "cpucores": raw[6],
        "cpumhz": raw[3],
        "cpumodel": str(raw[0]),
        "cpus": raw[2],
        "cputhreads": raw[7],
        "numanodes": raw[4],
        "phymemory": raw[1],
        "sockets": raw[5],
    }
    return info

def node_info(**kwargs):
    """
    Return a dict with information about this node

:param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.node_info
    """
    conn = __get_conn(**kwargs)
    info = _node_info(conn)
    conn.close()
    return info

def _node_devices(conn):
    """
    List the host available devices, using an established connection.

:param conn: the libvirt connection handle to use.

.. versionadded:: 3003
    """
    devices = conn.listAllDevices()

devices_infos = []
    for dev in devices:
        root = ElementTree.fromstring(dev.XMLDesc())

# Only list PCI and USB devices that can be passed through as well as NICs
        if not set(dev.listCaps()) & {"pci", "usb_device", "net"}:
            continue

infos = {
            "caps": " ".join(dev.listCaps()),
        }

if "net" in dev.listCaps():
            parent = root.find(".//parent").text
            # Don't show, lo, dummies and libvirt-created NICs
            if parent == "computer":
                continue
            infos.update(
                {
                    "name": root.find(".//interface").text,
                    "address": root.find(".//address").text,
                    "device name": parent,
                    "state": root.find(".//link").get("state"),
                }
            )
            devices_infos.append(infos)
            continue

vendor_node = root.find(".//vendor")
        vendor_id = vendor_node.get("id").lower()
        product_node = root.find(".//product")
        product_id = product_node.get("id").lower()
        infos.update(
            {"name": dev.name(), "vendor_id": vendor_id, "product_id": product_id}
        )

# Vendor or product display name may not be set
        if vendor_node.text:
            infos["vendor"] = vendor_node.text
        if product_node.text:
            infos["product"] = product_node.text

if "pci" in dev.listCaps():
            infos["address"] = "{:04x}:{:02x}:{:02x}.{}".format(
                int(root.find(".//domain").text),
                int(root.find(".//bus").text),
                int(root.find(".//slot").text),
                root.find(".//function").text,
            )
            class_node = root.find(".//class")
            if class_node is not None:
                infos["PCI class"] = class_node.text

# Get the list of Virtual Functions if any
            vf_addresses = [
                _format_pci_address(vf)
                for vf in root.findall(
                    "./capability[@type='pci']/capability[@type='virt_functions']/address"
                )
            ]
            if vf_addresses:
                infos["virtual functions"] = vf_addresses

# Get the Physical Function if any
            pf = root.find(
                "./capability[@type='pci']/capability[@type='phys_function']/address"
            )
            if pf is not None:
                infos["physical function"] = _format_pci_address(pf)
        elif "usb_device" in dev.listCaps():
            infos["address"] = "{:03}:{:03}".format(
                int(root.find(".//bus").text), int(root.find(".//device").text)
            )

# Don't list the pci bridges and USB hosts from the linux foundation
        linux_usb_host = vendor_id == "0x1d6b" and product_id in [
            "0x0001",
            "0x0002",
            "0x0003",
        ]
        if (
            root.find(".//capability[@type='pci-bridge']") is None
            and not linux_usb_host
        ):
            devices_infos.append(infos)

return devices_infos

def node_devices(**kwargs):
    """
    List the host available devices.

:param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. versionadded:: 3003
    """
    conn = __get_conn(**kwargs)
    devs = _node_devices(conn)
    conn.close()
    return devs

def get_nics(vm_, **kwargs):
    """
    Return info about the network interfaces of a named vm

:param vm_: name of the domain
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.get_nics <domain>
    """
    conn = __get_conn(**kwargs)
    nics = _get_nics(_get_domain(conn, vm_))
    conn.close()
    return nics

def get_macs(vm_, **kwargs):
    """
    Return a list off MAC addresses from the named vm

:param vm_: name of the domain
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.get_macs <domain>
    """
    doc = ElementTree.fromstring(get_xml(vm_, **kwargs))
    return [node.get("address") for node in doc.findall("devices/interface/mac")]

def get_graphics(vm_, **kwargs):
    """
    Returns the information on vnc for a given vm

:param vm_: name of the domain
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.get_graphics <domain>
    """
    conn = __get_conn(**kwargs)
    graphics = _get_graphics(_get_domain(conn, vm_))
    conn.close()
    return graphics

def get_loader(vm_, **kwargs):
    """
    Returns the information on the loader for a given vm

:param vm_: name of the domain
    :param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

CLI Example:

.. code-block:: bash

salt '*' virt.get_loader <domain>

.. versionadded:: 2019.2.0
    """
    conn = __get_conn(**kwargs)
    try:
        loader = _get_loader(_get_domain(conn, vm_))
        return loader
    finally:
        conn.close()

def get_disks(vm_, **kwargs):
    """
    Return the disks of a named vm

:param vm_: name of the domain
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.get_disks <domain>
    """
    conn = __get_conn(**kwargs)
    disks = _get_disks(conn, _get_domain(conn, vm_))
    conn.close()
    return disks

def setmem(vm_, memory, config=False, **kwargs):
    """
    Changes the amount of memory allocated to VM. The VM must be shutdown
    for this to work.

:param vm_: name of the domain
    :param memory: memory amount to set in MB
    :param config: if True then libvirt will be asked to modify the config as well
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.setmem <domain> <size>
        salt '*' virt.setmem my_domain 768
    """
    conn = __get_conn(**kwargs)
    dom = _get_domain(conn, vm_)

if VIRT_STATE_NAME_MAP.get(dom.info()[0], "unknown") != "shutdown":
        return False

# libvirt has a funny bitwise system for the flags in that the flag
    # to affect the "current" setting is 0, which means that to set the
    # current setting we have to call it a second time with just 0 set
    flags = libvirt.VIR_DOMAIN_MEM_MAXIMUM
    if config:
        flags = flags | libvirt.VIR_DOMAIN_AFFECT_CONFIG

ret1 = dom.setMemoryFlags(memory * 1024, flags)
    ret2 = dom.setMemoryFlags(memory * 1024, libvirt.VIR_DOMAIN_AFFECT_CURRENT)

conn.close()

# return True if both calls succeeded
    return ret1 == ret2 == 0

def setvcpus(vm_, vcpus, config=False, **kwargs):
    """
    Changes the amount of vcpus allocated to VM. The VM must be shutdown
    for this to work.

If config is True then we ask libvirt to modify the config as well

:param vm_: name of the domain
    :param vcpus: integer representing the number of CPUs to be assigned
    :param config: if True then libvirt will be asked to modify the config as well
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.setvcpus <domain> <amount>
        salt '*' virt.setvcpus my_domain 4
    """
    conn = __get_conn(**kwargs)
    dom = _get_domain(conn, vm_)

if VIRT_STATE_NAME_MAP.get(dom.info()[0], "unknown") != "shutdown":
        return False

# see notes in setmem
    flags = libvirt.VIR_DOMAIN_VCPU_MAXIMUM
    if config:
        flags = flags | libvirt.VIR_DOMAIN_AFFECT_CONFIG

ret1 = dom.setVcpusFlags(vcpus, flags)
    ret2 = dom.setVcpusFlags(vcpus, libvirt.VIR_DOMAIN_AFFECT_CURRENT)

conn.close()

return ret1 == ret2 == 0

def _freemem(conn):
    """
    Internal variant of freemem taking a libvirt connection as parameter
    """
    mem = conn.getInfo()[1]
    # Take off just enough to sustain the hypervisor
    mem -= 256
    for dom in _get_domain(conn, iterable=True):
        if dom.ID() > 0:
            mem -= dom.info()[2] / 1024
    return mem

def freemem(**kwargs):
    """
    Return an int representing the amount of memory (in MB) that has not
    been given to virtual machines on this node

:param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.freemem
    """
    conn = __get_conn(**kwargs)
    mem = _freemem(conn)
    conn.close()
    return mem

def _freecpu(conn):
    """
    Internal variant of freecpu taking a libvirt connection as parameter
    """
    cpus = conn.getInfo()[2]
    for dom in _get_domain(conn, iterable=True):
        if dom.ID() > 0:
            cpus -= dom.info()[3]
    return cpus

def freecpu(**kwargs):
    """
    Return an int representing the number of unallocated cpus on this
    hypervisor

:param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.freecpu
    """
    conn = __get_conn(**kwargs)
    cpus = _freecpu(conn)
    conn.close()
    return cpus

def full_info(**kwargs):
    """
    Return the node_info, vm_info and freemem

:param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.full_info
    """
    conn = __get_conn(**kwargs)
    info = {
        "freecpu": _freecpu(conn),
        "freemem": _freemem(conn),
        "node_info": _node_info(conn),
        "vm_info": vm_info(),
    }
    conn.close()
    return info

def get_xml(vm_, **kwargs):
    """
    Returns the XML for a given vm

:param vm_: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.get_xml <domain>
    """
    conn = __get_conn(**kwargs)
    xml_desc = (
        vm_.XMLDesc(0)
        if isinstance(vm_, libvirt.virDomain)
        else _get_domain(conn, vm_).XMLDesc(0)
    )
    conn.close()
    return xml_desc

def get_profiles(hypervisor=None, **kwargs):
    """
    Return the virt profiles for hypervisor.

Currently there are profiles for:

- nic
    - disk

:param hypervisor: override the default machine type.
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.get_profiles
        salt '*' virt.get_profiles hypervisor=vmware
    """
    # Use the machine types as possible values
    # Prefer 'kvm' over the others if available
    conn = __get_conn(**kwargs)
    caps = _capabilities(conn)
    hypervisors = sorted(
        {
            x
            for y in [guest["arch"]["domains"].keys() for guest in caps["guests"]]
            for x in y
        }
    )
    if len(hypervisors) == 0:
        raise SaltInvocationError("No supported hypervisors were found")

if not hypervisor:
        hypervisor = "kvm" if "kvm" in hypervisors else hypervisors[0]

ret = {
        "disk": {"default": _disk_profile(conn, "default", hypervisor, [], None)},
        "nic": {"default": _nic_profile("default", hypervisor)},
    }
    virtconf = __salt__["config.get"]("virt", {})

for profile in virtconf.get("disk", []):
        ret["disk"][profile] = _disk_profile(conn, profile, hypervisor, [], None)

for profile in virtconf.get("nic", []):
        ret["nic"][profile] = _nic_profile(profile, hypervisor)

return ret

def shutdown(vm_, **kwargs):
    """
    Send a soft shutdown signal to the named vm

:param vm_: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.shutdown <domain>
    """
    conn = __get_conn(**kwargs)
    dom = _get_domain(conn, vm_)
    ret = dom.shutdown() == 0
    conn.close()
    return ret

def pause(vm_, **kwargs):
    """
    Pause the named vm

:param vm_: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.pause <domain>
    """
    conn = __get_conn(**kwargs)
    dom = _get_domain(conn, vm_)
    ret = dom.suspend() == 0
    conn.close()
    return ret

def resume(vm_, **kwargs):
    """
    Resume the named vm

:param vm_: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.resume <domain>
    """
    conn = __get_conn(**kwargs)
    dom = _get_domain(conn, vm_)
    ret = dom.resume() == 0
    conn.close()
    return ret

def start(name, **kwargs):
    """
    Start a defined domain

:param vm_: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.start <domain>
    """
    conn = __get_conn(**kwargs)
    ret = _get_domain(conn, name).create() == 0
    conn.close()
    return ret

def stop(name, **kwargs):
    """
    Hard power down the virtual machine, this is equivalent to pulling the power.

:param vm_: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.stop <domain>
    """
    conn = __get_conn(**kwargs)
    ret = _get_domain(conn, name).destroy() == 0
    conn.close()
    return ret

def reboot(name, **kwargs):
    """
    Reboot a domain via ACPI request

:param vm_: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.reboot <domain>
    """
    conn = __get_conn(**kwargs)
    ret = _get_domain(conn, name).reboot(libvirt.VIR_DOMAIN_REBOOT_DEFAULT) == 0
    conn.close()
    return ret

def reset(vm_, **kwargs):
    """
    Reset a VM by emulating the reset button on a physical machine

:param vm_: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.reset <domain>
    """
    conn = __get_conn(**kwargs)
    dom = _get_domain(conn, vm_)

# reset takes a flag, like reboot, but it is not yet used
    # so we just pass in 0
    # see: http://libvirt.org/html/libvirt-libvirt.html#virDomainReset
    ret = dom.reset(0) == 0
    conn.close()
    return ret

def ctrl_alt_del(vm_, **kwargs):
    """
    Sends CTRL+ALT+DEL to a VM

:param vm_: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.ctrl_alt_del <domain>
    """
    conn = __get_conn(**kwargs)
    dom = _get_domain(conn, vm_)
    ret = dom.sendKey(0, 0, [29, 56, 111], 3, 0) == 0
    conn.close()
    return ret

def create_xml_str(xml, **kwargs):  # pylint: disable=redefined-outer-name
    """
    Start a transient domain based on the XML passed to the function

:param xml: libvirt XML definition of the domain
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.create_xml_str <XML in string format>
    """
    conn = __get_conn(**kwargs)
    ret = conn.createXML(xml, 0) is not None
    conn.close()
    return ret

def create_xml_path(path, **kwargs):
    """
    Start a transient domain based on the XML-file path passed to the function

:param path: path to a file containing the libvirt XML definition of the domain
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.create_xml_path <path to XML file on the node>
    """
    try:
        with salt.utils.files.fopen(path, "r") as fp_:
            return create_xml_str(
                salt.utils.stringutils.to_unicode(fp_.read()), **kwargs
            )
    except OSError:
        return False

def define_xml_str(xml, **kwargs):  # pylint: disable=redefined-outer-name
    """
    Define a persistent domain based on the XML passed to the function

:param xml: libvirt XML definition of the domain
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.define_xml_str <XML in string format>
    """
    conn = __get_conn(**kwargs)
    ret = conn.defineXML(xml) is not None
    conn.close()
    return ret

def define_xml_path(path, **kwargs):
    """
    Define a persistent domain based on the XML-file path passed to the function

:param path: path to a file containing the libvirt XML definition of the domain
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.define_xml_path <path to XML file on the node>

"""
    try:
        with salt.utils.files.fopen(path, "r") as fp_:
            return define_xml_str(
                salt.utils.stringutils.to_unicode(fp_.read()), **kwargs
            )
    except OSError:
        return False

def _define_vol_xml_str(conn, xml, pool=None):  # pylint: disable=redefined-outer-name
    """
    Same function than define_vml_xml_str but using an already opened libvirt connection
    """
    default_pool = "default" if conn.getType() != "ESX" else "0"
    poolname = (
        pool if pool else __salt__["config.get"]("virt:storagepool", default_pool)
    )
    pool = conn.storagePoolLookupByName(str(poolname))
    ret = pool.createXML(xml, 0) is not None
    return ret

def define_vol_xml_str(
    xml, pool=None, **kwargs
):  # pylint: disable=redefined-outer-name
    """
    Define a volume based on the XML passed to the function

:param xml: libvirt XML definition of the storage volume
    :param pool:
        storage pool name to define the volume in.
        If defined, this parameter will override the configuration setting.

.. versionadded:: 3001
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.define_vol_xml_str <XML in string format>

The storage pool where the disk image will be defined is ``default``
    unless changed with the pool parameter or a configuration like this:

.. code-block:: yaml

virt:
            storagepool: mine
    """
    conn = __get_conn(**kwargs)
    ret = False
    try:
        ret = _define_vol_xml_str(conn, xml, pool=pool)
    except libvirtError as err:
        raise CommandExecutionError(err.get_error_message())
    finally:
        conn.close()
    return ret

def define_vol_xml_path(path, pool=None, **kwargs):
    """
    Define a volume based on the XML-file path passed to the function

:param path: path to a file containing the libvirt XML definition of the volume
    :param pool:
        storage pool name to define the volume in.
        If defined, this parameter will override the configuration setting.

.. versionadded:: 3001
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.define_vol_xml_path <path to XML file on the node>

"""
    try:
        with salt.utils.files.fopen(path, "r") as fp_:
            return define_vol_xml_str(
                salt.utils.stringutils.to_unicode(fp_.read()), pool=pool, **kwargs
            )
    except OSError:
        return False

def migrate(vm_, target, **kwargs):
    """
    Shared storage migration

:param vm_: domain name
    :param target: target libvirt URI or host name

:param kwargs:
        - live:            Use live migration. Default value is True.
        - persistent:      Leave the domain persistent on destination host.
                           Default value is True.
        - undefinesource:  Undefine the domain on the source host.
                           Default value is True.
        - offline:         If set to True it will migrate the domain definition
                           without starting the domain on destination and without
                           stopping it on source host. Default value is False.
        - max_bandwidth:   The maximum bandwidth (in MiB/s) that will be used.
        - max_downtime:    Set maximum tolerable downtime for live-migration.
                           The value represents a number of milliseconds the guest
                           is allowed to be down at the end of live migration.
        - parallel_connections: Specify a number of parallel network connections
                           to be used to send memory pages to the destination host.
        - compressed:      Activate compression.
        - comp_methods:    A comma-separated list of compression methods. Supported
                           methods are "mt" and "xbzrle" and can be  used in any
                           combination. QEMU defaults to "xbzrle".
        - comp_mt_level:   Set compression level. Values are in range from 0 to 9,
                           where 1 is maximum speed and 9 is  maximum compression.
        - comp_mt_threads: Set number of compress threads on source host.
        - comp_mt_dthreads: Set number of decompress threads on target host.
        - comp_xbzrle_cache: Set the size of page cache for xbzrle compression in bytes.
        - copy_storage:    Migrate non-shared storage. It must be one of the following
                           values: all (full disk copy) or incremental (Incremental copy)
        - postcopy:        Enable the use of post-copy migration.
        - postcopy_bandwidth: The maximum bandwidth allowed in post-copy phase. (MiB/s)
        - username:        Username to connect with target host
        - password:        Password to connect with target host

.. versionadded:: 3002

CLI Example:

.. code-block:: bash

salt '*' virt.migrate <domain> <target hypervisor URI>
        salt src virt.migrate guest qemu+ssh://dst/system
        salt src virt.migrate guest qemu+tls://dst/system
        salt src virt.migrate guest qemu+tcp://dst/system

A tunnel data migration can be performed by setting this in the
    configuration:

.. code-block:: yaml

virt:
            tunnel: True

For more details on tunnelled data migrations, report to
    https://libvirt.org/migration.html#transporttunnel
    """

conn = __get_conn()
    dom = _get_domain(conn, vm_)

if not urllib.parse.urlparse(target).scheme:
        proto = "qemu"
        dst_uri = f"{proto}://{target}/system"
    else:
        dst_uri = target

ret = _migrate(dom, dst_uri, **kwargs)
    conn.close()
    return ret

def migrate_start_postcopy(vm_):
    """
    Starts post-copy migration. This function has to be called
    while live migration is in progress and it has been initiated
    with the `postcopy=True` option.

CLI Example:

.. code-block:: bash

salt '*' virt.migrate_start_postcopy <domain>
    """
    conn = __get_conn()
    dom = _get_domain(conn, vm_)
    try:
        dom.migrateStartPostCopy()
    except libvirt.libvirtError as err:
        conn.close()
        raise CommandExecutionError(err.get_error_message())
    conn.close()

def seed_non_shared_migrate(disks, force=False):
    """
    Non shared migration requires that the disks be present on the migration
    destination, pass the disks information via this function, to the
    migration destination before executing the migration.

:param disks: the list of disk data as provided by virt.get_disks
    :param force: skip checking the compatibility of source and target disk
                  images if True. (default: False)

CLI Example:

.. code-block:: bash

salt '*' virt.seed_non_shared_migrate <disks>
    """
    for _, data in disks.items():
        fn_ = data["file"]
        form = data["file format"]
        size = data["virtual size"].split()[1][1:]
        if os.path.isfile(fn_) and not force:
            # the target exists, check to see if it is compatible
            pre = salt.utils.yaml.safe_load(
                subprocess.Popen(
                    ["qemu-img", "info", "arch"], stdout=subprocess.PIPE
                ).communicate()[0]
            )
            if (
                pre["file format"] != data["file format"]
                and pre["virtual size"] != data["virtual size"]
            ):
                return False
        if not os.path.isdir(os.path.dirname(fn_)):
            os.makedirs(os.path.dirname(fn_))
        if os.path.isfile(fn_):
            os.remove(fn_)
        subprocess.call(["qemu-img", "create", "-f", form, fn_, size])
        creds = _libvirt_creds()
        subprocess.call(["chown", "{user}:{group}".format(**creds), fn_])
    return True

def set_autostart(vm_, state="on", **kwargs):
    """
    Set the autostart flag on a VM so that the VM will start with the host
    system on reboot.

:param vm_: domain name
    :param state: 'on' to auto start the VM, 'off' to mark the VM not to be
                  started when the host boots
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt "*" virt.set_autostart <domain> <on | off>
    """
    conn = __get_conn(**kwargs)
    dom = _get_domain(conn, vm_)

# return False if state is set to something other then on or off
    ret = False

if state == "on":
        ret = dom.setAutostart(1) == 0

elif state == "off":
        ret = dom.setAutostart(0) == 0

conn.close()
    return ret

def undefine(vm_, **kwargs):
    """
    Remove a defined vm, this does not purge the virtual machine image, and
    this only works if the vm is powered down

:param vm_: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.undefine <domain>
    """
    conn = __get_conn(**kwargs)
    dom = _get_domain(conn, vm_)
    if getattr(libvirt, "VIR_DOMAIN_UNDEFINE_NVRAM", False):
        # This one is only in 1.2.8+
        ret = dom.undefineFlags(libvirt.VIR_DOMAIN_UNDEFINE_NVRAM) == 0
    else:
        ret = dom.undefine() == 0
    conn.close()
    return ret

def purge(vm_, dirs=False, removables=False, **kwargs):
    """
    Recursively destroy and delete a persistent virtual machine, pass True for
    dir's to also delete the directories containing the virtual machine disk
    images - USE WITH EXTREME CAUTION!

:param vm_: domain name
    :param dirs: pass True to remove containing directories
    :param removables: pass True to remove removable devices

.. versionadded:: 2019.2.0
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.purge <domain>
    """
    conn = __get_conn(**kwargs)
    dom = _get_domain(conn, vm_)
    disks = _get_disks(conn, dom)
    if (
        VIRT_STATE_NAME_MAP.get(dom.info()[0], "unknown") != "shutdown"
        and dom.destroy() != 0
    ):
        return False
    directories = set()
    for disk in disks:
        if not removables and disks[disk]["type"] in ["cdrom", "floppy"]:
            continue
        if disks[disk].get("zfs", False):
            # TODO create solution for 'dataset is busy'
            time.sleep(3)
            fs_name = disks[disk]["file"][len("/dev/zvol/") :]
            log.info("Destroying VM ZFS volume %s", fs_name)
            __salt__["zfs.destroy"](name=fs_name, force=True)
        elif os.path.exists(disks[disk]["file"]):
            os.remove(disks[disk]["file"])
            directories.add(os.path.dirname(disks[disk]["file"]))
        else:
            # We may have a volume to delete here
            matcher = re.match("^(?P<pool>[^/]+)/(?P<volume>.*)$", disks[disk]["file"])
            if matcher:
                pool_name = matcher.group("pool")
                pool = None
                if pool_name in conn.listStoragePools():
                    pool = conn.storagePoolLookupByName(pool_name)

if pool and matcher.group("volume") in pool.listVolumes():
                    volume = pool.storageVolLookupByName(matcher.group("volume"))
                    volume.delete()

if dirs:
        for dir_ in directories:
            shutil.rmtree(dir_)
    if getattr(libvirt, "VIR_DOMAIN_UNDEFINE_NVRAM", False):
        # This one is only in 1.2.8+
        try:
            dom.undefineFlags(libvirt.VIR_DOMAIN_UNDEFINE_NVRAM)
        except Exception:  # pylint: disable=broad-except
            dom.undefine()
    else:
        dom.undefine()
    conn.close()
    return True

def virt_type():
    """
    Returns the virtual machine type as a string

CLI Example:

.. code-block:: bash

salt '*' virt.virt_type
    """
    return __grains__["virtual"]

def _is_kvm_hyper():
    """
    Returns a bool whether or not this node is a KVM hypervisor
    """
    if not os.path.exists("/dev/kvm"):
        return False
    return "libvirtd" in __salt__["cmd.run"](__grains__["ps"])

def _is_xen_hyper():
    """
    Returns a bool whether or not this node is a XEN hypervisor
    """
    try:
        if __grains__["virtual_subtype"] != "Xen Dom0":
            return False
    except KeyError:
        # virtual_subtype isn't set everywhere.
        return False
    try:
        with salt.utils.files.fopen("/proc/modules") as fp_:
            if "xen_" not in salt.utils.stringutils.to_unicode(fp_.read()):
                return False
    except OSError:
        # No /proc/modules? Are we on Windows? Or Solaris?
        return False
    return "libvirtd" in __salt__["cmd.run"](__grains__["ps"])

def get_hypervisor():
    """
    Returns the name of the hypervisor running on this node or ``None``.

Detected hypervisors:

- kvm
    - xen
    - bhyve

CLI Example:

.. code-block:: bash

salt '*' virt.get_hypervisor

.. versionadded:: 2019.2.0
        the function and the ``kvm``, ``xen`` and ``bhyve`` hypervisors support
    """
    # To add a new 'foo' hypervisor, add the _is_foo_hyper function,
    # add 'foo' to the list below and add it to the docstring with a .. versionadded::
    hypervisors = ["kvm", "xen", "bhyve"]
    result = [
        hyper
        for hyper in hypervisors
        if getattr(sys.modules[__name__], f"_is_{hyper}_hyper")()
    ]
    return result[0] if result else None

def _is_bhyve_hyper():
    vmm_enabled = False
    try:
        stdout = subprocess.Popen(
            ["sysctl", "hw.vmm.create"], stdout=subprocess.PIPE
        ).communicate()[0]
        vmm_enabled = len(salt.utils.stringutils.to_str(stdout).split('"')[1]) != 0
    except IndexError:
        pass
    return vmm_enabled

def is_hyper():
    """
    Returns a bool whether or not this node is a hypervisor of any kind

CLI Example:

.. code-block:: bash

salt '*' virt.is_hyper
    """
    if HAS_LIBVIRT:
        return _is_xen_hyper() or _is_kvm_hyper() or _is_bhyve_hyper()
    return False

def vm_cputime(vm_=None, **kwargs):
    """
    Return cputime used by the vms on this hyper in a
    list of dicts:

:param vm_: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

.. code-block:: python

[
            'your-vm': {
                'cputime' <int>
                'cputime_percent' <int>
                },
            ...
            ]

If you pass a VM name in as an argument then it will return info
    for just the named VM, otherwise it will return all VMs.

CLI Example:

.. code-block:: bash

salt '*' virt.vm_cputime
    """
    conn = __get_conn(**kwargs)
    host_cpus = conn.getInfo()[2]

def _info(dom):
        """
        Compute cputime info of a domain
        """
        raw = dom.info()
        vcpus = int(raw[3])
        cputime = int(raw[4])
        cputime_percent = 0
        if cputime:
            # Divide by vcpus to always return a number between 0 and 100
            cputime_percent = (1.0e-7 * cputime / host_cpus) / vcpus
        return {
            "cputime": int(raw[4]),
            "cputime_percent": int(f"{cputime_percent:.0f}"),
        }

info = {}
    if vm_:
        info[vm_] = _info(_get_domain(conn, vm_))
    else:
        for domain in _get_domain(conn, iterable=True):
            info[domain.name()] = _info(domain)
    conn.close()
    return info

def vm_netstats(vm_=None, **kwargs):
    """
    Return combined network counters used by the vms on this hyper in a
    list of dicts:

:param vm_: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

.. code-block:: python

[
            'your-vm': {
                'rx_bytes'   : 0,
                'rx_packets' : 0,
                'rx_errs'    : 0,
                'rx_drop'    : 0,
                'tx_bytes'   : 0,
                'tx_packets' : 0,
                'tx_errs'    : 0,
                'tx_drop'    : 0
                },
            ...
            ]

If you pass a VM name in as an argument then it will return info
    for just the named VM, otherwise it will return all VMs.

CLI Example:

.. code-block:: bash

salt '*' virt.vm_netstats
    """

def _info(dom):
        """
        Compute network stats of a domain
        """
        nics = _get_nics(dom)
        ret = {
            "rx_bytes": 0,
            "rx_packets": 0,
            "rx_errs": 0,
            "rx_drop": 0,
            "tx_bytes": 0,
            "tx_packets": 0,
            "tx_errs": 0,
            "tx_drop": 0,
        }
        for attrs in nics.values():
            if "target" in attrs:
                dev = attrs["target"]
                stats = dom.interfaceStats(dev)
                ret["rx_bytes"] += stats[0]
                ret["rx_packets"] += stats[1]
                ret["rx_errs"] += stats[2]
                ret["rx_drop"] += stats[3]
                ret["tx_bytes"] += stats[4]
                ret["tx_packets"] += stats[5]
                ret["tx_errs"] += stats[6]
                ret["tx_drop"] += stats[7]

return ret

def vm_diskstats(vm_=None, **kwargs):
    """
    Return disk usage counters used by the vms on this hyper in a
    list of dicts:

:param vm_: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

.. code-block:: python

[
            'your-vm': {
                'rd_req'   : 0,
                'rd_bytes' : 0,
                'wr_req'   : 0,
                'wr_bytes' : 0,
                'errs'     : 0
                },
            ...
            ]

If you pass a VM name in as an argument then it will return info
    for just the named VM, otherwise it will return all VMs.

CLI Example:

.. code-block:: bash

salt '*' virt.vm_blockstats
    """

def get_disk_devs(dom):
        """
        Extract the disk devices names from the domain XML definition
        """
        doc = ElementTree.fromstring(get_xml(dom, **kwargs))
        return [target.get("dev") for target in doc.findall("devices/disk/target")]

def _info(dom):
        """
        Compute the disk stats of a domain
        """
        # Do not use get_disks, since it uses qemu-img and is very slow
        # and unsuitable for any sort of real time statistics
        disks = get_disk_devs(dom)
        ret = {"rd_req": 0, "rd_bytes": 0, "wr_req": 0, "wr_bytes": 0, "errs": 0}
        for disk in disks:
            stats = dom.blockStats(disk)
            ret["rd_req"] += stats[0]
            ret["rd_bytes"] += stats[1]
            ret["wr_req"] += stats[2]
            ret["wr_bytes"] += stats[3]
            ret["errs"] += stats[4]

return ret

info = {}
    conn = __get_conn(**kwargs)
    if vm_:
        info[vm_] = _info(_get_domain(conn, vm_))
    else:
        # Can not run function blockStats on inactive VMs
        for domain in _get_domain(conn, iterable=True, inactive=False):
            info[domain.name()] = _info(domain)
    conn.close()
    return info

def _parse_snapshot_description(vm_snapshot, unix_time=False):
    """
    Parse XML doc and return a dict with the status values.

:param xmldoc:
    :return:
    """
    ret = dict()
    tree = ElementTree.fromstring(vm_snapshot.getXMLDesc())
    for node in tree:
        if node.tag == "name":
            ret["name"] = node.text
        elif node.tag == "creationTime":
            ret["created"] = (
                datetime.datetime.fromtimestamp(float(node.text)).isoformat(" ")
                if not unix_time
                else float(node.text)
            )
        elif node.tag == "state":
            ret["running"] = node.text == "running"

ret["current"] = vm_snapshot.isCurrent() == 1

return ret

def list_snapshots(domain=None, **kwargs):
    """
    List available snapshots for certain vm or for all.

:param domain: domain name
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

.. versionadded:: 2016.3.0

CLI Example:

.. code-block:: bash

salt '*' virt.list_snapshots
        salt '*' virt.list_snapshots <domain>
    """
    ret = dict()
    conn = __get_conn(**kwargs)
    for vm_domain in _get_domain(conn, *(domain and [domain] or list()), iterable=True):
        ret[vm_domain.name()] = [
            _parse_snapshot_description(snap) for snap in vm_domain.listAllSnapshots()
        ] or "N/A"

conn.close()
    return ret

def snapshot(domain, name=None, suffix=None, **kwargs):
    """
    Create a snapshot of a VM.

:param domain: domain name
    :param name: Name of the snapshot. If the name is omitted, then will be used original domain
                 name with ISO 8601 time as a suffix.

:param suffix: Add suffix for the new name. Useful in states, where such snapshots
                   can be distinguished from manually created.
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

.. versionadded:: 2016.3.0

CLI Example:

.. code-block:: bash

salt '*' virt.snapshot <domain>
    """
    if name and name.lower() == domain.lower():
        raise CommandExecutionError(
            "Virtual Machine {name} is already defined. "
            "Please choose another name for the snapshot".format(name=name)
        )
    if not name:
        name = "{domain}-{tsnap}".format(
            domain=domain, tsnap=time.strftime("%Y%m%d-%H%M%S", time.localtime())
        )

if suffix:
        name = f"{name}-{suffix}"

doc = ElementTree.Element("domainsnapshot")
    n_name = ElementTree.SubElement(doc, "name")
    n_name.text = name

conn = __get_conn(**kwargs)
    _get_domain(conn, domain).snapshotCreateXML(xmlutil.element_to_str(doc))
    conn.close()

return {"name": name}

def delete_snapshots(name, *names, **kwargs):
    """
    Delete one or more snapshots of the given VM.

:param name: domain name
    :param names: names of the snapshots to remove
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

.. versionadded:: 2016.3.0

CLI Example:

.. code-block:: bash

salt '*' virt.delete_snapshots <domain> all=True
        salt '*' virt.delete_snapshots <domain> <snapshot>
        salt '*' virt.delete_snapshots <domain> <snapshot1> <snapshot2> ...
    """
    deleted = dict()
    conn = __get_conn(**kwargs)
    domain = _get_domain(conn, name)
    for snap in domain.listAllSnapshots():
        if snap.getName() in names or not names:
            deleted[snap.getName()] = _parse_snapshot_description(snap)
            snap.delete()
    conn.close()

available = {
        name: [_parse_snapshot_description(snap) for snap in domain.listAllSnapshots()]
        or "N/A"
    }

return {"available": available, "deleted": deleted}

def revert_snapshot(name, vm_snapshot=None, cleanup=False, **kwargs):
    """
    Revert snapshot to the previous from current (if available) or to the specific.

:param name: domain name
    :param vm_snapshot: name of the snapshot to revert
    :param cleanup: Remove all newer than reverted snapshots. Values: True or False (default False).
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

.. versionadded:: 2016.3.0

CLI Example:

.. code-block:: bash

salt '*' virt.revert <domain>
        salt '*' virt.revert <domain> <snapshot>
    """
    ret = dict()
    conn = __get_conn(**kwargs)
    domain = _get_domain(conn, name)
    snapshots = domain.listAllSnapshots()

_snapshots = list()
    for snap_obj in snapshots:
        _snapshots.append(
            {
                "idx": _parse_snapshot_description(snap_obj, unix_time=True)["created"],
                "ptr": snap_obj,
            }
        )
    snapshots = [
        w_ptr["ptr"]
        for w_ptr in sorted(_snapshots, key=lambda item: item["idx"], reverse=True)
    ]
    del _snapshots

if not snapshots:
        conn.close()
        raise CommandExecutionError("No snapshots found")
    elif len(snapshots) == 1:
        conn.close()
        raise CommandExecutionError(
            "Cannot revert to itself: only one snapshot is available."
        )

snap = None
    for p_snap in snapshots:
        if not vm_snapshot:
            if p_snap.isCurrent() and snapshots[snapshots.index(p_snap) + 1 :]:
                snap = snapshots[snapshots.index(p_snap) + 1 :][0]
                break
        elif p_snap.getName() == vm_snapshot:
            snap = p_snap
            break

if not snap:
        conn.close()
        raise CommandExecutionError(
            snapshot
            and f'Snapshot "{vm_snapshot}" not found'
            or "No more previous snapshots available"
        )
    elif snap.isCurrent():
        conn.close()
        raise CommandExecutionError("Cannot revert to the currently running snapshot.")

domain.revertToSnapshot(snap)
    ret["reverted"] = snap.getName()

if cleanup:
        delete = list()
        for p_snap in snapshots:
            if p_snap.getName() != snap.getName():
                delete.append(p_snap.getName())
                p_snap.delete()
            else:
                break
        ret["deleted"] = delete
    else:
        ret["deleted"] = "N/A"

conn.close()

return ret

def _caps_add_machine(machines, node):
    """
    Parse the <machine> element of the host capabilities and add it
    to the machines list.
    """
    maxcpus = node.get("maxCpus")
    canonical = node.get("canonical")
    name = node.text

alternate_name = ""
    if canonical:
        alternate_name = name
        name = canonical

machine = machines.get(name)
    if not machine:
        machine = {"alternate_names": []}
        if maxcpus:
            machine["maxcpus"] = int(maxcpus)
        machines[name] = machine
    if alternate_name:
        machine["alternate_names"].append(alternate_name)

def _parse_caps_guest(guest):
    """
    Parse the <guest> element of the connection capabilities XML
    """
    arch_node = guest.find("arch")
    result = {
        "os_type": guest.find("os_type").text,
        "arch": {"name": arch_node.get("name"), "machines": {}, "domains": {}},
    }

child = None
    for child in arch_node:
        if child.tag == "wordsize":
            result["arch"]["wordsize"] = int(child.text)
        elif child.tag == "emulator":
            result["arch"]["emulator"] = child.text
        elif child.tag == "machine":
            _caps_add_machine(result["arch"]["machines"], child)
        elif child.tag == "domain":
            domain_type = child.get("type")
            domain = {"emulator": None, "machines": {}}
            emulator_node = child.find("emulator")
            if emulator_node is not None:
                domain["emulator"] = emulator_node.text
            for machine in child.findall("machine"):
                _caps_add_machine(domain["machines"], machine)
            result["arch"]["domains"][domain_type] = domain

# Note that some features have no default and toggle attributes.
    # This may not be a perfect match, but represent them as enabled by default
    # without possibility to toggle them.
    # Some guests may also have no feature at all (xen pv for instance)
    features_nodes = guest.find("features")
    if features_nodes is not None and child is not None:
        result["features"] = {
            child.tag: {
                "toggle": child.get("toggle", "no") == "yes",
                "default": child.get("default", "on") == "on",
            }
            for child in features_nodes
        }
    return result

def _parse_caps_cell(cell):
    """
    Parse the <cell> nodes of the connection capabilities XML output.
    """
    result = {"id": int(cell.get("id"))}

mem_node = cell.find("memory")
    if mem_node is not None:
        unit = mem_node.get("unit", "KiB")
        memory = mem_node.text
        result["memory"] = f"{memory} {unit}"

pages = [
        {
            "size": "{} {}".format(page.get("size"), page.get("unit", "KiB")),
            "available": int(page.text),
        }
        for page in cell.findall("pages")
    ]
    if pages:
        result["pages"] = pages

distances = {
        int(distance.get("id")): int(distance.get("value"))
        for distance in cell.findall("distances/sibling")
    }
    if distances:
        result["distances"] = distances

cpus = []
    for cpu_node in cell.findall("cpus/cpu"):
        cpu = {"id": int(cpu_node.get("id"))}
        socket_id = cpu_node.get("socket_id")
        if socket_id:
            cpu["socket_id"] = int(socket_id)

core_id = cpu_node.get("core_id")
        if core_id:
            cpu["core_id"] = int(core_id)
        siblings = cpu_node.get("siblings")
        if siblings:
            cpu["siblings"] = siblings
        cpus.append(cpu)
    if cpus:
        result["cpus"] = cpus

return result

def _parse_caps_bank(bank):
    """
    Parse the <bank> element of the connection capabilities XML.
    """
    result = {
        "id": int(bank.get("id")),
        "level": int(bank.get("level")),
        "type": bank.get("type"),
        "size": "{} {}".format(bank.get("size"), bank.get("unit")),
        "cpus": bank.get("cpus"),
    }

controls = []
    for control in bank.findall("control"):
        unit = control.get("unit")
        result_control = {
            "granularity": "{} {}".format(control.get("granularity"), unit),
            "type": control.get("type"),
            "maxAllocs": int(control.get("maxAllocs")),
        }

minimum = control.get("min")
        if minimum:
            result_control["min"] = f"{minimum} {unit}"
        controls.append(result_control)
    if controls:
        result["controls"] = controls

return result

def _parse_caps_host(host):
    """
    Parse the <host> element of the connection capabilities XML.
    """
    result = {}
    for child in host:

if child.tag == "uuid":
            result["uuid"] = child.text

elif child.tag == "cpu":
            cpu = {
                "arch": (
                    child.find("arch").text if child.find("arch") is not None else None
                ),
                "model": (
                    child.find("model").text
                    if child.find("model") is not None
                    else None
                ),
                "vendor": (
                    child.find("vendor").text
                    if child.find("vendor") is not None
                    else None
                ),
                "features": [
                    feature.get("name") for feature in child.findall("feature")
                ],
                "pages": [
                    {"size": "{} {}".format(page.get("size"), page.get("unit", "KiB"))}
                    for page in child.findall("pages")
                ],
            }
            # Parse the cpu tag
            microcode = child.find("microcode")
            if microcode is not None:
                cpu["microcode"] = microcode.get("version")

topology = child.find("topology")
            if topology is not None:
                cpu["sockets"] = int(topology.get("sockets"))
                cpu["cores"] = int(topology.get("cores"))
                cpu["threads"] = int(topology.get("threads"))
            result["cpu"] = cpu

elif child.tag == "power_management":
            result["power_management"] = [node.tag for node in child]

elif child.tag == "migration_features":
            result["migration"] = {
                "live": child.find("live") is not None,
                "transports": [
                    node.text for node in child.findall("uri_transports/uri_transport")
                ],
            }

elif child.tag == "topology":
            result["topology"] = {
                "cells": [
                    _parse_caps_cell(cell) for cell in child.findall("cells/cell")
                ]
            }

elif child.tag == "cache":
            result["cache"] = {
                "banks": [_parse_caps_bank(bank) for bank in child.findall("bank")]
            }

result["security"] = [
        {
            "model": (
                secmodel.find("model").text
                if secmodel.find("model") is not None
                else None
            ),
            "doi": (
                secmodel.find("doi").text if secmodel.find("doi") is not None else None
            ),
            "baselabels": [
                {"type": label.get("type"), "label": label.text}
                for label in secmodel.findall("baselabel")
            ],
        }
        for secmodel in host.findall("secmodel")
    ]

return result

def _capabilities(conn):
    """
    Return the hypervisor connection capabilities.

:param conn: opened libvirt connection to use
    """
    caps = ElementTree.fromstring(conn.getCapabilities())

return {
        "host": _parse_caps_host(caps.find("host")),
        "guests": [_parse_caps_guest(guest) for guest in caps.findall("guest")],
    }

def capabilities(**kwargs):
    """
    Return the hypervisor connection capabilities.

:param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.capabilities
    """
    conn = __get_conn(**kwargs)
    try:
        caps = _capabilities(conn)
    except libvirt.libvirtError as err:
        raise CommandExecutionError(str(err))
    finally:
        conn.close()
    return caps

def _parse_caps_enum(node):
    """
    Return a tuple containing the name of the enum and the possible values
    """
    return (node.get("name"), [value.text for value in node.findall("value")])

def _parse_caps_cpu(node):
    """
    Parse the <cpu> element of the domain capabilities
    """
    result = {}
    for mode in node.findall("mode"):
        if not mode.get("supported") == "yes":
            continue

name = mode.get("name")
        if name == "host-passthrough":
            result[name] = True

elif name == "host-model":
            host_model = {}
            model_node = mode.find("model")
            if model_node is not None:
                model = {"name": model_node.text}

vendor_id = model_node.get("vendor_id")
                if vendor_id:
                    model["vendor_id"] = vendor_id

fallback = model_node.get("fallback")
                if fallback:
                    model["fallback"] = fallback
                host_model["model"] = model

vendor = (
                mode.find("vendor").text if mode.find("vendor") is not None else None
            )
            if vendor:
                host_model["vendor"] = vendor

features = {
                feature.get("name"): feature.get("policy")
                for feature in mode.findall("feature")
            }
            if features:
                host_model["features"] = features

result[name] = host_model

elif name == "custom":
            custom_model = {}
            models = {
                model.text: model.get("usable") for model in mode.findall("model")
            }
            if models:
                custom_model["models"] = models
            result[name] = custom_model

return result

def _parse_caps_devices_features(node):
    """
    Parse the devices or features list of the domain capatilities
    """
    result = {}
    for child in node:
        if child.get("supported") == "yes":
            enums = [_parse_caps_enum(node) for node in child.findall("enum")]
            result[child.tag] = {item[0]: item[1] for item in enums if item[0]}
    return result

def _parse_caps_loader(node):
    """
    Parse the <loader> element of the domain capabilities.
    """
    enums = [_parse_caps_enum(enum) for enum in node.findall("enum")]
    result = {item[0]: item[1] for item in enums if item[0]}

values = [child.text for child in node.findall("value")]

if values:
        result["values"] = values

return result

def _parse_domain_caps(caps):
    """
    Parse the XML document of domain capabilities into a structure.
    """
    result = {
        "emulator": caps.find("path").text if caps.find("path") is not None else None,
        "domain": caps.find("domain").text if caps.find("domain") is not None else None,
        "machine": (
            caps.find("machine").text if caps.find("machine") is not None else None
        ),
        "arch": caps.find("arch").text if caps.find("arch") is not None else None,
    }

for child in caps:
        if child.tag == "vcpu" and child.get("max"):
            result["max_vcpus"] = int(child.get("max"))

elif child.tag == "iothreads":
            result["iothreads"] = child.get("supported") == "yes"

elif child.tag == "os":
            result["os"] = {}
            loader_node = child.find("loader")
            if loader_node is not None and loader_node.get("supported") == "yes":
                loader = _parse_caps_loader(loader_node)
                result["os"]["loader"] = loader

elif child.tag == "cpu":
            cpu = _parse_caps_cpu(child)
            if cpu:
                result["cpu"] = cpu

elif child.tag == "devices":
            devices = _parse_caps_devices_features(child)
            if devices:
                result["devices"] = devices

elif child.tag == "features":
            features = _parse_caps_devices_features(child)
            if features:
                result["features"] = features

return result

def domain_capabilities(emulator=None, arch=None, machine=None, domain=None, **kwargs):
    """
    Return the domain capabilities given an emulator, architecture, machine or virtualization type.

.. versionadded:: 2019.2.0

:param emulator: return the capabilities for the given emulator binary
    :param arch: return the capabilities for the given CPU architecture
    :param machine: return the capabilities for the given emulated machine type
    :param domain: return the capabilities for the given virtualization type.
    :param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

The list of the possible emulator, arch, machine and domain can be found in
    the host capabilities output.

If none of the parameters is provided, the libvirt default one is returned.

CLI Example:

.. code-block:: bash

salt '*' virt.domain_capabilities arch='x86_64' domain='kvm'

"""
    conn = __get_conn(**kwargs)
    result = []
    try:
        caps = ElementTree.fromstring(
            conn.getDomainCapabilities(emulator, arch, machine, domain, 0)
        )
        result = _parse_domain_caps(caps)
    finally:
        conn.close()

return result

def all_capabilities(**kwargs):
    """
    Return the host and domain capabilities in a single call.

.. versionadded:: 3001

:param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

CLI Example:

.. code-block:: bash

salt '*' virt.all_capabilities

"""
    conn = __get_conn(**kwargs)
    try:
        host_caps = ElementTree.fromstring(conn.getCapabilities())
        domains = [
            [
                (
                    guest.get("arch", {}).get("name", None),
                    key,
                    guest.get("arch", {}).get("emulator", None),
                )
                for key in guest.get("arch", {}).get("domains", {}).keys()
            ]
            for guest in [
                _parse_caps_guest(guest) for guest in host_caps.findall("guest")
            ]
        ]
        flattened = [pair for item in (x for x in domains) for pair in item]
        result = {
            "host": {
                "host": _parse_caps_host(host_caps.find("host")),
                "guests": [
                    _parse_caps_guest(guest) for guest in host_caps.findall("guest")
                ],
            },
            "domains": [
                _parse_domain_caps(
                    ElementTree.fromstring(
                        conn.getDomainCapabilities(emulator, arch, None, domain)
                    )
                )
                for (arch, domain, emulator) in flattened
            ],
        }
        return result
    finally:
        conn.close()

def cpu_baseline(full=False, migratable=False, out="libvirt", **kwargs):
    """
    Return the optimal 'custom' CPU baseline config for VM's on this minion

.. versionadded:: 2016.3.0

:param full: Return all CPU features rather than the ones on top of the closest CPU model
    :param migratable: Exclude CPU features that are unmigratable (libvirt 2.13+)
    :param out: 'libvirt' (default) for usable libvirt XML definition, 'salt' for nice dict
    :param connection: libvirt connection URI, overriding defaults

.. versionadded:: 2019.2.0
    :param username: username to connect with, overriding defaults

.. versionadded:: 2019.2.0
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.cpu_baseline

"""
    conn = __get_conn(**kwargs)
    caps = ElementTree.fromstring(conn.getCapabilities())
    cpu = caps.find("host/cpu")
    host_cpu_def = xmlutil.element_to_str(cpu)
    log.debug("Host CPU model definition: %s", host_cpu_def)

flags = 0
    if migratable:
        # This one is only in 1.2.14+
        if getattr(libvirt, "VIR_CONNECT_BASELINE_CPU_MIGRATABLE", False):
            flags += libvirt.VIR_CONNECT_BASELINE_CPU_MIGRATABLE
        else:
            conn.close()
            raise ValueError

if full and getattr(libvirt, "VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES", False):
        # This one is only in 1.1.3+
        flags += libvirt.VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES

cpu = ElementTree.fromstring(conn.baselineCPU([host_cpu_def], flags))
    conn.close()

if full and not getattr(libvirt, "VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES", False):
        # Try do it by ourselves
        # Find the models in cpu_map.xml and iterate over them for as long as entries have submodels
        with salt.utils.files.fopen("/usr/share/libvirt/cpu_map.xml", "r") as cpu_map:
            cpu_map = ElementTree.parse(cpu_map)

cpu_model = cpu.find("model").text
        while cpu_model:
            cpu_map_models = cpu_map.findall("arch/model")
            cpu_specs = [
                el
                for el in cpu_map_models
                if el.get("name") == cpu_model and bool(len(el))
            ]

if not cpu_specs:
                raise ValueError(f"Model {cpu_model} not found in CPU map")
            elif len(cpu_specs) > 1:
                raise ValueError(f"Multiple models {cpu_model} found in CPU map")

cpu_specs = cpu_specs[0]

# libvirt's cpu map used to nest model elements, to point the parent model.
            # keep this code for compatibility with old libvirt versions
            model_node = cpu_specs.find("model")
            if model_node is None:
                cpu_model = None
            else:
                cpu_model = model_node.get("name")

cpu.extend([feature for feature in cpu_specs.findall("feature")])

if out == "salt":
        return {
            "model": cpu.find("model").text,
            "vendor": cpu.find("vendor").text,
            "features": [feature.get("name") for feature in cpu.findall("feature")],
        }
    return ElementTree.tostring(cpu)

def network_define(
    name,
    bridge,
    forward,
    ipv4_config=None,
    ipv6_config=None,
    vport=None,
    tag=None,
    autostart=True,
    start=True,
    mtu=None,
    domain=None,
    nat=None,
    interfaces=None,
    addresses=None,
    physical_function=None,
    dns=None,
    **kwargs,
):
    """
    Create libvirt network.

:param name: Network name.
    :param bridge: Bridge name.
    :param forward: Forward mode (bridge, router, nat).

.. versionchanged:: 3003
           a ``None`` value creates an isolated network with no forwarding at all

:param vport: Virtualport type.
        The value can also be a dictionary with ``type`` and ``parameters`` keys.
        The ``parameters`` value is a dictionary of virtual port parameters.

.. code-block:: yaml

- vport:
              type: openvswitch
              parameters:
                interfaceid: 09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f

.. versionchanged:: 3003
           possible dictionary value

:param tag: Vlan tag.
        The value can also be a dictionary with the ``tags`` and optional ``trunk`` keys.
        ``trunk`` is a boolean value indicating whether to use VLAN trunking.
        ``tags`` is a list of dictionaries with keys ``id`` and ``nativeMode``.
        The ``nativeMode`` value can be one of ``tagged`` or ``untagged``.

.. code-block:: yaml

- tag:
              trunk: True
              tags:
                - id: 42
                  nativeMode: untagged
                - id: 47

.. versionchanged:: 3003
           possible dictionary value

:param autostart: Network autostart (default True).
    :param start: Network start (default True).
    :param ipv4_config: IP v4 configuration.
        Dictionary describing the IP v4 setup like IP range and
        a possible DHCP configuration. The structure is documented
        in net-define-ip_.

.. versionadded:: 3000
    :type ipv4_config: dict or None

:param ipv6_config: IP v6 configuration.
        Dictionary describing the IP v6 setup like IP range and
        a possible DHCP configuration. The structure is documented
        in net-define-ip_.

.. versionadded:: 3000
    :type ipv6_config: dict or None

:param connection: libvirt connection URI, overriding defaults.
    :param username: username to connect with, overriding defaults.
    :param password: password to connect with, overriding defaults.

:param mtu: size of the Maximum Transmission Unit (MTU) of the network.
        (default ``None``)

.. versionadded:: 3003

:param domain: DNS domain name of the DHCP server.
        The value is a dictionary with a mandatory ``name`` property and an optional ``localOnly`` boolean one.
        (default ``None``)

.. code-block:: yaml

- domain:
              name: lab.acme.org
              localOnly: True

.. versionadded:: 3003

:param nat: addresses and ports to route in NAT forward mode.
        The value is a dictionary with optional keys ``address`` and ``port``.
        Both values are a dictionary with ``start`` and ``end`` values.
        (default ``None``)

.. code-block:: yaml

- forward: nat
          - nat:
              address:
                start: 1.2.3.4
                end: 1.2.3.10
              port:
                start: 500
                end: 1000

.. versionadded:: 3003

:param interfaces: whitespace separated list of network interfaces devices that can be used for this network.
        (default ``None``)

.. code-block:: yaml

- forward: passthrough
          - interfaces: "eth10 eth11 eth12"

.. versionadded:: 3003

:param addresses: whitespace separated list of addresses of PCI devices that can be used for this network in `hostdev` forward mode.
        (default ``None``)

.. code-block:: yaml

- forward: hostdev
          - interfaces: "0000:04:00.1 0000:e3:01.2"

.. versionadded:: 3003

:param physical_function: device name of the physical interface to use in ``hostdev`` forward mode.
        (default ``None``)

.. code-block:: yaml

- forward: hostdev
          - physical_function: "eth0"

.. versionadded:: 3003

:param dns: virtual network DNS configuration.
        The value is a dictionary described in net-define-dns_.
        (default ``None``)

.. code-block:: yaml

- dns:
              forwarders:
                - domain: example.com
                  addr: 192.168.1.1
                - addr: 8.8.8.8
                - domain: www.example.com
              txt:
                example.com: "v=spf1 a -all"
                _http.tcp.example.com: "name=value,paper=A4"
              hosts:
                192.168.1.2:
                  - mirror.acme.lab
                  - test.acme.lab
              srvs:
                - name: ldap
                  protocol: tcp
                  domain: ldapserver.example.com
                  target: .
                  port: 389
                  priority: 1
                  weight: 10

.. versionadded:: 3003

.. _net-define-ip:

.. rubric:: IP configuration definition

Both the IPv4 and IPv6 configuration dictionaries can contain the following properties:

cidr
        CIDR notation for the network. For example '192.168.124.0/24'

dhcp_ranges
        A list of dictionaries with ``'start'`` and ``'end'`` properties.

hosts
        A list of dictionaries with ``ip`` property and optional ``name``, ``mac`` and ``id`` properties.

.. versionadded:: 3003

bootp
        A dictionary with a ``file`` property and an optional ``server`` one.

.. versionadded:: 3003

tftp
        The path to the TFTP root directory to serve.

.. versionadded:: 3003

.. _net-define-dns:

.. rubric:: DNS configuration definition

The DNS configuration dictionary contains the following optional properties:

forwarders
        List of alternate DNS forwarders to use.
        Each item is a dictionary with the optional ``domain`` and ``addr`` keys.
        If both are provided, the requests to the domain are forwarded to the server at the ``addr``.
        If only ``domain`` is provided the requests matching this domain will be resolved locally.
        If only ``addr`` is provided all requests will be forwarded to this DNS server.

txt:
        Dictionary of TXT fields to set.

hosts:
        Dictionary of host DNS entries.
        The key is the IP of the host, and the value is a list of hostnames for it.

srvs:
        List of SRV DNS entries.
        Each entry is a dictionary with the mandatory ``name`` and ``protocol`` keys.
        Entries can also have ``target``, ``port``, ``priority``, ``domain`` and ``weight`` optional properties.

CLI Example:

.. code-block:: bash

salt '*' virt.network_define network main bridge openvswitch

.. versionadded:: 2019.2.0
    """
    conn = __get_conn(**kwargs)
    vport = kwargs.get("vport", None)
    tag = kwargs.get("tag", None)

net_xml = _gen_net_xml(
        name,
        bridge,
        forward,
        vport,
        tag=tag,
        ip_configs=[config for config in [ipv4_config, ipv6_config] if config],
        mtu=mtu,
        domain=domain,
        nat=nat,
        interfaces=interfaces,
        addresses=addresses,
        physical_function=physical_function,
        dns=dns,
    )
    try:
        conn.networkDefineXML(net_xml)
    except libvirt.libvirtError as err:
        log.warning(err)
        conn.close()
        raise err  # a real error we should report upwards

try:
        network = conn.networkLookupByName(name)
    except libvirt.libvirtError as err:
        log.warning(err)
        conn.close()
        raise err  # a real error we should report upwards

if network is None:
        conn.close()
        return False

if (start or autostart) and network.isActive() != 1:
        network.create()

if autostart and network.autostart() != 1:
        network.setAutostart(int(autostart))
    elif not autostart and network.autostart() == 1:
        network.setAutostart(int(autostart))

conn.close()

return True

def _remove_empty_xml_node(node):
    """
    Remove the nodes with no children, no text and no attribute
    """
    for child in node:
        if not child.tail and not child.text and not child.items() and not child:
            node.remove(child)
        else:
            _remove_empty_xml_node(child)
    return node

def network_update(
    name,
    bridge,
    forward,
    ipv4_config=None,
    ipv6_config=None,
    vport=None,
    tag=None,
    mtu=None,
    domain=None,
    nat=None,
    interfaces=None,
    addresses=None,
    physical_function=None,
    dns=None,
    test=False,
    **kwargs,
):
    """
    Update a virtual network if needed.

:param name: Network name.
    :param bridge: Bridge name.
    :param forward: Forward mode (bridge, router, nat).
        A ``None`` value creates an isolated network with no forwarding at all.

:param vport: Virtualport type.
        The value can also be a dictionary with ``type`` and ``parameters`` keys.
        The ``parameters`` value is a dictionary of virtual port parameters.

.. code-block:: yaml

- vport:
              type: openvswitch
              parameters:
                interfaceid: 09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f

.. code-block:: yaml

- tag:
              trunk: True
              tags:
                - id: 42
                  nativeMode: untagged
                - id: 47

:param ipv4_config: IP v4 configuration.
        Dictionary describing the IP v4 setup like IP range and
        a possible DHCP configuration. The structure is documented
        in net-define-ip_.

:type ipv4_config: dict or None

:param ipv6_config: IP v6 configuration.
        Dictionary describing the IP v6 setup like IP range and
        a possible DHCP configuration. The structure is documented
        in net-define-ip_.

:type ipv6_config: dict or None

:param connection: libvirt connection URI, overriding defaults.
    :param username: username to connect with, overriding defaults.
    :param password: password to connect with, overriding defaults.

:param mtu: size of the Maximum Transmission Unit (MTU) of the network.
        (default ``None``)

:param domain: DNS domain name of the DHCP server.
        The value is a dictionary with a mandatory ``name`` property and an optional ``localOnly`` boolean one.
        (default ``None``)

.. code-block:: yaml

- domain:
              name: lab.acme.org
              localOnly: True

.. code-block:: yaml

- forward: nat
          - nat:
              address:
                start: 1.2.3.4
                end: 1.2.3.10
              port:
                start: 500
                end: 1000

:param interfaces: whitespace separated list of network interfaces devices that can be used for this network.
        (default ``None``)

.. code-block:: yaml

- forward: passthrough
          - interfaces: "eth10 eth11 eth12"

:param addresses: whitespace separated list of addresses of PCI devices that can be used for this network in `hostdev` forward mode.
        (default ``None``)

.. code-block:: yaml

- forward: hostdev
          - interfaces: "0000:04:00.1 0000:e3:01.2"

:param physical_function: device name of the physical interface to use in ``hostdev`` forward mode.
        (default ``None``)

.. code-block:: yaml

- forward: hostdev
          - physical_function: "eth0"

:param dns: virtual network DNS configuration.
        The value is a dictionary described in net-define-dns_.
        (default ``None``)

.. code-block:: yaml

.. versionadded:: 3003
    """
    # Get the current definition to compare the two
    conn = __get_conn(**kwargs)
    needs_update = False
    try:
        net = conn.networkLookupByName(name)
        old_xml = ElementTree.fromstring(net.XMLDesc())

# Compute new definition
        new_xml = ElementTree.fromstring(
            _gen_net_xml(
                name,
                bridge,
                forward,
                vport,
                tag=tag,
                ip_configs=[config for config in [ipv4_config, ipv6_config] if config],
                mtu=mtu,
                domain=domain,
                nat=nat,
                interfaces=interfaces,
                addresses=addresses,
                physical_function=physical_function,
                dns=dns,
            )
        )

elements_to_copy = ["uuid", "mac"]
        for to_copy in elements_to_copy:
            element = old_xml.find(to_copy)
            # mac may not be present (hostdev network for instance)
            if element is not None:
                new_xml.insert(1, element)

# Libvirt adds a connection attribute on running networks, remove before comparing
        old_xml.attrib.pop("connections", None)

# Libvirt adds the addresses of the VF devices on running networks with the ph passed
        # Those need to be removed before comparing
        if old_xml.find("forward/pf") is not None:
            forward_node = old_xml.find("forward")
            address_nodes = forward_node.findall("address")
            for node in address_nodes:
                forward_node.remove(node)

# Remove libvirt auto-added bridge attributes to compare
        default_bridge_attribs = {"stp": "on", "delay": "0"}
        old_bridge_node = old_xml.find("bridge")
        if old_bridge_node is not None:
            for key, value in default_bridge_attribs.items():
                if old_bridge_node.get(key, None) == value:
                    old_bridge_node.attrib.pop(key, None)

# Libvirt may also add the whole bridge network since the name can be computed
            # If the bridge name starts with virbr in a nat, route, open or isolated network
            # there is a good change it has been autogenerated...
            old_forward = (
                old_xml.find("forward").get("mode")
                if old_xml.find("forward") is not None
                else None
            )
            if (
                old_forward == forward
                and forward in ["nat", "route", "open", None]
                and bridge is None
                and old_bridge_node.get("name", "").startswith("virbr")
            ):
                old_bridge_node.attrib.pop("name", None)

# In the ipv4 address, we need to convert netmask to prefix in the old XML
        ipv4_nodes = [
            node
            for node in old_xml.findall("ip")
            if node.get("family", "ipv4") == "ipv4"
        ]
        for ip_node in ipv4_nodes:
            netmask = ip_node.attrib.pop("netmask", None)
            if netmask:
                address = ipaddress.ip_network(
                    "{}/{}".format(ip_node.get("address"), netmask), strict=False
                )
                ip_node.set("prefix", str(address.prefixlen))

# Add default ipv4 family if needed
        for doc in [old_xml, new_xml]:
            for node in doc.findall("ip"):
                if "family" not in node.keys():
                    node.set("family", "ipv4")

# Filter out spaces and empty elements since those would mislead the comparison
        _remove_empty_xml_node(xmlutil.strip_spaces(old_xml))
        xmlutil.strip_spaces(new_xml)

needs_update = xmlutil.to_dict(old_xml, True) != xmlutil.to_dict(new_xml, True)
        if needs_update and not test:
            conn.networkDefineXML(xmlutil.element_to_str(new_xml))
    finally:
        conn.close()
    return needs_update

def list_networks(**kwargs):
    """
    List all virtual networks.

:param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.list_networks
    """
    conn = __get_conn(**kwargs)
    try:
        return [net.name() for net in conn.listAllNetworks()]
    finally:
        conn.close()

def network_info(name=None, **kwargs):
    """
    Return information on a virtual network provided its name.

:param name: virtual network name
    :param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

If no name is provided, return the infos for all defined virtual networks.

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.network_info default
    """
    result = {}
    conn = __get_conn(**kwargs)

def _net_get_leases(net):
        """
        Get all DHCP leases for a network
        """
        leases = net.DHCPLeases()
        for lease in leases:
            if lease["type"] == libvirt.VIR_IP_ADDR_TYPE_IPV4:
                lease["type"] = "ipv4"
            elif lease["type"] == libvirt.VIR_IP_ADDR_TYPE_IPV6:
                lease["type"] = "ipv6"
            else:
                lease["type"] = "unknown"
        return leases

def _net_get_bridge(net):
        """
        Get the bridge of the network or None
        """
        try:
            return net.bridgeName()
        except libvirt.libvirtError as err:
            # Some network configurations have no bridge
            return None

try:
        nets = [
            net for net in conn.listAllNetworks() if name is None or net.name() == name
        ]
        result = {
            net.name(): {
                "uuid": net.UUIDString(),
                "bridge": _net_get_bridge(net),
                "autostart": net.autostart(),
                "active": net.isActive(),
                "persistent": net.isPersistent(),
                "leases": _net_get_leases(net),
            }
            for net in nets
        }
    except libvirt.libvirtError as err:
        log.debug("Silenced libvirt error: %s", err)
    finally:
        conn.close()
    return result

def network_get_xml(name, **kwargs):
    """
    Return the XML definition of a virtual network

:param name: libvirt network name
    :param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. versionadded:: 3000

CLI Example:

.. code-block:: bash

salt '*' virt.network_get_xml default
    """
    conn = __get_conn(**kwargs)
    try:
        return conn.networkLookupByName(name).XMLDesc()
    finally:
        conn.close()

def network_start(name, **kwargs):
    """
    Start a defined virtual network.

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.network_start default
    """
    conn = __get_conn(**kwargs)
    try:
        net = conn.networkLookupByName(name)
        return not bool(net.create())
    finally:
        conn.close()

def network_stop(name, **kwargs):
    """
    Stop a defined virtual network.

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.network_stop default
    """
    conn = __get_conn(**kwargs)
    try:
        net = conn.networkLookupByName(name)
        return not bool(net.destroy())
    finally:
        conn.close()

def network_undefine(name, **kwargs):
    """
    Remove a defined virtual network. This does not stop the virtual network.

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.network_undefine default
    """
    conn = __get_conn(**kwargs)
    try:
        net = conn.networkLookupByName(name)
        return not bool(net.undefine())
    finally:
        conn.close()

def network_set_autostart(name, state="on", **kwargs):
    """
    Set the autostart flag on a virtual network so that the network
    will start with the host system on reboot.

:param name: virtual network name
    :param state: 'on' to auto start the network, anything else to mark the
                  virtual network not to be started when the host boots
    :param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt "*" virt.network_set_autostart <pool> <on | off>
    """
    conn = __get_conn(**kwargs)
    try:
        net = conn.networkLookupByName(name)
        return not bool(net.setAutostart(1 if state == "on" else 0))
    finally:
        conn.close()

def _parse_pools_caps(doc):
    """
    Parse libvirt pool capabilities XML
    """

def _parse_pool_caps(pool):
        pool_caps = {
            "name": pool.get("type"),
            "supported": pool.get("supported", "no") == "yes",
        }
        for option_kind in ["pool", "vol"]:
            options = {}
            default_format_node = pool.find(f"{option_kind}Options/defaultFormat")
            if default_format_node is not None:
                options["default_format"] = default_format_node.get("type")
            options_enums = {
                enum.get("name"): [value.text for value in enum.findall("value")]
                for enum in pool.findall(f"{option_kind}Options/enum")
            }
            if options_enums:
                options.update(options_enums)
            if options:
                if "options" not in pool_caps:
                    pool_caps["options"] = {}
                kind = option_kind if option_kind != "vol" else "volume"
                pool_caps["options"][kind] = options
        return pool_caps

return [_parse_pool_caps(pool) for pool in doc.findall("pool")]

def _pool_capabilities(conn):
    """
    Return the hypervisor connection storage pool capabilities.

:param conn: opened libvirt connection to use
    """
    has_pool_capabilities = bool(getattr(conn, "getStoragePoolCapabilities", None))
    if has_pool_capabilities:
        caps = ElementTree.fromstring(conn.getStoragePoolCapabilities())
        pool_types = _parse_pools_caps(caps)
    else:
        # Compute reasonable values
        all_hypervisors = ["xen", "kvm", "bhyve"]
        images_formats = [
            "none",
            "raw",
            "dir",
            "bochs",
            "cloop",
            "dmg",
            "iso",
            "vpc",
            "vdi",
            "fat",
            "vhd",
            "ploop",
            "cow",
            "qcow",
            "qcow2",
            "qed",
            "vmdk",
        ]
        common_drivers = [
            {
                "name": "fs",
                "default_source_format": "auto",
                "source_formats": [
                    "auto",
                    "ext2",
                    "ext3",
                    "ext4",
                    "ufs",
                    "iso9660",
                    "udf",
                    "gfs",
                    "gfs2",
                    "vfat",
                    "hfs+",
                    "xfs",
                    "ocfs2",
                ],
                "default_target_format": "raw",
                "target_formats": images_formats,
            },
            {
                "name": "dir",
                "default_target_format": "raw",
                "target_formats": images_formats,
            },
            {"name": "iscsi"},
            {"name": "scsi"},
            {
                "name": "logical",
                "default_source_format": "lvm2",
                "source_formats": ["unknown", "lvm2"],
            },
            {
                "name": "netfs",
                "default_source_format": "auto",
                "source_formats": ["auto", "nfs", "glusterfs", "cifs"],
                "default_target_format": "raw",
                "target_formats": images_formats,
            },
            {
                "name": "disk",
                "default_source_format": "unknown",
                "source_formats": [
                    "unknown",
                    "dos",
                    "dvh",
                    "gpt",
                    "mac",
                    "bsd",
                    "pc98",
                    "sun",
                    "lvm2",
                ],
                "default_target_format": "none",
                "target_formats": [
                    "none",
                    "linux",
                    "fat16",
                    "fat32",
                    "linux-swap",
                    "linux-lvm",
                    "linux-raid",
                    "extended",
                ],
            },
            {"name": "mpath"},
            {"name": "rbd", "default_target_format": "raw", "target_formats": []},
            {
                "name": "sheepdog",
                "version": 10000,
                "hypervisors": ["kvm"],
                "default_target_format": "raw",
                "target_formats": images_formats,
            },
            {
                "name": "gluster",
                "version": 1002000,
                "hypervisors": ["kvm"],
                "default_target_format": "raw",
                "target_formats": images_formats,
            },
            {"name": "zfs", "version": 1002008, "hypervisors": ["bhyve"]},
            {
                "name": "iscsi-direct",
                "version": 4007000,
                "hypervisors": ["kvm", "xen"],
            },
        ]

libvirt_version = conn.getLibVersion()
        hypervisor = get_hypervisor()

def _get_backend_output(backend):
            output = {
                "name": backend["name"],
                "supported": (
                    not backend.get("version") or libvirt_version >= backend["version"]
                )
                and hypervisor in backend.get("hypervisors", all_hypervisors),
                "options": {
                    "pool": {
                        "default_format": backend.get("default_source_format"),
                        "sourceFormatType": backend.get("source_formats"),
                    },
                    "volume": {
                        "default_format": backend.get("default_target_format"),
                        "targetFormatType": backend.get("target_formats"),
                    },
                },
            }

# Cleanup the empty members to match the libvirt output
            for option_kind in ["pool", "volume"]:
                if not [
                    value
                    for value in output["options"][option_kind].values()
                    if value is not None
                ]:
                    del output["options"][option_kind]
            if not output["options"]:
                del output["options"]

return output

pool_types = [_get_backend_output(backend) for backend in common_drivers]

return {
        "computed": not has_pool_capabilities,
        "pool_types": pool_types,
    }

def pool_capabilities(**kwargs):
    """
    Return the hypervisor connection storage pool capabilities.

The returned data are either directly extracted from libvirt or computed.
    In the latter case some pool types could be listed as supported while they
    are not. To distinguish between the two cases, check the value of the ``computed`` property.

:param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. versionadded:: 3000

CLI Example:

.. code-block:: bash

salt '*' virt.pool_capabilities

"""
    try:
        conn = __get_conn(**kwargs)
        return _pool_capabilities(conn)
    finally:
        conn.close()

def pool_define(
    name,
    ptype,
    target=None,
    permissions=None,
    source_devices=None,
    source_dir=None,
    source_initiator=None,
    source_adapter=None,
    source_hosts=None,
    source_auth=None,
    source_name=None,
    source_format=None,
    transient=False,
    start=True,  # pylint: disable=redefined-outer-name
    **kwargs,
):
    """
    Create libvirt pool.

:param name: Pool name
    :param ptype:
        Pool type. See `libvirt documentation <https://libvirt.org/storage.html>`_  for the
        possible values.
    :param target: Pool full path target
    :param permissions:
        Permissions to set on the target folder. This is mostly used for filesystem-based
        pool types. See :ref:`pool-define-permissions` for more details on this structure.
    :param source_devices:
        List of source devices for pools backed by physical devices. (Default: ``None``)

Each item in the list is a dictionary with ``path`` and optionally ``part_separator``
        keys. The path is the qualified name for iSCSI devices.

Report to `this libvirt page <https://libvirt.org/formatstorage.html#StoragePool>`_
        for more information on the use of ``part_separator``
    :param source_dir:
        Path to the source directory for pools of type ``dir``, ``netfs`` or ``gluster``.
        (Default: ``None``)
    :param source_initiator:
        Initiator IQN for libiscsi-direct pool types. (Default: ``None``)

.. versionadded:: 3000
    :param source_adapter:
        SCSI source definition. The value is a dictionary with ``type``, ``name``, ``parent``,
        ``managed``, ``parent_wwnn``, ``parent_wwpn``, ``parent_fabric_wwn``, ``wwnn``, ``wwpn``
        and ``parent_address`` keys.

The ``parent_address`` value is a dictionary with ``unique_id`` and ``address`` keys.
        The address represents a PCI address and is itself a dictionary with ``domain``, ``bus``,
        ``slot`` and ``function`` properties.
        Report to `this libvirt page <https://libvirt.org/formatstorage.html#StoragePool>`_
        for the meaning and possible values of these properties.
    :param source_hosts:
        List of source for pools backed by storage from remote servers. Each item is the hostname
        optionally followed by the port separated by a colon. (Default: ``None``)
    :param source_auth:
        Source authentication details. (Default: ``None``)

The value is a dictionary with ``type``, ``username`` and ``secret`` keys. The type
        can be one of ``ceph`` for Ceph RBD or ``chap`` for iSCSI sources.

The ``secret`` value links to a libvirt secret object. It is a dictionary with
        ``type`` and ``value`` keys. The type value can be either ``uuid`` or ``usage``.

Examples:

.. code-block:: python

source_auth={
                'type': 'ceph',
                'username': 'admin',
                'secret': {
                    'type': 'uuid',
                    'value': '2ec115d7-3a88-3ceb-bc12-0ac909a6fd87'
                }
            }

.. code-block:: python

source_auth={
                'type': 'chap',
                'username': 'myname',
                'secret': {
                    'type': 'usage',
                    'value': 'mycluster_myname'
                }
            }

Since 3000, instead the source authentication can only contain ``username``
        and ``password`` properties. In this case the libvirt secret will be defined and used.
        For Ceph authentications a base64 encoded key is expected.

:param source_name:
        Identifier of name-based sources.
    :param source_format:
        String representing the source format. The possible values are depending on the
        source type. See `libvirt documentation <https://libvirt.org/storage.html>`_ for
        the possible values.
    :param start: Pool start (default True)
    :param transient:
        When ``True``, the pool will be automatically undefined after being stopped.
        Note that a transient pool will force ``start`` to ``True``. (Default: ``False``)
    :param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. _pool-define-permissions:

.. rubric:: Permissions definition

The permissions are described by a dictionary containing the following keys:

mode
        The octal representation of the permissions. (Default: `0711`)

owner
        the numeric user ID of the owner. (Default: from the parent folder)

group
        the numeric ID of the group. (Default: from the parent folder)

label
        the SELinux label. (Default: `None`)

.. rubric:: CLI Example:

Local folder pool:

.. code-block:: bash

salt '*' virt.pool_define somepool dir target=/srv/mypool \
                                  permissions="{'mode': '0744' 'ower': 107, 'group': 107 }"

CIFS backed pool:

.. code-block:: bash

salt '*' virt.pool_define myshare netfs source_format=cifs \
                                  source_dir=samba_share source_hosts="['example.com']" target=/mnt/cifs

.. versionadded:: 2019.2.0
    """
    conn = __get_conn(**kwargs)
    auth = _pool_set_secret(conn, ptype, name, source_auth)

pool_xml = _gen_pool_xml(
        name,
        ptype,
        target,
        permissions=permissions,
        source_devices=source_devices,
        source_dir=source_dir,
        source_adapter=source_adapter,
        source_hosts=source_hosts,
        source_auth=auth,
        source_name=source_name,
        source_format=source_format,
        source_initiator=source_initiator,
    )
    try:
        if transient:
            pool = conn.storagePoolCreateXML(pool_xml)
        else:
            pool = conn.storagePoolDefineXML(pool_xml)
            if start:
                pool.create()
    except libvirt.libvirtError as err:
        raise err  # a real error we should report upwards
    finally:
        conn.close()

# libvirt function will raise a libvirtError in case of failure
    return True

def _pool_set_secret(
    conn, pool_type, pool_name, source_auth, uuid=None, usage=None, test=False
):
    secret_types = {"rbd": "ceph", "iscsi": "chap", "iscsi-direct": "chap"}
    secret_type = secret_types.get(pool_type)
    auth = source_auth
    if source_auth and "username" in source_auth and "password" in source_auth:
        if secret_type:
            # Get the previously defined secret if any
            secret = None
            try:
                if usage:
                    usage_type = (
                        libvirt.VIR_SECRET_USAGE_TYPE_CEPH
                        if secret_type == "ceph"
                        else libvirt.VIR_SECRET_USAGE_TYPE_ISCSI
                    )
                    secret = conn.secretLookupByUsage(usage_type, usage)
                elif uuid:
                    secret = conn.secretLookupByUUIDString(uuid)
            except libvirt.libvirtError as err:
                # For some reason the secret has been removed. Don't fail since we'll recreate it
                log.info("Secret not found: %s", err.get_error_message())

# Create secret if needed
            if not secret:
                description = f"Passphrase for {pool_name} pool created by Salt"
                if not usage:
                    usage = f"pool_{pool_name}"
                secret_xml = _gen_secret_xml(secret_type, usage, description)
                if not test:
                    secret = conn.secretDefineXML(secret_xml)

# Assign the password to it
            password = auth["password"]
            if pool_type == "rbd":
                # RBD password are already base64-encoded, but libvirt will base64-encode them later
                password = base64.b64decode(salt.utils.stringutils.to_bytes(password))
            if not test:
                secret.setValue(password)

# update auth with secret reference
            auth["type"] = secret_type
            auth["secret"] = {
                "type": "uuid" if uuid else "usage",
                "value": uuid if uuid else usage,
            }
    return auth

def pool_update(
    name,
    ptype,
    target=None,
    permissions=None,
    source_devices=None,
    source_dir=None,
    source_initiator=None,
    source_adapter=None,
    source_hosts=None,
    source_auth=None,
    source_name=None,
    source_format=None,
    test=False,
    **kwargs,
):
    """
    Update a libvirt storage pool if needed.
    If called with test=True, this is also reporting whether an update would be performed.

Each item in the list is a dictionary with ``path`` and optionally ``part_separator``
        keys. The path is the qualified name for iSCSI devices.

The value is a dictionary with ``type``, ``username`` and ``secret`` keys. The type
        can be one of ``ceph`` for Ceph RBD or ``chap`` for iSCSI sources.

The ``secret`` value links to a libvirt secret object. It is a dictionary with
        ``type`` and ``value`` keys. The type value can be either ``uuid`` or ``usage``.

Examples:

.. code-block:: python

source_auth={
                'type': 'ceph',
                'username': 'admin',
                'secret': {
                    'type': 'uuid',
                    'uuid': '2ec115d7-3a88-3ceb-bc12-0ac909a6fd87'
                }
            }

.. code-block:: python

source_auth={
                'type': 'chap',
                'username': 'myname',
                'secret': {
                    'type': 'usage',
                    'uuid': 'mycluster_myname'
                }
            }

:param source_name:
        Identifier of name-based sources.
    :param source_format:
        String representing the source format. The possible values are depending on the
        source type. See `libvirt documentation <https://libvirt.org/storage.html>`_ for
        the possible values.
    :param test: run in dry-run mode if set to True
    :param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. rubric:: Example:

Local folder pool:

.. code-block:: bash

salt '*' virt.pool_update somepool dir target=/srv/mypool \
                                  permissions="{'mode': '0744' 'ower': 107, 'group': 107 }"

CIFS backed pool:

.. code-block:: bash

salt '*' virt.pool_update myshare netfs source_format=cifs \
                                  source_dir=samba_share source_hosts="['example.com']" target=/mnt/cifs

.. versionadded:: 3000
    """
    # Get the current definition to compare the two
    conn = __get_conn(**kwargs)
    needs_update = False
    try:
        pool = conn.storagePoolLookupByName(name)
        old_xml = ElementTree.fromstring(pool.XMLDesc())

# If we have username and password in source_auth generate a new secret
        # Or change the value of the existing one
        secret_node = old_xml.find("source/auth/secret")
        usage = secret_node.get("usage") if secret_node is not None else None
        uuid = secret_node.get("uuid") if secret_node is not None else None
        auth = _pool_set_secret(
            conn, ptype, name, source_auth, uuid=uuid, usage=usage, test=test
        )

# Compute new definition
        new_xml = ElementTree.fromstring(
            _gen_pool_xml(
                name,
                ptype,
                target,
                permissions=permissions,
                source_devices=source_devices,
                source_dir=source_dir,
                source_initiator=source_initiator,
                source_adapter=source_adapter,
                source_hosts=source_hosts,
                source_auth=auth,
                source_name=source_name,
                source_format=source_format,
            )
        )

# Copy over the uuid, capacity, allocation, available elements
        elements_to_copy = ["available", "allocation", "capacity", "uuid"]
        for to_copy in elements_to_copy:
            element = old_xml.find(to_copy)
            new_xml.insert(1, element)

# Filter out spaces and empty elements like <source/> since those would mislead the comparison
        _remove_empty_xml_node(xmlutil.strip_spaces(old_xml))
        xmlutil.strip_spaces(new_xml)

needs_update = xmlutil.to_dict(old_xml, True) != xmlutil.to_dict(new_xml, True)
        if needs_update and not test:
            conn.storagePoolDefineXML(xmlutil.element_to_str(new_xml))
    finally:
        conn.close()
    return needs_update

def list_pools(**kwargs):
    """
    List all storage pools.

:param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.list_pools
    """
    conn = __get_conn(**kwargs)
    try:
        return [pool.name() for pool in conn.listAllStoragePools()]
    finally:
        conn.close()

def pool_info(name=None, **kwargs):
    """
    Return information on a storage pool provided its name.

:param name: libvirt storage pool name
    :param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

If no name is provided, return the infos for all defined storage pools.

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.pool_info default
    """
    result = {}
    conn = __get_conn(**kwargs)

def _pool_extract_infos(pool):
        """
        Format the pool info dictionary

:param pool: the libvirt pool object
        """
        states = ["inactive", "building", "running", "degraded", "inaccessible"]
        infos = pool.info()
        state = states[infos[0]] if infos[0] < len(states) else "unknown"
        desc = ElementTree.fromstring(pool.XMLDesc())
        path_node = desc.find("target/path")
        return {
            "uuid": pool.UUIDString(),
            "state": state,
            "capacity": infos[1],
            "allocation": infos[2],
            "free": infos[3],
            "autostart": pool.autostart(),
            "persistent": pool.isPersistent(),
            "target_path": path_node.text if path_node is not None else None,
            "type": desc.get("type"),
        }

try:
        pools = [
            pool
            for pool in conn.listAllStoragePools()
            if name is None or pool.name() == name
        ]
        result = {pool.name(): _pool_extract_infos(pool) for pool in pools}
    except libvirt.libvirtError as err:
        log.debug("Silenced libvirt error: %s", err)
    finally:
        conn.close()
    return result

def pool_get_xml(name, **kwargs):
    """
    Return the XML definition of a virtual storage pool

.. versionadded:: 3000

CLI Example:

.. code-block:: bash

salt '*' virt.pool_get_xml default
    """
    conn = __get_conn(**kwargs)
    try:
        return conn.storagePoolLookupByName(name).XMLDesc()
    finally:
        conn.close()

def pool_start(name, **kwargs):
    """
    Start a defined libvirt storage pool.

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.pool_start default
    """
    conn = __get_conn(**kwargs)
    try:
        pool = conn.storagePoolLookupByName(name)
        return not bool(pool.create())
    finally:
        conn.close()

def pool_build(name, **kwargs):
    """
    Build a defined libvirt storage pool.

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.pool_build default
    """
    conn = __get_conn(**kwargs)
    try:
        pool = conn.storagePoolLookupByName(name)
        return not bool(pool.build())
    finally:
        conn.close()

def pool_stop(name, **kwargs):
    """
    Stop a defined libvirt storage pool.

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.pool_stop default
    """
    conn = __get_conn(**kwargs)
    try:
        pool = conn.storagePoolLookupByName(name)
        return not bool(pool.destroy())
    finally:
        conn.close()

def pool_undefine(name, **kwargs):
    """
    Remove a defined libvirt storage pool. The pool needs to be stopped before calling.

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.pool_undefine default
    """
    conn = __get_conn(**kwargs)
    try:
        pool = conn.storagePoolLookupByName(name)
        desc = ElementTree.fromstring(pool.XMLDesc())

# Is there a secret that we generated and would need to be removed?
        # Don't remove the other secrets
        auth_node = desc.find("source/auth")
        if auth_node is not None:
            auth_types = {
                "ceph": libvirt.VIR_SECRET_USAGE_TYPE_CEPH,
                "iscsi": libvirt.VIR_SECRET_USAGE_TYPE_ISCSI,
            }
            secret_type = auth_types[auth_node.get("type")]
            secret_usage = auth_node.find("secret").get("usage")
            if secret_type and f"pool_{name}" == secret_usage:
                secret = conn.secretLookupByUsage(secret_type, secret_usage)
                secret.undefine()

return not bool(pool.undefine())
    finally:
        conn.close()

def pool_delete(name, **kwargs):
    """
    Delete the resources of a defined libvirt storage pool.

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.pool_delete default
    """
    conn = __get_conn(**kwargs)
    try:
        pool = conn.storagePoolLookupByName(name)
        return not bool(pool.delete(libvirt.VIR_STORAGE_POOL_DELETE_NORMAL))
    finally:
        conn.close()

def pool_refresh(name, **kwargs):
    """
    Refresh a defined libvirt storage pool.

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt '*' virt.pool_refresh default
    """
    conn = __get_conn(**kwargs)
    try:
        pool = conn.storagePoolLookupByName(name)
        return not bool(pool.refresh())
    finally:
        conn.close()

def pool_set_autostart(name, state="on", **kwargs):
    """
    Set the autostart flag on a libvirt storage pool so that the storage pool
    will start with the host system on reboot.

:param name: libvirt storage pool name
    :param state: 'on' to auto start the pool, anything else to mark the
                  pool not to be started when the host boots
    :param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt "*" virt.pool_set_autostart <pool> <on | off>
    """
    conn = __get_conn(**kwargs)
    try:
        pool = conn.storagePoolLookupByName(name)
        return not bool(pool.setAutostart(1 if state == "on" else 0))
    finally:
        conn.close()

def pool_list_volumes(name, **kwargs):
    """
    List the volumes contained in a defined libvirt storage pool.

.. versionadded:: 2019.2.0

CLI Example:

.. code-block:: bash

salt "*" virt.pool_list_volumes <pool>
    """
    conn = __get_conn(**kwargs)
    try:
        pool = conn.storagePoolLookupByName(name)
        return pool.listVolumes()
    finally:
        conn.close()

def _get_storage_vol(conn, pool, vol):
    """
    Helper function getting a storage volume. Will throw a libvirtError
    if the pool or the volume couldn't be found.

:param conn: libvirt connection object to use
    :param pool: pool name
    :param vol: volume name
    """
    pool_obj = conn.storagePoolLookupByName(pool)
    return pool_obj.storageVolLookupByName(vol)

def _is_valid_volume(vol):
    """
    Checks whether a volume is valid for further use since those may have disappeared since
    the last pool refresh.
    """
    try:
        # Getting info on an invalid volume raises error and libvirt logs an error
        def discarder(ctxt, error):  # pylint: disable=unused-argument
            log.debug("Ignore libvirt error: %s", error[2])

# Disable the libvirt error logging
        libvirt.registerErrorHandler(discarder, None)
        vol.info()
        # Reenable the libvirt error logging
        libvirt.registerErrorHandler(None, None)
        return True
    except libvirt.libvirtError as err:
        return False

def _get_all_volumes_paths(conn):
    """
    Extract the path, name, pool name and backing stores path of all volumes.

:param conn: libvirt connection to use
    """
    pools = [
        pool
        for pool in conn.listAllStoragePools()
        if pool.info()[0] == libvirt.VIR_STORAGE_POOL_RUNNING
    ]
    volumes = {}
    for pool in pools:
        pool_volumes = {
            volume.path(): {
                "pool": pool.name(),
                "name": volume.name(),
                "backing_stores": [
                    path.text
                    for path in ElementTree.fromstring(volume.XMLDesc()).findall(
                        ".//backingStore/path"
                    )
                ],
            }
            for volume in pool.listAllVolumes()
            if _is_valid_volume(volume)
        }
        volumes.update(pool_volumes)
    return volumes

def volume_infos(pool=None, volume=None, **kwargs):
    """
    Provide details on a storage volume. If no volume name is provided, the infos
    all the volumes contained in the pool are provided. If no pool is provided,
    the infos of the volumes of all pools are output.

:param pool: libvirt storage pool name (default: ``None``)
    :param volume: name of the volume to get infos from (default: ``None``)
    :param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. versionadded:: 3000

CLI Example:

.. code-block:: bash

salt "*" virt.volume_infos <pool> <volume>
    """
    result = {}
    conn = __get_conn(**kwargs)
    try:
        backing_stores = _get_all_volumes_paths(conn)
        try:
            domains = _get_domain(conn)
            domains_list = domains if isinstance(domains, list) else [domains]
        except CommandExecutionError:
            # Having no VM is not an error here.
            domains_list = []
        disks = {
            domain.name(): {
                node.get("file")
                for node in ElementTree.fromstring(domain.XMLDesc(0)).findall(
                    ".//disk/source/[@file]"
                )
            }
            for domain in domains_list
        }

def _volume_extract_infos(vol):
            """
            Format the volume info dictionary

:param vol: the libvirt storage volume object.
            """
            types = ["file", "block", "dir", "network", "netdir", "ploop"]
            infos = vol.info()

vol_xml = ElementTree.fromstring(vol.XMLDesc())
            backing_store_path = vol_xml.find("./backingStore/path")
            backing_store_format = vol_xml.find("./backingStore/format")
            backing_store = None
            if backing_store_path is not None:
                backing_store = {
                    "path": backing_store_path.text,
                    "format": (
                        backing_store_format.get("type")
                        if backing_store_format is not None
                        else None
                    ),
                }

format_node = vol_xml.find("./target/format")

# If we have a path, check its use.
            used_by = []
            if vol.path():
                as_backing_store = {
                    path
                    for (path, volume) in backing_stores.items()
                    if vol.path() in volume.get("backing_stores")
                }
                used_by = [
                    vm_name
                    for (vm_name, vm_disks) in disks.items()
                    if vm_disks & as_backing_store or vol.path() in vm_disks
                ]

return {
                "type": types[infos[0]] if infos[0] < len(types) else "unknown",
                "key": vol.key(),
                "path": vol.path(),
                "capacity": infos[1],
                "allocation": infos[2],
                "used_by": used_by,
                "backing_store": backing_store,
                "format": format_node.get("type") if format_node is not None else None,
            }

pools = [
            obj
            for obj in conn.listAllStoragePools()
            if (pool is None or obj.name() == pool)
            and obj.info()[0] == libvirt.VIR_STORAGE_POOL_RUNNING
        ]
        vols = {
            pool_obj.name(): {
                vol.name(): _volume_extract_infos(vol)
                for vol in pool_obj.listAllVolumes()
                if (volume is None or vol.name() == volume) and _is_valid_volume(vol)
            }
            for pool_obj in pools
        }
        return {pool_name: volumes for (pool_name, volumes) in vols.items() if volumes}
    except libvirt.libvirtError as err:
        log.debug("Silenced libvirt error: %s", err)
    finally:
        conn.close()
    return result

def volume_delete(pool, volume, **kwargs):
    """
    Delete a libvirt managed volume.

:param pool: libvirt storage pool name
    :param volume: name of the volume to delete
    :param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. versionadded:: 3000

CLI Example:

.. code-block:: bash

salt "*" virt.volume_delete <pool> <volume>
    """
    conn = __get_conn(**kwargs)
    try:
        vol = _get_storage_vol(conn, pool, volume)
        return not bool(vol.delete())
    finally:
        conn.close()

def volume_define(
    pool,
    name,
    size,
    allocation=0,
    format=None,
    type=None,
    permissions=None,
    backing_store=None,
    nocow=False,
    **kwargs,
):
    """
    Create libvirt volume.

:param pool: name of the pool to create the volume in
    :param name: name of the volume to define
    :param size: capacity of the volume to define in MiB
    :param allocation: allocated size of the volume in MiB. Defaults to 0.
    :param format:
        volume format. The allowed values are depending on the pool type.
        Check the virt.pool_capabilities output for the possible values and the default.
    :param type:
        type of the volume. One of file, block, dir, network, netdiri, ploop or None.
        By default, the type is guessed by libvirt from the pool type.
    :param permissions:
        Permissions to set on the target folder. This is mostly used for filesystem-based
        pool types. See :ref:`pool-define-permissions` for more details on this structure.
    :param backing_store:
        dictionary describing a backing file for the volume. It must contain a ``path``
        property pointing to the base volume and a ``format`` property defining the format
        of the base volume.

The base volume format will not be guessed for security reasons and is thus mandatory.
    :param nocow: disable COW for the volume.
    :param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. rubric:: CLI Example:

Volume on ESX:

.. code-block:: bash

salt '*' virt.volume_define "[local-storage]" myvm/myvm.vmdk vmdk 8192

QCow2 volume with backing file:

.. code-block:: bash

salt '*' virt.volume_define default myvm.qcow2 qcow2 8192 \
                            permissions="{'mode': '0775', 'owner': '123', 'group': '345'"}" \
                            backing_store="{'path': '/path/to/base.img', 'format': 'raw'}" \
                            nocow=True

.. versionadded:: 3001
    """
    ret = False
    try:
        conn = __get_conn(**kwargs)
        pool_obj = conn.storagePoolLookupByName(pool)
        pool_type = ElementTree.fromstring(pool_obj.XMLDesc()).get("type")
        new_allocation = allocation
        if pool_type == "logical" and size != allocation:
            new_allocation = size
        xml = _gen_vol_xml(
            name,
            size,
            format=format,
            allocation=new_allocation,
            type=type,
            permissions=permissions,
            backing_store=backing_store,
            nocow=nocow,
        )
        ret = _define_vol_xml_str(conn, xml, pool=pool)
    except libvirt.libvirtError as err:
        raise CommandExecutionError(err.get_error_message())
    finally:
        conn.close()
    return ret

def _volume_upload(conn, pool, volume, file, offset=0, length=0, sparse=False):
    """
    Function performing the heavy duty for volume_upload but using an already
    opened libvirt connection.
    """

def handler(stream, nbytes, opaque):
        return os.read(opaque, nbytes)

def holeHandler(stream, opaque):
        """
        Taken from the sparsestream.py libvirt-python example.
        """
        fd = opaque
        cur = os.lseek(fd, 0, os.SEEK_CUR)

try:
            data = os.lseek(fd, cur, os.SEEK_DATA)
        except OSError as e:
            if e.errno != 6:
                raise e
            else:
                data = -1
        if data < 0:
            inData = False
            eof = os.lseek(fd, 0, os.SEEK_END)
            if eof < cur:
                raise RuntimeError(f"Current position in file after EOF: {cur}")
            sectionLen = eof - cur
        else:
            if data > cur:
                inData = False
                sectionLen = data - cur
            else:
                inData = True

hole = os.lseek(fd, data, os.SEEK_HOLE)
                if hole < 0:
                    raise RuntimeError("No trailing hole")

if hole == data:
                    raise RuntimeError("Impossible happened")
                else:
                    sectionLen = hole - data
        os.lseek(fd, cur, os.SEEK_SET)
        return [inData, sectionLen]

def skipHandler(stream, length, opaque):
        return os.lseek(opaque, length, os.SEEK_CUR)

stream = None
    fd = None
    ret = False
    try:
        pool_obj = conn.storagePoolLookupByName(pool)
        vol_obj = pool_obj.storageVolLookupByName(volume)

stream = conn.newStream()
        fd = os.open(file, os.O_RDONLY)
        vol_obj.upload(
            stream,
            offset,
            length,
            libvirt.VIR_STORAGE_VOL_UPLOAD_SPARSE_STREAM if sparse else 0,
        )
        if sparse:
            stream.sparseSendAll(handler, holeHandler, skipHandler, fd)
        else:
            stream.sendAll(handler, fd)
        ret = True
    except libvirt.libvirtError as err:
        raise CommandExecutionError(err.get_error_message())
    finally:
        if fd:
            try:
                os.close(fd)
            except OSError as err:
                if stream:
                    stream.abort()
                if ret:
                    raise CommandExecutionError(f"Failed to close file: {err.strerror}")
        if stream:
            try:
                stream.finish()
            except libvirt.libvirtError as err:
                if ret:
                    raise CommandExecutionError(
                        f"Failed to finish stream: {err.get_error_message()}"
                    )
    return ret

def volume_upload(pool, volume, file, offset=0, length=0, sparse=False, **kwargs):
    """
    Create libvirt volume.

:param pool: name of the pool to create the volume in
    :param name: name of the volume to define
    :param file: the file to upload to the volume
    :param offset: where to start writing the data in the volume
    :param length: amount of bytes to transfer to the volume
    :param sparse: set to True to preserve data sparsiness.
    :param connection: libvirt connection URI, overriding defaults
    :param username: username to connect with, overriding defaults
    :param password: password to connect with, overriding defaults

.. rubric:: CLI Example:

.. code-block:: bash

salt '*' virt.volume_upload default myvm.qcow2 /path/to/disk.qcow2

.. versionadded:: 3001
    """
    conn = __get_conn(**kwargs)

ret = False
    try:
        ret = _volume_upload(
            conn, pool, volume, file, offset=offset, length=length, sparse=sparse
        )
    finally:
        conn.close()
    return ret

MR SKB