Skip to main content
Matrix42 Self-Service Help Center

WinPE via HTTP(S)

  1. Last updated
  2. Save as PDF

Starting with WinPE preboot version 1.8.0, connection establishment via http(s) is supported. The following chapter describes the necessary adjustments and the current restrictions of the implementation.


Deployment via http(s) requires the use of the latest Matrix42 PreOS packages released with WinPE Preboot version 1.8.0 or later:

  • HardwareInfo 3.0 or higher
  • WindowsInstallation 5.0 or higher
  • EmpirumAgentSetup 2.0 or higher

Make sure that the boot configuration you are using is also created with the latest WinPE preboot version of 1.8.0 or later.

Current restrictions

With the current implementation, the following limitations must be considered:

  • Disk Imaging does not yet support http(s) transfer.
  • The timestamp of the SwDepot log entries for the PreOS packets may differ in the http(s) case.

http(s) support for self-created PreOS packages

It is possible that self-made PreOS packages are not immediately suitable for the http(s) transport. The reason for this is mostly that in the PowerShell scripts files or directories are accessed on the Empirum share in the SMB case that are not part of the PreOS package itself.

In order to facilitate the adjustments, certain peculiarities of the http(s) transfer will be discussed at this point.

  • Generally, local cache is used in the http(s) case. Files and directories are transferred from the Empirum share to local directories via http(s). Not all shares are transferred automatically, but only directories and files that are requested.
  • In the http(s) case, before the PreOS package is executed, the contents of the package (e.g. in the case of the WindowsInstallation PreOS package, the Configurator$\Packages\Matrix42\OsPackages\WindowsInstallation\5.6) is first transferred locally to a cache directory and then the install.ps1 script is executed locally. Relative accesses to files located in the package are thus covered.
  • If files need to be accessed in a PreOS package that are not present in the package directory, this must be done using the Get-EmpirumPackagePath . The method has been used in the past to get the path to the Empirum share (or offline media). This method, in the http(s) case, must first transfer the specified file or directory locally to a cache directory and then return the local path. The PreOS package can then continue to work with the local path and access the file or directory.
  • The Get-EmpirumAgentSetting -PeAgentConfig RemoteLogFolder cmdlet cannot be used in http(s) to modify log files on the Empirum share. For these purposes, the new Get-EmpirumTransfer cmdlet is provided. With the call Get-EmpirumTransfer LogFolder -Type RemoteLogFolder, similar to the Get-EmpirumPackagePath call, the EmpInst$\Wizard\OS\WinPeStatus subdirectory can be transferred locally. The method returns an object that can be used to access the path to the local cache via the Path property. The PreOS script can initiate the synchronization of the local files to the server via the Sync method after the adjustments have been made to the files in the cache. This will transfer the local changes to the server.

Here is an example from the HardwareInfo PreOS package:

$RemoteFolderObject = Get-EmpirumTransfer LogFolder -Type RemoteLogFolder -Verbose;
…
CreateAndCopyDriverJson $RemoteFolderObject.Path;
$RemoteFolderObject.Sync();

Set up WinPE based deployment via http(s)

The following steps describe the adjustments that need to be made so that in the WinPE based deployment the data transfer is performed via http(s). A connection to the Empirum share via SMB will then no longer be established.

  1. Configure and install the Empirum Subdepot Webservices Configuration package on a subdepot to be deployed via http(s) as described in the Online-Help.


When using Empirum up to and including version 20.0.0, write permissions must still be assigned to the user on the IIS that is used to establish the connection.

Starting with Empirum v20.0.1, manual setting of write permissions for the user on the IIS is no longer necessary!

Which user is used can be found in the Empirum Agent template used under General Settings > User name.

In the IIS Manager, switch to "Sites\Default Web Site\Matrix42-Empirum\Configurator\Log" in the left tree, double-click "WebDAV Authoring Rules" in the middle window and then click the user you are using. At the bottom of Permissions, check the Write option and confirm with OK.
WinPE_HowTo_505_IIS_Rights.png
In the IIS Manager, switch to "Sites\Default Web Site\Matrix42-Empirum/EmpInst/Wizard/OS/WinPEStatus" in the left tree, double-click "WebDAV Authoring Rules" in the middle window here as well, and then click the user you are using. At the bottom of Permissions, check the Write option and confirm with OK.

  1. Create an Empirum Agent template with the HTTP or HTTPS option checked in the transport protocols section. Make sure that the subdepot prepared in the first step is selected as the Fallback Server.
    WinPE_HowTo_510_HTTPS.png


