# 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

##

Type: array
No Additional Items

#### Tuple Validation

##### Parameter 1: vm_device_create

#### vm_device_create

Type: object

VMDeviceCreateArgs parameters.

No Additional Properties

##

#### Attributes

Device-specific configuration attributes.

## One of

#### VMCDROMDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for CD-ROM/DVD devices.

Specific value: `"CDROM"`

##

#### Path

Type: string

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

Type: const

Device type identifier for display/graphics devices.

Specific value: `"DISPLAY"`

##

#### 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

Default: null

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

## Any of

Type: integer

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

Type: null

##

#### Web Port

Default: null

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

## Any of

Type: integer
Type: null

##

#### Bind

Type: string Default: "127.0.0.1"

IP address to bind the display server to.

Must be at least `1` characters long

##

#### Wait

Type: boolean Default: false

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

##

#### Password

Default: null

Password for display server authentication.

## Any of

Type: string
Type: null

##

#### Web

Type: boolean Default: true

Whether to enable web-based display access.

##

#### Type

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

Display protocol type.

##### Must be one of:

- "SPICE"
- "VNC"

#### VMNICDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for network interface cards.

Specific value: `"NIC"`

##

#### Trust Guest Rx Filters

Type: boolean Default: false

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

##

#### 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

Default: null

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

## Any of

Type: string
Type: null

##

#### Mac

Default: null

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

## Any of

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

Type: const

Device type identifier for PCI passthrough devices.

Specific value: `"PCI"`

##

#### 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

Type: const

Device type identifier for raw disk devices.

Specific value: `"RAW"`

##

#### Path

Type: string

Filesystem path to the raw disk device or image file.

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

Must be at least `1` characters long

##

#### Type

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

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

##### Must be one of:

- "AHCI"
- "VIRTIO"

##

#### Exists

Type: boolean Default: false

Whether the disk file already exists or should be created.

##

#### Boot

Type: boolean Default: false

Whether this disk should be marked as bootable.

##

#### Size

Default: null

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

## Any of

Type: integer
Type: null

##

#### Logical Sectorsize

Default: null

Logical sector size for the disk. `null` for default.

## Any of

Type: enum (of integer or null)

##### Must be one of:

- null
- 512
- 4096

Type: null

##

#### Physical Sectorsize

Default: null

Physical sector size for the disk. `null` for default.

## Any of

Type: enum (of integer or null)

##### Must be one of:

- null
- 512
- 4096

Type: null

##

#### Iotype

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

I/O backend type for disk operations.

##### Must be one of:

- "NATIVE"
- "THREADS"
- "IO_URING"

##

#### Serial

Default: null

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

## Any of

Type: string

Must be at least `1` characters long

Type: null

#### VMDiskDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for virtual disk devices.

Specific value: `"DISK"`

##

#### Path

Default: null

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

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### 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

Type: boolean Default: false

Whether to create a new ZFS volume for this disk.

##

#### Zvol Name

Default: null

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

## Any of

Type: string
Type: null

##

#### Zvol Volsize

Default: null

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

## Any of

Type: integer
Type: null

##

#### Logical Sectorsize

Default: null

Logical sector size for the disk. `null` for default.

## Any of

Type: enum (of integer or null)

##### Must be one of:

- null
- 512
- 4096

Type: null

##

#### Physical Sectorsize

Default: null

Physical sector size for the disk. `null` for default.

## Any of

Type: enum (of integer or null)

##### Must be one of:

- null
- 512
- 4096

Type: null

##

#### Iotype

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

I/O backend type for disk operations.

##### Must be one of:

- "NATIVE"
- "THREADS"
- "IO_URING"

##

#### Serial

Default: null

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

## Any of

Type: string

Must be at least `1` characters long

Type: null

#### VMUSBDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for USB devices.

Specific value: `"USB"`

##

Default: null

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

## Any of

#### USBAttributes

Type: object
No Additional Properties

##

#### Vendor Id

Type: string

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

Type: string

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

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

Default: null

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

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Vm

Type: integer

ID of the virtual machine this device belongs to.

##

#### Order

Default: null

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

## Any of

