23.40. sledgehammer-builder - Sledgehammer Builder

The following documentation is for Sledgehammer Builder (sledgehammer-builder) content package at version v4.6.0-beta01.97+g1e33864277dc9bbb839f71f1eff994a0c4f05c23.

23.40.1. Object Specific Documentation

23.40.1.1. params

The content package provides the following params.

23.40.1.1.1. sledgehammer/extra-packages

If you need to add extra packages to Sledgeahmmer that are available from the usual install repos and/or EPEL, you can do so via this parameter. You need to take care that the settings for the sledgehammer/unwanted-packages leave enough of these dependencies alone to allow for proper package operation.

23.40.1.1.2. sledgehammer/mellanox-driver-package

THis param points at the Mellanox EN source tarball that should be used to install current Mellanox Ehternet drivers from. Please note that this task only installs the basic Ethernet driver packages, it does not attempt to install the drivers that enable Infiniband or RDMA.

23.40.1.1.3. sledgehammer/customize-tasks

If you want to build a customized Sledgehammer, the supported way to do it is to create additional tasks to perform whatever other customization steps you want to perform, and then add them to this list. They will be performed after the built-in extra package installation, and before discarding unneeded packages and conversion to a Sledgeahmmer image.

Any extra customization tasks should make sure that no extra bits wind up in the final Sledghammer image. THis includes removing any unneedeed documentation, source code, or additional packages and files that are not needed to support proper operation of Sledgehammer.

23.40.1.1.4. sledgehammer/disable-services

CentOS has serveral services enabled by default that we don’t need in Sledgeahmmer. This param controls the ones we will disable.

23.40.1.1.5. sledgehammer/enable-services

Sledgehammer needs several different services enabled in order to operate properly.

23.40.1.1.6. sledgehammer/exablaze-driver-repo

This param points at the Exablaze RPM repo that should be used to install current Exablaze drivers from.

23.40.1.1.7. sledgehammer/extra-ifs

Extra interfaces to configure during sledgehammer builds. This is only required if you are building a Sledgehammer instance on a VM with nonstandard networking, and it does not have anything to do with how Sledgehammer behaves at runtime.

23.40.1.1.8. sledgehammer/solarflare-driver-package

Tis param points at the Solarflare source tarball that should be used to install current Solarflare Ethernet drivers from.

23.40.1.1.9. sledgehammer/unwanted-kernel-modules

The default kernel in Sledgeahmmer includes a lot of additional modules that are neither required nor wanted ion a datacenter provisioning enviromnent. This parameter controls which drivers we will get rid of.

23.40.1.1.10. sledgehammer/unwanted-packages

On a freshly installed Centos syhstem, there are generally several packages that are installed by default but that are not required for Sledgehammer ot do its job. This param contains a list of such packages.

23.40.1.2. profiles

The content package provides the following profiles.

23.40.1.2.1. sledgehammer-full-drivers

This profile is used to define all the known extra drivers to build with.

  • Exablaze
  • Solarflare
  • Mellanox

23.40.1.3. stages

The content package provides the following stages.

23.40.1.3.1. sledgehammer-build

This stage is responsible for building a Sledgehammer image. To use it, set a machine to this Stage and reboot it. dr-provision will then install a trimmed-down version of CentOS on the machine, strip out non -essential bits, then package the remainder up as a Sledgehammer image that everyone will be able to use.

23.40.1.4. tasks

The content package provides the following tasks.

23.40.1.4.1. sledgehammer-prepare-for-image-creation

This task prepares the installed OS before we capture it as a bootable Sledgehammer image. It is responsible for removing any unneeded packages, files, and other data that is not required for Sledgehammer to perform its tasks. It also arranges for all the services to be set up properly.

23.40.1.4.2. sledgehammer-create-image

Now that all the bits are staged, create a tarball that contains everything properly built and signed. When finished, upload the ISO and the profile with bootenv overrides to dr-provision

23.40.1.4.3. sledgehammer-create-stage1

We need the stage1 image to be as small as we can get it, and still be possible to load the stage2 image. That means that the stage1 image has little more than busybox, a few required modules, and a swuashfs that contains only modules that may be required for fetching the stage2 image.

23.40.1.4.4. sledgehammer-create-stage2

This task creates the live squashfs image for Sledgehammer. It is what will wind up ruinning from memory.

23.40.1.4.5. sledgehammer-customize

This task allows you to customize Sledgehammer by programatically inserting extra tasks via the ‘sledgehammer/customize-tasks’ param.

