Self Provisioning

Last updated
Save as PDF

As of Matrix42 Client Management v19.0.1, WinPE-based OS deployment supports Computer Self Provisioning, which allows computers to be set up completely automatically with operating system and software by employees without Empirum knowledge.

Compared to Empirum-PE-based Computer Self Provisioning (EPE 4), two conceptual changes were made. First, the concept of computer templates has been introduced, which is explained in more detail below. In addition, the Empirum API is used to communicate with the Empirum server during Computer Self Provisioning execution. Thus, the Empirum API service must also be installed and configured on the Empirum server.

The WinPE-based Self Provisioning can be used on all (EFI) computers, but the local boot (to skip Self Provisioning) only works on computers that have already been set up with Empirum 19.0.1 / WinPE Support 1.6.1 before. Alternatively, Self Provisioning can also be performed via a USB stick, which can be created under Boot Configurations in Empirum. When running a self provisioning boot configuration, drivers added to the configuration in the current state are not installed.

WinPE-based Self Provisioning works only with EFI computers - BIOS computers are not supported. And therefore it is important to make sure that the WinPE-based boot configuration intended for Self Provisioning does not contain a BIOS option.

Deployment via the Empirum subdepot is currently only possible if the computer to be installed can connect directly to the Empirum API service of the Empirum Master Server.

If a USB stick is created on a Server 2012 R2 or Server 2016 or Windows Server prior to version 1703, offline sources cannot be added because these Windows Server versions cannot create a second NTFS partition. This feature is only supported from Server 2019 onwards. Alternatively, a current Windows 10 version with ADK 10 (2004) installed and Matrix42 Management Console installed can also be used.

If you define a WinPE PXE image as the default image, EPE-based OS installations are no longer possible through this PXE server. Mixed operation of WinPE PXE default/SP images and EPE PXE OS installations is not supported.

Starting with WinPE PreBoot Support version 1.8.3 it is possible to perform Self Provisioning also via http(s).

Computer templates

WinPE-based Computer Self Provisioning introduces the concept of computer templates. This replaces the concept of Self Provisioning groups. Computer templates are placeholders in Empirum and can be treated like normal computer objects. They can be assigned to configuration and assignment groups like normal computers. Thus the target state of the new computers can be defined.

While performing a Computer Self Provisioning, a computer template is selected to serve as a template for the new computer to be created. It is assigned to the configuration and assignment groups to which the computer template is also assigned. The new computer is activated and deployment is performed afterwards.

Create computer templates

Computer templates can be created in the Matrix42 Management Console under Administration using the context menu in the left tree.

Right-click Computer or Computer Templates and select New Computer Template.

The dialog opens, through which a new computer template can be created.

The New Computer Template dialog corresponds to the dialog for creating a new computer.
A special feature here is that the UUID and MAC address properties are not specified for computer templates. This information can only be specified by the respective computer at runtime of Computer Self Provisioning. These properties are therefore grayed out.

Enter a unique name to the right of Template Name. This is a required field.
Optionally, enter a Windows computer name for the computer(s) to be installed to the right of Name Pattern.
Optionally, enter a password to use this computer template to the right of Password and Confirm Password.
Enter a workgroup or domain name to the right of Workgr./Domain. For a domain name, the Domain option must be enabled (ticked). Specifying a workgroup/domain is a required field.
The FQDN (Fully-Qualified Domain Name) and OU (Organisational Unit) are not used/processed within the client Self Provisioning.
- Template Name
  Unique name for this computer template. A computer template can be assigned to a configuration group only once.
- Name Pattern
  f a name is specified in the name pattern, this value is taken in the self-provisioning process and the user is no longer prompted for the name. The value is automatically used as the computer name for the client to be created. Empirum API will append a "001, 002, ..." if necessary, if there is already a corresponding client. Only a maximum of 12 of the characters A-Z, a-z, 0-9, -, _ are allowed.
  If the value for Name pattern is empty, the user will be asked for the computer name in any case (during the self-provisioning process). The user can enter a name with a maximum of 15 characters. The system checks whether the name is already assigned in Empirum and informs the user accordingly.
- Password, Confirm password
  If a password is entered under Password and Confirm password, the password stored here must be entered directly after the display/selection of the computer SP template in order to start the installation. If no password is entered, no query is made.
- Workgr./Domain
  A domain/workgroup is composed of multiple computers that have been assigned a common name. A domain consists of shared resources and their users.
- Domain
  Specify here whether the computer is included in a domain. If no check mark is ticked here, the new computer belongs to the workgroup specified under Workgroup/Domain.
