# salt.states.virt

## Manage virt

For the key certificate this state uses the external pillar in the master to call for the generation and signing of certificates for systems running libvirt:

    libvirt_keys:
      virt.keys

salt.states.virt.defined(name, cpu=None, mem=None, vm_type=None, disk_profile=None, disks=None, nic_profile=None, interfaces=None, graphics=None, seed=True, install=True, pub_key=None, priv_key=None, connection=None, username=None, password=None, os_type=None, arch=None, boot=None, numatune=None, boot_dev=None, hypervisor_features=None, clock=None, serials=None, consoles=None, stop_on_reboot=False, live=True, host_devices=None, autostart=False)

  Starts an existing guest, or defines and starts a new VM with specified arguments.

  Added in version 3001.

  Parameters:

    - name -- name of the virtual machine to run

    - 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: 'yes'
                hotpluggable: 'no'
                order: 1
              1:
                enabled: 'no'
                hotpluggable: 'yes'
            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
            feature:
              policy: optional
              name: lahf_lm
            numa:
              0:
                 cpus: 0-3
                 memory: 1g
                 discard: 'yes'
                 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
                   - scheduler: fifo
                     priority: 2
                     vcpus: 1-3
                   - scheduler: rr
                     priority: 3
                     vcpus: 4
                 iothreadsched:
                   - scheduler: batch
                     iothreads: 2
                 emulatorsched:
                   scheduler: idle
                 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

      Added in version 3003.

    - mem --

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

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

      Changed in version 3002.

    - vm_type -- force virtual machine type for the new VM. The default value is taken from the host capabilities. This could be useful for example to use `'qemu'` type instead of the `'kvm'` one.

    - disk_profile -- Name of the disk profile to use for the new virtual machine

    - disks -- List of disk to create for the new virtual machine. See Disks Definitions for more details on the items on this list.

    - nic_profile -- Name of the network interfaces profile to use for the new virtual machine

    - interfaces -- List of network interfaces to create for the new virtual machine. See Network Interfaces Definitions for more details on the items on this list.

    - graphics -- Graphics device to create for the new virtual machine. See Graphics Definition for more details on this dictionary

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

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

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

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

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

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

    - connection -- libvirt connection URI, overriding defaults

    - username -- username to connect with, overriding defaults

    - password -- password to connect with, overriding defaults

    - os_type -- type of virtualization as found in the `//os/type` element of the libvirt definition. The default value is taken from the host capabilities, with a preference for `hvm`. Only used when creating a new virtual machine.

    - arch -- architecture of the virtual machine. The default value is taken from the host capabilities, but `x86_64` is prefed over `i686`. Only used when creating a new virtual machine.

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

      To update any boot parameters, specify the new path for each. To remove any boot parameters, pass a None object, for instance: 'kernel': `None`.

      Added in version 3000.

    - boot_dev --

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

      By default, the value will `"hd"`.

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

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

      Added in version 3003.

          hypervisor_features:
            kvm-hint-dedicated: True

    - clock --

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

      adjustment

        time adjustment in seconds or `reset`

      utc

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

      timezone

        synchronize the guest to the correspding timezone

      timers

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

      Added 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

    - serials --

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

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

      Added 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 to `False`

      Added in version 3003.

    - live --

      If set to `False` the changes will not be applied live to the running instance, but will only apply at the next start. Note that reboot will not take those changes.

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

      Added in version 3003.

    - autostart -- If set to `True` the host will start the guest after boot. (Default: `False`)

  Example States

  Make sure a virtual machine called `domain_name` is defined:

      domain_name:
        virt.defined:
          - cpu: 2
          - mem: 2048
          - boot_dev: network hd
          - disk_profile: prod
          - disks:
            - name: system
              size: 8192
              overlay_image: True
              pool: default
              image: /path/to/image.qcow2
            - name: data
              size: 16834
          - nic_profile: prod
          - interfaces:
            - name: eth0
              mac: 01:23:45:67:89:AB
            - name: eth1
              type: network
              source: admin
          - graphics:
              type: spice
              listen:
                  type: address
                  address: 192.168.0.125

