.. _prlctl:

prlctl
------

``prlctl`` is the primary tool for container management. To use it, you have to log in to the server as the root user. The following sections describe ``prlctl`` subcommands.

::

    prlctl <subcommand> <CT_name>
    prlctl --version
    prlctl --help

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``--version``                       | Displays the ``prlctl`` package version currently installed on the server.                                |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--help``                          | Displays the usage information about ``prlctl``.                                                          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _prlctl clone:

prlctl clone
~~~~~~~~~~~~

Creates an exact copy of the specified container.

::

    prlctl clone <CT_name> --name <new_name> [--template] [--dst=<path>]

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<CT_name>``                       | Name of the container to clone.                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--name <new_name>``               | Name to be assigned to the new container.                                                                 |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--template``                      | Create a container template instead of a clone. Template cannot be started.                               |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--dst=<path>``                    | Path to the directory where the ``<CT_UUID>`` directory with cloned container private area will be        |
|                                     | stored. If this parameter is omitted, the clone is created in the default directory ``/vz/private``.      |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _prlctl console:

prlctl console
~~~~~~~~~~~~~~

Creates a command prompt channel to a container. Allows to log in to and execute commands in running containers as well as attach to stopped containers to get information on their startup from bootstrap programs (such as ``init``) for troubleshooting purposes. Logging in to containers requires a virtual terminal (e.g., mingetty) to be installed in the container.

.. note:: To exit the console, press **Esc** and then **.** (period).

::

    prlctl console <CT_name>

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<CT_name>``                       | Container name.                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _prlctl create:

prlctl create
~~~~~~~~~~~~~

This command is used to create new containers.

::

    prlctl create <CT_name> --vmtype ct [<options>]

With this command, you can create regular containers. A unique container name is required for this command.

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<CT_name>``                       | An arbitrary name to assign to the new container.                                                         |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--vmtype ct``                     | Tells the ``prlctl create`` command to make a container. If the option is omitted, a virtual machine is   |
|                                     | created instead.                                                                                          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--ostemplate <name>``             | OS EZ template to use for creating the container. If omitted, this value is taken from the                |
|                                     | ``DEF_OSTEMPLATE`` parameter in the global Virtuozzo configuration file.                                  |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--config <name>``                 | Container sample configuration file to use for creating the container. Sample configuration files are     |
|                                     | located in ``/etc/vz/conf`` and have names in the format ``ve-<name>.conf-sample``. The sample            |
|                                     | configuration files usually have a number of resource control limits for the container and some           |
|                                     | application templates to be added to the container immediately upon its creation. If you skip this option |
|                                     | and the default configuration file name is not specified in the global Virtuozzo configuration file, you  |
|                                     | will have to set resource control parameters for the container using the ``prlctl set`` command.          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--uuid <uuid>``                   | A custom UUID to assign to the container.                                                                 |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _prlctl delete:

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

Deletes a container from the server.

::

    prlctl delete <CT_name>

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<CT_name>``                       | Container name.                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

When executed, ``prlctl delete`` physically removes all the files located in the container private area (specified as the ``VE_PRIVATE`` variable in the container configuration file) and renames the container configuration file in ``/etc/vz/conf`` from ``<CT_name>.conf`` to ``<CT_name>.conf.destroyed``. It also renames container action scripts, if any, in a similar manner.

.. note:: A container must be stopped before its private area can be unmounted.

.. _prlctl exec, enter:

prlctl exec, enter
~~~~~~~~~~~~~~~~~~

Allow running arbitrary commands in a container.

::

    prlctl exec <CT_name> [--without-shell] <command>
    prlctl enter <CT_name>

where ``<command>`` is a string to be executed in the container. If ``<command>`` is specified as ``-``, then the commands for execution will be read from the standard input until the end of file or ``exit`` is encountered.

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<CT_name>``                       | Container name.                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--without-shell``                 | Run commands directly without ``bash`` or ``cmd`` shell.                                                  |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

When using ``prlctl exec``, remember that the shell parses the command-line and, if your command has shell metacharacters in it, you should escape or quote them.

