vzctl(8)                     Virtual Environments                     vzctl(8)



NAME
       vzctl - utility to control a Virtual Environment.

SYNOPSIS
       vzctl [flags] create veid --ostemplate name] [--config name] [--private
       path] [--root path] [--ipadd addr] [--hostname name]

       vzctl [flags] set veid [parameters] [--save]

       vzctl [flags] destroy | mount | umount | start | stop | restart |
       status | enter veid

       vzctl [flags] exec | exec2 veid command [arg ...]

       vzctl runscript veid <script>

       vzctl --help | --version

DESCRIPTION
       Utility vzctl runs on Hardware Node (HN) and performs direct
       manipulations with Virtual Environments (VEs).

       Virtual Environments can be referred to by either numeric veid or by
       name (see --name option). Note that VE ID <= 100 are reserved for
       OpenVZ internal purposes.

OPTIONS
   Flags
       These flags can be used with almost any option.

       --quiet
           Disables logging to log file and screen.

       --verbose
           Sets logging level to maximum value.

   Setting VE parameters
       set veid [parameters] [--save]
           This command sets various VE parameters. If flag --save is given,
           parameters are saved in VE configuration file vps.conf(5).  If VE
           is currently running, vzctl applies these parameters to VE.

           The following options can be used with set command.

       Miscellaneous parameters

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

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

       --userpasswd user:password
           Sets password for the given user in VE, 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 VE (by modifying its /etc/passwd and /etc/shadow files).

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

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

       --disabled yes|no
           Disable VE start. To force the start of a disabled VE, use vzctl
           start with -force option.

       --name name
           Add a name for a VE. The name can later be used in subsequent calls
           to vzctl in place of veid.

       Network related parameters

       --ipadd addr
           Adds IP address to a given VE. Note that this option is
           incremental, so addr are added to already existing ones.

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

       --hostname name
           Sets VE hostname. vzctl writes it to the appropriate file inside a
           VE (distribution-dependent).

       --nameserver addr
           Sets DNS server IP address for a VE. 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 a VE. 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.

       --netif_add ifname[,mac,host_ifname,host_mac]
           Adds a virtual ethernet device (veth) to a given VE. Here ifname is
           the ethernet device name in the VE, mac is its MAC address,
           host_ifname is the ethernet device name on the host, and host_mac
           is its MAC address. MAC addresses should be in the format like
           XX:XX:XX:XX:XX:XX. All parameters except ifname are optional and
           are automatically generated if not specified.

           Interface configuration.

           The following options can be used to reconfigure the already-
           created virtual ethernet interface. To select the interface to
           configure, use --ifname name option.

            --mac XX:XX:XX:XX:XX:XX - MAC address of interface inside VE.
            --host_ifname name - interface name for virtual interface in VE0.
            --host_mac XX:XX:XX:XX:XX:XX - MAC address of interface in VE0.

       --netif_del dev_name|all
           Removes virtual ethernet device from VE. If you want to remove all
           devices, use all.

       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 page size is
           architecture-specific, it is 4096 bytes on IA32 platform.

           You can also specify different suffixes for set parameters (except
           for the parameters which names start with num).  For example, vzctl
           set veid --privvmpages 5M:6M should set privvmpages' barrier to 5
           megabytes and its limit to 6 megabytes.

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


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

       --numtcpsock items[:items]
           Maximum number of TCP sockets. This parameter limits the number of
           TCP connections and, thus, the number of clients the server
           application can handle in parallel.  Setting the barrier and the
           limit to different values does not make practical sense.

       --numothersock items[:items]
           Maximum number of non-TCP sockets (local sockets, UDP and other
           types of sockets).  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 a VE. The barrier is the amount of memory
           that VE'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.

       --kmemsize bytes[:bytes]
           Maximum amount of kernel memory used. This parameter is related to
           --numproc. Each process consumes certain amount of kernel memory -
           16 KB at leas, 30-50 KB typically. Very large processes may consume
           a bit more. It is important to have a certain safety gap between
           the barrier and the limit of this parameter: equal barrier and
           limit may lead to the situation where the kernel will need to kill
           VE applications to keep the kmemsize usage under the limit.

       --tcpsndbuf bytes[:bytes]
           Maximum size of TCP send buffers.  Barrier should be not less than
           64 KB, and difference between barrier and limit should be equal to
           or more than value of numtcpsock multiplied by 2.5 KB.

       --tcprcvbuf bytes[:bytes]
           Maximum size of TCP receive buffers.  Barrier should be not less
           than 64 KB, and difference between barrier and limit should be
           equal to or more than value of numtcpsock multiplied by 2.5 KB.

       --othersockbuf bytes[:bytes]
           Maximum size of other (non-TCP) socket send buffers. If VE
           processes needs to send very large datagrams, the barrier should be
           set accordingly.  Increased limit is necessary for high performance
           of communications through local (UNIX-domain) sockets.

       --dgramrcvbuf bytes[:bytes]
           Maximum size of other (non-TCP) socket receive buffers. If VE
           processes needs to send very large datagrams, the barrier should be
           set accordingly.  The difference between the barrier and the limit
           is not needed.

       --oomguarpages pages[:pages]
           Guarantees against OOM kill. Under this beancounter the kernel
           accounts the total amount of memory and swap space used by the VE
           processes. The barrier of this parameter is the out-of-memory
           guarantee. If the oomguarpages usage is below the barrier,
           processes of this VE are guaranteed not to be killed in out-of-
           memory situations. The meaning of limit is currently unspecified;
           it should be set to 2,147,483,647.

       --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 VE
           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), VE 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 VE 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.

       --numfile items[:items]
           Maximum number of open files.  Setting the barrier and the limit to
           different values does not make practical sense.

       --numflock items[:items]
           Maximum number of file locks. Safety gap should be between barrier
           and limit.

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

       --numsiginfo items[:items]
           Number of siginfo structures.  Setting the barrier and the limit to
           different values does not make practical sense.

       --dcachesize bytes[:bytes]
           Maximum size of filesystem-related caches, such as directory entry
           and inode caches. Exists as a separate parameter to impose a limit
           causing file operations to sense memory shortage and return an
           errno to applications, protecting from memory shortages during
           critical operations that should not fail.  Safety gap should be
           between barrier and limit.

       --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 is currently an accounting-only parameter. It shows the usage
           of RAM by this VE. Barrier should be set to 0, and limit should be
           set to 2,147,483,647.

       CPU fair scheduler parameters
           These parameters control CPU usage by VE.

       --cpuunits num
           CPU weight for a VE. Argument is positive non-zero number, which
           passed to and used in kernel fair scheduler. The larger the number
           is, the more CPU time this VE get. Maximum value is 500000, minimal
           is 8. Number is relative to weights of all the other running VEs.
           If cpuunits not specified default value 1000 ia used.

           You can set CPU weight for VE0 (hardware node itself) as well (use
           vzctl set 0 --cpuunits num). Usually, OpenVZ initscript
           (/etc/init.d/vz) takes care of setting this.

       --cpulimit num[%]
           Limit of CPU usage for the VE, in per cent.  Note if the computer
           has 2 CPUs, it has total of 200% CPU time. Default CPU limit is 0
           (no CPU limit).  --cpus num sets number of CPUs available in the
           VE.

       Memory output parameters
           This parameter control output of /proc/meminfo inside a VE

       --meminfo none
           No /proc/meminfo virtualization (the same as on host system).

       --meminfo mode:value
           Configure total memory output in a VE. Free memory is evaluated
           accordingly to the mode being set.
           You can use the following modes for mode:
           pages:value - sets total memory in pages
           privvmpages:value - sets total memory as privvmpages * value

       Iptables control parameters

       --iptables name
           Restrict access to iptables modules inside a VE (by default all
           iptables modules that are loaded in the host system are accessible
           inside a VE).

           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_REDIRECT xt_mac.

       Network devices control parameters

       --netdev_add name
           move network device from VE0 to a specified VE

       --netdev_del name
           delete network device from a specified VE

       Disk quota parameters

       --diskspace num[:num]
           sets soft and hard disk quotas, in blocks. First parameter is soft
           quota, second is hard quota. One block is currently equal to 1Kb.
           Also suffixes  G, M, K can be specified (see Resource limits
           section for more info).

       --diskinodes num[:num]
           sets soft and hard disk quotas, in i-nodes. First parameter is soft
           quota, second is hard quota.

       --quotatime seconds
           sets soft overusage time limit for disk quota (also known as grace
           period).

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

           Note that if you have previously set value of this parameter to 0,
           changing it while the VE is running will not take effect.

       Mount option

       --noatime yes|no
           Sets noatime flag (do not update inode access times) on file
           system.

       Capability option

       --capability capname:on|off
           Sets capability inside a VE. Note that setting capability when the
           VE is running does not take immediate effect; restart VE in order
           for changes to take effect. Note a VE has default set of
           capability, any operations on capability is logical and with
           default capability mask.

           You can use the following values for capname: chown, dac_override,
           dac_read_search, fowner, fsetid, kill, setgid, setuid, setpcap,
           linux_immutable, net_bind_service, net_broadcast, net_admin,
           net_raw, ipc_lock, ipc_owner, sys_module, sys_rawio, sys_chroot,
           sys_ptrace, sys_pacct, sys_admin, sys_boot, sys_nice, sys_resource,
           sys_time, sys_tty_config, mknod, lease, setveid, ve_admin.

       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 a VE.

       Features management

       --features name:on|off
           Enable disable specific VE feature. Known features are: sysfs, nfs.

           Apply config

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

       --applyconfig_map name
           Apply VE config parameters selected by name group, now only name
           argument supported. Restore VE name based on NAME variable in VE
           configuration file.

   Checkpointing and restore
       Checkpointing is a feature of OpenVZ kernel which allows to save a
       complete
              state of a running VE, and to restore it later.

       chkpnt veid [--dumpfile name]
              This command saves a complete state of a running VE to a dump
              file, and stops the VE. If an option --dumpfile is not set,
              default dump file name /vz/dump/Dump.veid is used.

       restore veid [--dumpfile name]
              This command restores a VE from dump file created by the chkpnt
              command.

   Performing VE actions
       create veid [--ostemplate name] [--config name] [--private path]
       [--root path] [--ipadd addr] [--hostname name]
           Creates a new VE area. This operation should be done once, before
           the first start of the VE.

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

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

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

           You can use --ipadd addr option to assign an IP address to a VE.
           Note that this option can be used multiple times.

           You can use --hostname name option to set a host name for a VE.


       destroy
           Removes a VE private area by deleting all files, directories and
           configuration file of this VE.

       start [---wait]
           Mounts (if necessary) and starts a VE. if --wait option specified
           wait until default runlevel is entered.

       stop
           Stops and unmounts a VE.

       restart
           Restarts a VE, i.e. stops it if it is running, and starts again.

       status
           Shows a VE status. Basically this is a line with five words
           separated by spaces.  First word is literally VEID. Second word is
           the numeric VE ID.  Third word is showing whether this VE exists or
           not, it can be either exist or deleted.  Fourth word is showing the
           status of the VE filesystem, it can be either mounted or unmounted.
           Fifth word shows if the VE is running, it can be either running or
           down.

           This command can also be usable from scripts.

       mount
           Mounts VE private area.

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

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

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

       runscript
           Run specified shell script in a VE, if the VE is not runnning it
           will be started.

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

   Other options
       --help
           Prints help message with a brief list of possible options.

       --version
           Prints vzctl version.

