# -*- coding: utf-8 -*-
'''
Work with virtual machines managed by libvirt

:depends: libvirt Python module

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>`_

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

# Import python libs
from __future__ import absolute_import, print_function, unicode_literals
import copy
import os
import re
import sys
import shutil
import subprocess
import string  # pylint: disable=deprecated-module
import logging
import time
import datetime
from xml.etree import ElementTree

# Import third party libs
import jinja2
import jinja2.exceptions
try:
    import libvirt  # pylint: disable=import-error
    from libvirt import libvirtError
    HAS_LIBVIRT = True
except ImportError:
    HAS_LIBVIRT = False

# Import salt libs
import salt.utils.files
import salt.utils.json
import salt.utils.network
import salt.utils.path
import salt.utils.stringutils
import salt.utils.templates
import salt.utils.validate.net
import salt.utils.versions
import salt.utils.yaml
from salt.exceptions import CommandExecutionError, SaltInvocationError
from salt.ext import six
from salt.ext.six.moves import range  # pylint: disable=import-error,redefined-builtin

log = logging.getLogger(__name__)

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

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

    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.connect', None)
        if conn_str is not None:
            salt.utils.versions.warn_until(
                'Sodium',
                '\'virt.connect\' configuration property has been deprecated in favor '
                'of \'virt:connection:uri\'. \'virt.connect\' will stop being used in '
                '{version}.'
            )
        else:
            conn_str = __salt__['config.get']('libvirt:connection', None)
            if conn_str is not None:
                salt.utils.versions.warn_until(
                    'Sodium',
                    '\'libvirt.connection\' configuration property has been deprecated in favor '
                    'of \'virt:connection:uri\'. \'libvirt.connection\' will stop being used in '
                    '{version}.'
                )

        conn_str = __salt__['config.get']('virt:connection:uri', conn_str)

    hypervisor = __salt__['config.get']('libvirt:hypervisor', None)
    if hypervisor is not None:
        salt.utils.versions.warn_until(
            'Sodium',
            '\'libvirt.hypervisor\' configuration property has been deprecated. '
            'Rather use the \'virt:connection:uri\' to properly define the libvirt '
            'URI or alias of the host to connect to. \'libvirt:hypervisor\' will '
            'stop being used in {version}.'
        )

    if hypervisor == 'esxi' and conn_str is None:
        salt.utils.versions.warn_until(
            'Sodium',
            'esxi hypervisor default with no default connection URI detected, '
            'please set \'virt:connection:uri\' to \'esx\' for keep the legacy '
            'behavior. Will default to libvirt guess once \'libvirt:hypervisor\' '
            'configuration is removed in {version}.'
        )
        conn_str = 'esx'

    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:
        raise CommandExecutionError(
            'Sorry, {0} failed to open a connection to the hypervisor '
            'software at {1}'.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 not all_vms:
        raise CommandExecutionError('No virtual machines found.')

    if vms:
        for name in vms:
            if name not in all_vms:
                raise CommandExecutionError('The VM "{name}" is not present'.format(name=name))
            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 = {}
    doc = ElementTree.fromstring(dom.XMLDesc(0))
    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 six.iteritems(v_node.attrib):
                    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 six.iteritems(v_node.attrib):
                    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 six.iteritems(g_node.attrib):
            out[key] = value
    return out


def _get_disks(dom):
    '''
    Get domain disks from a libvirt domain object.
    '''
    disks = {}
    doc = ElementTree.fromstring(dom.XMLDesc(0))
    for elem in doc.findall('devices/disk'):
        source = elem.find('source')
        if source is None:
            continue
        target = elem.find('target')
        if target is None:
            continue
        if 'dev' in target.attrib:
            qemu_target = source.get('file', '')
            if not qemu_target:
                qemu_target = source.get('dev', '')
            if not qemu_target and 'protocol' in source.attrib and 'name' in source.attrib:  # for rbd network
                qemu_target = '{0}:{1}'.format(
                        source.get('protocol'),
                        source.get('name'))
            if not qemu_target:
                continue

            disk = {'file': qemu_target, 'type': elem.get('device')}

            driver = elem.find('driver')
            if driver is not None and driver.get('type') == 'qcow2':
                try:
                    stdout = subprocess.Popen(
                                ['qemu-img', 'info', '--output', 'json', '--backing-chain', disk['file']],
                                shell=False,
                                stdout=subprocess.PIPE).communicate()[0]
                    qemu_output = salt.utils.stringutils.to_str(stdout)
                    output = _parse_qemu_img_info(qemu_output)
                    disk.update(output)
                except TypeError:
                    disk.update({'file': 'Does not exist'})

            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,
                                  shell=True,
                                  stdout=subprocess.PIPE).communicate()[0]
        group = salt.utils.stringutils.to_str(stdout).split('"')[1]
    except IndexError:
        group = 'root'
    try:
        stdout = subprocess.Popen(u_cmd,
                                  shell=True,
                                  stdout=subprocess.PIPE).communicate()[0]
        user = salt.utils.stringutils.to_str(stdout).split('"')[1]
    except IndexError:
        user = 'root'
    return {'user': user, 'group': group}


def _get_migrate_command():
    '''
    Returns the command shared by the different migration types
    '''
    tunnel = __salt__['config.option']('virt.tunnel')
    if tunnel:
        salt.utils.versions.warn_until(
            'Sodium',
            '\'virt.tunnel\' has been deprecated in favor of '
            '\'virt:tunnel\'. \'virt.tunnel\' will stop '
            'being used in {version}.')
    else:
        tunnel = __salt__['config.get']('virt:tunnel')
    if tunnel:
        return ('virsh migrate --p2p --tunnelled --live --persistent '
                '--undefinesource ')
    return 'virsh migrate --live --persistent --undefinesource '


def _get_target(target, ssh):
    '''
    Compute libvirt URL for target migration host.
    '''
    proto = 'qemu'
    if ssh:
        proto += '+ssh'
    return ' {0}://{1}/{2}'.format(proto, target, 'system')


def _gen_xml(name,
             cpu,
             mem,
             diskp,
             nicp,
             hypervisor,
             os_type,
             arch,
             graphics=None,
             **kwargs):
    '''
    Generate the XML string to define a libvirt VM
    '''
    mem = int(mem) * 1024  # MB
    context = {
        'hypervisor': hypervisor,
        'name': name,
        'cpu': six.text_type(cpu),
        'mem': six.text_type(mem),
    }
    if hypervisor in ['qemu', 'kvm']:
        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

    if 'boot_dev' in kwargs:
        context['boot_dev'] = []
        for dev in kwargs['boot_dev'].split():
            context['boot_dev'].append(dev)
    else:
        context['boot_dev'] = ['hd']

    if os_type == 'xen':
        # Compute the Xen PV boot method
        if __grains__['os_family'] == 'Suse':
            context['kernel'] = '/usr/lib/grub2/x86_64-xen/grub.xen'
            context['boot_dev'] = []

    if 'serial_type' in kwargs:
        context['serial_type'] = kwargs['serial_type']
    if 'serial_type' in context and context['serial_type'] == 'tcp':
        if 'telnet_port' in kwargs:
            context['telnet_port'] = kwargs['telnet_port']
        else:
            context['telnet_port'] = 23023  # FIXME: use random unused port
    if 'serial_type' in context:
        if 'console' in kwargs:
            context['console'] = kwargs['console']
        else:
            context['console'] = True

    context['disks'] = []
    disk_bus_map = {'virtio': 'vd', 'xen': 'xvd', 'fdc': 'fd', 'ide': 'hd'}
    for i, disk in enumerate(diskp):
        prefix = disk_bus_map.get(disk['model'], 'sd')
        disk_context = {
            'device': disk.get('device', 'disk'),
            'target_dev': '{0}{1}'.format(prefix, string.ascii_lowercase[i]),
            'disk_bus': disk['model'],
            'type': disk['format'],
            'index': six.text_type(i),
        }
        if 'source_file' and disk['source_file']:
            disk_context['source_file'] = disk['source_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

    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(vmname,
                 diskname,
                 disktype,
                 size,
                 pool):
    '''
    Generate the XML string to define a libvirt storage volume
    '''
    size = int(size) * 1024  # MB
    context = {
        'name': vmname,
        'filename': '{0}.{1}'.format(diskname, disktype),
        'volname': diskname,
        'disktype': disktype,
        'size': six.text_type(size),
        'pool': pool,
    }
    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):
    '''
    Generate the XML string to define a libvirt network
    '''
    context = {
        'name': name,
        'bridge': bridge,
        'forward': forward,
        'vport': vport,
        'tag': tag,
    }
    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):
    '''
    Generate the XML string to define a libvirt storage pool
    '''
    hosts = [host.split(':') for host in source_hosts or []]
    context = {
        'name': name,
        'ptype': ptype,
        'target': {'path': target, 'permissions': permissions},
        'source': {
            'devices': source_devices or [],
            'dir': source_dir,
            '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
        }
    }
    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 _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.option']('virt.images')
    if img_dir:
        salt.utils.versions.warn_until(
            'Sodium',
            '\'virt.images\' has been deprecated in favor of '
            '\'virt:images\'. \'virt.images\' will stop '
            'being used in {version}.')
    else:
        img_dir = __salt__['config.get']('virt:images')

    log.debug('Image directory from config option `virt:images`'
              ' is %s', img_dir)
    return img_dir


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 {0}, 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']('qemu-img info {}'.format(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={0} {1}'
                    .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'](
                    'qemu-img resize {0} {1}M'
                    .format(img_dest, disk_size)
                )

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

        except (IOError, OSError) as err:
            raise CommandExecutionError(
                'Problem while copying image. {0} - {1}'
                .format(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 {0} {1} {2}M'
                    .format(disk.get('format', 'qcow2'), img_dest, disk_size)
                )
            else:
                raise CommandExecutionError(
                    'Unable to create new disk {0},'
                    ' 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 (IOError, OSError) as err:
            raise CommandExecutionError(
                'Problem while creating volume {0} - {1}'
                .format(img_dest, err)
            )

    return img_dest


def _disk_profile(profile, hypervisor, disks=None, vm_name=None, image=None, pool=None, **kwargs):
    '''
    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',
                   'pool': '[{0}] '.format(pool if pool else '0')}
    elif hypervisor in ['qemu', 'kvm']:
        overlay = {'format': 'qcow2',
                   'device': 'disk',
                   'model': 'virtio'}
    elif hypervisor == 'xen':
        overlay = {'format': 'qcow2',
                   'device': 'disk',
                   'model': 'xen'}
    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 dictionnary and add the name as a property
        disklist = [dict(d, name=name) for disk in disklist for name, d in disk.items()]

        # Add the image to the first disk if there is one
        if image:
            # If image is specified in module arguments, then it will be used
            # for the first disk instead of the image from the disk profile
            log.debug('%s image from module arguments will be used for disk "%s"'
                      ' instead of %s', image, disklist[0]['name'], disklist[0].get('image', ""))
            disklist[0]['image'] = image

    # 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)

    for disk in disklist:
        # Add the missing properties that have defaults
        for key, val in six.iteritems(overlay):
            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 'source_file' in disk and disk['source_file']:
            disk['filename'] = os.path.basename(disk['source_file'])
        elif 'source_file' not in disk:
            _fill_disk_filename(vm_name, disk, hypervisor, **kwargs)

    return disklist


