We currently migrate to MediaWiki from our old installation, but not all content has been migrated yet. Take a look at the Wiki Team page for instructions how to help or browse through our new wiki at wiki.linux-vserver.org to find the information already migrated.

The [alpha branch] of util-vserver

The naming scheme of the tools is either x.y or x.y.z. When

Please note that the paths used in this documented are assuming an installation with packagemanagement. When using the plain ./configure, the path /usr translates to /usr/local, /etc to /usr/local/etc, and /var to /usr/local/var.

A description of the new configuration can be found on the [Flower Page]. But note that usually you don't create this configuration manually but use the tools as presented below.

ATTENTION

Beginning with 0.28.200, util-vserver will use CLONE_NS and RBIND to mount directories within vservers. Because some kernel support is missing at time of writing (Feb 10 2004), the mounted directories are not visible when entering the vserver with vserver <vserver-id> enter. Stopping them (vserver <vserver-id> stop) can have some issues too.

When you do not want to test this new feature, it is strongly recommended to do

# touch /etc/vservers/<vserver-id>/nonamespace

for every vserver. This flag can be set globally in /etc/vservers/.defaults too.

Since 0.29.197 it is possible to enter the vserver with

# vnamespace --enter <xid> vserver <vserver-id> enter

where <xid> is the xid of the running vserver. The nonamespace flag must not be set in this case.

Building the util-vserver tools

The util-vserver tarball contains a reference .spec file which can be used to build binary RPMs on Fedora Core 2 systems with the

$ rpmbuild -ta util-vserver-<version>.tar.bz2

command. On systems without the xalan XSL processor or without a recent dietlibc, the options --without xalan or --without dietlibc can be appended to the command above.

When prefering manual builds, you can execute the usual

$ ./configure && make && make install

sequence. Please note, that without an explicit --prefix option, everything will be installed and assumed under /usr/local. E.g. the configuration will not be at /etc/vservers, but at /usr/local/etc/vserver.

To enable the "standard" paths, read the ./configure --help output and set the responsible paths manually.

Vserver creation

This has only been done within a Fedora Core 1 host yet, but other distros should work.

Possible/tested vservers are:

# vserver <vserver-id> build -m apt-rpm <other-options>* -- -d fc1 # for FC1 vserver, use '-d rh9' for RHL 9
before doing this, you need a recent apt (e.g. from [fedora.us]) and have to configure your nearest mirror in /etc/vservers/.distributions/<dist>/apt/sources.list.
With applied quota-patch it is strongly recommended to use the --context <ctx> option.
# vserver <vserver-id> build -m yum <other-options>* -- -d fc3
this requires a recent enough 'yum' (>= 2.1.12 should be ok). BEWARE: this method has not been tested very much and it can not be guaranted that the underlying 'vyum' does not read files from the guest.
# vserver <vserver-id> build -m rpm <other-options>* -- -b <base-directory> <pkg-list>*
which installs a list of rpm-packages without resolving dependencies. <pkg-list> is a file with one package-name per line which will be searched below <base-directory>. Alternatively, a preconfigured packageset can be specified with -d <distribution> (currently, only fc3 is the only supported distribution).
# vserver <vserver-id> build -m debootstrap <other-options>* -- -d sarge # or woody
you can configure the mirror with '-m <mirror>' or by putting it into the file /etc/vservers/.defaults/apps/debootstrap/mirror. This command assumes either an installed debootstrap package, or will download it from the URI configured in /etc/vservers/.defaults/apps/debootstrap/uri (see /usr/lib/util-vserver/defaults/debootstrap.uri for the default value). You can setup a local path too by beginning it with '/'.
# vserver <vserver-id> build -m skeleton

The first two options need a good internet connection; it is possible that more than 100MB will be downloaded. Alternatively and when you are experienced with the apt-tools, you can create your own mirror which is based on the CD-ROMs.

<other-options> can be e.g. --hostname or --interface; for complete list see vserver - build --help output

Examples

Creates the vserver foo with the Fedora Core 1 distribution and apt-rpm method. Its hostname will be vs.foo.org and the name shown by tools like vps or vserver-stat be bar. The static context will be 42 and the assigned interface eth0 with ip 192.168.3.1 and prefix 21 (== mask 255.255.248.0).
Creates the vserver foo like above but with a predefined packageset. These packages will be searched on a mounted cdrom.
Creates the vserver foo with the debian sarge distribution using a network installation from the server ftp.debian.org.

