Skip to main content
Matrix42 Self-Service Help Center

Configure WinPE

This chapter provides "step by step" instructions for using Matrix42 OS Deployment - based on WinPE.

Generally, this variant of the deployment is based, on the one hand, on a WinPE-based PXE boot image that starts the Matrix42 Universal Agent Framework at boot time. The Matrix42 Universal Agent Framework then ensures that the booting computer connects to the assigned Empirum Server and executes the assigned Matrix42 PreOS packages. For the connection to the Empirum Server, the specifications in the selected agent template are used.

The WindowsInstallation package is one of these Matrix42 PreOS packages and contains the functionality to perform a Windows installation. It includes additional variable definitions that control the installation behavior. The WindowsInstallation package relies on the DiskPartitioning package, which must be run before the WindowsInstallation package. In addition, the PxeOffAndReboot, DomainJoin, and EmpirumAgentSetup packages must be run after the WindowsInstallation package.

The Matrix42 PreOS packages can be imported via the depot configuration of the Matrix42 Management Console and are then available as a special software package in Empirum. This allows you to assign the Matrix42 PreOS packages to a computer via the administration as usual, which then executes them during a WinPE boot.


Integrate current WinPE PreBoot version

  1. Download the latest WinPE PreBoot version from the Matrix42 Marketplace.
  2. Log in to the Matrix42 Empirum Master Server with an administrative account and copy the archive to a local folder (Temp) on the Empirum Master Server.
  3. Run the file WinPE_PreBoot_Support_x.x.x.exe (Run as administrator if UAC is enabled). The archive unpacks to the Empirum folder in the same directory.
  4. Move (cut) the Empirum folder to the location where your Empirum installation is located, e.g. to D:\ if your Empirum installation is located in D:\Empirum. Confirm the folder merge with Yes and Move and Replace all requested files.


Import PreOS packages

A Matrix42 PreOS package can be imported like a software package via the Matrix42 Management Console and is then available in Empirum.

Old or unneeded PreOS packages should be deleted from the EMC and locally from the hard disk.
Here, regularly check the existing PreOS packages in the Matrix42 Management Console (EMC) in the Configuration > Software Management > Depot > Matrix42 PreOS Packages tab and delete all unneeded or obsolete PreOS packages.
Locally, you can then delete the PreOS packages of the same name from the hard disk in the directory"%EmpirumServer%\Configurator$\PackageStore\PreOSPackages".

  1. Start the Matrix42 Management Console (EMC), go to Configuration > Software Management > Depot in the navigation bar.
  2. In the tree view, expand Register, right-click Matrix42 PreOS Packages and select Import/Export > Import Package.
    The dialog for importing software packages opens.
  3. Click Next.
  4. Click the directory button and select the \\%EmpirumServer%\Configurator$\PackageStore\PreOsPackages directory.

Do not select the Delete packages from directory after successful import option to keep the Matrix42 PreOS packages in the source directory.

  1. Click Next.
  2. The Import Wizard displays all detected OS software packages. Select the latest packages from the list for DiskPartitioning, DomainJoin, DriverIntegration, EmpirumAgentSetup, LanguageInstallation, PxeOffAndReboot and WindowsInstallation.
  3. Click Next.

If the Matrix42 PreOS package already exists, the Import Wizard will ask if the package should be imported anyway. If the import is performed, an error will occur.


  1. The Import Wizard shows a summary of which packages will be imported afterwards. Click Done to complete the import.
  2. After the successful import, the Import Wizard closes and the previously selected packages are displayed in the Matrix42 PreOS Packages tab.
    This is also the order in which the packages are executed later in the boot process. 

Matrix42 PreOS packages are always imported into the register specified in the configuration file (EmpirumPackageData.xml) of the package. This behavior is different from the behavior when importing software packages. If one starts there the import over a special register (for example software), then the software packages which can be imported are stored also in this register.
If no Matrix42 PreOS packages are available yet, the order of the packages is set based on the specification in the configuration file (EmpirumPackageData.xml) .
If a version of a Matrix42 PreOS package already exists, then its position in the register is first determined during the import and transferred to the new package to be imported. The new version of the package is then displayed directly below the already existing version.

It is very helpful if you first configure the required PreOS packages for the respective action via Configuration > View Designer. Afterwards, these can simply be assigned to a group via drag & drop.


Description of the PreOS packages

The description of the individual PreOS packages is in alphabetical order.


A detailed description of this PreOS package can be found here.


This PreOS package can be used to create an image from the hard disk of a computer that can be used as a master image for disk imaging. For configuration the collection of computer variables 'M42_INTERNAL_OS_IMAGING_CREATION' must be used.