DIAGNOSTICS
       Returns 0 upon success.

EXAMPLES
       To create and start "basic" VE with ID of 1000, using fedora-core-5 OS
       template, and IP address of 192.168.10.200:
            vzctl create 1000 --ostemplate fedora-core-5 --config vps.basic
            vzctl set 1000 --ipadd 192.168.10.200 --save
            vzctl start 1000
        To set number of processes barrier/limit to 80/100, and PTY
       barrier/limit to 16/20 PTYs:
            vzctl set 1000 --numproc 80:100 -t 16:20 --save

       To execute command ls -la in this VE:
            vzctl exec 1000 /bin/ls -la

       To execute command pipe ls -l / | sort in this VE:
            vzctl exec 1000 'ls -l / | sort'

       To stop this VE:
            vzctl stop 1000

       To permanently remove this VE:
            vzctl destroy 1000

FILES
        /etc/vz/vz.conf
       /etc/vz/conf/veid.conf
       /proc/vz/veinfo
       /proc/vz/vzquota
       /proc/user_beancounters
       /proc/fairsched

SEE ALSO
       vz.conf(5), vps.conf(5), vzquota(8),

LICENSE
       Copyright (C) 2000-2007, SWsoft. Licensed under GNU GPL v2.



OpenVZ                            12 Jan 2007                         vzctl(8)