community.libvirt.virt_cloud_instance module – Provision new virtual machines from cloud images via libvirt

arch

string

Request a non-native CPU architecture for the guest virtual machine.

If omitted, the host CPU architecture will be used in the guest.

audio

dictionary

Configure host audio output for the guest’s sound hardware.

The dictionary contains key/value pairs that define individual audio backend properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

audio_devices

list / elements=dictionary

Configure multiple audio backends for the guest.

autostart

boolean

Set the autostart flag for a domain.

Choices:

• false
• true

base_image

string / required

Path or URL to the cloud image.

Can be a local file path or a remote URL (http, https, ftp).

The image will be automatically downloaded if a URL is provided.

blkiotune

dictionary

Tune block I/O policy for the domain process.

devices

list / elements=dictionary

Tune the weights for individual host block device used by the guest.

Each dictionary entry contains a property name and its corresponding value.

weight

integer

The overall I/O weight of the guest.

The value should be in the range [100, 1000]. After kernel 2.6.39, the value could be in the range [10, 1000].

boot

string

Set the boot device priority for post-install configuration.

boot_opts

dictionary

Additional options for boot configuration.

The dictionary contains key/value pairs that define individual boot options.

channel

dictionary

Attach a communication channel device to connect the guest and host machine.

The dictionary contains key/value pairs that define individual channel properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

channel_devices

list / elements=dictionary

Configure multiple channel devices for the guest.

clock

dictionary

Configure the clock for the guest.

offset

string

Set the clock offset, e.g. utc or localtime.

timers

list / elements=dictionary

Tweak the guest’s timer settings on the specific hypervisor.

Each dictionary entry contains a property name and its corresponding value.

cloud_init

dictionary

Pass cloud-init metadata to the VM.

A cloud-init NoCloud ISO file is generated, and attached to the VM as a CDROM device.

clouduser_ssh_key

string

Specify a public key file to inject into the guest, providing ssh access to the default cloud-init user account.

disable

boolean

Disable cloud-init in the VM for subsequent boots.

Without this, cloud-init may reset auth on each boot.

Choices:

• false
• true

meta_data

any

Specify a cloud-init meta-data file content.

Can be provided as a YAML string (e.g., using the ‘|’ operator in Ansible) or as a dictionary structure.

Note: String values are preferred as dictionary values cannot ensure order preservation.

network_config

any

Specify a cloud-init network-config file content.

Can be provided as a YAML string (e.g., using the ‘|’ operator in Ansible) or as a dictionary structure.

Note: String values are preferred as dictionary values cannot ensure order preservation.

root_password_file

string

A file used to set the VM root password from.

root_password_generate

boolean

Generate a new root password for the VM.

Choices:

• false
• true

root_ssh_key

string

Specify a public key file to inject into the guest.

user_data

any

Specify a cloud-init user-data file content.

Can be provided as a YAML string (e.g., using the ‘|’ operator in Ansible) or as a dictionary structure.

Note: String values are preferred as dictionary values cannot ensure order preservation.

cloud_init_auto_reboot

boolean

When wait_for_cloud_init_reboot=true, automatically inject a reboot instruction into the cloud-init user-data.

If set to false, the reboot instructions should be included in the cloud-init user-data manually.

Only applies when wait_for_cloud_init_reboot=true.

Choices:

• false
• true ← (default)

cloud_init_reboot_timeout

integer

Maximum time in seconds to wait for the cloud-init reboot cycle to complete.

The timeout is checked at minute intervals, so the actual timeout may be up to 60 seconds longer.

Only applies when wait_for_cloud_init_reboot=true.

If the timeout is exceeded, the task will fail.

Default: 600

console

dictionary

Connect a text console between the guest and host.

The dictionary contains key/value pairs that define individual console properties.

Common properties include type and target for different console types.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

console_devices

list / elements=dictionary

Configure multiple console devices for the guest.

controller

dictionary

Attach a controller device to the guest.

The dictionary contains key/value pairs that define individual controller properties.