Directory/vserver unification

The alpha branch of util-vserver reimplemented vunify so that it can unify arbitrary directories without requiring information from package-management (rpm). It introduces the concept of reference-vservers too. It has rsync-like excludelists, so that you can e.g. exclude anything under /etc/ except /etc/termcap; the corresponding excludelist would be

+/etc/termcap
/etc
Unifying directories
just type
# /usr/lib/util-vserver/vunify --manually <dst-path> <dst-excludelist> <reference-path> <reference-excludelist>
It is possible too, to specify multiple reference-paths; when a file is unificable, it will be linked with the file of the first matching reference-path.
Unifying vservers
to do this, the vunify application must be configured by
# mkdir -p /etc/vservers/<refserver>/apps/vunify
# mkdir -p /etc/vservers/<vserver-id>/apps/vunify
# ln -s /etc/vservers/<refserver> /etc/vservers/<vserver-id>/apps/vunify/refserver.00
This will make <refserver> a reference vserver of <vserver-id>. You can create multiple refservers by creating more "refserver.X" symlinks. These links will be handled in alphanumerical order. Files in these vunify directories which are named "exclude" will be assumed as static excludelists. When packagemanagement is configured for the vserver, configuration-files will be added to the excludelist.
When typing
# /usr/lib/util-vserver/vunify <vserver-id>, or
# vserver <vserver-id> unify
the unification happens. Details and debuginformation can be turned on by specifying one or more -v options.

The initscript

Since 0.29.202, util-vserver has a vservers-default initscripts. This script is calling the start-vservers program which:

/etc/vservers/<vserver-id>/apps/init/mark
Content of this file is a string; the shipped vservers-default initscript handles all vservers having default as this string. The initscript can be easily modified to support other tags, for details just look into the script.

The vshelper userspace reboot helper (since 0.29.206)

The userspace helper is configured through the .../apps/vshelper directories. By placing a disabled file there, it can be disabled either globally (when using /etc/vservers/.defaults), or for a single vserver only. The default actions are configured to restart the vserver on 'restart' and to stop it at 'halt' or 'poweroff' events.

To make vshelper working, it was required to enable the CAP_SYS_BOOT capability for all vservers. By removing this capability explicitly, this could be changed. But since the vshelper is used for synchronisation of minit-style vservers also, touching of the disabled file is the preferred way.

Examples

# touch /etc/vservers/.defaults/apps/vshelper/disabled
# touch /etc/vservers/foo/apps/vshelper/disabled
# echo 'notify' >/etc/vservers/bar/apps/vshelper/action
# cp my-notify-script /etc/vservers/.defaults/apps/vshelper-methods/notify
(my-notify-script is a script expecting xid and event as parameters; the $VSERVER environment variable with the id of the vserver is set)
# vserver <id> enter
# ln -s /sbin/hard-reboot /etc/minit/ctrlaltdel/run
# echo 'RESTART' >/etc/minit/ctrlaltdel/params
# touch /etc/minit/ctrlaltdel/sync

Kernel 2.4 to kernel 2.6 transition

Since the barrier and immulink implementation differs between kernel 2.4 and kernel 2.6, the following problems will occur when under kernel 2.4 created vservers will be used under kernel 2.6:

# showattr -d /vservers
Things are fine when you see an uppercase 'B' like in
---Bui- /vservers
Else you should execute
# setattr --barrier /vservers

# lsattr -R 2>/dev/null /vservers | grep -- '----i------t-' | cut -d ' ' -f 2 | xargs setattr --iunlink
# lsattr -R 2>/dev/null /vservers | grep -- '----i------t-' | cut -d ' ' -f 2 | xargs chattr -t
(using only the reference vservers instead of /vservers would be probably more efficiently)
Obviously, these commands are not very reliable:
  • all affected vservers must be stopped; else symlink attacks are possible
  • filenames with whitespace are not accepted
Therefore, you should verify with
# lsattr -R 2>/dev/null /vservers | grep -- '----i------t-'
that all files have been updated.