4.1.16.2. Managing Virtual Devices

The prlctl set command allows to add, modify, and delete virtual devices of virtual machines.

Syntax.

prlctl set <VM_name> --device-add <dev_type> <options>
prlctl set <VM_name> --device-set <dev_name> <options>
prlctl set <VM_name>  --device-del <dev_name> <options> --destroy-image-force
prlctl set <VM_name>  --device-connect <dev_name>
prlctl set <VM_name>  --device-disconnect <dev_name>
prlctl set <VM_name>  --device-bootorder "dev_name1 dev_name2 [...]"

Table 4.17. Options

Name	Description
`<VM_name>`	Virtual machine name.
`--device-add <dev_type> <options>`	Adds a virtual device of the type <dev_type> to a virtual machine. The `<dev_type>` parameter can be: `hdd`, `cdrom`, `net`, `fdd`, `serial`, `usb`, `pci`. Except for SCSI and VirtIO hard disks, devices can only be added to stopped virtual machines.
`--device-set <dev_name> <options>`	Modifies the configuration of the virtual device <dev_name> in a stopped virtual machine.
`--device-del <dev_name> <options>`	Deletes the virtual device <dev_name> from a stopped virtual machine.
`--destroy-image-force`	Used with the `--device-del` option. Deletes a virtual machine HDD even if it is used in that virtual machine’s snapshots.
`--device-connect <dev_name>`	Connects the virtual device <dev_name> to a running virtual machine.
`--device-disconnect +<dev_name>`	Disconnects the virtual device <dev_name> from a running virtual machine.
`--device-bootorder "dev_name1 dev_name2 [...]"`	Specifies the boot order for a virtual machine.

Note

Note: Device names can be obtained with the prlctl list -i command.

The device-related <options> can be subdivided into the following categories:

hard disk drives
optical disk drives
network cards
floppy disk drives
serial ports
USB devices

Each group of options is explained in the following subsections in detail.

Hard Disk Drive Management Options

This group of options is used to add and configure virtual hard disks in a virtual machine. The first syntax uses a file to emulate a hard disk drive. The second syntax connects a physical hard disk on the host server to the virtual machine.

Syntax.

prlctl set +<VM_name> {--device-add hdd | --device-set hdd<N>}
           [--image <file>] [--type <expanded|plain>] [--size <size>] [--split]
           [--iface <ide|scsi|virtio>] [--position <pos>] [--enable|--disable]
prlctl set <VM_name> --device-add hdd --device <dev_name> [--position <pos>]
           [--iface <ide|scsi|virtio>]
prlctl set <VM_name> --backup-add <backup_ID> [--disk <disk_name>]
           [--iface <ide|scsi|virtio>] [--position <pos>]
prlctl set <VM_name> --backup-del {<backup_ID>|all}

Table 4.18. Options

Name	Description
`<VM_name>`	Virtual machine name.
`--device-add hdd`	Adds a virtual hard disk to the VM. New hard disks are created in the virtual machine directory and are automatically named `harddisk<N>.hdd`, where `<N>` is the next available disk index. SCSI and VirtIO hard disks can be added to both running and stopped VMs, IDE disks can only be added to stopped VMs.
`--device-set hdd<N>`	Modifies the parameters of an existing virtual hard disk. Virtual hard disks are named using the `hdd<N>` format where `<N>` is the drive index number starting from 0 (e.g., `hdd0`, `hdd1`). To obtain the list of disk names, use the `prlctl list` command with the `--info` option.
`--image <file>`	Specifies an image file that will be used to emulate the virtual disk. If the specified image does not exist, it is created and used to emulate the virtual hard disk. If the specified image exists, it is used to emulate the virtual hard disk.
`--device <dev_name>`	This option is used to connect a physical hard disk on the hardware node to the virtual machine. You can obtain the names of the existing hard disks on the server using the `prlsrvctl info` command.
`--size <size>`	The size of the virtual hard disk, in megabytes. The default size is 65536 MB.
`--split`	Splits the hard disk image file into 2 GB pieces. You should split a virtual disk if it is stored on a file system that cannot support files larger than 2 GB (e.g., FAT16).
`--enable`	Enables the specified virtual disk drive. All newly added disk drives are enabled by default (provided the `--disable` option is omitted).
`--disable`	Disables the specified virtual disk drive. The disk drive itself is not removed from the virtual machine configuration.
`--backup-add <backup_ID>`	Attach the backup with the identifier <backup_ID> to the virtual machine as a virtual hard disk. To obtain the backup ID, use the `prlctl backup-list -f` command.
`--disk <disk_name>`	Used with `--backup-add`. The name of the disk in the backup to attach. If a disk is not specified, all disks contained in the backup will be attached. To obtain the disk name(s), use the `prlctl backup-list -f` command.
+--backup-del {<backup_ID>\|all}	Detach either the backup with the identifier <backup_ID> or detach all backups from the virtual machine.
`--iface <ide\|scsi\|virtio>`	The disk drive Interface type. If omitted, the SCSI interface will be used.
`--position <pos>`	The SCSI or IDE device identifier to be used for the virtual disk.