Variable Description Control element Default value
USERNAME User used to access the network share (e.g. domain/user). Text  
PASSWORD Password for the USERNAME variable to access the network share. Password  
SHARE UNC path to the network share to store the VHD file (e.g. \\\EmpInst$). Also used to open the network connection for the first time. Text  
SOURCE Source of VHD contents.
  • Disk:<number> e.g. Disk:0 (default if empty and recommended value).
  • Volumes: <drive letter>; e.g. Volume: c, d (both volumes must be on the same disk).
DESTINATION The VHD file path (e.g. \\\EmpInst$\DiskImages\Win_10_20H2-12_ENT_x64_EN_GPT.vhd). The VHD files must be placed in the DiskImages folder! Text  

This option is currently not used for WinPE!

Option to enable SysPrep mode for the Empirum VHD Create package.

  • Yes: Necessary to prepare the image for distribution via disk imaging.
  • No: Only one VHD file is created from one client.
Extended Dropdown box  

For the later rollout, make sure that the user used has access to the target path and that the path specified under DESTINATION (including all subdirectories) is actually created.


This PreOS package can be used to install a disk image (a VHD created by DiskImageCreate) on a computer's hard disk. The target disk must be the same size or larger than the source disk image. Check both the PXE log and the disk image log (if present) to ensure that the disk image installation was successful. 

For configuration, the collection of computer variables 'M42_INTERNAL_OS_IMAGING_SETTINGS' must be used. The client configuration is supported by the DiskImageDeploy package variables. 

Variable definitions of M42_INTERNAL_OS_IMAGING_SETTINGS:

Variable Description Control element Default value
IMAGEFILE_MBR Name of the VHD file used for disk imaging with an MBR-based partition scheme (e.g. Test_MBR.vhd without path; the root path for images is \%EmpirumServer%\EmpInst$\DiskImages\). Text  
IMAGEFILE_GPT Name of the VHD file used for disk imaging with a GPT-based partition scheme (e.g. Test_GPT.vhd without path; the root path for images is \%EmpirumServer%\EmpInst$\DiskImages\). Text  
ADDRESS The IP multicast address (IPv4) to use.
  • Default value:
  • Multicast IP range: to
IP address
PORT Defines the original port of the communication channel.
  • Default value: 9000
  • Port range: 1 to 65536
Number 9000
CLIENTTHRESHOLD This variable is the trigger between unicast (0) and multicast (> 0). Number of clients needed for the transmission.
  • For unicast, the threshold must be set to 0.
  • For multicast, the threshold must be set to greater than 0.
Number 0
STARTTIMEOUT Defines the timeout until the multicast transfer starts, even if the maximum number of clients has not yet been reached.
  • Default value (s): 300
  • Min (s): 60
Number 300
JOINTIMEOUT Time period to wait after the client threshold has been reached to allow additional clients to join the group.
  • Default value (s): 180
  • Min (s): 10
Number 180
TTL "Time to live", i.e. validity period of the multicast packet. Defines the maximum number of router hops (intermediate stations).
  • Default value: 2
  • Min: 1
  • Max: 255
Number 2
CLIENTTIMEOUT Waiting time in seconds until an unresponsive client is removed from the server.
  • Default value (s): 120
  • Min (s): 30
Number 120
PACKAGESIZE Size of the transmitted multicast packet.
  • Default value: 65200
  • Min: 512
  • Max: 65200
Number 65200
PAGESIZE Number of multicast packets per page (packet count).
  • Default value: 1024
  • Min: 64
  • Max: 65536
Number 1024
DISKIMAGING_PASSWORD Variable to open the shell (Ctrl+O) on the client during the WinPE disk imaging phase for troubleshooting. Password  

Variable definitions from the DiskImageDeploy package:

Variable Description Control element Default value
LocalUserName Defines the name of the local account to be created. Text LocalAdmin
LocalUserPassword Defines the password of the local account to be created. Password  
LocalUserDisplayName Defines the display name of the local account to be created. Text Local Admin
SetupUILanguage Defines the language to be used in Windows Setup and Windows Deployment Services (e.g. en-US). Combo box en-US
InputLocale Specifies the input language and input method for input devices, such as keyboard layout (e.g. en-US). Combo box en-US
SystemLocale Specifies the default language to be used for non-Unicode programs (e.g. en-US). Combo box en-US
UILanguage Specifies the language to install, which is used as the default system language for displaying user interface (UI) elements (such as menus, dialog boxes, and help files) (for example, en-US). Combo box en-US
UserLocale Specifies the settings per user used for formatting date, time, currency and numbers in a Windows installation (e.g. en-US). Combo box en-US