Examples include type=usb,model=none to disable USB, or type=scsi,model=virtio-scsi for VirtIO SCSI.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

controller_devices

list / elements=dictionary

Configure multiple controller devices for the guest.

cpu

dictionary

Configure the CPU model and CPU features exposed to the guest.

cache

dictionary

vCPU cache configuration for the guest.

level

integer

Specify the level of CPU cache.

mode

string

If set to emulate, the hypervisor will provide a fake CPU cache data.

If set to passthrough, the host CPU cache data reported by the host CPU will be passed through to the vCPU.

If set to disable, the vCPU will report no CPU cache at all.

Choices:

• "emulate"
• "passthrough"
• "disable"

features

dictionary

Fine-tune features provided by the selected CPU model.

The value should be a dictionary where each key is a feature name and the value is a dictionary of options for that feature.

An empty object {} for a feature indicates to enable that feature.

policy

string

The policy for the CPU feature.

If set to force, the vCPU will claim the feature is supported regardless of it being supported by host CPU.

If set to require, guest creation will fail unless the feature is supported by the host CPU or the hypervisor is able to emulate it.

If set to optional, the feature will be supported by vCPU if and only if it is supported by host CPU.

If set to disable, the feature will not be supported by virtual CPU.

If set to forbid, guest creation will fail if the feature is supported by host CPU.

Choices:

• "force"
• "require"
• "optional"
• "disable"
• "forbid"

match

string

Specify how strictly the CPU model should be matched.

Choices:

• "exact"
• "minimum"
• "strict"

migratable

boolean

Specify whether this CPU model is migratable.

Choices:

• false
• true

model

string

A valid CPU model or configuration mode for the guest.

The possible values include: host-model, host-passthrough and maximum.

model_opts

dictionary

Additional options for CPU model configuration.

fallback

string

Specify whether to automatically fall back to the closest model supported by the hypervisor if unable to use the exact CPU model.

Choices:

• "forbid"
• "allow"

vendor_id

string

Set the vendor id seen by the guest. It must be exactly 12 characters long.

Typical possible values are AuthenticAMD and GenuineIntel.

numa

dictionary

Configure NUMA topology for the guest.

cell_specs

list / elements=dictionary

Specify a NUMA cell configuration.

cache_specs

list / elements=dictionary

Describe memory side cache for memory proximity domains.

Each dictionary entry contains a property name and its corresponding value.

cpus

string

Specify the CPU or range of CPUs that are part of this node.

discard

boolean

Fine tune the discard feature for given NUMA node.

Choices:

• false
• true

distances

dictionary

Define the distance between NUMA cells.

sibling_specs

list / elements=dictionary

Specify the distance value between sibling NUMA cells.

Each dictionary entry contains a property name and its corresponding value.

id

integer

Specify the NUMA node ID.

mem_access

string

Specify the memory access mode for the NUMA node.

This is valid only for hugepages-backed memory and nvdimm modules.

Choices:

• "shared"
• "private"

memory

integer

Specify the node memory size with a unit suffix.

interconnects

list / elements=dictionary

Describes the normalized memory read/write latency and bandwidth between Initiator Proximity Domains and Target Proximity Domains.

bandwidth_specs

list / elements=dictionary

Describe bandwidth between two memory nodes.

Each dictionary entry contains a property name and its corresponding value.

latency_specs

list / elements=dictionary

Describe latency between two memory nodes.

Each dictionary entry contains a property name and its corresponding value.

vendor

string

Specify CPU vendor requested by the guest

