salt.modules.virt¶

Work with virtual machines managed by libvirt

depends:

• libvirt Python module

• libvirt client

• qemu-img

• grep

virt:
  connection:
    uri: lxc:///

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

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

salt.modules.virt.all_capabilities(**kwargs)¶

Return the host and domain capabilities in a single call.

New in version 3001.

Parameters:

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

CLI Example:

salt '*' virt.all_capabilities

salt.modules.virt.capabilities(**kwargs)¶

Return the hypervisor connection capabilities.

Parameters:

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt '*' virt.capabilities

salt.modules.virt.cpu_baseline(full=False, migratable=False, out='libvirt', **kwargs)¶

Return the optimal 'custom' CPU baseline config for VM's on this minion

New in version 2016.3.0.

Parameters:

• full -- Return all CPU features rather than the ones on top of the closest CPU model

• migratable -- Exclude CPU features that are unmigratable (libvirt 2.13+)

• out -- 'libvirt' (default) for usable libvirt XML definition, 'salt' for nice dict

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.cpu_baseline

salt.modules.virt.create_xml_path(path, **kwargs)¶

Start a transient domain based on the XML-file path passed to the function

Parameters:

• path -- path to a file containing the libvirt XML definition of the domain

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

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

salt.modules.virt.create_xml_str(xml, **kwargs)¶

Start a transient domain based on the XML passed to the function

Parameters:

• xml -- libvirt XML definition of the domain

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

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

salt.modules.virt.ctrl_alt_del(vm_, **kwargs)¶

Sends CTRL+ALT+DEL to a VM

Parameters:

• vm -- domain name

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.ctrl_alt_del <domain>

salt.modules.virt.define_vol_xml_path(path, pool=None, **kwargs)¶

Define a volume based on the XML-file path passed to the function

Parameters:

• path -- path to a file containing the libvirt XML definition of the volume

• pool --

  storage pool name to define the volume in. If defined, this parameter will override the configuration setting.

  New in version 3001.

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

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

salt.modules.virt.define_vol_xml_str(xml, pool=None, **kwargs)¶

Define a volume based on the XML passed to the function

Parameters:

• xml -- libvirt XML definition of the storage volume

• pool --

  storage pool name to define the volume in. If defined, this parameter will override the configuration setting.

  New in version 3001.

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

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

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

virt:
    storagepool: mine

salt.modules.virt.define_xml_path(path, **kwargs)¶

Define a persistent domain based on the XML-file path passed to the function

Parameters:

• path -- path to a file containing the libvirt XML definition of the domain

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

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

salt.modules.virt.define_xml_str(xml, **kwargs)¶

Define a persistent domain based on the XML passed to the function

Parameters:

• xml -- libvirt XML definition of the domain

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

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

salt.modules.virt.delete_snapshots(name, *names, **kwargs)¶

Delete one or more snapshots of the given VM.

Parameters:

• name -- domain name

• names -- names of the snapshots to remove

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

New in version 2016.3.0.

CLI Example:

salt '*' virt.delete_snapshots <domain> all=True
salt '*' virt.delete_snapshots <domain> <snapshot>
salt '*' virt.delete_snapshots <domain> <snapshot1> <snapshot2> ...

salt.modules.virt.domain_capabilities(emulator=None, arch=None, machine=None, domain=None, **kwargs)¶

Return the domain capabilities given an emulator, architecture, machine or virtualization type.

New in version 2019.2.0.

Parameters:

• emulator -- return the capabilities for the given emulator binary

• arch -- return the capabilities for the given CPU architecture

• machine -- return the capabilities for the given emulated machine type

• domain -- return the capabilities for the given virtualization type.

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

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

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

CLI Example:

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

salt.modules.virt.freecpu(**kwargs)¶

Return an int representing the number of unallocated cpus on this hypervisor

Parameters:

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.freecpu

salt.modules.virt.freemem(**kwargs)¶

Return an int representing the amount of memory (in MB) that has not been given to virtual machines on this node

Parameters:

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.freemem

salt.modules.virt.full_info(**kwargs)¶

Return the node_info, vm_info and freemem

Parameters:

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.full_info

salt.modules.virt.get_disks(vm_, **kwargs)¶

Return the disks of a named vm

Parameters:

• vm -- name of the domain

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.get_disks <domain>

salt.modules.virt.get_graphics(vm_, **kwargs)¶

Returns the information on vnc for a given vm