The ``prlctl enter`` command is similar to ``prlctl exec /bin/bash``. The difference between the two is that ``prlctl enter`` makes the shell interpreter believe that it is connected to a terminal. As such, you receive a shell prompt and are able to execute multiple commands as if you were logged in to the container.

.. _prlctl migrate:

prlctl migrate
~~~~~~~~~~~~~~

Migrates a container from one server to another.

::

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

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<CT_name>``                       | The source container 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 ``<CT_UUID>`` directory with container private  |
|                                     | area will be stored.                                                                                      |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--clone``                         | Clone the original container to the destination server and leave it intact on the source server. The      |
|                                     | clone will have a different UUID, MAC address, and offline management disabled. If this option  is        |
|                                     | omitted, the original container will be removed from the source server after migration. Cannot be used    |
|                                     | together with ``--remove-src``.                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--remove-src``                    | Remove the original container from the source server. Cannot be used together with ``--clone``.           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--no-compression``                | Disable data compression during migration.                                                                |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--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.              |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _prlctl mount, umount:

prlctl mount, umount
~~~~~~~~~~~~~~~~~~~~

The ``prlctl mount`` command mounts the container private area to the container root directory (``/vz/root/<CT_name>`` on the server) without starting it. Normally, you do not have to use this command as the ``prlctl start`` command mounts the container private area automatically.

The ``prlctl umount`` command unmounts the container private area. Usually, there is no need in using this command either because ``prlctl stop`` unmounts the container private area automatically.

.. note:: These commands can trigger the execution of action scripts (see :ref:`Action Scripts`).

::

    prlctl mount  <CT_name>
    prlctl umount <CT_name>

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<CT_name>``                       | Container name.                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _prlctl move:

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

Moves the directory with container private area to a new location on the same server. The container can be stopped, suspended or running.

::

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

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<CT_name>``                       | Container name.                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--dst=<path>``                    | New location of the ``<CT_UUID>`` directory with container private area.                                  |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _prlctl problem-report:

prlctl problem-report
~~~~~~~~~~~~~~~~~~~~~

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

::

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

+-------------------------------------------------------------+----------------------------------------------------------------------------------+
| Name                                                        | Description                                                                      |
+=============================================================+==================================================================================+
| ``<CT_name>``                                               | The name of the container for which to generate the problem report.              |
+-------------------------------------------------------------+----------------------------------------------------------------------------------+
| ``-d, --dump``                                              | Collect technical data about the specified container 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.                                        |
+-------------------------------------------------------------+----------------------------------------------------------------------------------+

.. _prlctl register, unregister:

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

The ``register`` command is used to register a container with Virtuozzo.

The ``unregister`` command removes a container from the Virtuozzo registry.

::

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

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<path>``                          | Full path to the container directory.                                                                     |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``<CT_name>``                       | The name of the container to remove from the Virtuozzo registry.                                          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--preserve-uuid``                 | Do not change the container UUID. If ommited, the UUID is regenerated.                                    |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--uuid <UUID>``                   | Change the container UUID to the specified one. If ommited, the UUID is regenerated.                      |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

-  Use the ``register`` command when you have a container on the server that does not show up in the list of the containers registered with the Virtuozzo. This can be a container that was previously removed from the registry or that was copied from another location.

-  The ``unregister`` command removes a container from the Virtuozzo registry, but does not delete the container files from the server. You can re-register the container later using the ``register`` command.

.. _prlctl reinstall:

prlctl reinstall
~~~~~~~~~~~~~~~~

Recreates a container from scratch according to its configuration file. Copies old private area content to the ``/vz/root/<CT_name>/old`` directory.

::

    prlctl reinstall <CT_name> [--skipbackup] [--resetpwdb] [--scripts <script> [...]]
    prlctl reinstall <CT_name> [--listscripts] [--desc]

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<CT_name>``                       | Container name.                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--resetpwdb``                     | Removes container’s user database and creates a clean database as for any new installation.               |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--skipbackup``                    | Does not save the old private area contents to the ``/old`` directory.                                    |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--scripts <script>[…]``           | Specifies the scripts to be executed during reinstallation. These scripts are used to customize           |
|                                     | application templates in the new container and bring them to the same state as in the old container. By   |
|                                     | default, all available scripts are executed.                                                              |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--listscripts``                   | Lists the scripts to be executed during container reinstallation.                                         |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--desc``                          | Displays the description of the scripts to be executed during container reinstallation. Used together     |
|                                     | with the ``--listscripts`` option.                                                                        |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _prlctl set:

