FAQ

Question:  I assigned the SimpleOsDeployment package (or any other package) after the successful import and variable declaration, and activated the client, but the package does not start and the operating system is not installed.

Answer: Make sure that the SimpleOsDeployment package (or any other package) has also been released for installation.

Question: The client seems to have errors running and restarts all the time. How can I prevent it from restarting so I can see what is failing?

Answer: The client runs the PE agent, which executes the PreOS packages. In case of an error, a reboot is always performed, so that a faulty package is always reloaded and the client always restarts. The PE agent has its own configuration file that can be used to disable rebooting to debug the problem (Matrix42.Empirum.PeAgent.dll.config). You have to set the switch "EnableReboot" to "False" to disable reboots. With the switches "DelayOnErrorInSeconds" and "DelayRebootInSeconds" you can also delay the execution in case of error or before restarts (specification in seconds).

A simpler variant is to use the Matrix42 PreOS package DebugPackage. The package must be assigned to the client, the client must be activated and rebooted. The DebugPackage package disables the reboot from the PE agent so that after execution (successful or failed) of the assigned packages the PE agent does not reboot the client.
The Matrix42 PreOS package DebugPackage requires a PE Agent version 1.3.0 or higher.

Question: When importing a Matrix42 PreOS package, the package does not end up in the tab from where I started the import. What can I do?

Answer: 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 you start the import via a special tab (e.g. Software), the imported software packages are also added to this tab. If you want to change the register where the Matrix42 PreOS package should end up, then changes to the EmpirumPackageData.xml file in the SoftwareDepotRegister XML node are necessary.

Question: The domain join no longer works with the new WindowsInstallation 4.0 package. What can I do?

Answer: As of version 4.0, the WindowsInstallation package no longer contains the functionality of the domain join. The domain join has been moved to a separate PreOS package called "DomainJoin", which must now be additionally assigned and configured. The advantage now is that the status of the domain join can be checked better. The status of the new Domain Join package is to give information about the status of the Domain Join.

Question: Domain Join fails: "2224 - The account already exists." What can I do?

Answer: The DomainJoin package is not designed to move a computer from an already assigned OU. That is, the computer was already assigned in an OU and it is different from the currently configured one. Either check the ORGANIZATIONAL_UNIT variable and make sure that the OU has been configured correctly or remove the computer from the OU in Active Directory (Domain Controller).

Question: The Empirum Agent is no longer installed after using the new WindowsInstallation 4.0 package. What can I do?

Answer: As of version 4.0, the WindowsInstallation package no longer contains the functionality that the Empirum Agent is installed. The installation of the Empirum Agent has been moved to a separate PreOS package called "EmpirumAgentSetup", which must now be additionally assigned and configured. The advantage now is that the status of the Empirum agent installation can be checked better. The new package also interprets the MX42_AGENT_PUSH_PACKAGE_FOLDER.Windows variable to determine which Empirum Agent version is to be installed.

Question: An error occurs when importing a Matrix42 PreOS package. What can I do?

Answer: Older versions of a package may contain incompatible variable definitions that cannot be updated during the import. First delete all older versions of the package, which will also delete the incompatible variable definitions, and try the import again. Please note that the variable values of this package must be reset.

Question: When trying to set up a computer via WinPE based deployment, the PXE boot of the WinPE image regularly aborts. Is there a way to stabilize the transfer?

Answer: The TFTP block size setting can be used in the boot configuration to try to make the transfer more stable. A small block size reduces the risk that the transfer of the individual blocks will be aborted and, however, usually results in a slower transfer of the image.

Question: When trying to determine the manufacturer and model of a computer via HardwareInfo package, I have the problem that the computer cannot connect to the Empirum server and therefore cannot run the HardwareInfo package. Is there a way to get the information without the HardwareInfo package?

Answer: Yes. Each WinPE image contains the DriverInfo.exe tool in the UAF directory, which can be run after booting on the computer even without a network connection. The tool gives information about the devices and their driver supply on the computer and writes the information to a log file DriverInfo.exe.log in the UAF directory. In the first lines of this log the manufacturer name and the model name are listed.

Question: When running Windows Setup through the WindowsInstallation package, I get an error that reads something like "unable to locate an existing system partition"! What can I do here?

Answer: If there are several hard disks on the device to be installed and there is already a Windows installation and another hard disk has now been selected as the system hard disk - for example by using the "PreferFastDisk" variable, then it can lead to problems when executing the Windows setup. You can either clean up all disks manually via DISKPART or via the hidden variable "ClearAllDisks" when executing the DiskPartitioning package. For this you have to add the variable "ClearAllDisks" as a number to the variable "DiskPartitioning" under "Tools > Variable definitions" in EMC and set it to 1.

Question: If the WinPE image creation fails and there is an error message in the log of the BTQH service that reads something like "Start Windows PowerShell with the "Run as administrator" option and try to run the script again". What can I do?

Answer: The user account under which the BTQH service runs needs administrative rights. It must be ensured that this user is a member of the administrators group.

