Update the IAM appliance to version 1.0

In the release 1.0, the IAM appliance brings in new fixes and improvements. Service names at the systemd level were unified in this version as well. The names czechidm, czechidm-db, web-proxy, and their related scheduled tasks are now prefixed with iam-.

  • Changes in behavior

    • Some edge cases of loading trusted certificates to containers were removed.

    • An option to set the appliance timezone using the iam-firstboot tool.

    • Changes in the automatic relink of the CzechIdM application.

    • Fixes for attachment upload to CzechIdM, HTTP communication compression, etc.

    • Fixes in the CAS access manager redirects.

    • Fixes in the CzechIdM integration with CAS.

    • Improved configuration of the CAS access manager logging.

  • New features

    • Main page of the appliance with an application dashboard. The dashboard monitors if applications are working and based on this it gives access to a link to the application.

    • The internal DNS server service to which new records can be added by editing /etc/hosts.

    • Support for the CzechIdM 11.x application containers.

    • Automatic removal of unused container images.

  • Optional features

    • An option to encrypt directory server backups, (learn more).

    • An option for the security hardening of SSH access to the appliance OS, (learn more).

Prerequisites

Upgrade prerequisites.

Ports

The appliance communicates with the server repo.iamappliance.com using ports 443/tcp and 8443/tcp via the internet. This communication must be functional.

Verify that the communication is functional using the tcptraceroute too
[root@localhost ~]# tcptraceroute repo.iamappliance.com 443
traceroute to repo.iamappliance.com (87.236.196.108), 30 hops max, 60 byte packets
... abbreviated ....
 7  neon.bcvsolutions.eu (87.236.196.108) <syn,ack>  2.728 ms  3.013 ms  2.160 ms

[root@localhost ~]# tcptraceroute repo.iamappliance.com 8443
traceroute to repo.iamappliance.com (87.236.196.108), 30 hops max, 60 byte packets
... abbreviated ...
 7  neon.bcvsolutions.eu (87.236.196.108) <syn,ack>  1.995 ms  2.427 ms  2.235 ms

Connect the Docker repositories

Check that the configuration of the Docker repository repo.iamappliance.com:8443 is functional. Download any image, e. g., the busybox:latest image. You can remove the image immediately after the download.

Download a small image to check the configuration
[root@localhost ~]# docker pull repo.iamappliance.com:8443/busybox
Using default tag: latest
latest: Pulling from busybox
9ea23c65b705: Pull complete
Digest: sha256:540f2e917216c5cfdf047b246d6b5883932f13d7b77227f09e03d42021e98941
Status: Downloaded newer image for repo.iamappliance.com:8443/busybox:latest
repo.iamappliance.com:8443/busybox:latest
Remove the downloaded image
[root@localhost ~]# docker rmi repo.iamappliance.com:8443/busybox:latest
Untagged: repo.iamappliance.com:8443/busybox:latest
Untagged: repo.iamappliance.com:8443/busybox@sha256:540f2e917216c5cfdf047b246d6b5883932f13d7b77227f09e03d42021e98941
Deleted: sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749
Deleted: sha256:8ac8bfaff55af948c796026ee867448c5b5b5d9dd3549f4006d9759b25d4a893

Upgrade the software repository configuration

Verify that the RPM repository definition in your appliance is at least version 0.3. If they’re not, update this using these steps.

Check the iam-appliance-repos package version
[root@localhost ~]# rpm -qi iam-appliance-repos
Name        : iam-appliance-repos
Version     : 0.1
Release     : 1.el8
Architecture: noarch
... abbreviated ...

Upgrade

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.

Stop all services including containerization
[root@localhost ~]# systemctl stop czechidm
[root@localhost ~]# systemctl stop czechidm-db web-proxy iam-directory-server
[root@localhost ~]# systemctl stop docker

Remove unused packages and change the configuration of services

Remove unused software packages, enable and disable services based on the example below.

We explicitely disable some services related to CzechIdM because they will be renamed during the update. In next steps, we will enable them again. 
[root@localhost ~]# dnf remove firewalld firewalld-filesystem
[root@localhost ~]# systemctl enable --now haveged rngd fstrim.timer
[root@localhost ~]# systemctl disable --now kdump microcode nis-domainname dnf-makecache.timer
[root@localhost ~]# systemctl disable czechidm-db czechidm web-proxy czechidm-db-backup.timer

Update the RPM packages

Update RPM packages which belong to the IAM appliance.

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

Handle the configuration conflicts like you do during standard updates. Beware that new software versions may contain new configuration items; you cannot simply leave the original configuration files in place.

To ensure that the CzechIdM service works correctly, use a container image bcv-czechidm:10.8.2-r2 or newer. In the file /data/registry/node-active-config/docker-compose-czechidm.yml, verify that this image is really used. See details in known issues.

Reconfigure the environment

Since the appliance contains new applications, you need to perform further configuration.

Change the RTC time zone configuration

The appliance is supposed to run in an environment where local hardware clock is set to the UTC time zone. Set the internal appliance configuration this way. This configuration change only impacts the way in which the virtual server with the appliance receives time information from the hypervisor HW clock; the setting has no impact on the hypervisor.

