Configuring and Using Systemimager on Linux Systems

These notes are still in a preliminary stage of development.

Introduction

Systemimager forms a component of a collection of programs known as Sisuite (an abbreviation for Systemimager Suite) that allow for easy installs of large numbers of similar Linux systems. As a consequence, it can also be used as a simple method to backup an existing host and make it possible to re-install the host with a past state.

Depending on the version of systemimager, it may be necessary to prefix si_ to a command that does not begin with this prefix.

Preparing a host to be imaged

Start by choosing a host which has Systemimager client program prepareclient installed. On an Ubuntu or Debian system this can be done by installing the package systemimager-client.

To prepare a host (known as the golden client if it will serve as the basis of an image to be installed elsewhere) run the command (as root)

       prepareclient --server IMAGESERVER --yes --config file

(NOTE. There is a bug in Linux that sometimes results in NFS mounted directories not being displayed by programs like df. In particular, prepareclient relies on this to generate the file /etc/systemimager/mounted_filesystems which is then used by getimage to avoid getting such NFS mounted file systems) where IMAGESERVER would be substituted with the hostname of the image server, that is, the host where the host's files will be stored. The option --yes will answer yes to all questions and file contains all the name of the IMAGESERVER which results in this file being stored in the initrd.img file (it is NOT sufficient to simply specify it with the option =--server as the assumed image server when installing a client is the dhcp server that responds, provided such a server responds). The end result is an rsync server will be launched with a dynamically generated config file that ensures only the IMAGESERVER has permission to access the server. For additional options refer to the manpage.

Setting up the image server and creating the image of a prepared host

To have the command getimage available, install the systemimager-server package.

To retrieve the files of the GOLDENCLIENT run the command

  getimage --golden-client GOLDENCLIENT --image IMAGENAME

on the image server, where GOLDENCLIENT should be substituted with the hostname of the golden client. The preceding command will cause rsync to fetch all files (except for some host specific files) and store them under /var/lib/systemimager/images/ (/var/lib/systemimager can be a softlink to a sufficiently large disk partition). Take care not to touch the files in this image as rysnc relies on time stamps to determine whether it should update a file.

You may be asked what method you want to use to assign IP addresses to hosts that install or update themselves with the image. If the hosts in question use DHCP then that is the default method and should be chosen else you probably should use static option (which is necessary for some of our hosts). In the event you are backing up a single host use the replicant method and *name your image* appropriately to make it clear that it should not be installed on multiple hosts (this will alert anyone who chooses to install this on additional hosts that some manual reconfiguration on the host to fix the IP address and hostname will be required).

If you want to autoinstall the image on a new host it is useful to add the --post-install to getimage which controls the behaviour of the image when the --autoinstall option is used when running the updateclient command on a client you want to either update with the image or install with it. Specifically the auto installed host will either beep, reboot, or shutdown the client. It may be necessary to

PREFERED=Boot::Grub

to the file /etc/systemconfig.conf within the "[BOOT]" section. if the file /boot/grub/menu.lst does not contain an entry for systemimger. You may want to update-grub after running updateclient and check that both the systemimager and normal boot entries exist (these are useful if the systemimager portion did not boot or failed prior to repartitioning of the disk). Make sure the systemimager kernel is the default and reboot the machine.

Installing the Image on Another Computer

By re-installation we really do mean that the disks are repartitioned and all software on the host is installed from the fetched image. It is possible not do this by updating an old image with a new image on a running host but it is NOT recommended. Indeed, do not do it!

If you cannot remember the exact name of the image you want to update to run lsimage --server IMAGESERVER.

On an existing host that has Linux and Systemimager already installed

To auto install a client with an image execute the command setup the file /local.cfg and put in

IMAGESERVER=IP address of IMAGESERVER

if you are on any network that our DHCP server will respond to then, provided the host you are installing on is in our equipment database, our DHCP server will take care of providing systemimager with the correct networking attributes. If you do not have a /local.cfg file the files will be fetched from the responding DHCP server which, alas, which in CS network is not the same as the imageserver, and consequently the install will fail. Hence the requirement for the existence of /local.cfg.

If, on the other hand, you are not on a network which has IP addresses configured via our DHCP server (the 152 network, for example, which contains the frontends) you will need to add more information to /local.cfg (we give mef-fe02.student.cs an explicit example):

HOSTNAME=mef-fe02.student.cs
DOMAINNAME=uwaterloo.ca
IMAGESERVER=129.97.15.78
DEVICE=eth0
IPADDR=129.97.152.70
NETMASK=255.255.255.0
NETWORK=129.97.152.0
BROADCAST=129.97.152.255
GATEWAY=129.97.152.1
GATEWAYDEV=eth0

Next execute the command

     updateclient --server IMAGESERVER --auto-install

