4.1. Virtual Machine Utilities

Virtuozzo virtual machines can be managed using the prlctl command-line utility. The utility is installed on the hardware node during the product installation.

4.1.1. prlctl

The prlctl utility is used to perform administration tasks on virtual machines. The utility supports a full range of tasks from creating and administering virtual machines to getting statistics and generating problem reports.

prlctl <command> <VM_name> [<options>] [-v, --verbose <number>] [--timeout <sec>]
       [-l, --login [<user>[:_<passwd>_]@]<server>] [-p, --read-passwd <file>]]

Name

Description

<command>

The name of the command to execute.

<VM_name>

The name of the virtual machine to perform the operation on. To obtain the list of the available virtual machines, use the prlctl list command.

<options>

Command options. See individual commands for available options.

-v, --verbose <number>

Enables verbose output. The greater the <number>, the higher the verbosity.

--timeout <sec>

Use a custom operation timeout specified in seconds. The default timeout for all operations is unlimited.

-l, --login [<user>[:<passwd>]@]<server>

Connect to a remote <server> with the specified credentials. If this flag is omitted, the prlctl command is assumed to be run locally.

-p, --read-passwd <file>

Use the password from the file <file> to log in to a remote hardware node, other credentials being specified with the --login option. The --read-passwd option can be specified multiple times in order to form a password stack for operations requiring multiple passwords. Each password must be supplied in a separate file.

To display help, enter prlctl without any options.

4.1.2. prlctl backup, backup-list, backup-delete, restore

Creates, lists, deletes or restores virtual machine backups.

prlctl backup <VM_name|VM_UUID> [-f, --full] [-i, --incremental]
              [-s, --storage [<user>[:<passwd>]@]<server>[:<port>]]
              [--description <desc>] [--no-compression] [--no-tunnel]
              [--no-reversed-delta]
prlctl backup-list [<VM_name|VM_UUID>] [-f, --full] [--localvms] [--vmtype vm]
                   [-s, --storage [<user>[:<passwd>]@]<server>[:<port>]]
prlctl backup-delete {<VM_name|VM_UUID> | -t, --tag <backup_ID>} [--keep-chain]
prlctl restore {<VM_UUID> | -t, --tag <backup_ID>} [-n, --name <new_name>]
               [--dst=<path>] [-s, --storage [<user>[:<passwd>]@]<server>[:<port>]]
               [--no-tunnel] [--live]

Name

Description

<VM_name|VM_UUID>

Virtual machine name or UUID.

  • Use with prlctl backup to create a backup of the specified virtual machine.

  • Use with prlctl backup-list to list backups of the specified virtual machine.

  • Use with prlctl backup-delete to delete all backups of the specified virtual machine.

  • Use <VM_UUID> with prlctl restore to restore the most recent backup of the specified virtual machine.

-s, --storage [<user>[:<passwd>]@]<server>[:<port>]

Specifies a remote backup server address, port, and credentials. If this option is omitted, the backup will be saved on the default backup server that can be configured using the prlsrvctl set command.

--description <desc>

Backup description. Descriptions with white spaces must be enclosed in quotation marks.

-f, --full

  • Use with prlctl backup to create a full backup of the virtual machine. A full backup contains all virtual machine data.

  • Use with prlctl backup-list to display full backup information.

-i, --incremental

Create an incremental backup of the virtual machine. An incremental backup contains only the files changed since the previous full or incremental backup. This is the default backup type.

--localvms

List local backups only.

--vmtype vm

List virtual machine backups on the server.

-t, --tag <backup_ID>

The ID of the backup to restore or delete.

-n, --name <new_name>

A new name to assign to the restored virtual machine. If omitted, the virtual machine will be restored with the original name.

--dst=<path>

Restore the virtual machine to the specified directory on the hardware node. If this option is omitted, the virtual machine will be restored to /vz/vmprivate/<VM_UUID>.

--no-compression

Do not compress the created backup image.

--no-tunnel

Disables connection tunneling for backup. Connection tunneling provides secure data transmission.

To use this option, configure the firewall of the destination server to allow incoming connections on any port on the corresponding network interface.

--no-reversed-delta

Disables creating an intermediate temporary image for reversed delta writes during backup.

--keep-chain

Preserve the rest of the backup chain when deleting specific backups.

--live

