1vzctl(8) Containers vzctl(8)
2
6 vzctl - perform various operations on an OpenVZ container
7
9 vzctl [flags] create CTID --parameter value [...]
10 vzctl [flags] start CTID [--wait] [--force] [--skip-fsck] [--skip-
11 remount]
12 vzctl [flags] stop CTID [--fast] [--skip-umount]
13 vzctl [flags] restart CTID [--wait] [--force] [--fast] [--skip-fsck]
14 [--skip-remount]
15 vzctl [flags] suspend | resume CTID [--dumpfile name]
16 vzctl [flags] snapshot CTID [--id uuid] [--name name]
17 [--description desc] [--skip-suspend] [--skip-config]
18 vzctl [flags] snapshot-switch CTID [--skip-resume | --must-resume]
19 [--skip-config] --id uuid
20 vzctl [flags] snapshot-delete CTID --id uuid
21 vzctl [flags] snapshot-mount CTID --id uuid --target dir
22 vzctl [flags] snapshot-umount CTID --id uuid
23 vzctl [flags] snapshot-list CTID [-H] [-o field[,field...] [--id uuid]
24 vzctl [flags] set CTID --parameter value [...] [--save] [--force]
25 [--setmode restart|ignore]
26 vzctl [flags] set CTID --reset_ub
27 vzctl [flags] destroy | delete | mount | umount | status | quotaon |
28 quotaoff | quotainit CTID
29 vzctl [flags] console CTID [ttynum]
30 vzctl [flags] convert CTID [--layout ploop[:{expanded|plain|raw}]]
31 vzctl [flags] compact CTID
32 vzctl [flags] exec | exec2 CTID command [arg ...]
33 vzctl [flags] enter CTID [--exec command [arg ...]]
34 vzctl [flags] runscript CTID script
35 vzctl --help | --version
36
38 Utility vzctl runs on the host system (otherwise known as Hardware
39 Node, or HN) and performs direct manipulations with containers (CTs).
40 Containers can be referred to by either numeric CTID or by name (see
42 --name option). Note that CT ID <= 100 are reserved for OpenVZ internal
43 purposes. A numeric ID should not be more than 2147483644.
44
46 Flags
47 These flags come before a command, and can be used with any command.
48 They affect logging to console (terminal) only, and do not affect log‐
49 ging to a log file.
50 --quiet
52 Disables output. Note that scripts run by vzctl are still able to
53 produce some output.
54 --verbose
56 Increments logging level up from the default. Can be used multiple
57 times. Default value is set to the value of VERBOSE parameter in
58 the global configuration file vz.conf(5), or to 0 if not set by
59 VERBOSE parameter.
60 Setting container parameters
63 set CTID [--onboot yes|no] [--bootorder number] [--root path]
64 [--private path] [--mount_opts options] [--userpasswd user:pass]
65 [--disabled yes|no] [--name name] [--description string]
66 [--ostemplate string] [--stop-timeout seconds] [--ipadd addr]
67 [--ipdel addr|all] [--hostname name] [--nameserver addr]
68 [--searchdomain name] [--netif_add dev[,params...]]
69 [--netif_del dev|all] [--ifname dev [--mac hwaddr]
70 [--host_ifname dev] [--host_mac hwaddr] [--bridge name]
71 [--mac_filter on|off]] [--numproc items] [--numtcpsock items]
72 [--numothersock items] [--vmguarpages pages] [--kmemsize bytes]
73 [--tcpsndbuf bytes] [--tcprcvbuf bytes] [--othersockbuf bytes]
74 [--dgramrcvbuf bytes] [--oomguarpages pages] [--lockedpages pages]
75 [--privvmpages pages] [--shmpages pages] [--numfile items]
76 [--numflock items] [--numpty items] [--numsiginfo items]
77 [--dcachesize bytes] [--numiptent num] [--physpages pages]
78 [--swappages pages] [--ram bytes] [--swap bytes]
79 [--vm_overcommit float] [--cpuunits num] [--cpulimit num]
80 [--cpus num] [--cpumask cpus|auto|all] [--nodemask nodes|all]
81 [--meminfo none|mode:value] [--iptables name[,...]]
82 [--netfilter disabled|stateless|stateful|full]
83 [--netdev_add ifname] [--netdev_del ifname] [--diskquota yes|no]
84 [--diskspace num] [--diskinodes num] [--quotatime seconds]
85 [--quotaugidlimit num] [--capability capname:on|off[,...]]
86 [--devnodes param] [--devices param] [--pci_add dev]
87 [--pci_del dev] [--features name:on|off[,...]]
88 [--applyconfig name] [--applyconfig_map group] [--ioprio num]
89 [--iolimit mbps] [--iopslimit iops] [--save] [--force] [--reset_ub]
90 [--setmode restart|ignore]
91 This command sets various container parameters. If the container
93 is currently running, vzctl applies these parameters to the con‐
94 tainer. The following options can be used with set command.
95 Flags
98 --save
100 If this flag is given, parameters are saved in container configura‐
101 tion file ctid.conf(5).
102 --force
104 If this flag is given together with --save, parameters are saved
105 even if the current kernel doesn't support OpenVZ. Note this flag
106 does not make sense without --save, so --save is required.
107 --reset_ub
109 If this flag is given, vzctl applies all User Beancounter parame‐
110 ters from the configuration file to a running container. This is
111 helpful in case configuration file is modified manually. Please
112 note this flag is exclusive, i.e. it can not be combined with any
113 other options or flags.
114 --setmode restart | ignore
116 A few parameters can only be applied by restarting the container.
117 By default, vzctl prints a warning if such parameters are supplied
118 and a container is running. Use --setmode restart together with
119 --save flag to restart a container in such a case, or --setmode
120 ignore to suppress the warning.
121 Miscellaneous
124 --onboot yes | no
126 Sets whether the container will be started during system boot. The
127 container will be started on boot by vz initscript if either this
128 parameter is set to yes, or the container was running just before
129 last reboot, and this parameter is not set to no. Default value is
130 unset, meaning the container will be started if it was running
131 before the last reboot.
132 --bootorder number
134 Sets the boot order priority for this CT. The higher the number is,
135 the earlier in the boot process this container starts. By default
136 this parameter is unset, which is considered to be the lowest pri‐
137 ority, so containers with unset bootorder will start last.
138 --root path
140 Sets the path to root directory (VE_ROOT) for this container. This
141 is essentially a mount point for container's root directory. Argu‐
142 ment can contain literal string $VEID, which will be substituted
143 with the numeric CT ID.
144 --private path
146 Sets the path to private directory (VE_PRIVATE) for this container.
147 This is a directory in which all the container's files are stored.
148 Argument can contain literal string $VEID, which will be substi‐
149 tuted with the numeric CT ID.
150 --mount_opts option[,option...]
152 Sets additional mount options for container file system. Only
153 applicable for ploop layout, ignored otherwise.
154 --userpasswd user:password
156 Sets password for the given user in a container, creating the user
157 if it does not exists. Note that this option is not saved in con‐
158 figuration file at all (so --save flag is useless), it is applied
159 directly to the container, by running distribution-specific pro‐
160 grams inside the container. It is not recommended to combine this
161 option with any other options.
162 In case container was not running, it is automatically started then
164 all the appropriate changes are applied, then it is stopped.
165 Note that container should be created before using this option.
167 --disabled yes | no
169 Disable container start. To force the start of a disabled con‐
170 tainer, use vzctl start --force.
171 --name name
173 Add a name for a container. The name can later be used in subse‐
174 quent calls to vzctl in place of CTID. Note this option can not be
175 used without --save.
176 --description string
178 Add a textual description for a container.
179 --ostemplate string
181 Sets a new value of OSTEMPLATE parameter in container configuration
182 file ctid.conf(5). Requires --save flag. Useful after a
183 change/upgrade of a distribution running inside container, as vzctl
184 uses the value of OSTEMPLATE to run distribution-specific scripts.
185 --stop-timeout seconds
187 Sets a time to wait for container to stop on vzctl stop before
188 forcibly killing it, in seconds. Note this option can not be used
189 without --save flag.
190 Special value of 0 means to use compiled-in default.
192 Networking
195 --ipadd addr
197 Adds an IP address addr to a given container. Address can option‐
198 ally have a netmask specified in the CIDR notation (e.g.
199 10.1.2.3/25). Note that this option is incremental, so addr are
200 added to already existing ones.
201 --ipdel addr | all
203 Removes IP address addr from a container. If you want to remove all
204 the addresses, use --ipdel all.
205 --hostname name
207 Sets container hostname. vzctl writes it to the appropriate file
208 inside a container (distribution-dependent).
209 --nameserver addr
211 Sets DNS server IP address for a container. If you want to set sev‐
212 eral nameservers, you should do it at once, so use --nameserver
213 option multiple times in one call to vzctl, as all the name server
214 values set in previous calls to vzctl are overwritten.
215 A special value of inherit can be used to auto-propagate nameserver
217 value(s) from the host system's /etc/resolv.conf file.
218 --searchdomain name
220 Sets DNS search domains for a container. If you want to set several
221 search domains, you should do it at once, so use --searchdomain
222 option multiple times in one call to vzctl, as all the search
223 domain values set in previous calls to vzctl are overwritten.
224 A special value of inherit can be used to auto-propagate search
226 domain value(s) from the host system's /etc/resolv.conf file.
227 --netif_add ifname[,mac,host_ifname,host_mac,bridge]
229 Adds a virtual Ethernet device (veth) to a given container. Here
230 ifname is the Ethernet device name in the container, mac is its MAC
231 address, host_ifname is the Ethernet device name on the host, and
232 host_mac is its MAC address. MAC addresses should be in the format
233 like XX:XX:XX:XX:XX:XX. bridge is an optional parameter which can
234 be used in custom network start scripts to automatically add the
235 interface to a bridge. All parameters except ifname are optional
236 and are automatically generated if not specified.
237 --netif_del dev_name | all
239 Removes virtual Ethernet device from a container. If you want to
240 remove all devices, use all.
241 veth interface configuration
244 The following options can be used to reconfigure the already-created
246 virtual Ethernet interface. To select the interface to configure, use
247 --ifname name option.
248 --mac XX:XX:XX:XX:XX:XX
250 MAC address of interface inside a container.
251 --host_ifname name
253 interface name for virtual interface in the host system.
254 --host_mac XX:XX:XX:XX:XX:XX
256 MAC address of interface in the host system.
257 If you want an independent communication with the Container
259 through the bridge, you should specify a multicast MAC address
260 here (FE:FF:FF:FF:FF:FF).
261 --bridge name
263 Bridge name. Custom network start scripts can use this value to
264 automatically add the interface to a bridge.
265 --mac_filter on | off
267 Enables/disables MAC address filtering for the Container veth
268 device and the possibility of configuring the MAC address of
269 this device from inside the Container. If the filtering is
270 turned on:
271 · the veth device accepts only those packets that have a MAC
272 address in their headers corresponding to that of this device
273 (excluding all broadcast and multicast packets);
274 · it is impossible to modify the veth MAC address from inside
275 the Container.
276 By default, this functionality is enabled for all veth devices
278 existing inside the Container.
279 VSwap limits
282 The following options sets memory and swap limits for VSwap-enabled
284 kernels (kernel version 042stab042 or greater).
285 Argument is in bytes, unless otherwise specified by an optional suffix.
287 Available suffixes are:
288 · T, t - terabytes;
290 · G, g - gigabytes;
291 · M, m - megabytes;
292 · K, k - kilobytes;
293 · P, p - memory pages (arch-specific, usually 4KB);
294 · B, b - bytes (this is the default).
295 --ram bytes
297 Sets physical memory (RAM) available to a container. Actually,
298 the option is a shortcut for setting --physpages limit (the bar‐
299 rier is set to 0).
300 --swap bytes
302 Set swap space available to a container. Actually, the option
303 is a shortcut for setting --swappages limit (the barrier is set
304 to 0).
305 --vm_overcommit float
307 Set VM overcommitment value to float. If set, it is used to cal‐
308 culate privmmpages parameter in case it is not set explicitly
309 (see below). Default value is 0, meaning unlimited privvmpages.
310 vzctl checks if running kernel is VSwap capable, and refuses to use
312 these parameters otherwise. This behavior can be overriden by using
313 --force flag before parameters.
314 In VSwap mode, all beancounters other than RAM and swap become
316 optional. Note though that if some optional beancounters are not set,
317 they are calculated and set by vzctl implicitly, using the following
318 formulae:
319 · lockedpages.barrier = oomguarpages.barrier = ram
321 · lockedpages.limit = oomguarpages.limit = unlimited
323 · vmguarpages.barrier = vmguarpages.limit = ram + swap
325 · privvmpages.barrier = privvmpages.limit = (ram + swap) * vm_overcom‐
327 mit
328 (if vm_overcommit is 0 or not set, privvmpages is set to "unlimited")
330 Here is an example of setting container 777 to have 512 megabytes of
332 RAM and 1 gigabyte of swap:
333 vzctl set 777 --ram 512M --swap 1G --save
334 User Beancounter limits
337 The following options sets barrier and limit for various user beancoun‐
339 ters.
340 Note that for VSwap-enabled kernels (version 042stab042 or greater)
342 these limits are optional, you must only set --ram and --swap (see
343 above). For older kernels, these limits are obligatory.
344 Each option requires one or two arguments. In case of one argument,
346 vzctl sets barrier and limit to the same value. In case of two colon-
347 separated arguments, the first is a barrier, and the second is a limit.
348 Each argument is either a number, a number with a suffix, or a special
349 value unlimited.
350 Arguments are in items, pages or bytes. Note that page size is archi‐
352 tecture-specific, it is 4096 bytes on x86 and x86_64 platforms.
353 You can also specify different suffixes for User Beancounter parameters
355 (except for those which names start with num). For example, vzctl set
356 CTID --privvmpages 5M:6M should set privvmpages' barrier to 5 megabytes
357 and its limit to 6 megabytes.
358 Available suffixes are:
360 · T, t - terabytes;
362 · G, g - gigabytes;
363 · M, m - megabytes;
364 · K, k - kilobytes;
365 · P, p - memory pages (arch-specific, usually 4KB);
366 · B, b - bytes.
367 You can also specify the literal word unlimited in place of a number.
369 In that case the corresponding value will be set to LONG_MAX, i. e.
370 the maximum possible value.
371 --numproc items[:items]
373 Maximum number of processes and kernel-level threads. Setting
374 the barrier and the limit to different values does not make
375 practical sense.
376 --numtcpsock items[:items]
378 Maximum number of TCP sockets. This parameter limits the number
379 of TCP connections and, thus, the number of clients the server
380 application can handle in parallel. Setting the barrier and the
381 limit to different values does not make practical sense.
382 --numothersock items[:items]
384 Maximum number of non-TCP sockets (local sockets, UDP and other
385 types of sockets). Setting the barrier and the limit to differ‐
386 ent values does not make practical sense.
387 --vmguarpages pages[:pages]
389 Memory allocation guarantee. This parameter controls how much
390 memory is available to a container. The barrier is the amount of
391 memory that container's applications are guaranteed to be able
392 to allocate. The meaning of the limit is currently unspecified;
393 it should be set to unlimited.
394 --kmemsize bytes[:bytes]
396 Maximum amount of kernel memory used. This parameter is related
397 to --numproc. Each process consumes certain amount of kernel
398 memory - 16 KB at least, 30-50 KB typically. Very large pro‐
399 cesses may consume a bit more. It is important to have a certain
400 safety gap between the barrier and the limit of this parameter:
401 equal barrier and limit may lead to the situation where the ker‐
402 nel will need to kill container's applications to keep the kmem‐
403 size usage under the limit.
404 --tcpsndbuf bytes[:bytes]
406 Maximum size of TCP send buffers. Barrier should be not less
407 than 64 KB, and difference between barrier and limit should be
408 equal to or more than value of numtcpsock multiplied by 2.5 KB.
409 --tcprcvbuf bytes[:bytes]
411 Maximum size of TCP receive buffers. Barrier should be not less
412 than 64 KB, and difference between barrier and limit should be
413 equal to or more than value of numtcpsock multiplied by 2.5 KB.
414 --othersockbuf bytes[:bytes]
416 Maximum size of other (non-TCP) socket send buffers. If con‐
417 tainer's processes needs to send very large datagrams, the bar‐
418 rier should be set accordingly. Increased limit is necessary
419 for high performance of communications through local (UNIX-
420 domain) sockets.
421 --dgramrcvbuf bytes[:bytes]
423 Maximum size of other (non-TCP) socket receive buffers. If con‐
424 tainer's processes needs to receive very large datagrams, the
425 barrier should be set accordingly. The difference between the
426 barrier and the limit is not needed.
427 --oomguarpages pages[:pages]
429 Guarantees against OOM kill. Under this beancounter the kernel
430 accounts the total amount of memory and swap space used by the
431 container's processes. The barrier of this parameter is the
432 out-of-memory guarantee. If the oomguarpages usage is below the
433 barrier, processes of this container are guaranteed not to be
434 killed in out-of-memory situations. The meaning of limit is
435 currently unspecified; it should be set to unlimited.
436 --lockedpages pages[:pages]
438 Maximum number of pages acquired by mlock(2).
439 --privvmpages pages[:pages]
441 Allows controlling the amount of memory allocated by the appli‐
442 cations. For shared (mapped as MAP_SHARED) pages, each con‐
443 tainer really using a memory page is charged for the fraction of
444 the page (depending on the number of others using it). For
445 "potentially private" pages (mapped as MAP_PRIVATE), container
446 is charged either for a fraction of the size or for the full
447 size if the allocated address space. In the latter case, the
448 physical pages associated with the allocated address space may
449 be in memory, in swap or not physically allocated yet.
450 The barrier and the limit of this parameter control the upper
452 boundary of the total size of allocated memory. Note that this
453 upper boundary does not guarantee that container will be able to
454 allocate that much memory. The primary mechanism to control mem‐
455 ory allocation is the --vmguarpages guarantee.
456 --shmpages pages[:pages]
458 Maximum IPC SHM segment size. Setting the barrier and the limit
459 to different values does not make practical sense.
460 --numfile items[:items]
462 Maximum number of open files. In most cases the barrier and the
463 limit should be set to the same value. Setting the barrier to 0
464 effectively disables pre-charging optimization for this bean‐
465 counter in the kernel, which leads to the held value being pre‐
466 cise but could slightly degrade file open performance.
467 --numflock items[:items]
469 Maximum number of file locks. Safety gap should be between bar‐
470 rier and limit.
471 --numpty items[:items]
473 Number of pseudo-terminals (PTY). Note that in OpenVZ each con‐
474 tainer can have not more than 255 PTYs. Setting the barrier and
475 the limit to different values does not make practical sense.
476 --numsiginfo items[:items]
478 Number of siginfo structures. Setting the barrier and the limit
479 to different values does not make practical sense.
480 --dcachesize bytes[:bytes]
482 Maximum size of filesystem-related caches, such as directory
483 entry and inode caches. Exists as a separate parameter to impose
484 a limit causing file operations to sense memory shortage and
485 return an errno to applications, protecting from memory short‐
486 ages during critical operations that should not fail. Safety
487 gap should be between barrier and limit.
488 --numiptent num[:num]
490 Number of iptables (netfilter) entries. Setting the barrier and
491 the limit to different values does not make practical sense.
492 --physpages pages[:pages]
494 On VSwap-enabled kernels, this limits the amount of physical
495 memory (RAM) available to a container. The barrier should be set
496 to 0, and the limit to a total size of RAM that can be used used
497 by a container.
498 For older kernels, this is an accounting-only parameter, showing
500 the usage of RAM by this container. Barrier should be set to 0,
501 and limit should be set to unlimited.
502 --swappages pages[:pages]
504 For VSwap-enabled kernels (042stab042 or greater), this parame‐
505 ter limits the amount of swap space available to a container.
506 The barrier should be set to 0, and the limit to a total size of
507 swap that can be used by a container.
508 For older (pre-VSwap) kernels, the limit is used to show a total
510 amount of swap space available inside the container. The barrier
511 of this parameter is ignored. The default value is unlimited,
512 meaning total swap will be reported as 0.
513 CPU fair scheduler parameters
516 These parameters control CPU usage by container.
518 --cpuunits num
520 CPU weight for a container. Argument is positive non-zero num‐
521 ber, passed to and used in the kernel fair scheduler. The larger
522 the number is, the more CPU time this container gets. Maximum
523 value is 500000, minimal is 8. Number is relative to weights of
524 all the other running containers. If cpuunits are not speci‐
525 fied, default value of 1000 is used.
526 You can set CPU weight for CT0 (host system itself) as well (use
528 vzctl set 0 --cpuunits num). Usually, OpenVZ initscript
529 (/etc/init.d/vz) takes care of setting this.
530 --cpulimit num[%]
532 Limit of CPU usage for the container, in per cent. Note if the
533 computer has 2 CPUs, it has total of 200% CPU time. Default CPU
534 limit is 0 (no CPU limit).
535 --cpus num
537 sets number of CPUs available in the container.
538 --cpumask cpus | auto | all
540 Sets list of allowed CPUs for the container. Input format is a
541 comma-separated list of decimal numbers and/or ranges. Consecu‐
542 tively set bits are shown as two hyphen-separated decimal num‐
543 bers, the smallest and largest bit numbers set in the range.
544 For example, if you want the container to execute on CPUs 0, 1,
545 2, 7, you should pass 0-2,7. Default value is all (the con‐
546 tainer can execute on any CPU). If used with the --nodemask
547 option, value of auto assigns all CPUs from the specified NUMA
548 node to a container.
549 --nodemask nodes | all
551 Sets list of allowed NUMA nodes for the container. Input format
552 is the same as for --cpumask. Note that --nodemask must be used
553 with the --cpumask option.
554 Memory output parameters
557 For VSwap-enabled kernels (042stab042 or greater), this parameter is
559 ignored. For older kernels, it controls the output of /proc/meminfo
560 inside a container.
561 --meminfo none
563 No /proc/meminfo virtualization (the same as on host system).
564 --meminfo mode:value
566 Configure total memory output in a container. Reported free mem‐
567 ory is evaluated accordingly to the mode being set. Reported
568 swap is evaluated according to the settings of --swappages
569 parameter.
570 You can use the following modes for mode:
572 · pages:value - sets total memory in pages;
573 · privvmpages:value - sets total memory as privvmpages * value.
574 Default is privvmpages:1.
576 Netfilter (iptables) control parameters
579 --netfilter disabled|stateless|stateful|full
581 Restrict access to netfilter/iptables modules for a container.
582 This option replaces obsoleted --iptables.
583 Note that changing this parameter requires container restart, so
585 consider using --setmode option.
586 The following arguments can be used:
588 · disabled
590 no modules are allowed
591 · stateless
593 all modules except NAT and conntracks are allowed (i.e.
594 filter and mangle); this is the default
595 · stateful
597 all modules except NAT are allowed
598 · full all modules are allowed
600 --iptables name[,...]
602 Note this option is obsoleted, --netfilter should be used
603 instead.
604 Allow to use the functionality of name iptables module inside
606 the container. Multiple comma-separated names can be specified.
607 The default list of enabled iptables modules is defined by the
609 IPTABLES variable in vz.conf(5).
610 You can use the following values for name: iptable_filter, ipt‐
612 able_mangle, ipt_limit, ipt_multiport, ipt_tos, ipt_TOS,
613 ipt_REJECT, ipt_TCPMSS, ipt_tcpmss, ipt_ttl, ipt_LOG,
614 ipt_length, ip_conntrack, ip_conntrack_ftp, ip_conntrack_irc,
615 ipt_conntrack, ipt_state, ipt_helper, iptable_nat, ip_nat_ftp,
616 ip_nat_irc, ipt_REDIRECT, xt_mac, ipt_recent, ipt_owner.
617 Network devices control parameters
620 --netdev_add name
622 move network device from the host system to a specified con‐
623 tainer
624 --netdev_del name
626 delete network device from a specified container
627 Disk quota parameters
630 --diskquota yes | no
632 allows to enable or disable disk quota for a container. By
633 default, a global value (DISK_QUOTA) from vz.conf(5) is used.
634 Note that this parameter is ignored for ploop layout.
636 --diskspace num[:num]
638 For simfs layout, sets soft and hard disk quota limits. First
639 parameter is soft limit, second is hard limit.
640 For ploop layout, initiates the procedure of resizing the ploop
642 image file to the new size. Since there is no soft/hard limit
643 concept in ploop, second num, if specified, is ignored.
644 By default, ploop resize is done online, i.e. on a mounted
646 ploop. This is a preferred way of doing resize. Although, in a
647 rare case a container was using lots of disk space and should
648 now be resized to a much smaller size, an offline resize might
649 be more appropriate. In this case, make sure the container is
650 stopped and unmounted and use additional --offline-resize option
651 Note that ploop resize is NOT performed on container start, so
653 for consistency --diskspace must be used together with --save
654 flag.
655 Suffixes G, M, K can also be specified (see Resource limits sec‐
657 tion for more info on suffixes). If suffix is not specified,
658 value is in kilobytes.
659 --diskinodes num[:num]
661 sets soft and hard disk quota limits, in i-nodes. First parame‐
662 ter is soft limit, second is hard limit.
663 Note that this parameter is ignored for ploop layout.
665 --quotatime seconds
667 sets quota grace period. Container is permitted to exceed its
668 soft limits for the grace period, but once it has expired, the
669 soft limit is enforced as a hard limit.
670 Note that this parameter is ignored for ploop layout.
672 --quotaugidlimit num
674 Enables or disables in-container per-user and per-group disk
675 quotas. If the value is set to 0 or not set, disk quotas inside
676 the container is disabled and not accounted.
677 For simfs layout containers, non-zero value sets maximum number
679 of user/group IDs for which disk quota is accounted.
680 For ploop layout containers, any non-zero value enables disk
682 quota inside the container; the number of user/group IDs used by
683 disk quota is not limited by OpenVZ.
684 Note that enabling or disabling in-container disk quotas
686 requires container restart, so consider using --setmode option.
687 Capability option
690 --capability capname:on|off[,...]
692 Sets a capability for a container. Multiple comma-separated
693 capabilities can be specified.
694 Note that setting a capability when the container is running
696 does not take immediate effect; restart the container in order
697 for the changes to take effect (consider using --setmode
698 option).
699 A container has the default set of capabilities, thus any opera‐
701 tion on capabilities is "logical AND" with the default capabil‐
702 ity mask.
703 You can use the following values for capname: chown, dac_over‐
705 ride, dac_read_search, fowner, fsetid, kill, setgid, setuid,
706 setpcap, linux_immutable, net_bind_service, net_broadcast,
707 net_admin, net_raw, ipc_lock, ipc_owner, sys_module, sys_rawio,
708 sys_chroot, sys_ptrace, sys_pacct, sys_admin, sys_boot,
709 sys_nice, sys_resource, sys_time, sys_tty_config, mknod, lease,
710 setveid, ve_admin. For detailed description, see capabili‐
711 ties(7).
712 WARNING: setting some of those capabilities may have far reach‐
714 ing security implications, so do not do it unless you know what
715 you are doing. Also note that setting setpcap:on for a container
716 will most probably lead to inability to start it.
717 Device access management
720 --devnodes device:[r][w][q]|none
722 Give the container an access (r - read, w - write, q - disk
723 quota management, none - no access) to a device designated by
724 the special file /dev/device. Device file is created in a con‐
725 tainer by vzctl. Example:
726 vzctl set 777 --devnodes sdb:rwq
727 --devices b|c:major:minor|all:[r][w][q]|none
729 Give the container an access to a block or character device des‐
730 ignated by its major and minor numbers. Device file have to be
731 created manually.
732 PCI device management
735 --pci_add [domain:]bus:slot.func
737 Give the container an access to a specified PCI device. All num‐
738 bers are hexadecimal (as printed by lspci(8) in the first col‐
739 umn).
740 --pci_del [domain:]bus:slot.func
742 Delete a PCI device from the container.
743 Note that vps-pci configuration script is executed by vzctl then
745 configuring PCI devices. The script is usually located at
746 /usr/libexec/vzctl/scripts/.
747 Features management
750 --features name:on|off[,...]
752 Enable or disable a specific container feature. Known features
753 are: sysfs, nfs, sit, ipip, ppp, ipgre, bridge, nfsd. A few fea‐
754 tures can be specified at once, comma-separated.
755 Apply config
758 --applyconfig name
760 Read container parameters from the container sample configura‐
761 tion file /etc/vz/conf/ve-name.conf-sample, and apply them, if
762 --save option specified save to the container config file. The
763 following parameters are not changed: HOSTNAME, IP_ADDRESS,
764 OSTEMPLATE, VE_ROOT, and VE_PRIVATE.
765 --applyconfig_map group
767 Apply container config parameters selected by group. Now the
768 only possible value for group is name: to restore container name
769 based on NAME variable in container configuration file.
770 I/O scheduling
773 --ioprio priority
775 Assigns disk I/O priority to container. Priority range is 0-7.
776 The greater priority is, the more time for I/O activity con‐
777 tainer has. By default each container has priority of 4.
778 --iolimit limit[B|K|M|G]
780 Assigns disk I/O bandwidth limit for a container. Value is
781 either a number with an optional suffix, or a literal string
782 unlimited. Value of 0 means "unlimited". By default a container
783 has no I/O limit. Maximum allowed limit is 2 gigabytes per sec‐
784 ond; values exceeding the limit are truncated.
785 If no suffix is provided, the limit is assumed to be in
787 megabytes per second. Available suffixes are:
788 · b, B -- bytes per second;
789 · k, K -- kilobytes per second;
790 · m, M -- megabytes per second (default);
791 · g, G -- gigabytes per second;
792 --iopslimit iops
794 Assigns IOPS limit for a container, in number of input/output
795 operations per second. Value is a number or a literal string
796 unlimited. Value of 0 means "unlimited". By default a container
797 has no IOPS limit.
798 Suspending and resuming
801 Checkpointing is a feature of OpenVZ kernel which allows to save a com‐
802 plete in-kernel state of a running container, and to restore it later.
803 suspend|chkpnt CTID [--dumpfile name]
805 This command suspends a container to a dump file If an option
806 --dumpfile is not set, default dump file name
807 /var/lib/vz/dump/Dump.CTID is used.
808 resume|restore CTID [--dumpfile name]
810 This command restores a container from the dump file created by the
811 suspend command.
812 Snapshotting
815 Snapshotting is a feature based on checkpointing and ploop shapshots.
816 It allows to save a complete state of container file system. Plus, if
817 the container is running, it's in-memory state (as in checkpointing).
818 Note that snapshot functionality is only working for containers on
819 ploop device.
820 snapshot CTID [--id uuid] [--name name] [--description desc] [--skip-
822 suspend] [--skip-config]
823 Creates a container snapshot, i.e. saves the current container
824 state, including its file system state, running processes state,
825 and configuration file.
826 If a container is running, and --skip-suspend option is not speci‐
828 fied, a container is checkpointed and then restored, and CT memory
829 dump becomes the part of snapshot.
830 Unless --skip-config option is given, container configuration file
832 is saved to the snapshot.
833 If uuid is not specified, it is auto-generated. Options --name and
835 --description can be used to specify the snapshot name and descrip‐
836 tion, respectively. Name is displayed by snapshot-list.
837 snapshot-switch CTID [--skip-resume | --must-resume] [--skip-config]
839 --id uuid
840 Switches the container to a snapshot identified by uuid, restoring
841 its file system state, configuration (if available) and its running
842 state (if available).
843 Note that the current state of a container (including its file sys‐
845 tem state and its configuration file) is lost!
846 Option --skip-resume is used to ignore a CT memory dump file in a
848 snapshot, as a result the container will end up being in a stopped
849 state (same as if a snapshot has been taken with --skip-suspend).
850 If option --must-resume is set, absense of a memory dump is treated
852 as an error, and the inability to restore from the memory dump is
853 treated as an error rather than warning.
854 Option option --skip-config is used to ignore the CT configuration
856 file in a snapshot, i.e. the current configuration file will be
857 left as is.
858 snapshot-delete CTID --id uuid
860 Removes a specified snapshot.
861 snapshot-mount CTID --id uuid --target directory
863 Mounts a snapshot specified by uuid to a directory. Note this mount
864 is read-only.
865 snapshot-umount CTID --id uuid
867 Unmounts a specified snapshot.
868 snapshot-list CTID [-H] [-o field[,field...] [--id uuid]
870 List container's snapshots.
871 You can suppress displaying header using -H option.
873 You can use the -o option to display only the specified field(s).
875 List of available fields can be obtained using -L option.
876 Performing container actions
879 create CTID [--ostemplate name] [--config name]
880 [--layout simfs|ploop[:{expanded|plain|raw}]]
881 [--diskspace kbytes] [--diskinodes num] [--private path]
882 [--root path] [--ipadd addr] [--hostname name] [--name name]
883 [--local_uid uid] [--local_gid gid]
884 Creates a new container area. This operation should be done once,
886 before the first start of the container.
887 By default, an OS template denoted by DEF_OSTEMPLATE parameter of
889 vz.conf(5) is used to create a container. This can be overwritten
890 by --ostemplate option.
891 By default, a new container configuration file is created from a
893 sample configuration denoted by value of CONFIGFILE parameter of
894 vz.conf(5). If the container configuration file already exists, it
895 will not be modified.
896 The value of CONFIGFILE can be overwritten by using the --config
898 name option. This option can not be used if the container configu‐
899 ration file already exists.
900 A new container can either be created using simfs filesystem or on
902 a ploop device. The default is set by value of VE_LAYOUT parameter
903 of vz.conf(5) and can be overwritten by --layout option. In case
904 ploop is used, one can additionally specify ploop disk image format
905 after a colon. Possible ploop formats are expanded, plain and raw.
906 Default is expanded. Using value other than expanded is not recom‐
907 mended and is currently not supported.
908 You can use --diskspace and --diskinodes options to specify con‐
910 tainer file system size. Note that for ploop layout, you will not
911 be able to change inodes value later.
912 If DISKSPACE is not specified either in the sample configuration
914 file used for creation or in global configuration file vz.conf(5),
915 --diskspace parameter is required for ploop layout.
916 Suffixes G, M, K can also be specified (see Resource limits section
918 for more info on suffixes).
919 You can use --root path option to sets the path to the mount point
921 for the container root directory (default is VE_ROOT specified in
922 vz.conf(5) file). Argument can contain literal string $VEID, which
923 will be substituted with the numeric CT ID.
924 You can use --private path option to set the path to directory in
926 which all the files and directories specific to this very container
927 are stored (default is VE_PRIVATE specified in vz.conf(5) file).
928 Argument can contain literal string $VEID, which will be substi‐
929 tuted with the numeric CT ID.
930 You can use --ipadd addr option to assign an IP address to a con‐
932 tainer. Note that this option can be used multiple times.
933 You can use --hostname name option to set a host name for a con‐
935 tainer.
936 When running with an upstream Linux Kernel that supports user
938 namespaces (>= 3.8), the parameters --local_uid and --local_gid can
939 be used to select which uid and gid respectively will be used as a
940 base user in the host system. Note that user namespaces provide a
941 1:1 mapping between container users and host users. If these
942 options are not specified, the values LOCAL_UID and LOCAL_GID from
943 global configuration file vz.conf(5) are used. An explicit
944 --local_uid value of 0 will disable user namespace support, and run
945 the container as a privileged user. In this case, --local_gid is
946 ignored.
947 Warning: use --local_uid and --local_gid with care, specially when
949 migrating containers. In all situations, the container's files in
950 the filesystem needs to be correctly owned by the host-side users.
951 destroy | delete CTID
954 Removes a container private area by deleting all files, directories
955 and the configuration file of this container.
956 start CTID [--wait] [--force] [--skip-fsck] [--skip-remount]
958 Mounts (if necessary) and starts a container. Unless --wait option
959 is specified, vzctl will return immediately; otherwise an attempt
960 to wait till the default runlevel is reached will be made by vzctl.
961 Specify --force if you want to start a container which is disabled
963 (see --disabled).
964 Specify --skip-fsck to skip fsck for ploop-based container filesys‐
966 tem (this option is used by vz initscript).
967 By default, if a container to be started happens to be already
969 mounted, it is unmounted and mounted again. This behavior can be
970 turned off by using --skip-remount flag.
971 Note that this command can lead to execution of premount, mount and
973 start action scripts (see ACTION SCRIPTS below).
974 stop CTID [--fast] [--skip-umount]
976 Stops a container and unmounts it (unless --skip-umount is given).
977 Normally, halt(8) is executed inside a container; option --fast
978 makes vzctl use reboot(2) syscall instead which is faster but can
979 lead to unclean container shutdown.
980 Note that vzctl stop is not asyncronous, in other words vzctl waits
982 for container's init to exit (unless --fast is given), which can
983 take up to a few minutes. Default wait timeout is 120 seconds; it
984 can be changed globally, by setting STOP_TIMEOUT in vz.conf(5), or
985 per container (STOP_TIMEOUT in ctid.conf(5), see --stop-timeout).
986 Note that this command can lead to execution of stop, umount and
988 postumount action scripts (see ACTION SCRIPTS below).
989 restart CTID [--wait] [--force] [--fast] [--skip-fsck]
991 Restarts a container, i.e. stops it if it is running, and starts
992 again. Accepts all the start and stop options.
993 Note that this command can lead to execution of some action scripts
995 (see ACTION SCRIPTS below).
996 status CTID
998 Shows a container status. This is a line with five or six words,
999 separated by spaces.
1000 First word is literally CTID.
1002 Second word is the numeric CT ID.
1004 Third word is showing whether this container exists or not, it can
1006 be either exist or deleted.
1007 Fourth word is showing the status of the container filesystem, it
1009 can be either mounted or unmounted.
1010 Fifth word shows if the container is running, it can be either run‐
1012 ning or down.
1013 Sixth word, if exists, is suspended. It appears if a dump file
1015 exists for a stopped container (see suspend).
1016 This command can also be usable from scripts.
1018 mount CTID
1020 Mounts container private area. Note that this command can lead to
1021 execution of premount and mount action scripts (see ACTION SCRIPTS
1022 below).
1023 umount CTID
1025 Unmounts container private area. Note that this command can lead to
1026 execution of umount and postumount action scripts (see ACTION
1027 SCRIPTS below).
1028 Note that stop does umount automatically.
1030 convert CTID [--layout ploop[:{expanded|plain|raw}]]
1032 Convert CT private area to reside on a ploop device (available in
1033 kernel version 042stab052.8 and greater). Conversion should be per‐
1034 formed when a container is stopped, plus disk space quota should be
1035 set.
1036 compact CTID
1038 Compact container image. This only makes sense for ploop layout.
1039 quotaon CTID
1041 Turn disk quota on. Not that mount and start does that automati‐
1042 cally.
1043 quotaoff CTID
1045 Turn disk quota off. Not that umount and stop does that automati‐
1046 cally.
1047 quotainit CTID
1049 Initialize disk quota (i.e. run vzquota init) with the parameters
1050 taken from the CT configuration file ctid.conf(5).
1051 exec CTID command
1053 Executes command in a container. Environment variables are not set
1054 inside the container. Signal handlers may differ from default set‐
1055 tings. If command is -, commands are read from stdin.
1056 exec2 CTID command
1058 The same as exec, but return code is that of command.
1059 runscript CTID script
1061 Run specified shell script in the container. Argument script is a
1062 file on the host system which contents is read by vzctl and exe‐
1063 cuted in the context of the container. For a running container, the
1064 command jumps into the container and executes the script. For a
1065 stopped container, it enters the container, mounts container's root
1066 filesystem, executes the script, and unmounts CT root. In the lat‐
1067 ter case, the container is not really started, no file systems
1068 other than root (such as /proc) are mounted, no startup scripts are
1069 executed etc. Thus the environment in which the script is running
1070 is far from normal and is only usable for very basic operations.
1071 enter CTID [--exec command [arg ...]]
1073 Enters into a container (giving a container's root shell). This
1074 option is a back-door for host root only. The proper way to have CT
1075 root shell is to use ssh(1).
1076 Option --exec is used to run command with arguments after entering
1078 into container. This is useful if command to be run requires a ter‐
1079 minal (so vzctl exec can not be used) and for some reason you can
1080 not use ssh(1).
1081 You need to log out manually from the shell to finish session (even
1083 if you specified --exec).
1084 console CTID [ttynum]
1086 Attach to a container console. Optional ttynum argument is tty num‐
1087 ber (such as 4 for tty4), default is 1 which is used for con‐
1088 tainer's /dev/console.
1089 Note the consoles are persistent, meaning that:
1091 · it can be attached to even if the container is not running;
1092 · there is no automatic detachment upon the container stop;
1093 · detaching from the console leaves anything running in this con‐
1094 sole as is.
1095 The following escape sequences are recognized by vzctl console.
1097 Note that these sequences are only recognized at the beginning of a
1098 line.
1099 · Esc then . to detach from the console.
1101 · Esc then ! to kill anything running on the console (SAK). This is
1103 helpful when one expects a login prompt but there isn't one.
1104 Other options
1107 --help
1108 Prints help message with a brief list of possible options.
1109 --version
1111 Prints vzctl version.
1112
1114 vzctl has an ability to execute user-defined scripts when a specific
1115 vzctl command is run for a container. The following vzctl commands can
1116 trigger execution of action scripts: start, stop, restart, mount and
1117 umount.
1118 Action scripts are located in the /etc/vz/conf/ directory. There are
1120 global and per-CT scripts. Global scripts have a literal prefix of vps.
1121 and are executed for all containers. Per-CT scripts have a CTID.
1122 numeric prefix and are executed for the given container only.
1123 Please note scripts are executed in a host system (CT0) context, with
1125 the exception of .start and .stop scripts, which are executed in a con‐
1126 tainer context.
1127 The following action scripts are currently defined:
1129 vps.premount, CTID.premount
1131 Global and per-CT mount scripts which are executed for a con‐
1132 tainer before it is mounted. Scripts are executed in the host
1133 system context, while a CT is not yet mounted or running. Global
1134 script, if exists, is executed first.
1135 vps.mount, CTID.mount
1137 Global and per-CT mount scripts which are executed for a con‐
1138 tainer right after it is mounted. Otherwise they are the same as
1139 .premount scripts.
1140 CTID.start
1142 Right after vzctl has started a container, it executes this
1143 script in a container context.
1144 CTID.stop
1146 Right before vzctl has stopped a container, it executes this
1147 script in a container context.
1148 vps.umount, CTID.umount
1150 Global and per-CT umount scripts which are executed for a con‐
1151 tainer before it is unmounted. Scripts are executed in the host
1152 system context, while a CT is mounted. Global script, if exists,
1153 is executed first.
1154 vps.postumount, CTID.postumount
1156 Global and per-CT umount scripts which are executed for a con‐
1157 tainer right after it is unmounted. Otherwise they are the same
1158 as .umount scripts.
1159 The environment passed to all the *mount scripts is the standard envi‐
1161 ronment of the parent (i.e. vzctl) with two additional variables: $VEID
1162 and $VE_CONFFILE. The first one holds the ID of the container, and the
1163 second one holds the full path to the container configuration file. If
1164 the script needs to get other CT configuration parameters, such as
1165 $VE_ROOT, it needs to get those from global and per-CT configuration
1166 files.
1167 Here is an example of a mount script, which makes host system's
1169 /mnt/disk available to container(s). Script name can either be
1170 /etc/vz/conf/vps.mount or /etc/vz/conf/CTID.mount.
1171 # If one of these files does not exist then something
1173 # is really broken
1174 [ -f /etc/vz/vz.conf ] || exit 1
1175 [ -f $VE_CONFFILE ] || exit 1
1176 # Source both files. Note the order is important.
1177 . /etc/vz/vz.conf
1178 . $VE_CONFFILE
1179 SRC=/mnt/disk
1180 DST=/mnt/disk
1181 mount -n -t simfs $SRC ${VE_ROOT}${DST} -o $SRC
1182
1184 Returns 0 upon success, or an appropriate error code in case of an
1185 error:
1186 1 Failed to set a UBC parameter
1188 2 Failed to set a fair scheduler parameter
1190 3 Generic system error
1192 5 The running kernel is not an OpenVZ kernel (or some OpenVZ mod‐
1194 ules are not loaded)
1195 6 Not enough system resources
1197 7 ENV_CREATE ioctl failed
1199 8 Command executed by vzctl exec returned non-zero exit code
1201 9 Container is locked by another vzctl invocation
1203 10 Global OpenVZ configuration file vz.conf(5) not found
1205 11 A vzctl helper script file not found
1207 12 Permission denied
1209 13 Capability setting failed
1211 14 Container configuration file ctid.conf(5) not found
1213 15 Timeout on vzctl exec
1215 16 Error during vzctl suspend
1217 17 Error during vzctl resume
1219 18 Error from setluid() syscall
1221 20 Invalid command line parameter
1223 21 Invalid value for command line parameter
1225 22 Container root directory (VE_ROOT) not set
1227 23 Container private directory (VE_PRIVATE) not set
1229 24 Container template directory (TEMPLATE) not set
1231 28 Not all required UBC parameters are set, unable to start con‐
1233 tainer
1234 29 OS template is not specified, unable to create container
1236 31 Container not running
1238 32 Container already running
1240 33 Unable to stop container
1242 34 Unable to add IP address to container
1244 40 Container not mounted
1246 41 Container already mounted
1248 43 Container private area not found
1250 44 Container private area already exists
1252 46 Not enough disk space
1254 47 Bad/broken container (/sbin/init or /bin/sh not found)
1256 48 Unable to create a new container private area
1258 49 Unable to create a new container root area
1260 50 Unable to mount container
1262 51 Unable to unmount container
1264 52 Unable to delete a container
1266 53 Container private area not exist
1268 60 vzquota on failed
1270 61 vzquota init failed
1272 62 vzquota setlimit failed
1274 63 Parameter DISKSPACE not set
1276 64 Parameter DISKINODES not set
1278 65 Error setting in-container disk quotas
1280 66 vzquota off failed
1282 67 ugid quota not initialized
1284 71 Incorrect IP address format
1286 74 Error changing password
1288 78 IP address already in use
1290 79 Container action script returned an error
1292 82 Config file copying error
1294 86 Error setting devices (--devices or --devnodes)
1296 89 IP address not available
1298 91 OS template not found
1300 99 Ploop is not supported by either the running kernel or vzctl.
1302 100 Unable to find container IP address
1304 104 VE_NETDEV ioctl error
1306 105 Container start disabled
1308 106 Unable to set iptables on a running container
1310 107 Distribution-specific configuration file not found
1312 109 Unable to apply a config
1314 129 Unable to set meminfo parameter
1316 130 Error setting veth interface
1318 131 Error setting container name
1320 133 Waiting for container start failed
1322 139 Error saving container configuration file
1324 148 Error setting container IO parameters (ioprio)
1326 150 Ploop image file not found
1328 151 Error creating ploop image
1330 152 Error mounting ploop image
1332 153 Error unmounting ploop image
1334 154 Error resizing ploop image
1336 155 Error converting container to ploop layout
1338 156 Error creating ploop snapshot
1340 157 Error merging ploop snapshot
1342 158 Error deleting ploop snapshot
1344 159 Error switching ploop snapshot
1346 166 Error compacting ploop image
1348 167 Error listing ploop snapsots
1350
1352 To create and start "basic" container with ID of 1000 using centos-5 OS
1353 template and IP address of 192.168.10.200:
1354 vzctl create 1000 --ostemplate centos-5 --config basic
1356 vzctl set 1000 --ipadd 192.168.10.200 --save
1357 vzctl start 1000
1358 To set number of processes barrier/limit to 80/100, and PTY bar‐
1360 rier/limit to 16/20 PTYs:
1361 vzctl set 1000 --numproc 80:100 -t 16:20 --save
1363 To execute command ls -la in this container:
1365 vzctl exec 1000 /bin/ls -la
1367 To execute command pipe ls -l / | sort in this container:
1369 vzctl exec 1000 'ls -l / | sort'
1371 To enter this container and execute command apt-get install vim:
1373 vzctl enter 1000 --exec apt-get install vim
1375 Note that in the above example you will need to log out from the con‐
1377 tainer's shell after apt-get finishes.
1378 To enter this container, execute command apt-get install vim and logout
1380 after successful installation (or stay inside the container if instal‐
1381 lation process failed) use &&:
1382 vzctl enter 1000 --exec "apt-get install vim && logout"
1384 To enter this container, execute command apt-get install vim and logout
1386 independently of exit code of installation process use ;:
1387 vzctl enter 1000 --exec "apt-get install vim ; logout"
1389 Note that you need to quote the command if you use && or ;.
1391 To stop this container:
1393 vzctl stop 1000
1395 To permanently remove this container:
1397 vzctl destroy 1000
1399
1401 /etc/vz/vz.conf
1402 /etc/vz/conf/CTID.conf
1403 /etc/vz/conf/vps.{premount,mount,umount,postumount}
1404 /etc/vz/conf/CTID.{premount,mount,start,stop,umount,postumount}
1405 /proc/vz/veinfo
1406 /proc/vz/vzquota
1407 /proc/user_beancounters
1408 /proc/bc/*
1409 /proc/fairsched
1410
1412 vz.conf(5), ctid.conf(5), arpsend(8), vzcalc(8), vzcfgvalidate(8),
1413 vzcpucheck(8), vzifup-post(8), vzlist(8), vzmemcheck(8), vzmigrate(8),
1414 vzpid(8), vzquota(8), vzsplit(8), vzubc(8), http://wiki.openvz.org/UBC.
1415
1417 Copyright (C) 2000-2013, Parallels, Inc. Licensed under GNU GPL.
1418OpenVZ 3 Jul 2014 vzctl(8)