Using the instructions in Chapter 2, install the SystemImager server package on the machine you have chosen as your image server.
Install GNU/Linux on your golden client and customize as desired.
Using the instructions in Chapter 2, install the SystemImager client software on the golden client.
Run the si_prepareclient command on your golden client.
Choose and configure the method for assigning IP addresses to your autoinstall clients. This information is required for the si_getimage command in the next step; however, you can change these settings later by running the si_mkautoinstallscript command.
Run si_getimage on the image server to pull the golden client to the image server.
Run si_clusterconfig -e to define the groups of clients, populate the image server's /etc/hosts and to associate images and overrides to groups. The command si_clusterconfig is available only in SystemImager 3.9.4 or later. Otherwise, you can always use the command si_addclients (see the next point).
This point can be skipped if si_clusterconfig has been used to choose the image to deploy on each client. Otherwise, if you are more familiar with si_addclients run this command 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.
Generate a boot media for your clients. There are four ways to boot the clients for auto-installation:
boot from network (PXE) - see si_mkclientnetboot(8)
boot from an auto-install CD - see si_mkautoinstallcd(8)
boot from an auto-install disk (USB drive or internal disk) - see si_mkautoinstalldisk(8)
boot from a running system - see si_updateclient(8)
Autoinstall the golden image on other machines using one (or more) generated boot media.
![]() | See the SystemImager Tools section in this chapter for detailed tool descriptions and functions. |
Install the SystemImager server package on the machine you have chosen as your image server, using the instructions in Chapter 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.
Install the SystemImager client software on the golden client using the instructions in Chapter 2.
On the golden client, run the command si_prepareclient as root. This will create various files in your /etc/systemimager directory that contain information on your disk partition scheme, filesystem types, etc. si_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.
![]() | 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, the rsync daemon will be automatically stopped. In case of errors during the image retrieval be sure to manually deactivate the rsync daemon by killing the process or by simply rebooting the golden client. This rsync server will not start automatically on future reboots. In rsync over SSH mode the rsync communication is performed opening a SSH tunnel from the image server to the golden client. |
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 si_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 si_mkdhcpstatic command after your clients have booted and received an IP address. si_mkdhcpstatic will modify your /etc/dhcpd.conf file on the imageserver to include static entries for each of your hosts.
Alternately, you can pass hostname, imageserver, and networking information via installation parameters, in the form of VARIABLE=value. Installation parameters can be defined in /etc/systemimager/pxelinux.cfg/syslinux.cfg or can be passed as argument of si_mkautoinstalldisk, si_mkautoinstallcd, or si_mkclientnetboot using the --append "STRING" option. For a complete list of the available installation parameters see http://wiki.systemimager.org/index.php/Installation_Parameters .
Alternatively, if you are using a running system's hard drive as the boot media, you can run si_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.
Example 3-2. Running si_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
si_getimage, you can abbreviate them to
-im
and -ip
.
[root@server7]# si_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-2010 Brian Elliott Finley # # 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
Run si_getimage on the image server to pull the image from the golden client to the image server.
With si_getimage the image server pulls all the files and directories from the root of the client's filesystem back to the image repository in /var/lib/systemimager/images.
The basic syntax is: "si_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 si_getimage."
Example 3-3. Running si_getimage
[root@imageserver]# si_getimage -golden-client my-golden-client \ > -image web_server_image_v1
si_getimage contacts the golden client and requests its /etc/systemimager/mounted_filesystems file, which contains the list of mounted filesystems and their mount points. si_getimage pulls out the mount points for the filesystems that are unsupported and creates an exclusion list. The filesystems SystemImager currently supports ext2, ext3, ext4, reiserfs, xfs, jfs and vfat. All other filesytems will be ignored, including proc, nfs, devpts, iso9660, etc.
Run si_clusterconfig to manage the groups of your clients in the SystemImager database.
si_clusterconfig can be used also to show the defined groups with the list of clients that belong to each group and/or the image associated to each client or group of clients. In show-mode the command accepts as argument a list of hostnames, host-ranges and/or host-group, it resolves them in the equivalent list of hostnames and prints them to stdout. The edit-mode can be interactive (option -e) or batch (option -u). In interactive edit-mode si_clusterconfig opens an editor in your terminal that allows to modify the client group definitions and their properties using a XML syntax. In batch edit-mode it only parses the pre-defined XML configuration (/etc/systemimager/cluster.xml) and refresh the opportune SystemImager internal configuration files.
![]() | Do not edit /etc/systemimager/cluster.xml directly. Always use si_clusterconfig -e to be sure that all the files needed by the installations process will be properly synchronized. |
Here is a well-commented example of a simple cluster configuration:
<?xml version='1.0' standalone='yes'?> <!-- ********************************* WARNING ************************************** This file has been generated by si_clusterconfig(8), do not edit manually! ********************************* WARNING ************************************** This is the main configuration file to describe the topology of your clients and your image server informations. This file will be used by all the SystemImager commands to identify the logical groups of your clients and their specific configurations. See comments below for more details. --> <xml> <!-- The image server hostname. --> <master>master1</master> <!-- This is the global name: this name will be used to identify all the hosts defined in this file (the global supergroup). IMPORTANT: this is a mandatory entry!!! --> <name>all</name> <!-- This is the global override: all the files stored in this overrides will be pushed to all the clients. IMPORTANT: this is a mandatory entry!!! If you don't want to use it do not create the global override in /var/lib/systemimager/overrides/ Multiple overrides can be specified as a list of multiple XML tags: <override>OVERRIDE_NAME_1</override> <override>OVERRIDE_NAME_2</override> ... <override>OVERRIDE_NAME_N</override> The OVERRIDE_NAME_1 ... OVERRIDE_NAME_N will be distributed preserving the same order as they appear in the XML file. This means that in case of file overlaps (more files in multiple overrides that should be distributed to the same target filename) the first hit wins. In this case OVERRIDE_NAME_1 is the most important and OVERRIDE_NAME_N is the least important. --> <override>all</override> <!-- Following there is an example of a "fake" group. The group name is "Local", it uses the image "Local", the override in /var/lib/systemimager/overrides/Local and it contains only the localhost server. Totally useless, but it's there to explain how it works... ;-) --> <group> <name>Local</name> <image>Local</image> <override>Local</override> <node>localhost</node> </group> <!-- This is a group that contains two nodes: node001 and node002. The group is called "Login" and it uses the override: The clients node001 and node002 will be auto-installed using the image: /var/lib/systemimager/images/SuSE10 And the override: /var/lib/systemimager/overrides/SuSE10_frontend After the initial installation it will be possible to keep in sync the common files for the Login group creating them into the "SuSE10_frontend" override and using the command si_pushoverride(8). It will be even possible to define host-only files creating an override using the hostname of the target client. For example all the files in /var/lib/systemimager/overrides/node001 will be distributed only to node001 (and in case of overlaps these files will replace the files that come from the group override and from the global override). --> <group> <name>Login</name> <!-- If a client belongs to multiple groups, the group with the higher priority will be used to choose the image for that client; for the overrides the groups will be sorted by group priority: in case of file overlaps first hit wins. In this example node001, that belongs to the group Login and Storage, will be auto-installed with the image SuSE10 and it'll receive the overrides in the following order (remember that in case of file overlaps first hit wins): SuSE10_frontend, SuSE10, Storage --> <priority>10</priority> <image>SuSE10</image> <!-- Also a group can have multiple overrides. The same rules for multiple values of the global overrides are valid also here. --> <override>SuSE10_frontend</override> <override>SuSE10</override> <node>node001,node002</node> </group> <!-- Another example. The group Storage contains 16 nodes (from node1293 up to node1308). They will be auto-installed using the image: /var/lib/systemimager/images/RHEL4 And the override: /var/lib/systemimager/overrides/Storage In general the best practice is to use the same name for the override and the group name (like this group). --> <group> <name>Storage</name> <priority>20</priority> <image>RHEL4</image> <override>Storage</override> <node>node001,node1293-node1308</node> </group> <!-- Define your custom groups below (and remember to remove or comment the previous entries if you don't want to use them). ... --> </xml>
si_addclients creates a symbolic link to the master script for the image to which each specified autoinstall client is assigned. si_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.
![]() | You can skip the si_addclients step if si_clusterconfig has been used at the previous point. Remember also that si_addclients is deprecated in favor of si_clusterconfig, so it is always suggested to always use si_clusterconfig. |
When si_addclients is run without arguments, it takes you through three configuration screens interactively.
In the first configuration screen si_addclients, asks you to specify the hostname pattern of your autoinstall clients. Autoinstall client hostnames are defined by a host-range string and a domain name string. For example, if you choose "systemimager.org" as your domain name, and "www07-www11,www20" as your range, you will define the following autoinstall clients:
www07.systemimager.org |
www08.systemimager.org |
www09.systemimager.org |
www10.systemimager.org |
www11.systemimager.org |
www20.systemimager.org |
In the second screen, you map the clients defined in Section 1 to an image. This section is optional if si_clusterconfig has been used.
![]() | Each invocation of si_addclients allows you to map a single range of clients to an image. If you want to map different client ranges to different images, you must execute the si_addclients command multiple times. |
In the third configuration screen, the si_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-4. Entries in /etc/hosts created by si_addclients
If you give si_addclients a range of IPs from "192.168.1.1-192.168.1.99", a hostname range of "server1-server99" and "mydomain.com" as domain name, 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
Create a boot media to auto-install your clients.
You can use one of four methods to autoinstall the clients:
Boot the system from a USB disk or an internal disk.
Run si_mkautoinstalldisk to create an autoinstall USB disk (or a generic disk) that you can use with any machine.
Boot the system from a CDROM.
Run si_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.
Auto-install the images from a running system.
If your client is already running GNU/Linux you can simply
execute the si_updateclient command and
run it with the -autoinstall
option.
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.
SystemImager comes with the si_mkbootserver utility to help configure a PXE server. Running si_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 si_mkbootserver detects an error, it will fail out and generate an error message. When you have corrected the error, you can re-execute si_mkbootserver, and repeat until it exits successfully. si_mkbootserver will probably not work with all PXE clients. If it fails to work with your configuration, please send a mail to sisuite-users@lists.sourceforge.net.
Now it's time to install the images on your clients simply booting them with the generated boot media and waiting for the full auto-installation.
After configuring the golden client, run the si_prepareclient command to create a file with the partition informations from your disks that will be put it in /etc/systemimager/autoinstallscript.conf.
si_prepareclient will also create a temporary rsync(1) configuration file (in /tmp 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. Once the image is successfully pulled from the golden client, this rsync daemon will be automatically stopped.
After running si_prepareclient, run the the si_getimage command on the image server. For example : si_getimage -golden-client 192.168.1.1 -image my_webserver_image_v1
si_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, ext4, and reiserfs. All other filesystems are unsupported, including proc, devpts, iso9660, etc.
si_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 si_getimage to update an existing image by simply specifying an existing image name, for example, si_getimage -golden-client 192.168.1.1. -image <imagename>. si_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. si_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 si_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/
/var/lib/systemimager/images/my_webserver_image_v2/
/var/lib/systemimager/images/my_webserver_image_HEAD/
...
After si_getimage has pulled the files to the image directory on the imageserver, it creates an auto-install script customized for the image. The auto-install script in this example is named "my_webserver_image_v1.master". All auto-install scripts are placed in the /var/lib/systemimager/scripts directory.
The disk partitioning information left behind by the si_prepareclient command adds the necessary commands to re-partition the disk(s) on the autoinstall clients.
Filesystem informations are taken from the /etc/systemimager/autoinstallscript.conf file in the image (i.e. /var/lib/systemimager/images/my_webserver_image_v1/etc/systemimager/autoinstallscript.conf) and used to determine the appropriate filesystem creation commands and to determine mount points for the autoinstall process. Networking informations are added to the autoinstall script based on command line options passed to si_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.
After running si_getimage, run the si_clusterconfig command, which opens an interactive editor where you can define the bindings of your images with your groups of clients.
The same operation can be done by si_addclients, which asks you for the hostname range you will be installing, but it doesn't have the concept of host groups, so you can specify only host ranges or single hostnames (the same can be done by si_clusterconfig). si_addclients prompts you to choose the image that will be installed to these hosts and creates symbolic 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 si_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, but it is stronly suggested to limit these manual customizations and to always double check them before opening a new bug.
![]() | The configurations made by si_addclients can ovverride the configurations made by si_clusterconfig. In order to exclude unexpected problems it is strongly suggested to always use si_clusterconfig, and leave si_addclients only to populate /etc/hosts. |
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.img) can be used to boot from USB disks, CDROMs, the network, or any running Linux system's local hard drive.
The si_mkautoinstalldisk and si_mkautoinstallcd commands use the syslinux(2) utility to create disks 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 standard autoinstall kernel contains all the necessary drivers for the majority of systems. Custom kernels can be generated using UYOK feature to meet special disk and network driver requirements.
To use UYOK and generate kernel+initrd.img goes to your golden client and run the following command:
# si_prepareclient --server servername --no-rsyncd --my-modulesThe initrd.img will be generated on the fly from the initrd_template package (eg. systemimager-i386initrd_template). If you specify --no-rsyncd argument, rsyncd will be not restarted. With --my-modules you can save a lot of space in the UYOK initrd, because only the the modules that are currently loaded in your golden client will be included. Without --my-modules all the available modules will be added into the initrd allowing your UYOK kernel+initrd.img to be used also with heterogeneous clients. If all goes well you'll find the UYOK kernel+initrd.img in /etc/systemimager/boot/ in your golden client. When you run si_getimage from your image server (in this case do not specify --no-rsyncd) the UYOK kernel and initrd.img will be transferred to /usr/share/systemimager/boot/<arch>/<name_of_your_image> in your image server. In general, if you have an heterogeneous environment (clients with different hardware and components) it's better to use the standard BOEL kernel+initrd, because the standard kernel is strongly optimized to obtain better performances. In the other cases, in particular if you have 3rd-party or custom kernel modules it's strongly recommended to use UYOK.
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), installation parameters (passed by the kernel boot options, see http://wiki.systemimager.org/index.php/Installation_Parameters for a complete and up to date list of installation parameters), 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.
If you want to update an image on your image server, you can use one of the two following methods:
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, aptitude or RPM and yum for example.
Run the si_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 (suggested) or leave it alone. The advantages of running the si_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 si_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 si_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 a si_updateclient back to the last known working image.
![]() | In any case it is always suggested to stop the production in the machines before running the update via si_updateclient, since some files used by the running applications could be potentially updated or removed while the applications are using them. |
You can also use the si_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 in this way the image needs to be re-deployed.
si_updateclient then modifies the
boot-loader configuration 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 re-deploy any running Linux
machine without feeding the machine any external CD or USB
disk and without having to reconfigure the BIOS to boot off
the network, which can be quite problematic with some BIOSes.