Steel Toe - Taking the pain out of kickstart QUICKSTART 1. Install steeltoe rpm or "make install" 2. Modify /etc/steeltoe/steeltoe.xml for your environment 3. steeltoe gendhcpd -o /etc/dhcpd.steeltoe.conf 4. Modify /etc/dhcpd.conf to include /etc/dhcpd.steeltoe.conf 5. Configure hosts to boot from hard disk before ethernet 6. steeltoe install What does Steel Toe do? Steel Toe makes it easier to do kickstart installs on lots of hosts. It generates the config files needed to PXE install systems using kickstart. What does Steel Toe not do? Steel Toe does not provide a way to retrieve the images that Steel Toe installs. Mirroring distribution trees is a separate step that Steel Toe does not try to solve. How does Steel Toe do it all? Steel Toe makes extensive use of XML and related technologies. All data is stored in one flat XML file that can be spread out into multiple files using XInclude. Data is pulled from the file using XPath expression. Config files are generated using XSLT and XPath. Everything is tied together with a bash script. Steel Toe uses a unique TFTP directory organization method to keep things simple. Each host has its own directory under the TFTP root directory to hold its bootloader, bootloader config, kickstart config, kernel, and initial ramdisk. Steel Toe works on the principle that systems should not have to check in with Steel Toe when they are done an install. The systems should be configured to boot from the hard disk _before_ the network. This means that when a system successfully installs it does not have to check in with Steel Toe to disable PXE booting. It does mean that if an install fails, manual intervention may be required to get the system to retry the install. Steel Toe was not meant to be a finished solution. It is supposed to be a starting point for automating kickstart installs. The config files and templates are meant to be customized for each site. That is why they are installed in /etc/steeltoe rather than /usr/share/steeltoe. Steel Toe Configuration - /etc/steeltoe/steeltoe.xml Steel Toe uses one XML document for all configuration and data. This includes all trees that can be installed and all hosts that can be installed to. The document's root element should be . Global Configuration The global configuration is contained in a element which should be a child of the element. The following tags are currently used in Steel Toe. You can define additional tags as needed to hold your configuration data. To access these tags in a XML stylesheet use an XPath expression like "/steeltoe/config/foo." This is the hostname of the TFTP server. This is the directory where all Steel Toe generated config files will go so hosts can access them through TFTP. Yaboot insists that config files be put in /etc on the TFTP server. Set this value so Steel Toe can find this directory and place symlinks from here to the host's yaboot.conf in its directory. This is the base directory that hosts will use to access files through the TFTP server. This is the base URL which hosts will use to find their kickstart file. Steel Toe saves the generated kickstart file to the TFTP directory for each host, so this URL should point to the same directory as , but using a method allowed in the ks= kernel argument. This is the remote shell command to use when Steel Toe wants to run commands on the host. This is used for configuring the boot loader or rebooting the host. This is the remote copy command to use when Steel Toe wants to copy files to the host. This is used for copying kernels and ramdisks to the host for auto-kickstart installing. This is the host name of the server that holds all trees. It is used to generate the HTTP, FTP, or NFS URLs needed to install the trees. This is a list of boot loaders and their full path. This is used by Steel Toe to link the bootloader for each host into its respective TFTP directory. Example: /tftpboot/pxelinux/pxelinux.0 /tftpboot/efi/elilo.efi Trees Trees are installable distribution trees. They correspond to the "os" directory in a Red Hat Enterprise Linux build. Each tree has a name, a path element, and a meta section. The current templates expect that should work for all access methods (local, NFS, HTTP, FTP, etc). The names do not have to be unique. meta/arch is used a lot to match hosts with the correct trees. Use one entry per path, so each arch and variant of a release will have its own entry. /dist/released/RHEL-4/U4/AS/i386/tree RHELU4ASi3862.6.9-42.EL Hosts Hosts are systems that can be installed with Steel Toe. Each host has a name, a set of options, and a set of kickstart options. 00:12:3F:2A:AF:96 dash-02.lab.example.com x86_64 pxelinux.0 nostorage eth0 ata_piix qla2xxx sda name="foo" This is the short name for the host. It will be used to select the host for installation. This is the MAC address of the ethernet card used for PXE booting. Steel Toe needs this to generate a dhcpd.conf snippet for the host. This is the Fully Qualified Domain Name of the host. This is the architecture of the host. This is used to match against the meta/arch element of the trees. The bootloader used to network boot the host. This should have a corresponding element in /steeltoe/config/bootloader. This section defines values used in the kickstart file. Kickstart sections can specify a family to match against. The select-ks.xsl file determines which kickstart section is used to generate the kickstart file. Inside the section are several elements that are used to modify how the kickstart file is generated and what kernel arguments are used. The kickstart parameters to pass to the kernel via the boot loader. The ethernet device to use to fetch the kickstart file. The element corresponds directly to the device kickstart option. It allows you to specify the order in which scsi drivers are loaded. The device to use as the root disk. Steel Toe Command Line - steeltoe Steel Toe is held together with a single bash script called "steeltoe." steeltoe provides subcommands which makes Steel Toe go. gendhcpd [ -o outputfile ] This command generates host declarations for all hosts defined in steeltoe.xml. This can be included directly into an ISC DHCPD config file. It does not generate subnet declarations for the hosts. Modify dhcpd.conf to alter the output of this command. install [-r][-m http|ftp|nfs] tree host [host ...] Install the specified tree on the listed hosts. This is the primary subcommand of steeltoe. It creates the TFTP directory for each host and populates it with the bits required to install the specified tree. The -r option tells Steel Toe to reboot the node. The -m option allows the user to specify what installation method to try. list [-v] This is a simple subcommand to list all of the trees or hosts in steeltoe.xml. It needs work. genks [ -o outputfile ] host tree This command generates a kickstart file for the specified host and tree. Host and tree should be in steeltoe.xml. This command is used internally by the install subcommand. Modify kickstart.xsl to alter the output of this command. genpxe [ -o outputfile ] host tree This command generates a PXELINUX config to install the specified tree on the specified host. This command is used internally by the install subcommand. Modify pxeconf.xsl to alter the output of this command. genelilo [ -o outputfile ] host tree This command generates a ELILO config to install the specified tree on the specified host. This command is used internally by the install subcommand. Modify eliloconf.xsl to alter the output of this command. Steel Toe Helper Tools Steel Toe relies on two commands to help with processing XML files. These commands are part of the xpe package. gxpp - Global XPath Print This tool makes it trivial to extract information from an XML file. It is used to extract configuration information in steeltoe.sh and is useful for testing XPath expressions before they are added to .xsl files. See built in help for usage. gxpm - Global XPath Merge This tool makes it trivial to add or remove sections of XML documents. It takes an XML document from standard input and attaches it to the specified document in the location specified. This makes it easy for a tree mirroring script to generate the section and add it to steeltoe.xml. Steel Toe Template files Steel Toe depends on XSL Transformations to function. These .xsl files are meant to be customized to work for your environment. Here is a guide to the .xsl files included in Steel Toe. dhcpd.xsl This is used by the gendhcpd subcommand to create a dhcpd.conf snippet. It uses the tftpbase and tftpserver global config options and the name, macaddr, and bootloader host config options. select-ks.xsl This file is used by other templates to select the appropriate kickstart section from the host configuration. It expects the XSLT variables $host and $dist to be set. It in turn defines a $ks variable that references the correct kickstart section. eliloconf.xsl This is used by the genelilo subcommand to create a elilo.conf for systems that use ELILO to boot. It makes use of two parameters which should be passed on the command line, hostname and treename. It uses the kickstartbase global config option. pxeconf.xsl This is used by the genpxe subcommand to create a PXELINUX config file. It makes use of two parameters which should be passed on the command line, hostname and treename. It uses the kickstartbase global config option. yaboot.xsl This is used by the genyaboot subcommand to create a yaboot config file. autoks-args.xsl This is used to generate the kickstart arguments used during auto- kickstart installs. It takes advantage of select-ks.xsl to get the parameters right for the selected tree. kickstart.xsl This is the template for making kickstart files. This will probably be the file you customize the most. list.xsl This file is used to generate the list subcommand's output. Look away before you go blind. Configuring hosts for use with Steel Toe Steel Toe expects hosts to be configured in a certain way. Here are settings to chanage on each host before using Steel Toe. All Hosts Steel Toe expects all hosts to boot from the hard disk before booting from the network. The theory is that we only want to boot over the network when we need to reinstall the host. Otherwise the host should happily boot from the local hard disk and continue running the installed environment. x86 and x86-64 PXE Bootable Hosts In the BIOS settings, set the hard disk to boot before the network interfaces. ia64 Hosts Network booting is handled through EFI on ia64 systems. Create an EFI boot entry with the label "Steeltoe" which boots from the network. IBM pSeries hosts In the SMS menus, configure the system to boot from the hard disk, then the network. Steel Toe requires yaboot 1.3.15 or later which includes the netboot fixes. This allows Steel Toe to use yaboot config files instead of the "boot-file" nvram variable to set the kernel parameters. You should clear the boot-file variable. nvsetenv boot-file "" How to set up steeltoe 1. Install the steeltoe package software requirements isc dhcpd integrating with isc dhcpd BIOS settings to use on nodes HDD before ethernet Config files and stylesheets are meant to be customized Getting boot loaders (pxelinux.0 from syslinux, elilo.efi) Recommended Reading XML Path Language (XPath) - http://www.w3.org/TR/xpath XSL Transformations (XSLT) - http://www.w3.org/TR/xslt