Troubleshooting: IGEL OS 12 Devices Failing to Connect to UMS Due to Expired Client Certificates

IGEL OS 12 devices need to have valid client certificates to connect to the IGEL Universal Management Suite (UMS). Client certificates expire 1 year after device registration in the UMS. For devices running IGEL OS 12.4.1 or newer, the client certificates are renewed automatically, but for devices running IGEL OS 2.4.0 or older, the client certificates are never renewed, making the devices unmanageable through the UMS. The mitigation of the issue is done by allowing expired client certificates to be temporarily accepted through a custom TrustManager. This way, the devices can be updated without manual intervention.

Requirements

• UMS version 12.08.130

• Administrator / root access to terminal to run commands of the command line interface (CLI). For details, see IGEL UMS Administrator Command-Line Interface

Error Message of Expired Client Certificate

When a device has an expired client certificate, the connection to the UMS fails because the TLS handshake is aborted during the establishment of a TLS connection to the UMS.

You can see the following error message in the UMS tray app: ERROR: Connection failure: read failed

You can also see the same error message in the device log files when the device is trying to connect to the UMS.

Using the Custom TrustManager

Starting from UMS 12.08.130, a custom TrustManager is integrated in the UMS that can be enabled to accept expired client certificates. The TrustManager can be managed using the following CLI commands:

• Enable: umsadmin-cli accept-expired-client-certs enable

• Disable: umsadmin-cli accept-expired-client-certs disable

• Check current state: umsadmin-cli accept-expired-client-certs state

When the custom TrustManager is enabled, a warning is shown in the UMS Web App system info box to highlight the potential security and compliance risk. You can get further information if you click the warning icon.

The warning is only shown to administrators with write access to the UMS Console > UMS Administration > UMS Network node.

Step-by-Step Instructions to Renew Expired Client Certificates

To handle devices with expired client certificates:

1. Open the command prompt as Administrator in Windows or a terminal as root in Linux.

2. Enter umsadmin-cli accept-expired-client-certs enable

   This enables the custom TrustManager in the UMS to accept expired client certificates and restarts the UMS server.
   You should see the corresponding response.

3. To check that the option is enabled, use the umsadmin-cli accept-expired-client-certs state command and see that the option is enabled.

4. Restart the IGEL OS 12 devices with the expired certificates.
   The devices should be connect to the UMS after restart.

5. Go to the UMS Console or UMS Web App and check if the IGEL OS 12 devices are connected to the UMS now.

6. Go to the UMS Web App and update the IGEL OS 12 Base System version on the devices to the latest available version.
   The devices will get their client certificates renewed by the update.

7. Go back to the UMS CLI and enter umsadmin-cli accept-expired-client-certs disable

   This disables the custom TrustManager and devices with expired client certificates cannot connect to the UMS anymore.

8. To check that the option is disabled, use the umsadmin-cli accept-expired-client-certs state command.

9. Go to the UMS Console or UMS Web App and check if the updated IGEL OS 12 devices are connected to the UMS.