The appliance operating system update

The IAM appliance consists of the operating system CentOS as a base and additional software packages distributed with the appliance. These package groups can be updated separately from the OS.

Check that there are available updates for the operating system. If the appliance has Internet access or a local repository, it will refresh the list of new software versions automatically. If it doesn’t have Internet access, you need to allow it and refresh the software list manually.

Refresh the list of software packages
[root@localhost ~]# dnf makecache
... abbreviated ...
Metadata cache created.

Check whether there are some available updates for the operating system. Potential available updates will be listed.

Check available updates
[root@localhost ~]# dnf --disablerepo iam-rocky8 list updates
Last metadata expiration check: 0:01:03 ago on Thu 28 Jan 2021 11:34:45 AM UTC.
Available Upgrades
NetworkManager.x86_64                                   1:1.26.0-12.el8_3                                     baseos
NetworkManager-libnm.x86_64                             1:1.26.0-12.el8_3                                     baseos
... abbreviated ...
Update the operating system

  1. Turn off the appliance.

  2. Create a snapshot of the appliance drive to be able to restore the data in case of any issues.

  3. Turn on the appliance.

  4. Stop the services.

  5. Perform the update.

  6. Restart the appliance.

  7. Check.

Power off the appliance

Turn off the appliance using the usual way, e.g., using the command poweroff, or using ACPI shutdown.

Create a snapshot

Create a snapshot of the turned off virtual server.

Power on the appliance

Turn on the appliance the usual way. After startup, check that all services are running.

Stop the services

The appliance consists of several standalone services which need to be stopped before the update installation.

Stop the main services of the appliance
[root@localhost ~]# systemctl stop iam-czechidm iam-cas
[root@localhost ~]# systemctl stop iam-czechidm-db iam-web-proxy iam-directory-server

Perform the update

The update is done with explicitly disabled IAM appliance package repository to avoid unintentional update of appliance services.

[root@localhost ~]# dnf --disablerepo iam-rocky8 update

The dnf program prints its progress to the terminal. Check any potential errors that may appear during the update.

Restart the appliance

If the update was finished without any issues, you can restart the appliance. New software versions will be used automatically.

[root@localhost ~]# sync
[root@localhost ~]# reboot

Check

After the restart, all appliance services should be running correctly. If they don’t, check these services in particular:

  • NetworkManager.service - addressing and network

  • sshd.service - remote access to the console

  • docker.service - containerization

  • iam-web-proxy.service - web proxy container (web GUI of the appliance)

  • iam-czechidm.service - the identity manager CzechIdM container

  • iam-czechidm-db.service - identity manager database

  • iam-cas.service - the access manager which handles user authentication and authorization for the appliance components

  • iam-directory-server.service - database for the access manager; if it is not running, users will not be able to log-in

The service logs can be found in file /var/log/messages or (in newer versions of the appliance) in the directory structure /data/logs/…​.

Rollback

If you encounter any problem you are unable to fix, get the diagnostic output:

  • The contents of /var/log/messages and the output of the dmesg command.

  • The contents of /var/log/dnf.log.

  • The output of the systemctl status SERVICE command where SERVICE represents the above listed services.

  • The output of the command systemctl list-unit-files.

  • The service logs from /data/logs/…​ since the start of the update process.

Once you have the server diagnostics collected, turn the server off and revert its state to the snapshot.