This is an old revision of the document!
Table of Contents
wimboot
wimboot
is a boot loader for Windows Imaging Format (.wim
) files. It enables you to boot a Windows PE (WinPE) environment from a RAM disk, without wasting the memory used for the RAM disk image.
You can use wimboot
with iPXE to boot Windows PE via HTTP. With a Gigabit Ethernet network, a typical 200MB WinPE image should download in less than two seconds.
Advantages
Speed
wimboot
can download images at the full speed supported by your network, since it can use HTTP rather than TFTP.
Efficiency
wimboot
allows Windows to reuse the memory that was used to hold the RAM disk image; there is no wasted memory.
Ease of use
wimboot
works directly with .wim
image files; there is no need to wrap your .wim
into an ISO or FAT filesystem image.
BIOS/UEFI compatibility
wimboot
allows you to use a single procedure and set of files to boot under both BIOS and UEFI environments.
Download
You can download the latest version from http://git.ipxe.org/releases/wimboot/wimboot-latest.zip.
Older versions are available from http://git.ipxe.org/releases/wimboot. The source code is maintained in a git
repository at http://git.ipxe.org/wimboot.git.
Getting started
If you have a Windows installation DVD-ROM (Vista, Server 2008, or more recent), and a web server (such as Apache or IIS), then you have everything you need to start using wimboot
.
Extract the Windows boot files
Copy the contents of the Windows installation DVD-ROM to a directory on your web server (e.g. /var/www/win7
for Apache, or C:\inetpub\wwwroot\win7
for IIS).
If you do not have enough disk space to copy the entire contents of the DVD-ROM, then you may copy only the following files:
/boot/bcd /boot/boot.sdi /sources/boot.wim
Download wimboot
Download the latest version of wimboot and extract the file wimboot
to the same directory on your web server.
Create the iPXE script
Create a text file boot.ipxe
in the same directory on your web server, containing:
#!ipxe kernel wimboot initrd boot/bcd BCD initrd boot/boot.sdi boot.sdi initrd sources/boot.wim boot.wim boot
Boot
Boot using iPXE from the URL of your iPXE script, e.g. http://my.web.server/win7/boot.ipxe
. You should see iPXE download your Windows boot files via HTTP and boot into the Windows installer:
Next steps
You can use wimboot
to boot any bootable .wim
image. See the Windows PE tutorial for information on how to create and customise your own .wim
images.
Licence
wimboot
is free, open-source software licensed under the GNU GPL.
Advanced topics
Multi-image WIM files
A WIM file can contain multiple bootable images. You can use the index=<N>
command-line option to select the image to be booted. For example:
kernel wimboot index=2
Custom boot manager
wimboot
will attempt to extract an appropriate boot manager (such as bootmgr.exe
or bootmgfw.efi
) from the WIM file.
You can disable this behaviour by explicitly providing an appropriate set of boot manager binaries. For example:
kernel wimboot initrd bootmgr bootmgr initrd efi/boot/bootx64.efi bootx64.efi
Disabling automatic BCD modifications
wimboot
will automatically patch standard BIOS-compatible boot configuration data (BCD) files to allow them to be used on UEFI systems, by changing all occurrences of the string “.exe
” to “.efi
”.
You can disable this behaviour by using the rawbcd
command-line option. For example:
kernel wimboot rawbcd
Displaying graphical boot messages
wimboot
will force the Windows boot manager to display error messages in text mode. It does this to work around a bug in some versions of the Windows boot manager, which would otherwise fail to display error messages unless suitable font files are provided.
You can disable this behaviour by using the gui
command-line option and by providing all of the required font files. For example:
kernel wimboot gui initrd boot/fonts/segmono_boot.ttf segmono_boot.ttf initrd boot/fonts/segoe_slboot.ttf segoe_slboot.ttf initrd boot/fonts/segoen_slboot.ttf segoen_slboot.ttf initrd boot/fonts/wgl4_boot.ttf wgl4_boot.ttf
How wimboot works
When wimboot
is executed, it sets up a boot-loader environment before handing over execution to bootmgr.exe
, the Windows boot manager, which continues to boot Windows according to the supplied boot configuration data (BCD).
Command line processing
When wimboot
runs, it first processes the command line parameters supplied to it. The following parameters can be used to change its behaviour:
rawbcd
: Disable rewriting.exe
to.efi
in the BCD file.gui
: Display graphical boot messages.pause[=quiet]
: Show info and wait for keypress.index=n
: Use WIM image index n.initrdfile
: Ignored. For syslinux compatibility.
CPIO archive extraction
Much like the Linux kernel, wimboot
will extract the CPIO archive supplied to it by iPXE. The CPIO archive can be constructed with iPXE via the imgfetch
command, and each invocation should be on the form
imgfetch --name <somename> <uri> <somename>
This will fetch the file given by <uri>
and make it available with the virtual filename <somename>
in the CPIO archive supplied to wimboot
. Multiple imgfetch
commands can be used, one after another. The seemingly redundant <somename>
statements are used to provide compatibility with both UEFI mode (--name <name>
) and legacy BIOS mode (<name>
as the first argument) at the same time.
NOTE: The virtual filename <somename>
must be a flat filename without subdirectory components.
The wimboot virtual filesystem
The files from the CPIO archive are made available in a virtual filesystem provided up by wimboot
. Here's an example of how this works in practice:
imgfetch --name BCD http://.../test.bcd BCD imgfetch --name boot.sdi http://.../boot.sdi boot.sdi imgfetch --name boot.wim http://.../install.wim boot.wim
This fetches the three files, which will all – when wimboot
executes – be made available at multiple locations in a virtual filesystem. The locations are as follows:
\
\Boot
\Boot\Fonts
\Boot\Resources
\Sources
\EFI
\EFI\Boot
\EFI\Microsoft
\EFI\Microsoft\Boot
So for any given file, say test.bcd
, it will be made available with the filename BCD
at all the locations given above:
\BCD
\Boot\BCD
\Boot\Fonts\BCD
\Boot\Resources\BCD
\Sources\BCD
\EFI\BCD
\EFI\Boot\BCD
\EFI\Microsoft\BCD
\EFI\Microsoft\Boot\BCD
In practice, this enables bootmgr.exe
to read \Boot\BCD
and related files, even if they were seemingly placed only in the root directory by the imgfetch
command. This can avoid having to modify BCD files.
Once it's set up, the virtual filesystem is then mapped to a disk drive so that bootmgr.exe
can identify and read files from it.
NOTE: The BCD file name must be simply BCD
so that it can be found by bootmgr.exe
; it searches only for the specific path \Boot\BCD
.
NOTE: The boot.sdi
and boot.wim
paths must match the paths referred to in the BCD file. In other words, the BCD could refer to either boot.wim
, \Boot\boot.wim
, \Sources\boot.wim
or any of the other recognized subdirs; they would all work. On the other hand, if the BCD refers to a path not covered by the virtual filesystem, like \Image\boot.wim
, it would fail.
Extracting bootmgr.exe
As wimboot
reads each file from the CPIO archive, the file's virtual filename is matched against a list of special names to see if it needs special treatment:
bootmgr.exe
: Set this as the file to execute at the end of the boot-loader initialization.bootmgr
: Try to extractbootmgr.exe
from this compressed bootmgr file, unless abootmgr.exe
was already supplied.*.wim
: Try to extractbootmgr.exe
from the static path\Windows\Boot\PXE\bootmgr.exe
within the supplied WIM image, unless abootmgr.exe
was already supplied.
NOTE: The ability to extract bootmgr.exe
from the WIM image was added to wimboot
v2.2.0. It is a very convenient feature that lets you skip having to explicitly supply the bootmgr.exe
file explicitly.
NOTE: If no bootmgr.exe
is found, wimboot
exits.
Running bootmgr.exe
At the final stage of wimboot
execution, it reads bootmgr.exe
into memory and hands over execution to it.
EFI platform differences
On EFI platforms, a few details are changed:
wimboot
can extractbootmgfw.efi
from the supplied WIM image, using the path\Windows\Boot\EFI\bootmgfw.efi
.wimboot
automatically patches the BCD file to change any occurrence of.exe
to.efi
. This behaviour can be disabled by therawbcd
argument towimboot
.
How bootmgr.exe works
When bootmgr.exe
executes, it has the first-stage environment already set up for it, containing the virtual filesystem set up by wimboot
. As it runs, it performs the following steps.
Refer to the Microsoft How Booting into a Boot Image Works documentation for some additional details.
Reading the BCD file
bootmgr.exe
first interacts with the virtual filesystem by trying
to read the BCD (Boot Configuration Data store) file from the hardcoded path \Boot\BCD
.
The BCD file can come from a variety of sources, or it can be created from scratch or modified using the bcdedit.exe
tool in Windows. See the troubleshooting section for more information.
Refer to the Microsoft Boot Process and BCDEdit documentation for some additional details.
Reading additional files
Once the BCD is read, bootmgr.exe
will try to read the files referred to by the BCD from the virtual filesystem, such as the stub ramdisk SDI (System Deployment Image) path, e.g. \Boot\boot.sdi
, and the main WIM Windows Imaging Format) image, e.g. \Boot\boot.wim
.
NOTE: The SDI image is typically always provided by various Windows versions and deployment tools as boot.sdi
, which is a template ramdisk with no content. It does not change significantly and does not need any change or customizations applied to it.
NOTE: The WIM image is the main image, either extracted from the Windows installation medium, or containing custom content created by the user or some automated image creation/capture process.
Mounting the ramdisk
Once the relevant files are read from the virtual filesystem, bootmgr.exe
mounts the blank template SDI ramdisk and appends the WIM image to it.
Executing winload.exe
With the SDI+WIM ramdisk mounted and ready, bootmgr.exe
hands over execution to the ramdisk as if it were an actual disk. The loading routines will eventually hand over execution to \Windows\system32\winload.exe
.
Troubleshooting
Several things can go wrong in the boot process, and the bootmgr.exe
error handling and output is quite vague and ambiguous, making it hard to understand what the exact problem might be.
Example errors
Some common error messages are listed below:
- When
bootmgr.exe
cannot find or read the BCD file:
File: \Boot\BCD Status: 0xc000000f Info: An error occurred while attempting to read the boot configuration data.
- When
bootmgr.exe
cannot find or read the SDI file:
Status: 0xc000000f Info: The boot selection failed because a required device is inaccessible.
- When
bootmgr.exe
cannot find or read the WIM image:
Status: 0xc000000f Info: A required device isn't connected or can't be accessed.
Finding the culprit
The usual culprit is incorrect data in the BCD file, which causes bootmgr.exe
to stall without knowing how to proceed. Incorrect data can typically be:
- referring to the wrong file name; or
- referring to files outside the directories provided by the
wimboot
virtual file systems, such as\
,\Boot
,\Sources
, etc.
By following the wimboot
/bootmgr.exe
execution chain, troubleshooting is made a bit easier:
- Make sure to use the latest
wimboot
version. - Ensure that the
imgfetch
commands are successful. - Use the
pause
argument towimboot
to pause execution just afterwimboot
has printed some useful information about its initialization:
imgexec wimboot pause
Below is an example output of imgstat
showing the files that were retrieved, their sizes and their arguments. The arguments will map to the filenames as made available in the virtual filesystem set up by wimboot
:
test.bcd : 12288 bytes "BCD" boot.sdi : 3170304 bytes "boot.sdi" install.wim : 404876823 bytes "boot.wim" wimboot : 34576 bytes [bzImage] [SELECTED] "pause=quiet"
An example output of the wimboot
pause screen:
wimboot v2.4.1 -- Windows Imaging Format bootloader -- http://ipxe.org/wimboot Command line: "pause=quiet" Using BCD via 0x67925074 len 0x3000 Using boot.sdi via 0x67929078 len 0x306000 Using boot.wim via 0x67c30078 len 0x1821ee17 ...found WIM file boot.wim ...found file "\Windows\Boot\PXE\bootmgr.exe" Using bootmgr.exe via 0x2bc18 len 0x7fd80 ...extracted bootmgr.exe Emulating drive 0x81 Entering bootmgr.exe with parameters at 0x2a520
As for bootmgr.exe
, it will try to read the essential BCD from \Boot\BCD
. Once it succeeds, it will inspect the BCD and act accordingly. Ensure that the BCD contains valid data and refers to files and paths that are reachable within the wimboot
virtual filesystem.
BCD contents
Ensure that the BCD file contains valid configuration. To do this, you need to examine it with the Windows-only bcdedit.exe
program. Alternatively, the hivex registry hive libraries and associated language bindings can be used on other platforms, but the BCD hive structure and data encoding makes it very cumbersome.
Here's an example, using bcdedit.exe
to dump the BCD contents:
> bcdedit /enum all /store test.bcd Windows Boot Manager -------------------- identifier {bootmgr} description Windows 7 Boot Manager displayorder {9b0a74...} timeout 30 Windows Boot Loader ------------------- identifier {9b0a74...} device ramdisk=[boot]\Boot\boot.wim,{ramdiskoptions} description Windows 7 Installation osdevice ramdisk=[boot]\Boot\boot.wim,{ramdiskoptions} systemroot \Windows detecthal Yes winpe Yes Setup Ramdisk Options --------------------- identifier {ramdiskoptions} description Ramdisk Options ramdisksdidevice boot ramdisksdipath \Boot\boot.sdi
You might find that the BCD file contains references to files that have paths that will not ever match wimboot
's search list (\
, \Boot
, \Sources
, etc). If this is the case, you may want to either edit or recreate the BCD file.
Here's an example of creating a BCD file from scratch:
set BCDSTORE=BCD bcdedit /createstore %BCDSTORE% bcdedit /store %BCDSTORE% /create {ramdiskoptions} /d "Ramdisk Options" bcdedit /store %BCDSTORE% /set {ramdiskoptions} ramdisksdidevice Boot bcdedit /store %BCDSTORE% /set {ramdiskoptions} ramdisksdipath \Boot\boot.sdi for /f "Tokens=3" %%x in ('bcdedit /store %BCDSTORE% /create /d "Windows 7 Installation" /application osloader') do set GUID=%%x bcdedit /store %BCDSTORE% /set %GUID% systemroot \Windows bcdedit /store %BCDSTORE% /set %GUID% detecthal Yes bcdedit /store %BCDSTORE% /set %GUID% winpe Yes bcdedit /store %BCDSTORE% /set %GUID% osdevice ramdisk=[boot]\Boot\boot.wim,{ramdiskoptions} bcdedit /store %BCDSTORE% /set %GUID% device ramdisk=[boot]\Boot\boot.wim,{ramdiskoptions} bcdedit /store %BCDSTORE% /create {bootmgr} /d "Windows 7 Boot Manager" bcdedit /store %BCDSTORE% /set {bootmgr} timeout 30 bcdedit /store %BCDSTORE% /set {bootmgr} displayorder %GUID% bcdedit /enum all /store %BCDSTORE%
The BCD is a complex beast with lots of options, which makes it hard to know which details are required for the specific type of boot (ADK, AIK, WDS, etc). Refer to the iPXE WinPE documentation for more details.
WIM image contents
Should you need to verify the contents of the WIM image without access to Windows, use the example application applywim
supplied with wimlib. This can be useful for verifying that bootmgr.exe
is indeed located in the \Windows\Boot\PXE\
directory.