salt.modules.virt¶

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:

virt:
  connection:
    uri: lxc:///

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

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¶

New in version 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.

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
libvirt URI format
libvirt authentication configuration

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 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 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, **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
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, **kwargs)¶

Define a volume based on the XML passed to the function

Parameters

xml -- libvirt XML definition of the storage volume
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 a configuration like this:

virt:
    storagepool: mine

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

Define a 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 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 domain capabilities will be 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:

CLI Example:

salt '*' virt.get_hypervisor

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

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=esxi

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, image=None, 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', enable_vnc=False, enable_qcow=False, graphics=None, os_type=None, arch=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
mem -- Amount of memory to allocate to the virtual machine in MiB.
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:
```
{
    'name': 'name_of_disk_to_change',
    'image': '/path/to/the/image'
}
```
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')
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:
```
graphics={'type': 'vnc'}
```
Deprecated since version 2019.2.0.
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.
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:
```
{
    'name': 'name_of_disk_to_change',
    'overlay_image': True
}
```
Deprecated since version 2019.2.0.
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:
```
{
    'name': 'name_of_disk_to_change',
    'pool': 'mydatastore'
}
```
Deprecated since version Flurorine.
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:
```
{
    'name': 'name_of_nic_to_change',
    'mac': 'MY:MA:CC:ADD:RE:SS'
}
```
Deprecated since 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')
serial_type -- Serial device type. One of 'pty', 'tcp' (Default: None)
telnet_port -- Telnet port to use for serial device of type tcp.
console -- True to add a console device along with serial one (Default: True)
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.

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)

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

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.

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

Returns a bool whether or not this node is a KVM hypervisor

CLI Example:

salt '*' virt.is_kvm_hyper

Deprecated since version 2019.2.0.

salt.modules.virt.is_xen_hyper()¶

Returns a bool whether or not this node is a XEN hypervisor

CLI Example:

salt '*' virt.is_xen_hyper

Deprecated since version 2019.2.0.

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, ssh=False)¶

Shared storage migration

Parameters

vm -- domain name
target -- target libvirt host name
ssh -- True to connect over ssh

CLI Example:

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

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_non_shared(vm_, target, ssh=False)¶

Attempt to execute non-shared storage "all" migration

Parameters

vm -- domain name
target -- target libvirt host name
ssh -- True to connect over ssh

CLI Example:

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

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_non_shared_inc(vm_, target, ssh=False)¶

Attempt to execute non-shared storage "all" migration

Parameters

vm -- domain name
target -- target libvirt host name
ssh -- True to connect over ssh

CLI Example:

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

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.network_define(name, bridge, forward, **kwargs)¶

Create libvirt network.

Parameters

name -- Network name
bridge -- Bridge name
forward -- Forward mode(bridge, router, nat)
vport -- Virtualport type
tag -- Vlan tag
autostart -- Network autostart (default True)
start -- Network start (default True)
connection -- libvirt connection URI, overriding defaults
username -- username to connect with, overriding defaults
password -- password to connect with, overriding defaults

CLI Example:

salt '*' virt.network_define network main bridge openvswitch

New in version 2019.2.0.

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

Return informations 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.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_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, **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 informations on the use of part_separator
source_dir -- Path to the source directory for pools of type dir, netfs or gluster. (Default: None)
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'
    }
}

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, fast=True, **kwargs)¶

Delete the resources of a defined libvirt storage pool.

Parameters

name -- libvirt storage pool name
fast -- if set to False, zeroes out all the data. Default value is True.
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_info(name=None, **kwargs)¶

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

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> removables=False

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 pool, anything else to mark the pool 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>

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

Start a defined domain

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

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

Hard power down the virtual machine, this is equivalent to pulling the power.

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

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

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

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

Parameters

name -- Name of the domain to update
cpu -- Number of virtual CPUs to assign to the virtual machine
mem -- Amount of memory to allocate to the virtual machine in MiB.
disk_profile -- disk profile to use
disks -- Disk definitions as documented in the 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.
nic_profile -- network interfaces profile to use
interfaces -- Network interface definitions as documented in the 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.
graphics -- The new graphics definition as defined in Graphics Definition. If not set, the graphics will not be changed. To remove a graphics device, set this parameter to {'type': 'none'}.
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)
connection -- libvirt connection URI, overriding defaults
username -- username to connect with, overriding defaults
password -- password to connect with, overriding defaults

Returns

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

{
  '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']
}

New in version 2019.2.0.

CLI Example:

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

salt.modules.virt.virt_type()¶

Returns the virtual machine type as a string

CLI Example:

salt '*' virt.virt_type

salt.modules.virt.vm_cputime(vm_=None, **kwargs)¶

Return cputime used by the vms on this hyper in a list of dicts:

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.

[
    '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:

salt '*' virt.vm_cputime

salt.modules.virt.vm_diskstats(vm_=None, **kwargs)¶

Return disk usage counters used by the vms on this hyper in a list of dicts:

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.

[
    '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:

salt '*' virt.vm_blockstats

salt.modules.virt.vm_info(vm_=None, **kwargs)¶

Return detailed information about the vms on this hyper in a list of dicts:

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.

[
    '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:

salt '*' virt.vm_info

salt.modules.virt.vm_netstats(vm_=None, **kwargs)¶

Return combined network counters used by the vms on this hyper in a list of dicts:

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.

[
    '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:

salt '*' virt.vm_netstats

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

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

Generated on January 08, 2021 at 20:51:45 UTC.

You are viewing docs for the previous stable release, 2019.2.8. Switch to docs for the latest stable release, 3002.2, or to a recent doc build from the master branch.

saltstack.com