FAQ (Frequently Asked Questions)

Q: Where are the images stored?
Q: How do I make an autoinstall CD?
Q: How do I make an autoinstall USB disk?
Q: When I pass options from dhcp (option-100, etc), the client appears to get and try to use a hexadecimal number instead. How do I make it pass a dotted-quad IP address instead?
Q: I've got si_netbootmond running, but it isn't working. Why?
Q: How do I configure my server to net boot ia64 clients?
Q: How do I set up my autoinstall clients so that the console is available via the serial port?
Q: Does the DHCP server have to be on the image server?
Q: With which distributions does SystemImager work?
Q: How do I add a driver for a special card to the autoinstall kernel?
Q: Do I have to do anything to prepare a client from which I will get an image?
Q: Can I use the autoinstalldisk or autoinstallcd on more than one machine?
Q: How do I push an image to a client?
Q: How do I pull an image to a client?
Q: How does an autoinstall client know which image to install?
Q: What if I want to assign static IPs to my clients?
Q: I want to use DHCP to assign static IPs to my clients, but I don't want to have to enter my 1000 mac addresses manually. What can I do?
Q: What kind of performance can I expect?
Q: How do I update an image on the image server?
Q: How do I update a client to match an image?
Q: What is the updateclient.local.exclude file used for?
Q: How can I use SystemImager to update a small set of files? For instance, I apply a security patch and I want all boxes to reflect that change.
Q: Is there a log file where autoinstall client status is kept?
Q: What other software is SystemImager based on?
Q: What's an override directory?
Q: How do I expand a filesystem?
Q: How do I change the size of a partition?
Q: How do I change the filesystem(s) that my target machine(s) will use?
Q: How do I change the disk type(s) that my target machine(s) will use?
Q: Can I use a single image across machines with differing disk or partition configurations?

Q: Where are the images stored?

A: The images are stored in /var/lib/systemimager/images.

Note

NOTE: If you are short on disk space in this location, move the directory to another location:

mv /var/lib/systemimager/images /home/systemimager_images

Then create a soft link to the new directory.

ln -s /home/systemimager_images /var/lib/systemimager/images

Q: How do I make an autoinstall CD?

A: Run the si_mkautoinstallcd command on the image server.

Q: How do I make an autoinstall USB disk?

A: Run the si_mkautoinstalldisk command on the image server.

Q: When I pass options from dhcp (option-100, etc), the client appears to get and try to use a hexadecimal number instead. How do I make it pass a dotted-quad IP address instead?

A: The hexadecimal address is actually the hexadecimal representation of your IP address (you can verify this with the gethostip command). This is normally a quoting issue. Add quotes around the IP address in the configuration file.

Q: I've got si_netbootmond running, but it isn't working. Why?

A: In order for si_netbootmond to do it's thang, you must have the rsync daemon running: "/etc/init.d/systemimager-server-rsyncd start".

Q: How do I configure my server to net boot ia64 clients?

