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

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

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

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

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

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

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

3.2.7. 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 Action Scripts).

prlctl mount  <CT_name>
prlctl umount <CT_name>
Name Description
<CT_name> Container name.

3.2.8. prlctl move

Moves the directory with container private area to a new location on the same server.

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.

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

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

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

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

3.2.12.1. 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> --vnc-nopasswd Sets the VNC password for the container or specifies that no password is needed for VNC connections. 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 Hard Disk Drive Management Options.

3.2.12.2. 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 {<percent>|<megahertz>} CPU limit, in per cent or megahertz (MHz), the container is not allowed to exceed. This parameter is not 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

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

3.2.12.4. Hard Disk Drive Management Options

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

prlctl set <CT_name> {--device-add hdd |--device-set hdd<N>}
           [--image <file> [--recreate]] [--size <size>]
           [--mnt <path>] [--iface <ide|scsi|virtio>]
           [--position <pos>] [--autocompact <on|off>]
prlctl set <CT_name> ----device-add hdd --device <dev_name>
           [--mnt <path>] [--iface <ide|scsi|virtio>] [--position <pos>]
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 existing image file that will be used to emulate the virtual disk. To recreate the image file, add the --recreate option.
--device <dev_name> This option is used to connect a physical hard disk on the hardware node to the container. You can obtain the names of the existing hard disks on the server using the prlsrvctl info command.
--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>

Used with --device-set hdd<N>. 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 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.

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

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

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

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

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

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

3.2.17.1. Available Filters

Storage device statistics

  • devices.{ide|scsi|sata}<N>.read_requests - Total count of read requests to IDE, SCSI, or SATA controller
  • devices.{ide|scsi|sata}<N>.read_total - Total count of read bytes for IDE, SCSI, or SATA controller
  • devices.{ide|scsi|sata}<N>.write_requests - Total count of write requests to IDE, SCSI, or SATA controller
  • devices.{ide|scsi|sata}<N>.write_total - Total count of written bytes for IDE, SCSI, or SATA controller

Network statistics

  • net.nic<N>.pkts_in - Total number of incoming packets for network adapter
  • net.nic<N>.pkts_out - Total number of outgoing packets for network adapter
  • net.nic<N>.bytes_in - Total number of incoming bytes for network adapter
  • net.nic<N>.bytes_out - Total number of outgoing bytes for network adapter

Classful network statistics

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

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

CPU statistics

  • guest.cpu.usage - Guest OS CPU usage, in percent
  • guest.cpu.time - Sum of guest CPU time differences since the last query for each vCPU averaged by the number of host CPUs, in microseconds
  • host.cpu.time - Sum of host CPU time differences since the last query for each vCPU averaged by the number of host CPUs, in microseconds
  • guest.vcpu<N>.time - per-vCPU statistics, in nanoseconds

RAM statistics

  • guest.ram.usage - Guest OS used RAM, in MiB
  • guest.ram.cached - Guest OS cached RAM, in MiB
  • guest.ram.total - Guest OS total RAM, in MiB
  • guest.ram.swap_in - Guest OS virtual memory stats, in counts
  • guest.ram.swap_out - Guest OS virtual memory stats, in counts
  • guest.ram.minor_fault - Guest OS minor page fault count
  • guest.ram.major_fault - Guest OS major page fault count
  • guest.ram.balloon_actual - Guest OS balloon size, in MiB

Mounted 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

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

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

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