Skip to main content
Matrix42 Self-Service Help Center

OS Deployment via http(s)

With WinPE Preboot version 1.8.0 the connection setup via http(s) is supported. The following chapter describes the necessary adjustments and the current restrictions of the implementation.

With WinPE PreBoot version 1.8.0 the connection setup via http(s) is supported. The following chapter describes the necessary adjustments and the current restrictions of the implementation.

 

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

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

Make sure that the used boot configuration is also built with the current WinPE PreBoot version 1.8.0.

Limitations

The following restrictions must be considered with the current implementation:

  • Disk Imaging does not support the http(s) based transport.
  • The time stamp of the Swdepot log entries for the PreOS packages may differ in the http(s) case.

http(s) support for self-created PreOS packages

Maybe self-created PreOS packages are not immediately suitable for http(s) transport. The reason for this is mostly that in the PowerShell scripts accesses to files or directories that are not part of the PreOS package itself and are located at the Empirum.

To simplify the adjustments, certain characteristics of the http(s) transfer will be explained here.

  • In general, the http(s) case works with a local cache. Files and directories are transferred from the Empirum share via http(s) to local directories. Not all shares are transferred automatically, but only directories and files that are requested.
  • In the http(s) case, the contents of the package (e.g. in the case of the WindowsInstallation PreOS package the directory Configurator$\Packages\Matrix42\OsPackages\WindowsInstallation\5.0) is first transferred locally to a cache directory before the PreOS package is executed and then the install.ps1 script is executed locally. This covers relative access to files in the package.
  • If you need to access files in a PreOS package that do not exist in the package directory, you must do this using the Get-EmpirumPackagePath cmdlet. The method has been used in the past to get the path to the Empirum share (or offline medium). In the http(s) case, this method 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 working with the local path and access the file or directory.
  • The Get-EmpirumAgentSetting -PeAgentConfig RemoteLogFolder cmdlet in http(s) cannot be used to change log files on the Empirum share. For these purposes, the new Get-EmpirumTransfer cmdlet is provided. With the Get-EmpirumTransfer LogFolder -Type RemoteLogFolder call, 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 using the Path property. The PreOS script can synchronize the local files to the server via the Sync method after the files in the cache have been adjusted. The local changes are transferred to the server.

Here is an example from the HardwareInfo PreOS package:

$RemoteFolderObject = Get-EmpirumTransfer LogFolder -Type RemoteLogFolder -Verbose;

CreateAndCopyDriverJson $RemoteFolderObject.Path;

$RemoteFolderObject.Sync();

Setting up WinPE based deployment via http(s)

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

  1. Configure and install the Empirum Subdepot Webservice Configuration Package on a subdepot that should be used for deployment via http(s) as described in the online help Empirum Webservice Configuration Package.

 

Attention: Up to and including Empirum v20.0.0, write permissions must be assigned to the user on the IIS that is used to establish the connection. You can find out which user is used in the Empirum Agent Template under General Settings > Account.

Set the additional permission on these directories:

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 double-click on the user you are using. At the bottom of Permissions, set the check mark for the Write option and confirm with OK.

clipboard_e281bbf78c923c7262a10a86fc1de0923.png

In the IIS Manager, switch to "Sites\Default Web Site\Matrix42-Empirum/EmpInst/Wizard/OS/WinPeStatus" in the left tree, double-click on "WebDAV Authoring Rules" in the middle window and then double-click on the user you are using. At the bottom of Permissions, set the check mark for the Write option and confirm with OK.

Since Empirum v20.0.1 there is no need to assign write permissions on the IIS anymore.

  1. Create an Empirum Agent template with the HTTP or HTTPS option checked in the Transport Protocol area. Make sure that the subdepot that was prepared in the first step is selected as the Fallback Server.

clipboard_e44c2d4adb8d52cb6f611f0d1043974a7.png

Once the HTTP or HTTPS option is selected in the agent template, the SMB protocol is not used, even if it is enabled.

When selecting the HTTPS protocol, it must be ensured that the Fallback Server selected here can also be reached from "outside" under this name.

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

 

In older Empirum versions (before v20.0.2) the thumbprints cannot be stored via the boot configuration.

The thumbprint, or a comma-separated list of thumbprints (without spaces), must be entered in the Matrix42.Empirum.PeAgent.dll.config file at the Empirum share in the directory EmpInst$\Sys\Images\WinPE\binaries\UAF before saving the boot configuration.

clipboard_ebd3407e96f6dcd02b56e71ebda919b59.png

The following steps are therefore not necessary in the older Empirum versions.

Notice: The certificates used by IIS can be checked in the Internet Information Service (IIS) Manager.

In the IIS Manager, switch to the top level in the left tree to the server name entry and double click on "Server Certificates" in the middle window.

clipboard_e75e3070a763aeb2f9a7bb9bb8ea282f4.png

The certificates are then displayed in the middle window. Double-click on the used certificate to display the properties.

clipboard_ef13636e0a623618fc79d3361e919f4f5.png

In the tab "Details" the field "Thumbprint" can now be selected.

clipboard_e6dbf65a1d8221fd541cf55e2f789abf3.png

  1. Make sure that the advanced properties of the boot configuration are displayed by enabling the Advanced Properties check box.

clipboard_e69ecf818df8042cd014c7b6ad54d4e20.png

  1. In the lower part of the Properties section, a list is displayed for the thumbprints that is currently empty.

clipboard_e2da550e1a84bab2747232f6c361693b7.png

  1. Add a new thumbprint with the + button.

clipboard_ed46ef95597cb3bf2cef85e5d45f7f973.png

  1. Now transfer the thumbprint value to the Thumbprint of the Server Certificate column and add a description.

clipboard_e48e1633bea6165d490158f84e2da0177.png

Notice: The certificates used by IIS can be checked in the Internet Information Service (IIS) Manager and their fingerprints can be read.
In the IIS Manager, switch to the top level in the left tree to the server name entry and double click on "Server Certificates" in the middle window.

clipboard_e8b23876f5552aea8007f81b6f1c175ee.png

The certificates are then displayed in the middle window. Double-click on the used certificate to display the properties.

clipboard_ebd8e8e5c44636e4d6ff4d991f914c88f.png

In the tab "Details" the field "Thumbprint" can now be selected.

  1. If the boot configuration is used for multiple depots, repeat the procedure for each depot and enter the corresponding thumbprint of the server certificate.
  1. If a time server other than 'pool.ntp.org' is to be used, this can be configured via the variable OS_RegionalSettings.TimeServer. Proceed for this as follows:
  1. Switch to the variable definitions in the Tools menu in Administration
  2. Create the variable TimeServer of type Operating System and the control element Text (see screenshot).

clipboard_e41e5a0d62362b49b920ee5de174cd6cf.png

  1. Press OK to save and close the dialogs.
  2. Then select the client or the respective configuration group and enter the desired time server, e.g. 'europe.pool.ntp.org' (see screenshot).

clipboard_e51fa55c9c6af0162c5644cc136f17647.png

Notice: In the standard system 'pool.ntp.org' is used as time server. If this is not to be changed, you do not need to perform this step.

  1. Assign the created Boot Configuration to the desired configuration group in the Administration and activate the deployment as usual.

 

  • Was this article helpful?