Starts the restored virtual machine right after launching the restore process to reduce the VM downtime.

4.1.3. prlctl capture

Captures a screenshot of a current virtual machine console in the Portable Network Graphics (PNG) format.

prlctl capture <VM_name> [--file <path>]

Name

Description

<VM_name>

Name of the virtual machine to take a screenshot of.

--file <path>

If the --file option is specified, a screenshot is stored to the path <path>; otherwise, it is dumped to stdout.

4.1.4. prlctl clone

Creates an exact copy or a template of the specified virtual machine.

Note

Running VMs cannot be cloned. Templates of running VMs can still be created.

prlctl clone <VM_name> --name <new_name> [--template] [--dst=<path>] [--changesid]
             [--detach-external-hdd <yes|no>] [--linked]

Name

Description

<VM_name>

Name of the virtual machine to clone.

--name <new_name>

Name to be assigned to the new virtual machine.

--template

Create a virtual machine template instead of a real virtual machine. Templates are used as a basis for creating new virtual machines.

--dst=<path>

Path to the directory where the <VM_UUID> directory with cloned VM files will be stored. If this option is omitted, the clone is created in the default directory /vz/vmprivate.

--changesid

Generate a new Windows security identifier (SID) for a Windows-based virtual machine. For this parameter to work, Virtuozzo Hybrid Server tools must be installed in the virtual machine.

Note

For Windows 2019 VMs, use Microsoft’s Sysprep tool instead of this option.

--detach-external-hdd <yes|no>

If set to no, hard disks located outside the source virtual machine are not removed from the configuration of the resulting clone. Setting the parameter to yes removes external hard disks from the configuration.

Note

External hard disks are not copied to the cloned virtual machine.

--linked

Create a linked clone of the virtual machine. Linked clones store only changes to virtual machine disks. They occupy less disk space but require access to the original disks.

Note

Migration, backup, restore, and unlink operations are not supported for linked clones.

4.1.5. prlctl create

Creates a new virtual machine. A virtual machine can be created from scratch or from a virtual machine template. When created from scratch, the target operating system type or version must be specified. To create a virtual machine from a template, the template name must be passed to the command.

prlctl create <VM_name> [<options>]

Name

Description

<VM_name>

User-defined new virtual machine name. If the name consists of two or more words separated by spaces, it must be enclosed in quotes.

-d, --distribution {<name>|list}

The operating system distribution the virtual machine will be optimized for. For the full list of supported distributions, refer to the prlctl man pages.

--ostemplate <template_name>

The name of the virtual machine template from which to create the new virtual machine. Use the prlctl list --template command to obtain the list of the available templates.

--dst <vm_path>

Path to the directory where the <VM_UUID> directory with VM files will be stored. If this parameter is omitted, the virtual machine is placed in the default directory /vz/vmprivate.

--uuid <uuid>

A custom UUID to assign to the virtual machine.

Note

You can use either --distribution or --ostemplate, not both options at once.

When creating a virtual machine from scratch, you may specify the operating system family or version. If an operating system version is specified using the --distribution parameter, the virtual machine will be configured for that operating system. If an operating system family is specified using the --ostype parameter, the virtual machine will be configured for the default version of this OS family. The default versions are determined internally by Virtuozzo Hybrid Server. The best way to find out the default versions used in your Virtuozzo Hybrid Server installation is by creating a sample virtual machine.

4.1.6. prlctl delete

Deletes a virtual machine from the hardware node. The command removes a virtual machine from the Virtuozzo Hybrid Server registry and permanently deletes all its files from the server. Once completed, this operation cannot be reversed.

prlctl delete <VM_name>

Name

Description

<VM_name>

The name of the virtual machine to delete.

4.1.7. prlctl installtools

Mounts the Virtuozzo guest tools image to virtual machine’s optical disk drive so the user can install Virtuozzo Hybrid Server tools.

prlctl installtools <VM_name>

Name

Description

<VM_name>

The name of the virtual machine.

4.1.8. prlctl update-qemu

Updates KVM/QEMU hypervisor in a running virtual machine from the qemu-kvm-vz package installed on the node. Make sure to update the qemu-kvm-vz package first.

prlctl update-qemu <VM_name>

Name

Description

<VM_name>

The name of the virtual machine.

4.1.9. prlctl enter

