LCFG installroot documentation

Overview

The constituent parts are :-

• initramfs image that the kernel loads up after initialisation
• installroot, to which the initramfs passes control once it has loaded appropriate kernel modules and configured the network
• the LCFG install component which calls various LCFG components to configure aspects of the target system

The LCFG initramfs image, created by the lcfg-mkbootpkg script, is an initrd image which the kernel unpacks and transfers control to after initial system initialisation. The initramfs consists of the kernel modules for the running kernel, a busybox binary, various symlinks to the busybox binary to provide utilities such as ln, mv, dhcp etc, and a bash script called init which is invoked by the kernel. This bash script, init, identifies and loads the appropriate kernel modules for the system's hardware, issues a DHCP request and configures the primary network interface, and either mounts the installroot off NFS (the NFS path having been provided via DHCP) or off the CDROM. Once the installroot is mounted, init overlays the installroot over the existing root filesystem and then transfers control to the /sbin/init binary in the installroot.

The initramfs image is created by the lcfg-mkbootpkg script which, along with the init script, is shipped in the lcfg-mkinitramfs RPM. lcfg-mkbootpkg takes, as input, the LCFG profile installroot-initramfs-{platform} and produces two RPMs called kernel-install-{platform}-{kernelversion} (for installing into the installroot) and kernel- install-{platform}-pxe-{kernelversion} (for installing on the PXE server(s)).

The installroot is basically a lightweight linux install, with just the minimum packages necessary to download an LCFG profile and call those LCFG components required to build a self-bootable target linux install. As described above, the initramfs calls /sbin/init - this starts the upstart boot system. Only one upstart event is provided - /etc/event.d/lcfg. This event calls /usr/sbin/lcfginstall which downloads the target machine's LCFG profile and then calls the LCFG install component. As well as being used to install new systems, it can also be used in rescue mode to debug already installed systems.

The installroot is built by the /usr/sbin/buildinstallroot script (shipped by the lcfg-buildinstallroot RPM). It takes, as input, the LCFG profile installroot-{platform}-stable and produces an ISO image which is then burnt to CD/DVD or installed, unpacked, on an NFS server for PXE booting. The LCFG profile simply provides the list of packages required to build the installroot image. The RPM lcfg-installroot contains the upstart LCFG event and the /usr/sbin/lcfginstall script.

Options

The LCFG install component (shipped by the lcfg-install RPM) calls other LCFG components to install the target system. Its behaviour is driven by the install resources :-

The initramfs accepts a number of options which can be passed via the kernel command line.

root=<root>

this option can be used to specify the device location of the installroot. The default value is 'auto', which directs the script to search for an installroot.

lcfg.extramods=<mod1,mod2,...>

this can be used to forcibly load extra kernel modules that weren't auto-detected

lcfg.ethdevice=<device>

this can be used to force the script to use the specified ether device. If this option is not provided, the initramfs will attempt to use each ether device in turn

lcfg.url=<url>

this can be used to specify the url for the machine's LCFG profile (otherwise the url will be requested from the DHCP server)

lcfg.debugstop=<tag>

this can be used to pause the install process at various points. See the source code for details

lcfg.prompt=none

this will disable the normal prompt to install/debug/reboot - useful for installing large numbers of machines (eg lab, beowulf)

Progress and error messages are logged to /var/log/messages.

HOWTO upgrade installroot

Upgrade initramfs (usually to update kernel)

Note: you can skip this step if you're just updating packages, other than the kernel, in the installroot.

• Update the relevant profile.packages resource in the source profile used to build the initramfs. (eg rfe lcfg/installroot-initramfs-f12)
• On the target platform, build the initramfs using /usr/sbin/lcfg-mkbootpkg. You will need to specify --revision if you're creating a second initramfs for the same kernel - unlikely unless you're making modifications to the initramfs code). You also need run as root.
• /usr/sbin/lcfg-mkbootpkg will display the location of the resulting initramfs RPMs (named kernel-install-{bla}-{bla}) Submit both RPMs to the package repository (LCFG bucket)
• In the relevant installroot package list (eg lcfg_f12_lcfg_installroot.rpms) update the kernel and kernel-install RPM versions to match the new kernel.

Rebuild the installroot (for both CDs and PXE)

Note: you can jump in here if you're just updating packages in the installroot.

• Build the installroot - /usr/sbin/buildinstallroot -f --verbose -o /r.iso If you're not waiting for the package changes to ship in the next stable release, you will need to specify the develop release copy of the installroot profile using, eg, --profile installroot-f12-develop
• Copy the resulting /r.iso image to the MPU afs hierarchy (/afs/inf.ed.ac.uk/group/mp-unit/cdroms)

Update the installroot on the PXE server

The standard ISOs which are built as part of the weekly stable release are transferred to the PXE NFS root server over night. Note however that the standard symlinks are NOT updated automatically. It is essential that the kernel in the install root and the PXE installer MUST match to ensure this is always the case the links must be updated manually. Here's how to update the symlinks to your preferred LCFG release (using 2012031201a as an example):

nsu
cd /export/linux/installroot/
for i in sl5 sl5_64 sl6 sl6_64 ; do rm -f $i; ln -s "$i-2012031201a" $i; done

If you need to do it manually here is the process:

• copy the /r.iso image to the PXE boot server (currently hare)
• on the PXE boot server, mount the iso (loopback) (eg mount -o loop /var/tmp/r.iso /mnt)
• rsync the loopback mounted installroot to a date stamped directory in /export/linux/installroot
• alter the appropriate symlink to point to this new directory

Historical documentation

• Documentation on the previous system (still current for SL5 as of Sept 10)
• Roger has written some very detailed descriptions of how the install process works (somewhat outdated).

-- AlastairScobie - 29 Sep 2010