prlctl set
~~~~~~~~~~

This command is used for setting container parameters.

::

    prlctl set <CT_name> <option> <value>

where <CT_name> is container name.

The command options specified in this file can be subdivided into the following categories:

-  miscellaneous

-  networking

-  resource management

-  hard disk drive management

.. _General Options:

General Options
^^^^^^^^^^^^^^^

The table below lists the general options you can use with ``prlctl set``.

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``--autostart <on|off|auto>``       | Sets the container startup options:                                                                       |
|                                     |                                                                                                           |
|                                     | -  ``on`` - automatically start the container when the hardware node starts.                              |
|                                     |                                                                                                           |
|                                     | -  ``off`` (default) - do not automatically start the container when the hardware node starts.            |
|                                     |                                                                                                           |
|                                     | -  ``auto`` - let the container assume the state it has been in before the hardware node reboot/shutdown. |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--offline-management <yes|no>``   | Enabling/disabling the direct managing of the container through a common Internet browser by means of     |
|                                     | Power Panels and the Plesk control panel (as defined by the ``OFFLINE_SERVICE`` parameter in the global   |
|                                     | or container configuration file).                                                                         |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--offline-service <service_name>``| Defines whether the container can be managed by means of Power Panel or Plesk or both. Valid only if the  |
|                                     | ``OFFLINE_MANAGEMENT`` parameter is set to ``yes``. The names of the available services can be taken from |
|                                     | the file names (excluding the ``.conf`` extension) in the ``/etc/vzredirect.d`` directory on the server.  |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--userpasswd <user>:<password>``  | This setting creates a new user with the specified password in the container, or changes the password of  |
|                                     | an already existing user. This command modifies not the container configuration file, but the             |
|                                     | ``/etc/passwd`` and ``/etc/shadow`` files inside the container. In case the container root is not         |
|                                     | mounted, it is automatically mounted to apply the changes and then unmounted.                             |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--crypted``                       | Used with ``--userpasswd``. Indicates that the specified password is already a hash.                      |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--features {<name>:on|off}``      | Enables/disables the support for the following functionality inside the container:                        |
|                                     |                                                                                                           |
|                                     | -  ``nfs``: mounting NFS shares                                                                           |
|                                     |                                                                                                           |
|                                     | -  ``ipip``: creating IPIP tunnels                                                                        |
|                                     |                                                                                                           |
|                                     | -  ``sit``: using the Simple Internet Transition (SIT) mechanisms                                         |
|                                     |                                                                                                           |
|                                     | -  ``bridge``: using bridges to connect virtual Ethernet devices                                          |
|                                     |                                                                                                           |
|                                     | -  ``nfsd``: running an NFS-kernel-space server                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--name <new_name>``               | Changes the container name. You can change the names of both stopped and running containers.              |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--description <desc>``            | Custom container description. Descriptions must be alphanumeric. Descriptions with white spaces must be   |
|                                     | enclosed in quotation marks.                                                                              |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--vnc-mode <auto|manual|off>``    | Enables or disables access to the container via the VNC protocol.                                         |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--vnc-port <port>``               | Sets the VNC port number for the container. Used with ``--vnc-mode manual``.                              |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--vnc-passwd <passwd>``           | Sets the VNC password for the container or specifies that no password is needed for VNC connections.      |
| ``--vnc-nopasswd``                  | Either of these options is mandatory for any VNC setup.                                                   |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--autocompact <on|off>``          | Enables or disables compaction for all disks in the container.                                            |
|                                     |                                                                                                           |
|                                     | .. note:: For details on how to enable or disable compaction for a specific disk in the container,        |
|                                     |           see :ref:`Hard Disk Drive Management Options`.                                                  |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _Resource Management Options:

