Gentoo Linux-VServer Howto

1.6 2006-06-19 Introduction

The Linux-VServer Concept

The basic concept of the Linux-VServer solution is to separate the user-space environment into distinct units (sometimes called Virtual Private Servers) in such a way that each VPS looks and feels like a real server to the processes contained within.

Terms used in this Howto Linux-VServer is the official name of the project and used in this Howto the same way All these are interchangable and refer to one instance of a server (i.e. one virtual server) The physical machine running your Gentoo Linux will host all virtual servers The util-vserver package contains all programs necessary for maintaining your virtual servers

Term	Description
Linux-VServer, VServer
virtual server, vserver, guest system
host system, host
util-vserver

Host configuration

Install a VServer kernel

# emerge vserver-sources

After the vserver-sources are installed it's time to configure them using make menuconfig.

# cd /usr/src/linux-<KERNELVERSION>-vserver-<VSERVERVERSION>
# make menuconfig

Linux VServer --->
  [ ] Enable Legacy Kernel API
  [*] Disable Legacy Networking Kernel API
(Highly recommended)
  [*] Enable Proc Security
  [*] Enable Hard CPU Limits
  Persistent Inode Context Tagging (UID24/GID24)  --->
  [ ] Tag NFSD User Auth and Files
  [ ] Compile Debugging Code

If you are using reiserfs as filesystem on the partition where guest images are stored, you will need to enable extended attributes for reiserfs in your kernel config and additionally add the attrs option in /etc/fstab.

File systems  --->
  <*> Reiserfs support
  [*]   ReiserFS extended attributes

/dev/hdb1 /vservers reiserfs noatime,attrs 0 0

After you've built and installed the kernel, update your boot loader and finally reboot to see if the kernel boots correctly.

(Building the kernel)
# make
(Installing)
# make modules_install
# cp arch/<arch>/boot/bzImage /boot/kernel-<KERNELVERSION>-vserver-<VSERVERVERSION>
(Edit bootloader config file as required and)
# reboot

Setup host environment

To maintain your virtual servers you need the util-vserver package which contains all necessary programs and many useful features. Be aware that there is also a package called vserver-utils. It is a new incarnation of the user-space implementation of the VServer kernel API, but not yet usable for production use.

This version of the howto requires features only available in >=sys-apps/util-vserver-0.30.210-r6. You may have to keyword/upgrade it first.

# emerge util-vserver

You have to run the vprocunhide command after every reboot in order to setup /proc permissions correctly for vserver use. An init script has been installed by util-vserver. To use it you should add it to a runlevel:

# rc-update add vservers default
# /etc/init.d/vservers start

This init script will also start your default vservers. Read below for more information.

The vshelper script is used to restart virtual servers correctly. You have to tell the kernel where the vshelper script is located:

# echo 'kernel.vshelper = /usr/lib/util-vserver/vshelper' >> /etc/sysctl.conf
# sysctl -p

Creating a guest template

Install a vserver stage3

You have to download a vserver prepared stage3 from one of our mirrors. Those stages are located under the experimental/<arch>/vserver/ directory. Then use the vserver-new script to create the initial guest.

Please note that starting with util-vserver-0.30.212 the vserver-new script stopped existing, as the functionality got merged into UPSTREAM's release and is now integrated into util-vserver's swiss army knive vserver. It's now called via vserver <name> build.

You have to choose a context ID for your vserver (dynamic context IDs are discouraged) as well as the necessary network device information (In this example eth0 is configured with 192.168.1.253/24 and the context ID is equivalent to the last two parts of the virtual servers IP).

The context ID should be 1 < ID < 49152.

# vserver-new gentoo-template \
  --hostname gentoo \
  --context 1253 \
  --interface eth0:192.168.1.253/24 \
  stage3 /path/to/stage3-<arch>-<date>.tar.bz2 <arch>

To reflect your network settings you should change /etc/conf.d/hostname, /etc/conf.d/domainname and /etc/hosts inside the guest to your needs. See chapter 8.b.1 and chapter 8.b.4. The rest of your virtual servers network setup will be done on the host.

Create the template tarball

You don't have to build a stage3 tarball for every guest. The vserver-new script supports templates. In order to use them you have to create a tarball of your vserver installation:

