Flags

These flags can be used with any vzctl command.

--quiet

Disables logging to a console (a terminal). Logging to a log file is not affected.

--verbose

Sets console (terminal) logging level to maximum value. Logging to a log file is not affected.

Setting CT parameters

set ctid

This command sets various CT parameters. If flag --save is given, parameters are saved in CT configuration file ve.conf(5). If CT is currently running, vzctl applies these parameters to CT, in case --setmode option specified apply logic for parameters that can't be applied or tunning CT will be changed, if restart - restart CT, if ignore - ignore error. Parameters that can not be applied runtime are quotaugidlimit, bindmount, features, and iptables.

The following options can be used with set command.

Miscellaneous parameters

--setmode restart|ignore

Change default mode for apply parameters that can not be applied on running CT. restart - restart CT, ignore - ignore error.

--onboot yes|no

Sets whether this CT will be started during system boot up. CT will not be auto-started during system boot up unless this parameter is set to yes.

--bootorder number

Sets the boot order priority for this CT. The higher the number is, the earlier in the boot process this container starts. By default this parameter is unset, this is considered to be the lowest priority, so containers with unset bootorder will start last.

--root path

Sets path to root directory for this CT. This is essentially a mount point for CT root. Argument can contain literal string $VEID, which will be substituted with numeric CT ID. Changing this parameter is not recommended, better edit vz(5) global configuration file.

--userpasswd user:password

Sets password for given user in CT, creating the user if it does not exists. Note that this option is not saved in configuration file at all (so --save flag is useless), it is applied to CT (by modifying its /etc/passwd and /etc/shadow files).

If the --crypted parameter is specified, the system assumes that the passwords are encrypted.

In case CT root is not mounted, it is automatically mounted, then all appropriate file changes are applied, then it is unmounted.

Note that CT area should be created before using this option.

--disabled yes|no

Disable CT start. For force start disabled CT option --force can be used.

--name name

Bind CT with name, it allows to use name instead of CT ID. The valid symbols for name are [0-9][aA-Zz][ -_.] and all international symbols.

--description desc

Assign description for CT. It can be viewed by vzlist(8) utility.

--distribution dist

Assign distribution for CT. It can be viewed by vzlist(8) utility.

Network related parameters

