### Utility Definition Schema Example Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Schema for defining utility boot options in `defaults/main.yml`, specifying type, kernel, and initrd URLs. ```yaml utilitiesefi: utility_key: name: "Display Name" enabled: true type: direct # one of: direct, ipxemenu, memdisk, memtest, sanboot kernel: "" initrd: "" # optional ``` -------------------------------- ### Adding a New Operating System - Configuration Steps Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Provides a step-by-step guide for adding a new operating system to Netboot.xyz. This involves updating configuration files, creating new templates, and potentially adding endpoint URLs. ```markdown 1. Add entry to `releases:` in `roles/netbootxyz/defaults/main.yml`. 2. Create `roles/netbootxyz/templates/menu/.ipxe.j2` following existing templates. 3. The menu template is auto-discovered via `filetree` iteration — no registration needed. 4. Add the distro to the appropriate category menu (e.g., `linux.ipxe.j2`) if it needs a menu entry. 5. If using live images, add endpoint to `endpoints.yml`. 6. Test: `ansible-playbook site.yml --syntax-check && ansible-lint -v roles/netbootxyz/tasks` ``` -------------------------------- ### Install Molecule for Testing Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Install Molecule and the Docker plugin for running integration tests. This is a prerequisite for running molecule tests. ```bash pip install molecule molecule-docker ``` -------------------------------- ### Netboot.xyz Menu Hierarchy Example Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Illustrates the hierarchical structure of the iPXE menus. Menus chain using `chain ${menu}.ipxe || goto error`, with signature verification as a potential gate. ```text menu.ipxe (main) → linux.ipxe → ubuntu.ipxe, fedora.ipxe, ... → bsd.ipxe → freebsd.ipxe, openbsd.ipxe, ... → live.ipxe → live-ubuntu.ipxe, ... → utils-*.ipxe → windows.ipxe ``` -------------------------------- ### OS Definition Schema Example Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Schema for defining operating system releases in `defaults/main.yml`, including essential fields like name, mirror, and versions. ```yaml releases: distro_key: # lowercase, no hyphens (e.g., almalinux, rockylinux) name: "Display Name" mirror: "http://mirror.url" base_dir: "path/on/mirror" enabled: true menu: linux # one of: linux, bsd, dos, unix versions: - code_name: "version_id" name: "Display Version" ``` -------------------------------- ### Run Molecule Tests Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Execute Molecule integration tests. These tests require Docker to be installed and configured. ```bash molecule test ``` -------------------------------- ### Build and Run netboot.xyz Docker Image Source: https://github.com/netbootxyz/netboot.xyz/blob/development/README.md Builds a Docker image for local netboot.xyz development and then runs a container to generate the build output in a local 'buildout' directory. Ensure you are in the project root directory. ```bash docker build -t localbuild --platform=linux/amd64 -f Dockerfile . docker run --rm -it --platform=linux/amd64 -v $(pwd):/buildout localbuild ``` -------------------------------- ### Docker Build for netboot.xyz Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Build a Docker image for netboot.xyz. The output is directed to the buildout/ directory. ```bash docker build -t localbuild --platform=linux/amd64 -f Dockerfile . ``` -------------------------------- ### Deploy netboot.xyz using Ansible Source: https://github.com/netbootxyz/netboot.xyz/blob/development/README.md This command initiates the Ansible playbook to generate and deploy a self-hosted netboot.xyz environment. The build output is typically located in /var/www/html. ```bash ansible-playbook site.yml ``` -------------------------------- ### Chainload netboot.xyz (Legacy BIOS) Source: https://github.com/netbootxyz/netboot.xyz/blob/development/README.md Use this command to chainload netboot.xyz from an existing iPXE environment in Legacy (PCBIOS) mode. ```ipxe chain --autofree http://boot.netboot.xyz/ipxe/netboot.xyz.lkrn ``` -------------------------------- ### Chainload netboot.xyz (UEFI) Source: https://github.com/netbootxyz/netboot.xyz/blob/development/README.md Use this command to chainload netboot.xyz from an existing iPXE environment in UEFI mode. ```ipxe chain --autofree http://boot.netboot.xyz/ipxe/netboot.xyz.efi ``` -------------------------------- ### Run Dockerized netboot.xyz Build Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Run the Docker container to perform the build process. Mounts the current directory to /buildout for output. ```bash docker run --rm -it --platform=linux/amd64 -v $(pwd):/buildout localbuild ``` -------------------------------- ### Netboot.xyz File Organization Table Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md This table outlines the purpose of key files and directories within the Netboot.xyz project. It helps understand where different configurations, templates, and scripts are located. ```markdown | Path | Purpose | |------|---------| | `site.yml` | Main playbook entry point | | `defaults/main.yml` | All OS/utility definitions and default config | | `endpoints.yml` | Live image endpoint URLs | | `user_overrides.yml` | Local overrides (not committed) | | `templates/menu/*.ipxe.j2` | ~100 iPXE menu templates | | `templates/disks/*.j2` | Bootloader embedded scripts | | `templates/pipxe/*.j2` | Raspberry Pi Makefile templates | | `tasks/*.yml` | 14 Ansible task files | | `vars/{debian,redhat,ubuntu}.yml` | Per-distro package lists | | `script/` | Build and release shell scripts | ``` -------------------------------- ### Enable Custom Menus Configuration Source: https://github.com/netbootxyz/netboot.xyz/blob/development/etc/netbootxyz/custom/README.md Set these variables in your netboot.xyz configuration to enable custom menu generation and specify the directory for custom templates. ```yaml custom_generate_menus: true custom_templates_dir: "{{ netbootxyz_conf_dir }}/custom" ``` -------------------------------- ### Copy Custom Menu Directory Source: https://github.com/netbootxyz/netboot.xyz/blob/development/etc/netbootxyz/custom/README.md Use this command to copy the default custom menu directory to your netboot.xyz configuration path. ```bash cp -r etc/netbootxyz/custom /etc/netbootxyz/custom ``` -------------------------------- ### Ansible Menu-Only Build Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Perform an Ansible build that only generates menus, skipping bootloader compilation. Useful for quick menu updates. ```bash ansible-playbook site.yml -e "generate_disks=false generate_checksums=false generate_signatures=false" ``` -------------------------------- ### iPXE Error Handling Strategy Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Describes iPXE error handling, including the use of `command || goto fallback` chains for protocol degradation (HTTPS → HTTP → local boot) and the necessity of an `:error` label for user prompts. ```ipxe - **iPXE**: Use `command || goto fallback` chains. Protocol degradation: HTTPS → HTTP → local boot. Always provide a `:error` label that prompts the user. ``` -------------------------------- ### Docker Custom Templates Directory Configuration Source: https://github.com/netbootxyz/netboot.xyz/blob/development/etc/netbootxyz/custom/README.md When building netboot.xyz via Docker, configure the custom templates directory to point to a 'custom' folder within the root source directory. ```yaml custom_generate_menus: true custom_templates_dir: "/ansible/custom" ``` -------------------------------- ### Build Release Script Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Execute the build_release script for different release stages: development, pull request testing, release candidate, production, and rolling releases. ```bash ./script/build_release dev ``` ```bash ./script/build_release pr ``` ```bash ./script/build_release rc ``` ```bash ./script/build_release release ``` ```bash ./script/build_release rolling ``` -------------------------------- ### Ansible Syntax Check Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Perform a fast syntax check on Ansible playbooks before running a full build. ```bash ansible-playbook site.yml --syntax-check ``` -------------------------------- ### Ansible Error Handling Best Practices Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Details Ansible error handling strategies, emphasizing fail-fast behavior, using `when:` conditions for task guarding, and employing `| default()` to prevent undefined variable errors. ```ansible - **Ansible**: Relies on default fail-fast behavior. No `block/rescue/always`. Guard tasks with `when:` conditions. Use `| default()` to prevent undefined variable errors. ``` -------------------------------- ### iPXE Script Exit Pattern Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Standard pattern for exiting an iPXE script gracefully by clearing the menu and exiting with code 0. ```ipxe :distro_exit clear menu exit 0 ``` -------------------------------- ### iPXE Script Error Handling Pattern Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Pattern for handling errors in iPXE scripts, displaying a message and returning to the main menu. ```ipxe :error echo Error occurred, press any key to return to menu prompt goto main_menu ``` -------------------------------- ### Shell Script Error Handling Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Specifies the use of `set -e` at the beginning of all shell scripts to ensure immediate exit upon encountering any error. ```shell - **Shell scripts**: Use `set -e` at the top of all scripts. ``` -------------------------------- ### Lint Ansible Tasks Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Lint Ansible tasks to ensure code quality and adherence to best practices. Use the -v flag for verbose output. ```bash ansible-lint -v roles/netbootxyz/tasks ``` -------------------------------- ### Ansible Guard Boolean Pattern Source: https://github.com/netbootxyz/netboot.xyz/blob/development/AGENTS.md Use this pattern to guard boolean variables in Ansible tasks, ensuring they are correctly interpreted. ```yaml when: - generate_menus | default(true) | bool ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.