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