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.

Introduction

VSkel is a script for creating and maintaining vservers using FreeVSD-style "skels". A skel (short for skeleton) is like a template server, and you can have several skels with different software and configurations. VSkel then allows you to easily create vservers based on those skels.

VSkel is primarily aimed at users implementing virtual servers in a commercial web hosting scenario, where you might create several skels representing different account types, with different software packages installed (or you might just have "one with everything", depending on your needs). Once a skel is built with a particular configuration, VSkel makes it easy to create vservers using the same configuration.


Download


Using VSkel

Type vskel.pl --help for a list of options. Essentially there are four modes of operation, as follows.

1. Building a Skel

Before you can do anything you need to have a skel to work with. Currently the only way of creating a skel is simply by making a copy of the host server (minus a few bits and pieces). This is not ideal because you end up with some things in the skel (and hence in vservers if you don't do anything about it) which you probably don't want there, such as your login in /etc/passwd and /etc/shadow, log files in /var, and copies of the util-vserver tools such as vrpm, vserver, vdu, etc. After building a skel you will need to go through it with a fine tooth comb and ensure that it only contains the things you want it to contain. (The good news is, you only need to do this once.)

Once you have VSkel installed, building a skel is as simple as typing:

vskel.pl --build-skel myskel

where "myskel" is whatever name you want to give the skel.

Parts of a Skel

Each skel is composed of three main parts, which are separate directories under /vservers/.skel/<skel name>.

global/
Global contains all files which should be the same across all vservers created from this skel. When creating a vserver, these files will be hard linked to save diskspace, and given the immutable-linkage-invert bit (which means they cannot be modified, only deleted). Global usually contains stuff like /bin, /lib, /sbin and /usr (but not /usr/local).
local/
Local contains all the other files; files which should be considered unique to each vserver. When creating a vserver, these files will be plain copied. This includes /etc and /var.
static/
Static is a special case, containing files which, like local, should be considered unique to each vserver. But these files will not be copied when doing a --merge-skel, so they will not be changed by package updates. More importantly, when a vserver is created, static files are scanned for special tokens which are replaced with the vserver's attributes: VS_NAME, VS_IP and VS_FQDN. By default this is currently only used for the /etc/hosts file.

There are two other items in each skel:

scripts/
The scripts directory contains scripts (or links to scripts) which are run at particular times when performing operations on a skel. Currently there is only one kind of script, post-create-vs scripts which are run after creating a vserver from the skel. One script (or "plugin") is provided, passwd.pl, which will configure the root password in the new vserver. Other scripts can be dropped into this directory and will be automatically executed at the appropriate time; it is intended that this will be an interface for configuration of software packages, e.g. MySQL?, Apache, Postfix, etc. that may need configuring for each vserver before use.
configfile
This is a template for the vserver configuration file (containing %% tokens similar to those in static files). If you want your vservers using this skel to have different default options, you can change them here. Changing this file only changes the default configuration file generated for vservers; it doesn't "configure" anything itself.

What It Does

VSkel will tell you what it is doing while it is building the skel, but basically what it does is:

  1. Makes the skel directory and component subdirectories under /vservers/.skel/<skel name>;
  2. Copies /bin, /lib*, /sbin and /usr to the global directory;
  3. Copies /etc and /var to the local directory;
  4. Moves usr/local from global to local;
  5. Sets all files in global to have the immutable-linkage-invert bit using chattr;
  6. Makes some empty local dirs: /home, /root and /tmp;
  7. Makes /dev in local, copying only the system devices necessary for a vserver;
  8. Moves the passwd, shadow, group and gshadow files from /etc to static, and writes out a static /etc/hosts file using %% tokens;
  9. Makes a symlink to each script in /etc/vservers/vskel/scripts in the skel's scripts directory;
  10. Copies /etc/vservers/vskel/configfile.default to /vservers/.skel/<skel name>/configfile;
  11. Prints a nice big warning explaining how you need to double check everything in the skel it just created.

Once you have a skel created and you have double checked everything in it, you can start making vservers.

2. Creating a Vserver

Creating a vserver is as simple as typing:

vskel.pl --create-vs myskel

VSkel will prompt you to enter information about the vserver you are creating (name, IP address and domain name). If you prefer, you can provide this information on the command line, for example:

vskel.pl --create-vs myskel testvs test.example.com 192.168.1.10

What It Does

  1. First it creates the vserver directory, /vservers/<vs name>;
  2. Hard links are created to everything in the skel's global directory;
  3. Everything in the skel's local directory is copied;
  4. Each file in the skel's static directory is copied and any %% tokens are replaced with the vserver's correct values;
  5. A proc/ directory is created;
  6. The skel's configfile is copied to /etc/vservers/<vs name>.conf and all %% tokens are replaced with the vserver's correct values;
  7. The vserver is assigned a unique context ID;
  8. Lastly, it runs each plugin script in the skel's scripts/post-create-vs directory to perform post-creation vserver/package configuration.

3. Turning a Skel into a Temporary Vserver

If you need to install/upgrade/remove a package in a skel, you'll need to turn the skel into a single tree so that you can run rpm inside it. This can be accomplished like so:

vskel.pl --merge-skel myskel

This essentially creates a vserver from the skel, but without performing some of the configuration steps performed on a vserver. A temporary vserver is created with the name tmp_skel_<skel name> in /vservers. You can "enter" this vserver, but avoid trying to "start" it, or you may create unwanted log files and such. Also watch out for e.g. .bash_history files in /root in the skel.

Note that the skel's static/ directory is not merged, so any static files will not exist in the temporary vserver.

When a temporary vserver is created from a skel, a copy of the original skel's global/ and local/ directories are kept as global.bak/ and local.bak/ under the skel directory.

The intended use of merging is for package management using the vrpm command, e.g.:

vrpm tmp_skel_myskel -- -Uvh somerpm.rpm

Caveats

  1. Updating a package in the skel using rpm will unlink the files before they are updated (this is the default behaviour of rpm, and is required with the immutable-linkage-invert bit for security in any case). While the skel will be updated fine, any changes will not show through to vservers built from this skel. Hopefully VSkel will be extended to resolve this in the future. Meanwhile, a less than ideal solution is to update the skel (for the sake of future vservers), and to also install the package updates in each existing vserver using vrpm with the --unify option. Note that this will unify the vservers with each other, but not with the skel.
  2. Recreating the skel from the temporary vserver requires making some assumptions about which directories in the skel are global and which are local. See the following section.

4. Turning a Temporary Vserver Back Into a Skel

When you have finished making changes to packages in a skel, and before you can again create vservers from the skel, the skel needs to be recreated in its original form:

vskel.pl --split-skel myskel

This will turn the temporary vserver tmp_skel_myskel back into the skel myskel.

Caveats

  1. To split the temporary vserver back out into global and local directories, VSkel has to make assumptions about which directories are global. The default behaviour is the same as for building the skel with --build-skel, i.e. /bin, /lib*, /sbin and /usr (but not /usr/local) are global, while everything else is local. You can of course edit VSkel if you need it to work differently...

Context IDs

VSkel uses its own system for managing context IDs (maybe this will become standard, unless someone finds a better way). For compatibility with the [Per Context Quota] / [Per Context Disk Limits] vserver patches, VSkel gives each vserver it creates a fixed context ID, rather than using dynamically assigned context IDs.

By default, VSkel starts numbering vservers at context ID number 50. This can be set by the $opt_ctxstart line at the top of vskel.pl.

The first time you create a vserver with VSkel, a directory /etc/vservers/contexts, and a file /etc/vservers/contexts/nextid containing one line, probably "51", will be created. The nextid file tells VSkel (or any other script using this method) what ID number to use for the next vserver created.

In addition, when a vserver is created, a symbolic link will be created in this directory to the vserver directory, named with vserver's context ID number; e.g. a vserver called "test" with context ID 53 will have a symbolic link 53 -> /vservers/test in /etc/vservers/contexts.


This software is released under the [GNU General Public License].

Copyright (C) 2003 Simon Garner

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.