In the MS Windows / Hyper-V, the RTC is not usually in the UTC timezone but in a local time zone. This setting is not relevant for Hyper-V platform.
Configure the appliance for RTC in UTC zone
[root@localhost ~]# timedatectl set-local-rtc 0

Change the appliance OS time zone

The base installation of the appliance uses UTC time zone as its time zone but this should be reconfigured. Use the tool iam-firstboot to change it. Do not skip this step even if you want to use the UTC time zone in the appliance because the iam-firstboot tool performs other steps in the background which must be performed.

The use of the configuration tool is very specific in this step:

  • Use the n option to skip previously configured options. We only need to set the time zone.

  • Use the interactive menu to select the desired time zone.

  • When you skip the password change option for the root user, the tool will warn you that you use the default password. Ignore the warning.

  • After you finish the configuration, the tool will tell you to restart the appliance. Do not restart the machine.

Configure the time zone using iam-firstboot
[root@localhost ~]# iam-firstboot
...
Configure network? [Y/n]: n
Configure hostname? [Y/n]: n
Configure NTP time synchronization? [Y/n]: n
Configure time zone? [Y/n]: y
... abbreviated ...
Set new root password [Y/n]: n

Change the DNS configuration

In this version of the appliance, we added an internal DNS server. As a result, you need to move the DNS server configuration of your environment if it was defined statically.

If the appliance gets the network address and the DNS server addresses from DHCP, you can skip the configuration using nmtui (steps 2-7) and continue by restarting the Network Manager.

  1. Remove the configuration file for the static configuration rm /etc/NetworkManager/conf.d/appliance-dns.conf.

  2. List the current settings using cat /etc/resolv.conf.

  3. Start the graphical terminal application nmtui.

  4. In the list of Ethernet connections, find the record corresponding to the external network interface of the appliance (ensX,enpXsY or similar) and open it.

  5. In the IPv4 (and possibly IPv6) section of the configuration, set the relevant values for items "DNS servers" and "Search domains". The IP address should already be specified.

  6. Save the configuration using OK.

  7. Exit nmtui.

After you finish the configuration, restart the network layer of the operating system. After the restart, verify that the given IP addresses are correct and the DNS server works.

# restart the network layer
[root@localhost ~]# systemctl restart NetworkManager

# "nameserver" must direct to 127.0.0.1
[root@localhost ~]# cat /etc/resolv.conf
...abbreviated...
nameserver 127.0.0.1

# the process "dnsmasq" must be visible in the NetworkManager output
[root@localhost ~]# systemctl status NetworkManager | grep -A3 CGroup
   CGroup: /system.slice/NetworkManager.service
           ├─892 /usr/sbin/NetworkManager --no-daemon
           └─942 /usr/sbin/dnsmasq --no-resolv --keep-in-foreground --no-hosts ...abbreviated...

# the translation of domain names must work
[root@localhost ~]# getent hosts repo.iamappliance.com
87.236.196.108  iamappliance.com repo.iamappliance.com

After changing the DNS, restart the container platform.

[root@localhost ~]# systemctl restart docker

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 the issue, we will start them in a controlled way.

Note that the services czechidm, czechidm-db, and `web-proxy were renamed at the systemd level (and the systemctl command).
Controlled start of the 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. Check that the service started correctly in its logfile /data/logs/SERVICENAME/SERVICENAME.log.

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

Check that the service started successfully in its logs.

The czechidm service will take a relatively long time to start because it will have to relink the CzechIdM application. Make sure that the appliance has access to the repo.iamappliance.com repository. Otherwise, the relink will fail. The entire operation can take more than ten minutes, depending on the system resources available.

Enable the autostart of the new services

You need the enable the automatic start of the new services after the operating system start.

Enable the autostart of the new services
[root@localhost ~]# systemctl enable iam-czechidm iam-czechidm-db iam-web-proxy

Enable the backup creation

Since the services were renamed, the original service for creating the CzechIdM database backups is not enabled. Start and enable the planned task.

Enable the backup creation for the directory server
[root@appliance ~]# systemctl start iam-czechidm-db-backup.timer
[root@appliance ~]# systemctl enable iam-czechidm-db-backup.timer

Enable the regular container image cleanup

Container images which are no longer in use do not need to be kept in the appliance. Enable the scheduled task which cleans them up. This tasks removes all images for which there is no corresponding container created. If needed, missing images will always be automatically downloaded from official repositories repo.iamappliance.com.

[root@localhost ~]# systemctl start iam-docker-images-prune.timer
[root@localhost ~]# systemctl enable iam-docker-images-prune.timer

Validate the functionality and security

Access the appliance webpage the same way you always do. If you were previously logged-in into CzechIdM and you will be let directly to the application without having to log in, log out.

If the authentication to the CzechIdM using the access manager works correctly, the update was successful. We recommend you restart the server and verify that each service started correctly.

Post-upgrade steps

We recommend you create a new snapshot of the server. You should keep the "before update" snapshot for at least one week.