BootEnv¶

The bootenv object defines an environment to boot a machine. It has two main components: an OS information section, and a templates list. The OS information section defines what makes up the installation base for this bootenv. It defines the install ISO, a URL to get the ISO, and SHA256 checksum to validate the image. These are used to provide the basic install image, kernel, and base packages for the bootenv.

Field	Definition	Key
`Name`	The name of the boot environment. Each bootenv must have a unique name, and bootenvs that are responsible for booting into an environment that will install an OS on a machine must end in `-install`.
`OnlyUnknown`	A boolean value indicating that this boot environment is tailored for use by unknown machines. Most boot environments will not have this flag.
`Loaders`	A map of indicated PXE boot architecture to the bootloader that should be used for that architecture. Unlike the per-arch Loader field, this one is relative to the path the BootEnv is expanded to, and distinguishes between amd64 legacy boot and amd64 UEFI boot.
	Used when the PXE options indicate that the system is attempting to PXE boot into a UEFI environment on an amd64 compatible system.	`amd64-uefi`
	Used when the PXE options indicate that the system is attempting to PXE boot in an ARM64 based UEFI environment.	`arm64-uefi`
	Used when the PXE options indicate that the system is attempting to PXE boot into into a i386 compatible legacy BIOS environment.	`386-pcbios`
	The values for these keys are interpreted as if they were appended to the appropriate env arch-specific path.
`OS`	an embedded structure that contains some basic information on the OS that this BootEnv will boot into, if applicable. OS contains the following fields:
	The name of the OS this BootEnv will boot into or install. It must be in the format of `<distro>-<version>`. Examples: `centos-7`, `debian-8`, `windows-2012r2`, `ubuntu-16.04`	`Name`
	The family of the OS, if any.	`Family`
	The codename of the OS, if any. Generally only really used by Debian, Ubuntu, and realted Linux distributions.	`Codename`
	The version of the OS, if any.	`Version`
	As an install convienence, DRP contains built-in ISO expansion functionality that can be used to provide a local mirror for installing operating systems. This field indicates the name of an install archive (usually a .iso file) that should be expanded to provide a local install repo for an operating system.	`IsoFile`
	If present, the sha256sum that the ISO should have.	`IsoSha256`
	The URL that ISO can be downloaded from.	`IsoUrl`
`Kernel`	If present, a partial path to the kernel that should be used to boot a machine over the network. The kernel must be specified as a relative path with no leading `/` or `..` characters allowed. As an example, the `Kernel` parameter for the community provided `ubuntu-16.04-install` boot environment is `install/netboot/ubuntu-installer/amd64/linux`, the path to the kernel relative to the root of the Ubuntu install ISO.
`Initrds`	If present, a list of partial paths to initrds that should be loaded along with the kernel when booting a machine over the network. Initrd paths follow the same rules as kernel paths.
`BootParams`	If present, a string that will undergo template expansion as if it were a template, and passed as arguments to the kernel when it boots.
`RequiredParams`	A list of parameters that are required to be present (directly or indirectly) on a machine to use this bootenv. Only applicable to bootenvs that do not have the `OnlyUnknown flag` set. It is used to verify that a machine has all the parameters it needs to be able to boot using this bootenv.
`OptionalParams`	A list of parameters that the bootenv may use if present (directly or indirectly) on a machine.
`Templates`	A list of templates that will be expanded and made available via static HTTP and TFTP for this bootenv. All bootenvs should include entries in their Templates list for the `pxelinux`, `grub`, and `ipxe` bootloaders. If the OnlyUnknown flag is set, their Paths should expand to an appropriate location to be loaded as the fallback config file for each bootloader type, otherwise their Paths should expand to an approriate location to be used as a boot file for the loader based on the IP address of the machine. Good examples for each are the discovery and the sledgehammer bootenvs.

Note

The Name field must include the suffix -install for any bootenv that is expected to boot into an OS installer because it adds path indexing into an install subdirectory.

Bootenvs are typically supported file collections uploaded as an ISO. ISOs are typically, but not necessarily, .iso files. For example, the sledgehammer ISO is actually a .tar file. A single bootenv may also have multiple supporting ISOs based on architecture, or other factors.

When a matching ISO for a bootenv is uploaded and its checksums match, the ISO will be expanded (or exploded) into components. In addition, ISOs intended for network booting must contain network bootable pieces.

The other primary section is a set of templates that represent files in the file server's file space that can served via HTTP or TFTP. The templates can be included in the bootenv object or reference a template object. The templates are specified as a list of paths in the filesystem. Either the ID of a template object, or template content included inline must be present. The Path field of the template information can use the same template expansion that is used in the template.

Additionally, the bootenv defines required and optional parameters. The required parameters are validated for presence and correctness at render time, an error is generated otherwise. These parameters can be met by the parameters on the machine, the profiles in machine's profiles list, or from the global profile.

Bootenvs can be marked OnlyUnknown. This tells the rest of the system that this bootenv is not for specific machines. It is a general bootenv. For example, the discovery and ignore bootenvs are OnlyUnknown. The discovery bootenv is used to discover unknown machines and add them to DRP. The ignore bootenv is a special bootenv that tells machines to boot their local disk. These bootenvs populate the pxelinux.0, ipxe, and elilo default, fallthrough files. These are different than their counterpart bootenvs (sledgehammer and local) which are machine specific bootenvs that populate configuration files specific to a single machine. A defined machine boots local whereas an unknown machine boots ignore. There can only be one OnlyUnknown bootenv active at a time. This is specified by the unknownBootEnv preference.