Chapter 3. Using SystemImager

3.1. Installation Procedures Overview

  1. Using the instructions in Chapter 2, install the SystemImager server package on the machine you have chosen as your image server.

  2. Install Linux on your golden client and customize as desired.

  3. Using the instructions in Chapter 2, install the SystemImager client software on the golden client.

  4. Run the prepareclient command on your golden client.

  5. Choose and configure the method for assigning IP addresses to your autoinstall clients. This information is required for the getimage command in the next step; however, you can change these settings later by running the mkautoinstallscript command.

  6. Run getimage on the image server to pull the golden client to the image server.

  7. Run addclients on the image server to tell it which clients will receive what image and to populate the image server's /etc/hosts and /var/lib/systemimager/scripts/hosts file.

  8. Autoinstall the golden image on other machines.

Note

See the SystemImager Tools section in this chapter for detailed tool descriptions and functions.

3.1.1. Detailed Installation Instructions

  1. Install the SystemImager server package on the machine you have chosen as your image server, using the instructions in Chapter 2.

  2. Install Linux on your "golden client" and customize as desired. Remember that the software installed will eventually constitute the golden image for all other nodes installed with SystemImager. Don't worry too much about getting it exactly right the first time, as you can easily use SystemImager to make incremental changes to your image and deploy those changes without doing a complete re-install.

  3. Install the SystemImager client software on the golden client using the instructions in Chapter 2.

  4. On the golden client, run the command prepareclient as root. This will create various files in your /etc/systemimager directory that contain information on your disk partition scheme, filesystem types, etc. prepareclient will also start an rsync daemon to allow its files to be transferred to a server. Your golden client is now ready to have its image pulled by an image server.

    Warning

    If you are not in ssh mode, all files on your golden client are openly accessible to anyone on your network. Once you have pulled the image from your golden client, you can deactivate the rsync daemon by killing the rsync process or by simply rebooting the golden client. This rsync server will not start automatically on future reboots.

  5. Choose and configure the method for assigning IP addresses to your autoinstall clients.

    The most common way to assign IP addresses to autoinstall clients is DHCP. To simplify the configuration of the DHCP configuration file (/etc/dhcpd.conf), SystemImager includes a utility called mkdhcpserver. This utility asks you for all the information it needs to create a DHCP configuration file that is appropriate for your installation of SystemImager. After installation, you can use DHCP to assign static IP addresses to your clients on an ongoing basis by running the mkdhcpstatic command after your clients have booted and received an IP address. mkdhcpstatic will modify your /etc/dhcpd.conf file on the imageserver to include static entries for each of your hosts.

    Alternately, you can put hostname, imageserver, and networking information in a configuration file on a floppy diskette. The format of the configuration file is simply VARIABLE=value for all the appropriate settings. The name of this file must be local.cfg and it must exist on the root of the floppy or hard drive. The floppy can be formatted with either ext2 or fat. An example local.cfg file, such as the one below, can be found with the documentation files that are usually installed in /usr/share/doc.

    Example 3-1. Contents of an example local.cfg provided with SystemImager:

    	    HOSTNAME=www1
    	    DOMAINNAME=systemimager.org
    	    DEVICE=eth0
    	    IPADDR=10.0.0.99
    	    NETMASK=255.255.255.0
    	    NETWORK=10.0.0.0
    	    BROADCAST=10.0.0.255
    	    GATEWAY=10.0.0.1
       	    GATEWAYDEV=eth0
    	    IMAGESERVER=10.0.0.3
    	    IMAGENAME=oracle_db_server-1.0 
    	  

    Alternatively, if you are using a running system's hard drive as the boot media, you can run updateclient -autoinstall -server <imageserver> -configure-from eth0 , which will create a local.cfg file at the root of the client's hard drive containing the existing live network settings. When the autoinstall client boots, it will look for this file and use the provided values instead of getting them from DHCP and the /var/lib/systemimager/scripts/hosts file on the image server.

    A local.cfg file on a floppy will work with any of the autoinstall media. You can even put the configuration file on the autoinstall floppy itself. If you use a local.cfg file on a hard drive and on a floppy, the settings on the floppy will override the settings on the hard drive.

    Example 3-2. Running mkdhcpserver

    [root@imageserver]# mkdhcpserver
    	  

    Example 3-3. Running updateclient with the "-autoinstall" and "-config" options

    Note that the options -autoinstall, -server, and -configure-from are abbreviated below as -a, -s, and -c. You can abbreviate options to minimum uniqueness with most SystemImager commands.

    Minimum uniqueness means that if two options for a single command are similar, such as the -image and -ip-assignment options to getimage, you can abbreviate them to -im and -ip.

    [root@server7]# updateclient -a -s imageserver -c eth0
    Retrieving SystemImager kernel...
    Retrieving SystemImager initial ramdisk...
    Adding SystemImager entry in /etc/lilo.conf...
    running /sbin/lilo -d 50 -D systemimager ...
    Ignoring entry 'delay'
    Ignoring entry 'default'
    Added linux
    Added systemimager *
    
    <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
    Below are the contents of your /local.cfg file.  Make sure that all
    the variables are filled in and that they contain the proper values.
    You may edit the file directly if you need to change any of the values.
    <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
    
    #
    # "SystemImager"
    #
    #  Copyright (C) 1999-2002 Bald Guy Software <brian.finley@baldguysoftware.com>
    #
    # This file is: /local.cfg
    #
    HOSTNAME=server7
    DOMAINNAME=mydomain.com
    DEVICE=eth0
    IPADDR=192.168.1.7
    NETMASK=255.255.255.0
    NETWORK=192.168.1.0
    BROADCAST=192.168.1.255
    GATEWAY=192.168.1.254
    GATEWAYDEV=eth0
    IMAGESERVER=192.168.1.203
    	  
  6. Run getimage on the image server to pull the image from the golden client to the image server.

    Example 3-4. Pull the golden client's image to the image server

    The basic syntax is: "getimage -golden-client [client_hostname] -image [image_name]"

    Where [client_hostname] is the hostname or IP address of the "golden client" and [image_name] is the name you want to give to this image. You can see many other options with "man getimage."

    Example 3-5. Running getimage

    	    [root@imageserver]# getimage -golden-client my-golden-client -image web_server_image_v1
    	  

    getimage contacts the golden client and requests its /etc/systemimager/mounted_filesystems file, which contains the list of mounted filesystems and their mount points. getimage pulls out the mount points for the filesystems that are unsupported and creates an exclusion list. The filesystems SystemImager currently supports are ext2, ext3 and reiserfs. All other filesytems will be ignored, including proc, nfs, devpts, iso9660, etc.

  7. addclients creates a symbolic link to the master script for the image to which each specified autoinstall client is assigned. addclients also populates the image server's /etc/hosts and /var/lib/systemimager/scripts/hosts files. The hosts file provides the default mechanism used by autoinstall clients to look up their hostnames.

    When addclients is run without arguments, it takes you through three configuration screens interactively.

    1. In the first configuration screen addclients, asks you to specify the hostname pattern of your autoinstall clients. Autoinstall client hostnames are comprised of [basename][number]. For example, if you choose "proxy" as your basename, and 3-10 as your range, you will define the following autoinstall clients:

      proxy3
      proxy4
      proxy5
      proxy6
      proxy7
      proxy8
      proxy9
      proxy10

    2. In the second screen, you map the clients defined in Section 1 to an image.

      Note

      Each invocation of addclients allows you to map a single range of clients to an image. If you want to map non-consecutive ranges of clients to an image, or want to map different client ranges to different images, you must execute the addclients command multiple times.

    3. In the third configuration screen, the addclients command asks you for a range of IP addresses from which it populates your /etc/hosts and /var/lib/systemimager/scripts/hosts files. When an autoinstall clients boots, it will attempt to retrieve the latter file from the image server and use it to look up its hostname. If this step fails, the client will attempt to do a reverse DNS lookup. If you have PTR records configured for each of your autoinstall clients, you can skip the third configuration step; however, it is recommended to complete it because it is more robust.

      Example 3-6. Entries in /etc/hosts created by addclients

      If you give addclients a range of IPs from 192.168.1.1-192.168.1.99, a base hostname server, and a hostname extension range of 1-99, then it would generate the following /etc/hosts file:

      192.168.1.1    server1.mydomain.com  server1
      192.168.1.2    server2.mydomain.com  server2
      192.168.1.3    server3.mydomain.com  server3
      192.168.1.4    server4.mydomain.com  server4
      192.168.1.5    server5.mydomain.com  server5
      192.168.1.6    server6.mydomain.com  server6
      192.168.1.7    server7.mydomain.com  server7
      192.168.1.8    server8.mydomain.com  server8
      192.168.1.9    server9.mydomain.com  server9
      192.168.1.10   server10.mydomain.com  server10
      192.168.1.11   server11.mydomain.com  server11
      
      [ ... etc, etc, etc ... ]
      
      192.168.1.97    server97.mydomain.com  server97
      192.168.1.98    server98.mydomain.com  server98
      192.168.1.99    server99.mydomain.com  server99
      	  

  8. Autoinstall the golden image on other machines.

    You can use one of four methods to autoinstall the clients:

    • Boot the system from a floppy diskette.

      Run mkautoinstalldiskette to create an autoinstall diskette that you can use with any machine unless you add a customized /local.cfg file to the diskette.

    • Boot the system from a CDROM.

      Run mkautoinstallcd to create an ISO image that can be burned to CDROM. You can use the CDROM to boot your autoinstall clients and use it with any machine.

    • Boot the system from its own hard drive.

      If your client is already running Linux and uses LILO as its boot loader, you can simply copy the updateclient command and run it with the -autoinstall option.

      Example 3-7. Booting the autoinstall media from a system's hard drive

      		[root@server7]# updateclient -a -s imageserver -c eth0
      	      
    • Boot the system from the network. If your systems are network-boot capable, using PXE for example, you can start an autoinstall without using local media.

      PXE is usually enabled through a BIOS setting. Booting can be unstable and client side firmware is not consistent. If you must boot without physically touching your machines, try the -autoinstall option to updateclient first.

      SystemImager comes with the mkbootserver utility to help configure a PXE server. Running mkbootserver is an iterative process. It will attempt to generate an appropriate tftproot directory, configure your tftp server, and run various tests to see if things are functioning properly. Once mkbootserver detects an error, it will fail out and generate an error message. When you have corrected the error, you can re-execute mkbootserver, and repeat until it exits successfully. mkbootserver will probably not work with all PXE clients. If it fails to work with your configuration, please submit a bug report to http://sourceforge.net/tracker/?group_id=259&atid=100259.