# cd /vservers/gentoo-template
# tar cjvpf ../gentoo-template-<arch>-<date>.tar.bz2 ./

To create a new guest using this tarball just use vserver-new:

# cd /vservers
# vserver-new myguest \
  --hostname myguest \
  --context 1252 \
  --interface eth0:192.168.1.252/24 \
  template ./gentoo-template-<arch>-<date>.tar.bz2 <arch>

You should use a shared portage tree to keep guests small in size. Edit /etc/vservers/myguest/fstab and uncomment the entries for /usr/portage and /usr/portage/distfiles. Guests will have read-only access to /usr/portage and read-write access to /usr/portage/distfiles.

Test the virtual server

You should be able to start and enter the vserver by using the commands below. If you miss commands like mount or dmesg you should emerge util-linux inside your virtual server as the vserver profile doesn't ship this package by default.

# vserver myguest start
# vserver-stat
CTX   PROC    VSZ    RSS  userTIME   sysTIME    UPTIME NAME
0       90   1.4G 153.4K  14m00s11   6m45s17   2h59m59 root server
1252     2     3M   286    0m00s45   0m00s42   0m02s91 myguest
# vserver myguest enter
# ps ax
PID   TTY      STAT   TIME COMMAND
    1 ?        S      0:00 init [3]
22887 ?        Ss     0:00 /usr/sbin/syslog-ng
20496 pts/0    S      0:00 /bin/bash -login
20508 pts/0    R+     0:00 ps ax
# logout

Maintenance made easy

Start guests on boot

You can start certain guests during boot. Each guest can be assigned a MARK. Now everything you have to do is configure these MARKs in the guests configuration and tell the init script to run all MARKed guests.

(Do this for every guest you want to start)
# mkdir -p /etc/vservers/myguest/apps/init
# echo "default" > /etc/vservers/myguest/apps/init/mark

Since all guests marked with "default" are started by default, nothing more has to be done. If you have different marks you should also update /etc/conf.d/vservers.

Gentoo goodies

The util-vserver ebuild has installed some goodies for Gentoo guests. You know vserver-new from the previous chapter. In this chapter, you will learn how to use vesync and vemerge to keep portage in sync as well as vupdateworld and vdispatch-conf to update guests.

Keep portage in sync

The script vesync will help you to keep the metadata cache and overlays in sync. vemerge is a simple wrapper for emerge in guests.

(Sync metadata for 'myguest')
# vesync myguest
(Sync metadata for all guests)
# vesync -a
(Sync metadata for all guests except 'myguest')
# vesync -a -e myguest
(Sync 'myoverlay' for all guests)
# vesync -a \
  --overlay /usr/local/overlays/myoverlay \
  --overlay-host rsync://rsync.myhost.com/myoverlay \
  --overlay-only
(emerge app-editors/vim in 'myguest')
# vemerge myguest app-editors/vim -va

This script requires you to have a shared portage tree.

Update guests

Gentoo guests can share packages to save compilation time. In order to use shared packages, you have to create a central directory for packages on the host. We will use /var/cache/vpackages on the host and mount it to /usr/portage/packages in every guest.

# mkdir -p /var/cache/vpackages
# $EDITOR /etc/vservers/myguest/fstab
(Add this line at the end)
/var/cache/vpackages /usr/portage/packages none bind,rw 0 0

Now you can use vupdateworld to update every guest. The command is equivalent to something like emerge --deep --update --newuse world depending on command line options.

(Pretend update for 'myguest')
# vupdateworld -p myguest
(Update 'myguest' using binary packages)
# vupdateworld -k myguest
(Update all guests using binary packages)
# vupdateworld -ka

In order to get binary packages you can either use PORTAGE_BINHOST (see man make.conf) or set FEATURES="buildpkg" in one or more guests.

After a successful update you can easily update all configuration files with vdispatch-conf. It is a simple wrapper for dispatch-conf and behaves exactly the same.

(Update configuration files for 'myguest')
# vdispatch-conf myguest
(Update configuration files for all guests)
# vdispatch-conf -a

Contact

Please feel free to contact the author or file a bug on Bugzilla in case of any problems.