Howto create custom VPS stages

1. Introduction

In most cases there is not a single vserver on one machine, but rather plenty of them. To ease installation and save resources it is recommended to create custom stages with necessary packages already included, so there is no need to compile the initial software in the guest environment.

Requirements

To create stages Gentoo developers use a tool called catalyst. If you do not already have it installed on your system please do so:

Code Listing 1.1: Install catalyst

# emerge dev-util/catalyst

Since the base requirement for every Gentoo system is a stage3, you don't have to bother about building stage1, 2 or 3, but rather download a precompiled stage3 for your architecture and add your custom packages. As soon as as baselayout-1.13 is stable you can use a regular stage3 available from one of our mirrors. In the meantime please download a stage3 from here.

Code Listing 1.2: Download precompiled stage3

# mkdir -p /var/tmp/catalyst/builds/default
# cd /var/tmp/catalyst/builds/default
# wget http://people.linux-vserver.org/~hollow/stages/stage3-<ARCH>-<DATE>.tar.bz2

Finally, you need a copy of the portage tree used by catalyst. You can either download a snapshot from on of our mirrors or create one yourself.

Code Listing 1.3: Get a portage snapshot

(Download from our mirrors)
#  mkdir -p /var/tmp/catalyst/snapshots
#  cd /var/tmp/catalyst/snapshots
# wget http://url/to/snapshots/portage-latest.tar.bz2

(Create one yourself)
# catalyst -s latest

2. Building your stage4

Download a spec-file template

The Gentoo VPS team provides several spec files that can be used with catalyst. In many cases it is probably enough to just download a spec-file and start building. However, if you want to customize the list of packages even further, take a look at the spec-files and the catalyst reference manual.

Code Listing 2.1: Download a spec-file

# CONFDIR=/etc/vservers/.stages
# mkdir -p $CONFDIR/specs
# cd $CONFDIR/specs
# wget http://people.linux-vserver.org/~hollow/stages/specs/stage4-<ARCH>-<NAME>.spec

As long as baselayout-1.13 is not stable you need to keyword/unmask baselayout and some dependencies. Fortunately, the spec-files are already prepared for this and the list of dependencies is rather small.

Code Listing 2.2: Unmask baselayout

# mkdir -p $CONFDIR/portage
# echo sys-apps/baselayout >> $CONFDIR/portage/package.keywords
# echo sys-apps/makedev    >> $CONFDIR/portage/package.keywords
# echo app-shells/bash     >> $CONFDIR/portage/package.keywords
# echo sys-apps/baselayout >> $CONFDIR/portage/package.unmask
# echo sys-apps/makedev    >> $CONFDIR/portage/package.unmask

Start build process

Your environment is now ready to start the build process with catalyst. To be able to maintain multiple stages in one repository, there is no version number in the spec-files, so you have to specify it on the command line.

Code Listing 2.3: Run catalyst

# time catalyst -f $CONFDIR/specs/stage4-<ARCH>-<NAME>.spec -C version_stamp=$(date +%Y%m%d)

Depending on your hardware and package selection this can take a rather long time, so get yourself a cup of coffee and check back occasionally. Once finished, the newly created stage can be found in /var/tmp/catalyst/builds/default.

Contact

Please feel free to contact the author or file a bug on Bugzilla in case of any problems or if you wish to contribute custom spec-files.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.