3.1.2. SystemImager Tools

3.1.2.1. the prepareclient command

  • After configuring the golden client, run the prepareclient command to create a file with the partition information from your disks and put it in the /etc/systemimager/partitionschemes directory.

  • prepareclient will also create an rsync(1) configuration file (/tmp/rsyncd.conf) and start rsync in server mode (rsync--daemon). This step allows the image server to pull the image from the client but will not cause the rsync daemon to be restarted after the golden client is rebooted, helping avoid security concerns from sharing a golden client's root filesystem via rsync.

3.1.2.2. The getimage command

  • After running prepareclient, run the the getimage command on the image server. For example : getimage -golden-client 192.168.1.1 -image my_webserver_image_v1

  • getimage contacts the golden client and requests its /etc/systemimager/mounted_filesystems file, which contains the list of mounted filesystems and the devices on which they are mounted. It pulls out the mount points for the filesystems that are unsupported and creates an exclusion list. Currently supported filesystems are ext2, ext3, and reiserfs. All other filesystems are unsupported, including proc, devpts, iso9660, etc.

  • getimage then pulls the golden client's entire system image, excluding the filesystems in the exclusion list, by connecting to the rsync daemon running on the golden client. All the files from the client will be copied over, recreating the file and directory hierarchy in the image directory.

  • You can also use getimage to update an existing image by simply specifying an existing image name, for example, getimage -golden-client 192.168.1.1. -image <imagename>. getimage then updates the image to match the files on your golden client. When you do this, only the parts of files that are different will be copied over. Files that exist in the old image but not on the golden client will be deleted, and files that exist in both places but have changed will be updated. getimage is one way to update an image when new security patches or other system updates come out. However, this method is revision control on an image-by-image basis, and not true revision control where individual file revisions are tracked on a line-by-line basis. The recommended method is never to overwrite a known working image. Revision control on an image-by-image basis also ties in to the updateclient command. By default, all images are stored in the parent directory of /var/lib/systemimager/images/ in a directory that bears the image name. For example: /var/lib/systemimager/images/my_webserver_image_v1/