Creates a command prompt channel to a virtual machine. By using this command, you can create a command prompt channel and execute commands in a virtual machine. Virtuozzo Hybrid Server tools must be installed in a virtual machine to use this utility.

prlctl enter <VM_name>

Name

Description

<VM_name>

The name of the virtual machine.

4.1.10. prlctl exec

Executes a command inside a virtual machine. Virtuozzo Hybrid Server tools must be installed in a virtual machine to use this utility. By default, running prlctl exec <command> is equivalent to executing bash -c <command> in a Linux VM or cmd /c <command> in a Windows VM.

prlctl exec <VM_name> [--without-shell] <command>

Name

Description

<VM_name>

The name of the virtual machine.

<command>

A command to execute.

--without-shell

Run commands directly without bash or cmd shell.

4.1.11. prlctl list

Displays a list of virtual machines on the Hardware Node. Displays information on virtual machines on the Hardware Node.

prlctl list --vmtype vm [-a, --all] [-o, --output <field>[,...]]
            [-s, --sort {<field>|-<field>}] [-t, --template] [-j, --json]
prlctl list -i, --info --vmtype vm [<VM_name>] [-f, --full] [-t, --template]
                                   [-j, --json]

Name

Description

-a, --all

List all running, stopped, suspended, and paused virtual machines. If this and the rest of the parameters are omitted, only the running virtual machines will be displayed.

-t, --template

List available virtual machine templates instead of actual virtual machines.

-o, --output <field>[,....]

Display only the specified fields. Type field names in lower case. Separate multiple fields with commas. For the list of fields, see prlctl list Output Parameters.

-s, --sort {<field>|-<field>}

Sort virtual machines by the specified field in either ascending or descending order.

-i, --info

Display detailed information about the specified virtual machine.

-f, --full

Display detailed information about network cards in virtual machines. Used with the --info option.

<VM_name>

The name of the virtual machine for which to display the detailed information. If not specified, the information will be displayed for all registered virtual machines.

-j, -json

Produce machine-readable output in the JSON format.

4.1.11.1. prlctl list Output Parameters

Listed below are the parameters that can be specified after the -o switch.

Name

Output Column

Description

uuid

UUID

Virtual machine UUID.

hostname

HOSTNAME

Virtual machine hostname.

name

NAME

Virtual machine name.

description

DESCRIPTION

Virtual machine description.

ostemplate

OSTEMPLATE

Specifies the name of the OS template the virtual machine is based on (e.g., centos-6-x86_64).

ip

IP_ADDR

Virtual machine IP address.

status

STATUS

Virtual machine status (e.g., running or stopped).

numproc

NPROC

The number of threads allowed.

mac

MAC

Network device’s MAC address.

netif

NETIF

Network devices in the virtual machine .

iolimit

IOLIMIT

The bandwidth the virtual machine is allowed to use for its disk input and output (I/O) operations, in bytes per second.

ha_enable

HA_ENABLE

Indicates whether the virtual machine is joined to the High Availability Cluster.

ha_prio

HA_PRIO

Virtual machine priority in the High Availability Cluster (0 is the lowest). Higher-priority virtual environments are restarted first in case of failures.

4.1.12. prlctl migrate

Migrates a virtual machine from one server to another.

prlctl migrate <VM_name> <destination_server>[/<VM_name>]
               [--dst=<path>] [--clone|--remove-src] [--changesid] [--no-compression]
               [--no-tunnel] [--ssh <options>]

Name

Description

<VM_name>

The source virtual machine name.

<source_server>

The source server information. Use the following format to specify this info: [<user>[:<password>]@]<server_IP_address_or_hostname>[:<port>].

<destination_server>

The destination server information. If omitted, the migration will be performed locally. Use the following format to specify this info: [<user>[:<password>]@]<server_IP_address_or_hostname>[:<port>].

--dst=<path>

Path to the directory on the destination server where the <VM_UUID> directory with VM files will be stored.

--clone

Clone the original virtual machine to the destination server and leave it intact on the source server. The clone will have a different UUID, MAC address, SID (for Windows-based VMs only; if --changesid is specified), and offline management disabled. If this option is omitted, the original virtual machine will be removed from the source server after migration. Cannot be used together with --remove-src.

--remove-src

Remove the original virtual machine from the source server. Enabled by default. Cannot be used together with --clone.

--changesid

