vm.device.create

Create a new device for the VM of id vm.

If attributes.dtype is the RAW type and a new raw file is to be created, attributes.exists will be passed as false. This means the API handles creating the raw file and raises the appropriate exception if file creation fails.

If attributes.dtype is of DISK type and a new Zvol is to be created, attributes.create_zvol will be passed as true with valid attributes.zvol_name and attributes.zvol_volsize values.

Type: object

Call parameters

Type: array
No Additional Items

Tuple Validation

Parameter 1: vm_device_create

vm_device_create

Type: object

VMDeviceCreateArgs parameters.

No Additional Properties

attributes Required

Attributes

Device-specific configuration attributes.

One of

• VMCDROMDevice
• VMDisplayDevice
• VMNICDevice
• VMPCIDevice
• VMRAWDevice
• VMDiskDevice
• VMUSBDevice

VMCDROMDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for CD-ROM/DVD devices.

Must be one of:

• "CDROM"

Specific value: "CDROM"

path

Path

Type: string Default: "*"

Path must not contain "{", "}" characters, and it should start with "/mnt/".

Must match regular expression: ^[^{}]*$

Must be at least 1 characters long

VMDisplayDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for display/graphics devices.

Must be one of:

• "DISPLAY"

Specific value: "DISPLAY"

resolution

Resolution

Type: enum (of string) Default: "1024x768"

Screen resolution for the virtual display.

Must be one of:

• "1920x1200"
• "1920x1080"
• "1600x1200"
• "1600x900"
• "1400x1050"
• "1280x1024"
• "1280x720"
• "1024x768"
• "800x600"
• "640x480"

port

Port

Default: null

VNC/SPICE port number for remote display access. null for auto-assignment.

Any of

• Option 1
• Option 2

Type: integer

Value must be greater or equal to 5900 and lesser or equal to 65535

Type: null

web_port

Web Port

Default: null

Web-based display access port number. null for auto-assignment.

Any of

• Option 1
• Option 2

Type: integer

Type: null

bind

Bind

Type: string Default: "127.0.0.1"

IP address to bind the display server to.

Must be at least 1 characters long

wait

Wait

Type: boolean Default: false

Whether to wait for a client connection before starting the VM.

password

Password

Default: null

Password for display server authentication.

Any of

• Option 1
• Option 2

Type: string

Type: null

web

Web

Type: boolean Default: true

Whether to enable web-based display access.

type

Type

Type: enum (of string) Default: "SPICE"

Display protocol type.

Must be one of:

• "SPICE"
• "VNC"

VMNICDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for network interface cards.

Must be one of:

• "NIC"

Specific value: "NIC"

trust_guest_rx_filters

Trust Guest Rx Filters

Type: boolean Default: false

Whether to trust guest OS receive filter settings for better performance.

type

Type

Type: enum (of string) Default: "E1000"

Network interface controller type. E1000 for Intel compatibility, VIRTIO for performance.

Must be one of:

• "E1000"
• "VIRTIO"

nic_attach

Nic Attach

Default: null

Host network interface or bridge to attach to. null for no attachment.

Any of

• Option 1
• Option 2

Type: string

Type: null

mac

Mac

Default: null

MAC address for the virtual network interface. null for auto-generation.

Any of

• Option 1
• Option 2

Type: string
Must match regular expression: ^([0-9A-Fa-f]{2}[:-]?){5}([0-9A-Fa-f]{2})$

Type: null

VMPCIDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for PCI passthrough devices.

Must be one of:

• "PCI"

Specific value: "PCI"

pptdev Required

Pptdev

Type: string

Host PCI device identifier to pass through to the VM.

Must be at least 1 characters long

VMRAWDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for raw disk devices.

Must be one of:

• "RAW"

Specific value: "RAW"

path

Path

Type: string Default: "127.0.0.1"

Path must not contain "{", "}" characters.

Must match regular expression: ^[^{}]*$

Must be at least 1 characters long

type

Type

Type: enum (of string) Default: "AHCI"

