Generic update guide for the IAM appliance

Use this tutorial only if the documentation does not contain a tutorial for the specific version of the IAM appliance.

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

Chech that there are available updates for the IAM appliance. 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 IAM packages. Potential available updates will be listed.

Check available updates
[root@localhost ~]# dnf list updates | grep iam-
Last metadata expiration check: 0:01:03 ago on Thu 28 Jan 2021 11:34:45 AM UTC.
Available Upgrades
iam-appliance.noarch                                   0.5-1.el8                                     iam-centos8
... abbreaviated ...
Update the IAM appliance

  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. Handle configuration conflicts.

  7. Start the services in a controlled way.

  8. Check.

Turn off the appliance

Turn off the appliance 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.

Turn 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

Updating is performed with explicitly selected appliance packages to avoid updating the entire operating system. Because of the dependencies of the appliance on some OS components, these components may be updated as well. This is expected behavior.

Update the IAM appliance packages
[root@localhost ~]# dnf update iam-*

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

Handle configuration conflicts

Software packages carry several configuration files which need to be locally edited to reflect the specifics of the deployment. Since it is undesirable to lose the local configuration, the update process will not remove it.

If a file which was locally edited is updated, you will find a notice in the dnf output that the file war created with a suffix .rpmnew or .rpmsave. This represents a configuration conflict with must be solved manually.

Conflict 1 - the .rpmnew file

Let’s assume the case of the file docker-compose-czechidm.yml. This file was locally edited to allow the service to use more system resources. During update, a new file, docker-compose-czechidm.yml.rpmnew appears in the same directory.

  • The file docker-compose-czechidm.yml.rpmnew is a new version of the file from the software package.

  • The file docker-compose-czechidm.yml is the original file and it is the same as it was before the update. This means that the service will use the original configuration.

In this case, we need to check that the new configuration file docker-compose-czechidm.yml.rpmnew does not contain any new configuration we need to incorporate to the existing one and that no other configuration had changed.

Differences must be merged into the docker-compose-czechidm.yml file. The docker-compose-czechidm.yml.rpmnew file may (and should) be removed afterwards.

Conflict 2 - the .rpmsave file

Let’s assume the case of the file 10_czechidm.conf which was edited locally. During update, a new file 10_czechidm.conf.rpmsave appears in the same directory.

  • The file 10_czechidm.conf is authoritatively updated from the software package.

  • The file 10_czechidm.conf.rpmsave is the original locally changed file. This means that the service will use the new configuration from the package.

It is necessary to manually resolve the conflict and move the changes to the 10_czechidm.conf file. After that, the 10_czechidm.conf.rpmsave file may (and should) be removed.

The occurrence of this type of conflict suggests that the appliance is using a nonstandard configuration.

The .rpmsave files may occur when a software package is uninstalled. In this case, they remain because their content was locally changed.

Other conflicts and warnings

In some cases, various warnings are printed during the update process. These are generally marked as WARNING: or NOTICE:, followed by detailed information. If they contain a warning Manual action required., an explicit action from the administrator is necessary.

Start the services in a controlled way

After the update, new service configurations may use new Docker images which must be downloaded by the system during the first start of the service.

Since it is impossible to say with certainty how long the Docker image download will take, there is a risk that services will not start in the correct order. To avoid this issue, start them in a controlled way.

Controlled start of independent services
[root@localhost ~]# systemctl start iam-czechidm-db iam-web-proxy iam-directory-server

If a new Docker image is being downloaded, the log file /var/log/messages will contain a line such as this one:

The system is downloading a new container image
Jan 28 09:42:32 localhost docker-compose[5967]: 12-r1: Pulling from bcv-postgres

After the image is downloaded, the container is automatically created and the service is started. Once that happens, we can start dependent services.

A successful start of a service can be verified in the log - /var/log/messages or (since appliance version appliance 0.5 or higher) in logs save in the structure /data/logs/…​.

Start the dependent services
[root@localhost ~]# systemctl start iam-czechidm iam-cas

There are five services in this version of the appliance: iam-czechidm, iam-czechidm-db, iam-web-proxy, iam-cas, and iam-directory-server. There may also be some optional services but this depends on the specific deployment. All services are containerized and to be able to start them, the docker service must be running.

  • The service iam-czechidm depends on iam-czechidm-db and it cannot be started without it.

  • The service iam-web-proxy has no dependencies.

  • The service iam-cas depends on iam-directory-server and it cannot be started without it.

  • The service iam-czechidm depends on iam-cas. The services can be started in any order, the iam-cas service must be running to authenticate users, however.

Check

Test that each appliance service works and perform user acceptance tests.

You can find the service logs 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.