3.1.2.3. Autoinstall scripts

  • After getimage has pulled the files to the image directory on the imageserver, it creates a customized autoinstall script. The autoinstall script in this example is named "my_webserver_image_v1.master". All autoinstall scripts are placed in the /var/lib/systemimager/scripts directory.

  • The disk partitioning information left behind by the prepareclient command adds the necessary commands to re-partition the disk(s) on the autoinstall clients.

  • File system information is taken from the /etc/fstab file in the image (i.e.: /var/lib/systemimager/images/my_webserver_image_v1/etc/fstab) and used to determine the appropriate file system creation commands and to determine mount points for the autoinstall process. Networking information is added to the autoinstall script based on command line options passed to getimage or information it prompts you for. This information is added in variable form as the autoinstall client will determine the values for things such as its hostname and IP address during the autoinstall process.

3.1.2.4. The addclients Command

  • After running getimage, run the addclients command, which asks you for the series of hostnames you will be installing by combining a base host name and a number range. For example, if your base host name is "www", and your number range is from "1" to "3," then the resultant host names would be "www1, www2, www3". addclients then prompts you to choose the image that will be installed to these hosts and creates soft links for each hostname that point to the master autoinstall script for that image. For example: "www3.sh -> web_server_image_v1.master".

  • If the image is updated and you allow getimage to update the master autoinstall script also, then each of the associated soft links will point to the updated autoinstall script. If individual host configuration is necessary, the soft link for that host can be removed and replaced with a copy of the master autoinstall script that can then be customized for that host. This customization is a manual process and is up to the system administrator.

