User Guide/Operations on Containers

From OpenVZ Virtuozzo Containers Wiki
Revision as of 17:09, 16 January 2009 by Kir (talk | contribs) (created (half-finished))
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Warning.svg Warning: This User's Guide is still in development
User's Guide
Preface
OpenVZ Philosophy
Installation and Preliminary Operations
Operations on Containers
Managing Resources
Advanced Tasks
Troubleshooting
Reference

This chapter describes how to perform day-to-day operations on separate Containers taken in their wholeness.

{{Note|We assume that you have successfully installed, configured, and deployed your OpenVZ system. In case you have not, please turn to the Installation Guide providing detailed information on all these operations.

Creating New Container

This section guides you through the process of creating a Container. We assume that you have successfully installed OpenVZ and prepared at least one OS template. If there are no OS templates prepared for the Container creation, turn to the Templates Management Guide first.

Before You Begin

Before you start creating a Container, you should:

  • Check that the Hardware Node is visible on your network. You should be able to connect to/from other hosts. Otherwise, your Containers will not be accessible from other servers.
  • Check that you have at least one IP address per Container and the addresses belong to the same network as the Hardware Node or routing to the Containers has been set up via the Hardware Node.

To create a new Container, you have to:

  • choose the new Container ID;
  • choose the OS template to use for the Container;
  • create the Container itself.

Choosing Container ID

Every Container has a numeric ID, also known as Container ID, associated with it. The ID is a 32-bit integer number beginning with zero and unique for a given Hardware Node. When choosing an ID for your Container, please follow the simple guidelines below:

  • ID 0 is used for the Hardware Node itself. You cannot and should not try to create a Container with ID 0.
* The OpenVZ software reserves the IDs ranging from 0 to 100. Though OpenVZ uses only ID 0, future versions might use additional Container IDs for internal needs. Please do not create Containers with IDs below 101.

The only strict requirement for a Container ID is to be unique for a particular Hardware Node. However, if you are going to have several computers running OpenVZ, we recommend assigning different Container ID ranges to them. For example, on Hardware Node 1 you create Containers within the range of IDs from 101 to 1000; on Hardware Node 2 you use the range from 1001 to 2000, and so on. This approach makes it easier to remember on which Hardware Node a Container has been created, and eliminates the possibility of Container ID conflicts when a Container migrates from one Hardware Node to another.

Another approach to assigning Container IDs is to follow some pattern of Container IP addresses. Thus, for example, if you have a subnet with the 10.0.x.x address range, you may want to assign the 17015 ID to the Container with the 10.0.17.15 IP address, the 39108 ID to the Container with the 10.0.39.108 IP address, and so on. This makes it much easier to run a number of OpenVZ utilities eliminating the necessity to check up the Container IP address by its ID and similar tasks. You can also think of your own patterns for assigning Container IDs depending on the configuration of your network and your specific needs.

Before you decide on a new Container ID, you may want to make sure that no Container with this ID has yet been created on the Hardware Node. The easiest way to check whether the Container with the given ID exists is to issue the following command:

# vzlist -a 101
Container not found

This output shows that Container 101 does not exist on the particular Hardware Node; otherwise it would be present in the list.

Choosing OS Template

Before starting to create a Container, you shall decide on which OS template your Container will be based. There might be several OS templates installed on the Hardware Node and prepared for the Container creation; use the following command to find out what OS templates are available on your system:

# ls /vz/template/cache/
centos-4-x86.tar.gz       fedora-7-x86.tar.gz     suse-10.3-x86.tar.gz
centos-4-x86_64.tar.gz    fedora-7-x86_64.tar.gz  suse-10.3-x86_64.tar.gz
centos-5-x86.tar.gz       fedora-8-x86.tar.gz     ubuntu-7.10-x86.tar.gz
centos-5-x86_64.tar.gz    fedora-8-x86_64.tar.gz  ubuntu-7.10-x86_64.tar.gz
debian-3.1-x86.tar.gz     fedora-9-x86.tar.gz     ubuntu-8.04-x86.tar.gz
debian-4.0-x86.tar.gz     fedora-9-x86_64.tar.gz  ubuntu-8.04-x86_64.tar.gz
debian-4.0-x86_64.tar.gz
Yellowpin.svg Note: You have to remove the .tar.gz suffix from the name to make it a valid OS template name. For example, centos-4-x86 is a valid OS template name.

Creating Container

After the Container ID and the installed OS template have been chosen, you can create the Container private area with the vzctl create command. The private area is the directory containing the actual files of the given Container; it is usually residing in /vz/private/CTID/. The private area is mounted to the /vz/root/CTID directory on the Hardware Node and provides Container users with a complete Linux file system tree.

The vzctl create command requires only the Container ID and the name of the OS template as arguments; however, in order to avoid setting all the Container resource control parameters after creating the private area, you can specify a sample configuration to be used for your new Container. The sample configuration files are residing in the /etc/vz/conf directory and have names with the following mask: ve-configname.conf-sample. The most commonly used sample is the ve-basic.conf-sample file; this sample file has resource control parameters suitable for most Containers.

Thus, for example, you can create a new Container by typing the following string:

# vzctl create 101 --ostemplate centos-5-x86 -–config basic
Creating container private area (centos-5-x86)
Performing postcreate actions
Container private area was created

In this case, the OpenVZ software will create a Container with ID 101, the private area based on the centos-5-x86 OS template, and configuration parameters taken from the ve-basic.conf-sample sample configuration file.

If you specify neither an OS template nor a sample configuration, vzctl will try to take the corresponding values from the global OpenVZ configuration file (/etc/vz/vz.conf). So you can set the default values in this file using your favorite text file editor, for example:

DEF_OSTEMPLATE="centos-5-x86"
CONFIGFILE="basic"

and do without specifying these parameters each time you create a new Container.

Now you can create a Container with ID 101 with the following command:

# vzctl create 101
Creating container private area (centos-5-x86)
Performing postcreate actions
Container private area was created

In principle, now you are ready to start your newly created Container. However, typically you need to set its network IP address, hostname, DNS server address and root password before starting the Container for the first time.

Configuring Container

Configuring a Container consists of several tasks:

  • Setting Container startup parameters;
  • Setting Container network parameters;
  • Setting Container user passwords;
  • Configuring Quality of Service (Service Level) parameters.

For all these tasks, the vzctl set command is used. Using this command for setting Container startup parameters, network parameters, and user passwords is explained later in this subsection. Service Level Management configuration topics are dwelled upon in the Managing Resources chapter.

Setting Startup Parameters

The vzctl set command allows you to define the onboot Container startup parameter. Setting this parameter to yes makes your Container automatically boot at the Hardware Node startup. For example, to enable Container 101 to automatically start on your Hardware Node boot, you can execute the following command:

# vzctl set 101 --onboot yes --save
Saved parameters for CT 101

The onboot parameter will have effect only on the next Hardware Node startup.

Setting Network Parameters

In order to be accessible from the network, a Container shall be assigned a correct IP address and hostname; DNS servers shall also be configured. In addition, the SSH daemon shall be running inside the Container. The session below illustrates setting the Container 101 network parameters:

# vzctl set 101 --hostname server101.mydomain.com --save
Set hostname: server101.mydomain.com
Saved parameters for CT 1010101
# vzctl set 101 --ipadd 10.0.186.1 --save
Adding IP address(es): 10.0.186.1
Saved parameters for CT 1010101
# vzctl set 101 --nameserver 192.168.1.165 --save
File resolv.conf was modified
Saved parameters for CT 1010101

These commands will assign Container 101 the IP address of 10.0.186.1, the hostname of server101.mydomain.com, and set the DNS server address to 192.168.1.165. The –-save flag instructs vzctl to also save all the parameters set to the Container configuration file.

You can issue the above commands when the Container is running. In this case, if you do not want the applied values to persist, you can omit the –-save option and the applied values will be valid only until the Container shutdown.

To check whether SSH is running inside the Container, use vzctl exec, which allows executing any commands in the Container context.

# vzctl start 101
[This command starts Container 101, if it is not started yet]
# vzctl exec 101 service sshd status
sshd is stopped
# vzctl exec 101 service sshd start
Starting sshd: [ OK ]
# vzctl exec 101 service sshd status
sshd (pid 3801) is running...

The above example assumes that Container 101 is created on the CentOS 5 template. For other OS templates, please consult the corresponding OS documentation.

For more information on running commands inside a Container from the Hardware Node, see the #Running Commands in Container subsection.

Setting root Password for Container

Setting the root user password is necessary for connecting to a Container via SSH. By default, the root account is locked in a newly created Container, and you cannot log in. In order to log in to the Container, it is necessary to create a user account inside the Container and set a password for this account, or unlock the root account. The easiest way of doing it is to run:

# vzctl start 101
[This command starts Container 101, if it is not started yet]
# vzctl set 101 --userpasswd root:test

In this example, we set the root password for Container 101 to "test", and you can log in to the Container via SSH as root and administer it in the same way as you administer a standalone Linux server: install additional software, add users, set up services, and so on. The password will be set inside the Container in the /etc/shadow file in an encrypted form and will not be stored in the Container configuration file. Therefore, if you forget the password, you have to reset it. Note that --userpasswd ignores the --save switch, the password is anyway persistently set for the given Container.

While you can create users and set passwords for them using the vzctl exec or vzctl set commands, it is suggested that you delegate user management to the Container administrator advising him/her of the Container root account password.

Starting, Stopping, Restarting, and Querying Status of Container

When a Container is created, it may be started up and shut down like an ordinary server. To start Container 101, use the following command:

# vzctl start 101
Starting container ...
Container is mounted
Adding IP address(es): 10.0.186.1
Setting CPU units: 1000
Configure meminfo: 65536
Set hostname: server101.mydomain.com
File resolv.conf was modified
Container start in progress...

To check the status of a Container, use the vzctl status command:

# vzctl status 101
CTID 101 exist mounted running

Its output shows the following information:

  • Whether the Container private area exists;
  • Whether this private area is mounted;
  • Whether the Container is running.

In our case, vzctl reports that Container 101 exists, its private area is mounted, and the Container is running. Alternatively, you can make use of the vzlist utility:

# vzlist 101
      CTID      NPROC STATUS  IP_ADDR         HOSTNAME                        
   101             10 running 10.0.186.1      server101.mydomain.com 

Still another way of getting the Container status is checking the /proc/vz/veinfo file. This file lists all the Containers currently running on the Hardware Node. Each line presents a running Container in the CT_ID reserved number_of_processes IP_address... format:

# cat /proc/vz/veinfo
   101         0    10      10.0.186.1
         0     0    79

This output shows that Container 101 is running, there are 20 running processes inside the Container, and its IP address is 10.0.186.1. The second line corresponds to the Container with ID 0, which is the Hardware Node itself.

The following command is used to stop a Container:

# vzctl stop 101
Stopping container ...
Container was stopped
Container is unmounted
# vzctl status 101
CTID 101 exist unmounted down

vzctl has a two-minute timeout for the Container shutdown scripts to be executed. If the Container is not stopped in two minutes, the system forcibly kills all the processes in the Container. The Container will be stopped in any case, even if it is seriously damaged. To avoid waiting for two minutes in case of a Container that is known to be corrupt, you may use the --fast switch:

# vzctl stop 101 --fast
Stopping container ...
Container was stopped
Container is unmounted

Make sure that you do not use the --fast switch with healthy Containers, unless necessary, as the forcible killing of Container processes may be potentially dangerous.

The vzctl start and vzctl stop commands initiate the normal Linux OS startup or shutdown sequences inside the Container. In case of a Red Hat-like distribution, System V initialization scripts will be executed just like on an ordinary server. You can customize startup scripts inside the Container as needed.

To restart a Container, you may as well use the vzctl restart command:

# vzctl restart 101
Restarting container
Stopping container ...
Container was stopped
Container is unmounted
Starting container ...
Container is mounted
Adding IP address(es): 10.0.186.1
Setting CPU units: 1000
Configure meminfo: 65536
Set hostname: server101.mydomain.com
File resolv.conf was modified
Container start in progress...

{{Note|You can also use Container names to start, stop, and restart the corresponding Containers. For detailed information on Container names, please turn to the #Setting Name for Container section.

Listing Containers

Very often you may want to get an overview of the Containers existing on the given Hardware Node and to get additional information about them — their IP addresses, hostnames, current resource consumption, etc. In the most general case, you may get a list of all Containers by issuing the following command:

# vzlist -a
     CTID      NPROC STATUS  IP_ADDR         HOSTNAME                        
      101         10 running 10.101.66.101   server101.mydomain.com
      102          - stopped 10.101.66.102   server102.mydomain.com                         
      103          5 running 10.101.66.103   server103.mydomain.com

The -a switch tells the vzlist utility to output both running and stopped Containers. By default, only running Containers are shown. The default columns inform you of the Container IDs, the number of running processes inside Containers, their status, IP addresses, and hostnames. This output may be customized as desired by using vzlist command line switches. For example:

# vzlist -o ctid,diskinodes.s -s diskinodes.s
      CTID DQINODES.S
       101     400000
       103     200000

This shows only running Containers with the information about their IDs and soft limit on disk inodes (see the Template:Chapter link chapter for more information), with the list sorted by this soft limit. The full list of the vzlist command line switches and output and sorting options is available in the vzlist(8) man page.

FIXME

Setting Name for Container

Storing Extended Information on Container

Expand Migrating Container

Moving Container Within Hardware Node

Copying Container Within Hardware Node

Deleting Container

Disabling Container

Suspending Container

Running Commands in Container