Skip to content

(1) Article Details

  1. Author: Christopher S. Bates
    Updated: March 24, 2025
    Published: March 24, 2025

Migrating from OS 11 to OS 12

This document describes how to upgrade endpoint devices from IGEL OS 11.09 to IGEL OS 12 via the IGEL UMS (1).

  1. IGEL UMS Management Suite
Recomendation: Test Before Mass Deployment

After going through all of the Prerequisites please make sure to test the upgrade on one or more representative devices before you update all devices. For this purpose, perform the upgrade described under Manual Upgrade on the test devices.

Prerequisites

IGEL Software Versions

IGEL Product Minimum Version Recommended Version
IGEL UMS 12.07.100 Latest Available Version
IGEL Cloud Gateway Latest Available Version Latest Available Version
IGEL OS 11 11.09.120 11.10.250 or later
IGEL OS 12 Base Image 12.6 PR2 Latest Available Version

Confirm IGEL and UMS Licensing

IGEL OS and UMS must both be licensed properly to migrate to UMS and OS 12. Please reaference the official article below.

Confirm Endpoint Devices Are Supported

For hardware requirements, please see Devices Supported by IGEL OS 12.

IGEL OS 11.09.260 and later performs a hardware check to determine whether the endpoint device's hardware is suitable for IGEL OS 12.

UNSUPPORTED - Upgrade Low-End Devices to OS 12

It is possible to upgrade devices with 2 GB. For this purpose, you must set the registry parameter system.upgrade_igelos.ignore_memory_requirement to enabled.

Universal Management Suite (UMS) Configurations

There are a few adjustments that may be made to UMS before it can support OS 12 devices.

Configure UMS Server Public Address and Public Web Port

This is the address and port that your IGEL OS 12 devices, ICG servers, or external load balancers will locate your UMS server(s). It is required to set your Public Address as the FQDN of your UMS server(s).

Example

An FQDN is the full address of the server.
- Short-name: ums01
- FQDN: ums01.igel-lab.local
- IP: 192.168.1.101

Do NOT set the short name or IP as the Public Address

You cannot set the public address as an IP, and the FQDN is required for proper communication for OS 12 devices! Setting to to an IP can cause inconsistencies with connections for OS 12 devices.

  1. Open the IGEL UMS Console, and go to the UMS Administration section
  2. Navigate to UMS Network > Server
  3. Right-click the UMS server you wish to adjust, and select the Edit... button
  4. Enter a unique identifier into the Display Name field (this does not impact functionality, just how it appears in the UMS Console)
  5. Enter the Fully Qualified Domain Name of your UMS server that the IGEL will connect to on from your local network into the Public Address field
Public Web Port

You may set the Public Web Port to the required port. The default is 8443 and it is recommended to set it, even if using the default

UMS Cluster Address

If you plan to use an external reverse proxy server or load balancer, you will need to adjust the UMS Cluster Address to point to your external VIP FQDN and port. However, your Public Addresses should still be configured for each UMS server.

Validate UMS Web Certificates

In order for the new Unified Protocol and UMS Web App to function properly, your UMS Web Certificates must contain either a list of all your UMS server public addresses, load balancer FQDN, and igelrmserver (if in use), or any other address that may be used to access UMS in the SAN, or use a wild card certificate.

Additional FQDN's

If you use any other URL's to access the UMS Web App, or an external load balancer/reverse proxy address, these will need to be added as well (i.e umslb.igel-lab.local).

Handling Multiple Domains

If you have multiple domains, it is possible to generate certificates from UMS containing multiple domain names. This may not be possible while using an external / public Certificate Authority.

Example (umslb.igel-lab.local and umslb.igel.com are the load balancer addresses)

Cert Type SAN Examples
Individual ums01.igel-lab.local, ums02.igel-lab.local, umslb.igel-lab.local, igelrmserver.igel-lab.local, umslb.igel.com
Wild Card .igel-lab.local, .igel.com
Subject Alternative Names UMS Certificate Example

San Certificates