Optical Disk Drive Management Options

This group of options is used to add and configure virtual optical disk drives, such as DVD or CD drives.

Syntax.

prlctl set <VM_name> {--device-add cdrom | --device-set cdrom<N>}
           {--device <dev_name> | --image <file>} [--iface <ide|scsi>]
           [--position <pos>] [--enable|--disable] [--connect|--disconnect]

Table 4.19. Options

Name	Description
`<VM_name>`	Virtual machine name.
`--device-add cdrom`	Adds a DVD/CD drive to the virtual machine.
`--device-set cdrom<N>`	Modifies the parameters of an existing virtual optical disk. The `<N>` postfix indicates the drive index number. To obtain the list of the available drives, use the `prlctl list` command with the `--info` option.
`--device <dev_name>`	The name of the physical optical disk to connect to the virtual machine.
`--image <file>`	The name of an existing disk image file to mount in the virtual machine. Currently, the following image file formats are supported: `.iso`, `.cue`, `.ccd`, and `.dmg`. The image must not be compressed and/or encrypted.
`--iface <ide\|scsi>`	Interface type: `ide` - IDE disk. `scsi` - SCSI disk (default).
`--position <pos>`	The SCSI or IDE device identifier to be used for the DVD/CD drive. You can use one of the following formats for specifying IDs: `<ID>:_<bus>_`, `<ID>-<bus>`, `<ID>`. For example, if you specify `3:0` (or `3-0` or `3`) as `<number>` for a SCSI drive, the guest OS will see the drive as having ID 3 on SCSI bus 0.
`--enable`	Enables the specified DVD/CD drive. All newly added drives are enabled by default (provided the `--disable` option is omitted).
`--disable`	Disables the specified optical disk drive. The disk drive itself is not removed from the virtual machine configuration.
`--connect`	Automatically connect the specified optical disk drive during the virtual machine startup process.
`--disconnect`	Do not automatically connect the specified optical disk drive during the virtual machine startup process.

Network Adapter Management Options

This group of options is used to manage virtual network adapters in a virtual machine.

Syntax.

prlctl set <VM_name> {--device-add net | --device-set net<N>}
           {--type routed | --network <network_ID>} [--mac {<addr>|auto}]
           [{--ipadd <addr>[/<mask>] | --ipdel <addr>[/<mask>] | --dhcp <yes|no> |
           --dhcp6 <yes|no>}] [--gw <gw>] [--gw6 <gw>]
           [--nameserver <addr>] [--searchdomain <addr>]
           [--configure <yes|no>] [--ipfilter <yes|no>] [--macfilter <yes|no>]
           [--preventpromisc <yes|no>] [--enable|--disable]
           [--connect|--disconnect] [--adapter-type <e1000|rtl|virtio>]

Table 4.20. Options

Name	Description
`<VM_name>`	Virtual machine name.
`--device-add net`	Adds a new virtual network adapter to the virtual machine.
`--device-set net<N>`	Modifies an existing virtual network adapter. To obtain the list of the available adapters, use the `prlctl list` command with the `--info` option.
`--type routed`	Sets the networking mode for the virtual network adapter to "routed". In this mode, the network adapter is communicating with the outside world through an internal virtual network adapter.
`--network <network_ID>`	Sets the networking mode for the virtual network adapter to "virtual_network". In this mode the adapter is connected to a virtual network specified by `<network_ID>`.
`--mac {<addr>\|auto}`	Specifies the MAC address to assign to an existing network adapter. Specify a desired MAC address using the `addr` parameter value or use the `auto` option to generate the existing address automatically.
`--ipadd <addr>[/<mask>]`	Adds an IP address and a mask (optional) to the network adapter.
`--ipdel <addr>[/<mask>]`	Deletes an IP address from the network adapter.
`--dhcp <yes\|no>`	Specifies whether the virtual network adapter should obtain the IPv4 settings through a DHCP server.
`--dhcp6 <yes\|no>`	Specifies whether the virtual network adapter should obtain the IPv6 settings through a DHCP server .
`--gw <gw>`	The default gateway to be used by the virtual machine.
`--gw6 <gw>`	The default IPv6 gateway to be used by the virtual machine.
`--nameserver <addr>`	The default DNS server address to be used by the virtual machine.
`--searchdomain <addr>`	The default search domain to be used by the virtual machine.
`--configure <yes\|no>`	If set to `yes`, the settings above are applied to the virtual network adapter instead of its original settings. Configuring any of the settings above automatically sets this option to `yes`.
`--ipfilter <yes\|no>`	Determines if the specified network adapter is configured to filter network packages by IP address. If set to `yes`, the adapter is allowed to send packages only from IPs in the network adapter IP addresses list.
`--macfilter <yes\|no>`	Determines if the specified network adapter is configured to filter network packages by MAC address. If set to `yes`, the adapter is allowed to send packages only from its own MAC address.
`--preventpromisc <yes\|no>`	Determines if the specified network adapter should reject packages not addressed to its virtual machine. If set to `yes`, the adapter will drop such packages.
`--enable\|--disable`	Enables or disable the network adapter. If omitted during the adapter creation, the adapter will be enabled.
`--connect\|--disconnect`	Connects or disconnects the network adapter. When disconnected, the adapter is not removed from the virtual machine.
`--adapter-type <e1000\|rtl\|virtio>`	Emulated network adapter: `e1000` - Intel 82545EM, `rtl` - Realtek RTL8029, `virtio` - VirtIO. Note Note: The adapter requires no additional configuration on supported Linux and FreeBSD guest operating systems. However, additional drivers need to be installed on Windows Server 2012 R2 guest OSes. For the drivers, visit https://alt.fedoraproject.org/pub/alt/virtio-win/latest/. The VirtIO adapter is not supported on the Windows Server 2008 guest operating systems.

