vzctl - utility to control Virtual Private Server.
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
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.
These flags can be used with almost any option.
- --quiet
- Disables logging to log file and screen.
- --verbose
- Sets logging level to maximum value.
- 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)
- 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.
- --help
- Prints help message with a brief list of possible options.
- --version
- Prints vzctl version.
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
/etc/sysconfig/vz
/etc/sysconfig/vz-scripts/vpsid.conf
/proc/vz/veinfo
/proc/vz/vzquota
/proc/user_beancounters
/proc/fairsched
vz(5), vps.conf(5), vzquota(8),
Copyright (C) 2000-2005, SWsoft. Licensed under QPL.