Changes the resulting virtual machine SID.

Note

For Windows 2019 VMs, use Microsoft’s Sysprep tool instead of this option.

--no-compression

Disable data compression during migration.

--no-tunnel

Disables connection tunneling for migration. Connection tunneling provides secure data transmission. The option works only for VM live migration.

To use this option, configure the firewall of the destination server to allow incoming connections on any port on the corresponding network interface.

--ssh

Additional options to pass to ssh to connect to the destination server. All standard ssh options are supported.

Note

Do not specify the destination server hostname or IP address as an ssh option.

4.1.13. prlctl mount, umount

Mounts or unmounts the hard disks of a virtual machine to the /vz/root/<UUID> directory on the hardware node.

prlctl mount <VM_name> [-o <ro|rw> | --info]
prlctl umount <VM_name>

Name

Description

<VM_name>

Virtual machine name.

-o <ro|rw>

Sets access rights:

  • ro - read-only,

  • rw - read-write.

--info

Show information about the mounted virtual disks.

4.1.14. prlctl move

Moves the directory with virtual machine files to a new location on the same server.

prlctl move <VM_name> --dst=<path>

Name

Description

<VM_name>

Virtual machine name.

--dst=<path>

New location of the <VM_UUID> directory with virtual machine files.

4.1.15. prlctl pause, suspend, resume

Pause, suspend, and resume a virtual machine.

prlctl pause <VM_name>
prlctl suspend <VM_name>
prlctl resume <VM_name>

Name

Description

<VM_name>

The name of the virtual machine to pause, suspend, or resume.

The pause command pauses a virtual machine. To continue the virtual machine operation, use the prlctl start command.

The suspend command suspends the virtual machine operation. When a running virtual machine is suspended, the state of the virtual machine processes is saved to a file on the host. After that, the machine is stopped. To resume the machine, use the resume command.

4.1.16. prlctl problem-report

Obtains a problem report for the specified virtual machine and either sends it to the Virtuozzo technical support team or displays it on the screen.

prlctl problem-report <VM_name> -d, --dump | -s, --send \
                      [--proxy [<user>[:<passwd>]@]<proxyhost>[:<port>] | --no-proxy]

Name

Description

<VM_name>

The name of the virtual machine for which to obtain the problem report. If the name consists of separate words, it must be enclosed in quotes.

-d, --dump

Collect technical data about a virtual machine and display it on the screen. You can also pipe the output to a file and then send it to the Virtuozzo technical support team to analyze your problem.

-s, --send

Send the generated problem report to the Virtuozzo technical support team.

