.. _VM prlctl:

prlctl
------

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

.. _General Syntax:

General Syntax
~~~~~~~~~~~~~~

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

.. _VM prlctl capture:

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

.. _VM prlctl clone:

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

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| 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 tools must be installed in the virtual machine.                                        |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--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.                               |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _VM prlctl create:

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. The best way to find out the default versions used in your Virtuozzo installation is by creating a sample virtual machine.

.. _VM prlctl delete:

prlctl delete
~~~~~~~~~~~~~

Deletes a virtual machine from the hardware node. The command removes a virtual machine from the Virtuozzo 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.                                                                |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _prlctl installtools:

prlctl installtools
~~~~~~~~~~~~~~~~~~~

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

::

    prlctl installtools <VM_name>

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<VM_name>``                       | The name of the virtual machine.                                                                          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _prlctl update-qemu:

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

.. _prlctl enter:

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

.. _prlctl exec:

prlctl exec
~~~~~~~~~~~

Executes a command inside a virtual machine. Virtuozzo 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.                                                  |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _VM prlctl list:

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 :ref:`VM 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.                                                       |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _VM prlctl list Output Parameters:

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 processes and 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.        |
+------------------------------+------------------------------+--------------------------------------------------------------------------------------+

.. _VM prlctl migrate:

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

.. _VM prlctl mount, umount:

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

.. _VM prlctl move:

prlctl move
~~~~~~~~~~~

Moves the directory with virtual machine files to a new location on the same server. The virtual machine must be stopped or suspended.

::

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

.. _prlctl pause, suspend, resume:

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.

.. _VM prlctl problem-report:

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

.. _VM prlctl register, unregister:

prlctl register, unregister
~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

The ``unregister`` command removes a virtual machine from the Virtuozzo 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 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. 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 registry, but does not delete the virtual machine files from the server. You can re-register such a machine with Virtuozzo later using the ``register`` command.

.. _prlctl reset-uptime:

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

.. _VM prlctl set:

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.

.. _Modifying Virtual Machine Configuration:

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>] [--distribution _<name>] [--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.                                                 |
+------------------------------------------------------------------------+------------------------------------------------------------------------+
| ``--distribution <name>``                                              | Optimize the virtual machine for use with  the  operating  system      |
|                                                                        | ``<name>``. You can get the list of available distributions using the  |
|                                                                        | ``prlctl set <VM_name> -d list`` command.                              |
+------------------------------------------------------------------------+------------------------------------------------------------------------+
| ``--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 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 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 |
|                                                                        |    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 component responsible for    |
|                                                                        |    managing virtual machines.                                          |
|                                                                        |                                                                        |
|                                                                        | -  ``suspend`` - the virtual machine is suspended when the hardware    |
|                                                                        |    node is shut down or the Virtuozzo component responsible for        |
|                                                                        |    managing virtual machines is disabled.                              |
+------------------------------------------------------------------------+------------------------------------------------------------------------+
| ``--applyconfig <conf>``                                               | Applies the resource parameter values from the specified VM sample     |
|                                                                        | file in ``/etc/parallels/samples`` 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 tools   |
|                                                                        | must be installed in the virtual machine 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 update of Virtuozzo guest tools in       |
|                                                                        | virtual machines. If set to ``on``, Virtuozzo tools are updated        |
|                                                                        | automatically via a weekly ``cron`` job (requires that the             |
|                                                                        | ``vz-guest-tools-updater`` package be installed on the node).          |
|                                                                        |                                                                        |
|                                                                        | .. warning:: During the update, Virtuozzo 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 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.                        |
|                                                                        |                                                                        |
|                                                                        | .. warning:: This feature is experimental and tested only on Linux     |
|                                                                        |    guests.                                                             |
|                                                                        |                                                                        |
+------------------------------------------------------------------------+------------------------------------------------------------------------+

.. _Managing Virtual Devices:

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>           | Adds a virtual device of the type <dev_type> to a virtual machine. The ``<dev_type>`` parameter can be:   |
| <options>``                         | ``hdd``, ``cdrom``, ``net``, ``fdd``, ``serial``, ``usb``, ``pci``. Except for SCSI and VirtIO hard       |
|                                     | disks, devices can only be added to stopped virtual machines.                                             |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--device-set <dev_name>           | Modifies the configuration of the virtual device <dev_name> in a stopped virtual machine.                 |
| <options>``                         |                                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--device-del <dev_name>           | Deletes the virtual device <dev_name> from a stopped virtual machine.                                     |
| <options>``                         |                                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--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                | Specifies the boot order for a virtual machine.                                                           |
| "dev_name1 dev_name2 [...]"``       |                                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

    .. 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>] [--type <expanded|plain>] [--size <size>]
               [--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 image file that will be used to emulate the virtual disk.                                    |
|                                     |                                                                                                           |
|                                     | -  If the specified image does not exist, it is created and used to emulate the virtual hard disk.        |
|                                     |                                                                                                           |
|                                     | -  If the specified image exists, it is used to emulate the virtual hard disk.                            |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--device <dev_name>``             | This option is used to connect a physical hard disk on the hardware node to the virtual machine. You can  |
|                                     | obtain the names of the existing hard disks on the server using the ``prlsrvctl info`` command.           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--size <size>``                   | The size of the virtual hard disk, in megabytes. The default size is 65536 MB.                            |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--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 the virtual machine.                                                               |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--device-set cdrom<N>``           | Modifies the parameters of an existing virtual optical disk. The ``<N>`` postfix indicates the drive      |
|                                     | index number. To obtain the list of the available drives, use the ``prlctl list`` command with the        |
|                                     | ``--info`` option.                                                                                        |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--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 the virtual machine.                                                |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--device-set net<N>``             | Modifies an existing virtual network adapter. To obtain the list of the available adapters, use the       |
|                                     | ``prlctl list`` command with the ``--info`` option.                                                       |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--type routed``                   | Sets the networking mode for the virtual network adapter to "routed". In this mode, the network adapter   |
|                                     | is communicating with the outside world through an internal virtual network adapter.                      |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--network <network_ID>``          | Sets the networking mode for the virtual network adapter to "virtual_network". In this mode the adapter   |
|                                     | is connected to a virtual network specified by ``<network_ID>``.                                          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--mac {<addr>|auto}``             | Specifies the MAC address to assign to an existing network adapter. Specify a desired MAC address using   |
|                                     | the ``addr`` parameter value or use the ``auto`` option to generate the existing address automatically.   |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--ipadd <addr>[/<mask>]``         | Adds an IP address and a mask (optional) to the network adapter.                                          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--ipdel <addr>[/<mask>]``         | Deletes an IP address from the network adapter.                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--dhcp <yes|no>``                 | Specifies whether the virtual network adapter should obtain the IPv4 settings through a DHCP server.      |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--dhcp6 <yes|no>``                | Specifies whether the virtual network adapter should obtain the IPv6 settings through a DHCP server .     |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--gw <gw>``                       | The default gateway to be used by the virtual machine.                                                    |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--gw6 <gw>``                      | The default IPv6 gateway to be used by the virtual machine.                                               |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--nameserver <addr>``             | The default DNS server address to be used by the virtual machine.                                         |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--searchdomain <addr>``           | The default search domain to be used by the virtual machine.                                              |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--configure <yes|no>``            | If set to ``yes``, the settings above are applied to the virtual network adapter instead of its original  |
|                                     | settings. Configuring any of the settings above automatically sets this option to ``yes``.                |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--ipfilter <yes|no>``             | Determines if the specified network adapter is configured to filter network packages by IP address. If    |
|                                     | set  to ``yes``, the adapter is allowed to send packages only from IPs in the network adapter IP          |
|                                     | addresses list.                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--macfilter <yes|no>``            | Determines if the specified network adapter is configured to filter network packages by MAC address. If   |
|                                     | set to ``yes``, the adapter is allowed to send packages only from its own MAC address.                    |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--preventpromisc <yes|no>``       | Determines if  the  specified  network adapter should reject packages not addressed to its virtual        |
|                                     | machine. If set to ``yes``, the adapter will drop such packages.                                          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--enable|--disable``              | Enables or disable the network adapter. If omitted during the adapter creation, the adapter will be       |
|                                     | enabled.                                                                                                  |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--connect|--disconnect``          | Connects or disconnects the network adapter. When disconnected, the adapter is not removed from the       |
|                                     | virtual machine.                                                                                          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--adapter-type                    | Emulated network adapter:                                                                                 |
| <e1000|rtl|virtio>``                |                                                                                                           |
|                                     | -  ``e1000`` - Intel 82545EM,                                                                             |
|                                     |                                                                                                           |
|                                     | -  ``rtl`` - Realtek RTL8029,                                                                             |
|                                     |                                                                                                           |
|                                     | -  ``virtio`` - VirtIO.                                                                                   |
|                                     |                                                                                                           |
|                                     |    .. note:: The adapter requires no additional configuration on supported Linux and FreeBSD guest        |
|                                     |        operating systems. However, additional drivers need to be installed on Windows Server 2012 R2      |
|                                     |        guest OSes. For the drivers, visit https://alt.fedoraproject.org/pub/alt/virtio-win/latest/. The   |
|                                     |        VirtIO adapter is not supported on the Windows Server 2008 guest operating systems.                |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

**Floppy Disk Drive Management Options**

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

::

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

**USB Controller Management Options**

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

::

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

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

**Removing Devices from Virtual Machines**

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

::

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

.. _VM prlctl snapshot, snapshot-list, snapshot-switch, snapshot-delete:

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

.. _prlctl start, stop, restart, reset, status:

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 tools are installed in a virtual machine, the graceful shutdown will be performed using its facilities.

-  If Virtuozzo 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).

.. _VM prlctl statistics:

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 filesystem index).                                     | 
+------------------------+-----------------------------------------------------------------------------------------------------------+

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 filesystems statistics** 
 
- ``guest.fs<N>.name`` - Device name as seen from inside the guest filesystem 
 
- ``guest.fs<N>.total`` - Total size of the filesystem, in bytes
 
- ``guest.fs<N>.free`` - Amount of free space on the filesystem, in bytes
 
- ``guest.fs<N>.disk.<N>`` - Disk indices 

