path: root/README

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 <tree> <host>

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 <steeltoe>.

  Global Configuration
  
    The global configuration is contained in a <config> element which
    should be a child of the <steeltoe> 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."

    <tftpserver>

    This is the hostname of the TFTP server.

    <tftproot>

    This is the directory where all Steel Toe generated config files
    will go so hosts can access them through TFTP.

    <yabootetc>

    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.

    <tftpbase>

    This is the base directory that hosts will use to access files
    through the TFTP server.

    <kickstartbase>

    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 <tftpbase>, but using a method allowed in the ks=
    kernel argument.

    <remoteshell>

    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.

    <remotecopy>

    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.

    <treeserver>

    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.

    <bootloader>

    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:
      
      <bootloader>
        <pxelinux.0>/tftpboot/pxelinux/pxelinux.0</pxelinux.0>
        <elilo.efi>/tftpboot/efi/elilo.efi</elilo.efi>
      </bootloader>

  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 <path> 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.

      <tree name="RHEL4-U4">
        <path>/dist/released/RHEL-4/U4/AS/i386/tree</path>
        <meta>
          <family>RHELU4</family><variant>AS</variant><arch>i386</arch><kernel>2.6.9-42.EL</kernel>
        </meta>
      </tree>

  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.

      <host name="dash-02">
        <macaddr>00:12:3F:2A:AF:96</macaddr>
        <fqdn>dash-02.lab.example.com</fqdn>
        <arch>x86_64</arch>
        <bootloader>pxelinux.0</bootloader>
        <kickstart>
          <ksparams>nostorage</ksparams>
          <ksdevice>eth0</ksdevice>
          
          <device type="scsi">ata_piix</device>
          <device type="scsi">qla2xxx</device>
          <rootdisk>sda</rootdisk>
        </kickstart>
      </host>

    name="foo"

    This is the short name for the host.  It will be used to select the
    host for installation.

    <macaddr>

    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.

    <fqdn>

    This is the Fully Qualified Domain Name of the host.

    <arch>

    This is the architecture of the host.  This is used to match against
    the meta/arch element of the trees.

    <bootloader>

    The bootloader used to network boot the host.  This should have a
    corresponding element in /steeltoe/config/bootloader.

    <kickstart>

    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 <kickstart> section are several elements that are used to
    modify how the kickstart file is generated and what kernel arguments
    are used.

      <ksparams>
      
      The kickstart parameters to pass to the kernel via the boot
      loader.

      <ksdevice>

      The ethernet device to use to fetch the kickstart file.

      <device type="scsi">

      The element corresponds directly to the device kickstart option.
      It allows you to specify the order in which scsi drivers are
      loaded.

      <rootdisk>

      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] <host|tree>

  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 <tree> 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