--proxy [<user>[:<passwd>]@<proxyhost>[:<port>]

Use the specified information to send the generated report through a proxy server, if you use one to connect to the Internet.

--no-proxy

Do not use a proxy server to send the generated report. This is the default behavior, so you can omit this parameter.

4.1.17. prlctl register, unregister

The register command is used to register a virtual machine with Virtuozzo Hybrid Server.

The unregister command removes a virtual machine from the Virtuozzo Hybrid Server registry.

prlctl register <path> [--preserve-uuid | --uuid <UUID>]
prlctl unregister <VM_name>

Name

Description

<path>

An absolute path to the virtual machine directory.

<VM_name>

The name of the virtual machine to remove from the Virtuozzo Hybrid Server registry.

--preserve-uuid

Do not change the virtual machine UUID. If ommited, the UUID is regenerated.

--uuid <UUID>

Change the virtual machine UUID to the specified one. If ommited, the UUID is regenerated.

Use the register command when you have a virtual machine on the server that does not show up in the list of the virtual machines registered with the Virtuozzo Hybrid Server. This can be a machine that was previously removed from the registry or a machine that was copied from another location.

The unregister command removes a virtual machine from the Virtuozzo Hybrid Server registry, but does not delete the virtual machine files from the server. You can re-register such a machine with Virtuozzo Hybrid Server later using the register command.

4.1.18. prlctl reset-uptime

Resets a virtual machine uptime counter as well as count start date and time.

prlctl reset-uptime <VM_name>

Name

Description

<VM_name>

Virtual machine name. Names consisting of multiple words must be enclosed in quotes.

4.1.19. prlctl set

The prlctl set command is used to modify the configuration of a virtual machine and manage virtual machine devices. The following subsections provide technical information on how to use the command to perform these tasks.

4.1.19.1. Modifying Virtual Machine Configuration

The prlctl set command is used to modify the virtual machine configuration parameters.

prlctl set <VM_name> [--cpus <number>] [--cpu-sockets <number>] [--memsize <number>]
           [--videosize <number>] [--memguarantee <percentage>]
           [--mem-hotplug <on|off>] [--description <desc>]
           [--autostart <on|off|auto>] [--autostart-delay <number>]
           [--autostop <stop|suspend>] [--applyconfig <conf>] [--name <new_name>]
           [--vnc-mode <auto|manual|off> {--vnc-passwd <passwd> | --vnc-nopasswd}]
           [--vnc-port <port>] [--vnc-address <address>] [--cpu-hotplug <on|off>]
           [--cpuunits <units>] [--cpulimit {<percent>|<megahertz>}]
           [--ioprio <priority>] [--iolimit <limit>] [--iopslimit <limit>]
           [--cpumask {<N>[,N,N1-N2] | all}] [--nodemask {<N>[,N,N1-N2] | all}]
           [--offline-management <on|off>] [--offline-service <service_name>]
           [--userpasswd <user>:<passwd>] [--rate <rate>]
           [--ratebound <on|off>_] [--apply-iponly <yes|no>] [--efi-boot <on|off>]
           [--tools-autoupdate <on|off>] [--on-crash <pause|restart>[:no-report]]
           [--nested-virt <on|off>]

Name

Description

<VM_name>

Target virtual machine name.

--cpus <number>

Number of CPU cores per CPU socket available to the virtual machine. The overall number of CPU cores available to a virtual machine is calculated by multiplying the number of CPU sockets by the number of CPU cores per socket and can be no greater than the number of CPU cores on the physical server. The default value is 2.

--cpu-sockets <number>

Number of CPU sockets available to the virtual machine. The default value is 1.

--memsize <number>

The amount of memory (RAM) available to the virtual machine, in megabytes. You can use the following suffixes to specify measurement units:

  • G for gigabytes

  • M for megabytes

  • K for kilobytes

  • B for bytes

--videosize <number>

The amount of video memory available to the virtual machine graphics card. You can use the following suffixes to specify measurement units:

  • G for gigabytes

  • M for megabytes

  • K for kilobytes

  • B for bytes

--memguarantee <size>

Sets a percentage of virtual machine’s RAM that said VM is guaranteed to have. By default, set to 80%.

--mem-hotplug <on|off>

Enables or disables memory (RAM) hotplug support in the virtual machine. This feature is disabled in the virtual machine by default. The guest operating system must support memory hotplug for this functionality to work.

--description <desc>

Sets virtual machine description. Descriptions with white spaces must be enclosed in quotation marks.

--autostart <on|off|auto>

Sets the virtual machine startup options:

  • on - automatically start the virtual machine when the hardware node starts or the Virtuozzo Hybrid Server component responsible for managing virtual machines is enabled.

  • off (default) - do not automatically start the virtual machine when the hardware node starts or the Virtuozzo Hybrid Server component responsible for managing virtual machines is enabled.

  • auto - let the virtual machine assume the state it has been in before the hardware node reboot/shutdown or disabling the Virtuozzo Hybrid Server component responsible for managing virtual machines.

--autostart-delay <number>

Sets the time delay used during the virtual machine automatic startup.

--autostop <stop|suspend>

Sets the automatic shutdown mode for the specified virtual machine:

  • stop - the virtual machine is stopped when you shut down the hardware node or disable the Virtuozzo Hybrid Server component responsible for managing virtual machines.

  • suspend - the virtual machine is suspended when the hardware node is shut down or the Virtuozzo Hybrid Server component responsible for managing virtual machines is disabled.

--applyconfig <conf>

Applies the resource parameter values from the specified VM configuration file to the virtual machine. The following parameters are applied:

  • all memory-related parameters (both RAM and video)

  • all CPU-related parameters

  • IO and IOPS limits

  • disk size

--name <new_name>

Changes the virtual machine name. You can only change the names of stopped virtual machines.

--vnc-mode <auto|manual|off>

Enables or disables access to the virtual machine via the VNC protocol.

--vnc-port <port>

Sets the VNC port number.

--vnc-passwd <passwd> | --vnc-nopasswd

Sets the VNC password or specifies that no password is needed for VNC connections. Either of these options is mandatory for any VNC connection.

--vnc-address <address>

Sets the IP address to use for logging in to the virtual machine via VNC. It must be one of the IP addresses assigned to the hardware node. By default, you can use any of the IP addresses of the hardware node to log in to the virtual machine.

--cpu-hotplug <on|off>

Enables or disables CPU hotplug support in the virtual machine. This feature is disabled by default. The guest operating system must support CPU hotplug for this functionality to work.

--cpuunits <units>

Sets the CPU weight for the virtual machine. This is a positive integer number that defines how much CPU time the virtual machine can get as compared to the other virtual machines and containers running on the server. The larger the number, the more CPU time the virtual machine can receive. Possible values range from 8 to 500000. If this parameter is not set, the default value of 1000 is used.

--cpulimit {<percent>|<megahertz>}

CPU limit, in percent or megahertz (MHz) the virtual machine is not allowed to exceed.  By default, the limit is set in percent. To set the limit in MHz, specify “m” after the value.

Note

If the server has 2 processors, the total CPU time equals 200%.

--ioprio <priority>

Disk I/O priority level from 0 to 7. The default is 4.

--iolimit <limit>

Disk I/O bandwidth limit. The default is 0 (no limit). By default the limit is set in megabytes per second. You can use the following letters following the number to specify units of measure:

  • G - gigabytes per second (e.g., 1G).

  • K - kilobytes per second (e.g., 10K).

  • B - bytes per second (e.g., 100B).

The default I/O bandwidth limit for all newly created virtual machines is set to 0, which means that no limits are applied to them.

--iopslimit <limit>

Maximum number of disk input and output operations per second a virtual machine is allowed to perform. By default, any newly created container does not have the IOPS limit set and can perform so many disk I/O operations per second as necessary.

--cpumask {<N>[,N,N1-N2] | all}

An affinity mask indicating what CPU(s) the virtual machine processes should be run on. You can specify a list of CPUs identified by their index numbers separated by commas (0, 1, 2, 3, etc.) or a range (4-6). To make all CPUs available for the virtual machine processes specify --cpumask all.

--nodemask {<N>[,N,N1-N2] | all}

The NUMA node mask defining a NUMA node to bind the virtual machine to. Once you set the mask, the processes running in the virtual machine will be executed only on the CPUs that belong to the specified NUMA node. You can specify a list of NUMA nodes by their index numbers separated by commas and as a range (e.g., 0,1,2,3,4-6). To make all NUMA nodes available for virtual machine’s processes specify --nodemask all.

--offline-management <on|off>

Turns the offline management on or off.

--offline-service <service_name>

The name of the service to use for offline management.

--userpasswd <user>:<passwd>

Sets the password for the specified user in the virtual machine. If the user account does not exist, it will be created. Virtuozzo Hybrid Server tools must be installed in the VM for the command to work.

--rate <rate>

Sets the guaranteed outgoing traffic rate in Kbps for the virtual machine.

--ratebound <on|off>

Turns the network traffic rate limitation set by the --rate parameter (above) on or off. The default value is off.

--apply-iponly <yes|no>

If set to yes, the hostname, nameserver, and search domain settings from the virtual machine configuration file are ignored.

--efi-boot <on|off>

If set to on, the virtual machine will boot using the EFI firmware. If set to off (default), the virtual machine will boot using the BIOS firmware.

--tools-autoupdate <on|off>

Enables or disables automatic install and update of Virtuozzo Hybrid Server guest tools in VMs. If set to on, Virtuozzo Hybrid Server tools are installed and updated automatically via a weekly cron job (requires that the vz-guest-tools-updater package be installed on the node).

Important

During the installation or update, Virtuozzo Hybrid Server guest tools image is forcibly mounted to VM’s optical disk drive even if it is already in use.

If set to off, Virtuozzo guest tools are not installed and updated automatically, so that you can do it manually at a convenient time.

--on-crash <pause|restart>[:no-report]

Specifies VM behavior after it crashes: pause or restart. The problem report is sent by default. To omit sending the problem report, add :no-report.

--nested-virt <on|off>

Enables nested Intel VT-x virtualization in VM.

Important

This feature is experimental and tested only on Linux guests.

4.1.19.2. Managing Virtual Devices

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

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 [...]"

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. <dev_type> can be: hdd, cdrom, net, fdd, serial, usb, pci. SCSI and VirtIO hard disks, network interfaces, and USB devices can be added to both running and stopped VMs, while other device types can only be added to stopped VMs.

--device-set <dev_name> <options>

Modifies the configuration of the virtual device <dev_name> in a virtual machine.

--device-del <dev_name> <options>

Deletes the virtual device <dev_name> from a 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

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.

prlctl set <VM_name> {--device-add hdd | --device-set hdd<N>}
           [--image <file> [--recreate]] [--size <size>] [--no-fs-resize]
           [--iface <ide|scsi|virtio>] [--subtype <virtio-scsi|hyperv>]
           [--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}

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 existing image file that will be used to emulate the virtual disk. To recreate the image file, add the --recreate option.

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

--no-fs-resize

Used with --size. Do not resize the last partition on the hard disk during online resize.

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

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

Sets disk drive interface type. If omitted, the SCSI interface will be used.

--subtype <virtio-scsi|hyperv>

Sets paravirtualized SCSI controller type. If omitted, VirtIO SCSI will be used. Hyper-V is recommended for Windows virtual machines as it allows to use native hard disk drivers.

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

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

Name

Description

<VM_name>

Virtual machine name.

--device-add cdrom

Adds a DVD/CD drive to a stopped 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.

--image <file>

Mounts the specified disk image file 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.

--device <dev_name>

This option is used to connect a physical optical disk on the hardware node to the virtual machine. You can obtain the names of the existing optical disks on the server using the prlsrvctl info command.

--iface <ide|scsi>

Sets disk interface type:

  • ide - IDE disk.

  • scsi - SCSI disk (default).

--subtype <virtio-scsi|hyperv>

Sets paravirtualized SCSI controller type. If omitted, VirtIO SCSI will be used. Hyper-V is recommended for Windows virtual machines as it allows to use native optical disk drivers.

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

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

Name

Description

<VM_name>

Virtual machine name.

--device-add net

Adds a new virtual network adapter to a running or stopped 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

    The VirtIO adapter is not supported on the Windows Server 2008 guest operating system.

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.

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

Name

Description

<VM_name>

Virtual machine name.

--device-add fdd

Adds a new floppy disk drive to a stopped virtual machine.

--device-set fdd0

Modifies the parameters of the existing virtual floppy disk drive.

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

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

Name

Description

<VM_name>

Virtual machine name.

--device-add serial

Adds a new serial port to a stopped 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.

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

Name

Description

<VM_name>

Virtual machine name.

--device-add usb

Add a USB device to a running or stopped virtual machine.

--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. USB devices, optical and floppy disk drives can be removed from both running and stopped VMs while hard disk drives, network interfaces, and serial ports can only be removed from stopped VMs.

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

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.

4.1.20. prlctl snapshot, snapshot-list, snapshot-switch, snapshot-delete

Takes, displays, reverts to, and deletes snapshots of a running virtual machine.

prlctl snapshot <VM_name> [-n, --name <name>] [-d, --description <desc>]
prlctl snapshot-list <VM_name> [-t, --tree] [-i, --id <snapshot_ID>]
prlctl snapshot-switch <VM_name> -i, --id <snapshot_ID>
prlctl snapshot-delete <VM_name> -i, --id <snapshot_ID> [-c,--children]

Name

Description

<VM_name>

Virtual machine name.

-n, --name <name>

User-defined snapshot name. Names with white spaces must be enclosed in quotation marks.

-d, --description <desc>

User-defined snapshot description. Descriptions with white spaces must be enclosed in quotation marks.

-t, --tree

Displays the snapshot list as a tree. The default display format is tabular with Parent Snapshot ID and Snapshot ID as columns.

-i, --id <snapshot_ID>

  • Use with prlctl snapshot-list to specify the ID of the snapshot to use as the root. If this parameter is omitted, the entire snapshot tree will be displayed.

  • Use with prlctl snapshot-switch to specify the ID of the snapshot to revert to.

  • Use with prlctl snapshot-delete to specify the ID of the snapshot to delete.

-c,--children

If the snapshot you want to delete has children snapshots derived from it, they will be deleted. If the option is omitted, they become the children of the deleted snapshot parent.

4.1.21. prlctl start, stop, restart, reset, status

Start, stop, reset, and check the status of a virtual machine.

prlctl start <VM_name>
prlctl stop <VM_name> [--kill]
prlctl restart <VM_name>
prlctl reset <VM_name>
prlctl status <VM_name>

Name

Description

<VM_name>

The name of the virtual machine to start, stop, restart, reset, or check the status of.

--kill

Perform a hard virtual machine shutdown. If this option is omitted, an attempt to perform a graceful shutdown will be made.

The stop command can perform a hard or a graceful virtual machine shutdown. If the --kill parameter is included, the hard shutdown will be performed. If the parameter is omitted, the outcome of the graceful shutdown attempt will depend on the following:

  • If Virtuozzo Hybrid Server tools are installed in a virtual machine, the graceful shutdown will be performed using its facilities.

  • If Virtuozzo Hybrid Server tools are not installed, the command will try to perform a graceful shutdown using ACPI. Depending on the ACPI support availability in the guest operating system, this may work or not.

The restart command first gracefully shuts down a virtual machine and then starts it again.

The reset command resets a virtual machine without shutting it down.

Note

Resetting a VM may result in loss of unsaved data stored in that VM.

The start command can be used to start a stopped virtual machine or to resume a paused virtual machine).