Wild Card UMS Certificate Example

Wildcard Example

Optional: UMS Configurations and Administrative Tasks

You can find additional recommended UMS configurations in the KB below. Though not required for migrating to IGEL OS 12, these Administrative Tasks are recommended to have in place.

KB in Progress

External Environment Configurations

In order to fully support OS 12 you may need to do quick validation / remediation of some basic network items related to UMS.

DNS Configuration

IGEL OS 12 relies heavily on DNS records to validate certificates and establish a secure connection. It is recommended to implement all DNS records for UMS servers, load balancers, and the igelrmserver address if in use, as well as pointer records for all UMS Public Host names.

  1. Confirm that you have a DNS record for each UMS servers Public Address, Load balancers, and the igrlemserver URL if in use
  2. Validate that the IGEL devices can resolve all of them
  3. Confirm you have a reverse lookup pointer configured for the IP addresses of all of your UMS servers, and that they resolve to the UMS Public Address
  4. i.e. nslookup 192.168.10.10 should return ums01.igel.lab in the IGEL lab Reverse Lookup Example

IGEL Cloud Gateway (ICG) Configurations

Configure ICG Host Names

This is normally already done, but it is good to validate that your ICG server addresses and certificates are configured to use Fully Qualified Domain Names and not IP Addresses.

Your ICG has two hostnames, and both should be using Fully Qualified Domain Names. These can be the same as long as UMS, internal devices, and external devices can resolve the address to the proper IP Addresses.

Using your OS's hosts File

If you are using a publicly signed certificate from an external CA, it is most likely required to only have the external host name in the cert. If you cannot add an internal DNS name to route to the internal ICG address, a hosts file can be deployed to UMS to make this work.

Please document this if the host file method is used.

Validate ICG Certificates

Similar to the UMS Web Certificates, your ICG certificates will need to have all internal host names, external host names, and load balancer addresses in the SAN, or you will need to use a wildcard.

Example (icg.igel.com is the load balancer)

Cert Type SAN Examples
Individual icg.igel.com, icg01.igel.com, icg02.igel.com, icg01.igel-lab.local, icg02.igel-lab.local.
Wild Card .igel-lab.local, .igel.com
Subject Alternative Names ICG Certificate Example

Wild Card ICG Certificate Example

Licensing

For migration to IGEL OS 12, an active Workspace Edition or Workspace Edition Evaluation license is required.

Starter Licnse

An IGEL OS Starter License is not valid for migrating devices to IGEL OS 12.

Getting IGEL OS 12 from the App Portal

Note - UMS Registration Required

Before you can import the IGEL OS 12 Base App into your IGEL UMS Server, you will need to link your UMS server to the app portal Registering UMS with IGEL Cloud Services. Otherwise, you will need to follow the process defined in "How to Install OS 12 Apps in a UMS Environment with Limited or No Internet Access" to manually download and import the Base OS App into the UMS server.

  1. In the UMS Console, open the UMS Web App, or open a browser and navigate to https://:8443/webapp Launch WUMS

  2. In the UMS Web App, open the App Portal. App Portal Button

  3. In the App Portal, search for"base" and then select IGEL OS Base System. image-20250219083634626

  4. Choose the appropriate version, click IMPORT and confirm the dialogs. image-20240827-184123.png image-20240917-162401.png image-20240827-184154.png

The IGEL OS Base System app is imported into your UMS and will be available for your devices.

  1. In the UMS web App, go to Apps. img

  2. In the Apps list, select Base. If Newest Version is not Default Version is displayed, set the newly imported version as the default version. img img img

Creating new Profiles for IGEL OS 12

Due to the changes required to make OS 12 modular, it is required to recreate all profiles that were used for OS 11 as an OS 12 profile. OS 11 profiles will not work for OS 12 profiles. It is recomended to create a few base OS profiles before continuing, but you can migrate your other App Profiles once you have converted a few test devices.

For those settings that refer to a session, like Citrix, RDP, or the Chromium browser, the IGEL OS 12 profile will trigger the installation of the appropriate app.

