Prev Next

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

Version 7.5 — Dec 11, 2024

Edit Print

Prev Next