Getting started with OS Deployment

Last updated
Save as PDF

Introduction

This Getting started explains how to use the Empirum offline tools on a Windows client, e.g. to create a WinPE boot image and upload it to the master server in the cloud.
It is helpful to set up an offline Subdepot server first. A description of the procedure can be found here.

The following procedure is possible directly on the Subdepot server.

Start the Matrix42 Management Console via the link provided to you.

Procedure if A SubDepot has been set up yet

The packages required to create an offline boot image can be installed by assigning and activating them.
Prerequisite: A functional UEM agent is already installed! More information can be found here
If the client is not yet in the Matrix42 Management Console, it can be integrated by taking inventory of the client.

Assign the Empirum Packaging Center and the Matrix42 WinPE Support Package to the client. Your configuration group will look something like this:
Activate the client.
The activated packages are automatically installed by the UEM Agent on the client.

Procedure if "no" SubDepot has been set up yet

Only with a running local Subdepot OS Deployment is supported!

Prerequisite: A Windows 10 or Windows 11 client is required. The following requirements must be met on this client:

Fully installed operating system (here Windows 10).
Administrative rights must be available on the client.
All Windows updates are installed.
A up to date WADK 10 2004 is installed (Download WADK 10 | 11).
The latest WinPE add-on is installed (Download WinPE from Matrix42 Marketplace).
An up-to-date UEM agent (2312.1.2) is installed (via MSI package) - HTTPS.
The latest Matrix42 Packaging Center is installed.
The current Matrix42 WinPE Support Package is installed.
Matrix42 Packaging Center must be run "as administrator".
The Empirum master server (Cloud) is accessible.

Install UEM Agent

After the Windows 10 client is installed, equipped with all Windows updates and the complete WADK 10 and latest WinPE add-on, the UEM agent must now be installed first. The required UEM Agent version must be downloaded from the Marketplace.

Launch a browser (Edge), log in to the Matrix42 Marketplace site and download the latest Matrix42 UEM Agent Standard Feature Release version (currently this is 2312.1.2) to e.g. C:\Temp.
Unzip the file UEM_Agent_2312.1.2-Standard-Feature-Release.zip.
Execute the file ".\Empirum\Configurator\Packages\Matrix42\UEM Agent Windows\MSI\2312.1.2\Matrix42 UEM Agent 2312.1.2 Standard Feature Release Setup 64bit.msi".
Click Next.
Accept the terms in the license agreement and click Next.
Select https as protocol, enter your server name and port 443. Enter the user to be used for the UEM agent and the associated password (sync-encrypted, not encrypted is also possible).

Protocol: https
Server:       empirumXXX.m42cloud.com (Replace XXX with your instance)
Port: 443
User:    .\DepotUser (Replace this user with your user)
Password:  <Your Password>
Click Next. The installation will be performed.
After successful installation, click Finish.
It may be necessary to restart the client.
If you right-click on the Matrix42 Software Depot logo at the bottom right (System Tray) and select Info About, you will see the connected server and the protocol used.

Install Packaging Center and WinPE Support Package

Double click on the Matrix42 Software Depot logo , highlight the latest Empirum Packaging Center package and the latest Matrix42 WinPE Support Package.
Click on Install 2 programs.
After successful installation of the two packages, there is now an Empirum Packaging Center icon on the desktop.

Create Offline WinPE Boot Image

A detailed description of the Matrix42 Offline PXE Image Creator can be found here DE / EN.
In this example configuration, a WinPE boot image is created that accesses the offline depot server via SMB protocol.

If you don't see the UI you need to reinstall the Packaging center package on your client

Right-click the Empirum Packaging Center desktop icon and select Run as administrator.
You will be taken to the Matrix42 Packaging Center. Click Offline PXE Image Creator at the bottom left.

The Matrix42 Offline PXE Image Creator window is displayed. If there is no configuration yet, an empty window is displayed.
Click on New.
The default settings for a self-provisioning image are prefilled.
Enter an Image Name (in this example WinPEx64DepotSMB).
Enter the Name of Agent Template (in this example Depot - Client - SMB). Note: If you don't know the correct name of the Agent Template, let it empty. The power shell script will transfer all known Agent Templates from the server in a local temp folder.
Select a WinPE Version (if not already entered).
Select the TFTP Blocksize that is functional for your environment.
Enter the WinPE drivers required for this boot configuration under Driver List.
The required drivers were previously stored under "D:\Temp\Drivers\WinPE".
As this is not an HTTPS configuration, Thumbprint List remains empty.
Deactivate the Selfprovisioning option.
The upload is done via PowerShell, therefore the option Create Zip remains deactivated.
Your configuration now looks something like this:
Click on Create Image.
The offline PXE boot image is created via a PowerShell script (parameters that cannot be verified are queried).