def _fill_disk_filename(vm_name, disk, hypervisor, **kwargs):
    '''
    Compute the disk file name and update it in the disk value.
    '''
    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 the pool is a known libvirt one with a target path, use it as target path
        if not base_dir:
            base_dir = _get_images_dir()
        else:
            if not base_dir.startswith('/'):
                # The pool seems not to be a path, lookup for pool infos
                infos = pool_info(base_dir, **kwargs)
                pool = infos[base_dir] if base_dir in infos else None
                if not pool or not pool['target_path'] or pool['target_path'].startswith('/dev'):
                    raise CommandExecutionError(
                                'Unable to create new disk {0}, specified pool {1} does not exist '
                                'or is unsupported'.format(disk['name'], base_dir))
                base_dir = pool['target_path']

    # Compute the filename and source file properties if possible
    if vm_name:
        disk['filename'] = '{0}_{1}.{2}'.format(vm_name, disk['name'], disk['format'])
        disk['source_file'] = os.path.join(base_dir, disk['filename'])


def _complete_nics(interfaces, hypervisor, dmac=None):
    '''
    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}
    overlays = {
            'xen': xen_overlay,
            'kvm': kvm_overlay,
            'qemu': kvm_overlay,
            'vmware': vmware_overlay,
            }

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

            bridge: br0

             or

            network: net0

             or

            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 six.iteritems(overlays[hypervisor]):
            if key not in attributes or not attributes[key]:
                attributes[key] = value

    def _assign_mac(attributes, hypervisor):
        '''
        Compute mac address for NIC depending on hypervisor
        '''
        if dmac is not None:
            log.debug('Default MAC address is %s', dmac)
            if salt.utils.validate.net.mac(dmac):
                attributes['mac'] = dmac
            else:
                msg = 'Malformed MAC address: {0}'.format(dmac)
                raise CommandExecutionError(msg)
        else:
            if hypervisor in ['qemu', 'kvm']:
                attributes['mac'] = salt.utils.network.gen_mac(
                    prefix='52:54:00')
            else:
                attributes['mac'] = salt.utils.network.gen_mac()

    for interface in interfaces:
        _normalize_net_types(interface)
        if interface.get('mac', None) is None:
            _assign_mac(interface, hypervisor)
        if hypervisor in overlays:
            _apply_default_overlay(interface)

    return interfaces


def _nic_profile(profile_name, hypervisor, dmac=None):
    '''
    Compute NIC data based on profile
    '''

    default = [{'eth0': {}}]

    # support old location
    config_data = __salt__['config.option']('virt.nic', {}).get(
        profile_name, None
    )

    if config_data is not None:
        salt.utils.versions.warn_until(
            'Sodium',
            '\'virt.nic\' has been deprecated in favor of \'virt:nic\'. '
            '\'virt.nic\' will stop being used in {version}.'
        )
    else:
        config_data = __salt__['config.get']('virt:nic', {}).get(
            profile_name, default
        )

    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 six.iteritems(profile_dict):
            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)

    # dmac can only be used from init()
    return _complete_nics(interfaces, hypervisor, dmac=dmac)


def _get_merged_nics(hypervisor, profile, interfaces=None, dmac=None):
    '''
    Get network devices from the profile and merge uer defined ones with them.
    '''
    nicp = _nic_profile(profile, hypervisor, dmac=dmac) 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 init(name,
         cpu,
         mem,
         image=None,
         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',
         enable_vnc=False,
         enable_qcow=False,
         graphics=None,
         os_type=None,
         arch=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
    :param mem: Amount of memory to allocate to the virtual machine in MiB.
    :param image: Path to a disk image to use as the first disk (Default: ``None``).
                  Deprecated in favor of the ``disks`` parameter. To set (or change) the image of a
                  disk, add the following to the disks definitions:

                  .. code-block:: python

                      {
                          'name': 'name_of_disk_to_change',
                          'image': '/path/to/the/image'
                      }

    :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 enable_vnc:
        ``True`` to setup a vnc display for the VM (Default: ``False``)

        Deprecated in favor of the ``graphics`` parameter. Could be replaced with
        the following:

        .. code-block:: python

            graphics={'type': 'vnc'}

        .. deprecated:: 2019.2.0
    :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 enable_qcow:
        ``True`` to create a QCOW2 overlay image, rather than copying the image
        (Default: ``False``).

        Deprecated in favor of ``disks`` parameter. Add the following to the disks
        definitions to create an overlay image of a template disk image with an
        image set:

        .. code-block:: python

            {
                'name': 'name_of_disk_to_change',
                'overlay_image': True
            }

        .. deprecated:: 2019.2.0
    :param pool:
        Path of the folder where the image files are located for vmware/esx hypervisors.

        Deprecated in favor of ``disks`` parameter. Add the following to the disks
        definitions to set the vmware datastore of a disk image:

        .. code-block:: python

            {
                'name': 'name_of_disk_to_change',
                'pool': 'mydatastore'
            }

        .. deprecated:: Flurorine
    :param dmac:
        Default MAC address to use for the network interfaces. By default MAC addresses are
        automatically generated.

        Deprecated in favor of ``interfaces`` parameter. Add the following to the interfaces
        definitions to force the mac address of a NIC:

        .. code-block:: python

            {
                'name': 'name_of_nic_to_change',
                'mac': 'MY:MA:CC:ADD:RE:SS'
            }

        .. deprecated:: 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 serial_type: Serial device type. One of ``'pty'``, ``'tcp'`` (Default: ``None``)
    :param telnet_port: Telnet port to use for serial device of type ``tcp``.
    :param console: ``True`` to add a console device along with serial one (Default: ``True``)
    :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

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

    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``)

    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``)

    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.

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

    .. _init-graphics-def:

    .. rubric:: Graphics Definition

    The graphics dictionnary 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.

    .. 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
    '''
    caps = capabilities(**kwargs)
    os_types = sorted({guest['os_type'] for guest in caps['guests']})
    arches = sorted({guest['arch']['name'] for guest in caps['guests']})
    if not hypervisor:
        hypervisor = __salt__['config.get']('libvirt:hypervisor', hypervisor)
        if hypervisor is not None:
            salt.utils.versions.warn_until(
                'Sodium',
                '\'libvirt:hypervisor\' configuration property has been deprecated. '
                'Rather use the \'virt:connection:uri\' to properly define the libvirt '
                'URI or alias of the host to connect to. \'libvirt:hypervisor\' will '
                'stop being used in {version}.'
            )
        else:
            # 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})
            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
    hypervisor = 'vmware' if hypervisor == 'esxi' else hypervisor

    log.debug('Using hypervisor %s', hypervisor)

    # the NICs are computed as follows:
    # 1 - get the default NICs from the profile
    # 2 - Complete the users NICS
    # 3 - Update the default NICS list to the users one, matching key is the name
    dmac = kwargs.get('dmac', None)
    if dmac:
        salt.utils.versions.warn_until(
            'Sodium',
            '\'dmac\' parameter has been deprecated. Rather use the \'interfaces\' parameter '
            'to properly define the desired MAC address. \'dmac\' will be removed in {version}.'
        )
    nicp = _get_merged_nics(hypervisor, nic, interfaces, dmac=dmac)

    # the disks are computed as follows:
    # 1 - get the disks defined in the profile
    # 2 - set the image on the first disk (will be removed later)
    # 3 - update the disks from the profile with the ones from the user. The matching key is the name.
    pool = kwargs.get('pool', None)
    if pool:
        salt.utils.versions.warn_until(
            'Sodium',
            '\'pool\' parameter has been deprecated. Rather use the \'disks\' parameter '
            'to properly define the vmware datastore of disks. \'pool\' will be removed in {version}.'
        )

    if image:
        salt.utils.versions.warn_until(
            'Sodium',
            '\'image\' parameter has been deprecated. Rather use the \'disks\' parameter '
            'to override or define the image. \'image\' will be removed in {version}.'
        )

    diskp = _disk_profile(disk, hypervisor, disks, name, image=image, pool=pool, **kwargs)

    # Create multiple disks, empty or from specified images.
    for _disk in diskp:
        log.debug("Creating disk for VM [ %s ]: %s", name, _disk)

        if 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)
                vol_xml = _gen_vol_xml(
                    name,
                    _disk['name'],
                    _disk['format'],
                    _disk['size'],
                    _disk['pool']
                )
                define_vol_xml_str(vol_xml)

        elif hypervisor in ['qemu', 'kvm', 'xen']:

            create_overlay = enable_qcow
            if create_overlay:
                salt.utils.versions.warn_until(
                    'Sodium',
                    '\'enable_qcow\' parameter has been deprecated. Rather use the \'disks\' '
                    'parameter to override or define the image. \'enable_qcow\' will be removed '
                    'in {version}.'
                )
            else:
                create_overlay = _disk.get('overlay_image', False)

            if _disk['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:
                img_dest = None

            # Seed only if there is an image specified
            if seed and img_dest and _disk.get('image', None):
                log.debug('Seed command is %s', seed_cmd)
                __salt__[seed_cmd](
                    img_dest,
                    id_=name,
                    config=kwargs.get('config'),
                    install=install,
                    pub_key=pub_key,
                    priv_key=priv_key,
                )

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

    log.debug('Generating VM XML')

    if enable_vnc:
        salt.utils.versions.warn_until(
            'Sodium',
            '\'enable_vnc\' parameter has been deprecated in favor of '
            '\'graphics\'. Use graphics={\'type\': \'vnc\'} for the same behavior. '
            '\'enable_vnc\' will be removed in {version}. ')
        graphics = {'type': 'vnc'}

    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]

    vm_xml = _gen_xml(name, cpu, mem, diskp, nicp, hypervisor, os_type, arch, graphics, **kwargs)
    conn = __get_conn(**kwargs)
    try:
        conn.defineXML(vm_xml)
    except libvirtError as err:
        # check if failure is due to this domain already existing
        if "domain '{}' already exists".format(name) in six.text_type(err):
            # continue on to seeding
            log.warning(err)
        else:
            conn.close()
            raise err  # a real error we should report upwards

    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')
    source1 = ElementTree.tostring(disk1.find('source')) if disk1.find('source') is not None else None
    source2 = ElementTree.tostring(disk2.find('source')) if disk2.find('source') is not None else None

    return source1 == source2 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')


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
        '''
        return {
            'type': nic.attrib['type'],
            'source': nic.find('source').attrib[nic.attrib['type']] if nic.find('source') is not None else None,
            'mac': nic.find('mac').attrib['address'].lower() if nic.find('mac') is not None else None,
            'model': nic.find('model').attrib['type'] if nic.find('model') is not None else None,
        }
    return _filter_nic(nic1) == _filter_nic(nic2)


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 not in node.attrib or node.attrib[attrib] in default['values']):
                node.set(attrib, default['values'][0])
        return gfx_copy

    return ElementTree.tostring(_filter_graphics(gfx1)) == ElementTree.tostring(_filter_graphics(gfx2))


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 _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 = ['{0}{1}'.format(prefix, string.ascii_lowercase[i]) for i in range(len(new))
                      if '{0}{1}'.format(prefix, string.ascii_lowercase[i]) not in targets][0]
        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
    '''
    diff = _diff_lists(old, new, _nics_equal)

    # Remove duplicated addresses mac addresses and let libvirt generate them for us
    macs = [nic.find('mac').get('address') for nic in diff['unchanged']]
    for nic in diff['new']:
        mac = nic.find('mac')
        if mac.get('address') in macs:
            nic.remove(mac)

    return diff


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 update(name,
           cpu=0,
           mem=0,
           disk_profile=None,
           disks=None,
           nic_profile=None,
           interfaces=None,
           graphics=None,
           live=True,
           **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
    :param mem: Amount of memory to allocate to the virtual machine in MiB.
    :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

    :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': []},
        'interface': {'attached': [], 'detached': []}
    }
    conn = __get_conn(**kwargs)
    domain = _get_domain(conn, name)
    desc = ElementTree.fromstring(domain.XMLDesc(0))
    need_update = False

    # Compute the XML to get the disks, interfaces and graphics
    hypervisor = desc.get('type')
    all_disks = _disk_profile(disk_profile, hypervisor, disks, name, **kwargs)
    new_desc = ElementTree.fromstring(_gen_xml(name,
                                               cpu,
                                               mem,
                                               all_disks,
                                               _get_merged_nics(hypervisor, nic_profile, interfaces),
                                               hypervisor,
                                               domain.OSType(),
                                               desc.find('.//os/type').get('arch'),
                                               graphics,
                                               **kwargs))

    # Update the cpu
    cpu_node = desc.find('vcpu')
    if cpu and int(cpu_node.text) != cpu:
        cpu_node.text = six.text_type(cpu)
        cpu_node.set('current', six.text_type(cpu))
        need_update = True

    # Update the memory, note that libvirt outputs all memory sizes in KiB
    for mem_node_name in ['memory', 'currentMemory']:
        mem_node = desc.find(mem_node_name)
        if mem and int(mem_node.text) != mem * 1024:
            mem_node.text = six.text_type(mem)
            mem_node.set('unit', 'MiB')
            need_update = True

    # Update the XML definition with the new disks and diff changes
    devices_node = desc.find('devices')
    parameters = {'disk': ['disks', 'disk_profile'],
                  'interface': ['interfaces', 'nic_profile'],
                  'graphics': ['graphics']}
    changes = {}
    for dev_type in parameters:
        changes[dev_type] = {}
        func_locals = locals()
        if [param for param in parameters[dev_type] if func_locals.get(param, None) is not None]:
            old = devices_node.findall(dev_type)
            new = new_desc.findall('devices/{0}'.format(dev_type))
            changes[dev_type] = globals()['_diff_{0}_lists'.format(dev_type)](old, new)
            if changes[dev_type]['deleted'] or changes[dev_type]['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
        if changes['disk']:
            for idx, item in enumerate(changes['disk']['sorted']):
                source_file = all_disks[idx]['source_file']
                if item in changes['disk']['new'] and source_file and not os.path.isfile(source_file):
                    _qemu_image_create(all_disks[idx])

        try:
            conn.defineXML(salt.utils.stringutils.to_str(ElementTree.tostring(desc)))
            status['definition'] = True
        except libvirt.libvirtError as err:
            conn.close()
            raise err

        # 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 domain.isActive() and live:
            if cpu:
                commands.append({'device': 'cpu',
                                 'cmd': 'setVcpusFlags',
                                 'args': [cpu, libvirt.VIR_DOMAIN_AFFECT_LIVE]})
            if mem:
                commands.append({'device': 'mem',
                                 'cmd': 'setMemoryFlags',
                                 'args': [mem * 1024, libvirt.VIR_DOMAIN_AFFECT_LIVE]})

            for dev_type in ['disk', 'interface']:
                for added in changes[dev_type].get('new', []):
                    commands.append({'device': dev_type,
                                     'cmd': 'attachDevice',
                                     'args': [salt.utils.stringutils.to_str(ElementTree.tostring(added))]})

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

        for cmd in commands:
            try:
                ret = getattr(domain, cmd['cmd'])(*cmd['args'])
                device_type = cmd['device']
                if device_type in ['cpu', 'mem']:
                    status[device_type] = not bool(ret)
                else:
                    actions = {'attachDevice': 'attached', 'detachDevice': 'detached'}
                    status[device_type][actions[cmd['cmd']]].append(cmd['args'][0])

            except libvirt.libvirtError as err:
                if 'errors' not in status:
                    status['errors'] = []
                status['errors'].append(six.text_type(err))

    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(dom):
        '''
        Compute the infos of a domain
        '''
        raw = dom.info()
        return {'cpu': raw[3],
                'cputime': int(raw[4]),
                'disks': _get_disks(dom),
                'graphics': _get_graphics(dom),
                'nics': _get_nics(dom),
                'uuid': _get_uuid(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(_get_domain(conn, vm_))
    else:
        for domain in _get_domain(conn, iterable=True):
            info[domain.name()] = _info(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': six.text_type(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 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_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(_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 = _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=esxi
    '''
    ret = {}

    caps = capabilities(**kwargs)
    hypervisors = sorted({x for y in [guest['arch']['domains'].keys() for guest in caps['guests']] for x in y})
    default_hypervisor = 'kvm' if 'kvm' in hypervisors else hypervisors[0]

    if not hypervisor:
        hypervisor = __salt__['config.get']('libvirt:hypervisor')
        if hypervisor is not None:
            salt.utils.versions.warn_until(
                'Sodium',
                '\'libvirt:hypervisor\' configuration property has been deprecated. '
                'Rather use the \'virt:connection:uri\' to properly define the libvirt '
                'URI or alias of the host to connect to. \'libvirt:hypervisor\' will '
                'stop being used in {version}.'
            )
        else:
            # Use the machine types as possible values
            # Prefer 'kvm' over the others if available
            hypervisor = default_hypervisor
    virtconf = __salt__['config.get']('virt', {})
    for typ in ['disk', 'nic']:
        _func = getattr(sys.modules[__name__], '_{0}_profile'.format(typ))
        ret[typ] = {'default': _func('default', hypervisor)}
        if typ in virtconf:
            ret.setdefault(typ, {})
            for prf in virtconf[typ]:
                ret[typ][prf] = _func(prf, 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 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 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, IOError):
        return False


def define_xml_str(xml, **kwargs):  # pylint: disable=redefined-outer-name
    '''
    Define a 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 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, IOError):
        return False


def define_vol_xml_str(xml, **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 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 a configuration like this:

    .. code-block:: yaml

        virt:
            storagepool: mine
    '''
    poolname = __salt__['config.get']('libvirt:storagepool', None)
    if poolname is not None:
        salt.utils.versions.warn_until(
            'Sodium',
            '\'libvirt:storagepool\' has been deprecated in favor of '
            '\'virt:storagepool\'. \'libvirt:storagepool\' will stop '
            'being used in {version}.'
        )
    else:
        poolname = __salt__['config.get']('virt:storagepool', 'default')

    conn = __get_conn(**kwargs)
    pool = conn.storagePoolLookupByName(six.text_type(poolname))
    ret = pool.createXML(xml, 0) is not None
    conn.close()
    return ret


def define_vol_xml_path(path, **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 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()),
                **kwargs
            )
    except (OSError, IOError):
        return False


def migrate_non_shared(vm_, target, ssh=False):
    '''
    Attempt to execute non-shared storage "all" migration

    :param vm_: domain name
    :param target: target libvirt host name
    :param ssh: True to connect over ssh

    CLI Example:

    .. code-block:: bash

        salt '*' virt.migrate_non_shared <vm name> <target hypervisor>

    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
    '''
    cmd = _get_migrate_command() + ' --copy-storage-all ' + vm_\
        + _get_target(target, ssh)

    stdout = subprocess.Popen(cmd,
                              shell=True,
                              stdout=subprocess.PIPE).communicate()[0]
    return salt.utils.stringutils.to_str(stdout)


def migrate_non_shared_inc(vm_, target, ssh=False):
    '''
    Attempt to execute non-shared storage "all" migration

    :param vm_: domain name
    :param target: target libvirt host name
    :param ssh: True to connect over ssh

    CLI Example:

    .. code-block:: bash

        salt '*' virt.migrate_non_shared_inc <vm name> <target hypervisor>

    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
    '''
    cmd = _get_migrate_command() + ' --copy-storage-inc ' + vm_\
        + _get_target(target, ssh)

    stdout = subprocess.Popen(cmd,
                              shell=True,
                              stdout=subprocess.PIPE).communicate()[0]
    return salt.utils.stringutils.to_str(stdout)


def migrate(vm_, target, ssh=False):
    '''
    Shared storage migration

    :param vm_: domain name
    :param target: target libvirt host name
    :param ssh: True to connect over ssh

    CLI Example:

    .. code-block:: bash

        salt '*' virt.migrate <domain> <target hypervisor>

    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
    '''
    cmd = _get_migrate_command() + ' ' + vm_\
        + _get_target(target, ssh)

    stdout = subprocess.Popen(cmd,
                              shell=True,
                              stdout=subprocess.PIPE).communicate()[0]
    return salt.utils.stringutils.to_str(stdout)


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 six.iteritems(disks):
        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',
                                                             shell=True,
                                                             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_)
        cmd = 'qemu-img create -f ' + form + ' ' + fn_ + ' ' + size
        subprocess.call(cmd, shell=True)
        creds = _libvirt_creds()
        cmd = 'chown ' + creds['user'] + ':' + creds['group'] + ' ' + fn_
        subprocess.call(cmd, shell=True)
    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 pool, anything else to mark the
                  pool 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=None, **kwargs):
    '''
    Recursively destroy and delete a virtual machine, pass True for dir's to
    also delete the directories containing the virtual machine disk images -
    USE WITH EXTREME CAUTION!

    Pass removables=False to avoid deleting cdrom and floppy images. To avoid
    disruption, the default but dangerous value is True. This will be changed
    to the safer False default value in Sodium.

    :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> removables=False
    '''
    conn = __get_conn(**kwargs)
    dom = _get_domain(conn, vm_)
    disks = _get_disks(dom)
    if removables is None:
        salt.utils.versions.warn_until(
            'Sodium',
            'removables argument default value is True, but will be changed '
            'to False by default in {version}. Please set to True to maintain '
            'the current behavior in the future.'
        )
        removables = True
    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
        os.remove(disks[disk]['file'])
        directories.add(os.path.dirname(disks[disk]['file']))
    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+
        dom.undefineFlags(libvirt.VIR_DOMAIN_UNDEFINE_NVRAM)
    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
    '''
    try:
        with salt.utils.files.fopen('/proc/modules') as fp_:
            if 'kvm_' not in salt.utils.stringutils.to_unicode(fp_.read()):
                return False
    except IOError:
        # No /proc/modules? Are we on Windows? Or Solaris?
        return False
    return 'libvirtd' in __salt__['cmd.run'](__grains__['ps'])


def is_kvm_hyper():
    '''
    Returns a bool whether or not this node is a KVM hypervisor

    CLI Example:

    .. code-block:: bash

        salt '*' virt.is_kvm_hyper

    .. deprecated:: 2019.2.0
    '''
    salt.utils.versions.warn_until(
        'Sodium',
        '\'is_kvm_hyper\' function has been deprecated. Use the \'get_hypervisor\' == "kvm" instead. '
        '\'is_kvm_hyper\' will be removed in {version}.'
    )
    return _is_kvm_hyper()


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, IOError):
        # No /proc/modules? Are we on Windows? Or Solaris?
        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

    CLI Example:

    .. code-block:: bash

        salt '*' virt.is_xen_hyper

    .. deprecated:: 2019.2.0
    '''
    salt.utils.versions.warn_until(
        'Sodium',
        '\'is_xen_hyper\' function has been deprecated. Use the \'get_hypervisor\' == "xen" instead. '
        '\'is_xen_hyper\' will be removed in {version}.'
    )
    return _is_xen_hyper()


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

    Detected hypervisors:

    - kvm
    - xen

    CLI Example:

    .. code-block:: bash

        salt '*' virt.get_hypervisor

    .. versionadded:: 2019.2.0
        the function and the ``kvm`` and ``xen`` 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']
    result = [hyper for hyper in hypervisors if getattr(sys.modules[__name__], '_is_{}_hyper').format(hyper)()]
    return result[0] if result else None


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()
    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('{0:.0f}'.format(cputime_percent))
               }
    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 six.itervalues(nics):
            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
    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 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 = "{name}-{suffix}".format(name=name, suffix=suffix)

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

    conn = __get_conn(**kwargs)
    _get_domain(conn, domain).snapshotCreateXML(
        salt.utils.stringutils.to_str(ElementTree.tostring(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 'Snapshot "{0}" not found'.format(vm_snapshot) 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': {}
        },
    }

    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:
        result['features'] = {child.tag: {'toggle': True if child.get('toggle') == 'yes' else False,
                                          'default': True if child.get('default') == 'no' else True}
                              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'] = "{} {}".format(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'] = "{} {}".format(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(**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)
    caps = ElementTree.fromstring(conn.getCapabilities())
    conn.close()

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


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 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 domain capabilities
    will be returned.

    CLI Example:

    .. code-block:: bash

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

    '''
    conn = __get_conn(**kwargs)
    caps = ElementTree.fromstring(conn.getDomainCapabilities(emulator, arch, machine, domain, 0))
    conn.close()

    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 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')
    log.debug('Host CPU model definition: %s', salt.utils.stringutils.to_str(ElementTree.tostring(cpu)))

    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([salt.utils.stringutils.to_str(ElementTree.tostring(cpu))], 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('Model {0} not found in CPU map'.format(cpu_model))
            elif len(cpu_specs) > 1:
                raise ValueError('Multiple models {0} found in CPU map'.format(cpu_model))

            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 cpu.toxml()


def network_define(name, bridge, forward, **kwargs):
    '''
    Create libvirt network.

    :param name: Network name
    :param bridge: Bridge name
    :param forward: Forward mode(bridge, router, nat)
    :param vport: Virtualport type
    :param tag: Vlan tag
    :param autostart: Network autostart (default True)
    :param start: Network start (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

    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)
    autostart = kwargs.get('autostart', True)
    starting = kwargs.get('start', True)
    net_xml = _gen_net_xml(
        name,
        bridge,
        forward,
        vport,
        tag,
    )
    try:
        conn.networkDefineXML(net_xml)
    except libvirtError as err:
        log.warning(err)
        conn.close()
        raise err  # a real error we should report upwards

    try:
        network = conn.networkLookupByName(name)
    except 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 (starting is True or autostart is True) and network.isActive() != 1:
        network.create()

    if autostart is True and network.autostart() != 1:
        network.setAutostart(int(autostart))
    elif autostart is False and network.autostart() == 1:
        network.setAutostart(int(autostart))

    conn.close()

    return True


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

    try:
        nets = [net for net in conn.listAllNetworks() if name is None or net.name() == name]
        result = {net.name(): {
                       'uuid': net.UUIDString(),
                       'bridge': net.bridgeName(),
                       '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', str(err))
    finally:
        conn.close()
    return result


def network_start(name, **kwargs):
    '''
    Start a defined virtual network.

    :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

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

    :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

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

    :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

    .. 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 pool_define(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,
                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 informations 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_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',
                    '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 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)
    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=source_auth,
        source_name=source_name,
        source_format=source_format
    )
    try:
        if transient:
            pool = conn.storagePoolCreateXML(pool_xml)
        else:
            pool = conn.storagePoolDefineXML(pool_xml)
            if start:
                pool.create()
    except 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 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 informations 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', str(err))
    finally:
        conn.close()
    return result


def pool_start(name, **kwargs):
    '''
    Start a defined libvirt storage pool.

    :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

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

    :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

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

    :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

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

    :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

    .. versionadded:: 2019.2.0

    CLI Example:

    .. code-block:: bash

        salt '*' virt.pool_undefine default
    '''
    conn = __get_conn(**kwargs)
    try:
        pool = conn.storagePoolLookupByName(name)
        return not bool(pool.undefine())
    finally:
        conn.close()


def pool_delete(name, fast=True, **kwargs):
    '''
    Delete the resources of a defined libvirt storage pool.

    :param name: libvirt storage pool name
    :param fast: if set to False, zeroes out all the data.
                 Default value is True.
    :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_delete default
    '''
    conn = __get_conn(**kwargs)
    try:
        pool = conn.storagePoolLookupByName(name)
        flags = libvirt.VIR_STORAGE_POOL_DELETE_NORMAL
        if fast:
            flags = libvirt.VIR_STORAGE_POOL_DELETE_ZEROED
        return not bool(pool.delete(flags))
    finally:
        conn.close()


def pool_refresh(name, **kwargs):
    '''
    Refresh a defined libvirt storage pool.

    :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

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

    :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

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