3.1.2.5. Additional Installation Information

  • The unattended install procedure is flexible and works with almost any available hardware. You can also easily modify it to work with new or special hardware. A miniature Linux distribution called Brian's Own Embedded Linux (boel) is used for autoinstalls. It consists of a customized kernel and an initial ram disk that contains only the specific commands and utilities necessary to perform autoinstalls. The same kernel and initial ram disk (initrd.gz) can be used to boot from floppy disks, CDROMs, the network, or any running Linux system's local hard drive.

    The mkautoinstalldiskette and mkautoinstallcd commands use the syslinux(2) utility to create floppies and CDROMs that will boot the SystemImager kernel and initial ram disk. pxelinux(2), which is a sister tool to syslinux, allows the same kernel and initial ram disk to boot PXE capable machines from the network. Both syslinux and pxelinux need a configuraton file, but the two tools can use the same one and SystemImager handles this for you.

  • The autoinstall kernel contains all the necessary drivers for the majority of systems. Custom kernels can be compiled to meet special disk and network driver requirements. To use a custom kernel, simply copy it to /tftpboot/kernel. All of the autoinstall media is created from /tftpboot/kernel and /tftpboot/initrd.gz on the image server.

  • Once the kernel has booted, it mounts the initial ram disk as its root filesystem. The kernel then executes an initialization script on the ram disk that has been written to do SystemImager-specific tasks. This script will use either a configuration file (/local.cfg) or a combination of DHCP and the /var/lib/systemimager/scripts file pulled from the image server to determine the autoinstall client's IP address and hostname information.

    If DHCP is used, the client parses the hosts file which was retrieved from the image server to find its IP address and determine its hostname. Finally, the client retrieves an autoinstall script from the image server based on its hostname and executes it. The autoinstall script is image specific, determining which image a client will receive. Following is a summary: IP address -> hostname -> image specific autoinstall script named with hostname.

3.1.2.6. How to Update an Image

  • If you want to update an image on your image server, you can use one of the two following methods:

    1. Directly edit the files in the image directory. The best way to do this is to chroot into the image directory. You can then work with the image as if it were a running machine. You can even install packages with apt-get or RPM, for example.

    2. Run the getimage command again, specifying a golden client that has been modified in the desired way. Again, only the parts of the files that have changed will be pulled across. Files that have been deleted on the golden client will also be deleted in the image. You have the option to update the master autoinstall script for the image or leave it alone. The advantages of running the getimage command are that you can verify that your new configuration works on the golden client and that the master autoinstall script is updated.

  • Once a system has been autoinstalled, you can use the updateclient command to update a client system to match a new or updated image on the image server. So, for example, if you've installed your company's 300 web servers and a security patch comes out the next day, you can simply update the image on the image server and run updateclient on each of your web servers. Only the modified files are pulled over, so your site is patched very quickly. You should create an entirely new image with a new version number so that you have some form of revision control. This way, if you find out that the patch you applied corrupted your entire web farm, you can simply do an updateclient back to the last known working image.

  • By incorporating some modifications submitted by A. L. Lambert of epicRealm, you can use the updateclient command with the -autoinstall option to copy the autoinstall kernel and initial ram disk to the local hard drive of an autoinstall client that is currently running but needs to be re-deployed. updateclient then modifies the /etc/lilo.conf file to include an appropriate entry for the new kernel and initial ram disk and makes this new kernel the default. The next time the client system boots, it loads the SystemImager kernel and initial ram disk, which begins the autoinstall process. You can therefore remotely redeploy any running Linux machine without feeding the machine a floppy or CD and without having to reconfigure the BIOS to boot off the network, which can be quite problematic with some BIOSes.