23.40.1.4.6. sledgehammer-exablaze-current-drivers

This task installs up-to-date Exablaze drivers from the source repo defined in the sledgehammer/exablaze-driver-repo param.

This task is not included in Sledgehammer by default – to include it, add it to sledgehammer/customize-tasks and rebuild Sledgehammer.

Please note that a Sledgeahmmer image built using this task will not be compatible with UEFI Secure Boot, as the resulting kernel modules will not be signed by the CentOS signing authority.

THIS DOES NOT WORK BECAUSE DKMS IS NOT FUNCTIONAL IN SLEDGEHAMMER. NEED SOURCE STYLE FOR THIS.

23.40.1.4.7. sledgehammer-mellanox-current-drivers

This task installs up-to-date Mellanox drivers from the sourec package defined in the sledgehammer/mellanox-driver-package param.

This task is not included in Sledgehammer by default – to include it, add it to sledgehammer/customize-tasks and rebuild Sledgehammer.

Please note that a Sledgeahmmer image built using this task will not be compatible with UEFI Secure Boot, as the resulting kernel modules will not be signed by the CentOS signing authority.

Please also note that this task is designed to only install the Ethernet drivers, not the RDMA or Infiniband driver set. If you need those, you may need to spin your own custom version of Sledgehammer using a new task.

23.40.1.4.8. sledgehammer-place-start-up

This task places a few static assets that are needed for the Sledgehammer start-up process. It handles the following assets:

  • sledgehammer-start-up.sh

    This script is run as a systemd service once Sledgehammer has started. It is responsible for making sure the image was booted with the necessary kernel parameters and then downloading and executing the machine-independent startup script from dr-provision.

  • sledgehammer-motd

    This sets the default login banner.

  • sledgehammer-ssh-config

    This sets the default sshd configuration. We default to allowing root logins only via key based authentication and allowing sftp.

  • sledgehammer-service

    This is the systemd unit file that is responsible for starting sledgehammer-start-up.sh when Sledgehammer boots. It waits until the network has been configured and is online before starting.

23.40.1.4.9. sledgehammer-solarflare-current-drivers

This task installs up-to-date Solarflare drivers from the source package defined in the sledgehammer/solarflare-driver-package param.

This task is not included in Sledgehammer by default – to include it, add it to sledgehammer/customize-tasks and rebuild Sledgehammer.

Please note that a Sledgeahmmer image built using this task will not be compatible with UEFI Secure Boot, as the resulting kernel modules will not be signed by the CentOS signing authority.

23.40.1.4.10. sledgehammer-place-stage1-assets

This task places the stage1 assets where they must be present for the stage1 initramfs to be built. The assets placed are:

  • sledgehammer-stage1-init

    This script is run when the Sledgehammer kernel and initrd have been loaded. It is responsible for transferring the stage2 image from dr-provision and transferring control to it.

  • sledgehammer-stage1-udhcpc-config

    This script is invoked by udhcpc whenever it gets or releases a lease. It is responsible for actually configuring the network interface.

  • squashfs-excludes

    this file defines what will be excluded from the stage2 squashfs image.

23.40.1.5. workflows

The content package provides the following workflows.

23.40.1.5.1. sledgehammer-build

Sledghammer is the OS image Digital Rebar uses for discovery, inventory, and hardwre configuration. Sledgehammer is based on the current centos-8 boot environment, and requires that bootenv to be present and functional to operate.

You can customize the Sledgehammer build process by adding updated versions of the follwing Params to the machine you will run this workflow on:

  • sledgehammer/extra-packages
  • sledgehammer/unwanted-packages
  • sledgehammer/unwanted-kernel-modules
  • sledgehammer/disable-services
  • sledgehammer/enable-services
  • sledgehammer/customize-tasks

Please refer to the documentation for each of those parameters for information on what they are and what they allow you to change.

Once this workflow has finished building a new image, it will upload it to dr-provision along with a profile that will allow you to start using the new image immediately, and then power off the machine that was used to build the image.

23.40.1.6. bootenvs

The content package provides the following bootenvs.

23.40.1.6.1. sledgehammer-install

This BootEnv is used as the basis for building Sledgehammer, our in-memory discovery and inventory management environment. This bootenv is reponsible for performing a basic CentOS install on a sacrificial machine. The tasks that run after the install has finished are responsible for stripping out everything we do not need for Sledgehammer to boot as an in-memory OS image and packaging everything up for distribution.