PreShellConfig - PhoenixPE/PhoenixPE GitHub Wiki
PhoenixPE uses a custom build AutoIt3 script during boot which takes care of essential tasks, such as preparing the environment, installing/loading drivers, loading and monitoring the shell, creating shortcuts, starting applications (autorun), starting network services, etc.
The PhoenixPE startup process consist of the following stages:
| Stage | Description |
|---|---|
| InitPE | Load drivers, configure the display, etc. |
| InitAudio | Initialize audio. |
| PreShellConfig | Configuration changes and applications/services that need to be started before the shell is loaded. This includes installing drivers, creating Ramdrives, mounting CD/USB, etc. |
| CreateShortcuts | Create shortcuts on the desktop and in the start menu. |
| InitShell | Start the shell (Explorer.exe, WinXShell, etc.). |
| PostShellConfig | Configuration changes and applications/services that can be started after the shell is running. |
| InitNetwork | Load drivers, initialize network adapters, and start network services. |
| AfterNetwork | Run configuration and applications/services after network services have been started. |
| Standby/Monitor | Monitor the shell. |
PhoenixPE.au3 is the loader script that runs on boot and is responsible for the entire PhoenixPE startup process. A skeleton script is placed in the %TargetDir%\System32 directory during build and this script is dynamically modified throughout the build process using PhoenixAPI script commands such as AddShortcut, AddAutoRun, AddStartupConfig, etc. The PhoenixPE.au3 script is not intended to be modified directly unless you an experienced developer with very specific needs.
Advanced users may choose to include user scripts written in either AutoIt3 or PECMD format to be run on startup. A typical use case would be to create shortcuts, run a program, or add registry entries during the boot process.
By placing a specifically named script in a pre-defined location these scripts will automatically be processed by the PhoenixPE loader during the PreShell stage.
| Filename | Location | Description |
|---|---|---|
| PhoenixPE-UserConfig.a3x | %TargetDir%\System32 |
Compiled AutoIt3 script packed in boot.wim. |
| PhoenixPE-UserConfig.a3x | %OutputDir%\PhoenixPE |
Compiled AutoIt3 script included on boot media (CD/USB). |
| PhoenixPE-UserConfig.au3 | %TargetDir%\PhoenixPE |
AutoIt3 script packed in boot.wim. |
| PhoenixPE-UserConfig.au3 | %OutputDir%\PhoenixPE |
AutoIt3 script included on boot media (CD/USB). |
| PhoenixPE-UserConfig.ini | %TargetDir%\System32 |
PECMD startup script packed in boot.wim. |
| PhoenixPE-UserConfig.ini | %OutputDir%\PhoenixPE |
PECMD startup script included on boot media (CD/USB). |
| PhoenixPE-UserConfig.wcs | %TargetDir%\System32 |
PECMD script (may be encrypted) packed in boot.wim. |
| PhoenixPE-UserConfig.wcs | %OutputDir%\PhoenixPE |
PECMD script (may be encrypted) included on boot media (CD/USB). |
| PhoenixPE-UserConfig.wcz | %TargetDir%\System32 |
Compressed/Encrypted PECMD script packed in boot.wim. |
| PhoenixPE-UserConfig.wcz | %OutputDir%\PhoenixPE |
Compressed/Encrypted PECMD script included on boot media (CD/USB). |
Autoit3 Script using PhoenixPE extensions
#NoTrayIcon
; This is a user defined PhoenixPE configuration file.
; It will be executed during the PhoenixPE Pre-Shell config.
AutoItSetOption("ExpandEnvStrings", 1)
#include "PhoenixPE.Common.au3"
; Main
Config()
Shortcuts()
LoadDrivers()
RunPrograms()
Func Config()
SetSplashText("Additional configuration in progress...")
RegWrite("HKEY_LOCAL_MACHINE\Software\Example", "Key1", "REG_SZ", "This is an example of RegWrite")
EndFunc ;==>Config
Func Shortcuts()
SetSplashText("Creating additional shortcuts...")
MakeShortcut("%WinDir%\myProgram.exe", @ProgramsCommonDir & "\MyProgram.lnk")
EndFunc ;==>Shortcuts
Func LoadDrivers()
SetSplashText("Loading additional drivers...")
RunProgramWait(@SystemDir & "\Drvload.exe %WinDir%\inf\basicdisplay.inf", "", @SW_HIDE)
RunProgram(@SystemDir & "\pnputil.exe", "/add-driver %WinDir%\inf\hdaudio.inf /install", "", @SW_HIDE)
EndFunc ;==>LoadDrivers
Func RunPrograms()
SetSplashText("Running additional programs...")
RunProgramWait("Y:\Autorun.cmd", "", "", @SW_HIDE)
RunProgram("Y:\Programs\Sysinternals\procmon.exe")
EndFunc ;==>RunPrograms
Autoit3 Script using pure Autoit functions
#NoTrayIcon
; This is a user defined PhoenixPE configuration file.
; It will be executed during the PhoenixPE Pre-Shell config.
AutoItSetOption("ExpandEnvStrings", 1)
; Main
Config()
Shortcuts()
LoadDrivers()
RunPrograms()
SplashOff()
Func Config()
SplashTextOn("", "Additional configuration in progress...", 500, 50, -1, 600, 1)
RegWrite("HKEY_LOCAL_MACHINE\Software\Example", "Key1", "REG_SZ", "This is an example of RegWrite")
EndFunc ;==>Config
Func Shortcuts()
SplashTextOn("", "Creating additional shortcuts...", 500, 50, -1, 600, 1)
FileCreateShortcut("%WinDir%\myProgram.exe", @ProgramsCommonDir & "\MyProgram.lnk")
EndFunc ;==>Shortcuts
Func LoadDrivers()
SplashTextOn("", "Loading additional drivers...", 500, 50, -1, 600, 1)
RunWait(@SystemDir & "\Drvload.exe %WinDir%\inf\basicdisplay.inf", @SW_HIDE)
Run(@SystemDir & "\pnputil.exe", "/add-driver %WinDir%\inf\hdaudio.inf /install", "", @SW_HIDE)
EndFunc ;==>LoadDrivers
Func RunPrograms()
SplashTextOn("", "Running additional programs...", 500, 50, -1, 600, 1)
RunWait("Y:\Autorun.cmd", "", @SW_HIDE)
Run("Y:\Programs\Sysinternals\procmon.exe")
EndFunc ;==>RunPrograms
PECMD Script
// This is a user defined PECMD configuration file.
// It will be executed during the PhoenixPE Pre-Shell config.
CALL Config
CALL Shortcuts
CALL LoadDrivers
CALL RunPrograms
WAIT 3000
////////////////////////////////////////////////////////////////////////////////////////////////
_SUB Config
TEXT Additional configuration in progress...#0xFFFFFF L59 T39 $20
DISP W1024 H768 B32 F60
_END Config
////////////////////////////////////////////////////////////////////////////////////////////////
_SUB Shortcuts
TEXT Creating additional shortcuts...#0xFFFFFF L59 T39 $20
LINK %Programs%\Explorer,%WinDir%\myProgram.exe
_END Shortcuts
////////////////////////////////////////////////////////////////////////////////////////////////
_SUB LoadDrivers
TEXT Loading additional drivers...#0xFFFFFF L59 T39 $20
DEVI %WinDir%\inf\xxxxx.inf
_END LoadDrivers
////////////////////////////////////////////////////////////////////////////////////////////////
_SUB RunPrograms
// Syntax: EXEC <State><PathToExe> [WorkingDir]
// <State>: = - Wait
// @ - Background
// ! - Hide
// Example:
// EXEC =WaitNoHide.cmd - Execute WaitNoHide.cmd and wait until it is finished before continuing
// EXEC @!=WaitHide.cmd - Execute WaitHide.cmd, hide the window and wait until it is finished before continuing.
// EXEC NoWaitNoHide.cmd - Execute NoWaitNoHide.cmd and continue with the next command.
// EXEC @!NoWaitHide.cmd - Execute NoWaitHide.cmd, hide the window and continue with the next command.
TEXT Running additional programs...#0xFFFFFF L59 T39 $20
EXEC @!Y:\Autorun.cmd
EXEC Y:\Programs\Sysinternals\procmon.exe
_END RunPrograms
For more flexibility it is preferred to run AutoIt3 or PECMD scripts directly at different startup stages using the AddAutoRun command.
Example
// Autorun a PECMD script during PostConfig
AddAutoRun,PostShell,HideWait,"Running custom PECMD script...","myscript.wcs"
// Autorun an AutoIt3 script after network startup
AddAutoRun,AfterNetwork,HideWait,"Running custom script...",myscript.au3",
Prior to the PhoenixPE 2024-01-14 release, the pre-shell operations used PECMD, a command interpreter popular for use in WinPE environments written by Chinese developers Lxl1638(Li Shiting), Yonsm, and DSystem. It was formally open source, but has been closed source since 2012 when DSystem took over development. It worked well enough for simple tasks, but had a number of drawbacks, including arcane syntax, limited command set, poor documentation, and a number of undocumented "features" that kept popping up an causing some serious bugs and problems with newer versions of Windows. An alternative was needed in order to accelerate development of more advanced features and move PhoenixPE to the next level.
We did not want to go the route of trying to write a PECMD clone, or follow LiveSystemPro or older Win7PE_SE projects and use closed source custom loaders such as PEInit.exe or shortcuts.exe that limited options and required writing and learning new config files. We wanted something that didn't have to be compiled and was open and easy to use so project developers and advanced users could clearly see what was going on under the hood and further contribute to the WinPE community.
In the end it was decided to use the AutoIt3 scripting language. Autoit as a long history of use on the WinPE scene, is a full featured language with full access to the Win32 API, freely distributibtable, well documented, and has an active development forum. All these lend to an easy learning curve and rapid development.
The result is a fast, open, and efficient loader and tool set that should provide freedom and flexibility for years to come.