grub-mknetdir

grub-mknetdir [OPTION...] DIRECTORY

-d, --grub-mkimage-parameters=PARAMETERS
    Passes additional PARAMETERS directly to the grub-mkimage command during the image generation process. This allows for fine-grained control over the modules included or other grub-mkimage options.

-a, --net-file-name=FILENAME
    Sets the default network boot filename that will be used by PXE clients (e.g., grub.efi, pxelinux.0). This name is typically placed in the architecture-specific subdirectory.

-s, --subdir=SUBDIR
    Specifies a custom SUBDIR within the target directory where the architecture-specific images will be installed. By default, GRUB uses architecture names (e.g., i386-pc, x86_64-efi) as subdirectories.

-r, --root-directory=PATH
    Treats PATH as the root of the GRUB installation. This is useful when generating images from a chroot environment or when GRUB files are located in a non-standard prefix.

-v, --verbose
    Prints verbose messages during execution, showing details about the image generation process and files being created.

--version
    Displays version information and exits.

-h, --help
    Displays a help message describing command options and usage, then exits.

The grub-mknetdir command is used to prepare a directory for network booting GRUB via TFTP. It automates the complex process of creating architecture-specific GRUB core images and placing them in a suitable subdirectory structure (e.g., i386-pc, x86_64-efi) within the specified target directory. These generated images include the necessary network modules for TFTP and PXE booting.

Essentially, this command simplifies the setup of a TFTP server's root directory by providing ready-to-serve GRUB boot files for various hardware platforms. It internally leverages grub-mkimage to create these bootable images, ensuring they contain the correct modules for network-based booting. This significantly streamlines the deployment of operating systems over a network, especially in environments with diverse client architectures.

The functionality of grub-mknetdir heavily depends on the GRUB modules and platforms installed on the system. If required modules or platform support files are missing, it may fail to generate bootable images for certain architectures. A functional TFTP server and, for PXE, a DHCP server configured to point to the TFTP server, are prerequisites for utilizing the generated network boot directory.

Under the hood, grub-mknetdir orchestrates multiple calls to grub-mkimage for each supported architecture (e.g., i386-pc, x86_64-efi, arm64-efi). For each architecture, it intelligently selects and bundles the necessary GRUB modules, including those required for network protocols like TFTP, HTTP, and DHCP, into a minimal boot image (e.g., core.img or grub.efi). These images are then placed into an organized directory structure, ready to be served by a TFTP server.

To effectively use the output of grub-mknetdir, a TFTP server must be configured to serve the created directory. For PXE booting, a DHCP server also needs to be set up to provide clients with the IP address of the TFTP server and the boot filename (often specified using DHCP options like 66 and 67). Clients will then download the appropriate GRUB image and configuration files from the TFTP server to initiate the network boot process.

grub-mknetdir is an integral part of the GRand Unified Bootloader (GRUB) project, specifically introduced in GRUB 2. Its development was driven by the increasing complexity of network booting scenarios, including support for multiple architectures (i386, x86_64, ARM, etc.) and firmware interfaces (BIOS, UEFI). Prior to this command, setting up a comprehensive GRUB netboot environment often required manual execution of grub-mkimage for each desired architecture and a deeper understanding of GRUB's module system.

The command aims to streamline and automate this process, making GRUB's powerful network boot capabilities more accessible and robust. Its existence reflects GRUB's continuous evolution to support diverse hardware and boot methods in modern computing environments.

grub-mkimage(1), grub-install(8), grub-mkconfig(8), grub-probe(8)