Parameters:

• vm -- name of the domain

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.get_graphics <domain>

salt.modules.virt.get_hypervisor()¶

Returns the name of the hypervisor running on this node or None.

Detected hypervisors:

• kvm

• xen

• bhyve

CLI Example:

salt '*' virt.get_hypervisor

New in version 2019.2.0: the function and the kvm, xen and bhyve hypervisors support

salt.modules.virt.get_loader(vm_, **kwargs)¶

Returns the information on the loader for a given vm

Parameters:

• vm -- name of the domain

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

CLI Example:

salt '*' virt.get_loader <domain>

New in version 2019.2.0.

salt.modules.virt.get_macs(vm_, **kwargs)¶

Return a list off MAC addresses from the named vm

Parameters:

• vm -- name of the domain

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.get_macs <domain>

salt.modules.virt.get_nics(vm_, **kwargs)¶

Return info about the network interfaces of a named vm

Parameters:

• vm -- name of the domain

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.get_nics <domain>

salt.modules.virt.get_profiles(hypervisor=None, **kwargs)¶

Return the virt profiles for hypervisor.

Currently there are profiles for:

• nic

• disk

Parameters:

• hypervisor -- override the default machine type.

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.get_profiles
salt '*' virt.get_profiles hypervisor=vmware

salt.modules.virt.get_xml(vm_, **kwargs)¶

Returns the XML for a given vm

Parameters:

• vm -- domain name

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.get_xml <domain>

salt.modules.virt.init(name, cpu, mem, nic='default', interfaces=None, hypervisor=None, start=True, disk='default', disks=None, saltenv='base', seed=True, install=True, pub_key=None, priv_key=None, seed_cmd='seed.apply', graphics=None, os_type=None, arch=None, boot=None, boot_dev=None, numatune=None, hypervisor_features=None, clock=None, serials=None, consoles=None, stop_on_reboot=False, host_devices=None, **kwargs)¶

Initialize a new vm

Parameters:

• name -- name of the virtual machine to create

• cpu --

  Number of virtual CPUs to assign to the virtual machine or a dictionary with detailed information to configure cpu model and topology, numa node tuning, cpu tuning and iothreads allocation. The structure of the dictionary is documented in cpu parameters definition.

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

  New in version 3003.

• mem --

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

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

  Changed in version 3002.

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

• 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 Network Interfaces Definitions.

  New in version 2019.2.0.

• hypervisor -- the virtual machine type. By default the value will be computed according to the virtual host capabilities.

• start -- True to start the virtual machine after having defined it (Default: True)

• disk -- Disk profile to use (Default: 'default'). If set to None, no profile will be used.

• 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 Disks Definitions.

  New in version 2019.2.0.

• saltenv -- Fileserver environment (Default: 'base'). See cp module for more details

• seed -- True to seed the disk image. Only used when the image parameter is provided. (Default: True)

• install -- install salt minion if absent (Default: True)

• pub_key -- public key to seed with (Default: None)

• priv_key -- public key to seed with (Default: None)

• seed_cmd -- Salt command to execute to seed the image. (Default: 'seed.apply')

• graphics --

  Dictionary providing details on the graphics device to create. (Default: None) See Graphics Definition for more details on the possible values.

  New in version 2019.2.0.

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

  New in version 2019.2.0.

• arch --

  architecture of the virtual machine. The default value is taken from the host capabilities, but x86_64 is prefed over i686.

  New in version 2019.2.0.

• config -- minion configuration to use when seeding. See seed module for more details

• boot_dev -- String of space-separated devices to boot from (Default: 'hd')

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

• stop_on_reboot --

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

  New in version 3003.

• boot --

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

  New in version 3000.

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

• boot_dev --

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

  By default, the value will "hd".

• numatune --

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

  New in version 3003.

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

• hypervisor_features --

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

  New in version 3003.

  hypervisor_features:
    kvm-hint-dedicated: True
  

• clock --

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

  adjustment

  time adjustment in seconds or reset

  utc

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

  timezone

  synchronize the guest to the correspding timezone

  timers

  a dictionary associating the timer name with its configuration. This configuration is a dictionary with the properties track, tickpolicy, catchup, frequency, mode, present, slew, threshold and limit. See libvirt time keeping documentation for the possible values.

  New in version 3003.

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

  clock:

  adjustment: 3600 utc: False

  Set the clock to a specific time zone:

  clock:
    timezone: CEST
  

  Tweak guest timers:

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

