Filename requirements should be documented

[PicoMitchell]

When I first started setting up wimboot 2.6, I noticed and documented some quirks, mainly about using custom scripts in consistent way for a dual Legacy BIOS and UEFI usage. I don't think any of these are serious bugs, but it is stuff that I had to discover with trial and error because it was undocumented or unclear in the documentation. Sorry if any of these are actually documented, I may have just rewritten a few things to be clear reminders in my face in the future if editing my wimboot config.

Since it looks like wimboot is now back in a development phase, I thought I would share these notes in case any of them seem worth addressing, or at least officially documenting as standard behavior.

I am not sure if any of these behaviors have already changed after version 2.6 since my current config works on 2.7.1 and I have not retested all these things to try to my break wimboot or my loading of custom scripts.

Notes about adding custom script files and naming:

• CUSTOM SCRIPTS can be dynamically added into WinPE and MUST be loaded BEFORE the .wim is loaded.
• CUSTOM SCRIPTS can ONLY be added into \Windows\System32, any custom path specified after a URL as described in https://ipxe.org/cmd/imgfetch is used as a filename instead of a path in Legacy BIOS mode and is ignored in UEFI mode.
• In Legacy BIOS mode, for wimboot to load properly, each script MUST have a name specified after the URL (which will also set the filename in the filesystem) even if the file doesn't need to be renamed.
• Also, in Legacy BIOS mode, because of needing to supply a filename as a argument, it appears that there is no way to use a filename that has spaces. So if a filename has spaces it MUST be renamed to not have any spaces.
• In UEFI mode, the names after the URLs are not required and are ignored (they do not rename the file). If a file needs to be renamed, initrd's "-n" arg can be used.
• In Legacy BIOS mode, the specified name after the URL is used even if a different name is set with "-n".
• In UEFI mode, the original filename will be used or a custom filename if one is set with initrd's "-n" arg.
• Since different args modify filenames differently for Legacy BIOS and UEFI mode it's very important to make sure filenames will be set the same in both environments.

This one is probably the most like an actual bug and was discovered when adding an empty flag file to put my own install script into a "testing mode" with extra debug logging:

• For some reason if this is an empty 0 byte file it will make wimboot in Legacy BIOS hang forever (so just put any text in the file).

Notes about .wim, BCD, and boot.sdi files:

• In Legacy BIOS mode, the name args after the URLs are required for wimboot to load properly as shown in https://ipxe.org/howto/winpe
• In UEFI mode, the name args after the URLs don't matter, BUT the .wim MUST be renamed to "boot.wim" using initrd's "-n" arg: https://forum.ipxe.org/showthread.php?tid=7814&pid=11905
• The settings required to Legacy BIOS don't interfere with UEFI and vice versa.

Please let me know if you need any clarification or examples about any of these notes.

[mcb30]

• CUSTOM SCRIPTS can be dynamically added into WinPE and MUST be loaded BEFORE the .wim is loaded.

This is documented at https://ipxe.org/wimboot#injected_files. As of commit 1f974a4 (in the 2.7.1 release) they will be used even if loaded after the .wim.

• CUSTOM SCRIPTS can ONLY be added into \Windows\System32, any custom path specified after a URL as described in https://ipxe.org/cmd/imgfetch is used as a filename instead of a path in Legacy BIOS mode and is ignored in UEFI mode.

True. The documentation at https://ipxe.org/wimboot#injected_files does already say "These files will appear within the X:\Windows\System32 directory"

• In Legacy BIOS mode, for wimboot to load properly, each script MUST have a name specified after the URL (which will also set the filename in the filesystem) even if the file doesn't need to be renamed.
• Also, in Legacy BIOS mode, because of needing to supply a filename as a argument, it appears that there is no way to use a filename that has spaces. So if a filename has spaces it MUST be renamed to not have any spaces.
• In UEFI mode, the names after the URLs are not required and are ignored (they do not rename the file). If a file needs to be renamed, initrd's "-n" arg can be used.
• In Legacy BIOS mode, the specified name after the URL is used even if a different name is set with "-n".
• In UEFI mode, the original filename will be used or a custom filename if one is set with initrd's "-n" arg.
• Since different args modify filenames differently for Legacy BIOS and UEFI mode it's very important to make sure filenames will be set the same in both environments.
• In Legacy BIOS mode, the name args after the URLs are required for wimboot to load properly as shown in https://ipxe.org/howto/winpe
• In UEFI mode, the name args after the URLs don't matter, BUT the .wim MUST be renamed to "boot.wim" using initrd's "-n" arg: https://forum.ipxe.org/showthread.php?tid=7814&pid=11905

Yes, it's probably worth documenting these naming requirements.

This one is probably the most like an actual bug and was discovered when adding an empty flag file to put my own install script into a "testing mode" with extra debug logging:
* For some reason if this is an empty 0 byte file it will make wimboot in Legacy BIOS hang forever (so just put any text in the file).

This is an iPXE bug - I can reproduce it without wimboot using a Linux kernel. Good catch!

* The settings required to Legacy BIOS don't interfere with UEFI and vice versa.

Not sure what you mean by this one, sorry - could you clarify?

Thanks!

[PicoMitchell]

I hope the custom script naming notes can help someone in the future. It all seems fairly straightforward to me now, but was a lot to figure out when I had just started using iPXE and wimboot and I didn't know whether I was making mistakes or running into bugs when files weren't loading properly in one environment or the other.

The settings required for Legacy BIOS don't interfere with UEFI and vice versa.

I wrote these quite a long time ago now... I think this was just saying that the required args for BIOS are ignored when in UEFI mode and the required args for UEFI are ignored when in BIOS mode, and that they don't conflict with each other. Probably an unnecessary note after the previous more specific information.

[mcb30]

This one is probably the most like an actual bug and was discovered when adding an empty flag file to put my own install script into a "testing mode" with extra debug logging:

• For some reason if this is an empty 0 byte file it will make wimboot in Legacy BIOS hang forever (so just put any text in the file).

This is an iPXE bug - I can reproduce it without wimboot using a Linux kernel. Good catch!

Now fixed in commit ipxe/ipxe@8446a439b

[mcb30]

I hope the custom script naming notes can help someone in the future. I all seems fairly obvious to me know, but was a lot to figure out when I had just started using iPXE and wimboot and I didn't know whether I was making mistakes or running into bugs when files weren't loading properly.

The settings required for Legacy BIOS don't interfere with UEFI and vice versa.

I wrote these quite a long time ago now... I think this was just saying that the required args for BIOS are ignored when in UEFI mode and the required args for UEFI are ignored when in BIOS mode, and that they don't conflict with each other. Probably an unnecessary note after the previous more specific information.

Makes sense, thanks. I'll keep this open as an issue for me to add a file-naming section to the documentation.

[ixeldino]

• CUSTOM SCRIPTS can ONLY be added into \Windows\System32, any custom path specified after a URL as described in https://ipxe.org/cmd/imgfetch is used as a filename instead of a path in Legacy BIOS mode and is ignored in UEFI mode.

initrd use.bat ..\..\use.bat

Thank's

[mcb30]

• CUSTOM SCRIPTS can ONLY be added into \Windows\System32

This is correct. Files are placed into \Windows\System32 since this allows for the injection of files such as winpeshl.ini that will be executed automatically by Windows.

If you need files moved elsewhere, inject a batch file that copies the files to the required locations after WinPE starts up.