If you entered no Agent Template name, the PowerShell script is searching for all available Agent Templates on the Empirum server and it looks like you see in the picture below.
After a successful run, the complete path to the created PXE image is displayed.

When the PowerShell script is exited with ENTER, the Matrix42 Offline PXE Image Creator shows that the script has been saved.

If authorization problems occur when starting PowerShell - or during its work - the local PowerShell execution policy must be adjusted. To do this, start an administrative PowerShell and enter the following command:
Set-ExecutionPolicy unrestricted
You can view your current PowerShell ExecutionPolicy setting by using the Get-ExecutionPolicy command.

If you are using Self Provisioning you need to use the right Port to connect to the Empirum API.
Empirum Managemen Console starts under "https://empirum000.m42cloud.com/... - API Port 8443
Empirum Managemen Console starts under "https://client.wvd.microsoft.com/arm/... - API Port 443

Transfer Offline PXE Boot Image to the Master Server

Here is how to transfer files to the master server in the Cloud, without having our UUX. The user EmpSupportXXX is used for uploading.
If you are using our UUX it's much easier to upload files and you can find more information's here.

Matrix42 recommends the WebDav-capable tool WinSCP for the upload.

To open a WebDAV connection, the WebDav redirector must first be installed on a Windows server!
Start a Windwos PowerShell as administrator and execute the following command (this restarts the server):
Install-WindowsFeature WebDav-Redirector -Restart

If you have not already done so, please download and install the WinSCP tool.
Start the WinSCP tool.

The login window for a new Site is displayed.
Under File protocol, select WebDAV.
Under Encryption, select TLS/SSL Implicit encryption.
Enter your Matrix42 Master Server under Host name - empirumXXX.m42cloud.com (Replace XXX with your instance).
Enter Port 443 under Port number.
1. The login is done with the stored connection information, e.g.
  User: EmpCloudXXX-X (Replace XXX-X with your user).
  Password: <Your Password>
Click on the Advanced button.
Select the Directories folder and enter /Matrix42-Empirum under Remote directory.
Click OK, click Save and then click Login.
You have now established a connection with the share on your Matrix42 Cloud Server.
Now you can copy the previously created WinPE boot image "WinPEx64DepotSMB" (in the directory C:\Temp\2\OfflinePxeImage) to the
/Matrix42-Empirum/Configurator/PackageStore directory (this may take longer, depending on the connection speed).

WinPE Boot Images, Variable Configurations, and Software Packages, but also Operating System, Drivers and Language Package imports can be copied to the PackageStore directory.

Import WinPE Boot Image via SDK

After the WinPE boot image has been uploaded to the master server, it can now be imported via SDK. This step is obsolete when you are using our UUX upload function.

Start Windows PowerShell ISE as administrator.
To test a connection, you can use the CLOUD-DepotXXX__ConnectionTest.ps1.txt PowerShell script - (replace XXX, user and Password with your credentials and delete the .txt extension).
param([string]$ServerName='empirumXXX.m42cloud.com', [int32]$Port=443, [string]$UserName='m42cloud\EmpCloudXXX-1', [string]$Password='Password', [string]$TcpPort)
If the connection information is correct, the following is displayed:
In this CLOUD-DepotXXX__Import_via_SDK.ps1.txt PowerShell script you need to check the path to the WinPE boot image you just uploaded - in this example it is
"Z:\Configurator\PackageStore\WinPEx64DepotSMB" (replace XXX, user and Password with your credentials and delete the .txt extension). With this Script we will overwrite all existing PXE images in this path.
In this example script it is important to specify "Z:\" as Import Path and "-IsSecure $true" in the Connection String.
[string]$ServerName = "empirumXXX.m42cloud.com" [int]$Port = 443 [string]$UserName = "m42cloud\EmpCloudXXX-X" [string]$Password = "Password" [string]$importPath = "Z:\Configurator\PackageStore\OfflineDepotSMB" ... $session = Open-Matrix42ServiceConnection -ServerName $ServerName -Port $Port -UserName $UserName -Password $Password -IsSecure $true
If all entries are correct, run the script (F5). After a successful run, the following is displayed:

View in the Matrix42 Management Console

The PXE boot image imported via SDK is now displayed in the Matrix42 Management Console under Configuration > Boot Configurations.

Boot configurations created offline cannot be edited in the Matrix42 Management Console (grayed out). Therefore, if changes to the boot configuration are necessary, the boot image created offline must be recreated, or another boot image - see Create Offline WinPE Boot Image - must be created.

In Management > Administration the boot image can now be assigned to a configuration group.

Create USB flash drive

To create a USB flash drive, a PXE boot image is created as described above under Create Offline WinPE Boot Image - but here the option "Create a Self Provisioning image?" must be answered with yes "y" and the Empirum API user and password must be specified.

Make sure that ADK and ADK Windows PE Add-on are installed on your PC.
Right-click the Empirum Packaging Center desktop icon and select Run as administrator.
You will be taken to the Matrix42 Packaging Center. Click Offline PXE Image Creator at the bottom left.
Click on New.
Enter an Image Name (in this example WinPEx64DepotSP).
Enter the Name of Agent Template (in this example Depot - Client - SMB).
Note: If you don't know the correct name of the Agent Template, let it empty. The power shell script will transfer all known Agent Templates from the server in a local temp folder.
Select a WinPE Version (if not already entered).
Select the TFTP Blocksize that is functional for your environment.
Enter the WinPE drivers required for this boot configuration under Driver List.
The required drivers were previously stored under "D:\Temp\Drivers\WinPE".
As this is not an HTTPS configuration, Thumbprint List remains empty.
Activate the Selfprovisioning option (Check mark is set).
Enter the EmpirumAPI Server.
Enter the EmpirumAPI Port.
Enter the EmpirumAPI Username.
Enter the corresponding EmpirumAPI Password.
The upload is done via PowerShell, therefore the option Create Zip remains deactivated.
Activate the Create a USB flash drive option (Check mark is set).
Your configuration now looks something like this:
Click on Create Image.
The offline PXE boot image is created via a PowerShell script (parameters that cannot be verified are queried).
After the PowerShell script has been started, the configuration parameters are evaluated and all connected USB flash drives are displayed in a list.
Select the USB flash drive (here in the example it is only one USB flash drive, no. 1, drive P:) that is to be written to with this configuration.

If no USB flash drive is displayed, a further search can be carried out by entering "0".
The PXE boot image is created, followed by a confirmation prompt asking whether all data on the selected USB flash drive should really be deleted.
Answer the security prompt with Yes.
Once the WinPE USB flash drive has been successfully created, it can then be used for the operating system installation via self-provisioning.

Operating system and language packages - create - transfer - import

If an offline subdepot is not yet installed, or if it is not to be used, the requirements as described above must also be fulfilled here.

After an operating system source and / or language package has been created via the Packaging Center > Prepackaged OS Wizard, it must also be transferred to the master server in the cloud.

The procedure is identical to "Transfer Offline PXE Boot Image to the Master Server".
After the network location is established, the offline operating system source or the offline language package can be transferred to the PackageStore directory on the master server.

Import via SDK can be done using the same CLOUD-DepotXXX__Import_via_SDK.ps1.txt PowerShell script, or you can create a new script.
The only difference is the path specification to the operating system source or language package.
Change the row
[string]$importPath = "Z:\Configurator\PackageStore\<Operating system source or language pack>"
to your uploaded operating system source or language pack. If all parameters are entered correctly, the operating system source or language pack is imported and is then available for assignment in the middle tree of the Matrix42 Management Console.

Operating system drivers - create - transfer - import

If an offline subdepot is not yet installed, or if it is not to be used, the requirements as described above must also be fulfilled here.

After a driver package has been created via the Packaging Center > Offline Driver Package Creator, it must also be transferred to the master server in the cloud.

The procedure is identical to "Transfer Offline PXE Boot Image to the Master Server".
After the "network location" is established, the driver package can be transferred to the PackageStore directory on the master server.

Import via SDK can be done using the same CLOUD-DepotXXX__Import_via_SDK.ps1.txt PowerShell script, or you can create a new script.
The only difference is the path specification to the operating system driver.
Change the row
[string]$importPath = "Z:\Configurator\PackageStore\<operating system driver>"
to your uploaded operating system driver. If all parameters are entered correctly, the operating system driver is imported and can then be assigned in the Matrix42 Management Console via the Driver Wizard.