Prev Next

3.2. Container Utilities¶

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

3.2.1. 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 <command> <CT_name> [<options>] [-v, --verbose <number>] [--timeout <sec>]
       [-l, --login [<user>[:_<passwd>_]@]<server>] [-p, --read-passwd <file>]]

Name	Description
`<command>`	The name of the command to execute.
`<CT_name>`	The name of the container to perform the operation on. To obtain the list of the available containers, use the `prlctl list` command.
`<options>`	Command options. See individual commands for available options.
`-v, --verbose <number>`	Enables verbose output. The greater the `<number>`, the higher the verbosity.
`--timeout <sec>`	Use a custom operation timeout specified in seconds. The default timeout for all operations is unlimited.
`-l, --login [<user>[:<passwd>]@]<server>`	Connect to a remote `<server>` with the specified credentials. If this flag is omitted, the `prlctl` command is assumed to be run locally.
`-p, --read-passwd <file>`	Use the password from the file `<file>` to log in to a remote hardware node, other credentials being specified with the `--login` option. The `--read-passwd` option can be specified multiple times in order to form a password stack for operations requiring multiple passwords. Each password must be supplied in a separate file.

To display help, enter prlctl without any options.

3.2.2. prlctl backup, backup-list, backup-delete, restore¶

Creates, lists, deletes, or restores container backups.

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

Name	Description
`<CT_name\|CT_UUID>`	Container name or UUID. Use with `prlctl backup` to create a backup of the specified container. Use with `prlctl backup-list` to list backups of the specified container. Use with `prlctl backup-delete` to delete all backups of the specified container. Use <CT_UUID> with `prlctl restore` to restore the most recent backup of the specified container.
`-s, --storage [<user>[:<passwd>]@]<server>[:<port>]`	Specifies a remote backup server address, port, and credentials. If this option is omitted, the backup will be saved on the default backup server that can be configured using the `prlsrvctl set` command.
`--description <desc>`	Backup description. Descriptions with white spaces must be enclosed in quotation marks.
`-f, --full`	Use with `prlctl backup` to create a full backup of the container. A full backup contains all container data. Use with `prlctl backup-list` to display full backup information.
`-i, --incremental`	Create an incremental backup of the container. An incremental backup contains only the files changed since the previous full or incremental backup. This is the default backup type.
`--localvms`	List local backups only.
`--vmtype ct`	List container backups on the server.
`-t, --tag <backup_ID>`	The ID of the backup to restore or delete.
`-n, --name <new_name>`	A new name to assign to the restored container. If this option is omitted, the container will be restored with the original name.
`--dst=<path>`	Restore the container to the specified directory on the server. If this option is omitted, the container will be restored to `/vz/private/<CT_UUID>`.
`--no-compression`	Do not compress the created backup image.
`--no-tunnel`	Disables connection tunneling for backup. Connection tunneling provides secure data transmission. To use this option, configure the firewall of the destination server to allow incoming connections on any port on the corresponding network interface.
`--keep-chain`	Preserve the rest of the backup chain when deleting specific backups.

3.2.3. 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.4. 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.5. 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 Hybrid Server 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 Hybrid Server 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.6. 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.7. 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.8. 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.9. 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.10. 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.11. 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 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.12. prlctl register, unregister¶

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

The unregister command removes a container from the Virtuozzo Hybrid Server 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 Hybrid Server 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 Hybrid Server. 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 Hybrid Server registry, but does not delete the container files from the server. You can re-register the container later using the register command.

3.2.13. prlctl reinstall¶

Recreates a container’s root virtual disk, installs all applications previously installed from application templates, copies credentials from the old container (unless --resetpwdb is specified), and renames the old root directory '/' to '/old' (unless --no-backup is specified).

prlctl reinstall <ve_id|ve_name> [--no-backup] [--resetpwdb] [--ostemplate <name>]

Name	Description
`<ve_id\|ve_name>`	Container ID and name.
`--no-backup`	Does not save the old private area contents to the `/old` directory.
`--resetpwdb`	Removes the container’s user database and creates a clean database like for any new installation.
`--ostemplate <name>`	The name of OS templates.

3.2.14. 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.14.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, `time`: changing the system time.
`--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.14.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 Hybrid Server, 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.14.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.

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.14.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.15. 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 file system 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.16. 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.17. 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.18. 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.18.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., `almalinux-8-x86_64`).
`ip`	`IP_ADDR`	Container IP address.
`status`	`STATUS`	Container status (e.g., running or stopped).
`numproc`	`NPROC`	The number of threads allowed.
`mac`	`MAC`	Network device’s MAC address.
`netif`	`NETIF`	Network devices in the 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.19. 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 file system index).

3.2.19.1. Available Filters¶

Storage device statistics

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

Network statistics

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

Classful network statistics

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

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

CPU statistics

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

RAM statistics

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

Mounted file systems statistics

guest.fs<N>.name - Device name as seen from inside the guest file system
guest.fs<N>.total - Total size of the file system, in bytes
guest.fs<N>.free - Amount of free space on the file system, in bytes
guest.fs<N>.disk.<N> - Disk indices

3.2.20. 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 Hybrid Server. 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.20.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.20.2. Manually Created Action Scripts¶

Action scripts recognized by Virtuozzo Hybrid Server 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.

Version 7.5 — Dec 11, 2024

Edit Print

Prev Next