• serials --

  Dictionary providing details on the serials connection to create. (Default: None) See Serials and Consoles Definitions for more details on the possible values.

  New in version 3003.

• consoles --

  Dictionary providing details on the consoles device to create. (Default: None) See Serials and Consoles Definitions for more details on the possible values.

  New in version 3003.

• host_devices --

  List of host devices to passthrough to the guest. The value is a list of device names as provided by the node_devices() function. (Default: None)

  New in version 3003.

cpu parameters definition

The cpu parameters dictionary can contain the following properties:

cpuset

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

current

the number of virtual cpus available at startup

placement

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

vcpus

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

match

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

check

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

mode

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

model

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

vendor

specifies CPU vendor requested by the guest.

topology

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

features

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

cache

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

numa

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

vcpupin

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

emulatorpin

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

iothreadpin

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

shares

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

period

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

quota

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

global_period

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

global_quota

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

emulator_period

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

emulator_quota

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

iothread_period

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

iothread_quota

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

vcpusched

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

iothreadsched

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

emulatorsched

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

cachetune

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

monitor

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

memorytune

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

iothreads

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

Boot parameters definition

The boot parameters dictionary can contains the following properties:

kernel

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

initrd

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

cmdline

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

loader

The path to the UEFI binary loader to use.

New in version 3001.

nvram

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

New in version 3001.

efi

A boolean value.

New in version 3001.

Memory parameter definition

Memory parameter can contain the following properties:

boot

The maximum allocation of memory for the guest at boot time

current

The actual allocation of memory for the guest

max

The run time maximum memory allocation of the guest

slots

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

hard_limit

the maximum memory the guest can use

soft_limit

memory limit to enforce during memory contention

swap_hard_limit

the maximum memory plus swap the guest can use

min_guarantee

the guaranteed minimum memory allocation for the guest

hugepages

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

nosharepages

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

locked

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

source

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

access

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

allocation

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

discard

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

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)

Disks Definitions

Disk dictionaries can contain the following properties:

name

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

format

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

size

Disk size in MiB

pool

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

Changed in version 3001.

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

model

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

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

image

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

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

overlay_image

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

Changed in version 3001.

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

backing_store_path

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

New in version 3001.

backing_store_format

Image format of the disk or volume to use as backing store. This property is mandatory when using backing_store_path to avoid problems

New in version 3001.

source_file

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

Changed in version 3001.

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

device

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

hostname_property

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

sparse_volume

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

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

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

io

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

New in version 3003.

iothread_id

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

New in version 3003.

Graphics Definition

The graphics dictionary can have the following properties:

type

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

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

port

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

tls_port

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

listen

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

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

Serials and Consoles Definitions

Serial dictionaries can contain the following properties:

type

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

path

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

host

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

port

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

protocol

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

tls

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

target_port

The guest device port number starting from 0

target_type

The guest device type. Common values are serial, virtio or usb-serial, but more are documented in the libvirt documentation.

CLI Example

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:

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

salt.modules.virt.is_hyper()¶

Returns a bool whether or not this node is a hypervisor of any kind

CLI Example:

salt '*' virt.is_hyper

salt.modules.virt.list_active_vms(**kwargs)¶

Return a list of names for active virtual machine on the minion

Parameters:

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.list_active_vms

salt.modules.virt.list_domains(**kwargs)¶

Return a list of available domains.

Parameters:

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.list_domains

salt.modules.virt.list_inactive_vms(**kwargs)¶

Return a list of names for inactive virtual machine on the minion

Parameters:

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.list_inactive_vms

salt.modules.virt.list_networks(**kwargs)¶

List all virtual networks.

Parameters:

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt '*' virt.list_networks

salt.modules.virt.list_pools(**kwargs)¶

List all storage pools.

Parameters:

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt '*' virt.list_pools

salt.modules.virt.list_snapshots(domain=None, **kwargs)¶

List available snapshots for certain vm or for all.

Parameters:

• domain -- domain name

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

New in version 2016.3.0.

CLI Example:

salt '*' virt.list_snapshots
salt '*' virt.list_snapshots <domain>

salt.modules.virt.migrate(vm_, target, **kwargs)¶

Shared storage migration

Parameters:

• vm -- domain name

• target -- target libvirt URI or host name

