Differences

This shows you the differences between two versions of the page.

--- wiki:sandbox [2015-10-06 02:49] – [WIM image contents] 72.5.59.165
+++ wiki:sandbox [2016-01-22 19:19] (current) – removed Aleksandr
@@ Line 1: / Line 1: @@
-====== wimboot ======
-''wimboot'' is a boot loader for Windows Imaging Format (''.wim'') files.  It enables you to boot a [[http://en.wikipedia.org/wiki/Windows_Preinstallation_Environment|Windows PE (WinPE)]] environment from a RAM disk, without wasting the memory used for the RAM disk image.
-You can use ''wimboot'' with [[:start|iPXE]] to [[:howto:winpe|boot Windows PE via HTTP]].  With a Gigabit Ethernet network, a typical 200MB WinPE image should download in less than two seconds.
-===== Advantages =====
-{{ :clipart:lightbulb.png?180x200|A light bulb}}
-== 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 ====
-{{ :clipart:cdrom.jpeg?150x150|A CD-ROM}}
-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 [[http://git.ipxe.org/releases/wimboot/wimboot-latest.zip|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 [[:start|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:
-{{ :screenshots:wimboot.png?600x334 |wimboot booting Windows 7}}
-{{ :screenshots:win7_installer.png?600x450 |Windows 7 installer booted via wimboot}}
-==== Next steps ====
-You can use ''wimboot'' to boot any bootable ''.wim'' image.  See the [[:howto:winpe|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 [[http://www.gnu.org/licenses/old-licenses/gpl-2.0.html|GNU GPL]].
-{{ :clipart:smile.png?100x100 |A smile}}
-===== Advanced topics =====
-{{ :clipart:books.png?180x180|Some books}}
-==== 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 ''[[:cmd: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 ''[[:cmd: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 ''[[:cmd: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 extract ''bootmgr.exe'' from this compressed bootmgr file, unless a ''bootmgr.exe'' was already supplied.
-  * ''*.wim'': Try to extract ''bootmgr.exe'' from the static path ''\Windows\Boot\PXE\bootmgr.exe'' within the supplied WIM image, unless a ''bootmgr.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 extract ''bootmgfw.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 the ''rawbcd'' argument to ''wimboot''.
-===== 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 //[[http://technet.microsoft.com/en-us/library/cc771845|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 ([[http://technet.microsoft.com/en-us/library/cc770770|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 //[[http://technet.microsoft.com/en-us/library/ee221031|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 [[http://technet.microsoft.com/en-us/library/cc732289|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.
-* [[device1:]]
-* [[device2:]]
-==== 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 ''[[:cmd:imgfetch]]'' commands are successful.
-    * Use the ''[[:cmd:imgstat]]'' command (optionally followed by ''[[:cmd:prompt]]'' in scripts) to verify that the files fetched by ''[[:cmd:imgfetch]]'' were successfully retrieved.
-  - Use the ''pause'' argument to ''wimboot'' to pause execution just after ''wimboot'' has printed some useful information about its initialization:
-    imgexec wimboot pause
-Below is an example output of ''[[:cmd: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 [[http://libguestfs.org/hivex.3.html|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 [[:howto:winpe|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 [[http://wimlib.sourceforge.net/|wimlib]]. This can be useful for verifying that ''bootmgr.exe'' is indeed located in the ''\Windows\Boot\PXE\'' directory.
-==== 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 [[http://wimlib.sourceforge.net/|wimlib]]. This can be useful for verifying that ''bootmgr.exe'' is indeed located in the ''\Windows\Boot\PXE\'' directory.