salt.modules.virt
Work with virtual machines managed by libvirt
- depends
-
libvirt Python module
libvirt client
qemu-img
grep
Connection
The connection to the virtualization host can be either setup in the minion configuration, pillar data or overridden for each individual call.
By default, the libvirt connection URL will be guessed: the first available libvirt hypervisor driver will be used. This can be overridden like this:
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
Units
Units 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 |
-
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.all_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.capabilities(**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.cpu_baseline(full=False, migratable=False, out='libvirt', **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_path(path, **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.create_xml_str(xml, **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.ctrl_alt_del(vm_, **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_path(path, 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_vol_xml_str(xml, pool=None, **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_path(path, **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.define_xml_str(xml, **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.delete_snapshots(name, *names, **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.domain_capabilities(emulator=None, arch=None, machine=None, domain=None, **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.freecpu(**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.freemem(**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.full_info(**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_disks(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_graphics(vm_, **kwargs)
-
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
andbhyve
hypervisors support
salt.modules.virt.get_hypervisor()
-
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_loader(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_macs(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_nics(vm_, **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_profiles(hypervisor=None, **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.get_xml(vm_, **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
anddiscard
. 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 forslots
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 toNone
, 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 toNone
, 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'
). Seecp module for more details
seed --
True
to seed the disk image. Only used when theimage
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 forhvm
.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 overi686
.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'
)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.
-
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 toFalse
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
ornetwork
.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 toTrue
. - 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
andlimit
. 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
orauto
- vcpus
-
specify the state of individual vcpu. Possible attribute for each individual vcpu include:
id
,enabled
,hotpluggable
andorder
. Validids
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 areminimum
,exact
orstrict
. - 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 arenone
,partial
andfull
. - 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 arecustom
,host-model
andhost-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 areallow
orforbid
.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
, andthreads
, 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 conains a set of cpu features to fine-tune features provided by the selected CPU model. Use cpu feature
name
as the key and thepolicy
as the value.policy
Attribute takesforce
,require
,optional
,disable
orforbid
. - cache
-
describes the virtual CPU cache. Optional attribute
level
takes an integer value which describes cache levelmode
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 haveid
attribute in case referring to some cell is necessary in the code. optional attributememAccess
control whether the memory is to be mapped asshared
orprivate
,discard
attribute which fine tunes the discard feature for given numa node, possible values areTrue
orFalse
.distances
element define the distance between NUMA cells andsibling
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 (valuesbatch
,idle
,fifo
,rr
) and the optionalpriority
andvcpus
keys. Thepriority
value usually is a positive integer and thevcpus
value is a cpu set like1-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 (valuesbatch
,idle
,fifo
,rr
) and the optionalpriority
andvcpus
keys. Thepriority
value usually is a positive integer and thevcpus
value is a cpu set like1-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 (valuesbatch
,idle
,fifo
,rr
) and the optionalpriority
andvcpus
keys. Thepriority
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 withnodeset
andsize
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 andmemfd
backing. (QEMU/KVM only) - access
-
specify if the memory is to be
shared
orprivate
. This can be overridden per numa node by memAccess. - allocation
-
specify when to allocate the memory by supplying either
immediate
orondemand
. - 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 withimage
as backing file. IfFalse
the file pointed to by theimage
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
andbacking_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 problemsNew 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 beNone
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/[email protected] 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
andio_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
andrdp
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
andrdp
. It has atype
property withaddress
andNone
as possible values, and anaddress
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
orusb-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.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)
-
Returns a bool whether or not this node is a hypervisor of any kind
CLI Example:
salt '*' virt.is_hyper
salt.modules.virt.is_hyper()
-
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_active_vms(**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_domains(**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_inactive_vms(**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_networks(**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_pools(**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.list_snapshots(domain=None, **kwargs)
-
Shared storage migration
- Parameters
-
vm -- domain name
target -- target libvirt URI or host name
-
ssh --
True to connect over ssh
Deprecated since version 3002.
-
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(vm_, target, ssh=False, **kwargs)
-
Attempt to execute non-shared storage "all" migration
- Parameters
-
vm -- domain name
target -- target libvirt host name
-
ssh --
True to connect over ssh
Deprecated since version 3002.
-
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.
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_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(vm_, target, ssh=False, **kwargs)
-
Attempt to execute non-shared storage "inc" migration
- Parameters
-
vm -- domain name
target -- target libvirt host name
-
ssh --
True to connect over ssh
Deprecated since version 3002.
-
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.
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_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.migrate_non_shared_inc(vm_, target, ssh=False, **kwargs)
-
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.migrate_start_postcopy(vm_)
-
create default dict that allows arbitrary level of nesting
salt.modules.virt.nesthash(value=None)
-
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
andparameters
keys. Theparameters
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 optionaltrunk
keys.trunk
is a boolean value indicating whether to use VLAN trunking.tags
is a list of dictionaries with keysid
andnativeMode
. ThenativeMode
value can be one oftagged
oruntagged
.- 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).
-
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.
-
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 optionallocalOnly
boolean one. (defaultNone
)- 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
andport
. Both values are a dictionary withstart
andend
values. (defaultNone
)- 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 addreses 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. (defaultNone
)- 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 optionalname
,mac
andid
properties.New in version 3003.
- bootp
-
A dictionary with a
file
property and an optionalserver
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
andaddr
keys. If both are provided, the requests to the domain are forwarded to the server at theaddr
. If onlydomain
is provided the requests matching this domain will be resolved locally. If onlyaddr
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
andprotocol
keys. Entries can also havetarget
,port
,priority
,domain
andweight
optional properties.
CLI Example:
salt '*' virt.network_define network main bridge openvswitch
New in version 2019.2.0.
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)
-
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_get_xml(name, **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_info(name=None, **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_set_autostart(name, state='on', **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_start(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_stop(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_undefine(name, **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
andparameters
keys. Theparameters
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 optionaltrunk
keys.trunk
is a boolean value indicating whether to use VLAN trunking.tags
is a list of dictionaries with keysid
andnativeMode
. ThenativeMode
value can be one oftagged
oruntagged
.- 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 optionallocalOnly
boolean one. (defaultNone
)- 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
andport
. Both values are a dictionary withstart
andend
values. (defaultNone
)- 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 addreses 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. (defaultNone
)- 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.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)
-
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_devices(**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.node_info(**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.pause(vm_, **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_build(name, **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_capabilities(**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 optionallypart_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
orgluster
. (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
andparent_address
keys.The
parent_address
value is a dictionary withunique_id
andaddress
keys. The address represents a PCI address and is itself a dictionary withdomain
,bus
,slot
andfunction
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
andsecret
keys. The type can be one ofceph
for Ceph RBD orchap
for iSCSI sources.The
secret
value links to a libvirt secret object. It is a dictionary withtype
andvalue
keys. The type value can be eitheruuid
orusage
.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
andpassword
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 forcestart
toTrue
. (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_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)
-
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_delete(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_get_xml(name, **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_info(name=None, **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_list_volumes(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_refresh(name, **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_set_autostart(name, state='on', **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_start(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_stop(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_undefine(name, **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 optionallypart_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
orgluster
. (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
andparent_address
keys.The
parent_address
value is a dictionary withunique_id
andaddress
keys. The address represents a PCI address and is itself a dictionary withdomain
,bus
,slot
andfunction
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
andsecret
keys. The type can be one ofceph
for Ceph RBD orchap
for iSCSI sources.The
secret
value links to a libvirt secret object. It is a dictionary withtype
andvalue
keys. The type value can be eitheruuid
orusage
.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
andpassword
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.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)
-
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.purge(vm_, dirs=False, removables=False, **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.reboot(name, **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.reset(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.resume(vm_, **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.revert_snapshot(name, vm_snapshot=None, cleanup=False, **kwargs)
-
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.seed_non_shared_migrate(disks, force=False)
-
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.set_autostart(vm_, state='on', **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.setmem(vm_, memory, 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.setvcpus(vm_, vcpus, config=False, **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.shutdown(vm_, **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.snapshot(domain, name=None, suffix=None, **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.start(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.stop(name, **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.undefine(vm_, **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 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.
To update any cpu parameters specify the new values to the corresponding tag. To remove any element or attribute, specify
None
object. Please note thatNone
object is mapped tonull
in yaml, usenull
in sls file instead. -
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
anddiscard
. 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 forslots
must be an integer.To remove any parameters, pass a None object, for instance: 'soft_limit':
None
. Please note thatNone
is mapped tonull
in sls file, passnull
in sls file instead.- mem: hard_limit: null soft_limit: null
Changed in version 3002.
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. IfTrue
, 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
-
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.
Refer to Boot parameters definition for the complete boot parameter description.
To update any boot parameters, specify the new path for each. To remove any boot parameters, pass
None
object, for instance: 'kernel':None
. To switch back to BIOS boot, specify ('loader':None
and 'nvram':None
) or 'efi':False
. Please note thatNone
is mapped tonull
in sls file, passnull
in sls file instead.SLS file Example:
- boot: loader: null nvram: null
New in version 3000.
-
boot_dev --
Space separated list of devices to boot from sorted by decreasing priority. Values can be
hd
,fd
,cdrom
ornetwork
.By default, the value will
"hd"
.New in version 3002.
-
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.To update any numatune parameters, specify the new value. To remove any
numatune
parameters, pass a None object, for instance: 'numatune':None
. Please note thatNone
is mapped tonull
in sls file, passnull
in sls file instead.New in version 3003.
-
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.
-
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 toFalse
New in version 3003.
-
test --
run in dry-run mode if set to True
New in version 3001.
-
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 toTrue
. - 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
andlimit
. 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
-
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.
- 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.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)
-
Returns the virtual machine type as a string
CLI Example:
salt '*' virt.virt_type
salt.modules.virt.virt_type()
-
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_cputime(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_diskstats(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_info(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_netstats(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>
salt.modules.virt.vm_state(vm_=None, **kwargs)
-
Create libvirt volume.
- Parameters
-
pool -- name of the pool to create the volume in
name -- name of the volume to define
size -- capacity of the volume to define in MiB
allocation -- allocated size of the volume in MiB. Defaults to 0.
format -- volume format. The allowed values are depending on the pool type. Check the virt.pool_capabilities output for the possible values and the default.
type -- type of the volume. One of file, block, dir, network, netdiri, ploop or None. By default, the type is guessed by libvirt from the pool type.
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.
-
backing_store --
dictionary describing a backing file for the volume. It must contain a
path
property pointing to the base volume and aformat
property defining the format of the base volume.The base volume format will not be guessed for security reasons and is thus mandatory.
nocow -- disable COW for the volume.
connection -- libvirt connection URI, overriding defaults
username -- username to connect with, overriding defaults
password -- password to connect with, overriding defaults
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_define(pool, name, size, allocation=0, format=None, type=None, permissions=None, backing_store=None, nocow=False, **kwargs)
-
Delete a libvirt managed volume.
- Parameters
-
pool -- libvirt storage pool name
volume -- name of the volume to delete
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.volume_delete <pool> <volume>
salt.modules.virt.volume_delete(pool, volume, **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
-
pool -- libvirt storage pool name (default:
None
)volume -- name of the volume to get infos from (default:
None
)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.volume_infos <pool> <volume>
salt.modules.virt.volume_infos(pool=None, volume=None, **kwargs)
-
Create libvirt volume.
- Parameters
-
pool -- name of the pool to create the volume in
name -- name of the volume to define
file -- the file to upload to the volume
offset -- where to start writing the data in the volume
length -- amount of bytes to transfer to the volume
sparse -- set to True to preserve data sparsiness.
connection -- libvirt connection URI, overriding defaults
username -- username to connect with, overriding defaults
password -- password to connect with, overriding defaults
CLI Example:
salt '*' virt.volume_upload default myvm.qcow2 /path/to/disk.qcow2
New in version 3001.
salt.modules.virt.volume_upload(pool, volume, file, offset=0, length=0, sparse=False, **kwargs)
© 2021 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.virt.html