• kwargs --

  • live: Use live migration. Default value is True.

  • persistent: Leave the domain persistent on destination host.

    Default value is True.

  • undefinesource: Undefine the domain on the source host.

    Default value is True.

  • offline: If set to True it will migrate the domain definition

    without starting the domain on destination and without stopping it on source host. Default value is False.

  • max_bandwidth: The maximum bandwidth (in MiB/s) that will be used.

  • max_downtime: Set maximum tolerable downtime for live-migration.

    The value represents a number of milliseconds the guest is allowed to be down at the end of live migration.

  • parallel_connections: Specify a number of parallel network connections

    to be used to send memory pages to the destination host.

  • compressed: Activate compression.

  • comp_methods: A comma-separated list of compression methods. Supported

    methods are "mt" and "xbzrle" and can be used in any combination. QEMU defaults to "xbzrle".

  • comp_mt_level: Set compression level. Values are in range from 0 to 9,

    where 1 is maximum speed and 9 is maximum compression.

  • comp_mt_threads: Set number of compress threads on source host.

  • comp_mt_dthreads: Set number of decompress threads on target host.

  • comp_xbzrle_cache: Set the size of page cache for xbzrle compression in bytes.

  • copy_storage: Migrate non-shared storage. It must be one of the following

    values: all (full disk copy) or incremental (Incremental copy)

  • postcopy: Enable the use of post-copy migration.

  • postcopy_bandwidth: The maximum bandwidth allowed in post-copy phase. (MiB/s)

  • username: Username to connect with target host

  • password: Password to connect with target host

  New in version 3002.

CLI Example:

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

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

virt:
    tunnel: True

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

salt.modules.virt.migrate_start_postcopy(vm_)¶

Starts post-copy migration. This function has to be called while live migration is in progress and it has been initiated with the postcopy=True option.

CLI Example:

salt '*' virt.migrate_start_postcopy <domain>

salt.modules.virt.nesthash(value=None)¶

create default dict that allows arbitrary level of nesting

salt.modules.virt.network_define(name, bridge, forward, ipv4_config=None, ipv6_config=None, vport=None, tag=None, autostart=True, start=True, mtu=None, domain=None, nat=None, interfaces=None, addresses=None, physical_function=None, dns=None, **kwargs)¶

Create libvirt network.

Parameters:

• name -- Network name.

• bridge -- Bridge name.

• forward --

  Forward mode (bridge, router, nat).

  Changed in version 3003: a None value creates an isolated network with no forwarding at all

• vport --

  Virtualport type. The value can also be a dictionary with type and parameters keys. The parameters value is a dictionary of virtual port parameters.

  - vport:
      type: openvswitch
      parameters:
        interfaceid: 09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f
  

  Changed in version 3003: possible dictionary value

• tag --

  Vlan tag. The value can also be a dictionary with the tags and optional trunk keys. trunk is a boolean value indicating whether to use VLAN trunking. tags is a list of dictionaries with keys id and nativeMode. The nativeMode value can be one of tagged or untagged.

  - tag:
      trunk: True
      tags:
        - id: 42
          nativeMode: untagged
        - id: 47
  

  Changed in version 3003: possible dictionary value

• autostart -- Network autostart (default True).

• start -- Network start (default True).

• ipv4_config (dict or None) --

  IP v4 configuration. Dictionary describing the IP v4 setup like IP range and a possible DHCP configuration. The structure is documented in net-define-ip.

  New in version 3000.

• ipv6_config (dict or None) --

  IP v6 configuration. Dictionary describing the IP v6 setup like IP range and a possible DHCP configuration. The structure is documented in net-define-ip.

  New in version 3000.

• connection -- libvirt connection URI, overriding defaults.

• username -- username to connect with, overriding defaults.

• password -- password to connect with, overriding defaults.

• mtu --

  size of the Maximum Transmission Unit (MTU) of the network. (default None)

  New in version 3003.

• domain --

  DNS domain name of the DHCP server. The value is a dictionary with a mandatory name property and an optional localOnly boolean one. (default None)

  - domain:
      name: lab.acme.org
      localOnly: True
  

  New in version 3003.

• nat --

  addresses and ports to route in NAT forward mode. The value is a dictionary with optional keys address and port. Both values are a dictionary with start and end values. (default None)

  - forward: nat
  - nat:
      address:
        start: 1.2.3.4
        end: 1.2.3.10
      port:
        start: 500
        end: 1000
  

  New in version 3003.