Resource Management Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Resource management options control the amount of resources a container may consume. If the setting has ``bar:lim`` after it than this setting requires specifying both barrier and limit values separated by colons.

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``--applyconfig <name>``            | This option lets you set the resource parameters for the container not one by one, but by reading them    |
|                                     | from the container sample configuration file. All container sample configuration files are located in the |
|                                     | ``/etc/vz/conf`` directory and are named according to the following pattern: ``ve-<name>.conf-sample``,   |
|                                     | so you should specify only the ``<name>`` part of the corresponding sample name after the                 |
|                                     | ``--applyconfig`` option. Note that the names of sample configuration files cannot contain spaces. The    |
|                                     | ``--applyconfig`` option applies all the parameters from the specified sample file to the given           |
|                                     | container, except for the ``OSTEMPLATE``, ``TEMPLATES``, ``VE_ROOT``, ``VE_PRIVATE``, ``HOSTNAME``,       |
|                                     | ``IP_ADDRESS``, ``TEMPLATE``, ``NETIF`` parameters (if they exist in the configuration sample file).      |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--cpuunits <units>``              | CPU weight. This is a positive integer number that defines how much CPU time the container can get as     |
|                                     | compared to the other virtual machines and containers running on the server. The larger the number, the   |
|                                     | more CPU time the container can receive. Possible values range from 8 to 500000. If this parameter is not |
|                                     | set, the default value of 1000 is used.                                                                   |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--cpulimit                        | CPU limit, in per cent or megahertz (MHz), the container is not allowed to exceed. This parameter is not  |
| {<percent>|<megahertz>}``           | set for newly created containers; so they can consume all free CPU power of the server. By default, the   |
|                                     | limit is set in percent. To set the limit in MHz, specify ``m`` after the value. When setting this        |
|                                     | parameter in per cent, keep in mind that one CPU core makes up 100%. So if the server has 4 CPU cores,    |
|                                     | the total CPU power will equal 400%.                                                                      |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--cpus <number>``                 | Number of CPU cores per CPU socket defining the CPU limit for a container. The limit is calculated by     |
|                                     | multiplying the power of one CPU core by the number of the specified CPU cores. This option also defines  |
|                                     | the number of CPUs shown to container users. This parameter is not set for newly created containers; so   |
|                                     | they can consume all free CPU power of the server.                                                        |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--cpumask <number>``              | CPU affinity mask. This mask defines the CPUs on the server that can be used to handle the processes      |
|                                     | running in the container. The CPU mask can be specified as both separate CPU index numbers (1,2,3) and    |
|                                     | CPU ranges (2-4,5-7).                                                                                     |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--nodemask {<number>|all}``       | The NUMA node mask defining a NUMA node to bind the container to. Once you set the mask, the processes    |
|                                     | running in the container 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 container's processes specify ``--nodemask all``.  |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--quotaugidlimit {<0|<N>}``       | Enables (if set to a value other than ``0``) or disables (if set to ``0``) per-user/group quotas for      |
|                                     | further management with the standard Linux ``quota`` utility. Keep in mind the following:                 |
|                                     |                                                                                                           |
|                                     | -  Enabling per-user and per-group quotas for a container requires restarting the container.              |
|                                     |                                                                                                           |
|                                     | -  If you delete a registered user but some files with their ID continue residing inside your container,  |
|                                     |    the current number of UGIDs (user and group identities) inside the container will not decrease.        |
|                                     |                                                                                                           |
|                                     | -  If you copy an archive containing files with user and group IDs not registered inside your container,  |
|                                     |    the number of UGIDs inside the container will increase by the number of these new IDs.                 |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--ioprio <number>``               | The container priority for disk I/O operations. The allowed range of values is ``0-7``. The greater the   |
|                                     | priority, the more time the container has for writing to and reading from the disk. The default container |
|                                     | priority is ``4``.                                                                                        |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--iolimit <number>``              | The bandwidth a container is allowed to use for its disk input and output (I/O) operations. By default,   |
|                                     | the limit is set in megabytes per second. You can use the following suffixes to specify measurement       |
|                                     | units:                                                                                                    |
|                                     |                                                                                                           |
|                                     | -  ``G``: sets the limit in gigabytes per second                                                          |
|                                     |                                                                                                           |
|                                     | -  ``M``: sets the limit in megabytes per second                                                          |
|                                     |                                                                                                           |
|                                     | -  ``K``: sets the limit in kilobytes per second                                                          |
|                                     |                                                                                                           |
|                                     | -  ``B``: sets the limit in bytes per second                                                              |
|                                     |                                                                                                           |
|                                     | In the current version of Virtuozzo, the maximum I/O bandwidth limit you can set for a container is 2 GB  |
|                                     | per second. The default I/O bandwidth limit for all newly created containers is set to 0, which means     |
|                                     | that no limits are applied to any containers.                                                             |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--iopslimit <number>``            | The maximum number of disk input and output operations per second a container 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.                                                                       |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--rate <class>:_<Kbits>_``        | If traffic shaping is turned on, then this parameter specifies bandwidth guarantee for the container. The |
|                                     | format is ``<class>_:_<Kbits>_`` where ``<class>`` is the network class (group of IP addresses) and       |
|                                     | ``<Kbits>`` is the traffic bandwidth.                                                                     |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--ratebound <yes|no>``            | If set to "yes", the bandwidth guarantee is also the limit for the container and the container cannot     |
|                                     | borrow the bandwidth from the ``TOTALRATE`` bandwidth pool.                                               |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--memsize <size>``                | The amount of RAM that can be used by the processes of a container, in megabytes. 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 container’s RAM that said container is guaranteed to have. By default, set to 0%.    |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--swappages <pages>``             | The amount of swap space that can be used by the container for swapping out memory once the RAM is        |
|                                     | exceeded, in 4KB pages. You can use the following suffixes to specify measurement units:                  |
|                                     |                                                                                                           |
|                                     | -  ``G`` for gigabytes                                                                                    |
|                                     |                                                                                                           |
|                                     | -  ``M`` for megabytes                                                                                    |
|                                     |                                                                                                           |
|                                     | -  ``K`` for kilobytes                                                                                    |
|                                     |                                                                                                           |
|                                     | -  ``B`` for bytes                                                                                        |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--swap <size>``                   | The amount of swap space that can be used by the container for swapping out memory once the RAM is        |
|                                     | exceeded, in bytes. You can use the following suffixes to specify measurement units:                      |
|                                     |                                                                                                           |
|                                     | -  ``G`` for gigabytes                                                                                    |
|                                     |                                                                                                           |
|                                     | -  ``M`` for megabytes                                                                                    |
|                                     |                                                                                                           |
|                                     | -  ``K`` for kilobytes                                                                                    |
|                                     |                                                                                                           |
|                                     | -  ``B`` for bytes                                                                                        |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _Network Options:

Network Options
^^^^^^^^^^^^^^^

Network-related options allow you to set the hostname and configure ``iptables`` modules.

+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| Name                                                     | Description                                                                          |
+==========================================================+======================================================================================+
| ``--hostname <name>``                                    | Sets the hostname to the specified name.                                             |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--apply-iponly <yes|no>``                              | If set to ``yes``, the hostname, nameserver, and search domain settings from the     |
|                                                          | container configuration file are ignored.                                            |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--netfilter <disabled|stateless|stateful|full>``       | Indicates which ``iptables`` modules are allowed for the container. If some of the   |
|                                                          | allowed modules are not loaded on the destination Hardware Node after migration or   |
|                                                          | restoration from backup, they will be automatically loaded on the migrated or        |
|                                                          | restored container start. The following modes are available:                         |
|                                                          |                                                                                      |
|                                                          | -  **disabled**: none.                                                               |
|                                                          |                                                                                      |
|                                                          | -  **stateless**: all modules except ``conntrack`` and NAT-related.                  |
|                                                          |                                                                                      |
|                                                          | -  **stateful**: all modules except NAT-related.                                     |
|                                                          |                                                                                      |
|                                                          | -  **full**: (default) all modules.                                                  |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+

You can also set other network parameters, such as the DNS server address and the IP addresses (both IPv4 and IPv6), when adding a new or configuring the existing container network adapter:

::

    prlctl set <CT_name> {--device-add net | --device-set net<N>} <options>

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<CT_name>``                       | Container name.                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--device-add net``                | Adds a new virtual network adapter to the container.                                                      |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--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 container.                                                          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--gw6 <gw>``                      | The default IPv6 gateway to be used by the container.                                                     |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--nameserver <addr>``             | The default DNS server address to be used by the container.                                               |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--searchdomain <addr>``           | The default search domain to be used by the container.                                                    |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``--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 the container.     |
|                                     | If set to ``yes``, the adapter will drop such packages.                                                   |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _Hard Disk Drive Management Options:

Hard Disk Drive Management Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This group of options is used to manage virtual hard disks in a container.

::

    prlctl set <CT_name> --device-add hdd [--image <file>] [--size <size>]
               [--mnt <path>] [--iface <ide|scsi|virtio>] [--position <pos>]
    prlctl set <CT_name> --device-set hdd<N> [--image <file>] [--size <size>]
               [--mnt <path>] [--iface <ide|scsi|virtio>] [--position <pos>]
               [--autocompact <on|off>]
    prlctl set <CT_name> --backup-add <backup_ID> [--disk <disk_name>]
    prlctl set <CT_name> --device-del hdd<N> [--detach-only|--destroy-image]
    prlctl set <CT_name> --backup-del {<backup_ID>|all}

+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| Name                                                     | Description                                                                          |
+==========================================================+======================================================================================+
| ``<CT_name>``                                            | Container name.                                                                      |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--device-add hdd``                                     | Adds a virtual hard disk to the container. If no other options are specified, the    |
|                                                          | command creates a new unmounted disk with the following parameters:                  |
|                                                          |                                                                                      |
|                                                          | -  name: ``hdd<N>`` where ``<N>`` is the next available disk index.                  |
|                                                          |                                                                                      |
|                                                          | -  size: 65536 MB                                                                    |
|                                                          |                                                                                      |
|                                                          | -  image location: ``/vz/private/<CT_UUID>/disk-<ID>.hdd``.                          |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--device-set hdd<N>``                                  | Modifies the parameters of the virtual hard disk ``hdd<N>``.                         |
|                                                          |                                                                                      |
|                                                          | .. note:: For the list of disks, use the ``prlctl list -i`` command.                 |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--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.       |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--size <size>``                                        | Specifies the size of the virtual hard disk, in megabytes.                           |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--mnt <path>``                                         | Specifies the mount point of the virtual hard disk inside the container. A           |
|                                                          | corresponding entry is also added to container’s ``/etc/fstab`` file, so the disk is |
|                                                          | mounted automatically on container start.                                            |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--autocompact <on|off>``                               | Enables or disables compaction for the specified disk in the container.              |
|                                                          |                                                                                      |
|                                                          | .. note:: For details on how to enable or disable compaction for all disks in        |
|                                                          |     the container, see :ref:`General Options`.                                       |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--backup-add <backup_ID>``                             | Attach the backup with the identifier ``<backup_ID>`` to the virtual machine as a    |
|                                                          | virtual hard disk. To obtain the backup ID, use the ``prlctl backup-list -f``        |
|                                                          | command.                                                                             |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--disk <disk_name>``                                   | Used with ``--backup-add``. The name of the disk in the backup to attach. If a disk  |
|                                                          | is not specified, all disks contained in the backup will be attached. To obtain the  |
|                                                          | disk name, use the ``prlctl backup-list -f`` command.                                |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--device-del hdd<N>``                                  | Deletes a virtual hard disk from the stopped container.                              |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--detach-only``                                        | Removes the virtual disk from the container configuration but leaves its image file  |
|                                                          | intact.                                                                              |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--destroy-image``                                      | Removes the virtual disk from the container configuration and deletes its image      |
|                                                          | file.                                                                                |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+
| ``--backup-del {<backup_ID>|all}``                       | Detach either the backup with the identifier ``<backup_ID>`` or detach all backups   |
|                                                          | from the virtual machine.                                                            |
+----------------------------------------------------------+--------------------------------------------------------------------------------------+

.. _prlctl snapshot, snapshot-list, snapshot-switch, snapshot-delete:

prlctl snapshot, snapshot-list, snapshot-switch, snapshot-delete
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Takes, displays, reverts to, and deletes container snapshots.

.. note:: Taking a snapshot of a running container saves not only its filesystem state but in-memory state (checkpoint) as well. 

