Documentation
¶
Index ¶
- func AddElToritoEFIBoot(isoPath string, bootImage []byte) error
- func BootloaderSidecarPath(isoPath string) string
- func CreateFATImage(imgPath string, files map[string][]byte) error
- func CreateFATImageSized(imgPath string, files map[string][]byte, minSize int64) error
- func CreateSimpleISO(isoPath string, files map[string][]byte) error
- func CreateWindowsISO(isoPath, stageDir, volumeLabel string) error
- func DiagnoseISO(isoPath string) string
- func FindFileExtent(isoPath, filePath string) (uint32, int64, error)
- func ReadFileFromFAT(imgPath, filePath string) ([]byte, error)
- func ReadFileFromISO(isoPath, filePath string) ([]byte, error)
- func RequireEFIBootable(isoPath string) error
- func SetElToritoBootImage(isoPath string, loadRBA uint32, sectorCount uint16) error
- type ElToritoInfo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddElToritoEFIBoot ¶
AddElToritoEFIBoot makes an ISO EFI-bootable by writing an El Torito Boot Record Volume Descriptor at sector 17 (the LBA the El Torito specification fixes and firmware reads directly), a boot catalog in the unused system area, and the boot image itself appended to the end of the file. hdiutil makehybrid cannot author El Torito EFI entries, so the macOS mastering path bolts them on after the fact (run 20260812T081924: a pure-UDF image with no catalog got no FSn: mapping from EDK2 and dropped to the EFI shell).
Two starting layouts are handled:
- pure UDF (hdiutil -udf): BEA01/NSR02/TEA01 at sectors 16–18. NSR and TEA shift down one sector to free sector 17. That stays valid UDF: ECMA-167 readers skip foreign CD001 descriptors while walking the recognition sequence, which is how stock Microsoft bridge media is laid out.
- plain ISO 9660: the set terminator at sector 17 moves to 18 when that sector is free; otherwise it is dropped, which parsers tolerate — they stop at the first sector that is no valid descriptor.
func BootloaderSidecarPath ¶
BootloaderSidecarPath is where mastering exports the installer's BOOTAA64.EFI next to the ISO. Pure-UDF media (the macOS hdiutil path) is unreadable to the Go-native ISO readers, so the bootloader the answer volume needs is saved while the staged tree still exists as plain files.
func CreateFATImage ¶
CreateFATImage creates a FAT32 disk image at imgPath containing the given files. Keys are absolute paths (e.g. "/startup.nsh"), values are file content. UEFI firmware mounts FAT natively, so this is the right format for images that need to be visible as an FS device in the UEFI shell.
func CreateFATImageSized ¶
CreateFATImageSized works like CreateFATImage but enforces a minimum disk size. Use this when the guest needs free space beyond the initial content (e.g. a builder WinPE that writes results back to the volume).
func CreateSimpleISO ¶
CreateSimpleISO creates an ISO 9660 image with Rock Ridge extensions at isoPath containing the given files. Keys are absolute paths (e.g. "/autounattend.xml"), values are file content.
func CreateWindowsISO ¶
CreateWindowsISO creates a bootable Windows installer ISO from a staged directory tree. The stageDir must contain efi/microsoft/boot/efisys.bin (or efisys_noprompt.bin, preferred) for EFI boot.
On Linux: uses genisoimage/mkisofs with UDF + El Torito. On macOS: uses hdiutil makehybrid (built-in) as primary, genisoimage/mkisofs as fallback. hdiutil produces a UDF+ISO9660 hybrid that UEFI firmware boots natively without an El Torito catalog.
func DiagnoseISO ¶
DiagnoseISO returns a human-readable dump of the ISO's volume descriptor chain and partition detection, for debugging why readers fail on some platforms.
func FindFileExtent ¶
FindFileExtent returns the starting sector (2048-byte LBA) and size of a file on an ISO 9660 image. Needed to point boot structures at a file, which ReadFileFromISO cannot express since it only returns contents.
func ReadFileFromFAT ¶
ReadFileFromFAT reads a file from a FAT32 disk image and returns its content.
func ReadFileFromISO ¶
ReadFileFromISO reads a file from an ISO 9660 image and returns its content. It tries three strategies in order:
- go-diskfs (handles simple ISOs created by CreateSimpleISO)
- raw ISO 9660 directory parsing (handles hybrid images)
- external tool (7z or bsdtar — handles pure UDF like Windows ARM64 media)
func RequireEFIBootable ¶
RequireEFIBootable reports whether firmware can boot the ISO: it must carry an El Torito boot catalog with a bootable EFI (0xEF) entry. Images failing this (e.g. raw hdiutil -udf output) drop the VM to the EFI shell.
func SetElToritoBootImage ¶
SetElToritoBootImage repoints an ISO's default El Torito boot entry at a different image. Windows media carries both a prompting boot image (efisys.bin, "Press any key to boot from CD or DVD") and a silent one (efisys_noprompt.bin); unattended installs want the latter, and stock Microsoft ISOs always ship with the prompting one selected.
Types ¶
type ElToritoInfo ¶
type ElToritoInfo struct {
// PlatformID from the validation entry: 0x00 = 80x86, 0xEF = EFI.
// UEFI firmware requires 0xEF; 0x00 marks the image as BIOS-bootable only.
PlatformID byte
// Bootable is true when the default entry's boot indicator is 0x88.
Bootable bool
// LoadRBA is the absolute sector (2048-byte) of the boot image.
LoadRBA uint32
// SectorCount is the number of 512-byte virtual sectors to load.
SectorCount uint16
}
ElToritoInfo describes the El Torito boot catalog of an ISO image.
func InspectElTorito ¶
func InspectElTorito(isoPath string) (*ElToritoInfo, error)
InspectElTorito parses the El Torito boot catalog of an ISO image. It returns an error if the image has no Boot Record Volume Descriptor.
Source Files