DEBOPS.IPXE(5)

NAME
debops.ipxe - Manage iPXE boot service using Ansible

SYNOPSIS

debops run service/ipxe [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The iPXE <https://ipxe.org/> project provides an open source network boot firmware. It can be used to boot computers over the network using DHCP, PXE and TFTP protocols, and hand off the boot process to other operating systems provided over HTTP, NFS or iSCSI protocols.

The debops.ipxe Ansible role installs the ipxe APT package and prepares a simple boot menu which can be used to either launch the Debian Installer over the network, or switch to another publicly available network boot menu.

GETTING STARTED

  Debian netboot installer support

By default the role will download and prepare a set of Debian netboot installers for various OS releases. The Debian installers will be available via the boot menu, with a possibility to boot into the text, graphical or expert install. A preseeded configuration is also available for larger environments.

Optionally, the role can include the non-free firmware required by certain devices (for example network cards) for convenience.The installation of the non-free firmware is disabled by default, you can enable it using the ipxe__debian_netboot_firmware variable. The firmware will also be enabled automatically if non-free repositories are configured on the host in APT.

  Additional services required

The debops.ipxe role relies on other DebOps roles to provide the needed DHCP and TFTP services. You can use either debops.dnsmasq on an internal network to configure DHCP, DNS, PXE and TFTP services, or use debops.dhcpd and debops.tftpd roles to set up a more comprehensive network environment.

  Example inventory

To configure iPXE boot firmware on a given host, you need to include in the [debops_service_ipxe] Ansible inventory group:

[debops_service_ipxe]
hostname

If you are using debops.dnsmasq to provide DHCP and TFTP services, you can configure iPXE environment on the same host. Alternatively, debops.tftpd role can be used to provide TFTP service on a separate host on the network, which is then specified via DHCP as the "next server" for other hosts to boot from.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.ipxe role:

---
- name: Manage iPXE configuration files
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_ipxe' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: ipxe
      tags: [ 'role::ipxe', 'skip::ipxe' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::ipxe
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

  Other resources

List of other useful resources related to the debops.ipxe Ansible role:

•   iPXE scripting documentation <https://ipxe.org/scripting>, command reference <https://ipxe.org/cmd>

•   Installing Debian using network booting <https://wiki.debian.org/PXEBootInstall>

•   Non-free firmware in Debian <https://wiki.debian.org/Firmware> documentation page

•   How to include non-free firmware in Debian netboot installer <https://wiki.debian.org/DebianInstaller/NetbootFirmware>

•   netboot.xyz <https://netboot.xyz/> - public network boot server, available from DebOps Boot Menu

•   SAL's Boot Menu <http://boot.salstar.sk/> - another public network boot server available via DebOps Boot Menu

•   Rackspace Boot Server <http://boot.rackspace.com/>, available via DebOps Boot Menu

DEFAULT VARIABLES: CONFIGURATION

some of debops.ipxe default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  ipxe__debian_netboot_release_map

The ipxe__debian_netboot_*_release_map variables define a list of Debian Installer releases known to the role. These releases will be downloaded and prepared by the debops.ipxe Ansible role for use on the local network.

The Debian netboot installers are prepared in an elaborate directory structure inside of the ipxe__debian_netboot_pxe_root directory, which supports multiple OS releases, architectures and installation flavors. Each installer optionally can be supplemented by a set of non-free firmware packages provided by Debian to allow use of hardware that requires it.

  Examples

See the ipxe__debian_netboot_default_release_map variable for an example configuration.

  Syntax

Each list entry is a YAML dictionary with specific parameters:

name
    Required. An identifier for a particular configuration entry, not used otherwise. Configuration entries with the same name parameter are merged together, this can be used to modify entries from the role defaults using Ansible inventory.

state
    Optional. If not specified or present, a given Debian Installer release will be downloaded and prepared by the role. If absent, a given release will be skipped; existing configuration will not be modified or removed. If ignore, a given configuration entry will not be evaluated by the role. This can be used to modify the configuration conditionally.

release
    Required. Name of the OS release a given entry defines. The OS releases which will be prepared are filtered by the ipxe__debian_netboot_releases list variable.

architecture
    Required. Name of the OS architecture a given entry defines. The OS architectures which will be prepared are filtered by the ipxe__debian_netboot_architectures list variable.

netboot_url
    Optional. An URL to the netboot.tar.gz tarball which contains the installer files. If not specified, the URL will be generated automatically based on the selected Debian mirror, release and architecture.

netboot_subdir
    Optional. Normally empty, this parameter can be used to specify a subdirectory in the installer directory which will be included in the URL to the installer tarball. Currently this is only useful to define a "gtk-based" installer entry which provides the graphical installer. At the moment the only sensible value is /gtk.

netboot_version
    Required. Specify the version of the installer to download and prepare. This parameter will be changed over time as the new installer version are released; the current symlink will be updated to match the selected version. The current and upstream versions can be checked in the DebOps monorepo root directory by running the make versions command.

netboot_checksum
    Optional. Specify the checksum of the installer tarball, usually a SHA256. If not specified, the file checksum will not be verified. The checksum should be updated on any version changes to match the new tarball.

netboot_current
    Optional, boolean. If not specified or True, the role will update the current symlink to the specified installer version. If False, existing symlink will not be updated.

firmware_url
    Optional. An URL to the firmware.cpio.gz file which contains the firmware packages. If not specified and the firmware_version parameter is specified, the URL will be generated automatically based on the firmware mirror URL, OS release and firmware version.

firmware_version
    Optional. Specify the version of the firmware file to download and add to the Debian installer initrd.gz file. If not specified, the firmware will not be downloaded.

firmware_checksum
    Optional. Specify the checksum of the firmware file, usually a SHA256. If not specified, the file checksum will not be verified. The checksum should be updated on any firmware version changes to match the new file.

  ipxe__scripts

The ipxe__*_scripts variables define a list of iPXE scripts stored in the ipxe__tftp_root directory (by default /srv/tftp/). At boot time, the iPXE boot loader will download and execute the menu.ipxe script (this is just a convention controlled by the DHCP server). The script contains iPXE commands which can be used to define an interactive menu, chainload other scripts and boot operating systems.

  Examples

See the ipxe__default_scripts variable for an example configuration.

Modify an existing default configuration to include additional main menu items that boot an ISO image over HTTP. When the new option is selected, the iPXE boot loader will load the new iso-image.ipxe script:

- name: 'menu.ipxe'
  options:
    - name: 'main-menu'
      raw: |
        item --key d debian-installer ${space} Install Debian GNU/Linux on this host [d]
        item iso-image ${space} Boot custom ISO image
        item
- name: 'iso-image.ipxe'
  raw: |
    set iso-root http://boot.{{ ansible_domain }}/iso/
    set iso-img custom-image.iso
    initrd ${iso-root}/${iso-img}
    chain memdisk iso || goto error
    :error
    echo Error occurred, press any key to return to menu...
    prompt
    set menu main_menu
    chain menu.ipxe
  state: 'present'

  Syntax

Each configuration entry defines one iPXE script. The configuration is specified as a YAML dictionary with specific parameters:

name
    Required. Name of the iPXE script. You can include subdirectories in the name (for example extra/menu.ipxe which will be created automatically. Entries with the same name parameter are merged together, this can be used to modify existing entries as needed.

comment
    Optional. A string or a YAML text block with a comment added at the top of the iPXE script.

state
    Optional. If not defined or present, a given iPXE script will be created by the role. If absent, the specified iPXE script will be removed by the role. If ignore, a given configuration entry will be ignored by the role during its execution. This can be used to activate configuration entries conditionally.

raw Optional. A YAML text block that contains the iPXE script, added as-is in the generated file. The #!ipxe shebang will be added automatically at the top of the file and does not have to be specified. See the iPXE documentation <https://ipxe.org/scripting> for more details about scripting the bootloader.

options
    Optional. An alternative way to define the contents of the generated iPXE script. The options parameters from different configuration entries are merged together and elements of the options list can affect each other. This is a list of YAML dictionaries, each dictionary describes a part of the generated file using specific parameters:

name
    Required. An identifier of a given part of the iPXE script. If raw parameter is specified, the name parameter is not used otherwise. If raw parameter is not specified, the name parameter is the second element in the script line (see value and command parameters). By default this defines an iPXE variable name. Option list entries with the same name parameter are merged together.

value
    Optional. If raw parameter is not specified, this parameter defines the third element of the script line. By default this defines a value of a given iPXE variable. You can specify a string or a list which will be concatenated with spaces as separators.

command
    Optional. If raw parameter is not specified, this parameter defines the first element of the script line, by default set which defines an iPXE variable.

raw Optional. YAML text block that contains a section of the iPXE script.

comment
    Optional. A string or YAML text block with a comment about a given script section.

state
    Optional. If not specified or present, a given script section will be included in the generated file. If absent, a given script section will be removed from the generated file.

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others