Work with virtual machines managed by libvirt
| depends: |
|
|---|
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
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.
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_migratevirt_typeis_*hyperUnits specification
New in version 3002.
The string should contain a number optionally followed by a unit. The number may have a decimal fraction. If the unit is not given then MiB are set by default. Units can optionally be given in IEC style (such as MiB), although the standard single letter style (such as M) is more convenient.
Valid units include:
| Standard | IEC | Standard | IEC | |
|---|---|---|---|---|
| Unit | Unit | Name | Name | Factor |
| B | Bytes | 1 | ||
| K | KiB | Kilobytes | Kibibytes | 2**10 |
| M | MiB | Megabytes | Mebibytes | 2**20 |
| G | GiB | Gigabytes | Gibibytes | 2**30 |
| T | TiB | Terabytes | Tebibytes | 2**40 |
| P | PiB | Petabytes | Pebibytes | 2**50 |
| E | EiB | Exabytes | Exbibytes | 2**60 |
| Z | ZiB | Zettabytes | Zebibytes | 2**70 |
| Y | YiB | Yottabytes | Yobibytes | 2**80 |
Additional decimal based units:
| Unit | Factor |
|---|---|
| KB | 10**3 |
| MB | 10**6 |
| GB | 10**9 |
| TB | 10**12 |
| PB | 10**15 |
| EB | 10**18 |
| ZB | 10**21 |
| YB | 10**24 |
salt.modules.virt.all_capabilities(**kwargs)¶Return the host and domain capabilities in a single call.
New in version 3001.
| Parameters: |
|
|---|
CLI Example:
salt '*' virt.all_capabilities
salt.modules.virt.capabilities(**kwargs)¶Return the hypervisor connection capabilities.
| Parameters: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
CLI Example:
salt '*' virt.freemem
salt.modules.virt.full_info(**kwargs)¶Return the node_info, vm_info and freemem
| Parameters: |
|
|---|
CLI Example:
salt '*' virt.full_info
salt.modules.virt.get_disks(vm_, **kwargs)¶Return the disks of a named vm
| Parameters: |
|
|---|
CLI Example:
salt '*' virt.get_disks <domain>
salt.modules.virt.get_graphics(vm_, **kwargs)¶Returns the information on vnc for a given vm
| Parameters: |
|
|---|
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, xen and bhyve hypervisors support
salt.modules.virt.get_loader(vm_, **kwargs)¶Returns the information on the loader for a given vm
| Parameters: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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:
| Parameters: |
|
|---|
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: |
|
|---|
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: |
|
|---|
cpu parameters definition
The cpu parameters dictionary can contain the following properties:
1-4,^3 cpuset 3 is excluded.static or autoid, 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 attribute specifies how strictly the virtual CPU provided to the guest matches the CPU
requirements, possible values are minimum, exact or strict.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 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.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.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.name as the key and the policy as the value. policy Attribute takes force, require,
optional, disable or forbid.level takes an integer value which describes cache level
mode attribute supported three possible values: emulate, passthrough, disablecell 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.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.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.scheduler key (values batch, idle, fifo, rr)
and the optional priority and vcpus keys. The priority value usually is a positive integer.Boot parameters definition
The boot parameters dictionary can contains the following properties:
The path to the UEFI binary loader to use.
New in version 3001.
The path to the UEFI data template. The file will be copied when creating the virtual machine.
New in version 3001.
A boolean value.
New in version 3001.
Memory parameter definition
Memory parameter can contain the following properties:
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"}].file which utilizes file memorybacking, anonymous by default and memfd backing.
(QEMU/KVM only)shared or private. This can be overridden per numa node by memAccess.immediate or ondemand.Network Interfaces Definitions
Network interfaces dictionaries can contain the following properties:
'bridge', 'network'None (Default: None).Disks Definitions
Disk dictionaries can contain the following properties:
'qcow2', 'raw', 'vmdk'.
(Default: depends on the hypervisor)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.
One of the disk busses allowed by libvirt (Default: depends on hypervisor)
See the libvirt disk element documentation for the allowed bus types.
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.
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.
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.
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.
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.
'disk')None)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
I/O control policy. String value amongst native, threads and io_uring.
(Default: native)
New in version 3003.
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:
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.
vnc, spice and rdp types.spice type.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:
'tcp', 'pty', 'file', 'udp', 'dev',
'pipe', 'unix'.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: |
|
|---|
CLI Example:
salt '*' virt.list_active_vms
salt.modules.virt.list_domains(**kwargs)¶Return a list of available domains.
| Parameters: |
|
|---|
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: |
|
|---|
CLI Example:
salt '*' virt.list_inactive_vms
salt.modules.virt.list_networks(**kwargs)¶List all virtual networks.
| Parameters: |
|
|---|
New in version 2019.2.0.
CLI Example:
salt '*' virt.list_networks
salt.modules.virt.list_pools(**kwargs)¶List all storage pools.
| Parameters: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
IP configuration definition
Both the IPv4 and IPv6 configuration dictionaries can contain the following properties:
'start' and 'end' properties.A list of dictionaries with ip property and optional name, mac and id properties.
New in version 3003.
A dictionary with a file property and an optional server one.
New in version 3003.
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:
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.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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
New in version 3003.
salt.modules.virt.node_devices(**kwargs)¶List the host available devices.
| Parameters: |
|
|---|
New in version 3003.
salt.modules.virt.node_info(**kwargs)¶Return a dict with information about this node
| Parameters: |
|
|---|
CLI Example:
salt '*' virt.node_info
salt.modules.virt.pause(vm_, **kwargs)¶Pause the named vm
| Parameters: |
|
|---|
CLI Example:
salt '*' virt.pause <domain>
salt.modules.virt.pool_build(name, **kwargs)¶Build a defined libvirt storage pool.
| Parameters: |
|
|---|
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: |
|
|---|
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: |
|
|---|
Permissions definition
The permissions are described by a dictionary containing the following keys:
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
CLI Example:
salt '*' virt.purge <domain>
salt.modules.virt.reboot(name, **kwargs)¶Reboot a domain via ACPI request
| Parameters: |
|
|---|
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: |
|
|---|
CLI Example:
salt '*' virt.reset <domain>
salt.modules.virt.resume(vm_, **kwargs)¶Resume the named vm
| Parameters: |
|
|---|
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: |
|
|---|
New in version 2016.3.0.
CLI Example:
salt '*' virt.revert <domain>
salt '*' virt.revert <domain> <snapshot>
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
CLI Example:
salt '*' virt.shutdown <domain>
salt.modules.virt.snapshot(domain, name=None, suffix=None, **kwargs)¶Create a snapshot of a VM.
| Parameters: |
|
|---|
New in version 2016.3.0.
CLI Example:
salt '*' virt.snapshot <domain>
salt.modules.virt.start(name, **kwargs)¶Start a defined domain
| Parameters: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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, boot=None, numatune=None, test=False, boot_dev=None, hypervisor_features=None, clock=None, serials=None, consoles=None, stop_on_reboot=False, host_devices=None, **kwargs)¶Update the definition of an existing domain.
| Parameters: |
|
|---|---|
| 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: |
|
|---|
[
'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: |
|
|---|
[
'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: |
|
|---|
[
'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: |
|
|---|
[
'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: |
|
|---|
CLI Example:
salt '*' virt.vm_state <domain>
salt.modules.virt.volume_define(pool, name, size, allocation=0, format=None, type=None, permissions=None, backing_store=None, nocow=False, **kwargs)¶Create libvirt volume.
| Parameters: |
|
|---|
CLI Example:
Volume on ESX:
salt '*' virt.volume_define "[local-storage]" myvm/myvm.vmdk vmdk 8192
QCow2 volume with backing file:
salt '*' virt.volume_define default myvm.qcow2 qcow2 8192 permissions="{'mode': '0775', 'owner': '123', 'group': '345'"}" backing_store="{'path': '/path/to/base.img', 'format': 'raw'}" nocow=True
New in version 3001.
salt.modules.virt.volume_delete(pool, volume, **kwargs)¶Delete a libvirt managed volume.
| Parameters: |
|
|---|
New in version 3000.
CLI Example:
salt "*" virt.volume_delete <pool> <volume>
salt.modules.virt.volume_infos(pool=None, volume=None, **kwargs)¶Provide details on a storage volume. If no volume name is provided, the infos all the volumes contained in the pool are provided. If no pool is provided, the infos of the volumes of all pools are output.
| Parameters: |
|
|---|
New in version 3000.
CLI Example:
salt "*" virt.volume_infos <pool> <volume>
salt.modules.virt.volume_upload(pool, volume, file, offset=0, length=0, sparse=False, **kwargs)¶Create libvirt volume.
| Parameters: |
|
|---|
CLI Example:
salt '*' virt.volume_upload default myvm.qcow2 /path/to/disk.qcow2
New in version 3001.
Docs for previous releases are available on readthedocs.org.
Latest Salt release: 3004.1