salt.states.virt.keys(name, basepath='/etc/pki', **kwargs)

  Manage libvirt keys.

  name

    The name variable used to track the execution

  basepath

    Defaults to `/etc/pki`, this is the root location used for libvirt keys on the hypervisor

  The following parameters are optional:

  > country

  >   The country that the certificate should use. Defaults to US.

  > Added in version 2018.3.0.

  > state

  >   The state that the certificate should use. Defaults to Utah.

  > Added in version 2018.3.0.

  > locality

  >   The locality that the certificate should use. Defaults to Salt Lake City.

  > Added in version 2018.3.0.

  > organization

  >   The organization that the certificate should use. Defaults to Salted.

  > Added in version 2018.3.0.

  > expiration_days

  >   The number of days that the certificate should be valid for. Defaults to 365 days (1 year)

  > Added in version 2018.3.0.

salt.states.virt.network_defined(name, bridge, forward, vport=None, tag=None, ipv4_config=None, ipv6_config=None, autostart=True, connection=None, username=None, password=None, mtu=None, domain=None, nat=None, interfaces=None, addresses=None, physical_function=None, dns=None)

  Defines a new network with specified arguments.

  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 (Default: `'None'`) The value can also be a dictionary with `type` and `parameters` keys. The `parameters` value is a dictionary of virtual port parameters.

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

      Changed in version 3003: possible dictionary value

    - tag --

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

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

      Changed in version 3003: possible dictionary value

    - ipv4_config -- IPv4 network configuration. See the `virt.network_define` function corresponding parameter documentation for more details on this dictionary. (Default: None).

    - ipv6_config -- IPv6 network configuration. See the `virt.network_define` function corresponding parameter documentation for more details on this dictionary. (Default: None).

    - autostart -- Network autostart (default `'True'`)

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

      Added in version 3003.

    - domain --

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

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

      Added in version 3003.

    - nat --

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

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

      Added 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"

      Added in version 3003.

    - addresses --

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

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

      Added in version 3003.

    - physical_function --

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

          - forward: hostdev
          - physical_function: "eth0"

      Added in version 3003.

    - dns --

      virtual network DNS configuration The value is a dictionary described in DNS configuration definition. (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

      Added in version 3003.

  Added in version 3001.

      network_name:
        virt.network_defined

      network_name:
        virt.network_defined:
          - bridge: main
          - forward: bridge
          - vport: openvswitch
          - tag: 180
          - autostart: True

      network_name:
        virt.network_defined:
          - bridge: natted
          - forward: nat
          - ipv4_config:
              cidr: 192.168.42.0/24
              dhcp_ranges:
                - start: 192.168.42.10
                  end: 192.168.42.25
                - start: 192.168.42.100
                  end: 192.168.42.150
          - autostart: True

salt.states.virt.network_running(name, bridge, forward, vport=None, tag=None, ipv4_config=None, ipv6_config=None, autostart=True, connection=None, username=None, password=None, mtu=None, domain=None, nat=None, interfaces=None, addresses=None, physical_function=None, dns=None)

  Defines and starts a new network with specified arguments.

  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 (Default: `'None'`) The value can also be a dictionary with `type` and `parameters` keys. The `parameters` value is a dictionary of virtual port parameters.

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

      Changed in version 3003: possible dictionary value

    - tag --

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

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

      Changed in version 3003: possible dictionary value

    - ipv4_config --

      IPv4 network configuration. See the :py:func`virt.network_define <salt.modules.virt.network_define>` function corresponding parameter documentation for more details on this dictionary. (Default: None).

      Added in version 3000.

    - ipv6_config --

      IPv6 network configuration. See the :py:func`virt.network_define <salt.modules.virt.network_define>` function corresponding parameter documentation for more details on this dictionary. (Default: None).

      Added in version 3000.

    - autostart -- Network autostart (default `'True'`)

    - connection --

      libvirt connection URI, overriding defaults

      Added in version 2019.2.0.

    - username --

      username to connect with, overriding defaults

      Added in version 2019.2.0.

    - password --

      password to connect with, overriding defaults

      Added in version 2019.2.0.

    - mtu --

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

      Added in version 3003.

    - domain --

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

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

      Added in version 3003.

    - nat --

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

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

      Added 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"

      Added in version 3003.

    - addresses --

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

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

      Added in version 3003.

    - physical_function --

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

          - forward: hostdev
          - physical_function: "eth0"

      Added in version 3003.

    - dns --

      virtual network DNS configuration The value is a dictionary described in DNS configuration definition. (default `None`)

          - dns:
              forwarders:
                - domain: example.com
                  addr: 192.168.1.1
                - addr: 8.8.8.8
                - domain: www.example.com
              txt:
                host.widgets.com.: "printer=lpr5"
                example.com.: "This domain name is reserved for use in documentation"
              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

      Added in version 3003.

      network_name:
        virt.network_running

      network_name:
        virt.network_running:
          - bridge: main
          - forward: bridge
          - vport: openvswitch
          - tag: 180
          - autostart: True

      network_name:
        virt.network_running:
          - bridge: natted
          - forward: nat
          - ipv4_config:
              cidr: 192.168.42.0/24
              dhcp_ranges:
                - start: 192.168.42.10
                  end: 192.168.42.25
                - start: 192.168.42.100
                  end: 192.168.42.150
          - autostart: True

salt.states.virt.pool_defined(name, ptype=None, target=None, permissions=None, source=None, transient=False, autostart=True, connection=None, username=None, password=None)

  Defines a new pool with specified arguments.

  Added in version 3001.

  Parameters:

    - ptype -- libvirt pool type

    - target -- full path to the target device or folder. (Default: `None`)

    - permissions -- target permissions. See Permissions definition for more details on this structure.

    - source -- dictionary containing keys matching the `source_*` parameters in function `salt.modules.virt.pool_define()`.

    - transient -- when set to `True`, the pool will be automatically undefined after being stopped. (Default: `False`)

    - autostart -- Whether to start the pool when booting the host. (Default: `True`)

    - start -- When `True`, define and start the pool, otherwise the pool will be left stopped.

    - connection -- libvirt connection URI, overriding defaults

    - username -- username to connect with, overriding defaults

    - password -- password to connect with, overriding defaults

      pool_name:
        virt.pool_defined:
          - ptype: netfs
          - target: /mnt/cifs
          - permissions:
              - mode: 0770
              - owner: 1000
              - group: 100
          - source:
              dir: samba_share
              hosts:
                - one.example.com
                - two.example.com
              format: cifs
          - autostart: True

salt.states.virt.pool_deleted(name, purge=False, connection=None, username=None, password=None)

  Deletes a virtual storage pool.

  Parameters:

    - name -- the name of the pool to delete.

    - purge -- if `True`, the volumes contained in the pool will be deleted as well as the pool itself. Note that these will be lost for ever. If `False` the pool will simply be undefined. (Default: `False`)

    - connection -- libvirt connection URI, overriding defaults

    - username -- username to connect with, overriding defaults

    - password -- password to connect with, overriding defaults

  In order to be purged a storage pool needs to be running to get the list of volumes to delete.

  Some libvirt storage drivers may not implement deleting, those actions are implemented on a best effort idea. In any case check the result's comment property to see if any of the action was unsupported.

      pool_name:
        uyuni_virt.pool_deleted:
          - purge: True

  Added in version 3000.

salt.states.virt.pool_running(name, ptype=None, target=None, permissions=None, source=None, transient=False, autostart=True, connection=None, username=None, password=None)

  Defines and starts a new pool with specified arguments.

  Added in version 2019.2.0.

  Parameters:

    - ptype -- libvirt pool type

    - target -- full path to the target device or folder. (Default: `None`)

    - permissions -- target permissions. See Permissions definition for more details on this structure.

    - source -- dictionary containing keys matching the `source_*` parameters in function `salt.modules.virt.pool_define()`.

    - transient -- when set to `True`, the pool will be automatically undefined after being stopped. (Default: `False`)

    - autostart -- Whether to start the pool when booting the host. (Default: `True`)

    - connection -- libvirt connection URI, overriding defaults

    - username -- username to connect with, overriding defaults

    - password -- password to connect with, overriding defaults

      pool_name:
        virt.pool_running

      pool_name:
        virt.pool_running:
          - ptype: netfs
          - target: /mnt/cifs
          - permissions:
              - mode: 0770
              - owner: 1000
              - group: 100
          - source:
              dir: samba_share
              hosts:
                - one.example.com
                - two.example.com
              format: cifs
          - autostart: True

salt.states.virt.powered_off(name, connection=None, username=None, password=None)

  Stops a VM by power off.

  Added in version 2016.3.0.

  Parameters:

    - connection --

      libvirt connection URI, overriding defaults

      Added in version 2019.2.0.

    - username --

      username to connect with, overriding defaults

      Added in version 2019.2.0.

    - password --

      password to connect with, overriding defaults

      Added in version 2019.2.0.

      domain_name:
        virt.stopped

salt.states.virt.rebooted(name, connection=None, username=None, password=None)

  Reboots VMs

  Added in version 2016.3.0.

  Parameters:

    - name

    - connection --

      libvirt connection URI, overriding defaults

      Added in version 2019.2.0.

    - username --

      username to connect with, overriding defaults

      Added in version 2019.2.0.

    - password --

      password to connect with, overriding defaults

      Added in version 2019.2.0.

salt.states.virt.reverted(name, snapshot=None, cleanup=False)

  Deprecated since version 2016.3.0.

  Reverts to the particular snapshot.

  Added in version 2016.3.0.

      domain_name:
        virt.reverted:
          - cleanup: True

      domain_name_1:
        virt.reverted:
          - snapshot: snapshot_name
          - cleanup: False

salt.states.virt.running(name, cpu=None, mem=None, vm_type=None, disk_profile=None, disks=None, nic_profile=None, interfaces=None, graphics=None, seed=True, install=True, pub_key=None, priv_key=None, connection=None, username=None, password=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, autostart=False)

  Starts an existing guest, or defines and starts a new VM with specified arguments.

  Added in version 2016.3.0.

  Parameters:

    - name -- name of the virtual machine to run

    - 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 that `None` object is mapped to `null` in yaml, use `null` 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` and `discard`. The structure of the dictionary is documented in Memory parameter definition. Both decimal and binary base are supported. Detail unit specification is documented in Units specification. Please note that the value for `slots` must be an integer.

      To remove any parameters, pass a None object, for instance: 'soft_limit': `None`. Please note that `None` is mapped to `null` in sls file, pass `null` in sls file instead.

          - mem:
              hard_limit: null
              soft_limit: null

      Changed in version 3002.

    - vm_type --

      force virtual machine type for the new VM. The default value is taken from the host capabilities. This could be useful for example to use `'qemu'` type instead of the `'kvm'` one.

      Added in version 2019.2.0.

    - disk_profile --

      Name of the disk profile to use for the new virtual machine

      Added in version 2019.2.0.

    - disks --

      List of disk to create for the new virtual machine. See Disks Definitions for more details on the items on this list.

      Added in version 2019.2.0.

    - nic_profile --

      Name of the network interfaces profile to use for the new virtual machine

      Added in version 2019.2.0.

    - interfaces --

      List of network interfaces to create for the new virtual machine. See Network Interfaces Definitions for more details on the items on this list.

      Added in version 2019.2.0.

    - graphics --

      Graphics device to create for the new virtual machine. See Graphics Definition for more details on this dictionary

      Added in version 2019.2.0.

    - saltenv --

      Fileserver environment (Default: `'base'`). See `cp module for more details`

      Added in version 2019.2.0.

    - seed --

      `True` to seed the disk image. Only used when the `image` parameter is provided.

        (Default: `True`)

      Added in version 2019.2.0.

    - install --

      install salt minion if absent (Default: `True`)

      Added in version 2019.2.0.

    - pub_key --

      public key to seed with (Default: `None`)

      Added in version 2019.2.0.

    - priv_key --

      public key to seed with (Default: `None`)

      Added in version 2019.2.0.

    - seed_cmd --

      Salt command to execute to seed the image. (Default: `'seed.apply'`)

      Added in version 2019.2.0.

    - connection --

      libvirt connection URI, overriding defaults

      Added in version 2019.2.0.

    - username --

      username to connect with, overriding defaults

      Added in version 2019.2.0.

    - password --

      password to connect with, overriding defaults

      Added in version 2019.2.0.

    - os_type --

      type of virtualization as found in the `//os/type` element of the libvirt definition. The default value is taken from the host capabilities, with a preference for `hvm`. Only used when creating a new virtual machine.

      Added in version 3000.

    - arch --

      architecture of the virtual machine. The default value is taken from the host capabilities, but `x86_64` is prefed over `i686`. Only used when creating a new virtual machine.

      Added in version 3000.

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

      To update any boot parameters, specify the new path for each. To remove any boot parameters, pass a None object, for instance: 'kernel': `None`.

      Added in version 3000.

    - serials --

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

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

      Added in version 3003.

    - boot_dev --

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

      By default, the value will `"hd"`.

      Added 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 that `None` is mapped to `null` in sls file, pass `null` in sls file instead.

      Added 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 to `False`

      Added in version 3003.

    - hypervisor_features --

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

      Added in version 3003.

          hypervisor_features:
            kvm-hint-dedicated: True

    - clock --

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

      adjustment

        time adjustment in seconds or `reset`

      utc

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

      timezone

        synchronize the guest to the correspding timezone

      timers

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

      Added 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

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

      Added in version 3003.

    - autostart -- If set to `True` the host will start the guest after boot. (Default: `False`)

  Example States

  Make sure an already-defined virtual machine called `domain_name` is running:

      domain_name:
        virt.running

  Do the same, but define the virtual machine if needed:

      domain_name:
        virt.running:
          - cpu: 2
          - mem: 2048
          - disk_profile: prod
          - boot_dev: network hd
          - disks:
            - name: system
              size: 8192
              overlay_image: True
              pool: default
              image: /path/to/image.qcow2
            - name: data
              size: 16834
          - nic_profile: prod
          - interfaces:
            - name: eth0
              mac: 01:23:45:67:89:AB
            - name: eth1
              type: network
              source: admin
          - graphics:
              type: spice
              listen:
                  type: address
                  address: 192.168.0.125

salt.states.virt.saved(name, suffix=None)

  Deprecated since version 2016.3.0: Use `snapshot()` instead.

  Takes a snapshot of a particular VM or by a UNIX-style wildcard.

  Added in version 2016.3.0.

      domain_name:
        virt.saved:
          - suffix: periodic

      domain*:
        virt.saved:
          - suffix: periodic

salt.states.virt.snapshot(name, suffix=None, connection=None, username=None, password=None)

  Takes a snapshot of a particular VM or by a UNIX-style wildcard.

  Added in version 2016.3.0.

  Parameters:

    - connection --

      libvirt connection URI, overriding defaults

      Added in version 2019.2.0.

    - username --

      username to connect with, overriding defaults

      Added in version 2019.2.0.

    - password --

      password to connect with, overriding defaults

      Added in version 2019.2.0.

      domain_name:
        virt.snapshot:
          - suffix: periodic

      domain*:
        virt.snapshot:
          - suffix: periodic

salt.states.virt.stopped(name, connection=None, username=None, password=None)

  Stops a VM by shutting it down nicely.

  Added in version 2016.3.0.

  Parameters:

    - connection --

      libvirt connection URI, overriding defaults

      Added in version 2019.2.0.

    - username --

      username to connect with, overriding defaults

      Added in version 2019.2.0.

    - password --

      password to connect with, overriding defaults

      Added in version 2019.2.0.

      domain_name:
        virt.stopped

salt.states.virt.unpowered(name)

  Deprecated since version 2016.3.0: Use `powered_off()` instead.

  Stops a VM by power off.

  Added in version 2016.3.0.

      domain_name:
        virt.stopped

salt.states.virt.volume_defined(pool, name, size, allocation=0, format=None, type=None, permissions=None, backing_store=None, nocow=False, connection=None, username=None, password=None)

  Ensure a disk volume is existing.

  Parameters:

    - pool -- name of the pool containing the volume

    - name -- name of the volume

    - 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 a `format` 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:

      esx_volume:
        virt.volume_defined:
          - pool: "[local-storage]"
          - name: myvm/myvm.vmdk
          - size: 8192

  QCow2 volume with backing file:

      myvolume:
        virt.volume_defined:
          - pool: default
          - name: myvm.qcow2
          - format: qcow2
          - size: 8192
          - permissions:
              mode: '0775'
              owner: '123'
              group: '345'
          - backing_store:
              path: /path/to/base.img
              format: raw
          - nocow: True

  Added in version 3001.