• interfaces --

  whitespace separated list of network interfaces devices that can be used for this network. (default None)

  - forward: passthrough
  - interfaces: "eth10 eth11 eth12"
  

  New in version 3003.

• addresses --

  whitespace separated list of addresses of PCI devices that can be used for this network in hostdev forward mode. (default None)

  - forward: hostdev
  - interfaces: "0000:04:00.1 0000:e3:01.2"
  

  New in version 3003.

• physical_function --

  device name of the physical interface to use in hostdev forward mode. (default None)

  - forward: hostdev
  - physical_function: "eth0"
  

  New in version 3003.

• dns --

  virtual network DNS configuration. The value is a dictionary described in net-define-dns. (default None)

  - dns:
      forwarders:
        - domain: example.com
          addr: 192.168.1.1
        - addr: 8.8.8.8
        - domain: www.example.com
      txt:
        example.com: "v=spf1 a -all"
        _http.tcp.example.com: "name=value,paper=A4"
      hosts:
        192.168.1.2:
          - mirror.acme.lab
          - test.acme.lab
      srvs:
        - name: ldap
          protocol: tcp
          domain: ldapserver.example.com
          target: .
          port: 389
          priority: 1
          weight: 10
  

  New in version 3003.

IP configuration definition

Both the IPv4 and IPv6 configuration dictionaries can contain the following properties:

cidr

CIDR notation for the network. For example '192.168.124.0/24'

dhcp_ranges

A list of dictionaries with 'start' and 'end' properties.

hosts

A list of dictionaries with ip property and optional name, mac and id properties.

New in version 3003.

bootp

A dictionary with a file property and an optional server one.

New in version 3003.

tftp

The path to the TFTP root directory to serve.

New in version 3003.

DNS configuration definition

The DNS configuration dictionary contains the following optional properties:

forwarders

List of alternate DNS forwarders to use. Each item is a dictionary with the optional domain and addr keys. If both are provided, the requests to the domain are forwarded to the server at the addr. If only domain is provided the requests matching this domain will be resolved locally. If only addr is provided all requests will be forwarded to this DNS server.

txt:

Dictionary of TXT fields to set.

hosts:

Dictionary of host DNS entries. The key is the IP of the host, and the value is a list of hostnames for it.

srvs:

List of SRV DNS entries. Each entry is a dictionary with the mandatory name and protocol keys. Entries can also have target, port, priority, domain and weight optional properties.

CLI Example:

salt '*' virt.network_define network main bridge openvswitch

New in version 2019.2.0.

salt.modules.virt.network_get_xml(name, **kwargs)¶

Return the XML definition of a virtual network

Parameters:

• name -- libvirt network name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 3000.

CLI Example:

salt '*' virt.network_get_xml default

salt.modules.virt.network_info(name=None, **kwargs)¶

Return information on a virtual network provided its name.

Parameters:

• name -- virtual network name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

If no name is provided, return the infos for all defined virtual networks.

New in version 2019.2.0.

CLI Example:

salt '*' virt.network_info default

salt.modules.virt.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.

Parameters:

• name -- virtual network name

• state -- 'on' to auto start the network, anything else to mark the virtual network not to be started when the host boots

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt "*" virt.network_set_autostart <pool> <on | off>

salt.modules.virt.network_start(name, **kwargs)¶

Start a defined virtual network.

Parameters:

• name -- virtual network name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt '*' virt.network_start default

salt.modules.virt.network_stop(name, **kwargs)¶

Stop a defined virtual network.

Parameters:

• name -- virtual network name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt '*' virt.network_stop default

salt.modules.virt.network_undefine(name, **kwargs)¶

Remove a defined virtual network. This does not stop the virtual network.

Parameters:

• name -- virtual network name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt '*' virt.network_undefine default

salt.modules.virt.network_update(name, bridge, forward, ipv4_config=None, ipv6_config=None, vport=None, tag=None, mtu=None, domain=None, nat=None, interfaces=None, addresses=None, physical_function=None, dns=None, test=False, **kwargs)¶

Update a virtual network if needed.

Parameters:

• name -- Network name.

• bridge -- Bridge name.

• forward -- Forward mode (bridge, router, nat). A None value creates an isolated network with no forwarding at all.

• vport --

  Virtualport type. The value can also be a dictionary with type and parameters keys. The parameters value is a dictionary of virtual port parameters.

  - vport:
      type: openvswitch
      parameters:
        interfaceid: 09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f
  

