Provided by: vzctl_3.0.22-14ubuntu2_i386 bug

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.

       --setmode restart|ignore
           Whether to restart a VE after  applying  any  parameters  requiring
           that the VE be restarted for those to take effect.

       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. Each argument is either a number, a number
           with a suffix, or a special value unlimited.

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

           You  can  also  specify  the  literal  word unlimited in place of a
           number.  In that case  the  corresponding  value  will  be  set  to
           LONG_MAX, i. e.  the maximum possible value.

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

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

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

       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

           Default is privvmpages:1.

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

       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  capabilities,  thus  any  operation  on
           capabilities  is  "logical  and" with the 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.

           WARNING: setting some of those  capabilities  may  have  far
           reaching  security  implications, so do not do it unless you
           know what you are doing. Also note that  setting  setpcap:on
           for a VE will most probably lead to inability to start it.

       Device access management

       --devnodes device:r|w|rw|none
           Give the VE an access (r - read, w - write, rw - read write,
           none - no access) to a device designated by the special file
           /dev/device. Device file is created in VE by vzctl.

       --devices b|c:major:minor|all:[r|w|rw|none]
           Give  the  VE  an  access  to  a  block  or character device
           designated by its major and minor numbers. Device file  have
           to be created manually.

       Features management

       --features name:on|off
           Enable  or  disable  a  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.

       I/O priority management

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

   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] [--force]
           Mounts (if necessary) and starts a VE. Unless --wait  option
           is  specified,  vzctl  will return immediately; otherwise an
           attempt to wait till the default runlevel is reached will be
           made by vzctl.

           Specify  --force if you want to start a VE which is disabled
           (see --disabled).

       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.