vzctl(8)                    Virtual Private Server                    vzctl(8)



NAME
       vzctl - utility to control Virtual Private Server.

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

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

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

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

       vzctl runscript ve_id <script>

       vzctl --help | --version

DESCRIPTION
       Utility vzctl runs on Hardware Node (HN) and performs direct
       manipulations with virtual private server (VPS).

       Virtual Private Servers can be referred to by numeric vpsid. Note that
       VPS 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 VPS parameters
       set vpsid [parameters] [--save]
           This command sets various VPS parameters. If flag --save is given,
           parameters are saved in VPS configuration file vps.conf(5).  If VPS
           is currently running, vzctl applies these parameters to VPS.

           The following options can be used with set command.

       Miscellaneous parameters

       --onboot yes|no
           Sets whether this VPS will be started during system boot up. VPS
           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 VPS. This is essentially a
           mount point for VPS root. Value must contain string $VEID, which
           will be substituted with numeric VPS ID. Changing this parameter is
           not recommended, better edit vz(5) global configuration file.

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

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

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

       --disabled yes|no
           Disable VPS start. For force start disabled VPS option --force can
           be used.

       Network related parameters

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

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

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

       --nameserver addr
           Sets DNS server IP address for VPS. 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 VPS. 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 page size is
           architecture-specific, it is 4096 bytes on IA32 platform.

       --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 VPS. The barrier is the amount of memory
           that VPS'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
           VPS 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 VPS
           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 VPS
           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 VPS
           processes. The barrier of this parameter is the out-of-memory
           guarantee. If the oomguarpages usage is below the barrier,
           processes of this VPS 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 VPS
           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), VPS 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 VPS 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 VPS 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 VPS. 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 VPS.

       --cpuunits num
           CPU weight for VPS. 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 VPS get. Maximum value is 500000,
           minimal is 8. Number is relative to weights of all the other
           running VPSs. If cpuunits not specified default value 1000 ia used.

           You can set CPU weight for VPS0 (hardware node itself) as well (use
           vzctl set 0 --cpuunits num).

       --cpulimit num
           Limit of CPU usage for the VPS, 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).

       Iptables control parameters

       --iptables name
           Restrict access to iptable modules inside VPS (by default all
           iptables modules that loaded in host system are accessible inside
           VPS)

           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.

       Network devices control parameters

       --netdev_add name
           move network device from VPS0 to specified VPS

       --netdev_del name
           delete network device from specified VPS

       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.

       --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 VPS for which disk quota
           in VPS will be accounted If this value is set to 0, user and group
           quotas will not be accounted inside VPS.

           Note that if you have previously set value of this parameter to 0,
           changing it while VPS 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 VPS. Note that setting capability when VPS
           is running does not take immediate effect; restart VPS in order for
           changes to take effect. VPS 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 VPS.

       Apply config

       --applyconfig name
           Read VPS parameters from VPS sample configuration file
           /etc/sysconfig/vz-scripts/ve-name.conf-sample, and apply them, if
           --save option specified save to VPS config file. These parameters
           are not changed (HOSTNAME IP_ADDRESS OSTEMPLATE VE_ROOT VE_PRIVATE)

   Performing VPS actions
       create vpsid --ostemlate name] [--config name] [--private path] [--root
       path]
           Creates VPS area. This operation should be done once, before the
           first startup of VPS.

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

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

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

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

       start
           Mounts (if necessary) and starts VPS.

       stop
           Stops and unmounts VPS.

       restart
           Restart VPS, stop if running and start.

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

           This command can also be usable from scripts.

       mount
           Mounts VPS private area.

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

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

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

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

       enter
           Enters into VPS. 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" VPS with ID 1000 using fedora-3 ostemplate,
       and IP address 192.168.10.200:
            vzctl create 1000 --ostemplate fedora-3 --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 processes 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 VPS:
            vzctl exec 1000 /bin/ls -la

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

       To stop this VPS:
            vzctl stop 1000

       To permanently remove this VPS:
            vzctl destroy 1000

FILES
        /etc/sysconfig/vz
       /etc/sysconfig/vz-scripts/vpsid.conf
       /proc/vz/veinfo
       /proc/vz/vzquota
       /proc/user_beancounters
       /proc/fairsched

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

LICENSE
       Copyright (C) 2000-2005, SWsoft. Licensed under QPL.



OpenVZ                            10 Aug 2005                         vzctl(8)