In the following, we create a profile for basic settings and a profile for the IGEL Base OS App and the Chromium browser App. The basic settings profile will configure the base system app, while the Chromium browser will configure the Chromium browser app.

Example Profile: Basic Settings

  1. In the UMS web App, go to Apps. WUMS Landing Page Apps

  2. Select the IGEL OS Base System and then click Create new profile. WUMS App Profile Selection

  3. Enter a name for the profile and click Save. WUMS First Profile Name

  4. Edit the settings according to your needs and then click Save and close. WUMS First Profile Settings

Example Profile: Chromium Browser

  1. If the Chromium Browser app is not available in your UMS, import it. The process is the same as that for the Base System, see Getting IGEL OS 12 from the App Portal.

  2. In the Apps list, select Chromium Browser and then click Create new profile. WUMS New Chromium Browser Profile

  3. Enter a name for the profile and click Save. WUMS Chromium Profile Name

  4. Edit the settings according to your needs and then click Save and close. WUMS First Chromium Settings

Creating OS 12 Directories & Directory Rules

It is recommended that you create a separate directory structure for your OS 12 devices. This will help organize and separate OS 11 configurations from OS 12 and make the migration easier. It is also recommended to create a default directory rule to migrate devices to the new OS 12 structure once the upgrade has been completed.

Create OS 12 Root Directory

This directory will act as the "root" or "base" directory for all OS 12 devices. Devices should only be moved to this directory once the OS 12 upgrade has been completed.

  1. Launch the JAVA Console, and navigate to IGEL Universal Management Suite 12 -> Devices

  2. Right-Click the "Devices" top level item, and select New Directory

  3. image-20250219092003650

  4. Enter in something like OS 12 or OS 12 Root image-20250219091746799

  5. Launch the IGEL UMS Web App image-20250219131650681

  6. Apply the "Base OS" App using the "Default Version" to the directory

  7. Apply the Profiles created in the Creating new Profiles for IGEL OS 12 section to the root directory

  8. Optional: You can create additional sub-directories below for your initial workflows image-20250219093700620

  9. Optional: Assign any additional profiles to any sub directories as needed for your workflow image-20250219131924613

Think before you copy

It's recommended to wait until you start to deploy to build other directories, as structures may change due to changes on how OS 12 works.

Creating OS 12 Initial Default Directory Rules

Creating a default directory rule will allow devices that have successfully upgraded to OS 12 to automatically move to the OS 12 base directory and receive the required profiles and apps.

IGEL KB - Default Directory Rules

  1. Launch the UMS JAVA Console and navigate to UMS Administration Global Configuration Default Directory Rules

  2. image-20250219094013357

  3. Select the top-level Default Directory rules object

  4. Use the Plus image-20250219094325767 Icon to enter the Rule Creation Wizard image-20250219094424436

  5. In the first window search for and select Firmware Version and click Next image-20250219094534458

  6. In the Version Search dialogue, select Above, enter 12 in the text box and click Next image-20250219094714441
  7. In the Select Directory window, select the Chose target directory option, select your OS 12 Root directory, and check the boxes next to all three rules to apply the rule at reboot, leave in the subdirectory, and override existing memberships. image-20250219094841873
  8. Click Finish to create the rule
Note - Sub Directories and Additional Rules

If you have another sub-directory, you can create also create sub-rules to move devices into those sub-directories following the same procedures above, but using the "Firmware version is greater than 12" as the starting point

Example with OS 12 Root and Chromium Sub-Directory

image-20250219095152577

Example with OS 11 (Firmware version is less than 12)

If you are planning on adding more OS 11 devices, then you may need to create a "Default Directory" rule to capture OS 11 devices. You may also want to disable the "Apply on boot" option for this rule to prevent existing devices from moving on reboot.

image-20250219095529984

Manual Upgrade

Creating a Migration Folder