Floppy Disk Drive Management Options

This group of options is used to add a floppy disk drive to a virtual machine and to modify the existing virtual floppy disk drive.

Syntax.

prlctl set <VM_name> {--device-add fdd | --device-set fdd0}
           {--device <dev_name> | --image <file>}
           [--enable|--disable] [--connect|--disconnect]

Table 4.21. Options

Name	Description
`<VM_name>`	Virtual machine name.
`--device-add fdd`	Adds a new floppy disk drive to the virtual machine.
`--device-set fdd0`	Modifies the parameters of the existing virtual floppy disk drive.
`--device <dev_name>`	The name of the physical floppy disk drive to connect to the virtual machine. If this parameter is omitted, a floppy drive image emulating the floppy disk drive will be created.
`--image <file>`	The name and path of an existing floppy disk image file (usually `floppy.fdd`) to mount in the virtual machine.
`--enable`	Enables the specified floppy disk drive. All newly added floppy drives are enabled by default (provided the `--disable` option was omitted during the drive creation).
`--disable`	Disables the specified floppy disk drive. The drive itself is not removed from the virtual machine configuration.
`--connect`	Connect the specified floppy disk drive automatically during the virtual machine startup process.
`--disconnect`	Use this option if you don’t want the specified floppy disk drive automatically connected to the virtual machine on its start.

Serial Port Management Options

This group of options is used to manage serial ports in a virtual machine.

Syntax.

prlctl set <VM_name> {--device-add serial | --device-add serial<N>}
           {--device <dev_name> | --output <file> | --socket <name>}
           [--enable|--disable] [--connect|--disconnect]

Table 4.22. Options

Name	Description
`<VM_name>`	Virtual machine name.
`--device-add serial`	Adds a new serial port to the virtual machine.
`--device-set serial<N>`	Modifies the parameters of an existing serial port.
`--device <dev_name>`	The name of the physical serial port to which to connect the virtual machine.
`--output <file>`	The name and path of the output file to which to connect the virtual serial port.
`--socket <name>`	The name of the physical socket to which to connect the virtual serial port.
`--enable\|--disable`	Enables or disables the virtual serial port. All newly added serial ports are enabled by default (provided the `--disable` option is omitted).
`--connect`	Automatically connect the virtual serial port during the virtual machine startup process.
`--disconnect`	Do not automatically connect the virtual serial port during the virtual machine startup process.

USB Controller Management Options

This group of options is used to manage the USB controller in a virtual machine.

Syntax.

prlctl set <VM_name> --device-add usb [--enable|--disable]

Table 4.23. Options

Name	Description
`<VM_name>`	Virtual machine name.
`--device-add usb`	The type of the virtual device to add to the virtual machine (in this instance, a USB device).
`--enable\|--disable`	Enables or disables the USB controller. The controller is enabled by default (provided the `--disable` option is omitted).

Removing Devices from Virtual Machines

The --device-del option is used to remove virtual devices from a virtual machine.

Syntax.

prlctl set <VM_name> --device-del <dev_name> [--detach-only|--destroy-image]

Table 4.24. Options

Name	Description
`<dev_name>`	The name of the virtual device to delete from the virtual machine. To obtain the list of virtual devices, use the `prlctl list -i` command.
`--detach-only`	Deletes the information about the specified device from the virtual machine configuration.
`--destroy-image`	Deletes the information about the specified device from the virtual machine configuration and removes the device from the server.

Prev	Up	Next
	Home

OpenVZ Command Line Reference4.1.16. prlctl set

4.1.16.2. Managing Virtual Devices

Note

Note

OpenVZ Command Line Reference
4.1.16. prlctl set