Type: integer
Type: null

##

#### VMDeviceEntry

Type: object

The newly created VM device configuration.

No Additional Properties

##

#### Id

Type: integer

Unique identifier for the VM device.

##

#### Attributes

Device-specific configuration attributes.

## One of

#### VMCDROMDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for CD-ROM/DVD devices.

Specific value: `"CDROM"`

##

#### Path

Type: string

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

Type: const

Device type identifier for display/graphics devices.

Specific value: `"DISPLAY"`

##

#### 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

Default: null

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

## Any of

Type: integer

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

Type: null

##

#### Web Port

Default: null

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

## Any of

Type: integer
Type: null

##

#### Bind

Type: string Default: "127.0.0.1"

IP address to bind the display server to.

Must be at least `1` characters long

##

#### Wait

Type: boolean Default: false

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

##

#### Password

Default: null

Password for display server authentication.

## Any of

Type: string
Type: null

##

#### Web

Type: boolean Default: true

Whether to enable web-based display access.

##

#### Type

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

Display protocol type.

##### Must be one of:

- "SPICE"
- "VNC"

#### VMNICDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for network interface cards.

Specific value: `"NIC"`

##

#### Trust Guest Rx Filters

Type: boolean Default: false

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

##

#### 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

Default: null

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

## Any of

Type: string
Type: null

##

#### Mac

Default: null

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

## Any of

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

Type: const

Device type identifier for PCI passthrough devices.

Specific value: `"PCI"`

##

#### 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

Type: const

Device type identifier for raw disk devices.

Specific value: `"RAW"`

##

#### Path

Type: string

Filesystem path to the raw disk device or image file.

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

Must be at least `1` characters long

##

#### Type

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

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

##### Must be one of:

- "AHCI"
- "VIRTIO"

##

#### Exists

Type: boolean Default: false

Whether the disk file already exists or should be created.

##

#### Boot

Type: boolean Default: false

Whether this disk should be marked as bootable.

##

#### Size

Default: null

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

## Any of

Type: integer
Type: null

##

#### Logical Sectorsize

Default: null

Logical sector size for the disk. `null` for default.

## Any of

Type: enum (of integer or null)

##### Must be one of:

- null
- 512
- 4096

Type: null

##

#### Physical Sectorsize

Default: null

Physical sector size for the disk. `null` for default.

## Any of

Type: enum (of integer or null)

##### Must be one of:

- null
- 512
- 4096

Type: null

##

#### Iotype

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

I/O backend type for disk operations.

##### Must be one of:

- "NATIVE"
- "THREADS"
- "IO_URING"

##

#### Serial

Default: null

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

## Any of

Type: string

Must be at least `1` characters long

Type: null

#### VMDiskDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for virtual disk devices.

Specific value: `"DISK"`

##

#### Path

Default: null

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

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### 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

Type: boolean Default: false

Whether to create a new ZFS volume for this disk.

##

#### Zvol Name

Default: null

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

## Any of

Type: string
Type: null

##

#### Zvol Volsize

Default: null

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

## Any of

Type: integer
Type: null

##

#### Logical Sectorsize

Default: null

Logical sector size for the disk. `null` for default.

## Any of

Type: enum (of integer or null)

##### Must be one of:

- null
- 512
- 4096

Type: null

##

#### Physical Sectorsize

Default: null

Physical sector size for the disk. `null` for default.

## Any of

Type: enum (of integer or null)

##### Must be one of:

- null
- 512
- 4096

Type: null

##

#### Iotype

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

I/O backend type for disk operations.

##### Must be one of:

- "NATIVE"
- "THREADS"
- "IO_URING"

##

#### Serial

Default: null

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

## Any of

Type: string

Must be at least `1` characters long

Type: null

#### VMUSBDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for USB devices.

Specific value: `"USB"`

##

Default: null

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

## Any of

#### USBAttributes

Type: object
No Additional Properties

##

#### Vendor Id

Type: string

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

Type: string

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

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

Default: null

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

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Vm

Type: integer

ID of the virtual machine this device belongs to.

##

#### Order

Type: integer

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

Required roles: VM_DEVICE_WRITE