====== Configure UEFI shim image ======

===== Synopsis =====

    shim [--timeout <timeout>] [<extra options>] <uri|image>


===== Examples =====

=== Download and configure a shim (if needed) ===

    shim http://192.168.0.1/shimx64.efi

=== Boot the RHEL installer via shim (if needed) ===

    #!ipxe
    
    set mirror http://192.168.0.1/rhel/BaseOS/x86_64/os
    
    kernel ${mirror}/images/pxeboot/vmlinuz initrd=initrd.img inst.repo=${mirror}
    initrd ${mirror}/images/pxeboot/initrd.img
    shim   ${mirror}/EFI/BOOT/BOOTX64.EFI
    boot

===== Description =====

Downloads the specified image and configures it for use as a UEFI Secure Boot shim, if needed.  A download progress timeout can be specified (in milliseconds) using the ''%%--timeout%%'' option.

The download will be skipped completely if iPXE is running in a BIOS environment, or if UEFI Secure Boot is disabled, or if a shim is not required to boot the currently selected image.

===== Command status =====

^ Success   | The shim was successfully downloaded, or the download was skipped     |
^ Failure   | The shim was not successfully downloaded                              |

===== See also =====

  * ''[[:cmd:kernel]]''
  * [[:cmd|List of all iPXE commands]]

===== Notes =====

The [[https://github.com/rhboot/shim|UEFI shim]] binary typically has a filename such as ''shimx64.efi'' or ''shimaa64.efi'', but is often found published under a UEFI default boot filename such as ''BOOTX64.EFI'' or ''BOOTAA64.EFI''.

The UEFI shim incorporates several curious design choices that generally render it incapable of directly executing a Linux kernel.  It is possible to build a customised shim that does not suffer from these problems, but this is no help to end users since any custom built shim will not include a UEFI Secure Boot signature.  iPXE therefore includes several workarounds that allow the shim binaries as signed and published by Linux distros to be used verbatim.

Various extra options are available to disable iPXE's workarounds for the problems in the UEFI shim:

  * The ''%%--require-loader%%'' option can be used to disable iPXE's automatic handling of the "shim lock" protocol entry point.  Use of this option will prevent the Linux kernel from booting successfully.  Do not use this option.

  * The ''%%--allow-pxe%%'' option can be used to disable iPXE's automatic handling of the API choices made available to the shim.  Use of this option will cause the shim to attempt to redownload the kernel and initrd via TFTP.  Do not use this option.

  * The ''%%--allow-sbat%%'' option can be used to disable iPXE's automatic handling of the [[https://github.com/rhboot/shim/blob/main/SBAT.md|Secure Boot Advanced Targeting]] metadata variable.  Use of this option will prevent the Linux kernel from booting successfully.  Do not use this option.