The DiskPartitioning package is responsible for partitioning the hard disk. The configuration of the partitioning is controlled by the package variables.

Running the DiskPartitioning package switches the package status of all previously installed packages to YELLOW, even if they were GREEN shortly before. Since a complete deletion of the hard disk takes place here, the previously determined status can now no longer be correct.

Two variants (absolute / fixed or relative / percentage partitioning) are available for partitioning, which is controlled by the DiskPartitioning.InterpretSizeInputAsPercentage variable. If the value is set to 1, then the specifications in DiskPartitioning.SizeDataPartition, DiskPartitioning.SizeSystemPartition are interpreted as percentage specifications.

Variable Description Control element Default value

The value entered here specifies the partition size of the system partition in gigabytes for an absolute / fixed partitioning variant.

If the value of the variable InterpretSizeInputAsPercentage = 1 a partition is created over the entire disk (100%), if the value = 0 a partition with 100 GB size is created.

Number 100
SizeDataPartition Specifies the partition size of the data partition in gigabytes for an absolute / fixed partitioning variant. If the specification is relative / percentage, SizeSystemPartition must be less than 100%. Number 0

If relative / percentage specifications are to be used for partitioning, the value must = 1.
For absolute / fixed partitioning in gigabytes (GB), the value must be = 0.

The DiskPartitioning package will abort with an error if the disk is too small to create the absolute partition sizes.

Number 1
MinimumSystemPartitionSizeInGB If a relative / percentage partitioning method (InterpretSizeInputAsPercentage=1) has been selected, this variable can be used to specify a minimum system partition size which will not be undercut during partitioning. Number  
SizeWinREPartitionInMB If a Windows recovery partition is also to be created during partitioning, the size can be defined via this variable in MB. If the value of the variable is empty or 0, no Windows recovery partition is created. The default size is 350 MB. Number 300
PreferFastDisk Often there are several hard disk drives of different designs in the client. In most cases, one would prefer to install the operating system on the fastest hard disk drive.
The DiskPartitioning package offers the possibility to define the preferred installation target drive via this variable in advance, based on the storage technology of the drive.
If this variable is set to 1, the DiskPartitioning package will search for the first (according to BIOS) NVME disk and will prepare it for the operating system installation.
Number 0
SizeEfiPartitionInMB This variable defines the size of the EFI partition to be created in MB in EFI-based client scenarios.
By default, this is created with 100 MB. It may also be defined larger, but not smaller, for EFI-based recordings.
For older MBR-based client scenarios, this variable is ignored.
Number 100
SizeMsrPartitionInMB This variable defines in EFI-based client scenarios the size in MB of the "Microsoft Reserved Partition" to be created.
By default, this is created with 128 MB. It may also be defined larger, but not smaller, for EFI-based recordings.
For older MBR-based client scenarios, this variable is ignored.
Number 128
PreserveDataPartition In WinPE-based deployment, the entire disk is erased beforehand by default. This behavior is preconfigured via the value = 0.
The WinPE-based deployment can also create a data partition on the system disk.
This is usually deleted when reloading.
If an Empirum-compliant system disk
(a system partition with the name "Windows" and exactly one data partition with the name "Data") should remain untouched during the reinstallation, this can be set with the value = 1.
If you want to leave one or more non-Empirum-compliant data partitions on a system disk untouched during a installation or reinstallation, you can configure this with the value = 2.
Number 0

You can use this variable to specify a configuration file that is used to partition a data disk (in addition to the system disk). Exactly one additional disk with up to four partitions and the file system NTFS is supported. Percentage partitioning can also be performed with less than 100% in total, absolute partition sizes, however, must match the complete target disk exactly to 1GB.
The storage location is the directory Empirum\Configurator\Packages\Matrix42\OsPackages\DiskConfigurations
In this directory there is a template named AdditionalDiskConfig.json.ref from which you can create your own JSON configuration. Currently supported features are:

Feature Value range Description
PartitionSizeAsPercentage  true / false Percentage partitioning (true / default), or absolute partitioning via GB specification (false)
PreserveMode 0,1 Always erase disk (0 / default), or do not erase if target state / reinstall already exists (1)
PartitionSize [%],[GB] Values in percent or GB. GB values must have a precision of 1 GB.
PartitionLabel [String] Partition-Label / Volume-Name of the Partition
ClearAllDisks Via this variable, which you have to add yourself, you can clean up all disks when running the DiskPartitioning package.
For this you have to add the variable "ClearAllDisks" as a number to DiskPartitioning in the EMC > Administration under "Tools > Variable definitions" and set it to 1.
ForceUEFI Via this variable, which you have to add yourself, a UEFI based installation of the client with a GPT based partitioning is forced, independent of how the client was booted.
For this you have to add the variable "ForceUEFI" as a number to DiskPartitioning in the EMC > Administration under "Tools > Variable definitions" and set it to 1.