• tag --

  Vlan tag. The value can also be a dictionary with the tags and optional trunk keys. trunk is a boolean value indicating whether to use VLAN trunking. tags is a list of dictionaries with keys id and nativeMode. The nativeMode value can be one of tagged or untagged.

  - tag:
      trunk: True
      tags:
        - id: 42
          nativeMode: untagged
        - id: 47
  

• ipv4_config (dict or None) -- IP v4 configuration. Dictionary describing the IP v4 setup like IP range and a possible DHCP configuration. The structure is documented in net-define-ip.

• ipv6_config (dict or None) -- IP v6 configuration. Dictionary describing the IP v6 setup like IP range and a possible DHCP configuration. The structure is documented in net-define-ip.

• connection -- libvirt connection URI, overriding defaults.

• username -- username to connect with, overriding defaults.

• password -- password to connect with, overriding defaults.

• mtu -- size of the Maximum Transmission Unit (MTU) of the network. (default None)

• domain --

  DNS domain name of the DHCP server. The value is a dictionary with a mandatory name property and an optional localOnly boolean one. (default None)

  - domain:
      name: lab.acme.org
      localOnly: True
  

• nat --

  addresses and ports to route in NAT forward mode. The value is a dictionary with optional keys address and port. Both values are a dictionary with start and end values. (default None)

  - forward: nat
  - nat:
      address:
        start: 1.2.3.4
        end: 1.2.3.10
      port:
        start: 500
        end: 1000
  

• interfaces --

  whitespace separated list of network interfaces devices that can be used for this network. (default None)

  - forward: passthrough
  - interfaces: "eth10 eth11 eth12"
  

• addresses --

  whitespace separated list of addresses of PCI devices that can be used for this network in hostdev forward mode. (default None)

  - forward: hostdev
  - interfaces: "0000:04:00.1 0000:e3:01.2"
  

• physical_function --

  device name of the physical interface to use in hostdev forward mode. (default None)

  - forward: hostdev
  - physical_function: "eth0"
  

• dns --

  virtual network DNS configuration. The value is a dictionary described in net-define-dns. (default None)

  - dns:
      forwarders:
        - domain: example.com
          addr: 192.168.1.1
        - addr: 8.8.8.8
        - domain: www.example.com
      txt:
        example.com: "v=spf1 a -all"
        _http.tcp.example.com: "name=value,paper=A4"
      hosts:
        192.168.1.2:
          - mirror.acme.lab
          - test.acme.lab
      srvs:
        - name: ldap
          protocol: tcp
          domain: ldapserver.example.com
          target: .
          port: 389
          priority: 1
          weight: 10
  

New in version 3003.

salt.modules.virt.node_devices(**kwargs)¶

List the host available devices.

Parameters:

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 3003.

salt.modules.virt.node_info(**kwargs)¶

Return a dict with information about this node

Parameters:

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.node_info

salt.modules.virt.pause(vm_, **kwargs)¶

Pause the named vm

Parameters:

• vm -- domain name

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.pause <domain>

salt.modules.virt.pool_build(name, **kwargs)¶

Build a defined libvirt storage pool.

Parameters:

• name -- libvirt storage pool name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt '*' virt.pool_build default

salt.modules.virt.pool_capabilities(**kwargs)¶

Return the hypervisor connection storage pool capabilities.

The returned data are either directly extracted from libvirt or computed. In the latter case some pool types could be listed as supported while they are not. To distinguish between the two cases, check the value of the computed property.

Parameters:

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 3000.

CLI Example:

salt '*' virt.pool_capabilities

salt.modules.virt.pool_define(name, ptype, target=None, permissions=None, source_devices=None, source_dir=None, source_initiator=None, source_adapter=None, source_hosts=None, source_auth=None, source_name=None, source_format=None, transient=False, start=True, **kwargs)¶

Create libvirt pool.

Parameters:

• name -- Pool name

• ptype -- Pool type. See libvirt documentation for the possible values.

• target -- Pool full path target

• permissions -- Permissions to set on the target folder. This is mostly used for filesystem-based pool types. See Permissions definition for more details on this structure.

• 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 for more information on the use of part_separator

• source_dir -- Path to the source directory for pools of type dir, netfs or gluster. (Default: None)

• source_initiator --

  Initiator IQN for libiscsi-direct pool types. (Default: None)

  New in version 3000.

• 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 for the meaning and possible values of these properties.

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