Disk controller interface type. AHCI for compatibility, VIRTIO for performance.

Must be one of:

• "AHCI"
• "VIRTIO"

exists

Exists

Type: boolean Default: false

Whether the disk file already exists or should be created.

boot

Boot

Type: boolean Default: false

Whether this disk should be marked as bootable.

size

Size

Default: null

Size of the disk in bytes. Required if creating a new disk file.

Any of

• Option 1
• Option 2

Type: integer

Type: null

logical_sectorsize

Logical Sectorsize

Default: null

Logical sector size for the disk. null for default.

Any of

• Option 1
• Option 2

Type: enum (of integer or null)

Must be one of:

• null
• 512
• 4096

Type: null

physical_sectorsize

Physical Sectorsize

Default: null

Physical sector size for the disk. null for default.

Any of

• Option 1
• Option 2

Type: enum (of integer or null)

Must be one of:

• null
• 512
• 4096

Type: null

iotype

Iotype

Type: enum (of string) Default: "THREADS"

I/O backend type for disk operations.

Must be one of:

• "NATIVE"
• "THREADS"
• "IO_URING"

serial

Serial

Default: null

Serial number to assign to the virtual disk. null for auto-generated.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

VMDiskDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for virtual disk devices.

Must be one of:

• "DISK"

Specific value: "DISK"

path

Path

Default: null

Path to existing disk file or ZFS volume. null if creating a new ZFS volume.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

type

Type

Type: enum (of string) Default: "AHCI"

Disk controller interface type. AHCI for compatibility, VIRTIO for performance.

Must be one of:

• "AHCI"
• "VIRTIO"

create_zvol

Create Zvol

Type: boolean Default: false

Whether to create a new ZFS volume for this disk.

zvol_name

Zvol Name

Default: null

Name for the new ZFS volume. Required if create_zvol is true.

Any of

• Option 1
• Option 2

Type: string

Type: null

zvol_volsize

Zvol Volsize

Default: null

Size of the new ZFS volume in bytes. Required if create_zvol is true.

Any of

• Option 1
• Option 2

Type: integer

Type: null

logical_sectorsize

Logical Sectorsize

Default: null

Logical sector size for the disk. null for default.

Any of

• Option 1
• Option 2

Type: enum (of integer or null)

Must be one of:

• null
• 512
• 4096

Type: null

physical_sectorsize

Physical Sectorsize

Default: null

Physical sector size for the disk. null for default.

Any of

• Option 1
• Option 2

Type: enum (of integer or null)

Must be one of:

• null
• 512
• 4096

Type: null

iotype

Iotype

Type: enum (of string) Default: "THREADS"

I/O backend type for disk operations.

Must be one of:

• "NATIVE"
• "THREADS"
• "IO_URING"

serial

Serial

Default: null

Serial number to assign to the virtual disk. null for auto-generated.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

VMUSBDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for USB devices.

Must be one of:

• "USB"

Specific value: "USB"

usb

Default: null

USB device attributes for identification. null for USB host controller only.

Any of

• USBAttributes
• Option 2

USBAttributes

Type: object
No Additional Properties

vendor_id

Vendor Id

Type: string Default: "127.0.0.1"

USB vendor identifier in hexadecimal format (e.g., '0x1d6b' for Linux Foundation).

Must match regular expression: ^0x.*

Must be at least 1 characters long

product_id

Product Id

Type: string Default: "127.0.0.1"

USB product identifier in hexadecimal format (e.g., '0x0002' for 2.0 root hub).

Must match regular expression: ^0x.*

Must be at least 1 characters long

Type: null

controller_type

Controller Type

Type: enum (of string) Default: "nec-xhci"

USB controller type for the virtual machine.

Must be one of:

• "piix3-uhci"
• "piix4-uhci"
• "ehci"
• "ich9-ehci1"
• "vt82c686b-uhci"
• "pci-ohci"
• "nec-xhci"
• "qemu-xhci"

device

Device

Default: null

Host USB device path to pass through. null for controller only.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

vm Required

Vm

Type: integer