In order to test the upgrade, we will need to apply the OS 12 Base OS App to your OS 11 devices directly. For testing, we will want to create a sub-directory in your existing OS 11 structure. This will allow you to keep the current OS 11 firmware, and the OS 12 app applied to that folder, which may be required if something fails during the upgrade.

  1. Launch the UMS JAVA console
  2. Navigate to Devices
  3. Identify an existing directory that contains all the settings

  4. Create a sub-directory under this folder for testing image-20250219130820988

  5. Validate that the OS 11 firmware package or profile is assigned directly or indirectly to this directory (required to fall-back if something goes wrong during the upgrade) image-20250219130924268

  6. Launch the UMS Web App image-20250219131633989

  7. Using the UMS Web App, assign the "Base OS" app to the directory, selecting the "Default Version"

  8. Apply at least the "Base OS" profiles created in the Creating new Profiles for IGEL OS 12 section image-20250219131144224

  9. Finally, move a test device to this new directory from the one above, and select Move and Apply Changes Now when prompted image-20250219131506094

Checking for Device Upgrade Readiness

In this section, we will determine if your IGEL OS 11 devices have passed the upgrade readiness check.

  1. In the UMS JAVA Console, go to Devices, open the context menu, and then select Other commands > Refresh system information.

  2. Click Refresh system information.

  4. Select a device, look up the Advanced System Information section, and check if the value of OS Type contains the text OS 12 Upgrade Ready.

  5. If this is the case, you can continue with the next step.

Starting the Upgrade

  1. In the UMS Console, open the context menu on our upgrade directory and select Specific Device Command.

  2. Select Upgrade to IGEL OS 12 and click Execute.

After a few reboots, the upgrade is complete, including the newly installed apps. No user interaction is necessary because all dialogs that are displayed during the update process have a timeout.

Patience Young Padawan

Please be patient, there is no indication the update has started until all packages have been downloaded. This may take longer for the first devices upgraded as UMS may need to download and populate packages and metadata

Troubleshooting and Known Issues

Initial Failures

If your upgrades fail there are a few quick items you can do to identify the issue.

  1. Review this document in it's entirety to make sure a small step was not missed
  2. Try using the IGEL OS Creator to create a new OS 12 devices, and register it. This will help identify any issues with the UMS configuration that may conflict with onboarding
  3. IGEL KB - Installing the Base System via IGEL OS Creator (OSC)
  4. IGEL KB - Onboarding IGEL OS 12 Devices
  5. IGEL KB - Troubleshooting: Possible Error Codes During the Onboarding

Action Required if Devices Are Managed via ICG and UMS 12.02.130

If some of the devices you want to upgrade are managed via the IGEL Cloud Gateway (ICG) and you are using UMS 12.02.130, please follow the instructions under Errors after OS12 Upgrade of an OS11 Device which Is Managed via ICG.

Workaround: What to Do If the EULA State is "Not Needed"

When the EULA State of your target version of IGEL OS 12 is Not needed, you must ensure that it gets changed to Accepted.

To achieve this, proceed as follows:

  1. Find the device that has imported the IGEL OS 12 version in question and delete it from the UMS. Do not forget to clear the recycle bin afterward. img img

As an alternative to deleting the device, you can change the version of the IGEL OS 12 Base System for all devices in the UMS; this includes all profiles that configure the Base System.

  1. In the UMS web app, go to Apps > Base and delete the Base System version in question. img

Now you can start with Getting IGEL OS 12 from the App Portal.

Errors after OS12 Upgrade of an OS11 Device which Is Managed via ICG

Environment

  • IGEL UMS 12.02.130
  • IGEL ICG 12.xx

Symptom

An OS11 device that is managed via ICG is not fully manageable after the upgrade to OS12. It is not possible to send commands or configurations to the device.

Solution

On your UMS Console, open the SQL console and execute the following statement:

UPDATE thinclient SET usg_process_id = null WHERE protocol = 'inified'

USE database_name
UPDATE schema_name.thinclient 
SET ust_procress_name = null WHERE protocol = 'unified'

Afterward, the device will be fully manageable.

Additional Resources & References