• 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:

  source_auth={
      'type': 'ceph',
      'username': 'admin',
      'secret': {
          'type': 'uuid',
          'value': '2ec115d7-3a88-3ceb-bc12-0ac909a6fd87'
      }
  }
  

  source_auth={
      'type': 'chap',
      'username': 'myname',
      'secret': {
          'type': 'usage',
          'value': 'mycluster_myname'
      }
  }
  

  Since 3000, instead the source authentication can only contain username and password properties. In this case the libvirt secret will be defined and used. For Ceph authentications a base64 encoded key is expected.

• source_name -- Identifier of name-based sources.

• source_format --

  String representing the source format. The possible values are depending on the source type. See libvirt documentation for the possible values.

• start -- Pool start (default True)

• transient -- When True, the pool will be automatically undefined after being stopped. Note that a transient pool will force start to True. (Default: False)

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

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)

CLI Example:

Local folder pool:

salt '*' virt.pool_define somepool dir target=/srv/mypool                                   permissions="{'mode': '0744' 'ower': 107, 'group': 107 }"

CIFS backed pool:

salt '*' virt.pool_define myshare netfs source_format=cifs                                   source_dir=samba_share source_hosts="['example.com']" target=/mnt/cifs

New in version 2019.2.0.

salt.modules.virt.pool_delete(name, **kwargs)¶

Delete the resources of a defined libvirt storage pool.

Parameters:

• name -- libvirt storage pool name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt '*' virt.pool_delete default

salt.modules.virt.pool_get_xml(name, **kwargs)¶

Return the XML definition of a virtual storage pool

Parameters:

• name -- libvirt storage pool name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 3000.

CLI Example:

salt '*' virt.pool_get_xml default

salt.modules.virt.pool_info(name=None, **kwargs)¶

Return information on a storage pool provided its name.

Parameters:

• name -- libvirt storage pool name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

If no name is provided, return the infos for all defined storage pools.

New in version 2019.2.0.

CLI Example:

salt '*' virt.pool_info default

salt.modules.virt.pool_list_volumes(name, **kwargs)¶

List the volumes contained in a defined libvirt storage pool.

Parameters:

• name -- libvirt storage pool name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt "*" virt.pool_list_volumes <pool>

salt.modules.virt.pool_refresh(name, **kwargs)¶

Refresh a defined libvirt storage pool.

Parameters:

• name -- libvirt storage pool name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt '*' virt.pool_refresh default

salt.modules.virt.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.

Parameters:

• name -- libvirt storage pool name

• state -- 'on' to auto start the pool, anything else to mark the pool not to be started when the host boots

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt "*" virt.pool_set_autostart <pool> <on | off>

salt.modules.virt.pool_start(name, **kwargs)¶

Start a defined libvirt storage pool.

Parameters:

• name -- libvirt storage pool name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt '*' virt.pool_start default

salt.modules.virt.pool_stop(name, **kwargs)¶

Stop a defined libvirt storage pool.

Parameters:

• name -- libvirt storage pool name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt '*' virt.pool_stop default

salt.modules.virt.pool_undefine(name, **kwargs)¶

Remove a defined libvirt storage pool. The pool needs to be stopped before calling.

Parameters:

• name -- libvirt storage pool name

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

New in version 2019.2.0.

CLI Example:

salt '*' virt.pool_undefine default

salt.modules.virt.pool_update(name, ptype, target=None, permissions=None, source_devices=None, source_dir=None, source_initiator=None, source_adapter=None, source_hosts=None, source_auth=None, source_name=None, source_format=None, test=False, **kwargs)¶

Update a libvirt storage pool if needed. If called with test=True, this is also reporting whether an update would be performed.

Parameters:

• name -- Pool name

• ptype --

  Pool type. See libvirt documentation for the possible values.

• target -- Pool full path target

• permissions -- Permissions to set on the target folder. This is mostly used for filesystem-based pool types. See Permissions definition for more details on this structure.

• 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 for more information on the use of part_separator

• source_dir -- Path to the source directory for pools of type dir, netfs or gluster. (Default: None)

• source_initiator --

  Initiator IQN for libiscsi-direct pool types. (Default: None)

  New in version 3000.

• 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 for the meaning and possible values of these properties.

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

