Custom entries in WinPEShl.ini

This page details how to use custom entries with WinPEShl.ini to run custom actions before or after the machine boots.

The default setup

2PXE writes a new WinPEShl.ini into the %programdata% directory each time it starts, one for x86 builds and one for x64 builds.

NOTE:

Please note that the WinPEShl.ini is ONLY transferred by default if the underlying configuration requires this. This is normally only the case for ConfigMgr related environments, and not other types of custom iPXE Anywhere Web Service scenarios. But the same file can be retrieved and injected if required.

The following text is written into the winpeshl.ini by default for an x64 boot image: (the x86 has other paths)

[LaunchApps] %SYSTEMDRIVE%\sms\bin\x64\TsProgressUI.exe,/register:winpe %windir%\system32\iPXEWinPEClient.exe,/NetworkInit %windir%\system32\iPXEWinPEClient.exe,/SkipNetworkInit %SYSTEMDRIVE%\sms\bin\x64\TsBootShell.exe

The x86 part with it's default paths:

[LaunchApps] %SYSTEMDRIVE%\sms\bin\i386\TsProgressUI.exe,/register:winpe %windir%\system32\iPXEWinPEClient.exe,/NetworkInit %windir%\system32\iPXEWinPEClient.exe,/SkipNetworkInit %SYSTEMDRIVE%\sms\bin\i386\TsBootShell.exe

The first line initialises the TSProgressUI.exe in WinPE to show ConfigMgr progress UI. This is done so that the second command, the iPXEWinPEClient.exe can show progress.

The second command, initialises the network drivers in a way that guarantees that the network is available at the time of the second command exits. It' seems as a trivial task, but is actually harder than what most people realise, as the WinPE environment linked with some extra interesting drivers for special hardware and it's a complicated mess to sort out.

The third command runs the iPXEWinPEClient.exe, but skips the network init, causing it to just contact the iPXE Anywhere infrastructure to report back/get any command line information required to run from the server side PowerShell script in the iPXE Anywhere Web Service.

The fourth command runs TSBootShell.exe that starts the whole OSD process. That's it.

Custom example to troubleshoot with cmd.exe as first step

If you want to modify the content of these WinPEShl.ini files, you can edit them directly in files under 2PXE's %ProgramData% directories, but the changes are only there until service restart. So if you want the change to be permanent, you need to change the .config file for 2PXE.

The following shows how to put an entry in the .config file for 2PXE, the key x64WinPEShlConfiguration and x86WinPEShlConfiguration. So the following adds a new step in there to launch a cmd.exe before it starts the TSBootShell.exe.

    <add key="x64WinPEShlConfiguration" value="[LaunchApps]
%SYSTEMDRIVE%\sms\bin\x64\TsProgressUI.exe,/register:winpe
%windir%\system32\wpeutil.exe,InitializeNetwork
%windir%\system32\iPXEWinPEClient.exe,/SkipNetworkInit
%windir%\system32\cmd.exe /c start &quot;Paused TS: Close this to continue&quot; /wait cmd
%SYSTEMDRIVE%\sms\bin\x64\TsBootShell.exe"
/>

The corresponding for an x86 system:

    <add key="x86WinPEShlConfiguration" value="[LaunchApps]
%SYSTEMDRIVE%\\sms\\bin\\i386\\TsProgressUI.exe,/register:winpe
%windir%\\system32\\iPXEWinPEClient.exe,/NetworkInit
%windir%\\system32\\iPXEWinPEClient.exe,/SkipNetworkInit
%windir%\system32\cmd.exe /c start &quot;Paused TS: Close this to continue&quot; /wait cmd
%SYSTEMDRIVE%\\sms\\bin\\i386\\TsBootShell.exe"
/>

There are a few tips here on the syntax:

1. Note that the x86 and x64 entries are just for matching the machines booting, NOT the server itself.

2. As this is XML, some characters might need to be encoded, using XML encoding syntax to allow proper handling of the .config file itself.

3. If you mess up the .config file, the service will fail to start and crash.

4. Given point two above, make sure you check the xml integrity if you are uncertain using an XML parser that is better than notepad.exe.

5. If you don't have carriage return + newline by separating into the same line, you can do the same via \r\n in the line above.

Custom Example to use with TSBackground

When using OneVinn's/Johan Schreweliu's TSBackground app, the syntax needs to be updated a little to avoid having it crash. If you never heard of it, check out: https://onevinn.schrewelius.it/Apps01.html

[LaunchApps] %windir%\system32\wpeutil.exe,InitializeNetwork %windir%\system32\iPXEWinPEClient.exe,/SkipNetworkInit x:\sms\pkg\sms10000\TSBackground\TSBackground.exe

Given above, the following would be the .config entry:

     <add key="x64WinPEShlConfiguration" value="[LaunchApps]
%windir%\system32\wpeutil.exe,InitializeNetwork
%windir%\system32\iPXEWinPEClient.exe,/SkipNetworkInit
x:\sms\pkg\sms10000\TSBackground\TSBackground.exe"/>