where IMAGESERVER is the same as IMAGESERVER as specified in /local.cfg (you can use a DNS name as opposed to an IP address here). The program will query the image server for possible images to install and you are asked to choose (unfortunately you cannot specify the image name when the --auto-install option is invoked). The program will note the presence of the /local.cfg and mount the root partition during the install and access the file, next it will then install the kernel and initrd images belonging to the image you have chosen to install and overwrite (hopefully this will be more configurable in later versions of systemimager) the boot loader configuration file so that only the systemimager kernel and initrd downloaded from the golden client becomes the only bootable option. I usually preserve the old version of the boot loader config file before and then restore it with the systemimager kernel and initrd being the default boot option as this allows for a return if the auto install fails (only possible if the disk partition phase was not reached in which case you'll need to use an install cdrom or if we had a PXE server and Imageserver that coincided we could just use that option).

The systemimager suite of tools can be used to install clients via DHCP and PXE boot images but in the case documented above this was not done, i.e., the client was installed manually first and then synced up to the golden client via the description above. Clearly we should pursue this setup further!*

In the case of PXE installs, we must have that the PXE server (i.e., the DHCP server) must be the same as the IMAGESERVER or, if they differ, the /local.cfg file must be put directly into initrd.img file

On a machine that does not have systemimager installed on it

A host that does not have systemimager installed may be a fresh host that has not be installed with an OS yet but has PXE boot capabilities. For this instance we need either have that the images are also installed on the PXE/DHCP server as the install media assumes these are the same unless a local.cfg has been installed into the initrd.img filesystem in / using the --config option to si_prepareclient.

Managing an Image

There are two ways, namely, manage the golden client directly by logging on and doing the usual system admin thing after which you would save a new version of the golden client's image, or, log on to the image server and manage the image by chrooting into it, i.e.,

chroot /var/lib/systemimager/<image name>/

and then you should be able do the usual system adminstration task such as apt-get new packages, etc. My recommendation is to only manage the golden client directly as you have the option of testing changes directly whereas a chroot environment isn't identical. Ideally the golden client should NOT be a system that our user base logs into, i.e., we need a test system to act as a golden client. Vmware might be an option for a test client.

Miscellanous tidbit

Kernel Boot Options that can be set

See http://wiki.systemimager.org/index.php/Installation_Parameters. In particular, one put in IMAGESERVER=imageserver

Large scale installations using BitTorrent

See http://wiki.systemimager.org/index.php/BitTorrent.

Modifying an image after retrieval

Suppose you want to adjust the image after it has been retrieved using si_getimage, in particular, you want to make it possible to grow the partitions to the full extent of the disk on a client (we assume the clients may have different size disks), then you can edit /var/lib/systemimager/images/$IMAGENAME/etc/systemconfig/autoinstallscript.conf, see http://wiki.systemimager.org/index.php/HOWTO_Net_Boot_Ubuntu#Adjusting_Your_Image_After_Retrieval for more details.

The file /etc/systemconfig/systemconfig.conf cannot be edited on a client directly as it will be overwritten everytime you run si_prepareclient. This file is used by si_getimage on the server to generate an install script located in /var/lib/systemimager/scripts/ where the script name is $IMAGENAME.master, which can be edited. In particular, it may be necessary to change the mount options as the busybox software in SystemImager may be too old to recognize some options, in particular, the relatime option is unrecognized in version 4.1.6. When re-retrieving an existing image it will ask whether you want to overwrite the autoinstall script. If you've modified it answer no.

Listing available images on the IMAGESERVER

If you want to know what images are available on a server, type

   lsimage -server IMAGESERVER

on any host that has the systemimager-client package installed installed (Ubuntu/Debian platforms). If you get a permission denied see the next paragraph.

To configure the behaviour of the systemimager rsync daemon process on the image server, edit the files in in /etc/systemimager/rsync_stubs/ and running mkrsyncd_conf which will regenerate the file etc/systemimager/rsyncd.conf which is used when the sytemimager managed rysnc process is managed by the init script /etc/init.d/systemimager-server. You should restart the daemon by running /etc/init.d/systemimager-server restart in order that your changes take effect (it seems the mkrsyncd_conf command does not do this although I'm not sure).

See SystemimagerDebug for ongoing work on debugging the latest versions of Sisuite as taken from subversion.

Whenever getimage runs it stores the kernel and initrd.img files in /usr/share/systemimager/boot/$ARCH/$IMAGENAME= where $ARCH is the debian architecture of the image (i386, amd64 are examples). By default the initrd.img does not contain a local.cfg file but one can modify it as follows. Go to the directory were the kernel and initrd.img files are stored and do

  mkdir unpacked-initrd 
  cd unpacked-initrd
  gzip -dc ../initrd.img |cpio -id
  modify the stuff in unpacked-initrd
  find ./ | cpio -H newc -o > ../initrd.img

This is useful in our case since one can then imbed the name of the IMAGESERVER as it does not agree with our dhcp server. NOTE when you rerun getimage it will clobber the modified initrd.img

To create a cdrom install run mkautoinstallcd --flavor $IMAGENAME --out-file $IMAGENAME.iso

External References

• http://wiki.systemimager.org is the home page of Systemimager and Sisuite,