The list of supported vendors can be found in cpu_map/*_vendors.xml.

cputune

dictionary

Tune CPU parameters for the guest.

emulator_period

integer

Specify the enforcement interval (unit: microseconds) for domain’s emulator threads.

emulator_quota

integer

Specify the maximum allowed bandwidth (unit: microseconds) for domain’s emulator threads.

emulatorpin

dictionary

Specify which host CPUs the domain emulator will be pinned to.

cpuset

string

Specify which physical CPUs to pin to.

emulatorsched

dictionary

Specify the scheduler type for emulator thread.

priority

integer

For real-time schedulers (fifo, rr), priority must be specified as well (and is ignored for non-real-time ones).

The value range for the priority depends on the host kernel (usually 1-99).

scheduler

string

The scheduler type.

Choices:

• "batch"
• "idle"
• "fifo"
• "rr"

global_period

integer

Specify the enforcement CFS scheduler interval (unit: microseconds) for the whole domain.

global_quota

integer

Specify the maximum allowed bandwidth (unit: microseconds) within a period for the whole domain.

iothread_period

integer

Specify the enforcement interval (unit: microseconds) for domain’s IOThreads.

iothread_quota

integer

Specify the maximum allowed bandwidth (unit: microseconds) for domain’s IOThreads.

iothreadpin_specs

list / elements=dictionary

Specify which of host physical CPUs the IOThreads will be pinned to.

cpuset

string

Specify which physical CPUs to pin to.

iothread

integer

Specify the IOThread ID.

iothreadsched_specs

list / elements=dictionary

Specify the scheduler type for particular IOThreads.

iothreads

string

Select which IOThreads this setting applies to.

priority

integer

For real-time schedulers (fifo, rr), priority must be specified as well (and is ignored for non-real-time ones).

The value range for the priority depends on the host kernel (usually 1-99).

scheduler

string

The scheduler type.

Choices:

• "batch"
• "idle"
• "fifo"
• "rr"

period

integer

Specify the enforcement interval (unit: microseconds).

The value should be in range [1000, 1000000]. A period with value 0 means no value.

quota

integer

Specify the maximum allowed bandwidth (unit: microseconds).

A domain with quota as any negative value indicates that the domain has infinite bandwidth for vCPU threads.

shares

integer

Specify the proportional weighted share for the domain.

vcpupin_specs

list / elements=dictionary

Specify which of host’s physical CPUs the domain vCPU will be pinned to

cpuset

string

A comma-separated list of physical CPU numbers.

vcpu

integer

Specify the vCPU ID.

vcpusched_specs

list / elements=dictionary

Specify the scheduler type for particular vCPUs.

priority

integer

For real-time schedulers (fifo, rr), priority must be specified as well (and is ignored for non-real-time ones).

The value range for the priority depends on the host kernel (usually 1-99).

scheduler

string

The scheduler type.

Choices:

• "batch"
• "idle"
• "fifo"
• "rr"

vcpus

string

Select which vCPUs this setting applies to.

disks

list / elements=dictionary

Specify the storage devices for the guest.

address

dictionary

Specify the controller properties where the disk should be attached.

The dictionary contains key/value pairs that define individual properties.

backing_format

string

Disk image format of backing_store.

backing_store

string

Path to a disk to use as the backing store for the newly created image.

blockio

dictionary

Override the default block device properties for the disk.

The dictionary contains key/value pairs that define individual properties.

boot

dictionary

Specify the boot order for the disk device.

The dictionary contains key/value pairs that define individual properties.

The per-device boot elements cannot be used together with general boot elements in the OS bootloader section.

bus

string

Disk bus type. (e.g. ide, sata, scsi, usb, virtio, xen)

cache

string

The cache mode to be used.

Choices:

• "none"
• "writethrough"
• "directsync"
• "unsafe"
• "writeback"

driver

dictionary

Specify the details of the hypervisor disk driver.

The dictionary contains key/value pairs that define individual properties.

format

string

Disk image format. For file volumes, this can be raw, qcow2, vmdk, etc.

geometry

dictionary

Override geometry settings for the disk.

The dictionary contains key/value pairs that define individual properties.

iotune

dictionary

Specify additional per-device I/O tuning.

The dictionary contains key/value pairs that define individual properties.

path

string

The path to some storage media to use, existing or not.

pool

string

An existing libvirt storage pool name to create new storage on.

rawio

boolean

Specify whether the disk needs rawio capability.

Choices:

• false
• true

readonly

boolean

Set drive as readonly

Choices:

• false
• true

serial

string

Serial number of the emulated disk device.

sgio

string

Specify whether unprivileged SG_IO commands are filtered for the disk.

Only available when the device is ‘lun’.

Choices:

• "filtered"
• "unfiltered"

shareable

boolean

Set drive as shareable

Choices:

• false
• true

size

integer

The size (in GiB) to use if creating new storage.

snapshot

string

Indicates the default behavior of the disk during disk snapshots.

Choices:

• "internal"
• "external"
• "no"

source

dictionary

Specify the details of the disk source.

The dictionary contains key/value pairs that define individual properties.

sparse

boolean

Whether to skip fully allocating newly created storage.

Choices:

• false
• true

target

dictionary

Specify the details of the target disk device.

The dictionary contains key/value pairs that define individual properties.

transient

boolean

If true, this indicates that changes to the device contents should be reverted automatically when the guest exits.

Choices:

• false
• true

transient_opts

dictionary

Additional options for transient disk configuration.

share_backing

boolean

If true, the transient disk is supposed to be shared between multiple concurrently running VMs.

Choices:

• false
• true

vol

string

An existing libvirt storage volume to use.

events

dictionary

Specify events values for the guest.

on_crash

string

Action to take when the guest crashes.

Choices:

• "destroy"
• "restart"
• "preserve"
• "rename-restart"
• "coredump-destroy"
• "coredump-restart"

on_lockfailure

string

Action to take when when a lock manager loses resource locks.

Choices:

• "poweroff"
• "restart"
• "pause"
• "ignore"

on_poweroff

string

Action to take when the guest requests a poweroff.

Choices:

• "destroy"
• "restart"
• "preserve"
• "rename-restart"

on_reboot

string

Action to take when the guest requests a reboot.

Choices:

• "destroy"
• "restart"
• "preserve"
• "rename-restart"

features

dictionary

Enable or disable certain machine features.

The value should be a dictionary where each key is a feature name and the value is a dictionary of options for that feature.

An empty object {} for a feature indicates to turn on that feature with default options.

Example: hyperv.spinlocks: {state: off}, pvspinlock: {}

filesystems

list / elements=dictionary

Specifies directories on the host to export to the guest.

accessmode

string

Specify the security mode for accessing the source.

Choices:

• "passthrough"
• "mapped"
• "squash"

address

dictionary

Specify the controller properties where the filesystem should be attached.

The dictionary contains key/value pairs that define individual properties.

binary

dictionary

Tune the options for virtiofsd.

The dictionary contains key/value pairs that define individual properties.

dmode

string

The creation mode for directories when used with the mapped value for accessmode.

driver

dictionary

Specify the details of the hypervisor driver.

The dictionary contains key/value pairs that define individual properties.

fmode

string

The creation mode for files when used with the mapped value for accessmode.

multidevs

string

Specify how to deal with a filesystem export containing more than one device.

Choices:

• "default"
• "remap"
• "forbid"
• "warn"

readonly

boolean

Enable exporting filesystem as a readonly mount for guest.

Choices:

• false
• true

source

dictionary

The source directory configuration on the host.

The dictionary contains key/value pairs that define individual properties.

space_hard_limit

integer

Maximum space available to this guest’s filesystem

space_soft_limit

integer

Maximum space available to this guest’s filesystem.

target

dictionary

The mount target configuration in the guest.

The dictionary contains key/value pairs that define individual properties.

type

string

Specify the source type of the filesystem.

Choices:

• "mount"
• "template"
• "file"
• "block"
• "ram"
• "bind"

force_disk

boolean

Force deletion and recreation of existing disk files.

When set to true, any existing disk files specified in disks will be removed and recreated.

When set to false, the module will fail if any disk file already exists.

This parameter only affects disk file creation, not VM definition.

Use with recreate=true to recreate both the VM and its disk files.

Choices:

• false ← (default)
• true

force_pull

boolean

Force pull of the cloud image even if it already exists in the cache.

Only used when base_image is a URL.

Useful for updating cached images to their latest versions.

Choices:

• false ← (default)
• true

graphics

dictionary

Configure the graphical display for the guest virtual machine.

The dictionary contains key/value pairs that define individual properties.

Common properties include type (e.g. vnc, spice) and listen.

graphics_devices

list / elements=dictionary

Configure multiple graphics devices for the guest.

host_devices

list / elements=dictionary

Configure multiple host devices for the guest.

hostdev

dictionary

Attach a physical host device to the guest.

The dictionary contains key/value pairs that define individual host device properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

hvm

boolean

Request the use of full virtualization.

Choices:

• false
• true

image_cache_dir

path

Directory where downloaded cloud images will be cached.

Only used when base_image is a URL.

If not specified, the base image will be downloaded to the temporary directory and not be cached.

image_checksum

string

If specified, the digest of the downloaded image will be calculated to verify the integrity of the downloaded image.

Format: <algorithm>:<checksum|url>, e.g. sha256:D98291AC[…]B6DC7B97, sha256:http://example.com/path/sha256sum.txt.

Only used when base_image is a URL.

If you worry about portability, only the sha1 algorithm is available on all platforms and python versions.

input

dictionary

Attach an input device to the guest.

Input device types include mouse, tablet, or keyboard.

The dictionary contains key/value pairs that define individual input device properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

input_devices

list / elements=dictionary

Configure multiple input devices for the guest.

iommu

dictionary

Add an IOMMU device to the guest.

The dictionary contains key/value pairs that define individual IOMMU properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

iommu_devices

list / elements=dictionary

Configure multiple IOMMU devices for the guest.

iothreads

integer

Number of I/O threads to configure for the guest.

iothreads_opts

dictionary

Additional options for I/O threads configuration.

defaultiothread

dictionary

Provide the capability to define the default event loop within hypervisor.

thread_pool_max

integer

Set upper boundary for number of worker threads for given IOThread.

thread_pool_min

integer

Set lower boundary for number of worker threads for given IOThread.

iothread_specs

list / elements=dictionary

Provide the capability to specifically define the IOThread ID’s for the domain.

id

integer

Define the IOThread ID.

thread_pool_max

integer

Set upper boundary for number of worker threads for given IOThread.

thread_pool_min

integer

Set lower boundary for number of worker threads for given IOThread.

keywrap

dictionary

Configure domain keywrap settings used for S390 cryptographic key management operations.

ciphers

list / elements=dictionary

Specify the cipher settings for the domain.

Each dictionary entry contains a property name and its corresponding value.

launch_security

dictionary

Enable launch security for the guest.

cbitpos

integer

The C-bit (aka encryption bit) location in guest page table entry.

dh_cert

string

The guest owners base64 encoded Diffie-Hellman (DH) key.

policy

string

The guest policy which must be maintained by the SEV firmware, e.g. 0x01.

reduced_phys_bits

integer

The physical address bit reduction, e.g. 1.

session

string

The guest owners base64 encoded session blob defined in the SEV API spec.

type

string / required

The type of launch security to enable, e.g. sev.

machine

string

The machine type to emulate. This will typically not need to be specified for Xen or KVM.

memballoon

dictionary

Attach a virtual memory balloon device to the guest.

The dictionary contains key/value pairs that define individual memory balloon properties.

Common properties include model (e.g. virtio, xen).

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

memballoon_devices

list / elements=dictionary

Configure multiple memory balloon devices for the guest.

memory

integer

Memory to allocate for the guest, in MiB.

memory_opts

dictionary

Additional options for memory allocation.

current_memory

integer

The actual allocation of memory for the guest, in MiB.

max_memory

integer

The run time maximum memory allocation of the guest, in MiB.

max_memory_opts

dictionary

Additional options for maximum memory configuration.

slots

integer

The number of slots available for adding memory to the guest.

memorybacking

dictionary

Specify how virtual memory pages are backed by host pages

access

dictionary

Configure memory access permissions.

mode

string

The access mode for the memory.

Choices:

• "shared"
• "private"

allocation

dictionary

Configure memory allocation behavior.

mode

string

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

Choices:

• "immediate"
• "ondemand"

threads

integer

The number of threads that hypervisor uses to allocate memory.

discard

boolean

If set to true, the memory content is discarded just before guest shuts down (or when DIMM module is unplugged).

Choices:

• false
• true

hugepage_specs

list / elements=dictionary

Configure hugepage specifications for memory backing.

nodeset

string

Specify the guest’s NUMA nodes to certain hugepage sizes.

page_size

integer

Specify the hugepage size with a unit suffix.

hugepages

boolean

Use huge pages for memory backing.

Choices:

• false
• true

locked

boolean

Memory pages will be locked in host’s memory and will not be swapped out.

Choices:

• false
• true

nosharepages

boolean

Instructs hypervisor to disable shared pages (memory merge, KSM) for this domain.

Choices:

• false
• true

source

dictionary

added in community.libvirt 2.1.0

Configure the source of memory backing.

type

string

The type of memory backing source.

Choices:

• "anonymous"
• "file"
• "memfd"

memtune

dictionary

Tune memory policy for the domain process.

The dictionary contains key/value pairs that define individual memtune entries.

metadata

dictionary

Specify the metadata for the guest virtual machine.

The dictionary contains key/value pairs that define individual metadata entries.

e.g. {uuid: 4dea22b3-1d52-d8f3-2516-782e98ab3fa0}

Use virt-install --metadata=? to see a list of all available sub options.

name

string / required

Name of the new guest virtual machine instance.

networks

list / elements=dictionary

Connect the guest to the host network.

Empty list [] means no default network interface.

address

dictionary

Specify the controller properties where the filesystem should be attached.

The dictionary contains key/value pairs that define individual properties.

boot

dictionary

Specify the boot order for the network interface.

The dictionary contains key/value pairs that define individual properties.

The per-device boot elements cannot be used together with general boot elements in the OS bootloader section.

bridge

string

Name of the host bridge device to connect to.

driver

dictionary

Specify the details of the hypervisor driver.

The dictionary contains key/value pairs that define individual properties.

filterref

dictionary

Configure network traffic filter rules for the guest.

The dictionary contains key/value pairs that define individual properties.

hostdev

string

Name of the host device to connect to for type=hostdev.

This uses PCI passthrough to directly assign a network device.

mac

dictionary

MAC address configuration for the network interface.

address

string

Fixed MAC address for the guest interface.

If not specified, a suitable address will be randomly generated.

model

dictionary

Network device model configuration.

type

string

Network device model as seen by the guest.

Examples include virtio, e1000, rtl8139.

mtu

dictionary

Configure MTU settings for the virtual network link. - The dictionary contains key/value pairs that define individual properties.

network

string

Name of the libvirt virtual network to connect to.

rom

dictionary

Specify the interface ROM BIOS configuration

The dictionary contains key/value pairs that define individual properties.

source

dictionary

Specify the details of the direct attached macvtap interface.

The dictionary contains key/value pairs that define individual properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

Example: source={value: bond0, mode: bridge}

state

dictionary

Set state of the virtual network link

The dictionary contains key/value pairs that define individual properties.

target

dictionary

Specify the details of the target network device.

The dictionary contains key/value pairs that define individual properties.

trust_guest_rx_filters

boolean

When set to true, enables the host to trust and accept MAC address changes and receive filter modifications reported by the guest VM.

Choices:

• false
• true

type

string

The type of network interface.

direct provides direct attachment to host network interface using macvtap.

If omitted, the type of network interface is determined by other options.

Choices:

• "direct"

virtualport

dictionary

Configure virtual port settings for the network interface.

The dictionary contains key/value pairs that define individual properties.

Common properties include type (e.g. 802.1Qbg, 802.1Qbh, openvswitch, midonet) and parameters containing type-specific settings.

numatune

dictionary

Tune NUMA policy for the domain process.

memnode_specs

list / elements=dictionary

Specify memory allocation policies per each guest NUMA node.

cellid

integer

Specify the NUMA node ID.

mode

string

Can be one of interleave, preferred, or strict (the default)

Choices:

• "interleave"
• "preferred"
• "strict"

nodeset

string

Specifies the NUMA nodes to allocate memory from.

memory

dictionary

Specifies how to allocate memory for the domain process on a NUMA host.

mode

string

Can be one of interleave, preferred, or strict (the default)

Choices:

• "interleave"
• "preferred"
• "strict"

nodeset

string

Specifies the NUMA nodes to allocate memory from.

placement

string

Indicate the memory placement mode for domain process.

Choices:

• "static"
• "auto"

osinfo

dictionary

Optimize the guest configuration for a specific operating system.

detect

boolean

Whether virt-install should attempt OS detection from the specified install media.

Choices:

• false
• true

id

string

The full URL style libosinfo ID.

name

aliases: short_id

string

The OS name from libosinfo. (e.g. fedora32, win10)

require

boolean

Whether virt-install should fail if OS detection fails.

Choices:

• false
• true

panic

dictionary

Attach a panic notifier device to the guest.

The dictionary contains key/value pairs that define individual panic device properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

panic_devices

list / elements=dictionary

Configure multiple panic devices for the guest.

parallel

dictionary

Attach a parallel device to the guest.

The dictionary contains key/value pairs that define individual parallel device properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

parallel_devices

list / elements=dictionary

Configure multiple parallel devices for the guest.

paravirt

boolean

This guest should be a paravirtualized guest.

Choices:

• false
• true

pm

dictionary

Configure the power management for the guest.

suspend_to_disk

dictionary

Configure BIOS support for S4 (suspend-to-disk) ACPI sleep states.

enabled

boolean

Enable or disable this sleep state.

Choices:

• false
• true

suspend_to_mem

dictionary

Configure BIOS support for S3 (suspend-to-mem) ACPI sleep states.

enabled

boolean

Enable or disable this sleep state.

Choices:

• false
• true

qemu_commandline

string

Pass options directly to the qemu emulator. Only works for the libvirt qemu driver.

recreate

boolean

Use with present to force the re-creation of an existing VM.

Choices:

• false ← (default)
• true

redirdev

dictionary

Add a redirected device for USB or other device redirection.

The dictionary contains key/value pairs that define individual redirection properties.

Common properties include bus=usb, type=tcp or type=spicevmc.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

redirected_devices

list / elements=dictionary

Configure multiple redirected devices for the guest.

resource

dictionary

Specify resource partitioning for the guest.

The dictionary contains key/value pairs that define individual resource entries.

Use virt-install --resource=? to see a list of all available sub options.

rng

dictionary

Configure a virtual random number generator (RNG) device.

The dictionary contains key/value pairs that define individual RNG properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

rng_devices

list / elements=dictionary

Configure multiple RNG devices for the guest.

security

dictionary

Configure domain seclabel domain settings.

The dictionary contains key/value pairs that define individual security entries.

serial

dictionary

Attach a serial device to the guest with various redirection options.

The dictionary contains key/value pairs that define individual serial device properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

serial_devices

list / elements=dictionary

Configure multiple serial devices for the guest.

shmem

dictionary

Attach a shared memory device to the guest.

The dictionary contains key/value pairs that define individual shared memory properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

shmem_devices

list / elements=dictionary

Configure multiple shared memory devices for the guest.

smartcard

dictionary

Configure a virtual smartcard device.

The dictionary contains key/value pairs that define individual smartcard properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

smartcard_devices

list / elements=dictionary

Configure multiple smartcard devices for the guest.

sound

dictionary

Attach a virtual audio device to the guest.

The dictionary contains key/value pairs that define individual sound device properties.

Common properties include model (e.g. ich6, ich9, ac97).

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

sound_devices

list / elements=dictionary

Configure multiple sound devices for the guest.

state

string

If set to present, create the VM if it does not exist.

Choices:

• "present" ← (default)
• "absent"

sysinfo

dictionary

Configure sysinfo/SMBIOS values exposed to the VM OS.

The dictionary contains key/value pairs that define individual sysinfo entries.

Use virt-install --sysinfo=? to see a list of all available sub options.

tpm

dictionary

Configure a virtual TPM (Trusted Platform Module) device.

The dictionary contains key/value pairs that define individual TPM properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

tpm_devices

list / elements=dictionary

Configure multiple TPM devices for the guest.

uri

string

Libvirt connection uri.

Default: "qemu:///system"

url_password

string

The password for HTTP basic authentication.

Only used when base_image is a URL.

url_timeout

integer

The timeout in seconds for downloading the base image from a URL.

Only used when base_image is a URL.

Default: 60

url_username

string

The username for HTTP basic authentication.

Only used when base_image is a URL.

vcpus

integer

Number of virtual cpus to configure for the guest.

vcpus_opts

dictionary

Additional options for virtual CPU configuration.

clusters

integer

number of clusters per die

cores

integer

Number of cores per cluster

cpuset

string

A comma-separated list of physical CPU numbers that domain process and virtual CPUs can be pinned to by default.

current

integer

Specify whether fewer than the maximum number of virtual CPUs should be enabled.

dies

integer

Number of dies per socket

maxvcpus

integer

If specified, the guest will be able to hotplug up to MAX vcpus while the guest is running.

placement

string

Indicate the CPU placement mode for domain process

Choices:

• "static"
• "auto"

sockets

integer

Total number of CPU sockets

threads

integer

Number of threads per core

vcpu_specs

list / elements=dictionary

Configure individual vCPU properties.

Each dictionary entry contains a property name and its corresponding value.

video

dictionary

Specify what video device model will be attached to the guest.

The dictionary contains key/value pairs that define individual video device properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

video_devices

list / elements=dictionary

Configure multiple video devices for the guest.

virt_type

string

The hypervisor used to create the VM guest. Example choices are kvm, qemu, or xen.

vsock

dictionary

Configure a vsock host/guest interface.

The dictionary contains key/value pairs that define individual vsock properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

vsock_devices

list / elements=dictionary

Configure multiple vsock devices for the guest.

wait_for_cloud_init_reboot

boolean

If set to true, wait for cloud-init to trigger a reboot and for the VM to come back online.

This requires that your cloud-init user-data includes a reboot action, or cloud_init_auto_reboot=true.

Only applicable when cloud_init configuration is provided.

Choices:

• false
• true ← (default)

watchdog

dictionary

Attach a virtual hardware watchdog device to the guest.

The dictionary contains key/value pairs that define individual watchdog properties.

You can use the special attribute value to specify a primary value that appears before other properties in the command line.

watchdog_devices

list / elements=dictionary

Configure multiple watchdog devices for the guest.

check_mode

Support: full

Supports check_mode.

base_image_path

string

Path to the base cloud image file.

This is the local path where the image was downloaded to (if URL was provided) or the original local path.

Returned: success

Sample: "/srv/cloud-images/ubuntu-20.04-server-cloudimg-amd64.img"

commands

list / elements=string

added in community.libvirt 2.2.0

List of commands executed by this module during VM provisioning.

Includes qemu-img commands for disk preparation and the virt-install command to create the VM.

Only populated when a VM is created or recreated (state=present and VM did not already exist, or recreate=true).

In check mode, the virt-install command includes the --dry-run flag.

Returned: when a VM was created or recreated

Sample: ["qemu-img resize /var/lib/libvirt/images/test.qcow2 20G", "virt-install --name test-vm --memory 2048 --vcpus 2 --import --disk path=/var/lib/libvirt/images/test.qcow2"]