4.1.22. prlctl statistics

Print statistics for running virtual machines on the server.

prlctl statistics {<VM_UUID_or_name>|-a, --all} [--loop] [--filter <filter>]

Name

Description

-a, --all

Print statistics for all virtual machines and containers on the server.

--loop

Print statistics every second until the program is terminated.

--filter <pattern>

Specifies the subset of performance statistics to collect and print. If omitted, all available statistics is shown. Asterisks (*) can be used as wildcards for any number of arbitrary characters. The available filters are listed below (<N> is the device or file system index).

4.1.22.1. Available Filters

Storage device statistics

  • devices.{ide|scsi|sata}<N>.read_requests - Total count of read requests to IDE, SCSI, or SATA controller

  • devices.{ide|scsi|sata}<N>.read_total - Total count of read bytes for IDE, SCSI, or SATA controller

  • devices.{ide|scsi|sata}<N>.write_requests - Total count of write requests to IDE, SCSI, or SATA controller

  • devices.{ide|scsi|sata}<N>.write_total - Total count of written bytes for IDE, SCSI, or SATA controller

Network statistics

  • net.nic<N>.pkts_in - Total number of incoming packets for network adapter

  • net.nic<N>.pkts_out - Total number of outgoing packets for network adapter

  • net.nic<N>.bytes_in - Total number of incoming bytes for network adapter

  • net.nic<N>.bytes_out - Total number of outgoing bytes for network adapter