• 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:

  source_auth={
      'type': 'ceph',
      'username': 'admin',
      'secret': {
          'type': 'uuid',
          'uuid': '2ec115d7-3a88-3ceb-bc12-0ac909a6fd87'
      }
  }
  

  source_auth={
      'type': 'chap',
      'username': 'myname',
      'secret': {
          'type': 'usage',
          'uuid': 'mycluster_myname'
      }
  }
  

  Since 3000, instead the source authentication can only contain username and password properties. In this case the libvirt secret will be defined and used. For Ceph authentications a base64 encoded key is expected.

• source_name -- Identifier of name-based sources.

• source_format --

  String representing the source format. The possible values are depending on the source type. See libvirt documentation for the possible values.

• test -- run in dry-run mode if set to True

• connection -- libvirt connection URI, overriding defaults

• username -- username to connect with, overriding defaults

• password -- password to connect with, overriding defaults

Example:

Local folder pool:

salt '*' virt.pool_update somepool dir target=/srv/mypool                                   permissions="{'mode': '0744' 'ower': 107, 'group': 107 }"

CIFS backed pool:

salt '*' virt.pool_update myshare netfs source_format=cifs                                   source_dir=samba_share source_hosts="['example.com']" target=/mnt/cifs

New in version 3000.

salt.modules.virt.purge(vm_, dirs=False, removables=False, **kwargs)¶

Recursively destroy and delete a persistent virtual machine, pass True for dir's to also delete the directories containing the virtual machine disk images - USE WITH EXTREME CAUTION!

Parameters:

• vm -- domain name

• dirs -- pass True to remove containing directories

• removables --

  pass True to remove removable devices

  New in version 2019.2.0.

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.purge <domain>

salt.modules.virt.reboot(name, **kwargs)¶

Reboot a domain via ACPI request

Parameters:

• vm -- domain name

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.reboot <domain>

salt.modules.virt.reset(vm_, **kwargs)¶

Reset a VM by emulating the reset button on a physical machine

Parameters:

• vm -- domain name

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.reset <domain>

salt.modules.virt.resume(vm_, **kwargs)¶

Resume the named vm

Parameters:

• vm -- domain name

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.resume <domain>

salt.modules.virt.revert_snapshot(name, vm_snapshot=None, cleanup=False, **kwargs)¶

Revert snapshot to the previous from current (if available) or to the specific.

Parameters:

• name -- domain name

• vm_snapshot -- name of the snapshot to revert

• cleanup -- Remove all newer than reverted snapshots. Values: True or False (default False).

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

New in version 2016.3.0.

CLI Example:

salt '*' virt.revert <domain>
salt '*' virt.revert <domain> <snapshot>

salt.modules.virt.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.

Parameters:

• disks -- the list of disk data as provided by virt.get_disks

• force -- skip checking the compatibility of source and target disk images if True. (default: False)

CLI Example:

salt '*' virt.seed_non_shared_migrate <disks>

salt.modules.virt.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.

Parameters:

• vm -- domain name

• state -- 'on' to auto start the VM, 'off' to mark the VM not to be started when the host boots

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt "*" virt.set_autostart <domain> <on | off>

salt.modules.virt.setmem(vm_, memory, config=False, **kwargs)¶

Changes the amount of memory allocated to VM. The VM must be shutdown for this to work.

Parameters:

• vm -- name of the domain

• memory -- memory amount to set in MB

• config -- if True then libvirt will be asked to modify the config as well

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.setmem <domain> <size>
salt '*' virt.setmem my_domain 768

salt.modules.virt.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

Parameters:

• vm -- name of the domain

• vcpus -- integer representing the number of CPUs to be assigned

• config -- if True then libvirt will be asked to modify the config as well

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.setvcpus <domain> <amount>
salt '*' virt.setvcpus my_domain 4

salt.modules.virt.shutdown(vm_, **kwargs)¶

Send a soft shutdown signal to the named vm

Parameters:

• vm -- domain name

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

CLI Example:

salt '*' virt.shutdown <domain>

salt.modules.virt.snapshot(domain, name=None, suffix=None, **kwargs)¶

Create a snapshot of a VM.

Parameters:

• domain -- domain name

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

• suffix -- Add suffix for the new name. Useful in states, where such snapshots can be distinguished from manually created.

• connection --

  libvirt connection URI, overriding defaults

  New in version 2019.2.0.

• username --

  username to connect with, overriding defaults

  New in version 2019.2.0.

• password --

  password to connect with, overriding defaults

  New in version 2019.2.0.

New in version 2016.3.0.

CLI Example:

salt '*' virt.snapshot <domain>