ID of the virtual machine this device belongs to.

order

Order

Default: null

Boot order priority for this device. null for automatic assignment.

Any of

• Option 1
• Option 2

Type: integer

Type: null

Return value

VMDeviceEntry

Type: object

The newly created VM device configuration.

No Additional Properties

id Required

Id

Type: integer

Unique identifier for the VM device.

attributes Required

Attributes

Device-specific configuration attributes.

One of

• VMCDROMDevice
• VMDisplayDevice
• VMNICDevice
• VMPCIDevice
• VMRAWDevice
• VMDiskDevice
• VMUSBDevice

VMCDROMDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for CD-ROM/DVD devices.

Must be one of:

• "CDROM"

Specific value: "CDROM"

path

Path

Type: string Default: "*"

Path must not contain "{", "}" characters, and it should start with "/mnt/".

Must match regular expression: ^[^{}]*$

Must be at least 1 characters long

VMDisplayDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for display/graphics devices.

Must be one of:

• "DISPLAY"

Specific value: "DISPLAY"

resolution

Resolution

Type: enum (of string) Default: "1024x768"

Screen resolution for the virtual display.

Must be one of:

• "1920x1200"
• "1920x1080"
• "1600x1200"
• "1600x900"
• "1400x1050"
• "1280x1024"
• "1280x720"
• "1024x768"
• "800x600"
• "640x480"

port

Port

Default: null

VNC/SPICE port number for remote display access. null for auto-assignment.

Any of

• Option 1
• Option 2

Type: integer

Value must be greater or equal to 5900 and lesser or equal to 65535

Type: null

web_port

Web Port

Default: null

Web-based display access port number. null for auto-assignment.

Any of

• Option 1
• Option 2

Type: integer

Type: null

bind

Bind

Type: string Default: "127.0.0.1"

IP address to bind the display server to.

Must be at least 1 characters long

wait

Wait

Type: boolean Default: false

Whether to wait for a client connection before starting the VM.

password

Password

Default: null

Password for display server authentication.

Any of

• Option 1
• Option 2

Type: string

Type: null

web

Web

Type: boolean Default: true

Whether to enable web-based display access.

type

Type

Type: enum (of string) Default: "SPICE"

Display protocol type.

Must be one of:

• "SPICE"
• "VNC"

VMNICDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for network interface cards.

Must be one of:

• "NIC"

Specific value: "NIC"

trust_guest_rx_filters

Trust Guest Rx Filters

Type: boolean Default: false

Whether to trust guest OS receive filter settings for better performance.

type

Type

Type: enum (of string) Default: "E1000"

Network interface controller type. E1000 for Intel compatibility, VIRTIO for performance.

Must be one of:

• "E1000"
• "VIRTIO"

nic_attach

Nic Attach

Default: null

Host network interface or bridge to attach to. null for no attachment.

Any of

• Option 1
• Option 2

Type: string

Type: null

mac

Mac

Default: null

MAC address for the virtual network interface. null for auto-generation.

Any of

• Option 1
• Option 2

Type: string
Must match regular expression: ^([0-9A-Fa-f]{2}[:-]?){5}([0-9A-Fa-f]{2})$

Type: null

VMPCIDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for PCI passthrough devices.

Must be one of:

• "PCI"

Specific value: "PCI"

pptdev Required

Pptdev

Type: string

Host PCI device identifier to pass through to the VM.

Must be at least 1 characters long

VMRAWDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for raw disk devices.

Must be one of:

• "RAW"

Specific value: "RAW"

path

Path

Type: string Default: "127.0.0.1"

Path must not contain "{", "}" characters.

Must match regular expression: ^[^{}]*$

Must be at least 1 characters long

type

Type

Type: enum (of string) Default: "AHCI"

Disk controller interface type. AHCI for compatibility, VIRTIO for performance.

Must be one of:

• "AHCI"
• "VIRTIO"

exists

Exists

Type: boolean Default: false

Whether the disk file already exists or should be created.

boot

Boot

Type: boolean Default: false