Classful network statistics

The result is provided in five columns: Class, Input(bytes), Input(packets), Output(bytes), Output(packets).

  • net.classful.traffic - Total counters for IPv4 and IPv6 traffic

  • net.classful.traffic.ipv4 - Counters for IPv4 traffic

  • net.classful.traffic.ipv6 - Counters for IPv6 traffic

CPU statistics

  • guest.cpu.usage - Guest OS CPU usage, in percent

  • guest.cpu.time - Sum of guest CPU time differences since the last query for each vCPU averaged by the number of host CPUs, in microseconds

  • host.cpu.time - Sum of host CPU time differences since the last query for each vCPU averaged by the number of host CPUs, in microseconds

  • guest.vcpu<N>.time - per-vCPU statistics, in nanoseconds

RAM statistics

  • guest.ram.usage - Guest OS used RAM, in MiB

  • guest.ram.cached - Guest OS cached RAM, in MiB

  • guest.ram.total - Guest OS total RAM, in MiB

  • guest.ram.swap_in - Guest OS virtual memory stats, in counts

  • guest.ram.swap_out - Guest OS virtual memory stats, in counts

  • guest.ram.minor_fault - Guest OS minor page fault count

  • guest.ram.major_fault - Guest OS major page fault count

  • guest.ram.balloon_actual - Guest OS balloon size, in MiB

Mounted file systems statistics

  • guest.fs<N>.name - Device name as seen from inside the guest file system

  • guest.fs<N>.total - Total size of the file system, in bytes

  • guest.fs<N>.free - Amount of free space on the file system, in bytes

  • guest.fs<N>.disk.<N> - Disk indices