::

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

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<CT_name>``                       | Container 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's parent.                             |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _prlctl start, stop, restart, status:

prlctl start, stop, restart, status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These commands start, stop, restart, and show the current state of containers, respectively.

::

    prlctl start <CT_name> [--wait]
    prlctl stop <CT_name> [--fast]
    prlctl restart <CT_name>
    prlctl status <CT_name>

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<CT_name>``                       | Container name.                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

The first command is used to start a container. It will set up all network interfaces inside the container, initialize the container quota, if needed, start the ``init`` process inside the container, and exit. You can also make the ``prlctl start`` command wait for all the necessary startup processes to complete and the container to boot into the default runlevel by passing the ``--wait`` option to this command.

``prlctl stop`` shuts the container down. If the container is not down after a two-minute timeout due to an error in an application, for example, ``prlctl`` will forcibly kill all the processes inside the container. To avoid waiting for two minutes in case of a corrupted container, you may use the ``--fast`` option with this command.

The ``prlctl restart <CT_name>`` command consecutively performs the stopping and starting of the corresponding container.

.. note:: The commands described above can trigger the execution of action scripts (see :ref:`Action Scripts`).

The ``prlctl status`` command shows the current container state. It outputs the following information: whether the container private area exists, whether it is mounted, and whether the container is running.

.. _prlctl suspend, resume:

prlctl suspend, resume
~~~~~~~~~~~~~~~~~~~~~~

The ``prlctl suspend`` command is used to save the state of a running container.

::

    prlctl suspend <CT_name>

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``<CT_name>``                       | Container name.                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

During the ``prlctl suspend`` execution, the current container state is saved to a special dump file and the container itself is stopped. The created dump file is saved to the ``Dump`` file in the ``/vz/private/<CT_UUID>/dump`` directory on the server.

The ``prlctl resume`` command is used to restore the container from its dump file created with the ``prlctl suspend`` command.

::

    prlctl resume <CT_name>

When executed, ``prlctl resume`` searches for the ``Dump`` file in the ``/vz/private/<CT_UUID>/dump`` directory on the server and restores the container from this file.You can restore the container dump file on the Source Server, i.e. on the server where this container was running before its dumping, or transfer the dump file to another server and restore it there.

.. note:: Before restoring a container from its dump file, make sure that the file system on the Destination Server is identical to that at the moment of the container dumping. Otherwise, the container restoration may fail.

.. _prlctl list:

prlctl list
~~~~~~~~~~~

Displays a list of containers on the Hardware Node. Displays information on containers on the Hardware Node.

::

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

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``-a, --all``                       | List all running, stopped, suspended, and paused containers. If this and the rest of the parameters are   |
|                                     | omitted, only the running containers will be displayed.                                                   |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``-t, --template``                  | List available container templates instead of actual containers.                                          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``-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:`prlctl list Output Parameters`.                                         |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``-s, --sort {<field>|-<field>}``   | Sort containers by the specified field in either ascending or descending order.                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``-i, --info``                      | Display detailed information about the specified container.                                               |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``-f, --full``                      | Display detailed information about network cards in containers. Used with the ``--info`` option.          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``<CT_name>``                       | Thename of the container for which to display the detailed information. If not specified, the information |
|                                     | will be displayed for all registered containers.                                                          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``-j, -json``                       | Produce machine-readable output in the JSON format.                                                       |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _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``                     | Container UUID.                                                                      |
+------------------------------+------------------------------+--------------------------------------------------------------------------------------+
| ``hostname``                 | ``HOSTNAME``                 | Container hostname.                                                                  |
+------------------------------+------------------------------+--------------------------------------------------------------------------------------+
| ``name``                     | ``NAME``                     | Container name.                                                                      |
+------------------------------+------------------------------+--------------------------------------------------------------------------------------+
| ``description``              | ``DESCRIPTION``              | Container description.                                                               |
+------------------------------+------------------------------+--------------------------------------------------------------------------------------+
| ``ostemplate``               | ``OSTEMPLATE``               | Specifies the name of the OS template your container is based on (e.g.,              |
|                              |                              | ``centos-6-x86_64``).                                                                |
+------------------------------+------------------------------+--------------------------------------------------------------------------------------+
| ``ip``                       | ``IP_ADDR``                  | Container IP address.                                                                |
+------------------------------+------------------------------+--------------------------------------------------------------------------------------+
| ``status``                   | ``STATUS``                   | Container 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 container.                                                    |
+------------------------------+------------------------------+--------------------------------------------------------------------------------------+
| ``iolimit``                  | ``IOLIMIT``                  | The bandwidth a container is allowed to use for its disk input and output (I/O)      |
|                              |                              | operation, in bytes per second.                                                      |
+------------------------------+------------------------------+--------------------------------------------------------------------------------------+
| ``ha_enable``                | ``HA_ENABLE``                | Indicates whether the container is joined to the High Availability Cluster.          |
+------------------------------+------------------------------+--------------------------------------------------------------------------------------+
| ``ha_prio``                  | ``HA_PRIO``                  | Container priority in the High Availability Cluster (0 is the lowest).               |
|                              |                              | Higher-priority virtual environments are restarted first in case of failures.        |
+------------------------------+------------------------------+--------------------------------------------------------------------------------------+

