Warning Livedoc is no longer being updated and will be deprecated shortly. Please refer to https://documentation.tjhsst.edu.

Difference between revisions of "SystemImager"

From Livedoc - The Documentation Repository
Jump to: navigation, search
m (Robot: Adding Category:Stub)
Line 62: Line 62:
[[Category:Obsolete Page]]

Revision as of 21:10, 12 May 2012

SystemImager is a package (mainly written in Perl) that we use to automate workstation management.


  • SystemImager (SI) offers basically two ways to update a machine's disk image.
    • The machine can be netbooted via PXE. The disks will be partitioned and formatted to match the image, and the entire image will be copied over. This is useful when first installing the machine, or when switching to an entirely new image. The process is also known as an autoinstall
    • Once a system is installed on the machine, the image can be updated, which will use rsync to copy only the parts of the filesystem that have changed since the last image.
  • It uses a client/server architecture. The image server stores as many images as desired (in /var/lib/systemimager/images/), and all workstations fetch their images from the server. It should be a reasonably fast machine with enough disk space for all the images you want to store, but it's hardware need not resemble the client machines.
  • The golden client is the machine, which should be very similar to the target machines, on which the image is created and maintained. Install a system on it and configure it as desired. Then install SystemImager. The image server will pull images from the golden client. This also uses rsync, so an image can be "updated" efficiently, however the preferred technique for normal operation is to make changes on the golden client then create a new image. That way, if there are serious problems with the new image, any system can be painlessly rolled back to the working image until the new one is fixed.

The Autoinstall Proccess

This is an in-depth description of netbooting, and more specifically SI's autoinstall system. Feel free to skip it unless you're interested.

  • The client boots either from a floppy such as Etherboot, or a BIOS built-in netboot utility (F12 on our HP desktops). It requests DHCP.
  • The DHCP server gives it an IP address and passes several related options stored in its config file, primarily "next-server" which contains the name of the netboot server, and "filename". These options can be unique to the client, or can be applied to a group of clients.
  • The client connects to the specified server using TFTP (trivial file transfer protocol). The server is running a tftp daemon, which exposes part of its filesystem (usually /tftpboot). The client downloads the specified filename ("pxelinux.0").
  • This PXE-Linux file is booted. It fetches configuration from the tftp directory pxelinux.cfg, trying to find a config file based on its IP address and falling back to "default".
  • This file tells it the name and options of the kernel to boot, which it fetches from tftp. It also grabs an initial ramdisk (initrd), if necessary.
  • The kernel + ramdisk is booted, and the netboot phase is complete. Enter SystemImager.
  • The ramdisk was either provided with SI or built on the golden client during the "prepareclient" step (see below). A custom built ramdisk and kernel is referred to as UYOK (Use Your Own Kernel), and is necessary if the provided ramdisk doesn't support enough of your hardware.
  • The ramdisk contains a compressed root filesystem with a few basic utilities (a mini Linux distro known as BOEL). It's init script, /etc/init.d/rcS, is loaded by init. This script sources the file /etc/init.d/functions, which defines a lot of functions used by SI. It starts networking, checks for local configurations, does some other odds and ends, and then uses rsync to fetch the scripts directory from the image server (whose name it was informed of via a custom DHCP option) to a temporary location.
  • This directory, /var/lib/systemimager/scripts/, contains the autoinstall script. By default this script is called <image>.master, but the scripts directory contains symlinks which instruct the client which script to use (i.e. myclient.sh -> myimage.master). The script was generated by SI when the image was first fetched from the golden client, and may have been customized by the user. It contains all further needed information and performs the rest of the installation process.
  • User-created pre-install scripts (from the pre-install subdirectory of scripts) are run based on image name.
  • The hard drives are scanned, then partitioned and formatted to match the golden client (though they will be expanded to fill the available disk space). The MBR is wiped.
  • The new partitions are mounted in /a/. (trivia: this mount point appears to be stolen from Solaris.)
  • The entire image is copied via rsync from the image server into /a/. Depending on image size and network speed, this could take quite a while. (rsync is merely used for its fast network copying, not acceleration as the drive has been wiped.)
    • NOTE: SystemImager supports other methods of copying, namely BitTorrent (peer-to-peer) and Flamethrower (multicast), but I have not tested them at this time.
  • /etc/fstab is created directly from the script (not sure why).
  • Override files are processed
  • /proc, /sys, and /dev of the ramdisk environment are mounted in /a/. This will allow things to work in a chroot.
  • SystemConfigurator is then run in a chroot, to do some hardware configuration magic and (most importantly) install the bootloader (it detects LILO or GRUB, and possibly others).
  • User-created post-install scripts are chosen based on image name and run.
  • Filesystems are unmounted and the machine reboots into the new system.


SystemImager is installed on the golden client, image server, and all the clients. Certain commands are intended to be run on these different machines. They all have the prefix si_. Most of them require command line options to specify certain things, and run interactively to confirm actions and get further data unless told otherwise.

On the golden client:

  • si_prepareclient: This prepares the golden client to have its image pulled. First it creates an initial ramdisk for PXE booting based on the installed kernel modules. It copies this, plus the kernel, to /etc/systemimager/boot. It then starts an rsync daemon configured to listen for connections from the image server.

On the image server:

  • si_getimage: This updates an image or creates a new one, rsync'ing the entire filesystem of the golden client (except for network filesystems and stuff like that). The images live in /var/lib/systemimager/images/.

On the workstation:

  • si_updateclient: This updates the workstation's image from the imageserver using rsync. You must specify which image to pull.

All SI commands come with manpages and accept --help. See the SI manual (which is installed in various formats in /usr/share/doc/systemimager/) for complete documentation of all commands.

Configuration; CSL Specifics

Under construction

SystemImager is a complex and not very heavily developed collection of software that attempts the ambitious goal of imaging any GNU/Linux-like system. As one can imagine, it does not work ideally in all circumstances. Here is a description of the various things we've had to do to make it work, plus a description of how we have it set up.

  • /var/lib/systemimager/scripts/
  • /etc/systemimager/
  • /tftpboot/
  • /tftpboot/pxelinux.cfg/
  • other directories

See Also

Gentoo Image