Once the HTTP or HTTPS option is selected in the agent template, the SMB protocol is not used even if it is enabled.
If the HTTPS protocol is selected, it must be ensured that the failover server selected here can also be reached from "outside" under this name.

  1. Switch to Boot Configurations and execute via the menu View > Refresh so that the current agent templates and their values are read from the database again.
  2. Select the created Empirum Agent template in a boot configuration.
  3. If the option "Only trust validated server certificates" is used in the HTTPS case in the agent template, you have to store the thumbprints of the server certificates that are to be trusted. At WinPE runtime, the usual validation via the certificate store and the certificate chains does not work.


In older Empirum versions (before v20.0.2), thumbprints cannot yet be stored via the boot configuration.
The thumbprint, or a comma-separated list of thumbprints (without spaces), must be entered in theMatrix42.Empirum.PeAgent.dll.config file on the Empirum share in the EmpInst$\Sys\Images\WinPE\binaries\UAF directory before saving the boot configuration in these cases.
WinPE_HowTo_515_File.png
Thus, the following steps cannot be performed in the older Empirum versions. 

  1. Make sure that the advanced properties of the boot configuration are displayed by enabling the Advanced Properties button.
    WinPE_HowTo_520_Advanced_Properties.png
  2. In the lower part of the properties pane, to the right of Thumbprints for https validation, a list for thumbprints is displayed that is currently empty.
    WinPE_HowTo_525_Thumbprint_empty.png
  3. Add a new thumbprint with the + button.
    WinPE_HowTo_530_Thumbprint_edit.png
  4. Now transfer the thumbprint value to the thumbprint column of the Thumbprint of Server Certificate and add a description.
    WinPE_HowTo_535_Thumbprint.png
  5. If the boot configuration is to be used for multiple depots, repeat the procedure for each depot and enter the appropriate server certificate thumbprints.
  6. Save the boot configuration again so that the changes are applied.
  7. Assign the created boot configuration to the appropriate configuration group in Administration and activate the deployment.

 

Read out IIS certificate (Thumbprint)

The certificates used by IIS can be checked in the Internet Information Service (IIS) Manager and their thumbprints can be read.

  1. In the IIS Manager, switch to the top level entry of the server name in the left tree, double-click "Server Certificates" in the middle window.
    WinPE_HowTo_540_IIS_Manager.png
  2. The certificates are then displayed in the middle window. Double-click the certificate you are using to display its properties.
    WinPE_HowTo_545_ServerCertificates.png
  3. In the "Details" tab, the "Thumbprint" field can now be selected.
    WinPE_HowTo_550_Thumbprint.png
    If there are spaces in the thumbprint, they must be removed.
    Example: the thumbprint "‎11 dc 80 bc eb e0 41 a0 ab b2 f9 de bd 91 18 20 0c 25 b0 ef" becomes "‎11dc80bcebe041a0abb2f9debd9118200c25b0ef".
    Then it can be entered.
  4. If the boot configuration is to be used for multiple depots, repeat the procedure for each depot and enter the corresponding server certificate thumbprints.
  5. Save the boot configuration again so that the changes are applied.
  6. Assign the created boot configuration to the appropriate configuration group in Administration and enable deployment.

 

Change default time server

If a time server other than 'pool.ntp.org' is to be used, this can be configured via the variable OS_RegionalSettings.TimeServer. To do this, proceed as follows:

By default, 'pool.ntp.org' is used as the time server. If this is not to be changed, you do not need to perform these steps.

  1. In the Matrix42 Management Console, switch to Administration and click Variable Definitions in the Tools menu.
  2. Double-click the OS_RegionalSettingsvariable in the right window.
  3. Create the TimeServer variable of the Operating System type and the Text control element (see picture).
    WinPE_HowTo_555_VarDef_TimeServer.png
  4. Press OK to save and close the dialogs.
  5. Then select the client or the respective configuration group and enter the desired time server, e.g. 'de.pool.ntp.org' (see picture).
    WinPE_HowTo_560_Client_TimeServer.png
  6. Activate the deployment.

 

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
  2. Tags
    This page has no tags.