Whether this disk should be marked as bootable.

size

Size

Default: null

Size of the disk in bytes. Required if creating a new disk file.

Any of

• Option 1
• Option 2

Type: integer

Type: null

logical_sectorsize

Logical Sectorsize

Default: null

Logical sector size for the disk. null for default.

Any of

• Option 1
• Option 2

Type: enum (of integer or null)

Must be one of:

• null
• 512
• 4096

Type: null

physical_sectorsize

Physical Sectorsize

Default: null

Physical sector size for the disk. null for default.

Any of

• Option 1
• Option 2

Type: enum (of integer or null)

Must be one of:

• null
• 512
• 4096

Type: null

iotype

Iotype

Type: enum (of string) Default: "THREADS"

I/O backend type for disk operations.

Must be one of:

• "NATIVE"
• "THREADS"
• "IO_URING"

serial

Serial

Default: null

Serial number to assign to the virtual disk. null for auto-generated.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

VMDiskDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for virtual disk devices.

Must be one of:

• "DISK"

Specific value: "DISK"

path

Path

Default: null

Path to existing disk file or ZFS volume. null if creating a new ZFS volume.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

type

Type

Type: enum (of string) Default: "AHCI"

Disk controller interface type. AHCI for compatibility, VIRTIO for performance.

Must be one of:

• "AHCI"
• "VIRTIO"

create_zvol

Create Zvol

Type: boolean Default: false

Whether to create a new ZFS volume for this disk.

zvol_name

Zvol Name

Default: null

Name for the new ZFS volume. Required if create_zvol is true.

Any of

• Option 1
• Option 2

Type: string

Type: null

zvol_volsize

Zvol Volsize

Default: null

Size of the new ZFS volume in bytes. Required if create_zvol is true.

Any of

• Option 1
• Option 2

Type: integer

Type: null

logical_sectorsize

Logical Sectorsize

Default: null

Logical sector size for the disk. null for default.

Any of

• Option 1
• Option 2

Type: enum (of integer or null)

Must be one of:

• null
• 512
• 4096

Type: null

physical_sectorsize

Physical Sectorsize

Default: null

Physical sector size for the disk. null for default.

Any of

• Option 1
• Option 2

Type: enum (of integer or null)

Must be one of:

• null
• 512
• 4096

Type: null

iotype

Iotype

Type: enum (of string) Default: "THREADS"

I/O backend type for disk operations.

Must be one of:

• "NATIVE"
• "THREADS"
• "IO_URING"

serial

Serial

Default: null

Serial number to assign to the virtual disk. null for auto-generated.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

VMUSBDevice

Type: object
No Additional Properties

dtype Required

Dtype

Type: const

Device type identifier for USB devices.

Must be one of:

• "USB"

Specific value: "USB"

usb

Default: null

USB device attributes for identification. null for USB host controller only.

Any of

• USBAttributes
• Option 2

USBAttributes

Type: object
No Additional Properties

vendor_id

Vendor Id

Type: string Default: "127.0.0.1"

USB vendor identifier in hexadecimal format (e.g., '0x1d6b' for Linux Foundation).

Must match regular expression: ^0x.*

Must be at least 1 characters long

product_id

Product Id

Type: string Default: "127.0.0.1"

USB product identifier in hexadecimal format (e.g., '0x0002' for 2.0 root hub).

Must match regular expression: ^0x.*

Must be at least 1 characters long

Type: null

controller_type

Controller Type

Type: enum (of string) Default: "nec-xhci"

USB controller type for the virtual machine.

Must be one of:

• "piix3-uhci"
• "piix4-uhci"
• "ehci"
• "ich9-ehci1"
• "vt82c686b-uhci"
• "pci-ohci"
• "nec-xhci"
• "qemu-xhci"

device

Device

Default: null

Host USB device path to pass through. null for controller only.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

vm Required

Vm

Type: integer

ID of the virtual machine this device belongs to.

order Required

Order

Type: integer

Boot order priority for this device (lower numbers boot first).

Required roles: VM_DEVICE_WRITE