- FQDN (not supported)
  Setting or overwriting the FQDN via a computer template is not yet supported.
- OU (not supported)
  Setting a specific OU value via a computer template is not yet supported.
If all the necessary information has been entered, the new computer template can be created by clicking OK.
It will then be displayed in the list under the Computer Templates filter in the left tree (moreover, the computer template will also be displayed in the list of unassigned computers).

The Computer Templates filter lists all computers with the assigned Computer Template role.

Configure and assign computer templates

Once the computer template has been created, it can be assigned to an existing configuration group that has already been prepared for WinPE-based OS deployment. As described in chapter Create Configuration Group, the configuration group must be prepared. Thus, the following settings must be made:

Assignment of a WinPE based PXE image
Assignment of the necessary PreOS packages (DiskPartitioning, WindowsInstallation, PxeOffAndReboot, DomainJoin, EmpirumAgentSetup, ...)
Configuration of deployment-relevant computer variables (variable configurations)
Assignment of operating system edition
Assignment of software packages to be installed after operating system installation

Computer templates can also be used to configure assignment groups and can also be assigned to multiple assignment groups. When performing a Computer Self Provisioning, the newly created client is assigned to all groups to which the computer template is also assigned.

Configure and install Empirum API service

As already described, the communication during Computer Self Provisioning with the Empirum Server takes place via the Empirum API. For this, the Empirum API service must be configured and installed on the Empirum Master Server via Matrix42 DBUtil.

For more detailed information about the services installation via Matrix42 DBUtil, please refer to the Matrix42 online help.

To do this, start Matrix42 DBUtil.
Log in with the appropriate user.
Select the location.
Open the services configuration via Menu > Actions > Install/configure services.
Select the HTTP protocol and configure the port for the HTTP connection (default value is 9200).

Currently, WinPE-based Computer Self Provisioning requires that the Empirum API service is configured with the HTTP protocol. This can be configured either unencrypted (HTTP) or encrypted with a certificate (HTTPS).

Apply the changes with Apply.
Reinstall the Empirum API service using the context menu of the Empirum API entry in the list.
After successful installation of the service, Matrix42 DBUtil can be closed again.

The Empirum API service is now installed and available for WinPE-based Computer Self Provisioning. Next, you can now proceed with the creation of a boot configuration for Computer Self Provisioning.

Boot Configurations - Computer Self Provisioning

To perform computer self-provisioning at boot time, a boot configuration that includes this functionality must be created. In a WinPE-based boot configuration, the Self Provisioning property must be enabled.

Activate the Advanced Properties button first.
Enable the Enable Self Provisioning option (ticked).
After activating, additional properties for the credentials will be displayed.
Enter an Empirum API username, the associated Empirum API password and password confirmation.
If you do not want to use the default Empirum API server, uncheck the Use default Empirum API server option and enter the server to be used to the right of Alternative Empirum API server.

Use a user that has sufficient rights on the database. The user must have at least the roles EMP_M_COMPUTER and EMP_M_COMP_ROLE, which can be assigned to the user via Matrix42 DBUtil. SQL Server or Windows users are possible.

The boot configuration must be saved afterwards so that the changes to the PXE boot image are implemented.

If the PXE boot image creation has then been successfully performed, you can proceed with Self Provisioning on the Computer.

Additional Empirum API connection data

To be able to establish communication at the WinPE runtime, additional connection data is taken from the database when the PXE boot image is built and stored in the PXE boot image. The following data is taken over:

Empirum API service server name or the server name entered via the Alternative Empirum API server option
Empirum API service HTTP protocol details:
- Port
- Encryption

If the Empirum API service has not yet been configured and installed via Matrix42 DBUtil, an error will occur when building the Self Provisioning enabled PXE boot image because the connection details to the Empirum API service are required.

Currently, only the HTTP protocol is supported, which can be configured either unencrypted (HTTP) or encrypted with a certificate (HTTPS).

Activate Computer Self Provisioning on the Empirum Server

WinPE-based self-provisioning in its current state is intended for installation streets only and should not be used in production environments, where workstations cannot be booted locally unless they have been set up once before with the WinPE support version (1.6.3) or EPE support version (4.7.11).

With the help of the Offline Boot Medium creation, a USB stick can be created under Boot Configuration in the Empirum Management Console, with the help of which Computer Self Provisioning can be executed directly on the new computer via booting the USB stick.

If computer self provisioning is to be enabled via a PXE boot, then in Matrix42 DBUtil the Default PXE Image on the Empirum-PXE server entry of the Empirum master server must be set to the generated WinPE based self provisioning image.
Afterwards the change must be saved with Apply and the PXE service must be reinstalled.