A:

  • Install tftp (tftp-hpa >= 0.28 is recommended) on your boot server.

  • Configure inetd or xinetd to enable tftp.

    • To configure inetd, find the tftp entry in /etc/inetd.conf and change it to:

      tftp dgram udp wait root /usr/sbin/in.tftpd -v -v -v -s /var/lib/tftpboot

      Change "/usr/sbin/in.tftpd" to be the full path to your tftp server, if you installed it in a different directory.

      The -v's aren't strictly required but make the tftp server more verbose, which makes it easier to diagnose problems.

      Finally, send a HUP signal to inetd (this causes it to reload its configuration file). # killall -HUP inetd

    • To configure xinetd, change:

         service tftp
      {
              socket_type             = dgram
              protocol                = udp
              wait                    = yes
              user                    = root
              server                  = /usr/sbin/in.tftpd
              server_args             = -s /home/tftp
              disable                 = no
      }
               

      to:

      service tftp
      {
              socket_type             = dgram
              protocol                = udp
              wait                    = yes
              user                    = root
              server                  = /usr/sbin/in.tftpd
              server_args             = -s /var/lib/tftpboot -r blksize
              disable                 = no
      }
               

      Finally, send a USR2 signal to xinetd (this causes it to reload its configuration file).

  • Configure your DHCP server so that it provides boot information to the client. Be careful when setting up your DHCP server - if it is set to hand out dynamic addresses and is located on a public subnet, it may give bogus information to other machines on the network, possibly destroying data on those machines. It is recommended that you use a private subnet for doing network installs. If possible, you should also configure your DHCP server to only answer requests from known hosts based on the MAC address.

    Add an entry for the boot client in /etc/dhcpd.conf

    host mcmuffin {
            hardware ethernet 00:30:6e:1e:0e:83;
            fixed-address 10.0.0.21;
            filename "elilo.efi";
    }
           
  • Copy elilo.efi from an IA-64 machine to your tftpboot directory and make them world readable. This file is usually found in a subdirectory under /boot/efi or in /usr/lib/elilo. It can also be found in the elilo package in IA64 distributions.

    You also must create an elilo.conf file in your tftpboot directory. A sample one is provided in /usr/share/doc/systemimager-doc/examples, or you can type in the one below.

  • Edit /var/lib/tftpboot/elilo.conf:

    #
    # Sample elilo.conf for netbooting ia64 systemimager clients
    #
    # Inside your tftp directory you may also want to do this:
    #
    #   mkdir -p ia64/standard
    #   cp /usr/share/systemimager/boot/ia64/standard/* ia64/standard/
    #
    default=systemimager
     
    image=ia64/standard/kernel
        label=systemimager
        initrd=ia64/standard/initrd.img
        root=/dev/ram
        append="vga=extended ramdisk_blocksize=4096 console=tty0"
        #
        # Uncomment APPEND line below, and comment out APPEND line above, to use
        # both monitor (tty0) and first serial port (ttyS0) as console at the
        # same time.
        #
        # NOTE: Be sure your serial port speed is appropriate (57600, 9600, etc.)
        #
        #append="vga=extended ramdisk_blocksize=4096 console=tty0 console=ttyS0,9600n8"
        read-only
           

    If ABCDEFGH is the client's IP address in hex, elilo.efi will use the first one of the following files that it finds as its configuration file:

    • ABCDEFGH.conf

    • ABCDEFG.conf

    • ABCDEF.conf

    • ...

    • A.conf

    • elilo.conf

    You can use the ipcalc utility, which is available in the syslinux package, to calculate the hex representation of an IP address in dotted quad form.

  • Configure the client to support TFTP booting.

    1. Boot to EFI

    2. Enter the Boot option maintenance menu

    3. Add a boot option

    4. Press return on the line saying "Load file [Acpi/.../Mac()]"

    5. Call the entry Netboot or something similar

    6. Save and exit, Netboot is now available in the boot menu.

  • Q: How do I set up my autoinstall clients so that the console is available via the serial port?

    A: si_mkautoinstallcd and si_mkautoinstalldisk support an -append option, allowing you to specify additional options for the autoinstall kernel, including serial console options. For example: si_mkautoinstallcd -out-file autoinstall.iso -append "console=ttyS0"

    Q: Does the DHCP server have to be on the image server?

    A: No. If you are using DHCP, you can use "option-140" and set its value to the IP address of the image server. If you use si_mkdhcpstatic to configure your dhcpd.conf file, it will ask you for the IP address of your image server and add the appropriate entry for you.

    Because this is not the official use for option-140, work is being done to either get an official number assigned or use a number from the private number range.

    Q: With which distributions does SystemImager work?

    A: SystemImager is designed to work with _any_ distribution. Post imaging configuration is handled by System Configurator, which uses a "footprinting" technique to identify the style of system configuration files used, and to configure networking, boot, and similar information accordingly. If you find a distribution that SystemImager does not work with, please file a bug report.

    Q: How do I add a driver for a special card to the autoinstall kernel?

    A: If you have hardware that requires a driver that was not included in the standard flavor boot package, you can build a custom boot package with UYOK feature. See http://wiki.systemimager.org/index.php/UYOK ).

    Q: Do I have to do anything to prepare a client from which I will get an image?

    A: Yes, you should install the systemimager-client package. If this package is already installed, simply run the si_prepareclient command prior to running si_getimage from the image server.

    You should also add any software, configure any files, and do any tweaking to customize the system to your specifications.

    Q: Can I use the autoinstalldisk or autoinstallcd on more than one machine?

    A: Yes. The autoinstall media is generic and can be on any machine you want to autoinstall.

    Q: How do I push an image to a client?

    A: Starting with version 3.8.0, you can use the si_pushinstall command, which opens an SSH tunnel from the image server to the clients. Then each client downloads the image using the SSH tunnel opened by the image server. This is the most secure approach to install clients over insecure networks.

    Q: How do I pull an image to a client?

    A: If you ran si_mkdhcpserver to configure your dhcp information, and if you answered all the questions you were asked when you did ran si_getimage, including the hostnames and IP addresses, then all you have to do is boot your client with any one of the following three forms of autoinstall media:

    1. autoinstallcd - it takes slightly little time to boot and is more durable, but you have to have a CD burner and clients that can read CD-R's)

    2. autoinstalldisk - it takes slightly little time to boot, but requires that the BIOS of your clients support boot over USB devices.

    3. network boot - boot time is dramatically, but this method requires PXE capable network cards in the clients and additional server-side configuration.

    See the entries for si_mkautoinstallcd and si_mkautoinstalldisk in the command reference chapter in this manual for more information.

    Q: How does an autoinstall client know which image to install?

    A: In order to better understand the answer, begin by reading the steps the autoinstall client goes through:

    1. Boots off the autoinstallmedia

    2. Gets an IP address from DHCP

    3. Determines the IP address of the image server via DHCP

    4. Requests a hosts file from the image server

    5. Finds its hostname in the hosts file based on its IP address

    6. Requests a script from the image server based on its hostname (for example: www237.sh)

    7. Executes this script.

    The script in question is typically a soft link pointing at the $image.master script that was dynamically created when you ran si_getimage. This script explicitly states which image to pull from the image server. Open it and take a look.

    These scripts and the $image.master script can be found in /var/lib/systemimager/scripts.

    Q: What if I want to assign static IPs to my clients?

    A: You can. si_getimage will ask you if you want to assign static IPs.

    Q: I want to use DHCP to assign static IPs to my clients, but I don't want to have to enter my 1000 mac addresses manually. What can I do?

    A: SystemImager comes with the si_mkdhcpstatic utility. As you boot your client systems, the DHCP server will assign addresses sequentially. By initially booting your systems in the order you want them to receive their IP addresses, you can ensure that they get the IP address you want them to have.

    After booting your systems, run si_mkdhcpstatic. It will re-write your /etc/dhcpd.conf file, associating each client's MAC address with its host name. You should then restart your dhcpd daemon. Subsequently, each time your clients request an IP address via DHCP, they will always be assigned their appropriate static IP address.

    Note: The client's hostname is used, instead of an explicit IP address, so that you simply have to change the hosts file on the DHCP server (or DNS, NIS, etc.) to change the IP address that that client recieves.

    Note: Assigning static IP addresses by DHCP is the author's preferred method for administering IP on a large number of systems.

    Q: What kind of performance can I expect?

    A: Ole Holm Nielsen, Department of Physics, Technical University of Denmark reports:

    In our SystemImager installation, we can install 18 clients simultaneously with 1.8 GB images in 6 minutes. Please see The NIFLHEIM SystemImager Page. Our server has Gigabit network, 2 GB of RAM, dual Intel Xeon 2.4 GHz, whereas the clients have Intel P4 and 100 Mbit Ethernet.

    James Braid reports:

    From a Celeron 700/512Mb server over 100Mbit ethernet, we manage to do a ~1Gb image in about 7 - 10 min. The disks are 5x 120Gb Seagate Barracuda V in one LVM set (non striped), with a ReiserFS filesystem.

    Q: How do I update an image on the image server?

    A: There are two ways to update an image on the image server:

    1. Make the changes to one of your clients and run the si_getimage again.

      - You can specify the same image name, in which case the current image will be updated (only changes are pulled across).

      - Or you can specify a new image name and have a form of revision control. (This method is highly recommended)

      Note: Every time si_getimage is run, it recreates the $image.master script. If you have customized your $image.master script, be sure to save it before running si_getimage again.

    2. Modify the files directly. You can simply cd into the appropriate image directory and edit the files there, or (recommended) you can cd into the image directory and run 'chroot . sh'. This will change your working root directory to the root of the image you want to manipulate. You can then run rpm and other commands on the image and not have to worry about getting confused and damaging the image server. When you are done, simply type exit and you will be returned to your normal shell.

    Q: How do I update a client to match an image?

    A: Once you have updated an image on the image server, you can then update your clients to reflect it. (You do not need to do a complete re-autoinstall.) You will find the command, si_updateclient, on your clients, which takes as its parameters the name of the image server and the name of the image you want to update the client to. Run si_updateclient -help to get more information about this command.

    Use the revision control method recommended in the "How do I update an image on the image server?" FAQ to bring your production environment back to a known state after doing an si_updateclient to a test image (i.e. do an si_updateclient to the last working image).

    The file /etc/systemimager/updateclient.local.exclude on your clients is used to exclude files and directories from being updated by the si_updateclient command. You can modify it to suit your own environment.

    Q: What is the updateclient.local.exclude file used for?

    A: It is used by the si_updateclient command. See the "How do I update a client to match an image?," FAQ for more information.

    Q: How can I use SystemImager to update a small set of files? For instance, I apply a security patch and I want all boxes to reflect that change.

    A: Use the si_updateclient command on the client.

    1. Choose one of the following methods to update the image on the server:

      1. apply the patch to the image directly

      2. apply the patch to a client and then do another si_getimage specifying the same imagename (won't take long and will update the image)

      3. apply the patch to a client and then do another si_getimage specifying a different imagename. This is preferred as it allows for revision control.

    2. Run si_updateclient on the clients that you want to update. Execute si_updateclient -help to get the syntax.

    Q: Is there a log file where autoinstall client status is kept?

    A: Yes. SystemImager logs can be found on the image server in the directory /var/log/systemimager

    Q: What other software is SystemImager based on?

    A: SystemImager is mostly written in Perl, and makes use of the following software:

    • busybox

    • bc

    • devfsd

    • ISC dhcp

    • discover

    • dosfstools

    • e2fsprogs

    • jfsutils

    • xfsprogs

    • Linux kernel

    • parted

    • pxelinux

    • rsync

    • syslinux

    • raidtools

    • reiserfsprogs

    • systemconfigurator

    • uClibc

    Also be sure to take a look at System Installation Suite (SIS), which includes SystemInstaller, SystemImager, and System Configurator. SystemInstaller is a tool that allows you to install images directly to a SystemImager image server. System Configurator, which is also used by the standard SystemImager release, performs configuration of target machine uniquenesses such as IP addresses, network cards, and initial RAM disks needed to boot clients after installation.

    Q: What's an override directory?

    A: An override directory is a directory that gets copied over to your target machines after the main image is transferred. All contents in the override directory are copied over to the root of the target machine's new filesystem. All file attributes are replicated, including directories, permissions, and ownership. This allows you to "over-ride" files in the image. Override directories live in /var/lib/systemimager/overrides/.

    Simply edit the master autoinstall script and change the overrides variable to include the appropriate override directory. For example, you could change OVERRIDES="my_image" to OVERRIDES="my_image-ide".

    If using the same overrides on all of your machines, you don't have to change the autoinstall script. Simply put the files that you want to override in the overrides directory that has the same name as your image, and proceed.

    You can also use multiple override directories, which are used in the order that you specify them -- each directory overriding the previous directories. You can use this methodology in a highly complex environment where slight variations exist between several classes of machines but where they all start with the same base image. For example, OVERRIDES="my_image-ide web_app".

    Q: How do I expand a filesystem?

    A: See "How do I change the size of a partition?"

    Q: How do I change the size of a partition?

    A:

    1. Open your autoinstallscript.conf file in your favourite text editor.

      Note

      The default autoinstallscript.conf file created by si_prepareclient lives in the /etc/systemimager directory in your image.

    2. Find the <disk> section where dev is set to the disk that holds the partition you want to change.

    3. Find the <part> entry where num is the number of the partition in question.

    4. Change size to the new partition size, keeping in mind that if the size you specify is not sufficient to hold the files stored there, the autoinstall will fail.

      NOTE: Each <disk> section can use either MB (megabytes) or % (percentages) to specify partition sizes. See man autoinstallscript.conf for more information.

    5. Run si_mkautoinstallscript to create a new autoinstall script using the new parameters.

      NOTE: By default, si_mkautoinstallscript uses the autoinstallscript.conf file located in your image's ./etc/systemimager directory. See man si_mkautoinstallscript and man autoinstallscript.conf for more information.

    Q: How do I change the filesystem(s) that my target machine(s) will use?

    A:

    1. Make sure that the kernel in your image supports the filesystem(s) you want to use.

    2. Open your autoinstallscript.conf file in your favorite text editor.

      NOTE: The default autoinstallscript.conf file created by si_prepareclient lives in the ./etc/systemimager directory in your image.

    3. Find the <fsinfo> entry where mp (mount point) is set to the filesystem that you want to change.

    4. Change fs to the filesystem you want to use. See man autoinstallscript.conf for a list of supported filesystems.

      You must understand the capabilities of your chosen filesystem. Depending on which one you use, you may also need to change the options used to mount the filesystem, which are set by the options entry. If you choose unsupported options, your autoinstall may fail.

      In all known cases to date, it has not been necessary to change the fs entries in the <disk> section when changing filesystem types. The fs entries in the <disk> section don't actually determine the filesystem that will be created on those partitions, but the parted tool that SystemImager uses for creating disk partitions requires that argument.

    5. Run si_mkautoinstallscript to create a new autoinstall script using the new parameters. By default, si_mkautoinstallscript uses the autoinstallscript.conf file located in the ./etc/systemimager directory in your image. See man si_mkautoinstallscript and man autoinstallscript.conf for more information.

    Q: How do I change the disk type(s) that my target machine(s) will use?

    A:

    1. Make sure that the kernel in your image has drivers for the disk types you want to use.

    2. Run si_mkautoinstallscript --autodetect-disks ... to create a new autoinstall script that will be able to automatically detect disk types at run-time during the imaging of your clients.

    3. An alternative method is to manually modify autoinstallscript.conf and re-run si_mkautoinstallscript.

    Q: Can I use a single image across machines with differing disk or partition configurations?

    A: Yes. Be sure to use --autodetect-disks with si_getimage or si_mkautoinstallscript if you have different disk types in your clients and create a different autoinstallscript.conf and master script for each partitioning schema you want to use.

    See also

    Consult the troubleshooting guide on the SystemImager web site at http://wiki.systemimager.org/index.php/Troubleshooting and the online FAQ at http://wiki.systemimager.org/index.php/FAQ for details.