.. _prlctl statistics:

prlctl statistics
~~~~~~~~~~~~~~~~~

Print statistics for running containers on the server.

::

    prlctl statistics {<CT_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 

.. _Action Scripts:

Action Scripts
~~~~~~~~~~~~~~

Action scripts can be used to perform actions on containers at various stages of container operation. The following ``prlctl`` commands can trigger action scripts: ``start``, ``stop``, ``restart``, ``mount``, and ``umount``.

Two types of scripts are supported: global, triggered for each container on host, and per-container, triggered for specific containers.

Some of the scripts (default) are shipped with Virtuozzo. Other are not present by default but can be created manually and must be assigned specific file names to be triggered.

If you need to extend the functionality of default action scripts, it is recommended to create additional custom scripts and call them from the default scripts.

.. _Default Action Scripts:

Default Action Scripts
^^^^^^^^^^^^^^^^^^^^^^

Default action scripts are located in the ``/usr/libexec/libvzctl/scripts/`` directory.

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``vz-create_prvt``                  | Creates a container private area from a private area template.                                            |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``vz-net_add``                      | Sets up the necessary routing entries for container IP addresses and adds public ARP records              |
|                                     | on all interfaces.                                                                                        |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``vz-net_del``                      | Deletes routing entries and ARP records for container IP addresses from all interfaces.                   |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``vz-pci_configure``                | Executed after a PCI device is added to or removed from a container.                                      |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``vz-setrate``                      | Configures the network traffic shaping for a container.                                                   |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``vz-start``                        | Called just before a container is started; used for additional container configuration (such as           |
|                                     | network setup).                                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``vz-stop``                         | Called just after a container is shut down; used for additional container cleanup (such as network        |
|                                     | cleanup).                                                                                                 |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. _Manually Created Action Scripts:

Manually Created Action Scripts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Action scripts recognized by Virtuozzo but not shipped by default can be of two types:

- Global, executed for all containers on host. Such scripts must have the prefix ``vps`` (e.g., ``vps.mount``) and need to be placed in ``/etc/vz/conf/``.

- per-container, executed for specific containers. Such scripts must not have the prefix ``vps`` and need to be placed in ``/vz/private/<CT_UUID>/scripts/``.

+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Name                                | Description                                                                                               |
+=====================================+===========================================================================================================+
| ``vps.mount``, ``mount``            | Executed after a container is mounted. Can be global or container-specific.                               |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``start``                           | Executed in container context on container start.                                                         |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``stop``                            | Executed in container context on container stop.                                                          |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ``vps.umount``, ``umount``          | Executed before a container unmounted. Can be global or container-specific.                               |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. note:: All action scripts except ``start`` and ``stop`` are executed in the host context. The ``start`` and ``stop`` scripts are executed in the container context.

The environment passed to the ``mount`` and ``umount`` scripts is the standard environment of the parent (e.g., ``prlctl``) with two additional variables: ``$VEID`` and ``$VE_CONFFILE``. The first has the container UUID and the second has the full path to container's configuration file. Other container configuration parameters required for the script (such as ``$VE_ROOT``) can be obtained from the global and per-container configuration files.