Example of a variable configuration:

Example of a configuration file with a percentage partitioning with two partitions named Data2-1, Data2-2 and a total of 66% disk space usage:

  "Disks": [
      "Comment_Disks": "----------- 1. Additional Disk -----------",
      "Comment_PartitionSizeAsPercentage": [
        "PartitionSizeAsPercentage specifies if the partition size values should be interpreted as percentage values or GB values:",
        "- true: Interprets the partition size values as percent values",
        "- false: Interprets the partition size values as GB values"
      "PartitionSizeAsPercentage": true,
      "Comment_PreserveMode": [
        "The PreserveMode value specifies the handling of already existing partitions:",
        "- 0: All partitions will always be removed and recreated",
        "- 1: The partition will be keeped if it was made by empirum (or will be created if not exists).",
        "     Partition sizes and labels must match the configuration to be retained."
      "PreserveMode": 0,
      "Comment_Partitions": "The list of all partitions of the first disk",
      "Partitions": [
          "Comment_Partitions": "----------- 1. Partition -----------",          
          "Comment_PartitionSize": "Partition size in GB value or percentage",
          "PartitionSize": 33,
          "Comment_PartitionLabel": "Label of the partition",
          "PartitionLabel": "Data2-1"
          "Comment_Partitions": "----------- 2. Partition -----------",          
          "PartitionSize": 33,
          "PartitionLabel": "Data2-2"


This PreOS package is used to add a computer to a domain or workgroup. If the domain is not selected, then even if the Matrix42 PreOS package DomainJoin is assigned, no domain join is performed and the computer is added to the specified workgroup.

The FQDN and ORGANIZATIONAL_UNIT (OU) variables, which can be configured via the computer properties dialog, are used by this package.
If a computer is configured for a domain, then make sure that the FQDN value is set in the properties of the computer (here in the properties of the computer or via the FQDN variable). This value must be specified for the domain join.

If Windows updates or ISO images were used for operating system installation after October 11, 2022, the changes introduced by Microsoft through KB5020276 for a domain join take effect. As of the DomainJoin package 1.12, there is a variable "DisableLegacyDomainJoin" for this purpose to prevent the deprecated domain join if this is set to 1.

The following packages are required for this:
1. WindowsInstallation (to provide the operating system)
2. PxeOffAndReboot (to send a PXE off message to the Empirum server and restart the client after the operating system installation)

Variable definitions

Variable Description Control element Default value
DomainJoinCredentialsUser Name with domain of the domain user to be used. Text  
DomainJoinCredentialsPassword Password of the user to be used. Password  

Error handling during the login process.

In case of an error during the logon process to another OU, a warning message is issued in the log that the client could not be logged on to the specified OU. The installation process continues if possible.

If an error occurs during the process of logging into another OU, an error message is displayed in the log and the installation process is aborted.

Extended Dropdown box Error
DomainJoinAuthority Defines whether the AD or Empirum governs the login process. Only if Empirum is selected here, an already existing client can be moved to another OU. Extended Dropdown box AD
DomainJoinOptionFlags Defines a custom NETSETUP OptionFlag bitmask with which the join process can be executed before or instead of the Empirum DomainJoin. Allowed here are empty values (default), decimal values, or hexadecimal values in the format "0x0000". Further information:
DomainJoinOptionFlagsOnly If DomainJoinOptionFlags is defined, the value DomainJoinOptionFlagsOnly can be used to determine whether a DomainJoin should only be executed via OptionFlags (value "1") or whether a standard Empirum Domainjoin should still be executed in case of failure (value "0" or empty). Number  
DisableLegacyDomainJoin Due to the KB5020276 introduced by Microsoft, the obsolete domain join (0 or empty) or the new domain join (1) can still be used here. Default is empty (not equal to 1).    

The function "Move to another OU" is only available from the OS installation of Windows 10 from build version 1809!


The DriverIntegration package provides the contents of the assigned driver archive/folder on a hard disk prepared for this step by the DiskPartitioning package. The following WindowsInstallation package then uses these prepared files for the device driver installation during the operating system installation. Therefore, the DriverIntegration package depends on the DiskPartitioning package.

On the other hand, the WindowsInstallation package can be used without the DriverIntegration package - if no additional device drivers are needed for the operating system installation.

For driver integration, the required drivers must be available as an archive (CAB or ZIP file) or as a folder structure. These files must be located on the server under  \\%EmpirumServer%\Configurator$\Packages\Matrix42\OsPackages\Drivers\. If there is no Drivers folder, it must be created first.

Starting with WinPE PreBoot Support 1.8.16, drivers in EXE format from Dell can also be integrated. Please note that these driver files are up to 4 GB in size - the RAM on the computer on which this driver package is to be installed must be correspondingly large (8 GB).
EXE files from other manufacturers can also be integrated.
For this, the variable "ExeUnpackOptions" must be added to the variable set "DriverIntegration" as control element "Text" under "Variable definitions".
For Dell, the following call for unpacking (in the PowerShell script) was integrated: /s /e=%targetpath%.
For another manufacturer, the call parameters can vary, but the target path where the driver package is unpacked must always be %targetpath%!
Files in EXE format can only be integrated by one manufacturer - so either Dell, or Lenovo, or HP!

More information can be found in the WinPE Driver Integration - HowTo.


The EmpirumAgentSetup package is executed to install the Empirum Agent on the client.

The M42_AGENT_PUSH_PACKAGE_FOLDER.Windows variable is used to specify the version and variant (Matrix42 Advanced Agent or Matrix42 UEM Agent) of the Empirum agent.

The value of this variable is a relative path to the desired agent directory starting with the folder located at "Configurator$\Packages\Matrix42\". For example:

  • UEM Agent Windows\2103.1.2
  • EmpirumAgent\19.0

From packages EmpirumAgentSetup 2.2 and higher determines and uses the latest Matrix42 UEM Agent version released for installation if no value is set.
Older versions of EmpirumAgentSetup use the Matrix42 Advanced Agent EmpirumAgent\19.0 by default.


This PreOS package can be used to wipe all disks of a client in an EndOfLife scenario. After the client is executed, the management state of the Empirum client is reset. The variables of this package can be used to configure the EndOfLife process.

For the three variables "RemoveFromADUser", "RemoveFromADPassword" and "RemoveFromADDC" the RSAT tool is required. This tool can be used to delete a computer from the AD at the runtime of EndOfLife - independently of Empirum-LDAPSync. For this, the value for the variable "RemoveFromAD" must also be set to "1".
More information on how to integrate the tool can be obtained from Matrix42 Support.
To remove an AD object, you need the rights:

  • DELETE access to the object itself
  • ADS_RIGHT_DS_DELETE_CHILD access to this object type in the parent container.

Information about this is described by Microsoft here.

Variable Description Control element Default value
ActivateEndOfLife Set the value to 1 if you want to activate EndOfLife (confirmation prompt). Number 0
RemoveFromEmpirum After EndOfLife, the client is removed from Empirum (1), or remains present (0). Number 1
RemoveFromAD Set this value to 1 if you want to remove the client from AD after EOL. If the value is 0, the client remains in AD. Also applies to deletion via RSAT. Number 0
GBytesWrite Specifies the size of randomized data on each disk in GB - set the value to 0 to overwrite the entire disk. Number 10
NVMEFallback Set this value to 0 if no recourse to sector based erasure should be made in case of NVME format errors. Number 1
EraseMethod Deletion method: Empirum , DoD5220.22M or BSI/VSITR Extended Dropdown Empirum
RemoveFromADUser "RSAT Required: Specifies the domain user (for example, Domain\username) that has permission to perform a RemoveFromAD operation. Text  
RemoveFromADPassword "RSAT required": Defines the password to be used for a "RemoveFromAD" operation. Password  
RemoveFromADDC "RSAT Required: Specifies the name of the AD domain controller (Full Qualified Name) on which to perform the RemoveFromAD operation. Text  


This PreOS package is a sample package that starts the hardware tool to collect information about all devices on a client to provide in the client's log.


This PreOS package can be used to install Windows language packages (Local Experience Pack or the CAB file format) and to set the display language configured in the WindowsInstallation package variable UILanguage.

Smooth operation of LXP's is supported with Empirum v20.0.
Local Experience Packs (LXP/APPX language pack formats) are only supported from Windows 10 version 1809 upwards. Only installations with an English (EN-US) base system are supported. All other base languages are only supported experimentally. The UILanguage/desktop language can be set user-specifically via the Windows "Regions and Language" dialog.
Known issues from Microsoft to LXP's: Language packs known issue | Microsoft Docs 


This PreOS package is a simple sample package that turns off PXE activation on a computer and sets the status of the currently running PreOS package to Reboot Needed Immediately.


TThis PreOS package is required for deploying a Windows 10, Server 2016 / 2019, or Windows 7 based operating system (x64 only in each case) on a client.

The following packages are required for this:

  1. DiskPartitioning (for partitioning the hard disk of the client)
  2. DriverIntegration (to add drivers for the operating system)

   - and after Windows installation -

  1. PxeOffAndReboot (to turn off PXE and restart the installed operating system)
  2. DomainJoin (to add a computer to a domain)
  3. EmpirumAgentSetup (to install an Empirum agent)

The execution order of these packages is important and must be ensured.

Variables definitions

When deploying server operating systems, the server name must be included when specifying local users, e.g. "%ServerName%\LocalUser". Do NOT use ".\LocalUser"!

Variable Description Control element Default value
ForceDotNetInstallation Forces the installation of .Net 4.7 (e.g. necessary on Windows 10 2016 LTSB). Extended Dropdown box No
LocalUserName Defines the name of the local account to be created. Text LocalAdmin
LocalUserPassword Defines the password of the local account to be created. Password  
LocalUserDisplayName Defines the display name of the local account to be created. Text Local Admin
SetupUILanguage Defines the language to be used in Windows Setup and Windows Deployment Services (e.g. en-US). Combo-Box en-US
InputLocale Specifies the input language and input method for input devices, such as keyboard layout (e.g. en-US). Combo-Box en-US
SystemLocale Specifies the default language to be used for non-Unicode programs (e.g. en-US). Combo-Box en-US
UILanguage Specifies the language to install, which is used as the default system language for displaying user interface (UI) elements (such as menus, dialog boxes, and help files) (for example, en-US). Combo-Box en-US
UserLocale Specifies the settings per user used for formatting date, time, currency and numbers in a Windows installation (e.g. en-US). Combo-Box en-US
ProductKey Specifies the product key to be used for Windows installation. Text  
UnattendXmlFile Specifies a path to an unattend.xml file to be used as template (e.g. 'Sys\unattend.xml'; in this case '\\%EmpirumServer%\EmpInst$\Sys\unattend.xml' will be used). If empty, the default template that is part of the PreOS package will be used. Text  
ActivationNow Immediate Windows activation after installation is performed. Number  
ActivationKey A special Windows activation key used after client installation. For example, MAK activation. Password  
UACLevel Defines the UAC level of the Windows client. Extended Dropdown box Notify, dim desktop
BuiltinAdministratorActive Specifies whether the built-in account should be active for managing the computer. Matrix42 suggests the use of LAPS for managing local Administrator passwords. Extended Dropdown box No
BuiltinAdministratorPassword Defines the password of the integrated account for managing the computer.  Password  

Miscellaneous variables

For a successful operating system installation, the following variables must also be configured.

Variable Description Control element Default value
MX42_AGENT_PUSH_PACKAGE_FOLDER Allows you to specify alternative operating system-specific package directories for the Agent Push. The specified path must be below and relative to the Empirum package path "Packages\Matrix42".
This specification allows you to specify a particular UEM Agent version for installation after the operating system installation.
Example: UEM Agent Windows\2103.1.2
FQDN Fully qualified domain name. It does not contain a computer name.


Import operating system sources and language packages

Before the Windows operating system (ISO) files can be imported, the Windows Assessment and Deployment Kit (WADK) 10 (2004 or newer) must be installed on the (master) server. 

The procedure for importing operating system files is described here.
The procedure for importing language packages is described here.


Create boot configuration

Boot configurations can be used to create a WinPE based PXE boot image based on the Windows ADK installed on the Empirum Master Server.

To use WinPE, an actual .NET and an actual Power Shell version (minimum 5.1) is needed!

Note: We recommend to use WADK 11 on building maschine with Windows 11 or Server 2022 and we recommend to use WADK 10 on building maschine with Windows 7/ 10 or Server 2016/ 2019!

  1. Switch to Configuration > Boot Configurations.

To be able to create or change a boot configuration, the logged in user needs the role EMP_I_DISK_CONFIG, which can be assigned via Matrix42 DBUtil in the user administration. If the logged in user does not have the role, the content of the boot configuration is grayed out.

Create a new boot configuration using the New button.
Symbol definition:

  • WinPE_Drv_Warning.gif One or more critical details are missing or incorrect.
  • WinPE_Save.gif Information or data has been changed but not yet saved.
  • WinPE_Queue.gif The job is in the queue.
  • WinPE_Create.gif The boot configuration is being created in the background.
  • WinPE_Successful.gif The boot configuration was successfully created.
  • WinPE_Error.gif An error occurred while creating the boot configuration.
  • WinPE_Refresh.gif The configuration has been changed in the background and can no longer be saved. A refresh is necessary to load the changes.
  • WinPE_Deleted.gif The boot configuration was deleted in the background and can no longer be saved. A refresh is required to remove the configuration from the list.
  1. Enter a descriptive name and description according to your requirements.

Only alphanumeric characters (a-z, A-Z and 0-9) are allowed for the name.
Names must be unique. The use of reserved names is prevented.
This includes names that are already used in the boot diskette configuration (EPE).
The WinPE_Drv_Warning.gif symbol indicates that the entry is not allowed.

  1. Select WinPE as the configuration type to create a WinPE-based PXE boot image-if not already selected.

If you select WinPE as the configuration type, the selection of the Empirum PE source and the dynamic server detection are hidden and are not available in the configuration. These properties are only available under the EPE4 configuration and are not necessary in the case of a WinPE Preinstallation Environment. By default, WinPE is selected for new configurations.

  1. Select the desired agent template from the Agent Template drop-down box.
    If at least one agent template is configured, it will be entered directly. If several Empirum agent templates have been created, the first one is always displayed directly, sorted alphabetically.
  2. To select which platforms are to be supported, you must check either EFI x86 or EFI x64 or select one of the platforms from the BIOS drop-down box. Multiple platforms can be selected at the same time. For BIOS, however, only one of the platforms can be selected at a time - either 32 bit or 64 bit. To create a configuration, at least one of the platforms must be selected. EFI x64 (64 bit) is selected as the default.

The entries in the selected agent template determine how and with which server it will attempt to connect during OS deployment.
If no entry is displayed in the selection under Agent Template, first create an Empirum Agent Template via Configuration > Software Management > Empirum Agent.
In addition to the user name, password and server name, the settings for the DHCP options are also transferred to the PXE boot image, provided it has been configured in the agent template. Afterwards, the selection can be updated via the Refresh WinPE_Refresh_all.gif button. The overview on the left is updated in real time. However, changes WinPE_Save.gif are only permanently applied after confirming with Save.

  1. Advanced Properties allows you to set the TFTP Block Size, Self Provisioning and Driver Directories. Click the button WinPE_HowTo_355_Advanced_Properties.png to show the fields.
    The TFTP block size setting can be used to adjust the transfer of the WinPE boot image to make it either more stable or faster.

A higher TFTP block size value usually results in faster transmission of the boot image. However, a larger block size can also lead to transmission interruptions. An optimal value depends on the existing network infrastructure and its load. For a newly created boot configuration, the default TFTP block size value is 4 KB.

Self Provisioning is described in detail here.

  1. To include additional drivers into the WinPE boot image, click the button WinPE_Add.gif below the list of additional driver folders.
    The Browse for Folder window will open, allowing you to select a directory.
  2. Confirm the selection with OK.
    The selected directory will be added to the list of additional driver folders.
  3. If several drivers have to be integrated, repeat the procedure from point 8.
    If you want to remove a driver directory, then click on the button WinPE_Deleted.gif to the right of the driver directory entry.
  4. After all settings have been made, confirm with Save and answer the security question with Yes.
    The configuration is saved in the database, the PXE boot image is created directly.

After saving the Empirum Preinstallation Environment configuration, the automatic creation of the PXE image is taken over by the Backend Task Queue extension.
After the PXE boot image has been successfully created, it is displayed with the specified name in Management > Administration under PXE-BootImages and can be assigned as usual using drag & drop.

Back-end tasks

Back-end Task Queue

The current jobs in the Backend Task Queue can be checked using the following dialog in the Matrix42 Management Console (EMC):

  • Matrix42 Management Console > Management > Administration > Info menu > Info > Back-end Tasks

The queue entries named PE (= Preinstallation Environment) are the jobs of interest for creating the PXE image.
The list shows which jobs are currently being processed by the queue.

The BTQH service must run under a user who has administrative rights.

Back-end Task Log

In the Back-end Task log tab, the status of the jobs that have already been processed can be viewed.
The Result column shows the success of the order. In case of failure, the Note column contains detailed information about the error.

Detailed information can also be obtained from the backend task queue log file - located at: 


Create variables configuration

To simplify the initial configuration, you can download a set of variable configurations for the OS Installer from the Matrix42 Marketplace (Add-ons button) and customize them for your environment. For this example, we use the variable configuration "1_v20.0.0__OS-Install.xml" or "1_v20.0.3__OS-Install.xml" from this package.

  1. Download the variable configuration package here and unpack it into a directory (e.g. Temp) on the Empirum Master Server.
  2. In the Matrix42 Management Console, go to Configuration > Variable Configurations and click the Import button at the bottom right.
  3. Change to the directory (Temp) where you have unpacked the variable configuration package. Select the template "1_v20.0.x__OS-Install.xml" and click Open.
  4. Confirm the successful import with OK.
  5. description which variables have to be adapted by you for your environment can be found here. In this case, this only concerns the variables of the Configuration OS Install variable. A description of the variables used can be found here: DiskPartitioning | DomainJoin | MX42_AGENT_PUSH_PACKAGE_FOLDER / FQDNOS_RegionalSettingsWindowsInstallation
  6. After all variables of the variable configuration OS-Install have been checked by you, adjusted to your environment, click Save in the bottom right corner.

After saving, this variable configuration is displayed in Management > Administration under Variable Configurations and can now be assigned via drag & drop. On the configuration side, all preparatory measures are now complete.


Create configuration group

In order for a computer to run the OS deployment via WinPE, the settings in the administration still have to be made.

  1. In the Matrix42 Management Console, go to Management > Administration.
  2. Create a new configuration group.
  3. If you have created a view for the Matrix42 PreOS packages, drag them now to the newly created configuration group.
    Otherwise, under Software Packages > Matrix42 PreOS Packages, drag the Matrix42 PreOS packages
     - DiskPartitioning,
     - WindowsInstallation,
     - PxeOffAndReboot,
     - DomainJoin,
     - EmpirumAgentSetup
    to the configuration group.
    When using language package imports, the LanguageInstallation package must also be assigned.
    If additional drivers are to be integrated into the operating system, the DriverIntegration package must also be assigned.
    The Matrix42 PreOS package HardwareInfo is only required if you also want to read out the hardware information for the assigned client (log).
  4. In the tree on the right, under Software Packages > Matrix42, drag the current Matrix42 UEM Agent Windows software package onto the configuration group.
  5. On the right side of the tree, drag the variable configuration (OS Install) imported under Variable Configurations onto the newly created configuration group.
  6. On the right side of the tree, drag the desired edition of the operating system under Operating System Imports > Microsoft > Windows 10 > x64 > "<your operating system import>" > e.g. Windows 10 Enterprise onto the configuration group.
  7. If language packs are required, drag the desired language pack(s) to the configuration group under Language Pack Imports on the right side of the tree.
  8. On the right side of the tree, drag the newly created WinPE boot image (WinPEx64) under PXE-BootImages onto the configuration group.
  9. In the tree on the right, under Agent Templates, drag the agent template you need for this configuration onto the configuration group.
  10. On the left side of the tree, under Unassigned Computers, drag a computer onto the configuration group
    The configuration group you created will look something like this:

In general, it is possible to assign multiple Matrix42 PreOS packages, which are then executed one after the other when the WinPE-based PXE image is booted.
The execution order of these packages can be controlled globally via the order of the packages in the depot, as with other software packages.

In the properties of the assigned virtual client, the options marked in yellow must be specified! Either the UUID and/or the MAC address must be specified.
    Once all assignments have been made, the computer can be activated via the context menu.

  1. Right-click on the configuration group and select Activate. In the Activation Wizard that opens, enable the PULL via DDS/DDC (Software packages only) and Enable PXE (Reinstall Computer) options. Click Next. Click Finish.
  2. Start the assigned virtual client - the operating system is installed via the WinPE boot image.
    When the assigned WinPE boot image is started on the computer, the Matrix42 Universal Agent Framework starts automatically, executing the assigned packages one by one.

In the current version, manual intervention in the execution of the Matrix42 Universal Agent Framework is possible.
This is to enable you to analyze the processes as easily as possible and to be able to correct them if necessary.
A manual intervention can lead to an abort of the installation if necessary!

Starting with WinPE support package 1.8.13, all PreOS packages in the WinPE phase are restarted if a package runs into an error. The behavior can be changed manually (see FAQ).

If you want to customize the WinPE boot configuration and e.g. change the background image or texts, you can find instructions here .

When the WindowsInstallation package is executed, the Windows installation is also executed.
After going through the various installation phases, the operating system is installed on the computer.



During the operating system installation with these packages, several reboots take place. The operating system is executed several times during this process. During this, the PE agent executes the associated packages: LanguageInstallation, DomainJoin and EmpirumAgentSetup. The PE agent itself is installed with the first boot of Windows in the phase of the first log-on and removes itself after successful execution of all packages.

For a better understanding or to follow the installation, it is recommended to look into the PXE log (Matrix42 Management Console > Administration > right mouse click on the computer in the middle tree > Show Log > PXE Log tab) of the corresponding client.

Manual IP Configuration

Instead of using DHCP, a manual IP configuration can also be used for the operating system installation in the WinPE / Windows phase.
To do this, the IP configuration must be made in the client properties (EMC > Administration > Properties Computer > IP Address > Static) in the IP Address and DNS tab.
The values entered here are then entered in the <Computer name>.ini file in the [MS_TCPIP] section.


  • Was this article helpful?