Question: There is an error when creating a Computer Self Provisioning capable WinPE image. In the log of the BTQH service there is the error message "Error at validating Empirum API server settings". What can I do?

Answer: The error message indicates that the Empirum API service settings cannot be read. Make sure that the Empirum API service is configured and installed via Matrix42 DBUtil. Also make sure that the HTTP protocol is used, because only this variant is currently supported by Computer Self Provisioning.

Question: How can I customize the default language of the WinPE Self Provisioning user interface?

Answer: In the file "Matrix42SelfProvisioningUI.exe.config" under .\Empirum\EmpInst\Sys\Images\WinPE\binaries\UAF\ there is the value at the very bottom. 
<add key="DefaultLanguage" value="German"/>. This value can be set to the desired language "German / English / Francais".

Question: Can I manually extend the newly created WinPE USB stick with data?

Answer: Since WinPE version 1.6.5 and higher creates two partitions on the USB stick, the second NTFS partition can be manually filled with the data - operating system files, language packages and drivers - from the Empirum Share.

Question: In the boot configuration all controls are grayed out. You cannot create or change a boot configuration. What is the reason?

Answer: To create or change boot configurations, the logged-in user needs the EMP_I_DISK_CONFIG role. If he does not have it, the control elements are grayed out and he can only view the existing configurations. To be able to change the boot configuration, log in to the Matrix42 Management Console with another user or use the user management in Matrix42 DBUtil to assign the EMP_I_DISK_CONFIG role to the logged-in user.

Question: The operating system installation via HTTP(S) fails, error 403 is displayed. What can I do?

Answer: If this error message is displayed, the specified user does not have write permissions to directory structures in IIS.
See also WinPE via http(s).

Question: The operating system installation via HTTP(S) goes through without any problems, but there are several 404 errors in the Matrix42.Platform.Service.Host.log. What is the reason for this?

Answer: Currently, the 404 errors also appear in the log file of a successful recording. The reason for this is a generic approach to transferring directories and individual files. If a single file is to be transferred, it is first treated as a directory. The transport first tries to determine the contents of this directory. This leads to the error 404, because a corresponding directory does not exist. The error message is then as follows:
[Error] [JobProcessorBase.Execute] The remote server returned an error: (404) Not Found.

This error message is then followed by another warning:
[Warning] [HttpTransfer.RunGenerateList] Issue at running list job. Message: The remote server returned an error: (404) Not Found.

Subsequently, it is indicated that the transfer is now attempted with a single file:
[Information] [HttpTransfer.TransferFromServer] Could not list content of 'http://EmpirumServer.Matrix42.de/Mat...iceMapping.xml'. => Try to transfer single file.

This transfer is then carried out successfully.
[Information] [HttpTransfer.StartTransfer] Final status: 'Finished'

As of WinPE Support version 1.8.5, these error messages no longer occur.

Question: The operating system installation via HTTP(S) fails when transferring the DeviceMapping.xml. The network card is not yet responsive. Is there a way to configure the number of connection attempts?

Answer: The number of connection attempts can be set in the configuration file Matrix42.Empirum.PeAgent.dll.config of the PE Agent. The file is located in the EmpInst$\Sys\Images\WinPE\binaries\UAF directory.
The OpenConnectionRetries value specifies the number of connection attempts and is originally set at 10 attempts.

If the value in the Matrix42.Empirum.PeAgent.dll.config file is changed, the boot configuration used must be saved again afterwards so that the change is adopted in the PXE image.

Question: The operating system installation via HTTPS aborts with the error message "Thumbprint list is empty at Https case.". What is the reason and what can I do?

Answer: The PE agent has tried to establish a transfer via Https. In the agent template used, the option "Trust only trusted server certificates" is selected. Since the usual validation via the certificate store and certificate chains does not work under WinPE, the PE Agent will perform the validation using the defined certificate thumbprints. However, the list of thumbprints defined in the configuration file Matrix42.Empirum.PeAgent.dll.config (in the EmpInst$\Sys\Images\WinPE\binaries\UAF directory) of the PE Agent is empty. Thus, a secure connection could not be established.
WinPE via http(s) describes in more detail how to get the thumbprint information using IIS Manger and how to enter it into the configuration file. Afterwards, the boot configuration used must be saved again so that the change is applied to the PXE image.
If a check of the server thumbprint is not desired, then the option "Trust only trusted server certificates" must be deselected in the agent template used. A connection can then also be established without thumbprints.

Question: Why are all packages in the WinPE phase restarted when a single package runs into an error?

Answer: As of WinPE support package 1.8.13, all PreOS packages are generally restarted in the WinPE phase if an error occurs.
If this behavior is not desired, the entry "<add key="CompleteRestartAtError" value="True"/>" in the file
".\Empirum\EmpInst\Sys\Images\WinPE\binaries\UAF\Matrix42.Empirum.PeAgent.dll.config" can be set to "False".