Registry adjustments for the Empirum PXE service

As with EmpirumPE 4 based (EPE 4) Computer Self Provisioning, make sure that the following registry value is set on the Empirum Master Server (where the PXE service is running):
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\matrix42\PXE\EPE4SP
TThis must be set to 1, or created (type = DWORD; value = 1).

Run Computer Self Provisioning on the computer

If the preparations have been made, Computer Self Provisioning can now be executed with a new computer. Booting can be performed either via the created USB stick or via PXE.

When the computer boots, the Windows Boot Manager is displayed with the Local Boot entry selected by default.
If you want to run Self Provisioning, you must select the Empirum Self Provisioning menu item.

After selecting Empirum Self Provisioning, the WinPE-based environment is automatically started and the user is guided through Computer Self Provisioning. The following information is required for this:

Computer template selection
Specification of the stored password (if configured)
Specification of the new computer name (if no name pattern was specified)

After starting the Self Provisioning user interface, the necessary drivers are installed (1). Afterwards, a connection to the Empirum server is established (2). If the action was successful, this is acknowledged with a green check mark in each case.

(3) Select computer template

Select one of the available computer templates.

Only assigned computer templates are displayed here for selection.
After selecting the computer template, you reach the entry for the password of the computer template (4). If no password has been assigned for the selected computer template, continue directly with (5).

(4) Enter computer template password

If a password was entered in the computer template, it must be confirmed here to reinstall the computer via Self Provisioning.
After entering the password, press the [ENTER] or [TAB] key.
The password of the computer template is checked. If the password was entered correctly, the process continues with (5) if no name pattern was defined.
If a name pattern has been defined, the process continues directly with (6).
If an incorrect password was entered for the selected computer template, you can enter it again or select another computer template (3).

(5) Enter new computer name

If no name pattern was defined in the computer template, a computer name must now be specified.
After entering the computer name, press the [ENTER] or [TAB] key, you will get to item (6).
A maximum of 15 of the characters A-Z, a-z, 0-9, -, _ are allowed. If the computer name is entered incorrectly, the input area turns red. If you move the mouse over the input area outlined in red, a corresponding error message is displayed.
If a computer template with a predefined name pattern has been selected, this name pattern is already entered as the computer name.

(6) Start deployment now

You now have the opportunity to check all the information provided.

Pressing any key [ENTER] completes the process, so that the deployment for the computer can be performed directly afterwards.
A check is made whether this computer name already exists - if so, a "001", "002 etc." is appended and the computer is registered with this name in Empirum.
Currently this scheme of name extension ("001", "002 etc.") is fixed and cannot be changed!
The lower area now shows the actual computer name as it was created in Empirum - in the group with the selected computer template - via API.
The new computer is now created in Empirum with the specified name and assigned to the configuration and assignment groups according to the selected computer template and activated.
If the computer is already known in Empirum, it will first be removed from all groups and from Empirum completely before being created again.

This Self Provisioning screen remains visible (hourglass) until the new deployment jobs have been written to the DDC file, then the startup screen is displayed and the usual OS deployment runs through.

Self Provisioning via Depot Server (Offline)

The following requirements must be met so that self-provisioning can also be performed via a depot server (offline):

Customized Empirum Agent Template.
Customized WinPE Bootimage - Standard and Self Provisioning.
Own Empirum group with correspondingly selected Empirum server (depot).
The variable FQDN must be filled with a correct value.
The sync template ESubdepot_DeviceMapping must be assigned to the depot server (offline).

Empirum Agent Template

It is best to create a separate Empirum Agent Template for the Depot Server (Offline) (in this example "Agent_Depot").

It is important that the depot server (offline) has been selected as "Failure Server" here (in this example "Doku-Depot.QALAB.Matrix42.de").

WinPE Boot images

For the standard WinPE boot image and for the self-provisioning boot image, the previously created agent template must be selected (in this example, "Agent_Depot").

Empirum Group

It makes sense to create a separate configuration group here (in this example "SelfProvisioning"). To ensure that the configuration files are transferred (synced) to the correct depot server, you must make the following setting.

Right-click on this group and select Properties. Switch to the Empirum Server tab. Select your Depot Server (Offline) under Available Empirum Servers and add it via the Plus button under Selected Empirum Servers.

For a functional run, this configuration group must have the PreOS packages you need, an operating system import, a PXE boot image (default, no self provisioning), and a computer template associated with it. Optionally, language packages, the UEM Agent, and other software packages can be assigned.
All variables used here must also be set on this configuration group, especially the FQDN variable.

The default boot image is required in case further reboots are necessary during the operating system installation.