--ipadd addr[/mask

Adds the IP address and subnet mask for the Container. To assign network masks to Containers operating in the venet0 mode, the USE_VENET_MASK parameter in the Containers configuration file must be set to "yes". Note that this option is incremental, so addr are added to already existing ones.

--ipdel addr | all

Removes IP address addr from CT. If you want to remove all addresses, use --ipdel all.

--ext_ipadd addr

Assign the external IP address to the Container. External IP addresses are considered valid IP addresses by the venet0 adapter, though they are not set as alias addresses inside Containers and are not announced via Address Resolution Protocol (ARP). You can assign the same external IP address to several Containers, irrespective of whether they reside on the same or different Hardware Nodes.

--ext_ipdel addr

Remove the external IP address from the Container. To delete all external IP addresses assigned to the Container, use ext_ipdel all.

--netif_add ifname[,mac,host_ifname,host_mac]

Adds virtual ethernet device to given CT. Where ifname is ethernet device name in the CT, mac its MAC address, host_ifname is ethernet device name on the host and host_mac its MAC address. MAC addresses has format like XX:XX:XX:XX:XX:XX. All parameters except ifname are option and automatically generated if not specified.

Per-interface configuration.
To select the interface to configure, use --ifname name option.
--mac XX:XX:XX:XX:XX:XX - MAC address of interface inside CT
--host_ifname name - interface name for virtual interface on host server
--host_mac XX:XX:XX:XX:XX:XX - MAC address of interface on host server
--gw ipaddr - default IPv4 gateway for interface
--gw6 ipaddr - default IPv6 gateway for interface
--ipadd ipaddr - add IP address(es) to interface
--ipdel ipaddr - delete IP address(es) from interface
--dhcp yes|no - turn on/off IPv4 dhcp
--dhcp6 yes|no - turn on/off IPv6 dhcp
--configure none|all - apply/ignore the network settings (gw,ip,dhcp) from the Container configuration file. Configuring any of the network settings automatically sets this option to "all".
--network id - connect virtual interface to virtual network with the given id. The valid symbols for network are [0-9][aA-Zz][ -_.#()] and all international symbols.
--mac_filter on|off - enable/disable packets filtering by MAC address and MAC changing on veth device inside CT.

--netif_del dev_name

Removes virtual ethernet device from CT.

--hostname name

Sets CT hostname and writes it to the appropriate file inside CT (distribution-dependent).

--nameserver addr

Sets DNS server IP address for CT. If you want to set several nameservers, you should do it at once, so use --nameserver option multiple times in one call to vzctl, as all the name server values set in previous calls to vzctl gets overwritten.

--searchdomain name

Sets DNS search domains for CT. If you want to set several search domains, you should do it at once, so use --searchdomain option multiple times in one call to vzctl, as all the search domain values set in previous calls to vzctl gets overwritten.

Resource limits

The following options sets barrier and limit for various user beancounters. Each option requires one or two arguments. In case of one argument, vzctl sets barrier and limit to the same value. In case of two colon-separated arguments, the first is a barrier, and the second is a limit.

Arguments are in items, pages or bytes. Note that the page size is architecture-specific, it is 4096 bytes on IA32 platform.

There is an ability to accept different suffixes for set parameters (except the parameters that name started with num). E.g. vzctl set XXX --privvmpages 5M:6M should set privvmpages barrier to 5 megabytes and limit to 6 megabytes.

Available suffixes are:
t, T -- terabytes
g, G -- gigabytes
m, M -- megabytes
k, K -- kilobytes
p, P -- pages (page is 4096 bytes on x86 architecture, other arches may differ)

-p, --numproc items[:items]

Maximum number of processes and kernel-level threads. Setting the barrier and the limit to different values does not make practical sense.

--vmguarpages pages[:pages]

Memory allocation guarantee. This parameter controls how much memory is available to CT. The barrier is the amount of memory that CT's applications are guaranteed to be able to allocate. The meaning of the limit is currently unspecified; it should be set to 2,147,483,647.

-l, --lockedpages pages[:pages]

Maximum number of pages acquired by mlock(2).

--privvmpages pages[:pages]

Allows controlling the amount of memory allocated by the applications. For shared (mapped as MAP_SHARED) pages, each CT really using a memory page is charged for the fraction of the page (depending on the number of others using it). For "potentially private" pages (mapped as MAP_PRIVATE), CT is charged either for a fraction of the size or for the full size if the allocated address space. It the latter case, the physical pages associated with the allocated address space may be in memory, in swap or not physically allocated yet.

The barrier and the limit of this parameter control the upper boundary of the total size of allocated memory. Note that this upper boundary does not guarantee that CT will be able to allocate that much memory. The primary mechanism to control memory allocation is the --vmguarpages guarantee.

--shmpages pages[:pages]

Maximum IPC SHM segment size. Setting the barrier and the limit to different values does not make practical sense.

-n, --numfile items[:items]

Maximum number of open files. Setting the barrier and the limit to different values does not make practical sense.

-f, --numflock items[:items]

Maximum number of file locks. Safety gap should be between barrier and limit.

-t, --numpty items[:items]

Number of pseudo-terminals (PTY). Note that in OpenVZ each CT can have no more than 255 PTYs. Setting the barrier and the limit to different values does not make practical sense.

-i, --numsiginfo items[:items]

Number of siginfo structures. Setting the barrier and the limit to different values does not make practical sense.

-e, --numiptent num[:num]

Number of iptables (netfilter) entries. Setting the barrier and the limit to different values does not make practical sense.

--physpages pages[:pages]

This parameter limits the physical memory (RAM) available to processes inside a container. The barrier is ignored, and the limit sets the limit.

--swappages pages[:pages]

This parameter limits the amount of swap space that can be allocated to processes running in a Container.

--ram bytes

The amount of RAM that can be used by the processes of a Container, in bytes. You can use the following suffixes to set RAM in other measurement units:
k, K -- kilobytes
m, M -- megabytes
g, G -- gigabytes
t, T -- terabytes

--swap bytes

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 set swap in other measurement units:
k, K -- kilobytes
m, M -- megabytes
g, G -- gigabytes
t, T -- terabytes

--vm_overcommit N

This parameter controls the memory allocation guarantee. It is calculated as (physpages + swappages) * N. By default, the parameter is equal to 1.

--memguarantee auto|value

Set the amount of memory (RAM) that will be guaranteed to a Container. The guaranteed memory is a percentage of total RAM that is set for the Container with the '--memsize' option. By default, memory guarantee is set to 'auto' (0% - no gurantee).

-e, --numnetif num

Maximum number of network interfaces. --pagecache-isolation yes|no By default page cache evicted from a memory cgroup (Container) on local pressure is stored in Nodes memory unmodified in case there is free RAM on the Node, thus the pages can be fetched back later without costly disk accesses improving the overall Node performance. Enable page cache isolation (set to yes) tuned off this logic.

CPU fair scheduler parameters

These parameters control CPU usage by CT.

--cpuunits num

sets CPU weight for CT. Argument is positive number, which passed to and used in kernel fair scheduler. The larger the number is, the more CPU time this CT get. Maximum value is 500000, minimal is 8. Number is relative to weights of all the other running CTs. If cpuunits not specified the default value 1000 is used.

--cpulimit num

Sets the CPU limit, in percent or megahertz (MHz), the Container is not allowed to exceed. By default, the limit is set in percent. To specify the limit in MHz, specify "m" after the value. Note: If the computer has 2 CPUs, the total CPU time equals 200%.

--cpus num

sets number of CPUs available in the CT.

--cpumask {N[,N][N-N]|all|auto}

Defines the CPUs on the physical server to use for executing the processes running in the Container. A CPU affinity mask can be a single CPU number or a CPU range separated by commas (0,2,3-10). If used with the --nodemask option, value of auto automatically assigns to a Container all CPUs from the specified NUMA node. Without the --nodemask option, it applies the default settings to a Container.

--nodemask {N[,N][N-N]|all}

Defines the NUMA node on the physical server to use for executing the processes running in the Container. A node mask can be a single number or a range separated by commas (0,2,3-10). --nodemask must be used with the --cpumask option.

--iptables name[,...]

Restrict access to iptable modules inside CT (by default modules defined in the IPTABLES variable in the global configuration file vz.conf(5) are accessible inside CT). Multiple comma-separated values can be specified.

You can use the following values for name: iptable_filter, iptable_mangle, ipt_limit, ipt_multiport, ipt_tos, ipt_TOS, ipt_REJECT, ipt_TCPMSS, ipt_tcpmss, ipt_ttl, ipt_LOG, ipt_length, ip_conntrack, ip_conntrack_ftp, ip_conntrack_irc, ipt_conntrack, ipt_state, ipt_helper, iptable_nat, ip_nat_ftp, ip_nat_irc, ipt_owner.

--netfilter mode

Restrict access to iptables modules inside the Container. The following modes are available:
disabled -- no modules are allowed.
stateless -- (default) all modules except NAT and conntracks are allowed.
stateful -- all modules except NAT are allowed.
full -- all modules are allowed.

Network devices control parameters

--netdev_add name

move network device from host server to specified CT

--netdev_del name

delete network device from specified CT

Disk quota parameters

--diskspace num

Sets disk quota, in blocks. One block is currently equal to 1Kb.

--quotaugidlimit num

sets maximum number of user/group IDs in CT for which disk quota in CT will be accounted. If this value is set to 0, user and group quotas will not be accounted inside CT.

Note that if you have previously set value of this parameter to 0, changing it while CT is running will not take effect. --jquota on|off Enables or disables journaled user/group quota for a ploop-based Container. Journaled quota is enabled by default.

Traffic shaping parameters

--rate dev:class:Kbits

Sets CT output bandwidth over specified network interface for specified traffic class. Traffic classes must be described in networks_classes(5) file.

--ratebound yes|no

If this parameter is set to yes then CT output bandwidth specified by --rate option will be bandwidth limit and guarantee. Otherwise --rate sets CT output bandwidth guarantee for traffic and limit is set by TOTALRATE global option.

Mount option

--noatime yes|no

Sets noatime flag (do not update inode access times) on file system. Default is yes for CT with class_id=1, otherwise no.

--mount_opts opt[,opt]

Specify the set of mount options for ploop-based Containers. The supported options are pfcache_csum (enables the cached ext4 file system) and nopfcache_csum (disables the cached ext4 file system).

--bindmount_add [src:]dst[,nosuid,noexec,nodev]

On CT start directory src will be mounted under CT $VE_ROOT/dst. If the src directory is not specified, it is created under $VE_PRIVATE/mnt/dst with permissions taken from CT $VE_ROOT/dst.

--bindmount_del dst|all

Remove directory dst from config file

Device access management

--devnodes device:r|w|rw|none

Give access (r - read, w - write, rw - read/write, none - no access) to special file /dev/device from CT.

I/O priority management

--ioprio priority

Assigns I/O priority to CT. Priority range is 0-7. The greater priority is, the more time for I/O activity CT has. By default each CT has priority of 4.

--iolimit limit[B|K|M|G]

Assigns I/O limit to CT. If no suffix is provided, the value is assumed to be in bytes per second. Available suffixes are:
b, B -- bytes
k, K -- kilobytes
m, M -- megabytes
g, G -- gigabytes
t, T -- terabytes

By default each CT has limit of 0 (unlimited). The maximum disk I/O bandwidth limit you can set for a Container is 2 GB per second.

--iopslimit limit

Assigns Input/Output Operations Per Second limit to CT.

Features management

--features name:on|off[,...]

Enable/disable feature for CT. Supported features are: bridge, ipgre, ipip, nfs, nfsd, ppp, sit, time. Multiple comma-separated values can be specified.

PCI device management

--pci_add [domain:]bus:slot.func

Give the container an access to a PCI device. All numbers are hexadecimal as printed by lspci(8) in the first column.

--pci_del [domain:]bus:slot.func

Delete PCI device from the container.

Apply config

--applyconfig name

Read CT parameters from CT sample configuration file /etc/vz/conf/ve-name.conf-sample, and apply them, if --save option specified save to CT config file. The following parameters are not changed: HOSTNAME, IP_ADDRESS, TEMPLATE, OSTEMPLATE, VE_ROOT, VE_PRIVATE.

High Availability Cluster

--ha_enable yes|no

Adds the Container to (yes) or removes it (no) from the High Availability Cluster. By default, the parameter is set to yes.

--ha_prio number

Sets the Container priority in the High Availability Cluster. Containers with a higher priority are restarted first in the case of a system failure. If the parameter is not set for a Container (default), it has the lowest priority and is restarted after all Containers with any priorities set.

Performing CT actions

create ctid [--ostemplate name] [--config name] [--private path] [--root path] [--name name] [--description desc] [--force]

Creates CT area. This operation should be done once, before the first startup of CT.

If the --config name option is specified, values from example configuration file /etc/vz/conf/ve-name.conf-sample are put into CT configuration file. If CT configuration file already exists, it will be removed.

You can use --root path option to sets the path to the mount point for CT root directory (default is VE_ROOT specified in vz(5) file). Argument can contain literal string $VEID, which will be substituted with numeric CT ID.

You can use --private path option to set the path to directory in which all the files and directories specific to this very CT are stored (default is VE_PRIVATE specified in vz(5) file). Argument can contain literal string $VEID, which will be substituted with numeric CT ID.

You can use the --force option to create a Container if your storage/disk drive has less than 10 GB of free disk space.

destroy|delete ctid

Removes CT private area by deleting all files, directories and configuration file of this CT. Also delete command can be used as alias for destroy.

start ctid [--wait] [--skip-fsck]

Mounts (if necessary) and starts CT, if --wait option specified wait until default runlevel is entered. If the --skip-fsck option is specified, the filesystem check will be skipped.

stop ctid [--fast] [--skip-umount]

Stops the Container and unmounts it (unless --skip-umount is given).

Normally, to stop a Container, halt(8) is executed inside; option --fast makes vzctl use reboot(2) syscall instead which is faster but can lead to unclean Container shutdown.

restart ctid [--wait]

Restart CT, stop if running and start. if --wait option specified wait until default runlevel is entered.

status ctid

Shows CT status. Basically this is a line with five or six words separated by spaces.

First word is literally VEID.

Second word is numeric CT ID.

Third word is showing whether CT exists or not, it can be either exist or deleted.

Fourth word is showing the status of CT filesystem, it can be either mounted or unmounted.

Fifth word shows if CT is running, it can be either running or down.

Sixth word, if exists, is suspended. It appears if a dump file exists for a stopped container (see suspend).

This command can also be usable from scripts.

mount ctid

Mounts CT private area.

umount ctid

Unmounts CT private area. Note that stop does umount automatically.

exec ctid command

Executes command in CT. Environment variables are not set inside CT. Signal handlers may differ from default settings. If command is -, commands are read from stdin.

exec2 ctid command

The same as exec, but return code is that of command.

exec3 ctid command

The same as exec2, but not quotes command args.

enter ctid

Enters into CT. This option is a back-door for host root only.

console ctid [-s|--start] [N]

Attach to the Container's console tty number N. If N is not specified, 2 (i.e. tty2) is used. Use 1 to attach to Container's system console, see log messages from init etc. Note that you can even attach to a console if a Container is not yet running. To exit from the console, press "Esc" then "." (note this sequence is only recognized after Enter).

If option --start is given, vzctl doesn't attach to a console, instead it starts getty for ttyN. Usually, getty is preconfigured to start on tty1 and tty2 only.

reinstall ctid [--skipbackup] [--resetpwdb] [--scripts script] [--skipscripts] [--vzpkg_opts opts]

The reinstall command creates a new private area, installs all applications, copies CT credentials from the old CT (unless --resetpwdb is given), and moves old CT private area to /old directory (unless --skipbackup option is given). To customize the reinstall process, two scripts should be created. The first one, vps.reinstall, creates a new private area. If this script exits with exit code of 128, it indicates that standard reinstall procedure will be done. The second script, vps.configure, is run inside CT there the old CT is mounted under '/old' directory.

pause <ctid>

Pause the specified Container.

reinstall ctid [--listscripts] [--desc]

List reinstall scripts if --desc option specified output description.

runscript ctid

Run the specified shell script in the Container. For a running Container, the command jumps into the Container and runs the script. For a stopped Container, it enters the Container, mounts the root (/) filesystem, and executes the script. In this case, only a process for the vzctl session, the script, and processes launched by the script are running in the Container.

execaction ctid

Run the distribution action for the Container by name, like SET_DNS or SET_HOSTNAME.

monitor ctid | 0

Display in real-time actions or events for ctid. In case ctid is 0, display actions and events for all CTs. Valid only on 2.6 kernel.

convert ctid

In OpenVZ, Containers use the new layout. The convert command converts a Container from the old layout to a new one.

register path ctid [--force

Register the Container using the configuration file path/ve.conf and having ID ctid. If the --force option is specified, all validation checks will be skipped.

unregister ctid|name

Unregister the specified Container.

compact <ctid> [--defrag]

Compact container image.

Container action scripts

Suspend/Restore

Checkpointing is an extension of OpenVZ kernel 2.6 which allows to save full state of running CT and to restore it later.

suspend ctid

This command saves all the state of running CT to a dump file and stops the CT. The dump files is named /VE_PRIVATE/dump/Dump.

resume ctid [--skip-fsck]

This command restores CT from dump file created by suspend command. The start or resume actions will invalidate dump file so it will be removed. If the --skip-fsck option is specified, the filesystem check will be skipped.

Snapshotting

Snapshotting is a feature based on checkpointing and ploop shapshots. It allows to save a complete state of container file system. Plus, if the container is running, it's in-memory state (as in checkpointing). Note that snapshot functionality is only working for containers on ploop device.

snapshot CTID [--id uuid] [--skip-suspend]

Creates a container snapshot. If uuid is not specified, it is auto-generated. If a container is running, and --skip-suspend option is not specified, it's checkpointed and then restored. If a container is not running, only file system state is saved.

snapshot-switch CTID --id uuid

Switches the container to a snapshot identified by uuid. Note that the current container state and its file system state is lost! If given snapshot contains CT memory dump, it is restored, otherwise it is stopped.

snapshot-delete CTID --id uuid

Removes a specified snapshot.

snapshot-mount CTID --id uuid --target path

Mounts a snapshot specified by uuid to path. Note that this is read-only mount.

snapshot-umount CTID --id uuid

Unmounts the snapshot specified by uuid.

snapshot-list CTID [-H] [-o field[,field...] [--id uuid]

Lists all snapshots. Active snapshot is marked with * sign.

You can suppress displaying header using -H option.

You can use the -o option to display only the specified field(s). List of available fields can be obtained using -L option.

Other options

--help

Prints help message with a brief list of possible options.

--version

Prints vzctl version.

System errors

1

Setting UBC parameters failed

2

Setting fair scheduler parameters failed

3

System error

4

Not enough memory error

5

Kernel does not have support for CT, or some VZ modules are not loaded

6

Not enough system resources

7

Creation of the virtual server failed

8

Command run by vzctl exec returned non-zero exit status

9

CT is locked by another vzctl operation

10

Global configuration file not found

14

CT configuration file not found

11

One of vzctl helper scripts not found

12

VZ license not loaded, or invalid class ID

Parameter errors

20

Invalid command line parameter

21

Invalid value for command line parameter

22

CT root directory is not set

23

CT private directory is not set

24

CT template directory is not set

25

Traffic shaping parameter RATE is not set

26

Traffic shaping parameter TOTALRATE is not set

27

Not all needed parameters set, unable to start CT

28

Not all UBC parameters set, unable to start CT

29

Package set parameter is not specified during create

30

Traffic shaping parameter BANDWIDTH is not set

76

Class ID is not set

77

Lock dir is not set

133

Failed to setup CT start wait functionality

CT errors

31

CT is not running

32

CT is already running

33

Unable to stop CT

79

Per CT action script returned with error

85

CT config file contain invalid data (belong to diferent config versions)

105

CT start disabled

140

Failed to register CT

141

CT owner check failed

142

Failed to unregister CT

File system errors

40

CT area is not mounted

41

CT area is mounted, can not destroy CT area

43

CT private area does not exist

44

CT private area already exists

46

Not enough disk space

47

CT private area is not created properly

48

Can not create new CT private area

49

Can not create mount point

50

Can not mount CT private area

51

Can not umount CT private area

52

Can not umount disk image, device is busy

231

Error deleting CT private area

53

Unknown mount type

54

Can not create directory

56

Unsupported /sbin/init

82

Can't copy sample config file, or sample config file not exist

Disk quota errors

60

Error during "quota on" operation

66

Error during "quota off" operation

61

Error during "quota init" operation

62

Error during "quota set" operation

67

Ugid quota can not be turned ON on mounted CT. It must be initialized first.

63

Can not init quota - disk space limit is not set

64

Can not init quota - disk inode limit is not set

65

Can not set ugid quota limit

Errors of vzctl set

70

Invalid host name

71

Invalid IP address

72

Invalid DNS server address

73

Invalid DNS domain name

74

Error changing password

34

Error adding IP address

78

IP address already in use

106

Error setting iptables parameter

135

Error setting meminfo parameter

137

Can not set CT name

146

Error setting cpumask parameter

147

Unable to configure PCI device

148

Error setting IO parameters

149

Error setting nodemask parameter

Traffic shaping error

80

Can not set up traffic shaping

Traffic accounting error

81

Can not set up traffic accounting

Template error

91

Private area tarball not found.

87

Unable to install applications.

Reinstall error

93

Unable to get installed packages

94

Reinstall error

55

Not enough quota limits to create temporary CT

Checkpointing error

16

Checkpoint error

17

Restore error

Ploop errors

151

Failed to create ploop image

152

Failed to mount ploop image

153

Failed to unmount ploop image

154

Failed to resize ploop image

155

Failed to convert CT to ploop

156

Failed to create ploop snapshot

157

Failed to merge ploop snapshots

158

Failed to delete ploop snapshot

159

Failed to switch to snapshot

160

Failed to mount ploop snapshot